kriskowal/q

Q is a JavaScript library that adds promises to the language. A promise is a placeholder object for a value that is not ready yet, for example the result of a network request or a file read. Instead of passing a callback function that gets called later when the work finishes, code asks for a promise and chains follow-up steps onto it. Q was one of the early libraries that brought this pattern to JavaScript and helped shape the design that browsers and Node.js later adopted as the built-in Promise type. The maintainers open the README with a clear note: most projects today should use the native Promise that every modern browser and Node version already provides. Native promises are faster and have better tooling. Q itself is no longer being actively developed. The code is still there, bugs will still be fixed, but new work has been unnecessary for years. The README frames the project as a piece of internet history more than as a current dependency. The main argument the README makes for promises in general is that they replace deeply nested callback code, which the author calls the Pyramid of Doom, with a flat chain. A series of asynchronous steps can be written as one Q.fcall followed by several .then calls, with a single .catch at the end. Errors thrown in any step flow straight to the catch handler, the way exceptions do in normal synchronous code with try and catch. The README also explains that returning a promise from inside a then handler causes the outer promise to wait for that inner one, which is how delays, combinations, and error recovery are built. Q can be loaded in several ways: as a plain script tag that adds a Q global, as a CommonJS module through the npm package q, as an AMD module, as a component, through Bower, or through NuGet. The minified gzipped script is about 2.5 kilobytes. Q can also exchange promises with other libraries from that era, including jQuery, Dojo, When.js, and WinJS. The rest of the README is a tutorial covering the then method, propagation rules, and the fail and fin shorthands. Links from the project wiki point to a full API reference, an examples gallery, a list of libraries that work with Q, and a guide for migrating from jQuery Deferred objects. The full README is longer than what was shown.