Wondering what’s next for npm?Check out our public roadmap! »

    @ygor/list

    5.4.1 • Public • Published

    @ygor/list

    NPM version Downloads Build Status Coverage Status

    An array-aware promise object. Like a regular promise, but with asynchronous iteration methods. Works wonderfully with async and await in Node.js 8 and above. Part of the Ygor toolkit.

    Install

    $ npm install --save @ygor/list

    Usage

    const list = require('@ygor/list');
     
    const [foo, bar] = await list(['/foo', '/bar'])
      .map(url => fetch(url))
      .map(res => res.json());
     
    console.log(foo);
    console.log(bar);

    API

    list(arr): List<any>

    • arr {Array<Promise|any>,Promise<Array<Promise|any>>} - An array of items, an array of promises, a promise for an array of items, or a promise for an array of promises.

    Creates a List, an array-aware Promise object. Always resolves to a resolved array of resolved items.

    List Methods

    .then() and .catch()

    A List is just a Promise with some extra methods, so the typical .then() and .catch() are here, plus the following.

    .filter(callback [, options]): List

    • callback {Function(item, i)} - Filter function.
    • options {Object} - See p-filter options.

    Essentially Array.prototype.filter, but the callback may return a promise.

    .find(callback [, options]): List

    • callback {Function(item, i)} - Find function.
    • options {Object} - See p-locate options.

    Essentially Array.prototype.find, but the callback may return a promise.

    .first([count [, options]]): List

    • count {Number} - Number of items to await. (default: 1)
    • options {Object} - See p-some options.

    Returns a List containing the first item or items that resolve.

    const delay = require('delay');
     
    const items = [
      delay(20, 'foo'),
      delay(10, 'bar'),
      delay(40, 'baz'),
      delay(30, 'bat')
    ];
     
    const first = await list(items).first();
     
    console.log(first); // -> ['bar']
     
    const firstTwo = await list(items).first(2);
     
    console.log(firstTwo); // -> ['bar', 'foo']
     
    const firstTwoB = await list(items).first(2, {
      filter: x => x.startsWith('b')
    });
     
    console.log(firstTwoB); // -> ['bar', 'bat']

    .flatMap(callback [, options]): List

    • callback {Function(item, i)} - Map function.
    • options {Object} - See p-map options.

    Convenience shorthand for list.map(...).flatten().

    .flatten(): List

    Flattens an array of arrays into a single array. Useful when map functions return an unknown number of items that should result in the new list.

    const letters = await list(['a', 'b', 'c'])
        .map(x => [x, x.toUpperCase()])
        .flatten();
     
    console.log(letters); // -> ['a', 'A', 'b', 'B', 'c', 'C']

    .map(callback [, options]): List

    • callback {Function(item, i)} - Map function.
    • options {Object} - See p-map options.

    Essentially Array.prototype.map, but the callback may return a promise.

    .reduce(callback, initial [, options]): List

    • callback {Function(item, i)} - Map function.
    • initial any - Initial value for reduction.
    • options {Object} - See p-reduce options.

    Essentially Array.prototype.reduce, but the callback may return a promise. Also, the return value will always be an array, even if the initial value is not. This allows you to continue the chain.

    const number = await list([1, 2, 3])
        .reduce((a, b) => a + b, 0)
        .flatMap(x => [x, x * x]);
     
    console.log(number); // -> [6, 36]

    ygor


    MIT © Shannon Moeller

    Install

    npm i @ygor/list

    DownloadsWeekly Downloads

    13

    Version

    5.4.1

    License

    MIT

    Unpacked Size

    8.97 kB

    Total Files

    3

    Last publish

    Collaborators

    • avatar