2 | Vow
3 | [](https://www.npmjs.com/package/vow)
4 | [](https://travis-ci.org/dfilatov/vow/branches)
5 | [](https://www.npmjs.org/package/vow)
6 | =========
7 |
8 | Vow is a [Promises/A+](http://promisesaplus.com/) implementation.
9 | It also supports [ES6 Promises](https://people.mozilla.org/~jorendorff/es6-draft.html#sec-promise-objects) specification.
10 |
11 | Full API reference can be found at http://dfilatov.github.io/vow/.
12 |
13 | Getting Started
14 | ---------------
15 | ### In Node.js ###
16 | You can install using Node Package Manager (npm):
17 |
18 | npm install vow
19 |
20 | ### In Browsers ###
21 | ```html
22 |
23 | ```
24 | It also supports RequireJS module format and [YM module](https://github.com/ymaps/modules) format.
25 |
26 | Vow has been tested in IE6+, Mozilla Firefox 3+, Chrome 5+, Safari 5+, Opera 10+.
27 |
28 | Usage
29 | -----
30 | ### Creating a promise ###
31 | There are two possible ways to create a promise.
32 | #### 1. Using a deferred ####
33 | ```js
34 | function doSomethingAsync() {
35 | var deferred = vow.defer();
36 |
37 | // now you can resolve, reject, notify corresponging promise within `deferred`
38 | // e.g. `defer.resolve('ok');`
39 |
40 | return deferred.promise(); // and return corresponding promise to subscribe to reactions
41 | }
42 |
43 | doSomethingAsync().then(
44 | function() {}, // onFulfilled reaction
45 | function() {}, // onRejected reaction
46 | function() {} // onNotified reaction
47 | );
48 | ```
49 | 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.
50 |
51 | #### 2. ES6-compatible way ####
52 | ```js
53 | function doSomethingAsync() {
54 | return new vow.Promise(function(resolve, reject, notify) {
55 | // now you can resolve, reject, notify the promise
56 | });
57 | }
58 |
59 | doSomethingAsync().then(
60 | function() {}, // onFulfilled reaction
61 | function() {}, // onRejected reaction
62 | function() {} // onNotified reaction
63 | );
64 | ```
65 |
66 | Extensions and related projects
67 | -------------------------------
68 | * [vow-fs](https://github.com/dfilatov/vow-fs) — vow-based file I/O for Node.js
69 | * [vow-node](https://github.com/dfilatov/vow-node) — extension for vow to work with nodejs-style callbacks
70 | * [vow-queue](https://github.com/dfilatov/vow-queue) — vow-based task queue with weights and priorities
71 | * [vow-asker](https://github.com/nodules/vow-asker) — wraps [asker](https://github.com/nodules/asker) API in the vow promises implementation
72 |
73 | **NOTE**. Documentation for old versions of the library can be found at https://github.com/dfilatov/vow/blob/0.3.x/README.md.
74 |
--------------------------------------------------------------------------------
/benchmarks/comparison.js:
--------------------------------------------------------------------------------
1 | var cliff = require('cliff'),
2 | benchmark = require('benchmark'),
3 | fs = require('fs'),
4 | data = require('./data'),
5 | Vow = require('..'),
6 | Q = require('q'),
7 | When = require('when'),
8 | Bluebird = require('bluebird'),
9 | Pinkie = require('pinkie'),
10 | corePromise = require('core-js/library/es6/promise'),
11 | Davy = require('davy'),
12 | tests = {
13 | 'Q' : function(deferred) {
14 | var toResolve = [],
15 | topPromises = [];
16 |
17 | Object.keys(data).forEach(function(key) {
18 | var defer = Q.defer();
19 | Q.all(data[key].map(function(val) {
20 | var defer = Q.defer();
21 | toResolve.push({ defer : defer, val : val });
22 | return defer.promise;
23 | }))
24 | .then(function(val) {
25 | defer.resolve(val);
26 | });
27 | topPromises.push(defer.promise);
28 | });
29 |
30 | Q.all(topPromises).then(function() {
31 | deferred.resolve();
32 | });
33 |
34 | toResolve.forEach(function(obj) {
35 | obj.defer.resolve(obj.val);
36 | });
37 | },
38 |
39 | 'When' : function(deferred) {
40 | var toResolve = [],
41 | topPromises = [];
42 |
43 | Object.keys(data).forEach(function(key) {
44 | var defer = When.defer();
45 | When.all(data[key].map(function(val) {
46 | var defer = When.defer();
47 | toResolve.push({ defer : defer, val : val });
48 | return defer.promise;
49 | }))
50 | .then(function(val) {
51 | defer.resolve(val);
52 | });
53 | topPromises.push(defer.promise);
54 | });
55 |
56 | When.all(topPromises).then(function() {
57 | deferred.resolve();
58 | });
59 |
60 | toResolve.forEach(function(obj) {
61 | obj.defer.resolve(obj.val);
62 | });
63 | },
64 |
65 | 'Bluebird' : function(deferred) {
66 | var toResolve = [],
67 | topPromises = [];
68 |
69 | Object.keys(data).forEach(function(key) {
70 | var resolve,
71 | promise = new Bluebird(function(_resolve) {
72 | resolve = _resolve;
73 | });
74 | Bluebird.all(data[key].map(function(val) {
75 | return new Bluebird(function(_resolve) {
76 | toResolve.push({ resolve : _resolve, val : val });
77 | });
78 | }))
79 | .then(function(val) {
80 | resolve(val);
81 | });
82 | topPromises.push(promise);
83 | });
84 |
85 | Bluebird.all(topPromises).then(function() {
86 | deferred.resolve();
87 | });
88 |
89 | toResolve.forEach(function(obj) {
90 | obj.resolve(obj.val);
91 | });
92 | },
93 |
94 | 'Pinkie' : function(deferred) {
95 | var toResolve = [],
96 | topPromises = [];
97 |
98 | Object.keys(data).forEach(function(key) {
99 | var resolve,
100 | promise = new Pinkie(function(_resolve) {
101 | resolve = _resolve;
102 | });
103 | Pinkie.all(data[key].map(function(val) {
104 | return new Pinkie(function(_resolve) {
105 | toResolve.push({ resolve : _resolve, val : val });
106 | });
107 | }))
108 | .then(function(val) {
109 | resolve(val);
110 | });
111 | topPromises.push(promise);
112 | });
113 |
114 | Pinkie.all(topPromises).then(function() {
115 | deferred.resolve();
116 | });
117 |
118 | toResolve.forEach(function(obj) {
119 | obj.resolve(obj.val);
120 | });
121 | },
122 |
123 | 'Davy': function (deferred) {
124 | var toResolve = [],
125 | topPromises = Object.keys(data).map(function(key) {
126 | var defer = Davy.defer();
127 | Davy.all(data[key].map(function(val) {
128 | var defer = Davy.defer();
129 | toResolve.push({ defer : defer, val : val });
130 | return defer.promise;
131 | }))
132 | .then(function(val) {
133 | defer.fulfill(val);
134 | });
135 | return defer.promise;
136 | });
137 |
138 | Davy.all(topPromises).then(function() {
139 | deferred.resolve();
140 | });
141 |
142 | toResolve.forEach(function(obj) {
143 | obj.defer.fulfill(obj.val);
144 | });
145 | },
146 |
147 | 'ES2015 Promise' : function(deferred) {
148 | var toResolve = [],
149 | topPromises = [];
150 |
151 | Object.keys(data).forEach(function(key) {
152 | var resolve,
153 | promise = new Promise(function(_resolve) {
154 | resolve = _resolve;
155 | });
156 | Promise.all(data[key].map(function(val) {
157 | return new Promise(function(_resolve) {
158 | toResolve.push({ resolve : _resolve, val : val });
159 | });
160 | }))
161 | .then(function(val) {
162 | resolve(val);
163 | });
164 | topPromises.push(promise);
165 | });
166 |
167 | Promise.all(topPromises).then(function() {
168 | deferred.resolve();
169 | });
170 |
171 | toResolve.forEach(function(obj) {
172 | obj.resolve(obj.val);
173 | });
174 | },
175 |
176 | 'core-js Promise' : function(deferred) {
177 | var toResolve = [],
178 | topPromises = [];
179 |
180 | Object.keys(data).forEach(function(key) {
181 | var resolve,
182 | promise = new corePromise(function(_resolve) {
183 | resolve = _resolve;
184 | });
185 | corePromise.all(data[key].map(function(val) {
186 | return new corePromise(function(_resolve) {
187 | toResolve.push({ resolve : _resolve, val : val });
188 | });
189 | }))
190 | .then(function(val) {
191 | resolve(val);
192 | });
193 | topPromises.push(promise);
194 | });
195 |
196 | corePromise.all(topPromises).then(function() {
197 | deferred.resolve();
198 | });
199 |
200 | toResolve.forEach(function(obj) {
201 | obj.resolve(obj.val);
202 | });
203 | },
204 |
205 | 'Vow' : function(deferred) {
206 | var toResolve = [],
207 | topPromises = Object.keys(data).map(function(key) {
208 | var defer = Vow.defer();
209 | Vow.all(data[key].map(function(val) {
210 | var defer = Vow.defer();
211 | toResolve.push({ defer : defer, val : val });
212 | return defer.promise();
213 | }))
214 | .then(function(val) {
215 | defer.resolve(val);
216 | });
217 | return defer.promise();
218 | });
219 |
220 | Vow.all(topPromises).then(function() {
221 | deferred.resolve();
222 | });
223 |
224 | toResolve.forEach(function(obj) {
225 | obj.defer.resolve(obj.val);
226 | });
227 | }
228 | },
229 | results = [],
230 | onTestCompleted = function(name) {
231 | results.push({
232 | '' : name,
233 | 'mean time' : (this.stats.mean * 1000).toFixed(3) + 'ms',
234 | 'ops/sec' : (1 / this.stats.mean).toFixed(0)
235 | });
236 | };
237 |
238 | var suite = new benchmark.Suite(
239 | 'comparison',
240 | {
241 | onStart : function() {
242 | console.log('Starts\n');
243 | },
244 |
245 | onComplete : function() {
246 | console.log(cliff.stringifyObjectRows(
247 | results,
248 | ['', 'mean time', 'ops/sec'],
249 | ['red', 'green', 'blue']) + '\n');
250 | results = [];
251 | }
252 | });
253 |
254 | Object.keys(tests).forEach(function(name) {
255 | var i = 0;
256 | suite.add(
257 | name,
258 | function(deferred) {
259 | tests[name](deferred);
260 | },
261 | {
262 | defer : true,
263 | onStart : function() {
264 | //console.log(name + ' \n');
265 | },
266 | onCycle : function() {
267 | console.log('\033[1A' + new Array(i++).join('.'));
268 | },
269 | onComplete : function() {
270 | console.log('');
271 | onTestCompleted.call(this, name);
272 | }
273 | });
274 | });
275 |
276 | suite.run();
277 |
--------------------------------------------------------------------------------
/benchmarks/data.js:
--------------------------------------------------------------------------------
1 | var res = {};
2 |
3 | ['A', 'B', 'C'].forEach(function(key) {
4 | res[key] = [];
5 | for(var i = 0; i < 100; i++) {
6 | res[key].push(key + i);
7 | }
8 | });
9 |
10 | module.exports = res;
11 |
--------------------------------------------------------------------------------
/benchmarks/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "promises-library-speed-comparison",
3 | "version": "0.0.1",
4 | "dependencies": {
5 | "benchmark": "",
6 | "bluebird": "3.4.6",
7 | "cliff": "",
8 | "core-js": "2.4.1",
9 | "pinkie": "2.0.4",
10 | "q": "1.4.1",
11 | "when": "3.7.7",
12 | "davy": "1.3.0"
13 | },
14 | "private": true
15 | }
16 |
--------------------------------------------------------------------------------
/bower.json:
--------------------------------------------------------------------------------
1 | {
2 | "name" : "vow",
3 | "version" : "0.4.20",
4 | "main" : "lib/vow.js",
5 | "ignore" : ["**/.*", "node_modules", "benchmarks", "test", "utils", "Makefile", "package.json"]
6 | }
7 |
--------------------------------------------------------------------------------
/lib/vow.js:
--------------------------------------------------------------------------------
1 | /**
2 | * @module vow
3 | * @author Filatov Dmitry