Savoy.js
Higher-order functions (synchronous and asynchronous each/eachSeries/map/filter/fold) and functions for flow control (parallel/series/waterfall) in under 1 KB.
- API is similar (not identical) to that of the Async library
- 2.5 KB minified, or about 0.9 KB minified and gzipped
- Legible tests, with 100% coverage
Why
Savoy’s higher-order functions differ from Async’s in the following ways:
- The signature of the
fn
iterator is different. Thecb
callback (invoked to signal the end of each iteration offn
) is the first argument offn
. In addition,fn
is also passed the index/key of the current element, and the originalcollection
itself. - If passed is an Object,
map
andfilter
will return an Object. (If passed an Object, Async’smap
andfilter
will return an Array.)
Also, mainly this:
Inventing your own wheels gives you a deep appreciation and understanding of how wheels work and what makes a good one.
API
In all of the method signatures below, collection
(in each/eachSeries/map/filter/fold) and fns
(in parallel/series/waterfall) can either be an Array or an Object literal.
each
savoy.each(collection, fn) — synchronous each
savoy;
-
Break from the loop by explicitly returning
false
fromfn
:savoy;
savoy.each(collection, fn, done) — asynchronous each
savoy;
- The asynchronous function
fn
is called in parallel over each item incollection
. - Invoke the
cb
callback infn
to signal the end of each iteration offn
. - The signature of the
cb
callback iscb(err)
. Iferr
is truthy, thedone
callback is called exactly once with theerr
. - When
fn
has completed execution over every item in thecollection
, thedone
callback is called exactly once with a falsyerr
.
eachSeries
savoy.eachSeries(collection, fn) — synchronous eachSeries
- Alias of
savoy.each
.
savoy.eachSeries(collection, fn, done) — asynchronous eachSeries
savoy;
- The asynchronous function
fn
is called in series over each item incollection
. - Invoke the
cb
callback infn
to signal the end of each iteration offn
. - The signature of the
cb
callback iscb(err)
. Iferr
is truthy, we stop iterating over thecollection
, and thedone
callback is called exactly once with theerr
. - When
fn
has completed execution over every item in thecollection
, thedone
callback is called exactly once with a falsyerr
.
map
savoy.map(collection, fn) — synchronous map
var result = savoy;console;//=> { a: 2, b: 4, c: 6 }
savoy.map(collection, fn, done) — asynchronous map
savoy;
- The asynchronous function
fn
is called in parallel over each item incollection
. - Invoke the
cb
callback infn
to signal the end of each iteration offn
. The signature of thecb
callback iscb(err, mapVal)
:err
— If truthy, thedone
callback is called exactly once with theerr
.mapVal
— This is accumulated in theresult
argument of thedone
callback.
- When
fn
has completed execution over every item in thecollection
, thedone
callback is called exactly once with a falsyerr
and theresult
of the map. - Note that if
collection
is an Object:result
will also be an Object.- Items in
result
may not be in the same order as their corresponding items in the originalcollection
.
filter
savoy.filter(collection, fn) — synchronous filter
var result = savoy;console;//=> [2, 3]
savoy.filter(collection, fn, done) — asynchronous filter
savoy;
- The asynchronous function
fn
is called in parallel over each item incollection
. - Invoke the
cb
callback infn
to signal the end of each iteration offn
. The signature of thecb
callback iscb(err, predicate)
:err
— If truthy, thedone
callback is called exactly once with theerr
.predicate
— If truthy, the current item is added to theresult
argument of thedone
callback.
- When
fn
has completed execution over every item in thecollection
, thedone
callback is called exactly once with a falsyerr
and theresult
of the filter. - Note that if
collection
is an Object:result
will also be an Object.- Items in
result
may not be in the same relative order as they were incollection
.
fold
savoy.fold(collection, acc, fn) — synchronous fold
var result = savoy;console;//=> 6
savoy.fold(collection, acc, fn, done) — asynchronous fold
savoy;
- The asynchronous function
fn
is called in series over each item incollection
. - Invoke the
cb
callback infn
to signal the end of each iteration offn
. The signature of thecb
callback iscb(err, foldVal)
:err
— If truthy, thedone
callback is called exactly once with theerr
.foldVal
— This is the value foracc
that is passed to the next iteration offn
.
- When
fn
has completed execution over every item in thecollection
, thedone
callback is called exactly once with a falsyerr
and theresult
of the fold.
parallel
savoy.parallel(fns [, done])
savoy;
- Each function in
fns
is called in parallel. - Invoke the
cb
callback in each function to signal the end of the function. The signature of thecb
callback iscb(err, val)
:err
— If truthy, thedone
callback is called exactly once with theerr
.val
— This is accumulated in theresult
argument of thedone
callback.
- When every function in
fns
has completed execution, thedone
callback is called exactly once with a falsyerr
and theresult
of each function.
series
savoy.series(fns [, done])
savoy;
- Each function in
fns
is called in series. - Invoke the
cb
callback in each function to signal the end of the function. The signature of thecb
callback iscb(err, val)
:err
— If truthy, thedone
callback is called exactly once with theerr
.val
— This is accumulated in theresult
argument of thedone
callback.
- When the entire series of functions has completed execution, the
done
callback is called exactly once with a falsyerr
and theresult
of each function.
waterfall
savoy.waterfall(fns [, done])
savoy;
- Each function in
fns
is called in series. - Invoke the
cb
callback in each function to signal the end of the function. The signature of thecb
callback iscb(err [, arg1, arg2, ...])
:err
— If truthy, thedone
callback is called exactly once with theerr
.arg1, arg2, ...
— Arguments that are passed on to the next function infns
.
- When the entire series of functions has completed execution, the
done
callback is called exactly once with a falsyerr
and arguments from the last function infns
.
Installation
Install via npm:
$ npm i --save savoy
Install via bower:
$ bower i --save yuanqing/savoy
To use Savoy in the browser, include the minified script in your HTML:
<!-- ... -->