Provides heavy-weight extensions to the Q API for using
asynchronous promises, both in the browser and in CommonJS
module systems like NodeJS.
The Q utility module exports all of the Q module's API but
additionally provides the following functions.
var Q = require("qq");
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 `qq` module provides a `Queue` object where
infinite promises for values can be dequeued before they are
enqueued.
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-2011 Kristopher Michael Kowal
MIT License (enclosed)