aa - async-await

co like library, go like channel, thunkify or promisify wrap package.

using ES6 (ES2015) generator function.

compatible with co@3 and co@4.

INSTALL:

1$ npm install aa --save
2   or
3$ npm install async-await --save

PREPARE:

1  var aa = require('aa');
2  // or
3  var aa = require('async-await');
4
5  var promisify    = aa.promisify;
6  var thunkify     = aa.thunkify;
7  var promisifyAll = aa.promisifyAll;
8  var thunkifyAll  = aa.thunkifyAll;
9  var Channel      = aa.Channel;
10
11  var Promise      = aa.Promise;      // override native Promise
12  var PromiseThunk = aa.PromiseThunk; // use PromiseThunk indivisually

or

https://lightspeedworks.github.io/promise-thunk/promise-thunk.js
https://lightspeedworks.github.io/aa/aa.js

1<script src="https://lightspeedworks.github.io/promise-thunk/promise-thunk.js"></script>
2<script src="https://lightspeedworks.github.io/aa/aa.js"></script>

USAGE:

aa(generator or generator function)

aa() returns promise (thunkified promise).

basic usage.
you can aa() promises, generators, and generator functions.

1aa(function *() {
2	// *** SEQUENTIAL EXECUTION ***
3
4	// yield value returns itself
5	yiled 1;
6	yiled [1, 2, 3];
7	yiled {x:1, y:2, z:3};
8
9	// yield promise returns resolved value
10	yield Promise.resolve(1);
11
12	// or throws rejected error
13	try { yield Promise.reject(new Error('expected')); }
14	catch (e) { console.error('%s', e); }
15
16	// *** PARALLEL EXECUTION ***
17
18	// yield an array of promises waits all promises and returns resolved array
19	yield [Promise.resolve(1), Promise.resolve(2)];
20
21	// yield an object of promises waits all promises and returns resolved object
22	yield {x: Promise.resolve(1), y: Promise.resolve(2)};
23
24	// *** OTHERS AND COMBINED OPERATIONS ***
25
26	// yield thunk
27	// yield generator or generator function
28	// yield channel for event stream
29});

aa.promisify([ctx,] fn, [options])

promisify() converts node style function into a function returns promise-thunk.
you can use fs.exists() and child_process.exec() also.

• ctx: context object. default: this or undefined.
• fn: node-style normal function.
• options: options object.
  • context: context object.

also thenable, yieldable, callable.

postgres pg example:

1var pg = require('pg');
2var pg_connect = aa.promisify(pg, pg.connect);         // -> yield pg_connect()
3var client_query = aa.promisify(client, client.query); // -> yield client_query()

aa.promisify(object, method, [options])

promisify() defines method promisified function returns promise-thunk.

• object: target object.
• method: method name string.
• options: method name suffix or postfix. default: 'Async'. or options object.
  • suffix: method name suffix or postfix. default: 'Async'.
  • postfix: method name suffix or postfix. default: 'Async'.

postgres pg example:

1var pg = require('pg');
2aa.promisify(pg, 'connect', {suffix: 'A'};             // -> yield pg.connectA()
3aa.promisify(pg.Client.prototype, 'connect'); // -> yield client.connectAsync()
4aa.promisify(pg.Client.prototype, 'query');   // -> yield client.queryAsync()

aa.promisifyAll(object, [options])

promisifyAll() defines all methods promisified function returns promise-thunk.

• object: target object.
• options: method name suffix or postfix. default: 'Async'. or options object.
  • suffix: method name suffix or postfix. default: 'Async'.
  • postfix: method name suffix or postfix. default: 'Async'.

file system fs example:

1var fs = require('fs');
2aa.promisifyAll(fs, {suffix: 'A'});  // -> yield fs.readFileA()

postgres pg example:

1var pg = require('pg');
2aa.promisifyAll(pg.constructor.prototype, {suffix: 'A'});  // -> yield pg.connectA()
3aa.promisifyAll(pg.Client.prototype);  // -> yield client.connectAsync()
4                                       // -> yield client.queryAsync()

aa.thunkify([ctx,] fn, [options])

thunkify() converts node style function into a thunkified function.
you can use fs.exists() and child_process.exec() also.

• ctx: context object. default: this or undefined.
• fn: node-style normal function with callback.
• options: options object.
  • context: context object.

also yieldable, callable.

postgres pg example:

1var pg = require('pg');
2var pg_connect = aa.thunkify(pg, pg.connect);         // -> yield pg_connect()
3var client_query = aa.thunkify(client, client.query); // -> yield client_query()

aa.thunkify(object, method, [options])

thunkify() defines method thunkified function returns thunk.

• object: target object.
• method: method name string.
• options: method name suffix or postfix. default: 'Async'. or options object.
  • suffix: method name suffix or postfix. default: 'Async'.
  • postfix: method name suffix or postfix. default: 'Async'.

postgres pg example:

1var pg = require('pg');
2aa.thunkify(pg, 'connect', {suffix: 'A'});  // -> yield pg.connectA()
3aa.thunkify(pg.Client.prototype, 'connect'); // -> yield client.connectAsync()
4aa.thunkify(pg.Client.prototype, 'query');   // -> yield client.queryAsync()

aa.thunkifyAll(object, [options])

thunkifyAll() defines all methods thunkified function returns thunk.

• object: target object.
• options: method name suffix or postfix. default: 'Async'. or options object.
  • suffix: method name suffix or postfix. default: 'Async'.
  • postfix: method name suffix or postfix. default: 'Async'.

file system fs example:

1var fs = require('fs');
2aa.thunkifyAll(fs, {suffix: 'A'});  // -> yield fs.readFileA()

postgres pg example:

1var pg = require('pg');
2aa.thunkifyAll(pg.constructor.prototype, {suffix: 'A'});  // -> yield pg.connectA()
3aa.thunkifyAll(pg.Client.prototype);  // -> yield client.connectAsync()
4                                      // -> yield client.queryAsync()

aa.Channel() : new channel for event stream

Channel() returns a new channel for event stream.
use a channel for node style function as a callback.
yield channel for wait it.

yield : waits and returns resolved value.

you can yield promises, thunkified functions, generators, generator functions, primitive values, arrays, and objects.

aa.callback(gtor) : returns callback function

callback(gtor) returns normal callback function

1http.createServer(aa.callback(function *(req, res) {
2	yield aa.wait(1000);
3	res.end('delayed hello');
4})).listen(process.env.PORT || 8000);

EXAMPLES:

Example 1 sequential: aa-readme-ex01-seq.js

1$ node aa-readme-ex01-seq.js

1	var aa = require('aa');
2
3
4	aa(main);
5
6
7	function *main() {
8		console.log('11:', yield asyncPromise(100, 11));
9		console.log('12:', yield asyncThunk(100, 12));
10		console.log('13:', yield asyncGenerator(100, 13));
11		yield sub(20);
12		yield sub(30);
13	}
14
15
16	function *sub(base) {
17		console.log('%s: %s', base + 1, yield asyncPromise(100, base + 1));
18		console.log('%s: %s', base + 2, yield asyncThunk(100, base + 2));
19		console.log('%s: %s', base + 3, yield asyncGenerator(100, base + 3));
20	}
21
22
23	// asyncPromise(msec, arg) : promise
24	function asyncPromise(msec, arg) {
25		return new Promise(function (resolve, reject) {
26			setTimeout(resolve, msec, arg);
27		});
28	}
29
30
31	// asyncThunk(msec, arg) : thunk
32	function asyncThunk(msec, arg) {
33		return function (callback) {
34			setTimeout(callback, msec, null, arg);
35		};
36	}
37
38
39	// asyncGenerator(msec, arg) : generator
40	function *asyncGenerator(msec, arg) {
41		var chan = aa.Channel();
42		setTimeout(chan, msec, arg);
43		return yield chan;
44	}

Example 2 parallel: aa-readme-ex02-par.js

1$ node aa-readme-ex02-par.js

1	var aa = require('aa');
2
3
4	aa(main);
5
6
7	function *main() {
8		console.log('[11, 12, 13]:', yield [
9			asyncPromise(100, 11),
10			asyncThunk(100, 12),
11			asyncGenerator(100, 13)
12		]);
13
14		console.log('{x:11, y:12, z:13}:', yield {
15			x: asyncPromise(100, 11),
16			y: asyncThunk(100, 12),
17			z: asyncGenerator(100, 13)
18		});
19
20		yield [sub(20), sub(30)];
21	}
22
23
24	function *sub(base) {
25		console.log('%s: %s', base + 1, yield asyncPromise(100, base + 1));
26		console.log('%s: %s', base + 2, yield asyncThunk(100, base + 2));
27		console.log('%s: %s', base + 3, yield asyncGenerator(100, base + 3));
28	}
29
30
31	// asyncPromise(msec, arg) : promise
32	function asyncPromise(msec, arg) {
33		return new Promise(function (resolve, reject) {
34			setTimeout(resolve, msec, arg);
35		});
36	}
37
38
39	// asyncThunk(msec, arg) : thunk
40	function asyncThunk(msec, arg) {
41		return function (callback) {
42			setTimeout(callback, msec, null, arg);
43		};
44	}
45
46
47	// asyncGenerator(msec, arg) : generator
48	function *asyncGenerator(msec, arg) {
49		var chan = aa.Channel();
50		setTimeout(chan, msec, arg);
51		return yield chan;
52	}

Example promisify: aa-readme-ex11-promisify.js

1$ node aa-readme-ex11-promisify.js

1	var aa = require('aa');
2	var promisify = aa.promisify;
3	var asyncPromise = promisify(asyncCallback);
4
5
6	aa(main);
7
8
9	function *main() {
10		console.log('11:', yield asyncPromise(100, 11));
11		console.log('12:', yield asyncPromise(100, 12));
12		console.log('13:', yield asyncPromise(100, 13));
13
14		asyncPromise(100, 21)
15		.then(function (val) {
16			console.log('21:', val);
17			return asyncPromise(100, 22);
18		})
19		.then(function (val) {
20			console.log('22:', val);
21			return asyncPromise(100, 23);
22		})
23		.then(function (val) {
24			console.log('23:', val);
25		});
26	}
27
28
29	// asyncCallback(msec, arg. callback) : node style normal callback
30	// callback : function (err, val)
31	function asyncCallback(msec, arg, callback) {
32		setTimeout(callback, msec, null, arg);
33	}

Example thunkify: aa-readme-ex12-thunkify.js

1$ node aa-readme-ex12-thunkify.js

1	var aa = require('aa');
2	var thunkify = aa.thunkify;
3	var asyncThunk = thunkify(asyncCallback);
4
5
6	aa(main);
7
8
9	function *main() {
10		console.log('11:', yield asyncThunk(100, 11));
11		console.log('12:', yield asyncThunk(100, 12));
12		console.log('13:', yield asyncThunk(100, 13));
13
14		asyncThunk(100, 21)
15		(function (err, val) {
16			console.log('21:', val);
17			asyncThunk(100, 22)
18			(function (err, val) {
19				console.log('22:', val);
20				asyncThunk(100, 23)
21				(function (err, val) {
22					console.log('23:', val);
23				});
24			});
25		});
26	}
27
28
29	// asyncCallback(msec, arg. callback) : node style normal callback
30	// callback : function (err, val)
31	function asyncCallback(msec, arg, callback) {
32		setTimeout(callback, msec, null, arg);
33	}

Quick example collection: aa-readme-example.js

1$ node aa-readme-example.js

1  var aa = require('aa');
2
3
4	// sleep(msec, args,... callback) : node style normal callback
5	// callback : function (err, val)
6	function sleep(msec) {
7		var args = [].slice.call(arguments, 1);
8		setTimeout.apply(null, [args.pop(), msec, null].concat(args));
9	}
10
11	sleep(1000, function (err, val) { console.log('1000 msec OK'); });
12
13
14	// delay(msec, args,...)(callback) : thunk
15	// callback : function (err, val)
16	function delay(msec) {
17		var args = [].slice.call(arguments);
18		return function (callback) {
19			sleep.apply(null, args.concat(callback));
20		};
21	}
22	// var delay = aa.thunkify(sleep);
23
24	delay(1100)(
25		function (err, val) { console.log('1100 msec OK'); }
26	);
27
28
29	// aa.promisify(fn)   : returns wrapped function a.k.a thunkify and promisify
30	// wait(msec, args,...) : returns promise & thunk
31	var wait = aa.promisify(sleep);
32
33	// wait() : as a thunk
34	wait(1200)(
35		function (err, val) { console.log('1200 msec OK'); }
36	);
37
38	// wait() : as a promise
39	wait(1300).then(
40		function (val) { console.log('1300 msec OK'); },
41		function (err) { console.log('1300 msec NG', err); }
42	).catch(
43		function (err) { console.log('1300 msec NG2', err); }
44	);
45
46
47	// aa(generator) : returns promise & thunk
48	aa(function *() {
49
50		yield 1;                    // primitive value
51		yield [1, 2, 3];            // array
52		yield {x:1, y:2, z:3};      // object
53
54
55		// wait for promise
56		yield Promise.resolve(2);
57
58
59		// wait for thunk
60		yield delay(800);
61
62
63		// wait for promise or thunk
64		yield wait(800);
65
66
67		console.log('0:', yield wait(300, 0));
68		console.log('1:', yield wait(300, 1));
69
70
71		// yield Promise.all([])
72		console.log('[1, 2, 3]:',
73			yield Promise.all([wait(200, 1), wait(300, 2), wait(100, 3)]));
74
75
76		// yield [] -> like Promise.all([]) !
77		console.log('[4, 5, 6]:',
78			yield [wait(200, 4), wait(300, 5), wait(100, 6)]);
79
80
81		// yield {} -> like Promise.all({}) !?
82		console.log('{x:7, y:8, z:9}:',
83			yield {x:wait(200, 7), y:wait(300, 8), z:wait(100, 9)});
84
85
86		// make channel for sync - fork and join
87		var chan = aa.Channel();
88
89		sleep(300, 20, chan);   // send value to channel : fork or spread
90		sleep(200, 10, chan);   // send value to channel : fork or spread
91		var a = yield chan;     // recv value from channel : join or sync
92		var b = yield chan;     // recv value from channel : join or sync
93		console.log('10 20:', a, b);
94
95
96		// fork thread -  make new thread and start
97		aa(function *() {
98			yield wait(200);      // wait 200 msec
99			return 200;
100		})(chan);               // send 200 to channel : join or sync
101
102		// fork thread -  make new thread and start
103		aa(function *() {
104			yield wait(100);      // wait 100 msec
105			return 100;
106		})(chan);               // send 100 to channel : join or sync
107
108		// fork thread -  make new thread and start
109		aa(function *() {
110			yield wait(300);      // wait 300
111			return 300;
112		})(chan);               // send 300 to channel : join or sync
113
114		// join threads - sync threads
115		var x = yield chan;     // wait & recv first  value from channel
116		var y = yield chan;     // wait & recv second value from channel
117		var z = yield chan;     // wait & recv third  value from channel
118		console.log('top 3 winners: 100 200 300:', x, y, z);
119
120
121		// communicate with channels
122		var chan1 = aa.Channel(), chan2 = aa.Channel();
123
124		// thread 1: send to chan1, recv from chan2
125		aa(function *() {
126			sleep(100, 111, chan1);
127			console.log('222:', yield chan2);
128			sleep(100, 333, chan1);
129			console.log('444:', yield chan2);
130			sleep(100, 555, chan1);
131			return 666;
132		})(chan);
133
134		// thread 1: recv from chan1, send to chan2
135		aa(function *() {
136			console.log('111:', yield chan1);
137			sleep(100, 222, chan2);
138			console.log('333:', yield chan1);
139			sleep(100, 444, chan2);
140			console.log('555:', yield chan1);
141			return 777;
142		})(chan);
143		console.log('666 777:', yield chan, yield chan);
144
145		return 11;
146	})
147	.then(
148		function (val) {
149			console.log('11 val:', val);
150			return wait(100, 22); },
151		function (err) {
152			console.log('11 err:', err);
153			return wait(100, 22); }
154	)
155	(function (err, val) {
156			console.log('22 val:', val, err ? 'err:' + err : '');
157			return wait(100, 33); })
158	(function (err, val) {
159			console.log('33 val:', val, err ? 'err:' + err : '');
160			return wait(100, 44); })
161	.then(
162		function (val) {
163			console.log('44 val:', val);
164			return wait(100, 55); },
165		function (err) {
166			console.log('44 err:', err);
167			return wait(100, 55); }
168	)
169	.catch(
170		function (err) {
171			console.log('55 err:', err);
172			return wait(100, 66); }
173	);

LICENSE:

MIT