JoshuaWise/jellypromise

A tiny and fast Promises/A+ library, with thoughtful error handling.

jellypromise

This is an implementation of Promises that achieves the following design goals:

• Tiny size (4.22 kB minified and gzipped)
• Fast performance (often faster than bluebird)
• Very low memory overhead
• A superset of the ES6 Promise
• Has a useful, carefully-selected set of utilities, without bloat
• Logs unhandled errors by default (the opposite of what then/promise does), provides long stack traces, and provides utilities for useful error handling patterns
• Has an object streaming library (observables) for efficient asynchronous processing chains with concurrency control

Installation

npm install --save jellypromise

Usage

var Promise = require('jellypromise');

var promise = new Promise(function (resolve, reject) {
  get('http://www.google.com', function (err, res) {
    if (err) reject(err);
    else resolve(res);
  });
});

Unhandled Rejections

When a promise is rejected but has no rejection handlers, the rejection will be logged to the console unless a rejection handler is added before the next event loop cycle. This helps the programmer quickly identify and fix errors.

However, in some situations, you may wish to refrain from adding a rejection handler until a later time. In these cases, you can use the .catchLater() utility method to suppress this behavior.

Production Mode

By default, long stack traces and warnings are turned on for superior debugging capabilities. However, if you use production mode, they will be turned off for performance reasons.

To use production mode, just load the module this way:

var Promise = require('jellypromise/production');

Browser Support

• Chrome 5+
• Firefox 4+
• Safari 5+
• Opera 11.6+
• Internet Explorer 9+

API

new Promise(handler)

This creates and returns a new promise. handler must be a function with the following signature:

function handler(resolve, reject)

1. resolve is a function that should be called with a single argument. If it is called with a non-promise value then the promise is fulfilled with that value. If it is called with a promise, then the constructed promise takes on the state of that promise.
2. reject is a function that should be called with a single argument. The returned promise will be rejected with that argument.

.then([onFulfilled], [onRejected]) -> promise

This method conforms to the Promises/A+ spec.

If you are new to promises, the following resources are available:

• Matt Greer's promise tutorial
• HTML5 Rocks's promise tutorial
• Promises.org's introduction to promises
• David Walsh's article on promises

If they are provided, onFulfilled and onRejected should be functions.

.catch([predicate], onRejected) -> promise

Sugar for .then(null, onRejected), to mirror catch in synchronous code.

If a predicate is specified, the onRejected handler will only catch exceptions that match the predicate.

The predicate can be:

• an Error class
  • example: .catch(TypeError, func)
• a filter function
  • example: .catch(function (err) {return err.statusCode === 404}, func)
• an array of accepted predicates
  • example: .catch([TypeError, SyntaxError, is404], func)

.catchLater() -> this

Prevents an error from being logged if the promise gets rejected without yet having a rejection handler (see Unhandled Rejections).

.finally(handler) -> promise

Pass a handler that will be called regardless of this promise's fate. The handler will be invoked with no arguments, and it cannot change the promise chain's current fulfillment value or rejection reason. If handler returns a promise, the promise returned by .finally will not be settled until that promise is settled.

This method is primarily used for cleanup operations.

.tap(handler) -> promise

Like .finally, but the handler will not be called if this promise is rejected. The handler cannot change the promise chain's fulfillment value, but it can delay chained promises by returning an unsettled promise (just like .finally). The handler is invoked with a single argument: the fulfillment value of the previous promise.

This method is primarily used for side-effects.

.rollback(handler) -> promise

The opposite of .tap. The given handler will only be invoked if this promise is rejected. Unlike .catch, however, the returned promise will still be rejected with the original rejection reason. Just like .tap and .finally, the handler can delay chained promises by returning an unsettled promise. The handler is invoked with a single argument: the rejection reason of the previous promise.

This method is primarily used for rollback operations.

.become(fulfilledValue, [rejectedValue]) -> promise

Sugar for .then(function () {return fulfilledValue}).

If a second argument is passed, it is equivilent to:

.then(function () {return fulfilledValue}, function () {return rejectedValue}).

.else([predicate], value) -> promise

Sugar for .catch(function () {return value}). This method is used for providing default values on a rejected promise chain. Predicates are supported, just like with the .catch method.

.delay(milliseconds) -> promise

Returns a new promise chained from this one, whose fulfillment is delayed by the specified number of milliseconds from when it would've been fulfilled otherwise. Rejections are not delayed.

.timeout(milliseconds, [reason]) -> promise

Returns a new promise chained from this one. However, if this promise does not settle within the specified number of milliseconds, the returned promise will be rejected with a TimeoutError.

If you specify a string reason, the TimeoutError will have reason as its message. Otherwise, a default message will be used. If reason is an instanceof Error, it will be used instead of a TimeoutError.

TimeoutError is available at Promise.TimeoutError.

.log([prefix]) -> promise

Conveniently logs the state and value of the promise when it becomes fulfilled or rejected.

If prefix is provided, it will be prepended to the logged value, separated by a space character.

.inspect() -> object

Returns an object that describes the current state of the promise. The returned object is not live, and will not update over time—it's just a snapshot.

If the promise is:

• pending, the descriptor will be { state: 'pending' }
• fulfilled, the descriptor will be { state: 'fulfilled', value: <fulfillmentValue> }
• rejected, the descriptor will be { state: 'rejected', reason: <rejectionReason> }

In Node.js, you'll always see this descriptor object when passing a jellypromise to console.log().

.stream() -> promiseStream

Returns a new PromiseStream that will contain the data in this promise's fulfillment value. If the promise is not fulfilled with an iterable object, the returned stream is rejected with a TypeError.

To learn about PromiseStreams, see this Streaming API section.

static Promise.resolve(value) -> promise

Creates a promise that is resolved with the given value. If you pass a promise or promise-like object, the returned promise takes on the state of that promise-like object (fulfilled or rejected).

static Promise.reject(value) -> promise

Creates a promise that is rejected with the given value (usually an Error object) as its rejection reason.

static Promise.race(iterable) -> promise

Returns a promise that will fulfill or reject with the same value/exception as the first fulfilled/rejected promise in the iterable argument.

Non-promise values in the iterable are treated like already-fulfilled promises.

static Promise.all(iterable) -> promise

Returns a promise for an iterable of promises. The returned promise will be rejected if any of promises in iterable are rejected. Otherwise, it will be fulfilled with an array of each fulfillment value, respectively.

Non-promise values in the iterable are treated like already-fulfilled promises.

Promise.all([Promise.resolve('a'), 'b', Promise.resolve('c')])
  .then(function (results) {
    assert(results[0] === 'a')
    assert(results[1] === 'b')
    assert(results[2] === 'c')
  })

static Promise.any(iterable) -> promise

Returns a promise for an iterable of promises. It will be fulfilled with the value of the first fulfilled promise in iterable. If all of the given promises reject, it will be rejected with the rejection reason of the promise that rejected first.

Non-promise values in the iterable are treated like already-fulfilled promises.

static Promise.props(object) -> promise

Like Promise.all, but for an object's properties instead of iterated values. Returns a promise that will be resolved with an object that has fulfillment values at respective keys to the original object. Only the object's own enumerable properties are considered (those retrieved by Object.keys).

Non-promise values in the iterable are treated like already-fulfilled promises.

Promise.props({users: getUsers(), news: getNews()})
  .then(function (results) {
    console.log(results.users)
    console.log(results.news)
  })

static Promise.settle(iterable) -> promise

Given an iterable of promises, returns a promise that fulfills with an array of promise descriptor objects.

If the corresponding input promise is:

• fulfilled, the descriptor will be { state: 'fulfilled', value: <fulfillmentValue> }
• rejected, the descriptor will be { state: 'rejected', reason: <rejectionReason> }

Non-promise values in the iterable are treated like already-fulfilled promises.

static Promise.build(keys, handler) -> promise

Returns a promise that fulfills with an object containing the given keys. handler must be a function with the following signature:

function handler(set, reject)

1. set is a function that should be called with two arguments (key, value) to assign properties to the eventually fulfilled object. You can also pass a single object argument whose key-value pairs will be used instead. Properties will only be assigned if they are specified in keys. set returns true or false, indicating whether a property was successfully assigned.
2. reject is a function that should be called with a single argument. The returned promise will be rejected with that argument.

When set has been used to assign a value for each property specified in keys, the returned promise will be fulfilled with the resulting object.

After the promise is resolved, any further attempts to set a property will fail and return false.

var words = ['anthophilous', 'conviviality', 'cynosure']
Promise.build(words, function (set, reject) {
  var reader = new EnglishDictionaryReader(database)
  reader.on('definition' function (word, definition) {
    set(word, definition)
  })
})

static Promise.after(milliseconds, [value]) -> promise

Returns a promise that will be resolved with value after the specified number of milliseconds. By default, value is undefined.

If value is a promise itself, the returned promise will adopt the state of value after the specified number of milliseconds.

static Promise.isPromise(value) -> boolean

Returns either true or false, whether value is a promise-like object (i.e., it has a .then method).

static Promise.promisify(function, [options]) -> function

NOTE: This function is not available in the browser!

Takes a function which accepts a node style callback and returns a new function that returns a promise instead.

var fs = require('fs')
var read = Promise.promisify(fs.readFile)

var promise = read('foo.json', 'utf8')
  .then(function (str) {
    var json = JSON.parse(str)
  })

There are two possible options:

• multiArgs
  • Setting this option to true means the resulting promise will always fulfill with an array of the callback's success values (arguments after the first).
• deoptimize
  • Setting this option to true can potentially improve the performance of functions that are frequently passed a widely varying number of arguments (and typically a very high number of arguments). In most cases though, this option will reduce the performance of the function.

static Promise.nodeify(function) -> function

NOTE: This function is not available in the browser!

Takes a promise-returning function, and returns a new function that instead accepts a node style callback as its last argument. The newly created function will always return undefined.

var callbackAPI = Promise.nodeify(promiseAPI)

callbackAPI('foo', 'bar', function (err, result) {
  // handle error or result here
})

Streaming API

Some promise libraries have functions like .map() or .filter() which operate on arrays of promises. Unfortunately, this is a very inefficient way to do batch processing on promises. Large and unnecessary arrays are kept in memory, and usually thousands of closures are created when processing large datasets this way. Additionally, each promise must wait for every other promise to finish one operation before the next operation can be started, which can cause serious bottlenecks.

To solve these problems, we provide the class Promise.Stream. For detailed documentation, see the Streaming API.

Promises of iterables can be transformed into a stream by using the Promise#stream method:

Promise.resolve(['a', 'b', 'c'])
    .stream()
    .map(function (value, index) {return value + value;})
    .reduce(function (previous, current) {return previous + current})
    .log()

// => "aabbcc"

License

MIT