undertake
Another choice beyond co.
If links in this document not avaiable, please access README on GitHub directly.
Description
undertake is incubated from jinang/co. It is something like well-known co. It just offers another choice.
Table of Contents
Get Started
const undertake = ; // A generator function. { // yield promise. let a = Promise; // yield thunkified function. let b = { ; }; let c = ; // c equals 3 // Traverse an array. let d = 0; undertake; // d equals 6 // Traverse an array and return a mapped one. let e = undertake; // e equals [2,4,6] let { ; }; let f1 = undertake; // f1 equals 24 let f2 = undertake; // f2 equals 24 return a + b + c + d;} { let m = Promise; let n = Promise; return m + n;} // When no callback passed in, an instance of Promise will be returned.; // A triditional callback is acceptable.;// RETURN undefined // If callback is also a generator function, an instance of Promise will be returned.; // Create a new function which will accept the same paramenters as the generator function do,// and return an instance of Promise on being invoked.let fn = undertake;;
API
-
Promise undertake(GeneratorFunction fn)
Something likeco
. -
Promise undertake(GeneratorFunction fn [, GeneratorFunction callback, boolean compatible ])
Successively execute generator functions fn and callback.
If compatible istrue
, returned value which is instance ofError
will be regarded as normal value. Otherwise and by default, such returned value will trigger rejection. -
void undertake(GeneratorFunction fn, Function callback [, boolean compatible ])
Execute the generator function fn, then invoke callback. -
Promise undertake.applying(Function fn, Object this_value, Array args)
Invoke fn and return an instance ofPromise
.
Function fn SHOULD accept a standard callback function as the last argument. Developer SHOULD NOT put a callback in args, it will be automatically appended when fn is really invoked.
This util is designed to make things easy to yield a traditional asynchronised function. -
Promise undertake.calling(Function fn, Object this_value, Any arg_0, ...)
Invoke fn and return an instance ofPromise
. -
Promise undertake.easy(GeneratorFunction fn)
See undertake vs. undertake.easy. -
Promise(undefined) undertake.each(Array arr, GeneratorFunction iterator)
For each item of arr, execute the generator function iterator with the item as the only argument. -
Promise(Array) undertake.map(Array arr, GeneratorFunction iterator)
Return an array ofPromise
instances. Each promise will carry the data returned by the corresponding generator function. -
boolean undertake.isGenerator(any foo) A util function.
-
boolean undertake.isGeneratorFunction(any foo)
A util function. -
Function undertake.sync(GeneratorFunction fn [, Function callback])
Wrap a generator function. Without callback, the new function will return an instance ofPromise
on being invoked. Otherwise,callback()
will be invoked finally when the new function is invoked and completed. -
Function undertake.async(GeneratorFunction fn [, number callbackIndex])
Wrap a generator function. The new function will return an instance ofPromise
on being invoked without a callback function, orcallback()
will be invoked finally. ParametercallbackIndex
will indicate the position ofcallback
. By default, the last argument with type of'function'
will be regarded as the callback function.
If callback(err, data)
exists, what returned by the generator function will become data and what throwed will become err.
undertake vs. undertake.easy
For undertake
, operator yield
expects a promise, generator function or thunkify function. If something following yield
is not expected, an error will be thrown.
For undertake.easy
, anything is allowed to follow yield
operator. If it is not an instance of Promise
or Function
, itself will be returned by yield
. E.g.
// A generator function. { let a = Promise; // `a` now equals 'A'. let b = 'B'; // `b` now equals 'B'; return a + b;} // Error: operator `yield` expects a promise, generator function or thunkify functionlet p0 = ; // It's OK.let p1 = undertake; // It's OK. As same as p1.let p2 = ;
undertake.sync vs. undertake.async
undertake.sync()
and undertake.async()
are used to create (or so-called "wrap") a generator function and return a new normal one. They two are actually identical when no "callback()" occurs.
{ return Promise;} { console;} // A new function is created. "main()" does not run now.const f0 = undertake;// Promise(A) returned.;// Promise(A) returned. "callback" is ignored.; // Both "main()" and "callback()" do not run now.const f1 = undertake;// Nothing returned. "a" is printed.; // f2 is the same as f0.const f2 = undertake;// Promise(A) returned.;// Nothing returned. "a" is printed. Here, the last argument is regarded as "callback" if it is a function.; // The first (index 0) argument passed to f3 will be regarded as "callback".const f3 = undertake;// Promise(A) returned.;// Nothing returned. "a" is printed.;