mio

Create a REST API and interact with it in the browser using the same interface. No need for any route handling or AJAX boilerplate.

Mio provides a common model layer between client and server for building REST APIs and web applications. REST is a first-class citizen with Mio's API, where get() is used instead of findOne(), and patch() where most libraries would provide save().

• RESTful models and collections
• Simple enumerable objects
• Hooks and events for object lifecycle
• Backbone-style API for extending resources
• Modular. Plugins provide storage, validation, etc.
• Browser and node.js support

API Documentation

Plugins

Guide

• Installation
• Resources
• Collections
• Actions and Queries
• Hooks and Events
• Relations
• Plugins
• REST API

Installation

Using npm:

npm install --save mio

Using bower:

bower install --save mio

Using browser script tag and global (UMD wrapper):

// Available via window.mio
<script src="dist/mio.js"></script>

It is recommended to use browserify when using mio in the browser and on the server. Platform-specific code can be wrapped in Resource.server() or Resource.browser() and server code excluded in the client build.

Resources

New resources are defined by extending the base resource class using mio.Resource.extend().

var User = mio.Resource.extend();

Attributes can be defined by extending the prototype:

var User = mio.Resource.extend({
  attributes: {
    id: {
      primary: true
    }
  }
});

Attributes can also be defined using the chainable attr() method:

var User = mio.Resource.extend();

User
  .attr('id', {
    primary: true
  })
  .attr('name')
  .attr('email');

Resources can be extended with prototype or static properties and methods:

var User = mio.Resource.extend({
  sayHello: function () {
    return 'hello';
  }
}, {
  type: 'User'
});

console.log(User.type); // => "User"

var user = new User();

user.sayHello(); // => "hello"

Collections

Each Resource has an associated collection. Actions that return multiple resources return instances of Resource.Collection. Collections have REST actions just as resources do.

For example, to fetch a collection of user resources:

User.Collection.get().exec(function (err, users) {...});

Array.prototype methods are available for collections, but a collection is not an array. The array of resources is kept at Collection#resources. Methods such as map() return arrays instead of the collection.

var resource1 = new Resource();
var collection = new Resource.Collection([resource]);

collection.push(new Resource());
collection.splice(1, 1, new Resource());

collection.at(0) === resource; // => true
collection.length === 2;       // => true
collection.indexOf(resource);  // => 0

Actions and Queries

Mio resource and collection methods map directly to REST actions and HTTP verbs. Instead of find() you use get(). Instead of save() you use put(), post(), or patch().

The actions get, put, patch, post, and delete exist for the resource class and instances. Collections also support a subset of these methods.

Storage plugins use event hooks provided for each method to fetch or persist resources to a database.

Fetching

Find one user:

User.get(123, function(err, user) {
  // ...
});

Find all users matching a query:

User.Collection.get({ active: true }, function (err, users) {
  // ...
});

Using a chainable query builder:

User.Collection.get()
  .where({ active: true })
  .sort({ created_at: "desc" })
  .size(10)
  .exec(function(err, users) {
    // ...
  });

Pagination

All queries are paginated using a common interface provided by the Query and Collection classes. Both queries and collections maintain from and size properties. The default and maximum page size are set by Resource.defaultPageSize and Resource.maxPageSize properties.

See the query documentation for more information.

Creating and updating

Creating or updating resources is accomplished with put, patch, and post:

var user = User.create({ name: 'Bob' });

user.post(function (err) {
  // ...
});

User.create() is just functional sugar for new User().

All instance actions are available as class actions:

User.post({ name: 'Bob' }, function (err, user) {
  // ...
});

Update a resource:

var user = User.create();

user
  .set({
    name: 'alex'
  }).patch(function(err) {
    // ...
  });

See the API documentation for a complete list of actions.

Plugins

Resources may use plugin functions which extend them with functionality such as validation, persistence, etc.

var mio = require('mio');
var MongoDB = require('mio-mongo');
var User = mio.Resource.extend();

User.use(MongoDB({
  url: 'mongodb://db.example.net:2500'
}));

Browser or server specific plugins:

User.browser(plugin);

User.server(plugin);

Hooks and Events

Asynchronous hooks are provided for CRUD operations and lifecycle events. They run in series before get, put, patch, post, and delete methods.

Hooks are used to implement validation, persistence, and other business logic.

Hooks receive a next function as the last argument, which must be called to continue firing subsequent listeners. Subsequent hooks will not be run if next receives any arguments. Arguments received by next are passed to the callback of the method that fired the event.

User.hook('get', function (query, next) {
  // retrieve user from storage using query
  db.getUser(query, next);
});

Collection hooks are prefixed with collection::

User.hook('collection:get', function (query, next) {
  // ...
});

See the full documentation for hooks.

In addition to hooks, synchronous events are fired after resource actions and other resource events like attribute changes.

User
  .on('patch', function (query, changed) {
    // do something after update
  })
  .on('change:name', function (user, value, prev) {
    // ...
  });

See the full documentation for events.

Hooks and events can also be registered when extending a resource:

var User = mio.Resource.extend({
  attributes: {
    id: {
      primary: true
    }
  }
}, {
  hooks: {
    'post': [function (representation, next) {
      // ...
    }]
  },
  events: {
    'initialize': [function (resource, attributes) {
      // ...
    }]
  }
});

Relations

Define relationships between resources in combination with a supporting storage plugin.

Author.hasMany('books', {
  target: Book,
  foreignKey: 'author_id'
});

Book.belongsTo('author', {
  target: Author,
  foreignKey: 'author_id'
});

// fetch book with related author included
Book.get(1).withRelated(['author']).exec(function(err, book) {
  console.log(book.author);
});

// fetch book by related author
Boook.get().where({
  'author.name': 'alex'
}).exec(function(function (err, book) {...});

See the relations API for more information.

REST API

Create a REST API server from your resources and interact with them from the browser using the same interface. No need for any route handling or AJAX boilerplate. Automatic client-server communication is provided by mio-ajax in the browser and mio-express on the server.

Create a Resource definition shared between browser and server:

var mio = require('mio');
var Validators = require('mio-validators');

var User = module.exports = mio.Resource.extend({
  attributes: {
    id: { primary: true },
    name: {
      required: true,
      constraints: [Validators.Assert.Type('string')]
    },
    created: {
      required: true,
      constraints: [Validators.Assert.Instance(Date)],
      default: function () {
        return new Date();
      }
    }
  }
}, {
  baseUrl: '/users'
});

Extend it on the server with server-specific plugins:

var User = require('./models/User');
var MongoDB = require('mio-mongo');
var ExpressResource = require('mio-resource');
var express = require('express');

User
  .use(MongoDB({
    url: 'mongodb://db.example.net:2500'
  }))
  .use(ExpressResource.plugin());

var app = express();

// register routes provided by ExpressResource
app.use(User.router);

app.listen(3000);

And in the browser:

var User = require('./models/User');
var Ajax = require('mio-ajax');

User.use(Ajax());

var user = User().set({ name: "alex" }).post(function(err) {
  // ...
});

MIT Licensed