mio-ajax

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

Installation

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>

Usage

var mio = require('mio');
var ajax = require('mio-ajax');

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

User.use(ajax());

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.

options

• 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:

User.browser(ajax({
  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) {
      setToken(token);
      retry();
    });
  }
});

Events

ajax:request

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');
});

ajax:response

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;
});

ajax:error

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) {
    refreshAccessToken(retry);
  }
});

MIT Licensed