ajax-promises
Small utility library for making common types of AJAX requests and return Promises + some extras.
NOTE: This does more or less the same as the standard upcoming fetch API and you probably want to use that instead. This repository mostly kept for historical purposes. :)
API
ajaxPromises.version
contains current version of ajaxPromises.
All GET/POST/HEAD methods take an optional options
argument. Current options:
headers
- a key-value object of extra HTTP headers to send along. Note that 'Content-type'
is overwritten when doing POSTs.withCredentials
- boolean, same as request.withCredentials (default: false
).
Method calls:
get(url, options = {})
- GET url with options.post(url, data, options = {})
- POST data to url (with options) as x-www-form-urlencoded
. This usually works for POSTing to mostpostJson(url, data, options = {})
- POST data as JSON to url (with options).head(url, options = {})
- HEAD request, then.encodeQuery
- URL-encode a key-value object for use as query string.
Promise enhancements
GET/POST promises returned can, instead of using .then()
, call .json()
in the same way to parse the result first. This is just the same as calling then(JSON.parse)
.
The promises returned also have a headers()
method which is a separate promise returning the headers of the request. If only the headers are of interest, use the head()
method.
Error handling
In case of errors, HTTP or otherwise, the error object in the catch clause will have the XMLHttpRequest
object available as e.request
for further inspection.
Usage
NPM (es6)
ajax-promises is written in es6, so if you are including the NPM module via browserify or similar, you may also need a transpiler such as babel/babelify if targeting current browsers.
npm install --save ajax-promises
const ajaxPromises = require('ajax-promises');
Javascript (es5)
The dist
directory contains UMD comipled files (minified and not) with source-maps, transpiled to es5 that can be included directly using a <script>
tag or loaded using CommonJS or RequireJS.
Examples
const data = {
single: 'abcdefghi',
multiple: ['abc', 'def', 'ghi']
};
ajaxPromises.get(url)
.then(console.log)
.catch(console.error);
ajaxPromises.get(url)
.json(console.log)
.catch(console.error);
ajaxPromises.get(url, {headers: {Accept: 'application/json'}})
.json(console.log)
.catch(console.error);
ajaxPromises.get(url)
.headers(console.log)
.then(console.log)
.catch(console.error);
ajaxPromises.get(url + '?' + ajaxPromises.encodeQuery(data))
.then(console.log)
.catch(console.error);
ajaxPromises.post(url, data)
.then(console.log)
.catch(console.error);
ajaxPromises.postJson(url, data)
.then(console.log)
.catch(console.error);
const hogan = require('hogan.js');
ajaxPromises.post(url, data)
.then(hogan.compile)
.then(console.log)
.catch(console.error);
ajaxPromises.head(url)
.then(console.log)
.catch(console.error);
Contribute
Patches and enhancements very welcome! Please make sure npm run lint
runs cleanly.