Provides a defer/when style promise API for JavaScript- usable as a CommonJS module, in Node,- usable as a <script> in all web browsers,- inspired by Tyler Close's Waterken ref_send promises, and- compliant with   -http://wiki.commonjs.org/wiki/Promises/A   -http://wiki.commonjs.org/wiki/Promises/B   -http://wiki.commonjs.org/wiki/Promises/DFor Node:    $ curlhttp://npmjs.org/install.sh | sh    $ npm install q    $ node examples/test.jsAPPLIED INTRODUCTION--------------------Skipping past what an asynchronous promise is and how to usethem directly for a moment, compare the usage of thislibrary to Tim Caswell's excellent `step` library.https://github.com/creationix/stepThe `q/util` module, included here, provides a `step`function similar to Tim's.  It takes any number of functionsas arguments and runs them in serial order.  Each functionreturns a promise to complete its step.  When that promiseis deeply resolved (meaning there are no more unfinishedjobs in its object graph), the resolution is passed as theargument to the next step.    var Q = require("q/util");    var FS = require("q-fs");    Q.step(        function () {            return FS.read(__filename);            // __filename is NodeJS-specific        },        function (text) {            return text.toUpperCase();        },        function (text) {            console.log(text);        }    );In Node, this example reads itself and writes itself out inall capitals.  Notice that any value can be treated as analready resolved promise, since the second and third stepsreturn a string and `undefined` respectively.You can also perform actions in parallel.  This examplereads two files at the same time and returns an array ofpromises for the results.  Since the second step has morethan one argument, the results array gets unpacked into thevariadic arguments.    var Q = require("q/util");    var FS = require("q-fs");    Q.step(        function () {            return [                FS.read(__filename),                FS.read("/etc/passwd")            ];        },        function (self, passwd) {            console.log(__filename + ':', self.length);            console.log('/etc/passwd:', passwd.length);        }    );The number of tasks performed in each step is not limited.You can just as well return an array of promises ofindefinite length.  This example reads all of the files inthe same directory as the program and notes the length ofeach.    var Q = require("q/util");    var FS = require("q-fs");    Q.step(        function () {            return FS.list(__dirname);        },        function (fileNames) {            return fileNames.map(function (fileName) {                return [fileName, FS.read(fileName)];            });        },        function (files) {            files.forEach(function (pair) {                var fileName = pair[0];                var file = pair[1];                console.log(fileName, file.length);            });        }    );All of these examples use the `q-fs` module, which ispackaged separately.  You can try these programs,`step{1,2,3}.js` in the `examples/` directory of thispackage.When working with promises, exceptions are generally onlythrown to indicate programmer errors.  Promise-returningAPI`s generally `reject` their promises to indicate that thepromise will never be resolved/fulfilled.  As such, theabove programs will terminate when the first step rejects athe returned promise, which can happen if there is an errorwhile reading or listing a file.  The rejection can beobserved because the `step` function returns a `promise`that will be eventually resolved by the return value of thelast step.    var completed = Q.step(...);We use the `when` method to observe either the resolution orthe rejection of the promise.    Q.when(completed, function callback(completion) {        // ok    }, function errback(reason) {        // error    });If a rejection is not explicitly observed, it getsimplicitly forwarded to the promise returned by `when`.This is the implementation of `step` in terms of the `when`method and the `deep` resolver method.    function step() {        return Array.prototype.reduce.call(            arguments,            function (value, callback) {                return Q.when(deep(value), function (value) {                    if (callback.length > 1) {                        return callback.apply(undefined, value);                    } else {                        return callback(value);                    }                });            },            undefined        );    }Thenables---------The Q API supports CommonJS/Promises/A, Kris Zyp's proposalfor "thenable" promises.  A thenable is any object with a"then(callback, errback)" method.  The "then" method, inturn, returns a promise for whatever value the callback'seventually return.  Thus, promises are chainable.Let's review Tim's example.  This illustrates the sameconcept as the first example.  We asynchronously read ourown program and print it out in all capitals.    var Q = require("q");    var FS = require("q-fs");    Q.when(FS.read(__filename))    .then(function (text) {        return text.toUpperCase();    }).then(function (text) {        console.log(text);    });/!\ IMPORTANTThe call to "Q.when" is not necessary but provides manyassurances that, even if the FS API is poorly written oreven if it is *maliciously* written, that the promisereturned will behave consistently.  That means that yourcallbacks will all occur in future turns of the event loop(so the state in your closure doesn't change), and that onecallback for each "thenable" will ever be called (so thatthe state in your closure doesn't change more than once).This example uses the "q/util" module again, because it hasthat lovely "deep" method for turning objects with promisesinside-out (to a promise for an object).    var Q = require("q/util");    var FS = require("q-fs");    Q.when(Q.deep({        "self": FS.read(__filename),        "passwd": FS.read("/etc/passwd")    })).then(function (texts) {        console.log(__filename + ":" + texts.self.length);        console.log("/ext/passwd:" + texts.passwd.length);    });In this case, we've simultaneously read the text of our ownprogram, and the Unix user database, and then printed outtheir corresponding file sizes.Finally, to read all of the files in the examples directoryand note the lengths of each one, we can use a three stepthenable:    var Q = require("q/util");    var FS = require("q-fs");    Q.when(FS.list(__dirname))    .then(function (fileNames) {        return Q.deep(fileNames.map(function (fileName) {            return {                "name": fileName,                "text": FS.read(FS.join(__dirname, fileName))            };        }));    }).then(function (files) {        files.forEach(function (file) {            console.log(file.name, file.text.length);        });    });Again, all of these examples are in the `examples` directorywith the names `then{1,2,3}.js`.Quacks Like a Duck:Any object with a "then(callback, errback)" method will betreated as a promise, and all promises provided by the Q APIhave "then" methods so they can be used by any API thataccepts thenables.The Q Ecosystem---------------    q-fshttps://github.com/kriskowal/q-fs              basic file system promises    q-httphttps://github.com/kriskowal/q-http              http client and server promises    q-utilhttps://github.com/kriskowal/q-util              promise control flow and data structures    q-commhttps://github.com/kriskowal/q-comm              remote object communication    teleporthttps://github.com/gozala/teleport              browser-side module promises    ...    All available through NPM.THE HALLOWED API----------------when(value, callback_opt, errback_opt)    Arranges for a callback to be called:     - with the value as its sole argument     - in a future turn of the event loop     - if and when the value is or becomes a fully resolved    Arranges for errback to be called:     - with a value respresenting the reason why the object will       never be resolved, typically a string.     - in a future turn of the event loop     - if the value is a promise and       - if and when the promise is rejected    Returns a promise:     - that will resolve to the value returned by either the callback       or errback, if either of those functions are called, or     - that will be rejected if the value is rejected and no errback       is provided, thus forwarding rejections by default.    The value may be truly _any_ value.    The callback and errback may be falsy, in which case they will not    be called.        Guarantees:     - The callback will not be called before when returns.     - The errback will not be called before when returns.     - The callback will not be called more than once.     - The errback will not be called more than once.     - If the callback is called, the errback will never be called.     - If the errback is called, the callback will never be called.     - If a promise is never resolved, neither the callback or the       errback will ever be called.    THIS IS COOL     - You can set up an entire chain of causes and effects in the       duration of a single event and be guaranteed that any       invariants in your lexical scope will not...vary.     - You can both receive a promise from a sketchy API and return a       promise to some other sketchy API and, as long as you trust       this module, all of these guarantees are still provided.     - You can use when to compose promises in a variety of ways:    INTERSECTION    function and(a, b) {        return when(a, function (a) {            return when(b, function (b) {                // ...            });        })    }defer()    Returns a "Deferred" object with a:     - promise property     - resolve(value) function     - reject(reason) function    The promise is suitable for passing as a value to    the "when" function.    Calling resolve with a promise notifies all observers    that they must now wait for that promise to resolve.    Calling resolve with a rejected promise notifies all    observers that the promise will never be fully resolved    with the rejection reason.  This forwards through the    the chain of "when" calls and their returned "promises"    until it reaches a "when" call that has an "errback".    Calling resolve with a fully resolved value notifies    all observers that they may proceed with that value    in a future turn.  This forwards through the "callback"    chain of any pending "when" calls.    Calling reject with a reason is equivalent to    resolving with a rejection.    In all cases where the resolution of a promise is set,    (promise, rejection, value) the resolution is permanent    and cannot be reset.  All future observers of the    resolution of the promise will be notified of the    resolved value, so it is safe to call "when" on     a promise regardless of whether it has been or will    be resolved.    THIS IS COOL    The Deferred separates the promise part from the resolver    part. So:     - You can give the promise to any number of consumers       and all of them will observe the resolution independently.       Because the capability of observing a promise is separated       from the capability of resolving the promise, none of the       recipients of the promise have the ability to "trick"       other recipients with misinformation.     - You can give the resolver to any number of producers       and whoever resolves the promise first wins.  Furthermore,       none of the producers can observe that they lost unless       you give them the promise part too.        UNION    function or(a, b) {        var union = defer();        when(a, union.resolve);        when(b, union.resolve);        return union.promise;    }    ref(value)    If value is a promise, returns the promise.    If value is not a promise, returns a promise that has    already been resolved with the given value.def(value)    Annotates a value, wrapping it in a promise, such that    that it is a local promise object which cannot be    serialized and sent to resolve a remote promise.    A def'ed value will respond to the `isDef` message    without a rejection so remote promise communication    libraries can distinguish it from non-def values.reject(reason)    Returns a promise that has already been rejected    with the given reason.        This is useful for conditionally forwarding a rejection    through an errback.        when(API.getPromise(), function (value) {            return doSomething(value);        }, function (reason) {            if (API.stillPossible())                return API.tryAgain();            else                return reject(reason);        })        Unconditionally forwarding a rejection is equivalent to    omitting an errback on a when call.isPromise(value)    Returns whether the given value is a promise.isResolved(value)    Returns whether the given value is fully resolved.    The given value may be any value, including    but not limited to promises returned by defer() and    ref(). Rejected promises are not considered    resolved.isRejected(value)    Returns whether the given value is a rejected    promise.promise.valueOf()    Promises override their valueOf method such that if the    promise is fully resolved, it will return the fully    resolved value.error(reason)    Accepts a reason and throws an error.  This is a    convenience for when calls where you want to trap the    error clause and throw it instead of attempting a    recovery or forwarding.enqueue(callback Function)    Calls "callback" in a future turn.ADVANCED API------------The "ref" promise constructor establishes the basic API forperforming operations on objects: "get", "put", "post", and"del".  This set of "operators" can be extended by creatingpromises that respond to messages with other operator names,and by sending corresponding messages to those promises.makePromise(descriptor, fallback_opt, valueOf_opt)    Creates a stand-alone promise that responds to messages.    These messages have an operator like "when", "get",    "put", and "post", corresponding to each of the above    methods for sending messages to promises.    The descriptor is an object with function properties    (methods) corresponding to operators.  When the made    promise receives a message and a corresponding operator    exists in the descriptor, the method gets called with    the variadic arguments sent to the promise.  If no    descriptor exists, the fallback method is called with    the operator, and the subsequent variadic arguments    instead.  These functions return a promise for the    eventual resolution of the promise returned by the    message-sender.  The default fallback returns a    rejection.    The `valueOf` function, if provided, overrides the    `valueOf` method of the returned promise.  This is    useful for providing information about the promise in    the same turn of the event loop.  For example, resolved    promises return their resolution value and rejections    return an object that is recognized by `isRejected`.send(value, operator, ...args)    Sends an arbitrary message to a promise.    Care should be taken not to introduce control-flow    hazards and secuirity holes when forwarding messages to    promises.  The methods above, particularly "when", are    carefully crafted to prevent a poorly crafted or    malicious promise from breaking the invariants like not    applying callbacks multiple times or in the same turn of    the event loop.THE UTIL MODULE---------------The Q utility module exports all of the Q module's API butadditionally provides the following functions.    var Q = require("q/util");step(...functions)    Calls each step function serially, proceeding only when    the promise returned by the previous step is deeply    resolved (see: `deep`), and passes the resolution of the    previous step into the argument or arguments of the    subsequent step.        If a step accepts more than one argument, the resolution    of the previous step is treated as an array and expanded    into the step's respective arguments.    `step` returns a promise for the value eventually    returned by the last step.delay(timeout, eventually_opt)    Returns a promise for the eventual value after `timeout`    miliseconds have elapsed.  `eventually` may be omitted,    in which case the promise will be resolved to    `undefined`.  If `eventually` is a function, progress    will be made by calling that function and resolving to    the returned value.  Otherwise, `eventually` is treated    as a literal value and resolves the returned promise    directly.shallow(object)    Takes any value and returns a promise for the    corresponding value after all of its properties have    been resolved.  For arrays, this means that the    resolution is a new array with the corresponding values    for each respective promise of the original array, and    for objects, a new object with the corresponding values    for each property.deep(object)    Takes any value and returns a promise for the    corresponding value after all of its properties have    been deeply resolved.  Any array or object in the    transitive properties of the given value will be    replaced with a new array or object where all of the    owned properties have been replaced with their    resolution.reduceLeft(values, callback, basis, this)reduceRight(values, callback, basis, this)reduce(values, callback, basis, this)    The reduce methods all have the signature of `reduce` on    an ECMAScript 5 `Array`, but handle the cases where a    value is a promise and when the return value of the    accumulator is a promise.  In these cases, each reducer    guarantees that progress will be made in a particular    order.        `reduceLeft` guarantees that the callback will be called    on each value and accumulation from left to right after    all previous values and accumulations are fully    resolved.    `reduceRight` works similarly from right to left.    `reduce` is opportunistic and will attempt to accumulate    the resolution of any previous resolutions.  This is    useful when the accumulation function is associative.THE QUEUE MODULE----------------The `q/queue` module provides a `Queue` object whereinfinite promises for values can be dequeued before they areenqueued.put(value)    Places a value on the queue, resolving the next gotten    promise in order.get()    Returns a promise for the next value from the queue.  If    more values have been enqueued than dequeued, this value    will already be resolved.close(reason_opt)    Causes all promises dequeued after all already enqueued    values have been depleted will be rejected for the given    reason.closed    A promise that, when resolved, indicates that all    enqueued values from before the call to `close` have    been dequeued.Copyright 2009, 2010 Kristopher Michael KowalMIT License (enclosed)