Class AsyncIterableCollection<TInput>

All methods that return IAsyncCollection are executed lazly which means they will be executed when the AsyncIterableCollection is iterated with forEach method or "for await of" loop. The rest of the methods are executed eagerly.

Type Parameters

  • TInput

Implements

Constructors

Methods

  • The after method returns the item that comes after the first item that matches predicateFn. If the collection is empty or the predicateFn does not match or matches the last item then null is returned.

    Parameters

    Returns Promise<null | TInput>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.after(item => item === 2);
    // 3
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.after(item => item === 4);
    // null
  • The afterOr method returns the item that comes after the first item that matches predicateFn. If the collection is empty or the predicateFn does not match or matches the last item then defaultValue is returned.

    Type Parameters

    Parameters

    Returns Promise<TInput | TExtended>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.afterOr(-1, item => item === 2);
    // 3
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.afterOr(-1, item => item === 4);
    // -1
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.afterOr(() => -1, item => item === 4);
    // -1
  • The before method returns the item that comes before the first item that matches predicateFn. If the predicateFn does not match or matches the first item then null is returned.

    Parameters

    Returns Promise<null | TInput>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.before(item => item === 2);
    // 1
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.before(item => item === 1);
    // null
  • The beforeOr method returns the item that comes before the first item that matches predicateFn. If the collection is empty or the predicateFn does not match or matches the first item then defaultValue is returned.

    Type Parameters

    Parameters

    Returns Promise<TInput | TExtended>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.beforeOr(-1, item => item === 2);
    // 1
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.beforeOr(-1, item => item === 1);
    // -1
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.beforeOr(() => -1, item => item === 1);
    // -1
  • The countBy method counts the occurrences of values in the collection by selectFn . By default the equality check occurs on the item.

    Type Parameters

    Parameters

    Returns IAsyncCollection<RecordItem<TOutput, number>>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection(["a", "a", "a", "b", "b", "c"]);
    const count = await collection
    .countBy()
    .map(([key, collection]) => [key, collection.toArray()])
    .toArray();
    // [
    // ["a", 3],
    // ["b", 2],
    // ["c", 1]
    // ]
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection(["alice@gmail.com", "bob@yahoo.com", "carlos@gmail.com"]);
    const count = await collection
    .countBy(item => item.split("@")[1])
    .toArray();
    // [
    // ["gmail.com", 2],
    // ["yahoo.com", 1]
    // ]
  • The crossJoin method cross joins the collection's values among iterables, returning a Cartesian product with all possible permutations.

    Type Parameters

    • TExtended

    Parameters

    Returns IAsyncCollection<CrossJoinResult<TInput, TExtended>>

    import { ListCollection } from "@daiso-tech/core";;

    const collection = new ListCollection([1, 2]);
    const matrix = collection.cross(["a", "b"]);
    await matrix.toArray();
    // [
    // [1, "a"],
    // [1, "b"],
    // [2, "a"],
    // [2, "b"],
    // ]
    import { ListCollection } from "@daiso-tech/core";;

    const collection = new ListCollection([1, 2]);
    const matrix = collection.cross(["a", "b"]).cross(["I", "II"]);
    await matrix.toArray();
    // [
    // [1, "a", "I"],
    // [1, "a", "II"],
    // [1, "b", "I"],
    // [1, "b", "II"],
    // [2, "a", "I"],
    // [2, "a", "II"],
    // [2, "b", "I"],
    // [2, "b", "II"],
    // ]
  • The delay method will delay collection such that each value is returned after the specified number of seconds. This method is especially useful for situations where you may be interacting with external APIs that rate limit incoming requests:

    Parameters

    • timeInMs: number

    Returns IAsyncCollection<TInput>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    // An iterator that will fetch all users from a specific api
    class ApiIterator implements AsyncIterable<IUser> { ... }
    const apiIterator = new ApiIterator();
    const collection = new AsyncIterableCollection(apiIterator);
    await collection.delay(1000).forEach(user => console.log(user))
  • The difference method will return the values in the original collection that are not present in iterable. By default the equality check occurs on the item.

    Type Parameters

    Parameters

    Returns IAsyncCollection<TInput>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 2, 3, 4, 5]);
    const difference = collection.difference([2, 4, 6, 8]);
    await difference.toArray();
    // [1, 3, 5]
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([
    { name: "iPhone 6", brand: "Apple", type: "phone" },
    { name: "iPhone 5", brand: "Apple", type: "phone" },
    { name: "Apple Watch", brand: "Apple", type: "watch" },
    { name: "Galaxy S6", brand: "Samsung", type: "phone" },
    { name: "Galaxy Gear", brand: "Samsung", type: "watch" },
    ]);
    const difference = collection.difference(
    [
    { name: "Apple Watch", brand: "Apple", type: "watch" },
    ],
    (product) => product.type
    );
    await difference.toArray();
    // [
    // { name: "iPhone 6", brand: "Apple", type: "phone" },
    // { name: "iPhone 5", brand: "Apple", type: "phone" },
    // { name: "Galaxy S6", brand: "Samsung", type: "phone" },
    // ]
  • The first method returns the first item in the collection that passes predicateFn . By default it will get the first item. If the collection is empty or no items passes predicateFn than null i returned.

    Type Parameters

    • TOutput

    Parameters

    Returns Promise<null | TOutput>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.first();
    // 1
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.first(item => item > 2);
    // 3
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.first(item => item > 10);
    // null
  • The firstOr method returns the first item in the collection that passes predicateFn By default it will get the first item. If the collection is empty or no items passes predicateFn than defaultValue .

    Type Parameters

    Parameters

    Returns Promise<TOutput | TExtended>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.firstOr(-1);
    // 1
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.firstOr(-1, item => item > 2);
    // 3
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.firstOr(-1, item => item > 10);
    // -1
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.firstOr(() => -1, item => item > 10);
    // -1
  • The firstOrFail method returns the first item in the collection that passes predicateFn . By default it will get the first item. If the collection is empty or no items passes predicateFn than error is thrown.

    Type Parameters

    • TOutput

    Parameters

    Returns Promise<TOutput>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.firstOrFail();
    // 1
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.firstOrFail(item => item > 2);
    // 3
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.firstOrFail(item => item > 10);
    // throws an error
  • The groupBy method groups the collection's items by selectFn . By default the equality check occurs on the item.

    Type Parameters

    Parameters

    Returns IAsyncCollection<RecordItem<TOutput, IAsyncCollection<TInput>>>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection(["a", "a", "a", "b", "b", "c"]);
    const group = await collection
    .groupBy()
    .map(([key, collection]) => [key, collection.toArray()])
    .toArray();
    // [
    // [
    // "a",
    // ["a", "a", "a"]
    // ],
    // [
    // "b",
    // ["b", "b"]
    // ],
    // [
    // "c",
    // ["c"]
    // ]
    // ]
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection(["alice@gmail.com", "bob@yahoo.com", "carlos@gmail.com"]);
    const group = await collection
    .groupBy(item => item.split("@")[1])
    .map(([key, collection]) => [key, collection.toArray()])
    .toArray();
    // [
    // [
    // "gmail.com",
    // ["alice@gmail.com", "carlos@gmail.com"]
    // ],
    // [
    // "yahoo.com",
    // ["bob@yahoo.com"]
    // ]
    // ]
  • The join method joins the collection's items with separator . An error will be thrown when if a none string item is encounterd.

    Parameters

    • separator: string = ","

    Returns Promise<EnsureType<TInput, string>>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.map(item => item.toString()).join();
    // "1,2,3,4"
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.map(item => item.toString()).join("_");
    // "1_2_3_4"
  • The last method returns the last item in the collection that passes predicateFn . By default it will get the last item. If the collection is empty or no items passes predicateFn than null i returned.

    Type Parameters

    • TOutput

    Parameters

    Returns Promise<null | TOutput>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.last();
    // 4
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.last(item => item < 4);
    // 3
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.last(item => item > 10);
    // null
  • The lastOr method returns the last item in the collection that passes predicateFn . By default it will get the last item. If the collection is empty or no items passes predicateFn than defaultValue .

    Type Parameters

    Parameters

    Returns Promise<TOutput | TExtended>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.lastOr(-1);
    // 4
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.lastOr(-1, item => item < 4);
    // 3
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.lastOr(-1, item => item > 10);
    // -1
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.lastOr(() => -1, item => item > 10);
    // -1
  • The lastOrFail method returns the last item in the collection that passes predicateFn . By default it will get the last item. If the collection is empty or no items passes predicateFn than error is thrown.

    Type Parameters

    • TOutput

    Parameters

    Returns Promise<TOutput>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.lastOrFail();
    // 4
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.lastOrFail(item => item < 4);
    // 3
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4]);
    await collection.lastOrFail(item => item > 10);
    // throws an error
  • The padEnd method pads this collection with fillItems until the resulting collection size reaches maxLength. The padding is applied from the end of this collection.

    Type Parameters

    Parameters

    Returns IAsyncCollection<TInput | TExtended>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    await new AsyncIterableCollection("abc").padEnd(10, "foo").join("");
    // "abcfoofoof"

    await new AsyncIterableCollection("abc").padEnd(6, "123465").join("");
    // "abc123"

    await new AsyncIterableCollection("abc").padEnd(8, "0").join("");
    // "abc00000"

    await new AsyncIterableCollection("abc").padEnd(1, "_").join("");
    // "abc"
  • The padStart method pads this collection with fillItems until the resulting collection size reaches maxLength. The padding is applied from the start of this collection.

    Type Parameters

    Parameters

    Returns IAsyncCollection<TInput | TExtended>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    await new AsyncIterableCollection("abc").padStart(10, "foo").join("");
    // "foofoofabc"

    await new AsyncIterableCollection("abc").padStart(6, "123465").join("");
    // "123abc"

    await new AsyncIterableCollection("abc").padStart(8, "0").join("");
    // "00000abc"

    await new AsyncIterableCollection("abc").padStart(1, "_").join("");
    // "abc"
  • The pipe method passes the orignal collection to callback and returns the result from callback. This method is useful when you want compose multiple smaller functions.

    Type Parameters

    Returns Promise<TOutput>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, "2", "a", 1, 3, {}]);
    function toNbrs<TInput>(
    collection: IAsyncCollection<TInput>,
    ): IAsyncCollection<number> {
    return collection
    .map((item) => Number(item))
    .reject((nbr) => Number.isNaN(nbr));
    }
    function nbrToStr(collection: IAsyncCollection<number>): number[] {
    return collection.repeat(2).toArray();
    }
    const piped = await collection.pipe(toNbrs).then(nbrToStr);
    console.log(piped);
    // [ 1, 2, 1, 3 ]
  • The slice method creates porition of the original collection selected from start and end where start and end (end not included) represent the index of items in the collection.

    Parameters

    • Optionalstart: number
    • Optionalend: number

    Returns IAsyncCollection<TInput>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection(["a", "b", "c", "d", "e", "f"]);
    await collection.slice(3).toArray();
    // ["d", "e", "f"]
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection(["a", "b", "c", "d", "e", "f"]);
    await collection.slice(undefined, 2).toArray();
    // ["a", "b"]
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection(["a", "b", "c", "d", "e", "f"]);
    await collection.slice(2, 5).toArray();
    // ["c", "d", "e"]
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection(["a", "b", "c", "d", "e", "f"]);
    await collection.slice(-2).toArray();
    // ["e", "f"]
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection(["a", "b", "c", "d", "e", "f"]);
    await collection.slice(undefined, -2).toArray();
    // ["a", "b", "c", "d"]
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection(["a", "b", "c", "d", "e", "f"]);
    await collection.slice(-4, -2).toArray();
    // ["c", "d"]
  • The sort method sorts the collection. You can provide a comparator function.

    Parameters

    Returns IAsyncCollection<TInput>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([-1, 2, 4, 3]);
    await collection.sort().toArray();
    // [-1, 2, 3, 4]
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([
    { name: "Anders", age: 30 },
    { name: "Joe", age: 20 },
    { name: "Hasan", age: 25 },
    { name: "Linda", age: 19 }
    ]);
    await collection.sort(({ age: ageA }, { age: ageB }) => ageA - ageB).toArray();
    // [
    // { name: "Linda", age: 19 }
    // { name: "Joe", age: 20 },
    // { name: "Hasan", age: 25 },
    // { name: "Anders", age: 30 },
    // ]
  • The split method breaks a collection evenly into chunkAmount of chunks.

    Parameters

    • chunkAmount: number

    Returns IAsyncCollection<IAsyncCollection<TInput>>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4, 5]);
    const chunks = collection.split(3);
    await chunks.map(chunk => chunk.toArray()).toArray();
    // [[1, 2], [3, 4], [5]]
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4, 5, 6]);
    const chunks = collection.split(3);
    await chunks.map(chunk => chunk.toArray()).toArray();
    // [[1, 2], [3, 4], [5, 6]]
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 2, 3, 4, 5, 6, 7]);
    const chunks = collection.split(3);
    await chunks.map(chunk => chunk.toArray()).toArray();
    // [[1, 2, 7], [3, 4], [5, 6]]
  • The take method takes the first limit items.

    Parameters

    • limit: number

    Returns IAsyncCollection<TInput>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([0, 1, 2, 3, 4, 5]);
    const chunk = collection.take(3);
    await chunk.toArray();
    // [0, 1, 2]
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([0, 1, 2, 3, 4, 5]);
    const chunk = collection.take(-2);
    await chunk.toArray();
    // [0, 1, 2, 3]
  • The timeout method returns a new collection that will iterate values until the specified time. After that time, the collection will then stop iterating:

    Parameters

    • timeInMs: number

    Returns IAsyncCollection<TInput>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    class AsyncInfiniteIterable implements AsyncIterable<number> {
    async *[Symbol.asyncIterator]() {
    while(true) {
    yield 1;
    }
    }
    }
    const asyncInfiniteIterable = new AsyncInfiniteIterable();
    const collection = new AsyncIterableCollection(asyncInfiniteIterable);
    await collection
    .timeout(1000)
    .forEach(nbr => console.log(nbr))
  • The unique method removes all duplicate values from the collection by selectFn . By default the equality check occurs on the item.

    Type Parameters

    Parameters

    Returns IAsyncCollection<TInput>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([1, 1, 2, 2, 3, 4, 2]);
    await collection.unique().toArray();
    // [1, 2, 3, 4]
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection([
    { name: "iPhone 6", brand: "Apple", type: "phone" },
    { name: "iPhone 5", brand: "Apple", type: "phone" },
    { name: "Apple Watch", brand: "Apple", type: "watch" },
    { name: "Galaxy S6", brand: "Samsung", type: "phone" },
    { name: "Galaxy Gear", brand: "Samsung", type: "watch" },
    ]);
    const unique = await collection.unique({
    selectFn: item => item.brand
    }).toArray();
    // [
    // { name: "iPhone 6", brand: "Apple", type: "phone" },
    // { name: "Galaxy S6", brand: "Samsung", type: "phone" },
    // ]
  • The zip method merges together the values of iterable with the values of the collection at their corresponding index. The returned collection has size of the shortest collection.

    Type Parameters

    • TExtended

    Parameters

    Returns IAsyncCollection<RecordItem<TInput, TExtended>>

    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection(["Chair", "Desk"]);
    const zipped = collection.zip([100, 200]);
    await zipped.toArray();
    // [["Chair", 100], ["Desk", 200]]
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection(["Chair", "Desk", "Couch"]);
    const zipped = collection.zip([100, 200]);
    await zipped.toArray();
    // [["Chair", 100], ["Desk", 200]]
    import { AsyncIterableCollection } from "@daiso-tech/core";;

    const collection = new AsyncIterableCollection(["Chair", "Desk"]);
    const zipped = collection.zip([100, 200, 300]);
    await zipped.toArray();
    // [["Chair", 100], ["Desk", 200]]