Concurrent

Promises/A+ with Scala Awesomeness

Examples

1var Future = require('concurrent').Future;
2var request = require('request');
3
4var req = function(options) {
5  var future = new Future();
6  request(options, future.convert(['res', 'body']));
7  return future;
8};
9
10/**
11 * Example #1: Simple Async Call
12 */
13// Fetch Google with a SLA
14var google = req('http://google.com').ready(1000);
15
16// Fetch the status
17var status = google.map(function(value) {
18  return value.res.statusCode;
19});
20
21// Log the final result
22status.onSuccess(function(statusCode) {
23  console.log(statusCode);
24});
25
26/**
27 * Examples #2: Parallel Calls
28 */
29var duckDuckGo = req('http://duckduckgo.com');
30var bingOrYahoo = req('http://bing.com').fallbackTo(req('http://yahoo.com'));
31
32var asArray = Future.sequence([google, duckDuckGo, bingOrYahoo]);
33
34asArray.onSuccess(function(values) {
35  console.log(values);
36});
37
38var asObject = Future.sequence({
39  google: google,
40  duckDuckGo: duckDuckGo,
41  bingOrYahoo: bingOrYahoo
42});
43
44var recoverable = asObject.recover({
45  promises: 'A+'
46});

Benchmarks

Here are the top 5 libraries for some of the tests

1==========================================================
2Test: promise-fulfill x 10000
3----------------------------------------------------------
4laissez:    |   3.00
5concurrent: ▇▇  14.00
6deferred:   ▇▇  19.00
7when:       ▇▇▇▇▇  36.00
8q:          ▇▇▇▇▇▇▇▇  57.00
9
10==========================================================
11Test: promise-reject x 10000
12----------------------------------------------------------
13concurrent: |   6.00
14avow:       ▇▇▇▇▇▇▇▇  55.00
15q:          ▇▇▇▇▇▇▇▇▇  60.00
16when:       ▇▇▇▇▇▇▇▇▇▇▇▇▇  89.00
17laissez:    ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 118.00
18
19==========================================================
20Test: promise-sequence x 10000
21----------------------------------------------------------
22laissez:    |   8.00
23when:       ▇▇▇▇▇▇▇▇ 204.00
24concurrent: ▇▇▇▇▇▇▇▇ 207.00
25avow:       ▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 335.00
26deferred:   ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 421.00
27
28==========================================================
29Test: defer-fulfill x 10000
30----------------------------------------------------------
31laissez:    ▇  21.00
32concurrent: ▇▇▇▇  62.00
33when:       ▇▇▇▇▇▇▇ 103.00
34avow:       ▇▇▇▇▇▇▇▇▇ 142.00
35deferred:   ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 424.00
36
37==========================================================
38Test: defer-reject x 10000
39----------------------------------------------------------
40avow:       ▇▇▇  50.00
41concurrent: ▇▇▇▇▇  80.00
42when:       ▇▇▇▇▇▇▇▇▇▇ 160.00
43laissez:    ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 240.00
44q:          ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 378.00
45
46==========================================================
47Test: defer-sequence x 10000
48----------------------------------------------------------
49laissez:    |   7.00
50concurrent: ▇▇▇▇▇▇▇▇▇▇▇ 176.00
51when:       ▇▇▇▇▇▇▇▇▇▇▇▇▇ 209.00
52deferred:   ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 271.00
53avow:       ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 352.00
54
55==========================================================
56Test: map x 10000
57----------------------------------------------------------
58deferred:   ▇▇▇▇▇  39.00
59concurrent: ▇▇▇▇▇▇▇▇▇▇▇▇▇ 103.00
60when:       ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 385.00
61
62==========================================================
63Test: reduce-large x 10000
64NOTE: in node v0.8.14, deferred.reduce causes a
65stack overflow for an array length >= 610
66----------------------------------------------------------
67concurrent: ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 371.00
68when:       ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 502.00

You can find more performance results here

Overview

Simple Promise

Concurrent supports the bare bones Promise implementation that supports then(onFulfilled, onRejected), fulfill(value), reject(reason).

1var Promise = require('concurrent').Promise;
2
3var success = new Promise();
4success.then(function(value) {
5  console.log(value); // 'success'
6});
7success.fulfill('success');
8
9var failure = new Promise();
10failure.then(null, function(reason) {
11  console.log(reason); // 'failure'
12});
13failure.reject('failure');

Documentation

Futures

Concurrent also provides a Future class which inherits from Promise. It has a lot of syntactic sugar on top of the Promises/A+ spec based on the Scala Future API.

1var Future = require('concurrent').Future;
2
3var success = new Future();
4success.onComplete(function(result) {
5  console.log(result; // 'success'
6});
7success.fulfill('success');
8
9var failure = new Future();
10failure.onComplete(function(result) {
11  console.log(result); // 'failure'
12});
13failure.reject('failure');

Documentation

Collections

Concurrent also provides a collections library which gives a lot of the standard iterators. All the iterators are performed asynchronously and return Futures. The following methods are supported:

• forEach
• every
• some
• filter
• map
• reverse
• reduce
• reduceRight

Documentation

Working with existing callbacks

Futures also have support for working with existing callback style libraries by using the convert method which returns a callback handler.

1var Future = require('concurrent').Future;
2var request = require('request');
3
4var google = new Future();
5google.map(function(value) {
6  var body = value[1]; // Request returns a response and a body
7  console.log(body); // HTML for http://www.google.com
8});
9request('http://www.google.com', google.convert());

Working with other Promise implementations

Since concurrent implements the Promises/A+ spec, it should work with other libraries that implement the spec. Also, the Future class internally does not expect any method beyond then, fulfill, and reject so the prototype methods can be merged into other implementations as long as they have those three methods.

Browsers

Concurrent can be used in browser environments that support ES5, specifically forEach, Array.isArray and Object.create. Look at this JsFiddle as an example of using the libary in the browser.

Credits

A lot of people had a hand in inspiring this project and helping getting it done. I'd like to thank:

• @brikis98 for helping me come up with the idea
• Promises, understanding by doing for the initial promise spec
• cujos/when for fully featured examples
• aheckmann/mpromise for node.js specific implementation
• promises-aplus/promises-tests for the test suite
• Scala Futures For API sugar

License

This is licensed under the MIT license. See the LICENSE file