Xaja

A simple ajax helper library.

Basic Usage

Interface is similar to jQuery's $.ajax, you can make a request:

const result = xaja.request('/some/url');
result.then(text => console.log(text));
 
// can also take a configuration object:
const result = xaja.request({
  url: '/some/other/url',
  method: 'GET',
  responseType: 'json',
}).then(json => {
  // do stuff with the json data
});
 
// alternatively using async/await
const json = await xaja.request('/some/json/data');
// do something with the result

Xaja abstracts over fetch, and will load an appropriate polyfill if there's no native implementation. NOTE: xaja does not load a Promise polyfill, if you're using browsers old enough to lack Promise support you'll need to load a polyfill before xaja. In the case of native fetch, you can get the raw response object:

const stream = xaja.request({
  url: '/some/stream/of/data',
  responseType: 'stream',
}).then(response => {
  if (response instanceof Response) {
    console.log('I am a raw Response object!');
  }
});

HTTP Error Codes

Unlike raw fetch, xaja will reject the returned Promise if the HTTP status code indicates an error. Any code not in the 200-399 range will cause a rejection.

Shorthand

In addition to the request function, xaja also offers get, post, and getJSON shorthand functions that invoke request with the appropriate configuration. They have the following signature:

(url:String, data:FormData|String|Object<optional>, options:Object<optional>) => Promise(Any)

Options Object

The options object supports the following parameters. Only the url parameter is required:

url:String

The url to be requested.

data:FormData|String|Object

Data to be passed along with the request. For POST requests it's passed as the body to the fetch call, for GET requests it is converted to a query string and appended to the url. Usernames and passwords are automatically stripped out and converted to an Authorization header.

method:String

HTTP method. Defaults to GET.

responseType:String

Expected response, when set to text or html automatically pulls the response text. For json it pulls the responsejson, etc. If set to stream or some unknown value you will get back the raw Response object. Defaults to text.

contentType:String

Mime type of the supplied data, e.g. application/x-www-form-urlencoded. Browsers are now pretty good at guessing this without any programmer input.

timeout:Number

Amount of time in milliseconds before the returned Promise rejects. Defaults to none.

cache:Boolean

If true the response's text/json/etc. will be cached in localStorage by the url, on subsequent requests if there is a timeout or error the Promise will resolve to the cached value rather than rejecting. Defaults to false.

headers:Headers|Object

The headers for the request.

credentials:String

The security setting for requests: e.g. same-origin.

Accessing the Request object

The promises returned by request et. al., if being used directly (rather than async/await) have an additional request property that contains the underlying Request object:

const promise = xaja.get('/some/url');
promise.request instanceof Request; // true