q

Note

Please consider using JavaScript promises instead of Q. Native promises are faster, have better tooling support and are the future.

When work on Q began, promises were an academic novelty in JavaScript, unlikely to be adopted much less popular, though obviously full of…promise. Callbacks dominated the landscape. Q aimed to introduce a technology to JavaScript that had been proven and vetted in languages like E and C♯. With four years of incubation, evangelism, education, and feedback, promises became part of the language. Every modern browser contains a built-in Promise implementation. Being able to influence the internet and working on a library used by millions of codebases was an exciting and humbling experience.

Q isn't going anywhere. The code is still here and bugs will be fixed but further development has been unnecessary for many years. We encourage you to read the code and the explainers to glimpse into the history of the internet.

Q

If a function cannot return a value or throw an exception without blocking, it can return a promise instead. A promise is an object that represents the return value or the thrown exception that the function may eventually provide. A promise can also be used as a proxy for a remote object to overcome latency.

On the first pass, promises can mitigate the “Pyramid of Doom”: the situation where code marches to the right faster than it marches forward.

step1(function (value1) {
    step2(value1, function(value2) {
        step3(value2, function(value3) {
            step4(value3, function(value4) {
                // Do something with value4
            });
        });
    });
});

With a promise library, you can flatten the pyramid.

Q.fcall(promisedStep1)
.then(promisedStep2)
.then(promisedStep3)
.then(promisedStep4)
.then(function (value4) {
    // Do something with value4
})
.catch(function (error) {
    // Handle any error from all above steps
})
.done();

With this approach, you also get implicit error propagation, just like try, catch, and finally. An error in promisedStep1 will flow all the way to the catch function, where it’s caught and handled. (Here promisedStepN is a version of stepN that returns a promise.)

The callback approach is called an “inversion of control”. A function that accepts a callback instead of a return value is saying, “Don’t call me, I’ll call you.”. Promises un-invert the inversion, cleanly separating the input arguments from control flow arguments. This simplifies the use and creation of API’s, particularly variadic, rest and spread arguments.

Getting Started

The Q module can be loaded as:

• A <script> tag (creating a Q global variable): ~2.5 KB minified and gzipped.
• A Node.js and CommonJS module, available in npm as the q package
• An AMD module
• A component as microjs/q
• Using bower as q#^1.4.1
• Using NuGet as Q

Q can exchange promises with jQuery, Dojo, When.js, WinJS, and more.

Resources

Our wiki contains a number of useful resources, including:

• A method-by-method Q API reference.
• A growing examples gallery, showing how Q can be used to make everything better. From XHR to database access to accessing the Flickr API, Q is there for you.
• There are many libraries that produce and consume Q promises for everything from file system/database access or RPC to templating. For a list of some of the more popular ones, see Libraries.
• If you want materials that introduce the promise concept generally, and the below tutorial isn't doing it for you, check out our collection of presentations, blog posts, and podcasts.
• A guide for those coming from jQuery's $.Deferred.

We'd also love to have you join the Q-Continuum mailing list.

Tutorial

Promises have a then method, which you can use to get the eventual return value (fulfillment) or thrown exception (rejection).

promiseMeSomething()
.then(function (value) {
}, function (reason) {
});

If promiseMeSomething returns a promise that gets fulfilled later with a return value, the first function (the fulfillment handler) will be called with the value. However, if the promiseMeSomething function gets rejected later by a thrown exception, the second function (the rejection handler) will be called with the exception.

Note that resolution of a promise is always asynchronous: that is, the fulfillment or rejection handler will always be called in the next turn of the event loop (i.e. process.nextTick in Node). This gives you a nice guarantee when mentally tracing the flow of your code, namely that then will always return before either handler is executed.

In this tutorial, we begin with how to consume and work with promises. We'll talk about how to create them, and thus create functions like promiseMeSomething that return promises, below.

Propagation

The then method returns a promise, which in this example, I’m assigning to outputPromise.

var outputPromise = getInputPromise()
.then(function (input) {
}, function (reason) {
});

The outputPromise variable becomes a new promise for the return value of either handler. Since a function can only either return a value or throw an exception, only one handler will ever be called and it will be responsible for resolving outputPromise.

• If you return a value in a handler, outputPromise will get fulfilled.

• If you throw an exception in a handler, outputPromise will get rejected.

• If you return a promise in a handler, outputPromise will “become” that promise. Being able to become a new promise is useful for managing delays, combining results, or recovering from errors.

If the getInputPromise() promise gets rejected and you omit the rejection handler, the error will go to outputPromise:

var outputPromise = getInputPromise()
.then(function (value) {
});

If the input promise gets fulfilled and you omit the fulfillment handler, the value will go to outputPromise:

var outputPromise = getInputPromise()
.then(null, function (error) {
});

Q promises provide a fail shorthand for then when you are only interested in handling the error:

var outputPromise = getInputPromise()
.fail(function (error) {
});

If you are writing JavaScript for modern engines only or using CoffeeScript, you may use catch instead of fail.

Promises also have a fin function that is like a finally clause. The final handler gets called, with no arguments, when the promise returned by getInputPromise() either returns a value or throws an error. The value returned or error thrown by getInputPromise() passes directly to outputPromise unless the final handler fails, and may be delayed if the final handler returns a promise.

var outputPromise = getInputPromise()
.fin(function () {
    // close files, database connections, stop servers, conclude tests
});

• If the handler returns a value, the value is ignored
• If the handler throws an error, the error passes to outputPromise
• If the handler returns a promise, outputPromise gets postponed. The eventual value or error has the same effect as an immediate return value or thrown error: a value would be ignored, an error would be forwarded.

If you are writing JavaScript for modern engines only or using CoffeeScript, you may use finally instead of fin.

Chaining

There are two ways to chain promises. You can chain promises either inside or outside handlers. The next two examples are equivalent.

return getUsername()
.then(function (username) {
    return getUser(username)
    .then(function (user) {
        // if we get here without an error,
        // the value returned here
        // or the exception thrown here
        // resolves the promise returned
        // by the first line
    })
});

return getUsername()
.then(function (username) {
    return getUser(username);
})
.then(function (user) {
    // if we get here without an error,
    // the value returned here
    // or the exception thrown here
    // resolves the promise returned
    // by the first line
});

The only difference is nesting. It’s useful to nest handlers if you need to capture multiple input values in your closure.

function authenticate() {
    return getUsername()
    .then(function (username) {
        return getUser(username);
    })
    // chained because we will not need the user name in the next event
    .then(function (user) {
        return getPassword()
        // nested because we need both user and password next
        .then(function (password) {
            if (user.passwordHash !== hash(password)) {
                throw new Error("Can't authenticate");
            }
        });
    });
}

Combination

You can turn an array of promises into a promise for the whole, fulfilled array using all.

return Q.all([
    eventualAdd(2, 2),
    eventualAdd(10, 20)
]);

If you have a promise for an array, you can use spread as a replacement for then. The spread function “spreads” the values over the arguments of the fulfillment handler. The rejection handler will get called at the first sign of failure. That is, whichever of the received promises fails first gets handled by the rejection handler.

function eventualAdd(a, b) {
    return Q.spread([a, b], function (a, b) {
        return a + b;
    })
}

But spread calls all initially, so you can skip it in chains.

return getUsername()
.then(function (username) {
    return [username, getUser(username)];
})
.spread(function (username, user) {
});

The all function returns a promise for an array of values. When this promise is fulfilled, the array contains the fulfillment values of the original promises, in the same order as those promises. If one of the given promises is rejected, the returned promise is immediately rejected, not waiting for the rest of the batch. If you want to wait for all of the promises to either be fulfilled or rejected, you can use allSettled.

Q.allSettled(promises)
.then(function (results) {
    results.forEach(function (result) {
        if (result.state === "fulfilled") {
            var value = result.value;
        } else {
            var reason = result.reason;
        }
    });
});

The any function accepts an array of promises and returns a promise that is fulfilled by the first given promise to be fulfilled, or rejected if all of the given promises are rejected.

Q.any(promises)
.then(function (first) {
    // An