![](\"http:\/\/secure.travis-ci.org\/kriskowal\/q.png?branch=master\")
<\/p>\n<\/p>\n
![](\"http:\/\/kriskowal.github.io\/q\/q.png\")
<\/p>\n
This is Q version 1, from the 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.<\/p>\n On the first pass, promises can mitigate the \u201cPyramid of Doom\u201d: the situation where code marches to the right faster than it marches forward.<\/p>\n With a promise library, you can flatten the pyramid.<\/p>\n With this approach, you also get implicit error propagation, just like The callback approach is called an \u201cinversion of control\u201d. A function that accepts a callback instead of a return value is saying, \u201cDon\u2019t call me, I\u2019ll call you.\u201d. Promises un-invert the inversion, cleanly separating the input arguments from control flow arguments. This simplifies the use and creation of API\u2019s, particularly variadic, rest and spread arguments.<\/p>\n The Q module can be loaded as:<\/p>\n Q can exchange promises with jQuery, Dojo, When.js, WinJS, and more.<\/p>\n Our wiki contains a number of useful resources, including:<\/p>\n We\u2019d also love to have you join the Q-Continuum mailing list.<\/p>\n Promises have a If 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. In this tutorial, we begin with how to consume and work with promises. We\u2019ll talk about how to create them, and thus create functions like The The If the If the input promise gets fulfilled and you omit the fulfillment handler, the value<\/strong> will go to Q promises provide a If you are writing JavaScript for modern engines only or using CoffeeScript, you may use Promises also have a If you are writing JavaScript for modern engines only or using CoffeeScript, you may use There are two ways to chain promises. You can chain promises either inside or outside handlers. The next two examples are equivalent.<\/p>\n The only difference is nesting. It\u2019s useful to nest handlers if you need to capture multiple input values in your closure.<\/p>\n You can turn an array of promises into a promise for the whole, fulfilled array using If you have a promise for an array, you can use But The The If you have a number of promise-producing functions that need to be run sequentially, you can of course do so manually:<\/p>\n However, if you want to run a dynamically constructed sequence of functions, you\u2019ll want something like this:<\/p>\n You can make this slightly more compact using Or, you could use the ultra-compact version:<\/p>\n One sometimes-unintuive aspect of promises is that if you throw an exception in the fulfillment handler, it will not be caught by the error handler.<\/p>\n To see why this is, consider the parallel between promises and In terms of promises, this means chaining your rejection handler:<\/p>\n It\u2019s 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 Like 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\u2019s an unfortunate pattern that the exceptions can go unobserved.<\/p>\n So, either return it,<\/p>\n Or, end it.<\/p>\n Ending a promise chain makes sure that, if an error doesn\u2019t get handled before the end, it will get rethrown and reported.<\/p>\n This is a stopgap. We are exploring ways to make unhandled errors visible without any explicit handling.<\/p>\n 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.<\/p>\n You can create a promise from a value using You can also use As the name implies, If you have to interface with asynchronous functions that are callback-based instead of promise-based, Q provides a few shortcuts (like Note that a deferred can be resolved with a value or a promise. The This is a simplified implementation of This is a simplified implementation of Finally, you can send a progress notification to the promise with 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.<\/p>\n Below is an example of how to use this This is an alternative promise-creation API that has the same power as the deferred concept, but without introducing another conceptual entity.<\/p>\n Rewriting the If If you are using a function that may return a promise, but just might return a value if it doesn\u2019t need to defer, you can use the \u201cstatic\u201d methods of the Q library.<\/p>\n The All of the other methods on a promise have static analogs with the same name.<\/p>\n The following are equivalent:<\/p>\n 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\u2019t provide all of the same methods. Most libraries only provide a partially functional 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 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.<\/p>\n If the promise is a proxy for a remote object, you can shave round-trips by using these functions instead of 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<\/p>\n with<\/p>\n If you\u2019re working with functions that make use of the Node.js callback pattern, where callbacks are in the form of 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\u2014like You can also create reusable wrappers with Finally, if you\u2019re working with raw deferred objects, there is a Q comes with optional support for \u201clong stack traces,\u201d wherein the v1<\/code> branch in Git. This documentation applies to the latest of both the version 1 and version 0.9 release trains. These releases are stable. There will be no further releases of 0.9 after 0.9.7 which is nearly equivalent to version 1.0.0. All further releases of q@~1.0<\/code> will be backward compatible. The version 2 release train introduces significant and backward-incompatible changes and is experimental at this time.<\/em><\/p>\nstep1(function (value1) {\n step2(value1, function(value2) {\n step3(value2, function(value3) {\n step4(value3, function(value4) {\n \/\/ Do something with value4\n });\n });\n });\n});\n<\/code><\/pre>\nQ.fcall(promisedStep1)\n.then(promisedStep2)\n.then(promisedStep3)\n.then(promisedStep4)\n.then(function (value4) {\n \/\/ Do something with value4\n})\n.catch(function (error) {\n \/\/ Handle any error from all above steps\n})\n.done();\n<\/code><\/pre>\ntry<\/code>, catch<\/code>, and finally<\/code>. An error in promisedStep1<\/code> will flow all the way to the catch<\/code> function, where it\u2019s caught and handled. (Here promisedStepN<\/code> is a version of stepN<\/code> that returns a promise.)<\/p>\nGetting Started<\/h2>\n
\n
Q<\/code> global variable): ~2.5 KB minified and gzipped.<\/li>\nmicrojs\/q<\/code><\/li>\nq#1.0.1<\/code><\/li>\nResources<\/h2>\n
\n
$.Deferred<\/code>.<\/li>\n<\/ul>\nTutorial<\/h2>\n
then<\/code> method, which you can use to get the eventual return value (fulfillment) or thrown exception (rejection).<\/p>\npromiseMeSomething()\n.then(function (value) {\n}, function (reason) {\n});\n<\/code><\/pre>\npromiseMeSomething<\/code> 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<\/code> function gets rejected later by a thrown exception, the second function (the rejection handler) will be called with the exception.<\/p>\nprocess.nextTick<\/code> in Node). This gives you a nice guarantee when mentally tracing the flow of your code, namely that then<\/code> will always return before either handler is executed.<\/p>\npromiseMeSomething<\/code> that return promises, below.<\/p>\nPropagation<\/h3>\n
then<\/code> method returns a promise, which in this example, I\u2019m assigning to outputPromise<\/code>.<\/p>\nvar outputPromise = getInputPromise()\n.then(function (input) {\n}, function (reason) {\n});\n<\/code><\/pre>\noutputPromise<\/code> 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<\/code>.<\/p>\n\n
outputPromise<\/code> will get fulfilled.<\/li>\noutputPromise<\/code> will get rejected.<\/li>\noutputPromise<\/code> will \u201cbecome\u201d that promise. Being able to become a new promise is useful for managing delays, combining results, or recovering from errors.<\/li>\n<\/ul>\ngetInputPromise()<\/code> promise gets rejected and you omit the rejection handler, the error<\/strong> will go to outputPromise<\/code>:<\/p>\nvar outputPromise = getInputPromise()\n.then(function (value) {\n});\n<\/code><\/pre>\noutputPromise<\/code>:<\/p>\nvar outputPromise = getInputPromise()\n.then(null, function (error) {\n});\n<\/code><\/pre>\nfail<\/code> shorthand for then<\/code> when you are only interested in handling the error:<\/p>\nvar outputPromise = getInputPromise()\n.fail(function (error) {\n});\n<\/code><\/pre>\ncatch<\/code> instead of fail<\/code>.<\/p>\nfin<\/code> function that is like a finally<\/code> clause. The final handler gets called, with no arguments, when the promise returned by getInputPromise()<\/code> either returns a value or throws an error. The value returned or error thrown by getInputPromise()<\/code> passes directly to outputPromise<\/code> unless the final handler fails, and may be delayed if the final handler returns a promise.<\/p>\nvar outputPromise = getInputPromise()\n.fin(function () {\n \/\/ close files, database connections, stop servers, conclude tests\n});\n<\/code><\/pre>\n\n
outputPromise<\/code><\/li>\noutputPromise<\/code> 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.<\/li>\n<\/ul>\nfinally<\/code> instead of fin<\/code>.<\/p>\nChaining<\/h3>\n
return getUsername()\n.then(function (username) {\n return getUser(username)\n .then(function (user) {\n \/\/ if we get here without an error,\n \/\/ the value returned here\n \/\/ or the exception thrown here\n \/\/ resolves the promise returned\n \/\/ by the first line\n })\n});\n<\/code><\/pre>\nreturn getUsername()\n.then(function (username) {\n return getUser(username);\n})\n.then(function (user) {\n \/\/ if we get here without an error,\n \/\/ the value returned here\n \/\/ or the exception thrown here\n \/\/ resolves the promise returned\n \/\/ by the first line\n});\n<\/code><\/pre>\nfunction authenticate() {\n return getUsername()\n .then(function (username) {\n return getUser(username);\n })\n \/\/ chained because we will not need the user name in the next event\n .then(function (user) {\n return getPassword()\n \/\/ nested because we need both user and password next\n .then(function (password) {\n if (user.passwordHash !== hash(password)) {\n throw new Error(\"Can't authenticate\");\n }\n });\n });\n}\n<\/code><\/pre>\nCombination<\/h3>\n
all<\/code>.<\/p>\nreturn Q.all([\n eventualAdd(2, 2),\n eventualAdd(10, 20)\n]);\n<\/code><\/pre>\nspread<\/code> as a replacement for then<\/code>. The spread<\/code> function \u201cspreads\u201d 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.<\/p>\nfunction eventualAdd(a, b) {\n return Q.spread([a, b], function (a, b) {\n return a + b;\n })\n}\n<\/code><\/pre>\nspread<\/code> calls all<\/code> initially, so you can skip it in chains.<\/p>\nreturn getUsername()\n.then(function (username) {\n return [username, getUser(username)];\n})\n.spread(function (username, user) {\n});\n<\/code><\/pre>\nall<\/code> 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<\/code>.<\/p>\nQ.allSettled(promises)\n.then(function (results) {\n results.forEach(function (result) {\n if (result.state === \"fulfilled\") {\n var value = result.value;\n } else {\n var reason = result.reason;\n }\n });\n});\n<\/code><\/pre>\nany<\/code> 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.<\/p>\nQ.any(promises)\n.then(function (first) {\n \/\/ Any of the promises was fulfilled.\n}, function (error) {\n \/\/ All of the promises were rejected.\n});\n<\/code><\/pre>\nSequences<\/h3>\n
return foo(initialVal).then(bar).then(baz).then(qux);\n<\/code><\/pre>\nvar funcs = [foo, bar, baz, qux];\n\nvar result = Q(initialVal);\nfuncs.forEach(function (f) {\n result = result.then(f);\n});\nreturn result;\n<\/code><\/pre>\nreduce<\/code>:<\/p>\nreturn funcs.reduce(function (soFar, f) {\n return soFar.then(f);\n}, Q(initialVal));\n<\/code><\/pre>\nreturn funcs.reduce(Q.when, Q(initialVal));\n<\/code><\/pre>\nHandling Errors<\/h3>\n
return foo()\n.then(function (value) {\n throw new Error(\"Can't bar.\");\n}, function (error) {\n \/\/ We only get here if \"foo\" fails\n});\n<\/code><\/pre>\ntry<\/code>\/catch<\/code>. We are try<\/code>-ing to execute foo()<\/code>: the error handler represents a catch<\/code> for foo()<\/code>, while the fulfillment handler represents code that happens after<\/em> the try<\/code>\/catch<\/code> block. That code then needs its own try<\/code>\/catch<\/code> block.<\/p>\nreturn foo()\n.then(function (value) {\n throw new Error(\"Can't bar.\");\n})\n.fail(function (error) {\n \/\/ We get here with either foo's error or bar's error\n});\n<\/code><\/pre>\nProgress Notification<\/h3>\n
then<\/code>:<\/p>\nreturn uploadFile()\n.then(function () {\n \/\/ Success uploading the file\n}, function (err) {\n \/\/ There was an error, and we get the reason for error\n}, function (progress) {\n \/\/ We get notified of the upload's progress as it is executed\n});\n<\/code><\/pre>\nfail<\/code>, Q also provides a shorthand for progress callbacks called progress<\/code>:<\/p>\nreturn uploadFile().progress(function (progress) {\n \/\/ We get notified of the upload's progress\n});\n<\/code><\/pre>\nThe End<\/h3>\n
return foo()\n.then(function () {\n return \"bar\";\n});\n<\/code><\/pre>\nfoo()\n.then(function () {\n return \"bar\";\n})\n.done();\n<\/code><\/pre>\nThe Beginning<\/h3>\n
Using
Q.fcall<\/code><\/h4>\nQ.fcall<\/code>. This returns a promise for 10.<\/p>\nreturn Q.fcall(function () {\n return 10;\n});\n<\/code><\/pre>\nfcall<\/code> to get a promise for an exception.<\/p>\nreturn Q.fcall(function () {\n throw new Error(\"Can't do it\");\n});\n<\/code><\/pre>\nfcall<\/code> can call functions, or even promised functions. This uses the eventualAdd<\/code> function above to add two numbers.<\/p>\nreturn Q.fcall(eventualAdd, 2, 2);\n<\/code><\/pre>\nUsing Deferreds<\/h4>\n
Q.nfcall<\/code> and friends). But much of the time, the solution will be to use deferreds<\/em>.<\/p>\nvar deferred = Q.defer();\nFS.readFile(\"foo.txt\", \"utf-8\", function (error, text) {\n if (error) {\n deferred.reject(new Error(error));\n } else {\n deferred.resolve(text);\n }\n});\nreturn deferred.promise;\n<\/code><\/pre>\nreject<\/code> function is a shorthand for resolving with a rejected promise.<\/p>\n\/\/ this:\ndeferred.reject(new Error(\"Can't do it\"));\n\n\/\/ is shorthand for:\nvar rejection = Q.fcall(function () {\n throw new Error(\"Can't do it\");\n});\ndeferred.resolve(rejection);\n<\/code><\/pre>\nQ.delay<\/code>.<\/p>\nfunction delay(ms) {\n var deferred = Q.defer();\n setTimeout(deferred.resolve, ms);\n return deferred.promise;\n}\n<\/code><\/pre>\nQ.timeout<\/code><\/p>\nfunction timeout(promise, ms) {\n var deferred = Q.defer();\n Q.when(promise, deferred.resolve);\n delay(ms).then(function () {\n deferred.reject(new Error(\"Timed out\"));\n });\n return deferred.promise;\n}\n<\/code><\/pre>\ndeferred.notify<\/code>.<\/p>\nfunction requestOkText(url) {\n var request = new XMLHttpRequest();\n var deferred = Q.defer();\n\n request.open(\"GET\", url, true);\n request.onload = onload;\n request.onerror = onerror;\n request.onprogress = onprogress;\n request.send();\n\n function onload() {\n if (request.status === 200) {\n deferred.resolve(request.responseText);\n } else {\n deferred.reject(new Error(\"Status code was \" + request.status));\n }\n }\n\n function onerror() {\n deferred.reject(new Error(\"Can't XHR \" + JSON.stringify(url)));\n }\n\n function onprogress(event) {\n deferred.notify(event.loaded \/ event.total);\n }\n\n return deferred.promise;\n}\n<\/code><\/pre>\nrequestOkText<\/code> function:<\/p>\nrequestOkText(\"http:\/\/localhost:3000\")\n.then(function (responseText) {\n \/\/ If the HTTP response returns 200 OK, log the response text.\n console.log(responseText);\n}, function (error) {\n \/\/ If there's an error or a non-200 status code, log the error.\n console.error(error);\n}, function (progress) {\n \/\/ Log the progress as it comes in.\n console.log(\"Request progress: \" + Math.round(progress * 100) + \"%\");\n});\n<\/code><\/pre>\nUsing
Q.Promise<\/code><\/h4>\nrequestOkText<\/code> example above using Q.Promise<\/code>:<\/p>\nfunction requestOkText(url) {\n return Q.Promise(function(resolve, reject, notify) {\n var request = new XMLHttpRequest();\n\n request.open(\"GET\", url, true);\n request.onload = onload;\n request.onerror = onerror;\n request.onprogress = onprogress;\n request.send();\n\n function onload() {\n if (request.status === 200) {\n resolve(request.responseText);\n } else {\n reject(new Error(\"Status code was \" + request.status));\n }\n }\n\n function onerror() {\n reject(new Error(\"Can't XHR \" + JSON.stringify(url)));\n }\n\n function onprogress(event) {\n notify(event.loaded \/ event.total);\n }\n });\n}\n<\/code><\/pre>\nrequestOkText<\/code> were to throw an exception, the returned promise would be rejected with that thrown exception as the rejection reason.<\/p>\nThe Middle<\/h3>\n
when<\/code> function is the static equivalent for then<\/code>.<\/p>\nreturn Q.when(valueOrPromise, function (value) {\n}, function (error) {\n});\n<\/code><\/pre>\nreturn Q.all([a, b]);\n<\/code><\/pre>\nreturn Q.fcall(function () {\n return [a, b];\n})\n.all();\n<\/code><\/pre>\nthen<\/code> method. This thankfully is all we need to turn them into vibrant Q promises.<\/p>\nreturn Q($.ajax(...))\n.then(function () {\n});\n<\/code><\/pre>\nQ.invoke<\/code> as a shorthand.<\/p>\nreturn Q.invoke($, 'ajax', ...)\n.then(function () {\n});\n<\/code><\/pre>\nOver the Wire<\/h3>\n
direct manipulation using a promise as a proxy\n-------------------------- -------------------------------\nvalue.foo promise.get(\"foo\")\nvalue.foo = value promise.put(\"foo\", value)\ndelete value.foo promise.del(\"foo\")\nvalue.foo(...args) promise.post(\"foo\", [args])\nvalue.foo(...args) promise.invoke(\"foo\", ...args)\nvalue(...args) promise.fapply([args])\nvalue(...args) promise.fcall(...args)\n<\/code><\/pre>\nthen<\/code>. To take advantage of promises for remote objects, check out Q-Connection.<\/p>\nreturn Q.fcall(function () {\n return [{ foo: \"bar\" }, { foo: \"baz\" }];\n})\n.then(function (value) {\n return value[0].foo;\n});\n<\/code><\/pre>\nreturn Q.fcall(function () {\n return [{ foo: \"bar\" }, { foo: \"baz\" }];\n})\n.get(0)\n.get(\"foo\");\n<\/code><\/pre>\nAdapting Node<\/h3>\n
function(err, result)<\/code>, Q provides a few useful utility functions for converting between them. The most straightforward are probably Q.nfcall<\/code> and Q.nfapply<\/code> (\u201cNode function call\/apply\u201d) for calling Node.js-style functions and getting back a promise:<\/p>\nreturn Q.nfcall(FS.readFile, \"foo.txt\", \"utf-8\");\nreturn Q.nfapply(FS.readFile, [\"foo.txt\", \"utf-8\"]);\n<\/code><\/pre>\nQ.nfcall<\/code>\u2014\u201cun-binds\u201d the method from its owner. To avoid this, you can either use Function.prototype.bind<\/code> or some nice shortcut methods we provide:<\/p>\nreturn Q.ninvoke(redisClient, \"get\", \"user:1:id\");\nreturn Q.npost(redisClient, \"get\", [\"user:1:id\"]);\n<\/code><\/pre>\nQ.denodeify<\/code> or Q.nbind<\/code>:<\/p>\nvar readFile = Q.denodeify(FS.readFile);\nreturn readFile(\"foo.txt\", \"utf-8\");\n\nvar redisClientGet = Q.nbind(redisClient.get, redisClient);\nreturn redisClientGet(\"user:1:id\");\n<\/code><\/pre>\nmakeNodeResolver<\/code> method on deferreds that can be handy:<\/p>\nvar deferred = Q.defer();\nFS.readFile(\"foo.txt\", \"utf-8\", deferred.makeNodeResolver());\nreturn deferred.promise;\n<\/code><\/pre>\nLong Stack Traces<\/h3>\n