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

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.

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.

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.

Copyright 2009, 2010 Kristopher Michael Kowal MIT License (enclosed)

Changelog

0.1.2

• restructured for overlay style package compatibility