aa v0.1.40

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:

$ npm install aa --save
   or
$ npm install async-await --save

PREPARE:

  var aa = require('aa');
  // or
  var aa = require('async-await');

  var promisify    = aa.promisify;
  var thunkify     = aa.thunkify;
  var promisifyAll = aa.promisifyAll;
  var thunkifyAll  = aa.thunkifyAll;
  var Channel      = aa.Channel;

  var Promise      = aa.Promise;      // override native Promise
  var PromiseThunk = aa.PromiseThunk; // use PromiseThunk indivisually

or

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

<script src="https://lightspeedworks.github.io/promise-thunk/promise-thunk.js"></script>
<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.

aa(function *() {
	// *** SEQUENTIAL EXECUTION ***

	// yield value returns itself
	yiled 1;
	yiled [1, 2, 3];
	yiled {x:1, y:2, z:3};

	// yield promise returns resolved value
	yield Promise.resolve(1);

	// or throws rejected error
	try { yield Promise.reject(new Error('expected')); }
	catch (e) { console.error('%s', e); }

	// *** PARALLEL EXECUTION ***

	// yield an array of promises waits all promises and returns resolved array
	yield [Promise.resolve(1), Promise.resolve(2)];

	// yield an object of promises waits all promises and returns resolved object
	yield {x: Promise.resolve(1), y: Promise.resolve(2)};

	// *** OTHERS AND COMBINED OPERATIONS ***

	// yield thunk
	// yield generator or generator function
	// yield channel for event stream
});

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:

var pg = require('pg');
var pg_connect = aa.promisify(pg, pg.connect);         // -> yield pg_connect()
var 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:

var pg = require('pg');
aa.promisify(pg, 'connect', {suffix: 'A'};             // -> yield pg.connectA()
aa.promisify(pg.Client.prototype, 'connect'); // -> yield client.connectAsync()
aa.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:

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

postgres pg example:

var pg = require('pg');
aa.promisifyAll(pg.constructor.prototype, {suffix: 'A'});  // -> yield pg.connectA()
aa.promisifyAll(pg.Client.prototype);  // -> yield client.connectAsync()
                                       // -> 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:

var pg = require('pg');
var pg_connect = aa.thunkify(pg, pg.connect);         // -> yield pg_connect()
var 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:

var pg = require('pg');
aa.thunkify(pg, 'connect', {suffix: 'A'});  // -> yield pg.connectA()
aa.thunkify(pg.Client.prototype, 'connect'); // -> yield client.connectAsync()
aa.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:

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

postgres pg example:

var pg = require('pg');
aa.thunkifyAll(pg.constructor.prototype, {suffix: 'A'});  // -> yield pg.connectA()
aa.thunkifyAll(pg.Client.prototype);  // -> yield client.connectAsync()
                                      // -> 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

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

EXAMPLES:

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

$ node aa-readme-ex01-seq.js

	var aa = require('aa');


	aa(main);


	function *main() {
		console.log('11:', yield asyncPromise(100, 11));
		console.log('12:', yield asyncThunk(100, 12));
		console.log('13:', yield asyncGenerator(100, 13));
		yield sub(20);
		yield sub(30);
	}


	function *sub(base) {
		console.log('%s: %s', base + 1, yield asyncPromise(100, base + 1));
		console.log('%s: %s', base + 2, yield asyncThunk(100, base + 2));
		console.log('%s: %s', base + 3, yield asyncGenerator(100, base + 3));
	}


	// asyncPromise(msec, arg) : promise
	function asyncPromise(msec, arg) {
		return new Promise(function (resolve, reject) {
			setTimeout(resolve, msec, arg);
		});
	}


	// asyncThunk(msec, arg) : thunk
	function asyncThunk(msec, arg) {
		return function (callback) {
			setTimeout(callback, msec, null, arg);
		};
	}


	// asyncGenerator(msec, arg) : generator
	function *asyncGenerator(msec, arg) {
		var chan = aa.Channel();
		setTimeout(chan, msec, arg);
		return yield chan;
	}

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

$ node aa-readme-ex02-par.js

	var aa = require('aa');


	aa(main);


	function *main() {
		console.log('[11, 12, 13]:', yield [
			asyncPromise(100, 11),
			asyncThunk(100, 12),
			asyncGenerator(100, 13)
		]);

		console.log('{x:11, y:12, z:13}:', yield {
			x: asyncPromise(100, 11),
			y: asyncThunk(100, 12),
			z: asyncGenerator(100, 13)
		});

		yield [sub(20), sub(30)];
	}


	function *sub(base) {
		console.log('%s: %s', base + 1, yield asyncPromise(100, base + 1));
		console.log('%s: %s', base + 2, yield asyncThunk(100, base + 2));
		console.log('%s: %s', base + 3, yield asyncGenerator(100, base + 3));
	}


	// asyncPromise(msec, arg) : promise
	function asyncPromise(msec, arg) {
		return new Promise(function (resolve, reject) {
			setTimeout(resolve, msec, arg);
		});
	}


	// asyncThunk(msec, arg) : thunk
	function asyncThunk(msec, arg) {
		return function (callback) {
			setTimeout(callback, msec, null, arg);
		};
	}


	// asyncGenerator(msec, arg) : generator
	function *asyncGenerator(msec, arg) {
		var chan = aa.Channel();
		setTimeout(chan, msec, arg);
		return yield chan;
	}

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

$ node aa-readme-ex11-promisify.js

	var aa = require('aa');
	var promisify = aa.promisify;
	var asyncPromise = promisify(asyncCallback);


	aa(main);


	function *main() {
		console.log('11:', yield asyncPromise(100, 11));
		console.log('12:', yield asyncPromise(100, 12));
		console.log('13:', yield asyncPromise(100, 13));

		asyncPromise(100, 21)
		.then(function (val) {
			console.log('21:', val);
			return asyncPromise(100, 22);
		})
		.then(function (val) {
			console.log('22:', val);
			return asyncPromise(100, 23);
		})
		.then(function (val) {
			console.log('23:', val);
		});
	}


	// asyncCallback(msec, arg. callback) : node style normal callback
	// callback : function (err, val)
	function asyncCallback(msec, arg, callback) {
		setTimeout(callback, msec, null, arg);
	}

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

$ node aa-readme-ex12-thunkify.js

	var aa = require('aa');
	var thunkify = aa.thunkify;
	var asyncThunk = thunkify(asyncCallback);


	aa(main);


	function *main() {
		console.log('11:', yield asyncThunk(100, 11));
		console.log('12:', yield asyncThunk(100, 12));
		console.log('13:', yield asyncThunk(100, 13));

		asyncThunk(100, 21)
		(function (err, val) {
			console.log('21:', val);
			asyncThunk(100, 22)
			(function (err, val) {
				console.log('22:', val);
				asyncThunk(100, 23)
				(function (err, val) {
					console.log('23:', val);
				});
			});
		});
	}


	// asyncCallback(msec, arg. callback) : node style normal callback
	// callback : function (err, val)
	function asyncCallback(msec, arg, callback) {
		setTimeout(callback, msec, null, arg);
	}

Quick example collection: aa-readme-example.js

$ node aa-readme-example.js

  var aa = require('aa');


	// sleep(msec, args,... callback) : node style normal callback
	// callback : function (err, val)
	function sleep(msec) {
		var args = [].slice.call(arguments, 1);
		setTimeout.apply(null, [args.pop(), msec, null].concat(args));
	}

	sleep(1000, function (err, val) { console.log('1000 msec OK'); });


	// delay(msec, args,...)(callback) : thunk
	// callback : function (err, val)
	function delay(msec) {
		var args = [].slice.call(arguments);
		return function (callback) {
			sleep.apply(null, args.concat(callback));
		};
	}
	// var delay = aa.thunkify(sleep);

	delay(1100)(
		function (err, val) { console.log('1100 msec OK'); }
	);


	// aa.promisify(fn)   : returns wrapped function a.k.a thunkify and promisify
	// wait(msec, args,...) : returns promise & thunk
	var wait = aa.promisify(sleep);

	// wait() : as a thunk
	wait(1200)(
		function (err, val) { console.log('1200 msec OK'); }
	);

	// wait() : as a promise
	wait(1300).then(
		function (val) { console.log('1300 msec OK'); },
		function (err) { console.log('1300 msec NG', err); }
	).catch(
		function (err) { console.log('1300 msec NG2', err); }
	);


	// aa(generator) : returns promise & thunk
	aa(function *() {

		yield 1;                    // primitive value
		yield [1, 2, 3];            // array
		yield {x:1, y:2, z:3};      // object


		// wait for promise
		yield Promise.resolve(2);


		// wait for thunk
		yield delay(800);


		// wait for promise or thunk
		yield wait(800);


		console.log('0:', yield wait(300, 0));
		console.log('1:', yield wait(300, 1));


		// yield Promise.all([])
		console.log('[1, 2, 3]:',
			yield Promise.all([wait(200, 1), wait(300, 2), wait(100, 3)]));


		// yield [] -> like Promise.all([]) !
		console.log('[4, 5, 6]:',
			yield [wait(200, 4), wait(300, 5), wait(100, 6)]);


		// yield {} -> like Promise.all({}) !?
		console.log('{x:7, y:8, z:9}:',
			yield {x:wait(200, 7), y:wait(300, 8), z:wait(100, 9)});


		// make channel for sync - fork and join
		var chan = aa.Channel();

		sleep(300, 20, chan);   // send value to channel : fork or spread
		sleep(200, 10, chan);   // send value to channel : fork or spread
		var a = yield chan;     // recv value from channel : join or sync
		var b = yield chan;     // recv value from channel : join or sync
		console.log('10 20:', a, b);


		// fork thread -  make new thread and start
		aa(function *() {
			yield wait(200);      // wait 200 msec
			return 200;
		})(chan);               // send 200 to channel : join or sync

		// fork thread -  make new thread and start
		aa(function *() {
			yield wait(100);      // wait 100 msec
			return 100;
		})(chan);               // send 100 to channel : join or sync

		// fork thread -  make new thread and start
		aa(function *() {
			yield wait(300);      // wait 300
			return 300;
		})(chan);               // send 300 to channel : join or sync

		// join threads - sync threads
		var x = yield chan;     // wait & recv first  value from channel
		var y = yield chan;     // wait & recv second value from channel
		var z = yield chan;     // wait & recv third  value from channel
		console.log('top 3 winners: 100 200 300:', x, y, z);


		// communicate with channels
		var chan1 = aa.Channel(), chan2 = aa.Channel();

		// thread 1: send to chan1, recv from chan2
		aa(function *() {
			sleep(100, 111, chan1);
			console.log('222:', yield chan2);
			sleep(100, 333, chan1);
			console.log('444:', yield chan2);
			sleep(100, 555, chan1);
			return 666;
		})(chan);

		// thread 1: recv from chan1, send to chan2
		aa(function *() {
			console.log('111:', yield chan1);
			sleep(100, 222, chan2);
			console.log('333:', yield chan1);
			sleep(100, 444, chan2);
			console.log('555:', yield chan1);
			return 777;
		})(chan);
		console.log('666 777:', yield chan, yield chan);

		return 11;
	})
	.then(
		function (val) {
			console.log('11 val:', val);
			return wait(100, 22); },
		function (err) {
			console.log('11 err:', err);
			return wait(100, 22); }
	)
	(function (err, val) {
			console.log('22 val:', val, err ? 'err:' + err : '');
			return wait(100, 33); })
	(function (err, val) {
			console.log('33 val:', val, err ? 'err:' + err : '');
			return wait(100, 44); })
	.then(
		function (val) {
			console.log('44 val:', val);
			return wait(100, 55); },
		function (err) {
			console.log('44 err:', err);
			return wait(100, 55); }
	)
	.catch(
		function (err) {
			console.log('55 err:', err);
			return wait(100, 66); }
	);

LICENSE:

MIT