This is an Promises/A+ solution with traceable fused that ease debugging to async code.
when
Returns a Promise/A+ object that is to be fulfilled or rejected in the future or immediately. Specifically promise objects created by this library relies on the promise package.
However for arguments that requires a promise object, any objects of Promise/A+ implementation should work.
Long stack trace
All errors raised during asynchronous callback are all processed by the traceable package so you can access the stack trace of the previous event loop.
;
Resolving routine
With handler and fulfilling value:
- If handler is a function, call the function with the fulfilling value:
- If exception raised during callback or an
Error
object is returned, follow the error handling routine. - Otherwise let handler to be the returned value and continue.
- If exception raised during callback or an
- If handler is a promise object, wait until:
- When that promise is fulfilled, fulfill with its fulfilling value.
- When that promise is rejected, follow the error handling routine.
- If handler is not
undefined
fulfill with handler. - Otherwise fulfill with fulfilling value or otherwise specified (null action).
Error handling routine
With handler and error:
- If handler is a function, follow resolving routine with handler and null action being rejecting with the same error.
- If handler is a map:
- If exception code (i.e.
Error#name
orError#code
) is one of the keys:- If the associated map value is a
string
, reject with an error with the new code and same message. - If the associated map value is a
function
, follow the error handling routine again.
- If the associated map value is a
- If the
default
key presents on the map:- Follow the subroutine as if the exception code is one of the keys.
- If exception code (i.e.
- Otherwise reject with the same error.
;;;;; // Combining `then` and `onerror`;
It is very similar to calling Promise#then(then, onerror)
except that
onerror
can catch any exceptions or errors fromthen
; and- any asynchronous subsequent exceptions or errors from
then
andonerror
.
So retry can be easily written as
var retryCount = 0;;
when(fn, [onerror])
Runs the callback fn
and returns a promise object.
;
The fn
function receives a function argument then
.
The primary usage of then
is to deal with Node.js callback pattern.
If then
is called with handler
, it returns a callback function that handles Node.js callback where:
- If error is received, follow the error handling routine with
onerror
as handler. - Otherwise follow the resolving routine with
handler
as handler and null action being doing nothing.
// Promise fulfilled with the file size; // Promise fulfilled with `fs.Stats`; // Promise that check if the file exists and then read the file content;
when(value, [then], [onerror])
If none of the overloads listed below matches, returns a fulfilled promise with value
.
then
and onerror
will be supplied as handlers for resolving routine and
error handling rountine.
when(Promise, [then], [onerror])
Returns a promise that wait until the given promise is fulfilled or rejected, and resolve the promise by resolving routine with the fulfilled value as handler.
// Promise fulfilled with 2;
when(Array<Promise>, [then], [onerror])
Returns a promise that wait until all promises are fulfilled or rejected:
- If any promises is rejected, follow the error handling routine with the first encountered error.
- Otherwise follow the resolving routine with an array of fulfilled values as handler.
If more than one promise is rejected, other errors will sinked silently.
To catch the sinked errors use when.monitor
.
;
when(Object<Promise>, [then], [onerror])
Returns a promise that wait until all promises are fulfilled or rejected:
- If any promises is rejected, follow the error handling routine with the first encountered error.
- Otherwise follow the resolving routine with a map of fulfilled values as handler.
If more than one promise is rejected, other errors will sinked silently.
To catch the sinked errors use when.monitor
.
;
when(EventEmitter, [eventHandlers], [onerror])
Returns a promise that:
- When the
EventEmitter
emits anerror
event, follow the error handling routine with the error. - If listened event is emitted, follow the resolving routine with the first argument as handler.
// Fulfill when response emit `end` event with the first argument// Reject when response emit `error` event; // Fulfill when response emit `end` event with custom value; // Fulfill on multiple event;
when(Array<Function>)
Returns a promise that sequentially calls the functions.
The promise will always be resolved after call on the last element.
Any exception raised in callback
will not break the asynchronous loop.
To catch the sinked errors use when.monitor
.
; // Print out "123"
when(Error)
Returns a rejected promise with the given error.
Utilities
when.map(array, callback, [then], [onerror])
Calls callback
on each element in the array
, creating promise objects on each value from the calls, and
returns a promise that wait until all promises are fulfilled or rejected.
// Promise fulfilled with [1, 4, 9] when; // Both the immediately returned promises and the fulfilled values of the promises// are flatten if their elements contains arrays// the following promise is fulfilled with [2, 3, 1, 4, 6, 4, 6, 9, 9]when; // Promises and values can be mixed on the map callback// the following promise is fulfilled with [1, 4, 3]when;
when.forEach(array, callback, [then], [onerror])
Sequentially calls callback
on each element in the array after the promise returned from the last call is fulfilled or rejected.
The promise will always be resolved after call on the last element.
Any exception raised in callback
will not break the asynchronous loop.
To catch the sinked errors use when.monitor
.
// `arr` will contain the exact sequence of numbers as the input arrayvar arr = ;when;
when.while(fn, [then], [onerror])
Asychronous version of while((value = fn(value)) !== false)
.
The fulfilled value returned from the fn
callback will be tested and as the parameter of the next call to fn
.
var result = ;when;
when.monitor([options], callback)
By this the returned promise object is exteneded with EventEmitter
so you can listen various event.
timeout
event
If timeout
options is specified, the timeout
event is emitted when one of the promise in the promise chain
did not fulfill or reject in the given amount of time.
The error object is raised with call stack information about the promise creation location.
when;
uncaughtException
event
The uncaughtException
event is emitted when creating a promise from an array of promise, where
only the first encountered error is propagated through the promise chain.
The other errors they are considered uncaught and will be sinked silently. By attaching a monitor you can catch those errors.
when;