xaja
v2.0.1
Published
Simple ajax lib
Downloads
6
Readme
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