q

What is q?

The 'q' npm package is a library for creating and managing promises in JavaScript. It provides a robust set of tools for working with asynchronous operations, allowing developers to write cleaner, more maintainable code by avoiding the 'callback hell' that can occur with deeply nested callbacks.

What are q's main functionalities?

Creating Promises

This feature allows the creation of a new promise using Q.defer(). The deferred object has a promise property and methods for resolving or rejecting the promise.

const Q = require('q');
const deferred = Q.defer();

function asyncOperation() {
  // Perform some asynchronous operation
  setTimeout(() => {
    // Resolve the promise after 1 second
    deferred.resolve('Operation completed');
  }, 1000);
  return deferred.promise;
}

asyncOperation().then(result => console.log(result));

Promise Chaining

This feature demonstrates how promises can be chained together, with the output of one promise being passed as input to the next.

const Q = require('q');

function firstAsyncOperation() {
  var deferred = Q.defer();
  setTimeout(() => deferred.resolve(1), 1000);
  return deferred.promise;
}

function secondAsyncOperation(result) {
  var deferred = Q.defer();
  setTimeout(() => deferred.resolve(result + 1), 1000);
  return deferred.promise;
}

firstAsyncOperation()
  .then(secondAsyncOperation)
  .then(result => console.log('Final result:', result));

Error Handling

This feature shows how to handle errors in promise-based workflows. The catch method is used to handle any errors that occur during the promise's execution.

const Q = require('q');

function mightFailOperation() {
  var deferred = Q.defer();
  setTimeout(() => {
    if (Math.random() > 0.5) {
      deferred.resolve('Success!');
    } else {
      deferred.reject(new Error('Failed!'));
    }
  }, 1000);
  return deferred.promise;
}

mightFailOperation()
  .then(result => console.log(result))
  .catch(error => console.error(error.message));

Other packages similar to q

bluebird

Bluebird is a fully-featured promise library with a focus on innovative features and performance. It is known for being one of the fastest promise libraries and includes utilities for concurrency, such as Promise.map and Promise.reduce, which are not present in 'q'.

when

When is another lightweight Promise library that offers similar functionality to 'q'. It provides a solid API for creating and managing promises but is generally considered to have a smaller footprint and to be more modular than 'q'.

promise

This package is a simple implementation of Promises/A+. It is smaller and may be more straightforward than 'q' for those who only need basic promise functionality without the additional utilities provided by 'q'.

README

Provides a defer/when style promise API for JavaScript

• usable as a CommonJS module, in Node,
• usable as a
• inspired by Tyler Close's Waterken ref_send promises, and
• compliant with http://wiki.commonjs.org/wiki/Promises/B

For Node:

$ curl http://npmjs.org/install.sh | sh
$ npm install q
$ node examples/test.js

APPLIED INTRODUCTION

Skipping past what an asynchronous promise is and how to use them directly for a moment, compare the usage of this library to Tim Caswell's excellent step library.

https://github.com/creationix/step

The q/util module, included here, provides a step function similar to Tim's. It takes any number of functions as arguments and runs them in serial order. Each function returns a promise to complete its step. When that promise is deeply resolved (meaning there are no more unfinished jobs in its object graph), the resolution is passed as the argument 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 in all capitals. Notice that any value can be treated as an already resolved promise, since the second and third steps return a string and undefined respectively.

You can also perform actions in parallel. This example reads two files at the same time and returns an array of promises for the results. Since the second step has more than one argument, the results array gets unpacked into the variadic 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 of indefinite length. This example reads all of the files in the same directory as the program and notes the length of each.

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 is packaged separately. You can try these programs, step{1,2,3}.js in the examples/ directory of this package.

When working with promises, exceptions are generally only thrown to indicate programmer errors. Promise-returning APIs generally rejecttheir promises to indicate that the promise will never be resolved/fulfilled. As such, the above programs will terminate when the first step rejects a the returned promise, which can happen if there is an error while reading or listing a file. The rejection can be observed because thestepfunction returns apromise` that will be eventually resolved by the return value of the last step.

var completed = Q.step(...);

We use the when method to observe either the resolution or the rejection of the promise.

Q.when(completed, function callback(completion) {
    // ok
}, function errback(reason) {
    // error
});

If a rejection is not explicitly observed, it gets implicitly 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
    );
}

The Q Ecosystem

q-fs      https://github.com/kriskowal/q-fs
          basic file system promises
q-http    https://github.com/kriskowal/q-http
          http client and server promises
q-util    https://github.com/kriskowal/q-util
          promise control flow and data structures
q-comm    https://github.com/kriskowal/q-comm
          remote object communication
teleport  https://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 value.

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.

defined(value)

Accepts a value or a promise for a value.

Returns a promise that will only resolve to a defined value.

If the given promise is resolved to "undefined", rejects
the returned promise.

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.

THE UTIL MODULE

The Q utility module exports all of the Q module's API but additionally 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 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, 2010 Kristopher Michael Kowal MIT License (enclosed)