A promisified XMLHttpRequest wrapper with json support, extensibility hooks and fixes to most common xhr issues built in. Designed to be used in a CommonJS based module system like Browserify.





GitHub Stars



Last Commit

6yrs ago






Size (min+gzip)




Type Definitions






A promisified XMLHttpRequest wrapper with json support, extensibility hooks and fixes to most common xhr issues built in.

This module's functions (GET, POST, PUT, PATCH and DELETE) returns a promise (

The module will return a JSON formatted response body as a property of the response object if the response Content-Type is "application/json".

It provides JSON "happy" methods to make it easier to work with getting and sending JSON data. (See Usage below for more details.)

It also provides a postFormUrlEncoded() method so you can pass the POST a vanilla JSON object and it will be serialised into a form url encoded body if you need to POST in this format.


npm install basic-ajax


Require the object:

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


Just need to do a get? it's as simple as passing in the url:


Just need to do a get and expect JSON back? Call getJson and it will set the "Accept" header correctly:


Want to tell the server you accept xml or something else not JSON? Just set the "Accept" header manually:

ajax.get('/users', {"Accept": "application/xml"});

You can of course set any headers you like:

ajax.get('/users', {"Accept": "application/json", "Origin": ""});

Okay, so you are expecting JSON back? it's already parsed for you into a "json" property:

ajax.getJson('/').then(function(response) {
    console.log("list of users:");

    for(var index = 0; index < response.json.length; index++) {

POST's, PUT's and PATCH's

Want to POST, PUT or PATCH some JSON? Just call the equivalent "JSON" method and pass in your object: We will set the content type header correctly for you and json stringify the object passed in.

ajax.postJson('/users/add', {"name": "Nick", "age": 18});
ajax.putJson('/users/1', {"name": "Nick", "age": 18});
ajax.patchJson('/users/1', {"op": "replace", "path": "/age", "value": 21});

If you already have your JSON as a string, just pass in a string and we won't attempt to stringify it!

ajax.postJson('/users/add', '{"name": "Nick", "age": 18}');

POSTing, PUTting or PATCHing something that isn't JSON? Want to set your own headers? Just use the base post(), put() or patch() methods and set the headers using a JSON object:'/users/add', {"Content-Type": "application/xml"}, "<person><name>Nick</name><age>18</age></person>");

POSTing bodies in form-url-encoded format

Just use the postFormUrlEncoded() method and pass in a JSON object:

ajax.postFormUrlEncoded('/users/add', {"name": "Nick", "age": 12});

Note: This currently only works on a "shallow" object, ie. a JSON object that is just a set of name/ value pairs - no deep object graph or arrays. Pull requests accepted or let me know if you want this expanded on!


You can make a DELETE call by calling the delete() method:


Response Headers:

Do you wanna see wot response headers you got? Just check da .headers object! Say you get 2 response headers: "Content-Type" and "Location", just get them like this:

ajax.get('/').then(function(response) {

Request Headers:

By default basic-ajax sets the X-Requested-With header to XMLHttpRequest. See the reasoning here: but basically it allows for the server to prevent CSRF attacks.

Basic-ajax does not allow you to override this setting as that is "A Bad Idea".


By default basic-ajax stops all possible browser caching of ajax calls by setting the Cache-Control header to no-cache, the Pragma header to no-cache and the If-Modified-Since header to 1 Jan 2000. This is to stop Internet Explorer's default behaviour to cache ajax calls. More info here:

If for some reason you want to turn this off you can just execute: ajax.allowCaching = false If for some reason you want to override any of these individual headers, just set them in the headers object you pass in and basic-ajax will use your values instead of it's own.


You can add pre and post hooks to basic-ajax. Pre hooks fire immediately prior to an xhr.send() and post hooks fire after a load(), error() or abort() event has been called.

We provide the function: ajax.setHooks([ordered, array, of, hooks]) in order to setup your hooks.

A hooks provider should look like this:

var hook = {
    pre: function (xhr, state) {
    post: function (ro, state) {
  • if a pre function returns an object with a cancel=true property on it then the xhr.send() will not fire and the promise will be immediately resolved returning an object with the reason string set to a reason string you return from the pre() function as well as the xhr object.
  • if a pre function cancels, no other hooks will get run.
  • you can setup either a pre or a post function or both in your hook
  • the state object is for passing state between the pre and post functions.
  • this state is private to each request and private to each hook that is run.
  • We don't currently allow for asynchronous hooks.
  • For more information look at the tests which should act as deeper documentation.

We provide ajax.addHooks() to add hooks to the existing chain of hooks set up (whereas ajax.setHooks will replace the existing chain.) We also provide the function ajax.removeHooks() which will remove all hooks applied by the mechanisms above.


npm test

Rate & Review

Great Documentation0
Easy to Use0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Unwelcoming Community0