presage
A set of utilities for working with ECMAScript Promises.
Documentation
Collections
eachSeries
filter
,filterSeries
map
,mapSeries
reduce
Control Flow
Utilities
Collections
eachSeries(coll, iteratee)
Applies the function iteratee
to each item in coll
, in series.
iteratee
is called with an item from the collection, and may return
a value or a Promise. If iteratee
throws an Error or returns a
rejected Promise, eachSeries
returns a rejected Promise.
This function is best used to yield side-effects. If in-place
transformation without side-effects are desired, use map
or
mapSeries
instead.
Arguments
coll
- A collection to iterate over.iteratee(item)
- A function to apply to each item incoll
. Note that the array index ofitem
is not passed toiteratee
.
Example
; presage;
filter(coll, iteratee)
Returns a new array of all the values in coll
which result in a truthy
value when iteratee
is applied to them. This operation is performed in
parallel, but the results array will be in the same order as coll
.
Arguments
coll
- A collection to iterate over.iteratee(item)
- A truth test to apply to each item incoll
. Expected, but not required, to return a Promise.
Example
;; const pAccess = { fs;}; presage;
Related
- filterSeries(coll, iteratee)
map(coll, iteratee)
Produces a new collection of values by mapping each value in coll
through the iteratee
function. The iteratee
is called with an item
from coll
and is expected (but not required) to return a Promise. If
iteratee
rejects or throws, the map
function returns a rejected
Promise.
This function applies iteratee
to each item in parallel. As such there
is no guarantee that iteratee
Promises will resolve in order. However,
the results array will be in the same order as the original coll
.
Arguments
coll
- A collection to iterate over.iteratee(item)
- A function to apply to each item incoll
.
Example
;; const pState = { const callbackFunction promise } = presage; fs; return promise;} presage;
Related
- mapSeries(coll, iteratee)
reduce(coll, reducer, initialValue)
Reduces coll
into a single value using async reducer
to return
each incremental result. initialValue
is the initial state of the
reduction. This function only operates in series.
Arguments
coll
- A collection to iterate over. This collection may contain values or Promises.reducer(memo, item)
- A function applied to each item incoll
to produce the next step in the reduction.memo
is the current memoization of the reduction, containing the partial result up to the current step.item
is the current item incoll
that is being processed.reducer
may return a value or a Promise.
Example
; presage;
Control Flow
parallel(tasks)
Runs the functions in the tasks
collection in parallel, without
waiting for the other tasks to finish. If any task throws an Error or
returns a rejected Promise, this function returns a rejected Promise.
Best used for performing multiple async I/O tasks in parallel. Should not be used for tasks that do not use timers or perform I/O; the single-threaded nature of JavaScript will run these tasks in series and not yield any performance gain.
This function accepts an object instead of an array. Each property will
be run as a function, and the results will be passed to the resolved
Promise returned by parallel
.
Arguments
tasks
- A collection containing functions to run.
Example
; presage; presage;
series(tasks)
Runs the functions in the tasks
collection in series, each task
running once the previous task has completed. If any tasks in the series
throw or return a rejected Promise, the task processing stops and the
series
function returns a rejected Promise. Otherwise, it returns a
resolved Promise when all tasks
have been completed.
A task may be a Promise, a function that returns a Promise, or a function that returns a value.
Arguments
tasks
- A collection containing functions to run. Each function is passed zero arguments.
Example
; presage;
Utilities
promiseWithCallback([valueReducer])
Returns an object containing a promise
and a callbackFunction
.
These are connected such that when callback
is invoked, promise
is
resolved or rejected accordingly.
The callback function has the signature:
callbackFunction(error[, arg1[, ...[, argN]]])
; it expects the first
argument to be an Error object or null, while subsequent arguments are
provided to promise
for resolution.
Takes an optional valueReducer
function that reduces values passed to
the callback function to a single value. promise
is resolved with this
value. If valueReducer
throws or rejects, promise
is rejected.
This function can be useful for wrapping callback-based async functions with Promises.
Arguments
valueReducer
- an optional variadic function that reduces its arguments to a single value.
Example
;; const pReadFile = { const callbackFunction promise } = presage; fs; return promise;}; ; // ...and with a value reducer that adds callback argumentsconst callbackFunction promise } = ; ;promise;