"readme":"[](http://travis-ci.org/kriskowal/q)\n\n<a href=\"http://promises-aplus.github.com/promises-spec\">\n <img src=\"http://kriskowal.github.io/q/q.png\"\n align=\"right\" alt=\"Q logo\"/>\n</a>\n\n*ThisisQversion1,fromthe`v1`branchinGit.Thisdocumentationappliesto\nthelatestofboththeversion1andversion0.9releasetrains.Thesereleases\narestable.Therewillbenofurtherreleasesof0.9after0.9.7whichisnearly\nequivalenttoversion1.0.0.Allfurtherreleasesof`q@~1.0`willbebackward\ncompatible.Theversion2releasetrainintroducessignificantand\nbackward-incompatiblechangesandisexperimentalatthistime.*\n\nIfafunctioncannotreturnavalueorthrowanexceptionwithout\nblocking,itcanreturnapromiseinstead.Apromiseisanobject\nthatrepresentsthereturnvalueorthethrownexceptionthatthe\nfunctionmayeventuallyprovide.Apromisecanalsobeusedasa\nproxyfora[remoteobject][Q-Connection]toovercomelatency.\n\n[Q-Connection]:https://github.com/kriskowal/q-connection\n\nOn the first pass, promises can mitigate the “[Pyramid of\nDoom][POD]”: the situation where code marches to the right faster\nthan it marches forward.\n\n[POD]: http://calculist.org/blog/2011/12/14/why-coroutines-wont-work-on-the-web/\n\n```javascript\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```\n\nWith a promise library, you can flatten the pyramid.\n\n```javascript\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```\n\nWith this approach, you also get implicit error propagation, just like `try`,\n`catch`, and `finally`. An error in `promisedStep1` will flow all the way to\nthe `catch` function, where it’s caught and handled. (Here `promisedStepN` is\na version of `stepN` that returns a promise.)\n\nThe callback approach is called an “inversion of control”.\nA function that accepts a callback instead of a return value\nis saying, “Don’t call me, I’ll call you.”. Promises\n[un-invert][IOC] the inversion, cleanly separating the input\narguments from control flow arguments. This simplifies the\nuse and creation of API’s, particularly variadic,\nrest and spread arguments.\n\n[IOC]: http://www.slideshare.net/domenicdenicola/callbacks-promises-and-coroutines-oh-my-the-evolution-of-asynchronicity-in-javascript\n\n\n## Getting Started\n\nThe Q module can be loaded as:\n\n- A ``<script>`` tag (creating a ``Q`` global variable): ~2.5 KB minified and\n gzipped.\n- A Node.js and CommonJS module, available in [npm](https://npmjs.org/) as\n the [q](https://npmjs.org/package/q) package\n- An AMD module\n- A [component](https://github.com/component/component) as ``microjs/q``\n- Using [bower](http://bower.io/) as `q#1.0.1`\n- Using [NuGet](http://nuget.org/) as [Q](https://nuget.org/packages/q)\n\nQ can exchange promises with jQuery, Dojo, When.js, WinJS, and more.\n\n## Resources\n\nOur [wiki][] contains a number of useful resources, including:\n\n- A method-by-method [Q API reference][reference].\n- A growing [examples gallery][examples], showing how Q can be used to make\n everything better. From XHR to database access to accessing the Flickr API,\n Q is there for you.\n- There are many libraries that produce and consume Q promises for everything\n from file system/database access or RPC to templating. For a list of some of\n the more popular ones, see [Libraries][].\n- If you want materials that introduce the promise concept generally, and the\n below tutorial isn't doing it for you, check out our collection of\n [presentations, blog posts, and podcasts][resources].\
