@stdlib/utils
Version:
Standard utilities.
224 lines (185 loc) • 6.33 kB
Plain Text
{{alias}}( collection, initial, [options,] reducer, done )
Applies a function against an accumulator and each element in a collection
and returns the accumulated result.
When invoked, `reducer` is provided a maximum of five arguments:
- accumulator: accumulated value.
- value: collection value.
- index: collection index.
- collection: the input collection.
- next: a callback to be invoked after processing a collection `value`.
The actual number of provided arguments depends on function length. If
`reducer` accepts three arguments, `reducer` is provided:
- accumulator
- value
- next
If `reducer` accepts four arguments, `reducer` is provided:
- accumulator
- value
- index
- next
For every other `reducer` signature, `reducer` is provided all five
arguments.
The `next` callback accepts two arguments:
- error: error argument.
- accumulator: accumulated value.
If a provided function calls the `next` callback with a truthy `error`
argument, the function suspends execution and immediately calls the `done`
callback for subsequent `error` handling.
Execution is *not* guaranteed to be asynchronous. To guarantee asynchrony,
wrap the `done` callback in a function which either executes at the end of
the current stack (e.g., `nextTick`) or during a subsequent turn of the
event loop (e.g., `setImmediate`, `setTimeout`).
The function does not support dynamic collection resizing.
If provided an empty collection, the function invokes the `done` callback
with the `initial` value as the second argument.
The function does not skip `undefined` elements.
When processing collection elements concurrently, *beware* of race
conditions when updating an accumulator. This is especially true when an
accumulator is a primitive (e.g., a number). In general, prefer object
accumulators.
Parameters
----------
collection: Array|TypedArray|Object
Input collection over which to iterate. If provided an object, the
object must be array-like (excluding strings and functions).
initial: any
Accumulator value used in the first invocation of the reduction
function.
options: Object (optional)
Function options.
options.limit: integer (optional)
Maximum number of pending invocations. Default: Infinity.
options.series: boolean (optional)
Boolean indicating whether to process each collection element
sequentially. Default: true.
options.thisArg: any (optional)
Execution context.
reducer: Function
The function to invoke for each element in a collection.
done: Function
A callback invoked either upon processing all collection elements or
upon encountering an error.
Examples
--------
// Basic usage:
> function fcn( acc, value, index, next ) {
... setTimeout( onTimeout, value );
... function onTimeout() {
... console.log( value );
... acc.sum += value;
... next( null, acc );
... }
... };
> function done( error, acc ) {
... if ( error ) {
... throw error;
... }
... console.log( acc.sum );
... };
> var arr = [ 3000, 2500, 1000 ];
> var acc = { 'sum': 0 };
> {{alias}}( arr, acc, fcn, done )
3000
2500
1000
6500
// Limit number of concurrent invocations:
> function fcn( acc, value, index, next ) {
... setTimeout( onTimeout, value );
... function onTimeout() {
... console.log( value );
... acc.sum += value;
... next( null, acc );
... }
... };
> function done( error, acc ) {
... if ( error ) {
... throw error;
... }
... console.log( acc.sum );
... };
> var opts = { 'limit': 2 };
> var arr = [ 3000, 2500, 1000 ];
> var acc = { 'sum': 0 };
> {{alias}}( arr, acc, opts, fcn, done )
2500
3000
1000
6500
// Process concurrently:
> function fcn( acc, value, index, next ) {
... setTimeout( onTimeout, value );
... function onTimeout() {
... console.log( value );
... acc.sum += value;
... next( null, acc );
... }
... };
> function done( error, acc ) {
... if ( error ) {
... throw error;
... }
... console.log( acc.sum );
... };
> var opts = { 'series': false };
> var arr = [ 3000, 2500, 1000 ];
> var acc = { 'sum': 0 };
> {{alias}}( arr, acc, opts, fcn, done )
1000
2500
3000
6500
{{alias}}.factory( [options,] fcn )
Returns a function which applies a function against an accumulator and each
element in a collection and returns the accumulated result.
Parameters
----------
options: Object (optional)
Function options.
options.limit: integer (optional)
Maximum number of pending invocations. Default: Infinity.
options.series: boolean (optional)
Boolean indicating whether to process each collection element
sequentially. Default: true.
options.thisArg: any (optional)
Execution context.
fcn: Function
The function to invoke for each element in a collection.
Returns
-------
out: Function
A function which invokes a function for each element in a collection.
Examples
--------
> function fcn( acc, value, index, next ) {
... setTimeout( onTimeout, value );
... function onTimeout() {
... console.log( value );
... acc.sum += value;
... next( null, acc );
... }
... };
> var opts = { 'series': false };
> var f = {{alias}}.factory( opts, fcn );
> function done( error, acc ) {
... if ( error ) {
... throw error;
... }
... console.log( acc.sum );
... };
> var arr = [ 3000, 2500, 1000 ];
> var acc = { 'sum': 0 };
> f( arr, acc, done )
1000
2500
3000
6500
> acc = { 'sum': 0 };
> arr = [ 2000, 1500, 1000 ];
> f( arr, acc, done )
1000
1500
2000
4500
See Also
--------