node package manager
Easy collaboration. Discover, share, and reuse code in your team. Create a free org »


mio-ajax Build Status Coverage Status Bower version NPM version Dependency Status

AJAX storage plugin for Mio. Pair with mio-express for automatic client-server communication.


Using bower:

bower install mio-ajax

Using browser script tag and global (UMD wrapper):

// Available as window.mio.ajax
<script src="dist/mio-ajax.js"></script>


var mio = require('mio');
var ajax = require('mio-ajax');
var User = mio.Resource.extend({
  attributes: {
    id: {
      primary: true
    username: {
      required: true
}, {
  baseUrl: '/users'

The example above would expect the following API:

GET      /users       // Return a JSON list of all users.
POST     /users       // Creates a new user. Returns JSON of that user.
DELETE   /users       // Destroys all users.
PATCH    /users       // Updates multiple users.
GET      /users/:id   // Return a JSON user object.
PUT      /users/:id   // Replaces existing user.
PATCH    /users/:id   // Updates existing user.
DELETE   /users/:id   // Destroys user.


  • patch Boolean use PATCH for Resource#save (default: true)
  • header Object.<String:String> map of request header fields to values

Defining Alternative Routes

You can specify alternative routes using options.url.actions:

  baseUrl: '/users',
  urls: {
    get:    '/users/:username',
    put:    '/users/:username',
    delete: '/users/:username'

This would make it so that the following routes were used:

GET   /users/:username
PATCH /users/:username
DEL   /users/:username

Retrying requests

You can use the retry function passed to the ajax error event to retry requests.

User.on('ajax:error', function(err, retry) {
  if (err.status == 401) {
    refreshAccessToken(function(token) {



Emitted before XHR request is sent.

User.on('ajax:request', function(req) {
  // req is superagent request object 
  req.set('Authorization', 'Bearer 13a9-34b3-a8da-c78d');


Emitted after the XHR request is complete.

User.on('ajax:response', function(res) {
  var users = res.body.results;
  // Convert JSON string dates into actual dates 
  users.forEach(u) {
     u.registeredAt = new Date(u.registeredAt);
  res.body = users;


Emitted on XHR error and 4xx or 5xx responses, with an Error as the first argument and a retry function as the second argument.

If executed, the retry function will retry the request and execute the original callback once the request is complete. If a new callback is supplied to retry() then that will be used when the retried request completes.

User.on('ajax:error', function(err, retry) {
  if (err.status == 401) {

MIT Licensed