@daiso-tech/core 0.22.2 → 0.24.0

package/dist/collection/implementations/async-iterable-collection/async-iterable-collection.d.ts

@@ -0,0 +1,305 @@
+/**
+ * @module Collection
+ */
+import type { EnsureMap, EnsureRecord } from "../../../collection/contracts/_module-exports.js";
+import { type AsyncCollapse, type AsyncPredicate, type AsyncForEach, type AsyncMap, type AsyncModifier, type AsyncTap, type AsyncTransform, type Comparator, type IAsyncCollection, type AsyncReduce, type CrossJoinResult } from "../../../collection/contracts/_module-exports.js";
+import { type AsyncIterableValue, type AsyncLazyable } from "../../../utilities/_module-exports.js";
+import type { TimeSpan } from "../../../utilities/_module-exports.js";
+import type { BackoffPolicy, RetryPolicy } from "../../../async/_module-exports.js";
+import { LazyPromise } from "../../../async/_module-exports.js";
+/**
+ *
+ * IMPORT_PATH: ```"@daiso-tech/core/collection/implementations"```
+ * @group Adapters
+ */
+export type AsyncIterableCollectionSettings = {
+    /**
+     * The default retry attempt to use in the returned <i>LazyPromise</i>.
+     */
+    retryAttempts?: number | null;
+    /**
+     * The default backof policy to use in the returned <i>LazyPromise</i>.
+     */
+    backoffPolicy?: BackoffPolicy | null;
+    /**
+     * The default retry policy to use in the returned <i>LazyPromise</i>.
+     */
+    retryPolicy?: RetryPolicy | null;
+    /**
+     * The default timeout to use in the returned <i>LazyPromise</i>.
+     */
+    timeout?: TimeSpan | null;
+};
+/**
+ * All methods that return <i>{@link IAsyncCollection}</i> are executed lazly.
+ * The methods that return <i>{@link IAsyncCollection}</i> will only be executed when <i>forEach</i> method is called or <i>for await</i> loop.
+ * The methods that return <i>{@link PromiseLike}</i> object will execute only when awaited or <i>then</i> method is called.
+ * @group Adapters
+ */
+export declare class AsyncIterableCollection<TInput = unknown> implements IAsyncCollection<TInput> {
+    private readonly iterable;
+    /**
+     * The <i>concat<i> static method is a convenient utility for easily concatenating multiple <i>{@link Iterable}</i> or <i>{@link AsyncIterable}</i>.
+     * @example
+     * ```ts
+     * import { AsyncIterableCollection } from "@daiso-tech/core";
+     *
+     * class MyAsyncIterable implements AsyncIterable<number> {
+     *   async *[Symbol.iterator](): Iterator<number> {
+     *     yield "a";
+     *     yield "b";
+     *     yield "c";
+     *   }
+     * }
+     *
+     * class MyIterable implements Iterable<number> {
+     *   *[Symbol.iterator](): Iterator<number> {
+     *     yield 1;
+     *     yield 2;
+     *     yield 3;
+     *   }
+     * }
+     *
+     * const collection = AsyncIterableCollection.concat([
+     *   new MyAsyncIterable(),
+     *   new MyIterable(),
+     *   new Set([1, 2, 3]),
+     *   new Map([["a", 1], ["b", 2]]),
+     *   ["a", "b", "c"]
+     * ]);
+     * await collection.toArray();
+     * // ["a", "b", "c", 1, 2, 3, 1, 2, 3, ["a", 1], ["b", 2], "a", "b", "c"]
+     * ```
+     */
+    static concat<TValue>(iterables: AsyncIterableValue<AsyncIterableValue<TValue>>): IAsyncCollection<TValue>;
+    /**
+     * The <i>difference</i> static method is used to compute the difference between two <i>{@link Iterable}</i> instances. By default, the equality check is performed on each item.
+     * @example
+     * ```ts
+     * import { AsyncIterableCollection } from "@daiso-tech/core";
+     *
+     * const collection = AsyncIterableCollection.difference(
+     *   [1, 2, 2, 3, 4, 5],
+     *   [2, 4, 6, 8]
+     * );
+     * await collection.toArray();
+     * // [1, 3, 5]
+     * ```
+     * @example
+     * ```ts
+     * import { AsyncIterableCollection } from "@daiso-tech/core";
+     *
+     * const collection = AsyncIterableCollection.difference(
+     *   [
+     *     { 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" },
+     *   ],
+     *   [
+     *     { name: "Apple Watch", brand: "Apple", type: "watch" },
+     *   ],
+     *   (product) => product.type
+     * );
+     * await collection.toArray();
+     * // [
+     * //   { name: "iPhone 6", brand: "Apple", type: "phone" },
+     * //   { name: "iPhone 5", brand: "Apple", type: "phone" },
+     * //   { name: "Galaxy S6", brand: "Samsung", type: "phone" },
+     * // ]
+     * ```
+     */
+    static difference<TValue, TSelect>(iterableA: AsyncIterableValue<TValue>, iterableB: AsyncIterableValue<TValue>, selectFn?: AsyncMap<TValue, IAsyncCollection<TValue>, TSelect>): IAsyncCollection<TValue>;
+    /**
+     * The <i>zip</i> static method merges together the values of <i>iterableA</i> with the values of the <i>iterableB</i> at their corresponding index.
+     * The returned collection has size of the shortest collection.
+     * @example
+     * ```ts
+     * import { AsyncIterableCollection } from "@daiso-tech/core";;
+     *
+     * const collection = AsyncIterableCollection.zip(["Chair", "Desk"], [100, 200]);
+     * await collection.toArray();
+     * // [["Chair", 100], ["Desk", 200]]
+     * ```
+     * @example
+     * ```ts
+     * import { AsyncIterableCollection } from "@daiso-tech/core";;
+     *
+     * const collection = AsyncIterableCollection.zip(["Chair", "Desk", "Couch"], [100, 200]);
+     * await collection.toArray();
+     * // [["Chair", 100], ["Desk", 200]]
+     * ```
+     * @example
+     * ```ts
+     * import { AsyncIterableCollection } from "@daiso-tech/core";;
+     *
+     * const collection = AsyncIterableCollection.zip(["Chair", "Desk"], [100, 200, 300]);
+     * await collection.toArray();
+     * // [["Chair", 100], ["Desk", 200]]
+     * ```
+     */
+    static zip<TValueA, TValueB>(iterableA: AsyncIterableValue<TValueA>, iterableB: AsyncIterableValue<TValueB>): IAsyncCollection<[TValueA, TValueB]>;
+    private static DEFAULT_CHUNK_SIZE;
+    private static defaultRetryPolicy;
+    private static makeCollection;
+    private readonly retryAttempts;
+    private readonly backoffPolicy;
+    private readonly retryPolicy;
+    private readonly timeout;
+    /**
+     * The <i>constructor</i> takes an <i>{@link Iterable}</i> or <i>{@link AsyncIterable}</i>.
+     *
+     * Works with <i>Array</i>.
+     * @example
+     * ```ts
+     * import { AsyncIterableCollection } from "@daiso-tech/core";
+     *
+     * const collection = new AsyncIterableCollection([1, 2, 3, 4]);
+     * ```
+     *
+     * Works with <i>String</i>.
+     * @example
+     * ```ts
+     * import { AsyncIterableCollection } from "@daiso-tech/core";
+     *
+     * const collection = new AsyncIterableCollection("ABCDE");
+     * ```
+     *
+     * Works with <i>Set</i>.
+     * @example
+     * ```ts
+     * import { AsyncIterableCollection } from "@daiso-tech/core";
+     *
+     * const collection = new AsyncIterableCollection(new Set([1, 2, 2 4]));
+     * ```
+     *
+     * Works with <i>Map</i>.
+     * @example
+     * ```ts
+     * import { AsyncIterableCollection } from "@daiso-tech/core";
+     *
+     * const collection = new AsyncIterableCollection(new Map([["a", 1], ["b", 2]]));
+     * ```
+     *
+     * Works with any <i>Iterable</i>.
+     * @example
+     * ```ts
+     * import { AsyncIterableCollection } from "@daiso-tech/core";
+     *
+     * class MyIterable implements Iterable<number> {
+     *   *[Symbol.iterator](): Iterator<number> {
+     *     yield 1;
+     *     yield 2;
+     *     yield 3;
+     *   }
+     * }
+     * const collection = new AsyncIterableCollection(new MyIterable());
+     * ```
+     *
+     * Works with any <i>AsyncIterable</i>.
+     * @example
+     * ```ts
+     * import { AsyncIterableCollection } from "@daiso-tech/core";
+     *
+     * class MyIterable implements AsyncIterable<number> {
+     *   async *[Symbol.iterator](): Iterator<number> {
+     *     yield 1;
+     *     yield 2;
+     *     yield 3;
+     *   }
+     * }
+     * const collection = new AsyncIterableCollection(new MyIterable());
+     * ```
+     */
+    constructor(iterable?: AsyncIterableValue<TInput>, settings?: AsyncIterableCollectionSettings);
+    private createLazyPromise;
+    [Symbol.asyncIterator](): AsyncIterator<TInput>;
+    toIterator(): AsyncIterator<TInput, void>;
+    entries(): IAsyncCollection<[number, TInput]>;
+    keys(): IAsyncCollection<number>;
+    values(): IAsyncCollection<TInput>;
+    filter<TOutput extends TInput>(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>, TOutput>): IAsyncCollection<TOutput>;
+    reject<TOutput extends TInput>(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>, TOutput>): IAsyncCollection<Exclude<TInput, TOutput>>;
+    map<TOutput>(mapFn: AsyncMap<TInput, IAsyncCollection<TInput>, TOutput>): IAsyncCollection<TOutput>;
+    reduce(reduceFn: AsyncReduce<TInput, IAsyncCollection<TInput>, TInput>): LazyPromise<TInput>;
+    reduce(reduceFn: AsyncReduce<TInput, IAsyncCollection<TInput>, TInput>, initialValue: TInput): LazyPromise<TInput>;
+    reduce<TOutput>(reduceFn: AsyncReduce<TInput, IAsyncCollection<TInput>, TOutput>, initialValue: TOutput): LazyPromise<TOutput>;
+    join(separator?: string): LazyPromise<Extract<TInput, string>>;
+    collapse(): IAsyncCollection<AsyncCollapse<TInput>>;
+    flatMap<TOutput>(mapFn: AsyncMap<TInput, IAsyncCollection<TInput>, Iterable<TOutput>>): IAsyncCollection<TOutput>;
+    change<TFilterOutput extends TInput, TMapOutput>(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>, TFilterOutput>, mapFn: AsyncMap<TFilterOutput, IAsyncCollection<TInput>, TMapOutput>): IAsyncCollection<TInput | TFilterOutput | TMapOutput>;
+    set(index: number, value: TInput | AsyncMap<TInput, IAsyncCollection<TInput>, TInput>): IAsyncCollection<TInput>;
+    get(index: number): LazyPromise<TInput | null>;
+    getOrFail(index: number): LazyPromise<TInput>;
+    page(page: number, pageSize: number): IAsyncCollection<TInput>;
+    sum(): LazyPromise<Extract<TInput, number>>;
+    average(): LazyPromise<Extract<TInput, number>>;
+    median(): LazyPromise<Extract<TInput, number>>;
+    min(): LazyPromise<Extract<TInput, number>>;
+    max(): LazyPromise<Extract<TInput, number>>;
+    percentage(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): LazyPromise<number>;
+    some<TOutput extends TInput>(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>, TOutput>): LazyPromise<boolean>;
+    every<TOutput extends TInput>(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>, TOutput>): LazyPromise<boolean>;
+    take(limit: number): IAsyncCollection<TInput>;
+    takeUntil(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): IAsyncCollection<TInput>;
+    takeWhile(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): IAsyncCollection<TInput>;
+    skip(offset: number): IAsyncCollection<TInput>;
+    skipUntil(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): IAsyncCollection<TInput>;
+    skipWhile(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): IAsyncCollection<TInput>;
+    when<TExtended = TInput>(condition: boolean, callback: AsyncModifier<IAsyncCollection<TInput>, IAsyncCollection<TExtended>>): IAsyncCollection<TInput | TExtended>;
+    whenEmpty<TExtended = TInput>(callback: AsyncModifier<IAsyncCollection<TInput>, IAsyncCollection<TExtended>>): IAsyncCollection<TInput | TExtended>;
+    whenNot<TExtended = TInput>(condition: boolean, callback: AsyncModifier<IAsyncCollection<TInput>, IAsyncCollection<TExtended>>): IAsyncCollection<TInput | TExtended>;
+    whenNotEmpty<TExtended = TInput>(callback: AsyncModifier<IAsyncCollection<TInput>, IAsyncCollection<TExtended>>): IAsyncCollection<TInput | TExtended>;
+    pipe<TOutput = TInput>(callback: AsyncTransform<IAsyncCollection<TInput>, TOutput>): LazyPromise<TOutput>;
+    tap(callback: AsyncTap<IAsyncCollection<TInput>>): IAsyncCollection<TInput>;
+    chunk(chunkSize: number): IAsyncCollection<IAsyncCollection<TInput>>;
+    chunkWhile(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): IAsyncCollection<IAsyncCollection<TInput>>;
+    split(chunkAmount: number): IAsyncCollection<IAsyncCollection<TInput>>;
+    partition(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): IAsyncCollection<IAsyncCollection<TInput>>;
+    sliding(chunkSize: number, step?: number): IAsyncCollection<IAsyncCollection<TInput>>;
+    groupBy<TOutput = TInput>(selectFn?: AsyncMap<TInput, IAsyncCollection<TInput>, TOutput>): IAsyncCollection<[TOutput, IAsyncCollection<TInput>]>;
+    countBy<TOutput = TInput>(selectFn?: AsyncMap<TInput, IAsyncCollection<TInput>, TOutput>): IAsyncCollection<[TOutput, number]>;
+    unique<TOutput = TInput>(selectFn?: AsyncMap<TInput, IAsyncCollection<TInput>, TOutput>): IAsyncCollection<TInput>;
+    difference<TOutput = TInput>(iterable: AsyncIterableValue<TInput>, selectFn?: AsyncMap<TInput, IAsyncCollection<TInput>, TOutput>): IAsyncCollection<TInput>;
+    repeat(amount: number): IAsyncCollection<TInput>;
+    padStart<TExtended = TInput>(maxLength: number, fillItems: AsyncIterableValue<TExtended>): IAsyncCollection<TInput | TExtended>;
+    padEnd<TExtended = TInput>(maxLength: number, fillItems: AsyncIterableValue<TExtended>): IAsyncCollection<TInput | TExtended>;
+    slice(start?: number, end?: number): IAsyncCollection<TInput>;
+    prepend<TExtended = TInput>(iterable: AsyncIterableValue<TInput | TExtended>): IAsyncCollection<TInput | TExtended>;
+    append<TExtended = TInput>(iterable: AsyncIterableValue<TInput | TExtended>): IAsyncCollection<TInput | TExtended>;
+    insertBefore<TExtended = TInput>(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>, iterable: AsyncIterableValue<TInput | TExtended>): IAsyncCollection<TInput | TExtended>;
+    insertAfter<TExtended = TInput>(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>, iterable: AsyncIterableValue<TInput | TExtended>): IAsyncCollection<TInput | TExtended>;
+    crossJoin<TExtended>(iterable: AsyncIterableValue<TExtended>): IAsyncCollection<CrossJoinResult<TInput, TExtended>>;
+    zip<TExtended>(iterable: AsyncIterableValue<TExtended>): IAsyncCollection<[TInput, TExtended]>;
+    sort(comparator?: Comparator<TInput>): IAsyncCollection<TInput>;
+    reverse(chunkSize?: number): IAsyncCollection<TInput>;
+    shuffle(mathRandom?: () => number): IAsyncCollection<TInput>;
+    first<TOutput extends TInput>(predicateFn?: AsyncPredicate<TInput, IAsyncCollection<TInput>, TOutput>): LazyPromise<TOutput | null>;
+    firstOr<TOutput extends TInput, TExtended = TInput>(defaultValue: AsyncLazyable<TExtended>, predicateFn?: AsyncPredicate<TInput, IAsyncCollection<TInput>, TOutput>): LazyPromise<TOutput | TExtended>;
+    firstOrFail<TOutput extends TInput>(predicateFn?: AsyncPredicate<TInput, IAsyncCollection<TInput>, TOutput>): LazyPromise<TOutput>;
+    last<TOutput extends TInput>(predicateFn?: AsyncPredicate<TInput, IAsyncCollection<TInput>, TOutput>): LazyPromise<TOutput | null>;
+    lastOr<TOutput extends TInput, TExtended = TInput>(defaultValue: AsyncLazyable<TExtended>, predicateFn?: AsyncPredicate<TInput, IAsyncCollection<TInput>, TOutput>): LazyPromise<TOutput | TExtended>;
+    lastOrFail<TOutput extends TInput>(predicateFn?: AsyncPredicate<TInput, IAsyncCollection<TInput>, TOutput>): LazyPromise<TOutput>;
+    before(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): LazyPromise<TInput | null>;
+    beforeOr<TExtended = TInput>(defaultValue: AsyncLazyable<TExtended>, predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): LazyPromise<TInput | TExtended>;
+    beforeOrFail(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): LazyPromise<TInput>;
+    after(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): LazyPromise<TInput | null>;
+    afterOr<TExtended = TInput>(defaultValue: AsyncLazyable<TExtended>, predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): LazyPromise<TInput | TExtended>;
+    afterOrFail(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): LazyPromise<TInput>;
+    sole<TOutput extends TInput>(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>, TOutput>): LazyPromise<TOutput>;
+    nth(step: number): IAsyncCollection<TInput>;
+    delay(time: TimeSpan): IAsyncCollection<TInput>;
+    takeUntilAbort(abortSignal: AbortSignal): IAsyncCollection<TInput>;
+    takeUntilTimeout(time: TimeSpan): IAsyncCollection<TInput>;
+    count(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): LazyPromise<number>;
+    size(): LazyPromise<number>;
+    isEmpty(): LazyPromise<boolean>;
+    isNotEmpty(): LazyPromise<boolean>;
+    searchFirst(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): LazyPromise<number>;
+    searchLast(predicateFn: AsyncPredicate<TInput, IAsyncCollection<TInput>>): LazyPromise<number>;
+    forEach(callback: AsyncForEach<TInput, IAsyncCollection<TInput>>): LazyPromise<void>;
+    toArray(): LazyPromise<TInput[]>;
+    toRecord(): LazyPromise<EnsureRecord<TInput>>;
+    toMap(): LazyPromise<EnsureMap<TInput>>;
+}