Skip to content
NOT MAINTAINED – this library was fun but hey, you can just use now :) – Minimal Promise ajax library based on Q
JavaScript HTML
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


A simple Promise-based ajax library based on Q.

Qajax is a simple and pure XMLHttpRequest wrapper.

Supported browsers

All browsers are supported (including IE).

SauceLabs Status


bower install qajax

Also available on NPM.


Checkout the Annotated Source Code

Usages and explanations

Qajax does not involve magic but does the strict minimum to work with ajax on all browsers (IE is supported!).

Qajax has been designed using Promise and split up into pure functions composable with .then.

The Qajax function just returns a successful Promise of XHR when the server has returned a result - whatever the status code is.

There are 3 possible signatures:

Qajax(url: String) => Promise[XHR]
Qajax(options: Object) => Promise[XHR]
Qajax(url: String, options: Object) => Promise[XHR]

Simple usage:

var promiseOfXHR = Qajax("/all.json");
// short version of: Qajax({ url: "/all.json", method: "GET" });

At this time, the promise is only rejected if the server has failed to reply to the client (network problem or timeout reached).

If you want to filter only on success statuses, then you need the Qajax.filterSuccess function:

var promiseOfSuccessfulXHR = 

But you can also provide you own filter logic:

var promiseOf200XHR = 
  .then(Qajax.filterStatus(function (code) {
    return code == 200; /* only support 200 */ 

And at the end you can map it to a JSON:

var promiseOfJson = 

Or you can use the getJSON shortcut for this specific use-case:

var promiseOfJson = Qajax.getJSON("/all.json");

POST & submit data

Of-course, you can use other HTTP Verbs like POST with Qajax:

Qajax({ url: "/entry", method: "POST" })
  .get("responseText") // using a cool Q feature here
  .then(function (txt) {
    console.log("server returned: "+txt);
  }, function (err) {
    console.log("xhr failure: ", err);

You can also submit some data as JSON:

Qajax({ url: "/people", method: "POST", data: { name: "Gaetan", age: 23 } })
  .then(doYourSuccessStuff, displayAnError)


Qajax.serialize helps you to deal with query string parameters:

var lastYearYoungPeople = 
  Qajax.getJSON("/people.json?"+Qajax.serialize({ from: "2012-01-01", to: "2013-01-01", "age$lt": 18 }));
  // will get from: "/people.json?from=2012-01-01&to=2013-01-01&age%24lt=18"

More advanced features

  • You can get progress event of the Ajax download. Exemple:
Qajax("/download").progress(function (xhrProgressEvent) {

See also:

  • Qajax has a timeout:
var p = Qajax("/", { timeout: 5000 });
// p will be rejected if the server is not responding in 5 seconds.

The default timeout is Qajax.defaults.timeout and can be overriden.

  • You can set XHR headers by giving the header options.

  • You can give a cancellation Promise to abort an ajax request.

Here is a typical use case:

var cancellationD = null;
function getResults (query) {
  if (cancellationD) {
  cancellationD = Q.defer();
  return Qajax({
    url: "/search?"+Qajax.serialize({ q: query }),
    cancellation: cancellationD.promise
 * getResults can be called typically for a typeahead,
 * it ensures it never creates 2 requests at the same time,
 * the previous xhr is aborted if still running so it let the latest query have the priority.
  • More defaults:
    • logs: Disable/Enable the logs
    • ie: Disable/Enable the IE support
    • header: Global headers for all requests
    • base: A base url for all requests


The library is stress-tested with qunit and a mock node.js server which test different edge-cases like different HTTP code, method, server lag,...

SauceLabs Status

Test locally: grunt test-local and go to http://localhost:9999/test/.


Install dev deps with npm install. Then run grunt.

Release Note


  • Implement the onprogress XHR event support using the progress event of the returned Promise.
  • Introduce cancellation parameter. It allows to provide a "cancellation" promise which if fulfilled will cancel the current XHR.
  • Deprecate the xhr parameter: use cancellation instead.


  • Put global configuration variables in a Qajax.defaults Object.
  • Add more defaults:
    • logs: Disable/Enable the logs
    • ie: Disable/Enable the IE support
    • timeout: Configure timeout for all requests
    • header: Global headers for all requests
    • base: A base url for all requests
  • timeout is now disabled when timeout is 0 (or null)


  • AMD module compatibility


  • Add new signature Qajax(url, settings) + validation


  • Using require('q') properly


  • Fix CommonJS compatibility


  • Initial release with Qajax, filterStatus, filterSuccess, toJSON, getJSON, serialize
Something went wrong with that request. Please try again.