@daiso-tech/core
Version:
The library offers flexible, framework-agnostic solutions for modern web applications, built on adaptable components that integrate seamlessly with popular frameworks like Next Js.
283 lines (282 loc) • 16 kB
TypeScript
/**
* @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 { AsyncLazy, Factory } from "../../../utilities/_module-exports.js";
import { LazyPromise } from "../../../async/_module-exports.js";
/**
*
* IMPORT_PATH: `"@daiso-tech/core/collection"`
* @group Adapters
*/
export type AsyncIterableCollectionSettings = {
lazyPromiseFactory?: Factory<AsyncLazy<any>, LazyPromise<any>>;
};
/**
* All methods that return {@link IAsyncCollection | `IAsyncCollection`} are executed lazly, meaning the execution will occur iterating the items withthe `forEach` method or `for await` loop.
*
* IMPORT_PATH: `"@daiso-tech/core/collection"`
* @group Adapters
*/
export declare class AsyncIterableCollection<TInput = unknown> implements IAsyncCollection<TInput> {
private readonly iterable;
/**
* The `concat` static method is a convenient utility for easily concatenating multiple {@link Iterable | `Iterable`} or {@link AsyncIterable | `AsyncIterable`}.
* @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 `difference` static method is used to compute the difference between two {@link Iterable | `Iterable`} 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 `zip` static method merges together the values of `iterableA` with the values of the `iterableB` 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 makeCollection;
private readonly lazyPromiseFactory;
/**
* The `constructor` takes an {@link Iterable | `Iterable`} or {@link AsyncIterable | `AsyncIterable`}.
*
* Works with `Array`.
* @example
* ```ts
* import { AsyncIterableCollection } from "@daiso-tech/core";
*
* const collection = new AsyncIterableCollection([1, 2, 3, 4]);
* ```
*
* Works with `String`.
* @example
* ```ts
* import { AsyncIterableCollection } from "@daiso-tech/core";
*
* const collection = new AsyncIterableCollection("ABCDE");
* ```
*
* Works with `Set`.
* @example
* ```ts
* import { AsyncIterableCollection } from "@daiso-tech/core";
*
* const collection = new AsyncIterableCollection(new Set([1, 2, 2 4]));
* ```
*
* Works with `Map`.
* @example
* ```ts
* import { AsyncIterableCollection } from "@daiso-tech/core";
*
* const collection = new AsyncIterableCollection(new Map([["a", 1], ["b", 2]]));
* ```
*
* Works with any `Iterable`.
* @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 `AsyncIterable`.
* @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(reduce: AsyncReduce<TInput, IAsyncCollection<TInput>, TInput>): LazyPromise<TInput>;
reduce(reduce: AsyncReduce<TInput, IAsyncCollection<TInput>, TInput>, initialValue: TInput): LazyPromise<TInput>;
reduce<TOutput>(reduce: 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>;
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>>;
}