@stdlib/utils/async/for-each-right/docs/repl.txt

Standard utilities.

{{alias}}( collection, [options,] fcn, done )
    Invokes a function once for each element in a collection, iterating from
    right to left.

    When invoked, `fcn` is provided a maximum of four arguments:

    - 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 `fcn`
    accepts two arguments, `fcn` is provided:

    - value
    - next

    If `fcn` accepts three arguments, `fcn` is provided:

    - value
    - index
    - next

    For every other `fcn` signature, `fcn` is provided all four arguments.

    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.

    The function does not skip `undefined` elements.

    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).

    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: false.

    options.thisArg: any (optional)
        Execution context.

    fcn: 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 onDuration( value, next ) {
    ...     setTimeout( onTimeout, value );
    ...     function onTimeout() {
    ...         console.log( value );
    ...         next();
    ...     }
    ... };
    > function done( error ) {
    ...     if ( error ) {
    ...         throw error;
    ...     }
    ...     console.log( 'Done.' );
    ... };
    > var arr = [ 1000, 2500, 3000 ];
    > {{alias}}( arr, onDuration, done )
    1000
    2500
    3000
    Done.

    // Limit number of concurrent invocations:
    > function onDuration( value, next ) {
    ...     setTimeout( onTimeout, value );
    ...     function onTimeout() {
    ...         console.log( value );
    ...         next();
    ...     }
    ... };
    > function done( error ) {
    ...     if ( error ) {
    ...         throw error;
    ...     }
    ...     console.log( 'Done.' );
    ... };
    > var opts = { 'limit': 2 };
    > var arr = [ 1000, 2500, 3000 ];
    > {{alias}}( arr, opts, onDuration, done )
    2500
    3000
    1000
    Done.

    // Process sequentially:
    > function onDuration( value, next ) {
    ...     setTimeout( onTimeout, value );
    ...     function onTimeout() {
    ...         console.log( value );
    ...         next();
    ...     }
    ... };
    > function done( error ) {
    ...     if ( error ) {
    ...         throw error;
    ...     }
    ...     console.log( 'Done.' );
    ... };
    > var opts = { 'series': true };
    > var arr = [ 1000, 2500, 3000 ];
    > {{alias}}( arr, opts, onDuration, done )
    3000
    2500
    1000
    Done.


{{alias}}.factory( [options,] fcn )
    Returns a function which invokes a function once for each element in a
    collection, iterating from right to left.

    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: false.

    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 onDuration( value, next ) {
    ...     setTimeout( onTimeout, value );
    ...     function onTimeout() {
    ...         console.log( value );
    ...         next();
    ...     }
    ... };
    > var opts = { 'series': true };
    > var f = {{alias}}.factory( opts, onDuration );
    > function done( error ) {
    ...     if ( error ) {
    ...         throw error;
    ...     }
    ...     console.log( 'Done.' );
    ... };
    > var arr = [ 1000, 2500, 3000 ];
    > f( arr, done )
    3000
    2500
    1000
    Done.
    > arr = [ 1000, 1500, 2000 ];
    > f( arr, done )
    2000
    1500
    1000
    Done.

    See Also
    --------