Promtie 👔
Neatly dress up your native promises with simple but powerful utils.
Unlike Bluebird
or Q
, promtie aims to be used with native promises by making it very easy to start a chain of promises or to intersect a set of promises with, for example, an each or map iteration.
Promtie
is just as powerful as Bluebird
or Q
, but instead of forcing the usage of custom Promise instances, with Promtie
you can use native promises.
This module includes the most common utils needed to work with collections of promises: each
, map
, filter
, reduce
, ...; as well as other common patterns when using promises: delay
, timeout
, retry
, spread
, catchIf
, ...
; // Greet all the unicorns at the same timepromtie// Feed each unicorn one at a time;
You can also use each util separately without requiring the whole module. This is the recomended way to use it.
; // using requirevar each = ;
Installation
$ npm install --save promtie
API Reference
- each
- map
- filter
- reduce
- values
- settle
- attempt
- spread
- retry
- delay
- timeout
- catchIf
- whilst
- times
- through
- nodeify
- promisify
- promisifyAll
each
each(array, fn) -> Promise
:
Iterates over the array
and calls fn
on each value (or promise that resolves to a value) in series.
; ;
each(fn) -> Function
:
If you omit the array, each
returns a function that takes the array instead as an argument.
; Promise;
map
map(array, fn, options) -> Promise
:
Iterates over the array
and calls fn
on each value (promise that resolves to a value) in parallel.
Concurrency can be controlled with options.concurrency
.
; ;
map(fn, options) -> Function
:
If you omit the array, map
returns a function that takes the array instead as an argument.
; Promise;
filter
filter(array, fn, [options]) -> Promise
:
Iterates over the array
and filters out the array values if they do not pass the function test.
Concurrency can be controlled with options.concurrency
; ;
filter(fn, [options]) -> Function
:
If you omit the array, filter
returns a function that takes the array instead as an argument.
; Promise;
reduce
reduce(array, fn, [initialValue]) -> Promise
:
Iterates over the array and calls fn on each value and accumulates the result to reduce it to a single value.
; ;
reduce(fn, [initialValue]) -> Function
:
If you omit the array, reduce
returns a function that takes the array instead as an argument.
; Promise;
values
values(object) -> Promise
:
Resolve the values of an object, whether they are promises or not, fulfilled.
; ; // 'value3'
values(fn) -> Function
:
If you omit the object, values
returns a function that takes the object instead as an argument.
; Promise // 'value3'
settle
settle(array) -> Promise
:
Wait until all the promises in the array settle, and then resolve a promise with all the fulfilment values or rejections.
;; ;
attempt
attempt(fn) -> Promise
:
Start a chain of promises while mapping synchronous exceptions to promise rejections.
;; ;
spread
spread(array, fn) -> Promise
:
Spreads array values to the arguments of fn
.
; ;
spread(array, fn) -> Function
:
If you omit the array, spread
returns a function that takes the array instead as an argument.
; Promise;
retry
retry(n, fn, [options]) -> Promise
:
Retry a function n
times. Delay in between retries can be configured with options.delay
.
// Retry at most three times to connect to db if the connection is timing out.;
delay
delay(n) -> Function
:
Delays the execution of the next promise by n
milliseconds.
; ; // Also works with promise failures;
delay(n, fn) -> Promise
:
Alternatively, if you also pass a function, delay
returns a promise.
Useful for starting a promise chain with a delay.
; // Wait 200 milliseconds to start the server;
timeout
timeout(n, fn | promise) -> Promise
:
Do not wait more than n
milliseconds for the operation to finish.
If Timeout is reached, the promise is rejected with timeout.TimeoutError
.
; ;
catchIf
catchIf(predicateFn, fn) -> Function
:
Returns a function that will handle an error if it passes the predicate function test.
If the predicate returns false, the error is propagated and fn
is not called.
Useful for treating different types of errors without cluttering the code with switch cases/ifs.
; db;// If the error thrown was not a NotFoundError or a ConnectionTimeoutError// the error continues to be thrown.
catchIf(object, fn) -> Function
:
Alternatively, you can pass an object to be matched with error instance.
; {}NotFoundErrorprototype = Object;NotFoundErrorprototype { thismessage = 'Not found'; thiscode = 'NOT_FOUND';}; db// If the error is an instance of NotFoundError;
whilst
whilst(conditionFn, fn, [options]) -> Promise
:
Whilst the conditionFn
returns true, execute fn
. fn
and conditionFn
can return a value or a promise. Delay in between iterations can be configured with options.delay
(default is 0).
; delay: 150 );
times
times(n, fn) -> Promise
:
Execute fn
, n
times. The returned promise fulfills to the n
results from each fn
call.
fn
calls are run in parallel.
Concurrency can be controlled with options.concurrency
.
;; ;
through
through(fn) -> Function
:
Execute fn
while passing the resolved value or rejection through, regardless of the promise's resolved value or rejection.
When used on both the fulfillment and rejection handlers, this is similar to the try/catch finally, meaning, regardless of the promise's end result, this code is executed.
; db// Close connection to db whether the promise was fulfilled or not; // Ordb// Close connection to db whether the promise was fulfilled or not;
nodeify
nodeify([fn]) -> Function
:
Returns a function that calls the callback function with the resulting value or the error. If the callback throws an error, it will be thrown to the global context.
If no callback is provided, the returned function simply returns the value or continues to propagate the error.
Useful for APIs that still want to support callback style.
; // Function can be used with callback style or promise style { return Promise ;} // Or { return Promise ;}
promisify
promisify(fn) -> Function
:
Promisifies a callback style function.
; const feedUnicornAsync = ; { console; ;} ;
promisifyAll
promisifyAll(object, [targetObject]) -> Object
:
Promisifies all the enumerable functions of an object, returning a new object, or assigning methods to the targetObject
.
Methods that also have methods are recursively promisified.
; const jeffy = ; jeffy;
Tests
$ npm test
Contributing
Feel free to propose PRs for bug fixes, adding utils, etc.
License
Released under the MIT License.