dfilatov / vow

ES6-compatible and Promises/A+ implementation for Node.js and browsers

Vow

Vow is a Promises/A+ implementation. It also supports ES6 Promises specification.

Full API reference can be found at http://dfilatov.github.io/vow/.

Getting Started

In Node.js

You can install using Node Package Manager (npm):

npm install vow

In Browsers

<script type="text/javascript" src="vow.min.js"></script>

It also supports RequireJS module format and YM module format.

Vow has been tested in IE6+, Mozilla Firefox 3+, Chrome 5+, Safari 5+, Opera 10+.

Usage

Creating a promise

There are two possible ways to create a promise.

1. Using a deferred

function doSomethingAsync() {
    var deferred = vow.defer();
    
    // now you can resolve, reject, notify corresponging promise within `deferred`
    // e.g. `defer.resolve('ok');`
        
    return deferred.promise(); // and return corresponding promise to subscribe to reactions
}

doSomethingAsync().then(
    function() {}, // onFulfilled reaction
    function() {}, // onRejected reaction
    function() {}  // onNotified reaction
    );

The difference between deferred and promise is that deferred contains methods to resolve, reject and notify corresponding promise, but the promise by itself allows only to subscribe on these actions.

2. ES6-compatible way

function doSomethingAsync() {
    return new vow.Promise(function(resolve, reject, notify) {
        // now you can resolve, reject, notify the promise
    });
}

doSomethingAsync().then(
    function() {}, // onFulfilled reaction
    function() {}, // onRejected reaction
    function() {}  // onNotified reaction
    );

Extensions and related projects

• vow-fs — vow-based file I/O for Node.js
• vow-node — extension for vow to work with nodejs-style callbacks
• vow-queue — vow-based task queue with weights and priorities
• vow-asker — wraps asker API in the vow promises implementation

NOTE. Documentation for old versions of the library can be found at https://github.com/dfilatov/vow/blob/0.3.x/README.md.

vow's Issues

Add support for Object in vow.any and vow.anyResolved function

Нужен аналог метода onresolve

Бывает удобным иметь один калбек и для reject и для fullfill

Add vow.cast method

Add static method Promise.when

Feature request: Mux

I often encounter situations where I have to call an async function multiple times:

friends.forEach(function(friend) {
    friend.save(callback);
});

It want to block on a call to all these. Sure, I could use async framework. Sometimes that is clunky, so I wrote Mux:

var myMux = new Vow.Mux();
friends.forEach(function(friend) {
    friend.save(myMux.createCallback());
});
myMux.then(function() {
    done();
});

Here is the library code and unit test.

// extend vow with helpers
var Vow = require('vow');

var Mux = module.exports = function Mux() {
    /**
     * An array of callbacks this Mux wraps
     * @type {Array}
     * @private
     */
    this._callbacks = [];

    /**
     * The results from all successful callbacks
     * @type {Array}
     * @private
     */
    this._results = [];

    /**
     * The error from all error callbacks
     * @type {Array}
     * @private
     */
    this._errors = [];

    /**
     * Count the number of times the callback wrapper is invoked
     * @type {number}
     * @private
     */
    this._countCallsBack = 0;

    /**
     * @type {Promise}
     * @private
     */
    this._innerPromise = Vow.promise();

    // copy Vow prototype over Mux
    for (var x in this._innerPromise) this[x] = this._innerPromise[x];
};

/**
 * Handles callbacks made to function created in createCallback
 * @param {number} position
 * @param {Error|null} err
 * @param {*} result
 * @private
 */
Mux.prototype._onCallback = function(position, err, result) {
    ++this._countCallsBack;

    // save error
    if (typeof err === 'undefined') {
        this._errors[position] = null;
    } else {
        this._errors[position] = err;
    }

    // save result
    if (typeof result === 'undefined') {
        this._results[position] = null;
    } else {
        this._results[position] = result;
    }

    if (this.isResolved()) {
        // already resolved
        return;
    } else if (err) {
        // reject on first error
        this.reject(err);
    } else if (this._countCallsBack === this._callbacks.length) {
        // fulfill with all available results
        this.fulfill(this._results);
    }
};

/**
 * Create one or more callbacks backed by a single promise
 * @returns {Function}
 */
Mux.prototype.createCallback = function() {
    var callback = this._onCallback.bind(this, this._callbacks.length);
    this._callbacks.push(callback);
    return callback;
}

Unit tests:

var assert = require('assert');
var Vow = require('../lib/vow');

describe('Vow.Mux', function() {
    it('resolve naive', function(done) {
        var m = new Vow.Mux();
        m.then(function() {
            done();
        }, function() {
            assert.fail('should not be rejected');
        });
        m.fulfill();
    });

    it('all callbacks', function(done) {
        var m = new Vow.Mux();
        m.then(function() {
            assert.equal(m._countCallsBack, 100);
            done();
        }, function() {
            assert.fail('should not be rejected');
        });

        var callbacks = [];
        for (var i = 0; i < 100; ++i) {
            setTimeout(m.createCallback(), i);
        }
    });

    it('reject on first', function(done) {
        var m = new Vow.Mux();
        m.then(function() {
            assert.fail('should not be fulfilled');
        }, function(err) {
            assert.equal(err.message, 'there is no spoon');
            done();
        });

        var callbacks = [];
        for (var i = 0; i < 100; ++i) {
            if (i === 69) {
                // 69 is an error
                setTimeout(m.createCallback().bind(m, new Error('there is no spoon')), i);
            } else if (i > 69) {
                // other error
                setTimeout(m.createCallback().bind(m, new Error('foobar')), i);
            } else {
                setTimeout(m.createCallback(), i);
            }
        }
    });
});

Implement Promise.any method

Vow.all failed when arguments contain null-like value

What about deffered?

What about deffered? Or this is out of scope of this library?

Add bower.json

Promise.all, Promise.allResolved: resulting promise should be fulfilled if argument is empty array

How to run tests in the browser?

You claim for browser support. But how to run tests inside the browser? Consider Mocha + Chai for tests. They support browser and NodeJS.

Add static Vow.spread method

Implement native Promise specification

promise.always ignore context of callback

Don't use "global" as a self-invoking function param

1. It obscures the NodeJS host object inside Vow lib and prevents of using it
2. It confuses cause it becomes as a empty object in Node

Ability to specify context for callbacks

Add promise.done(), Vow.done(value) methods

Make sure to pass the newly-updated Promises/A+ test suite

Currently none of the major libraries pass the fully-finished 1.0 version of the Promises/A+ test suite that I published to npm an hour ago. You could be the first!!!

Bonus: once you do so, go get a sweet badge from promises-aplus/promises-spec#57 :D.

Нотификация

Я тут попробовал использовать нотификацию (defer.notify + promise.progress) и получил миллион вызовов обработчика progress, среди них есть те что должны были произойти, однако 99% вызывается просто без параметров.

Я полез в твой код и вижу это
https://github.com/dfilatov/vow/blob/master/lib/vow.js#L564

Если я меняю defer.notify(res); на void(0); все начинает работать корректно.
Кажется это баг.

Add context param in Vow.invoke

Wanna have progress handler in Vow.

then(onSuccess, onError, onProgresss);

promise.always not pass onResolved returned value

Implement new PromiseA+ 2.x specification

setImmediate для Node.js

Node.js 0.9.x есть поддержка setImmediate, вроде он «правильнее» чем process.nextTick.

nodejs/node-v0.x-archive#3845

nextTick отрабатывает синхронно в IE8 в стандартном режиме.

Происходит это из-за того, что в IE8 postMessage отрабатывает в том же потоке, в котором был вызван. Не уверен, что так происходит всегда, но у меня воспроизводится стабильно на одном из кейсов.

Pass progress state from items in all array/objects methods

Хочется чтобы методы типа all и allResolved подписывались не только на reject и resolve, но и на нотификацию каждого промиса в коллекции.
Чтобы сейчас получить эти нотификации приходится их самому перебирать и подписываться, а также создавать новый defer, и возвращать его промис вместо результата all и allResolved. Это очень неудобно.

Add promise.delay, Vow.delay

Probably it would be cool to have a wrapper function for natives

Just an idea.

Simple API:

var vowNode = require('vow/node/wrap');
var promise = vowNode.call(fn, arg1, arg2, ...);

For example:

vowNode(require('zlib').deflate, buf)
  .then(...);

resolved delay()'ed promise doesn't clear inner setTimeout

test.js:

var promise = require('vow').promise('10s').delay(10 * 1000);

promise
    .then(function(msg) { console.log(msg) })
    .fail(function(msg) { console.log(msg) })
    .done();

promise.reject('fail');

node test.js

notify() is not chainable?

Add callbacks to done()

.always() swallows exceptions

if some exception lead to always call then execution continues like there was no exception

Make it browser-compatible

Use native Promise if possible

According to release notes, Chrome 35 Beta supports DOM promises by default (they are already available in Canary as well).

Haven't you thought about adding support of native Promise object to vow, if it's available in browser?

Call invoke methods handler with null context

In addition to #41
It might be better to provide similar behavior with context of the invoke handler.
Because now it points at an empty object in node but at the window object in browser

Add support for modules

See https://github.com/ymaps/modules

module.exports fires before modules.define

Было бы правильнее, в коде библиотеки, сначала проверять доступность modules и define и только после делать module.exports.

Сейчас если использовать vow из Node.js всегда будет срабатывать exports, даже если я хочу использовать модули.

It doesn't work in IE8

IE8 нas window.postMessage, but has no window.addEventListener

Add Vow.invoke

Please build not-minimized version also

Not-minimized version is appropriate for cases some kind of concatenation and uglyfying is used (requirejs, webpack,..)

construct to only call fail on vow.all when: all are resolved and any are rejected?

It there a way, with vow.all or otherwise, to call fail only when all promises are resolved and any are rejected?
usecase: aggregating errors.

See the following construct how I'd like it to be:

vow.all([promise1,promise2])
.then(function(){
//only fired when all resolved and all fulfilled
}).fail(function(err){
//only fired when all resolved and any failed
//currently with vow.all: any resolved and any failed
});

Is there a way to do this?

Buggy behavior if fail called before then on promise

var promise = require('vow').promise();

function done (from, obj) {
    console.log(from, obj);
}

promise
    .fail(function (a) {
        done('FAIL', a);
    })
    .then(function (a) {
        done('THEN', a);
    });

promise.reject('zxc');q

Actual output:

FAIL zxc
THEN undefined

Expected:

FAIL zxc

Add vow.anyResolved method

Use setImmediate instead of process.nextTick with latest node versions

Hi!
I had an issue with some recursive calls of third party lib.
The log message looks like this:

(node) warning: Recursive process.nextTick detected. This will break in the next version of node. Please use setImmediate for recursive deferral.
RangeError: Maximum call stack size exceeded

When i have changed nextTick with setImmediate in your Vow code,
it starts fail silently =)

Vow doesn't properly work in mocha/phantomjs environment

Vow's nextTick function relies on "process" global variable as a sign of nodeJs.

But in phantomjs/mocha environment has global var "process" that doesn't have nextTick.

It would be better to update it with a more reliable check of environment / or at least check for existence of nextTick property.

Propagation of progress state is broken

Exceptions don't contain full stack trace

When exception happens it looks like this:
/Users/scf/Projects/bem-tools/node_modules/vow/lib/vow.js:413
throw e;
^
Error: ENOENT, open '/Users/scf/Projects/bem-tools/test-make-temp/pages/example/example.bemdecl1.js'

There is no trace of the user code cause it to raise.

Add static isFulfilled, isRejected, isResolved methods

Throw exception from last callback

Example:

doRequest.then(function() {
   throw new Error('error');
});

doRequest.fulfill(); // should throw exception

sync method doesn't synchronize progress