rsvp-ajax

Overview

This library is a very simple wrapper on top of XMLHttpRequest that exposes its capabilities via rsvp promises.

Published module can be found in npm repository, latest stable version is available here.

Simple Usage Sample

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

// GET request:
var promise = ajax.request('GET', '/rest/resource/1');
promise.then(function (data) {
  // Note, that 'application/json' content type is expected by default and response
  // is automatically transformed to Javascript object
  console.log('Data received:', data);
});
//...

// POST request + error handling:
var body = {'do': 'something'};
var promise = ajax.request('POST', '/rest/trigger/action', body);
promise.then(function (data) {
  console.log('Data received:', data);
}, function (xhr) {
  // handle error, passed object is an XMLHttpRequest instance
  console.error('POST /rest/trigger/action returned error status', xhr.status);
});

Including in your package.json:

  "devDependencies": {
...
    "rsvp-ajax": "^1.0.0",
...
  },

Advanced Usage

For non-trivial AJAX requests use requestObject function.

For example, sending a request body in plain text form and receive response as plain text you can be done as follows:

  var ajax = require('rsvp-ajax');
  
  var password = "HelloWorld";
  var promise = ajax.requestObject({
    method: "POST",               // Do POST request...
    url: "/rest/password/encode", // ...to this relative URL
    requestBody: password,        // ...using requestBody as string
    contentType: "text/plain",    // ...set Content-Type to text/plain
    accept: "text/plain",         // ...set Accept to text/plain
    xhrCallback: function (xhr) { // ...using custom configuration for underlying XMLHttpRequest
      xhr.timeout = 2000; // set response timeout to 2 seconds
    }
  });

All the parameters expected by requestObject function:

• responseType - tells how to decode a response. Possible values: text and json. Default value is text.
• method - request method. Can be GET, POST, DELETE, PUT. Default value is GET.
• url - relative URL to invoke. Default value is /.
• requestBody - an object that should be sent in the request. Default value is null.
• accept - expected response content type (e.g. value in Accept header). Default value is */*.
• contentType - MIME type that identifies request body encoding scheme. Default value is null which means that this field will not be set.
• xhrCallback - a callback that takes an instance of XMLHttpRequest and does custom configuration on it. accept and contentType options take precedence over changes made in this callback.

The simpler counterpart - request function uses different defaults. It sets contentType to application/json whenever request body is passed to request function. Also it always sets Accept header to application/json and finally responseType is always json.

The fulfilled promise handler of the result of request and requestObject function calls always takes a decoded response body and failed promise handler always takes an instance of XMLHttpRequest used to make the associated AJAX call.

Global AJAX error handlers

Sometimes it might be convenient to set error handler in a uniform way for all the AJAX requests. It can be done by subscribing to global event defined in rsvp-ajax library:

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

  var xhrErrorSubscription = ajax.on(ajax.XHR_ERROR, function (xmlHttpRequest) {
    // ... extract error information from xmlHttpRequest
  });

  // if later we need to unsubscribe from XHR_ERROR, one can do:
  ajax.off(ajax.XHR_ERROR, xhrErrorSubscription);