You signed in with another tab or window.
Reload
to refresh your session.
You signed out in another tab or window.
Reload
to refresh your session.
You switched accounts on another tab or window.
Reload
to refresh your session.
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.
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
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
.
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
.
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
:
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.
varoutputPromise=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.
returngetUsername().then(function(username){returngetUser(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});
returngetUsername().then(function(username){returngetUser(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.
functionauthenticate(){returngetUsername().then(function(username){returngetUser(username);// chained because we will not need the user name in the next event.then(function(user){returngetPassword()// nested because we need both user and password next.then(function(password){if(user.passwordHash!==hash(password)){thrownewError("Can't authenticate");});});
Combination
You can turn an array of promises into a promise for the whole,
fulfilled array using all.
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.
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.
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){// Any of the promises was fulfilled.},function(error){// All of the promises were rejected.});
Sequences
If you have a number of promise-producing functions that need
to be run sequentially, you can of course do so manually:
One sometimes-unintuitive aspect of promises is that if you throw an
exception in the fulfillment handler, it will not be caught by the error
handler.
returnfoo().then(function(value){thrownewError("Can't bar.");},function(error){// We only get here if "foo" fails});
To see why this is, consider the parallel between promises and
try/catch. We are try-ing to execute foo(): the error
handler represents a catch for foo(), while the fulfillment handler
represents code that happens after the try/catch block.
That code then needs its own try/catch block.
In terms of promises, this means chaining your rejection handler:
returnfoo().then(function(value){thrownewError("Can't bar.");.fail(function(error){// We get here with either foo's error or bar's error});
Progress Notification
It's possible for promises to report their progress, e.g. for tasks that take a
long time like a file upload. Not all promises will implement progress
notifications, but for those that do, you can consume the progress values using
a third parameter to then:
returnuploadFile().then(function(){// Success uploading the file},function(err){// There was an error, and we get the reason for error},function(progress){// We get notified of the upload's progress as it is executed});
Like fail, Q also provides a shorthand for progress callbacks
called progress:
returnuploadFile().progress(function(progress){// We get notified of the upload's progress});
The End
When you get to the end of a chain of promises, you should either
return the last promise or end the chain. Since handlers catch
errors, it’s an unfortunate pattern that the exceptions can go
unobserved.
So, either return it,
returnfoo().then(function(){return"bar";});
Or, end it.
foo().then(function(){return"bar";.done();
Ending a promise chain makes sure that, if an error doesn’t get
handled before the end, it will get rethrown and reported.
This is a stopgap. We are exploring ways to make unhandled errors
visible without any explicit handling.
The Beginning
Everything above assumes you get a promise from somewhere else. This
is the common case. Every once in a while, you will need to create a
promise from scratch.
Using Q.fcall
You can create a promise from a value using Q.fcall. This returns a
promise for 10.
returnQ.fcall(function(){return10;});
You can also use fcall to get a promise for an exception.
returnQ.fcall(function(){thrownewError("Can't do it");});
As the name implies, fcall can call functions, or even promised
functions. This uses the eventualAdd function above to add two
numbers.
returnQ.fcall(eventualAdd,2,2);
Using Deferreds
If you have to interface with asynchronous functions that are callback-based
instead of promise-based, Q provides a few shortcuts (like Q.nfcall and
friends). But much of the time, the solution will be to use deferreds.
Note that a deferred can be resolved with a value or a promise. The
reject function is a shorthand for resolving with a rejected
promise.
// this:deferred.reject(newError("Can't do it"));// is shorthand for:varrejection=Q.fcall(function(){thrownewError("Can't do it");});deferred.resolve(rejection);
Finally, you can send a progress notification to the promise with
deferred.notify.
For illustration, this is a wrapper for XML HTTP requests in the browser. Note
that a more thorough implementation would be in order in practice.
functionrequestOkText(url){varrequest=newXMLHttpRequest();vardeferred=Q.defer();request.open("GET",url,true);request.onload=onload;request.onerror=onerror;request.onprogress=onprogress;request.send();functiononload(){if(request.status===200){deferred.resolve(request.responseText);}else{deferred.reject(newError("Status code was "+request.status));functiononerror(){deferred.reject(newError("Can't XHR "+JSON.stringify(url)));functiononprogress(event){deferred.notify(event.loaded/event.total);returndeferred.promise;
Below is an example of how to use this requestOkText function:
requestOkText("http://localhost:3000").then(function(responseText){// If the HTTP response returns 200 OK, log the response text.console.log(responseText);},function(error){// If there's an error or a non-200 status code, log the error.console.error(error);},function(progress){// Log the progress as it comes in.console.log("Request progress: "+Math.round(progress*100)+"%");});
Using Q.Promise
This is an alternative promise-creation API that has the same power as
the deferred concept, but without introducing another conceptual entity.
Rewriting the requestOkText example above using Q.Promise:
functionrequestOkText(url){returnQ.Promise(function(resolve,reject,notify){varrequest=newXMLHttpRequest();request.open("GET",url,true);request.onload=onload;request.onerror=onerror;request.onprogress=onprogress;request.send();functiononload(){if(request.status===200){resolve(request.responseText);}else{reject(newError("Status code was "+request.status));functiononerror(){reject(newError("Can't XHR "+JSON.stringify(url)));functiononprogress(event){notify(event.loaded/event.total);});
If requestOkText were to throw an exception, the returned promise would be
rejected with that thrown exception as the rejection reason.
The Middle
If you are using a function that may return a promise, but just might
return a value if it doesn’t need to defer, you can use the “static”
methods of the Q library.
The when function is the static equivalent for then.
All of the other methods on a promise have static analogs with the
same name.
The following are equivalent:
returnQ.all([a,b]);
returnQ.fcall(function(){return[a,b];.all();
When working with promises provided by other libraries, you should
convert it to a Q promise. Not all promise libraries make the same
guarantees as Q and certainly don’t provide all of the same methods.
Most libraries only provide a partially functional then method.
This thankfully is all we need to turn them into vibrant Q promises.
returnQ($.ajax(...)).then(function(){});
If there is any chance that the promise you receive is not a Q promise
as provided by your library, you should wrap it using a Q function.
You can even use Q.invoke as a shorthand.
returnQ.invoke($,'ajax', ...).then(function(){});
Over the Wire
A promise can serve as a proxy for another object, even a remote
object. There are methods that allow you to optimistically manipulate
properties or call functions. All of these interactions return
promises, so they can be chained.
direct manipulation using a promise as a proxy
-------------------------- -------------------------------
value.foo promise.get("foo")
value.foo = value promise.put("foo", value)
delete value.foo promise.del("foo")
value.foo(...args) promise.post("foo", [args])
value.foo(...args) promise.invoke("foo", ...args)
value(...args) promise.fapply([args])
value(...args) promise.fcall(...args)
If the promise is a proxy for a remote object, you can shave
round-trips by using these functions instead of then. To take
advantage of promises for remote objects, check out Q-Connection.
Even in the case of non-remote objects, these methods can be used as
shorthand for particularly-simple fulfillment handlers. For example, you
can replace
If you're working with functions that make use of the Node.js callback pattern,
where callbacks are in the form of function(err, result), Q provides a few
useful utility functions for converting between them. The most straightforward
are probably Q.nfcall and Q.nfapply ("Node function call/apply") for calling
Node.js-style functions and getting back a promise:
If you are working with methods, instead of simple functions, you can easily
run in to the usual problems where passing a method to another function—like
Q.nfcall—"un-binds" the method from its owner. To avoid this, you can either
use Function.prototype.bind or some nice shortcut methods we provide:
Q comes with optional support for “long stack traces,” wherein the stack
property of Error rejection reasons is rewritten to be traced along
asynchronous jumps instead of stopping at the most recent one. As an example:
usually would give a rather unhelpful stack trace looking something like
Error: boo!
at explode (/path/to/test.js:3:11)
at _fulfilled (/path/to/test.js:q:54)
at resolvedValue.promiseDispatch.done (/path/to/q.js:823:30)
at makePromise.promise.promiseDispatch (/path/to/q.js:496:13)
at pending (/path/to/q.js:397:39)
at process.startup.processNextTick.process._tickCallback (node.js:244:9)
But, if you turn this feature on by setting
Q.longStackSupport=true;
then the above code gives a nice stack trace to the tune of
Error: boo!
at explode (/path/to/test.js:3:11)
From previous event:
at theDepthsOfMyProgram (/path/to/test.js:2:16)
at Object.<anonymous> (/path/to/test.js:7:1)
Note how you can see the function that triggered the async operation in the
stack trace! This is very helpful for debugging, as otherwise you end up getting
only the first line, plus a bunch of Q internals, with no sign of where the
operation started.
In node.js, this feature can also be enabled through the Q_DEBUG environment
variable:
Q_DEBUG=1 node server.js
This will enable long stack support in every instance of Q.
This feature does come with somewhat-serious performance and memory overhead,
however. If you're working with lots of promises, or trying to scale a server
to many users, you should probably keep it off. But in development, go for it!
Tests
You can view the results of the Q test suite in your browser!