Gate — An utility to await multiple asynchronous calls
Gate is an utility to await multiple asynchronous calls in Node environment.
Installing
$ npm install gate
Example
You can get each asynchronous result by index or name.
By Index
var gate = ;var fs = ; var g = gate;fs;fs; g;
By Name
var gate = ;var fs = ; var g = gate;fs;fs; g;
Additions to Error objects
A extra field is added to an Error object.
error.gate_locatioin
: The asynchronous call location that the error occurred.
API
gate
module provides following API.
create([Object options]) -> Gate
Returns a Gate object.
options
: Optional. Theoptions
can have followng keys.
KEY | TYPE | DEFAULT VALUE | DESCRIPTION |
---|---|---|---|
count | Number | -1 | A number of times the returned function must be called before an awaiting callback can start. Negative value means that count is not specified. |
failFast | Boolean | true | Indicates whether an awaiting callback is invoked as soon as possible when any error is found. If failFast is true, the found error is set as first argument of the awaiting callback. |
var g = gate;
var g = gate;
--
Gate
objects provide following API.
latch([String name][, Object mapping]) -> Function
Returns a callback. The callback arguments are mapped with a mapping
definition.
If a count is given to gate.create()
, the count is decremented.
name
: Optional. A name for callback arguments. If not specified, an index number is used as name.
var g = gate;fs; // name is specifiedfs; // name is not specified g;
mapping
: Optional. An argument mapping definition. Themapping
gives names to callback arguments. Themappipng
must be a number or an object.- If the
mapping
is a number, single argument is mapped. - If the
mapping
is an object, multiple arguments can be mapped. - If the
mapping
isnull
orundefined
, all arguments are mapped as Array.
var g = gate;fs; // single argumentfs; // multiple argumentsfs; // all arguments g;
val(Object value) -> Object
Indicates that a value is a plain value and it's not a mapping index.
value
: Required. A plain value.
var g = gate; // a number for a `data` property is a mapping index, but a number for `g.val()` is a plain value fs;fs; g;
await(Function callback(err, results, gate)) -> Function
Awaits all asynchronous calls completion and then runs a callback
.
callback
: Required. A callback to run after all asynchronous calls are done.err
: An error to indicate any asynhronous calls are failed.results
: An array to contain each asynchronous result as element.gate
: A new gate object.
var g = gate;fs;fs; g;
count: Number
Gets a current count, if a count is given to gate.latch()
.
Otherwise, -1
is returned.
This is a readonly property.
var g = gate; console; // 2fs;console; // 1fs;console; // 0
More Examples
Arguments Mapping
Pass an argument index or an object includes argument indexs to a function being returned from gate.latch()
.
In the object, values except whose type is number
are recognized arguments.
To pass an number as argument, wrap it with val
function.
var gate = ;var fs = ;var exec = exec; var g = gate; // single mapping: arguments[1] in the callback will be resultfs; // multiple mapping: arguments[1] and argments[2] in the callback will be result; // all mapping: arguments will be resultfs; g;
Countdown
Pass a count number to gate.create()
to wait until a set of callbacks are done.
var gate = ;var fs = ; var files = 'file1' 'file2';var g = gate;g; process;
Error Handling
Check the first argument of the awaiting callback. If the argument is not null, it is any error object.
var gate = ;var fs = ; var g = gate;fs;fs; g;
Error Handling - handling all errors
Turn off failFaslt
option and include an error object in each result.
Then you can handle all errors by yourself.
var gate = ;var fs = ; var g = gate;fs;fs; g;
Nesting
You can use third argument of an awaiting callback to nest 'gate.await()'.
var gate = ;var fs = ; var g = gate;fs;fs; g;