p-fied

PromisiFIED asynchronous utility module.

Motivation

async.js proposed a lot of asynchronous way in JavaScript. But now we have a Promise.

Some of async.js functions can be easily expressed with the Promise (e.g. series, parallel...), so p-fied doesn't have these functions.

ここまで書いて async.js と Bluebird で足りたんじゃないのという気持ちになった．元気がなくなったので日本語で書く．

pfor(initialState, test, update, routine)

for([initialState], [test], [update]){
	[routine]
}

arguments

• initialState - 初期状態を示すObject．

• test - (state: Object) => bool | Promise<bool>．trueならループ続行，falseでループ終了．

• update - (state: Object) => state．状態を更新する．返値を更新後の値とする．返さなかった場合はroutineの返値

• routine - (state: Object) => state | Promise<state> | true | Promise<true> | any．ループのメイン処理を表現する．返値が状態オブジェクトやそのPromiseであるならば，updateに渡す値はここで返した値となる．ループ中のいわゆるcontinueを，routineがsynchronousである場合はreturnで，asynchronousである場合はreturn resolvedPromiseで表現する．breakはreturn rejectedPromise(true)で表現する．

• returns Promise<state>. エラー終了した場合はrejected，その他の場合はresolved．

pfied.pfor({i: 0}, s => s.i < 5, s => {i: s.i+1}, s => {
	setImmediate(_ => console.log(s.i));
}).then(s => console.log("done! %d", s.i));
/*
0
1
2
3
4
done! 5
*/

動作の詳細例はテストコードが参考になるだろう．

whilst(test, routine, initialState?)

doWhilst(test, routine, initialState?)

while文に対応．testがtrue || Promise<true>な間，routineを実行する．initialStateは省略可能．routineの挙動はpforのものに従う．

doWhilstはそのままdo-while文に対応する．

until(test, routine, initialState?)

doUntil(test, routine, initialState?)

while文に対応するが，testがfalse || Promise<false>である間にroutineを実行する．他はwhilstやdoWhilstに従う．

forever(routine, initialState)

無限ループ．routineはpforのものと同様の動作を期待する．

new Queue(worker, concurrency = 1)

async.jsのQueueと同様の機能を提供する．

• worker - (task: Object) => any．キューからタスクを受け取って処理する．

• concurrency - 並行して最大いくつまでworkerを実行するか指定する．初期値は1．

• Queue#push(task: Object) => Promise<worker returning value>

• Queue#unshift(task: Object) => Promise<worker returning value> キューにタスクを追加する．pushはFIFO，unshiftはLIFO．返値はそのタスクが処理されたときに解決されるPromise．

• Queue#pushBulk(tasks: [Object]) => [Promise<worker returning value>]

• Queue#unshiftBulk(tasks: [Object]) => [Promise<worker returning value>] キューにタスクを一度に複数個追加する．返値は単体時と同様のPromiseからなるArray．与えたタスク列の順に対応している．

• running() - ワーカーが処理中か否か true/false

• idle() - !running()

• pause() - ワーカーの追加を中止する．現在処理中のものは続行する．

• resume() - ワーカーの追加を再開する．

• kill() - ワーカーに渡されていないタスクをドロップする．

• saturated - タスクを追加する操作をしたとき，保持するタスク数がcurrencyを超えた場合にコールバックする関数を指定する．

• empty - タスク保持数がゼロになったときにコールバックする関数を指定する．

• drain - ワーカー稼働数がゼロになったときにコールバックする関数を指定する．

• error - ワーカー稼働中にエラーが発生した場合にコールバックする関数を指定する．エラーを第一引数で受け取れる．

new Cargo(worker, payload = 1)

Queueに近いが，ワーカーに渡すときpayloadの数を最大値として取れるだけ取り，配列に詰めて渡す．結果のPromiseはワーカーが正常終了すれば個別に返る．ワーカーが失敗すると一緒に渡されたタスクの結果Promiseは失敗原因でrejectされる．

new ProirityQueue(worker, concurrency, comperator)

Queueに近いが，タスク間の順序を定義しておくことで，その順にワーカーに渡す．先頭や末尾に追加するという概念がないので，unshiftを持たない．順序定義用の関数comperatorは，Array.prototype.sortが引数として要求する形式を満たすこと．

async.jsのものは固定値で優先度を定義してその順に取り出していたため，優先度の与え方がまったく異なる．