@anil-labs/collection-js 0.1.0

package/dist/src/collection/LazyCollection.d.ts

@@ -0,0 +1,173 @@
+import { Enumerable } from '../../contracts/Enumerable';
+import { MacroableTarget } from '../../macros/Macroable';
+import { ClassConstructor, Comparator, Predicate } from '../../support/types';
+import { RetrieverInput } from '../../support/valueRetriever';
+import { Collection } from '../../collection/Collection';
+import * as ops from '@/operations';
+export type LazySource<T> = Iterable<T> | (() => Iterable<T>);
+/**
+ * Lazy generator-backed collection. Mirrors Laravel's `LazyCollection`.
+ * The same fluent surface as `Collection`, but every method that returns a new
+ * collection returns a `LazyCollection` over a generator — values are produced
+ * on demand. Mutating methods (push/pop/etc.) are intentionally absent.
+ */
+export declare class LazyCollection<T> implements Enumerable<T> {
+    private readonly source;
+    constructor(source?: LazySource<T>);
+    [Symbol.iterator](): Iterator<T>;
+    get [Symbol.toStringTag](): string;
+    static make<T>(source?: LazySource<T>): LazyCollection<T>;
+    static empty<T>(): LazyCollection<T>;
+    static range(start: number, end: number, step?: number): LazyCollection<number>;
+    static times<T>(count: number, factory: (n: number) => T): LazyCollection<T>;
+    static wrap<T>(value: T | T[] | Iterable<T> | LazyCollection<T> | null | undefined): LazyCollection<T>;
+    static unwrap<T>(value: T | T[] | LazyCollection<T>): T | T[];
+    all(): T[];
+    toArray(): T[];
+    toJson(): string;
+    toJSON(): T[];
+    toMap<K, V>(keyFn: (item: T, i: number) => K, valueFn: (item: T, i: number) => V): Map<K, V>;
+    toSet(): Set<T>;
+    collect(): Collection<T>;
+    count(): number;
+    isEmpty(): boolean;
+    isNotEmpty(): boolean;
+    countBy(by?: RetrieverInput<T>): Record<string, number>;
+    first(predicate?: Predicate<T>): T | undefined;
+    firstOrFail(predicate?: Predicate<T>): T;
+    firstWhere(key: string, ...rest: readonly unknown[]): T | undefined;
+    last(predicate?: Predicate<T>): T | undefined;
+    sole(predicate?: Predicate<T> | string, expected?: unknown): T;
+    random(): T | undefined;
+    contains(target: unknown, ...rest: readonly unknown[]): boolean;
+    containsStrict(target: unknown, ...rest: readonly unknown[]): boolean;
+    doesntContain(target: unknown, ...rest: readonly unknown[]): boolean;
+    every(predicate: Predicate<T>): boolean;
+    some(predicate: Predicate<T>): boolean;
+    search(target: T | Predicate<T>, strict?: boolean): number | false;
+    has(key: string | readonly string[]): boolean;
+    sum(by?: RetrieverInput<T, number>): number;
+    average(by?: RetrieverInput<T, number>): number;
+    avg(by?: RetrieverInput<T, number>): number;
+    max<R = number>(by?: RetrieverInput<T, R>): R | undefined;
+    min<R = number>(by?: RetrieverInput<T, R>): R | undefined;
+    median(by?: RetrieverInput<T, number>): number | undefined;
+    mode(by?: RetrieverInput<T>): unknown[] | undefined;
+    percentage(predicate: Predicate<T>, precision?: number): number;
+    filter(predicate?: Predicate<T>): LazyCollection<T>;
+    reject(predicate: Predicate<T>): LazyCollection<T>;
+    where(key: string, ...rest: readonly unknown[]): LazyCollection<T>;
+    whereStrict(key: string, value: unknown): LazyCollection<T>;
+    whereIn(key: string, values: readonly unknown[]): LazyCollection<T>;
+    whereInStrict(key: string, values: readonly unknown[]): LazyCollection<T>;
+    whereNotIn(key: string, values: readonly unknown[]): LazyCollection<T>;
+    whereNotInStrict(key: string, values: readonly unknown[]): LazyCollection<T>;
+    /** Shared engine for the four whereIn/whereNotIn variants. */
+    private whereInFilter;
+    whereBetween(key: string, range: readonly [unknown, unknown]): LazyCollection<T>;
+    whereNotBetween(key: string, range: readonly [unknown, unknown]): LazyCollection<T>;
+    whereNull(key: string): LazyCollection<T>;
+    whereNotNull(key: string): LazyCollection<T>;
+    /** Lazy SQL-`LIKE` filter (`%` = any run, `_` = single char). See {@link Collection.whereLike}. */
+    whereLike(key: string, pattern: string, caseSensitive?: boolean): LazyCollection<T>;
+    /** Inverse of {@link whereLike}. */
+    whereNotLike(key: string, pattern: string, caseSensitive?: boolean): LazyCollection<T>;
+    whereInstanceOf<R>(Ctor: ClassConstructor<R> | (abstract new (...args: never[]) => R)): LazyCollection<R>;
+    map<R>(fn: (item: T, index: number) => R): LazyCollection<R>;
+    mapInto<R>(Ctor: ClassConstructor<R, [T]>): LazyCollection<R>;
+    mapSpread<R>(fn: (...args: T extends readonly unknown[] ? T : never) => R): LazyCollection<R>;
+    mapWithKeys<K extends PropertyKey, V>(fn: (item: T, index: number) => readonly [K, V]): Record<K, V>;
+    mapToGroups<K extends PropertyKey, V>(fn: (item: T, index: number) => readonly [K, V]): Record<K, V[]>;
+    flatMap<R>(fn: (item: T, index: number) => R | readonly R[]): LazyCollection<R>;
+    flatten(depth?: number): LazyCollection<unknown>;
+    collapse<U>(this: LazyCollection<readonly U[] | U>): LazyCollection<U>;
+    pluck(key: string): LazyCollection<unknown>;
+    pluck(key: string, keyBy: string): Record<string, unknown>;
+    take(count: number): LazyCollection<T>;
+    takeUntil(target: T | Predicate<T>): LazyCollection<T>;
+    takeWhile(predicate: Predicate<T>): LazyCollection<T>;
+    skip(count: number): LazyCollection<T>;
+    skipUntil(target: T | Predicate<T>): LazyCollection<T>;
+    skipWhile(predicate: Predicate<T>): LazyCollection<T>;
+    slice(start: number, length?: number): LazyCollection<T>;
+    forPage(page: number, perPage: number): LazyCollection<T>;
+    nth(step: number, offset?: number): LazyCollection<T>;
+    chunk(size: number): LazyCollection<LazyCollection<T>>;
+    chunkWhile(predicate: (item: T, key: number, chunk: readonly T[]) => boolean): LazyCollection<LazyCollection<T>>;
+    partition(predicate: Predicate<T>): [LazyCollection<T>, LazyCollection<T>];
+    groupBy(by: RetrieverInput<T, PropertyKey | readonly PropertyKey[]>): Record<PropertyKey, T[]>;
+    keyBy(by: RetrieverInput<T, PropertyKey>): Record<PropertyKey, T>;
+    split(groups: number): LazyCollection<LazyCollection<T>>;
+    splitIn(groups: number): LazyCollection<LazyCollection<T>>;
+    sort(comparator?: Comparator<T>): LazyCollection<T>;
+    sortDesc(): LazyCollection<T>;
+    sortBy(spec: ops.SortBySpec<T> | readonly ops.SortBySpec<T>[]): LazyCollection<T>;
+    sortByDesc(spec: ops.SortBySpec<T>): LazyCollection<T>;
+    sortKeys(): LazyCollection<T>;
+    sortKeysDesc(): LazyCollection<T>;
+    reverse(): LazyCollection<T>;
+    shuffle(random?: () => number): LazyCollection<T>;
+    values(): LazyCollection<T>;
+    keys(): LazyCollection<string>;
+    diff(other: readonly T[] | LazyCollection<T> | Collection<T>): LazyCollection<T>;
+    diffAssoc(other: readonly Partial<T>[] | LazyCollection<Partial<T>>): LazyCollection<T>;
+    diffKeys(otherKeys: readonly string[]): LazyCollection<T>;
+    intersect(other: readonly T[] | LazyCollection<T> | Collection<T>): LazyCollection<T>;
+    intersectAssoc(other: readonly Partial<T>[] | LazyCollection<Partial<T>>): LazyCollection<T>;
+    intersectByKeys(keys: readonly string[]): LazyCollection<T>;
+    union(other: readonly T[] | LazyCollection<T> | Collection<T>): LazyCollection<T>;
+    crossJoin<U>(...others: readonly (readonly U[])[]): LazyCollection<(T | U)[]>;
+    unique(by?: RetrieverInput<T>): LazyCollection<T>;
+    uniqueStrict(by?: RetrieverInput<T>): LazyCollection<T>;
+    duplicates(by?: RetrieverInput<T>): Record<number, T>;
+    duplicatesStrict(by?: RetrieverInput<T>): Record<number, T>;
+    only(keys: readonly string[]): LazyCollection<Partial<T>>;
+    except(keys: readonly string[]): LazyCollection<Partial<T>>;
+    flip(): LazyCollection<Record<string, number>>;
+    pad(size: number, value: T): LazyCollection<T>;
+    multiply(factor: number): LazyCollection<T>;
+    combine<V>(values: readonly V[] | LazyCollection<V> | Collection<V>): Record<string, V>;
+    zip<U>(values: readonly U[] | LazyCollection<U> | Collection<U>): LazyCollection<[T, U | undefined]>;
+    concat<U>(other: readonly U[] | LazyCollection<U> | Collection<U>): LazyCollection<T | U>;
+    merge<U>(...sources: readonly (readonly U[] | LazyCollection<U> | Collection<U>)[]): LazyCollection<T | U>;
+    each(callback: (item: T, index: number) => void | false): this;
+    /** Lazy: only fires as items are pulled out of subsequent operators. */
+    tapEach(callback: (item: T, index: number) => void): LazyCollection<T>;
+    reduce<R>(fn: (carry: R, item: T, index: number) => R, initial: R): R;
+    pipe<R>(callback: (collection: this) => R): R;
+    pipeInto<R>(Ctor: ClassConstructor<R, [this]>): R;
+    pipeThrough(pipes: readonly ((value: unknown) => unknown)[]): unknown;
+    tap(callback: (collection: this) => void): this;
+    implode(glueOrFormatter: string | ((item: T, index: number) => string), keyOrSeparator?: string): string;
+    join(glue: string, finalGlue?: string): string;
+    when(condition: boolean | ((c: this) => boolean), callback: (c: this, value: boolean) => this | void, fallback?: (c: this, value: boolean) => this | void): this;
+    unless(condition: boolean | ((c: this) => boolean), callback: (c: this, value: boolean) => this | void, fallback?: (c: this, value: boolean) => this | void): this;
+    whenEmpty(cb: (c: this) => this | void, fb?: (c: this) => this | void): this;
+    whenNotEmpty(cb: (c: this) => this | void, fb?: (c: this) => this | void): this;
+    unlessEmpty(cb: (c: this) => this | void): this;
+    unlessNotEmpty(cb: (c: this) => this | void): this;
+    /**
+     * Stop enumerating once `deadline` is reached. `deadline` may be a Date or
+     * an absolute epoch-millis number.
+     */
+    takeUntilTimeout(deadline: Date | number): LazyCollection<T>;
+    /**
+     * Async throttle — yields one value every `seconds` seconds. Only useful in
+     * an `for await` context: returns an async iterable rather than a sync one.
+     */
+    throttle(seconds: number): AsyncIterable<T>;
+    /**
+     * Memoize values that have already been pulled. Subsequent iterations replay
+     * them from cache rather than re-running the source generator.
+     */
+    remember(): LazyCollection<T>;
+    /**
+     * Invoke `callback` every `interval` (a Date or epoch-ms duration) while
+     * enumerating. Useful for extending locks / posting heartbeats.
+     */
+    withHeartbeat(intervalMs: number, callback: () => void): LazyCollection<T>;
+    static macro: MacroableTarget['macro'];
+    static hasMacro: MacroableTarget['hasMacro'];
+    static flushMacros: MacroableTarget['flushMacros'];
+    private materialise;
+}

package/dist/src/collection/index.d.ts

@@ -0,0 +1,5 @@
+export { Collection } from '../../collection/Collection';
+export { LazyCollection } from '../../collection/LazyCollection';
+export type { LazySource } from '../../collection/LazyCollection';
+export { createHigherOrderProxy, HIGHER_ORDER_TARGETS } from '../../collection/HigherOrderProxy';
+export type { HigherOrderTarget } from '../../collection/HigherOrderProxy';

package/dist/src/contracts/Arrayable.d.ts

@@ -0,0 +1,4 @@
+export interface Arrayable<T> {
+    toArray(): T[];
+}
+export declare function isArrayable<T>(value: unknown): value is Arrayable<T>;

package/dist/src/contracts/Enumerable.d.ts

@@ -0,0 +1,17 @@
+import { Arrayable } from '../../contracts/Arrayable';
+import { Jsonable } from '../../contracts/Jsonable';
+/**
+ * Shared contract between Collection<T> and LazyCollection<T>.
+ * Methods that must exist on both forms — mirrors Laravel's
+ * `Illuminate\Support\Enumerable` interface.
+ *
+ * Methods that mutate the underlying source (push/pop/shift/etc.) are
+ * intentionally excluded — they only exist on the eager Collection.
+ */
+export interface Enumerable<T> extends Iterable<T>, Arrayable<T>, Jsonable {
+    count(): number;
+    isEmpty(): boolean;
+    isNotEmpty(): boolean;
+    toArray(): T[];
+    toJson(): string;
+}

package/dist/src/contracts/Jsonable.d.ts

@@ -0,0 +1,3 @@
+export interface Jsonable {
+    toJson(): string;
+}

package/dist/src/contracts/Macroable.d.ts

@@ -0,0 +1,6 @@
+export type MacroFn = (this: unknown, ...args: readonly unknown[]) => unknown;
+export interface MacroableStatic {
+    flushMacros(): void;
+    hasMacro(name: string): boolean;
+    macro(name: string, fn: MacroFn): void;
+}

package/dist/src/contracts/index.d.ts

@@ -0,0 +1,5 @@
+export type { Arrayable } from '../../contracts/Arrayable';
+export { isArrayable } from '../../contracts/Arrayable';
+export type { Jsonable } from '../../contracts/Jsonable';
+export type { Enumerable } from '../../contracts/Enumerable';
+export type { MacroFn, MacroableStatic } from '../../contracts/Macroable';

package/dist/src/exceptions/CollectionException.d.ts

@@ -0,0 +1,3 @@
+export declare class CollectionException extends Error {
+    constructor(message: string);
+}

package/dist/src/exceptions/ItemNotFoundException.d.ts

@@ -0,0 +1,4 @@
+import { CollectionException } from '../../exceptions/CollectionException';
+export declare class ItemNotFoundException extends CollectionException {
+    constructor(message?: string);
+}

package/dist/src/exceptions/MultipleItemsFoundException.d.ts

@@ -0,0 +1,5 @@
+import { CollectionException } from '../../exceptions/CollectionException';
+export declare class MultipleItemsFoundException extends CollectionException {
+    readonly count: number;
+    constructor(count?: number, message?: string);
+}

package/dist/src/exceptions/UnexpectedValueException.d.ts

@@ -0,0 +1,4 @@
+import { CollectionException } from '../../exceptions/CollectionException';
+export declare class UnexpectedValueException extends CollectionException {
+    constructor(message?: string);
+}

package/dist/src/exceptions/index.d.ts

@@ -0,0 +1,4 @@
+export { CollectionException } from '../../exceptions/CollectionException';
+export { ItemNotFoundException } from '../../exceptions/ItemNotFoundException';
+export { MultipleItemsFoundException } from '../../exceptions/MultipleItemsFoundException';
+export { UnexpectedValueException } from '../../exceptions/UnexpectedValueException';

package/dist/src/helpers/collect.d.ts

@@ -0,0 +1,3 @@
+import { Collection } from '../../collection/Collection';
+/** Laravel's `collect()` helper — wraps any iterable/array-like into a Collection. */
+export declare function collect<T>(items?: Iterable<T> | ArrayLike<T> | null | undefined): Collection<T>;

package/dist/src/helpers/index.d.ts

@@ -0,0 +1,2 @@
+export { collect } from '../../helpers/collect';
+export { lazy } from '../../helpers/lazy';

package/dist/src/helpers/lazy.d.ts

@@ -0,0 +1,3 @@
+import { LazyCollection, LazySource } from '../../collection/LazyCollection';
+/** Helper for building a LazyCollection from a generator function or iterable. */
+export declare function lazy<T>(source?: LazySource<T>): LazyCollection<T>;

package/dist/src/index.d.ts

@@ -0,0 +1,31 @@
+import { collect } from '../helpers/collect';
+export { Collection } from '../collection/Collection';
+export { LazyCollection } from '../collection/LazyCollection';
+export { AsyncCollection } from '../async/AsyncCollection';
+export type { AsyncSource } from '../async/AsyncCollection';
+export { mapWithConcurrency } from '../async/concurrent';
+export { collect } from '../helpers/collect';
+export { lazy } from '../helpers/lazy';
+export { parseCsv, toCsv } from '../io/csv';
+export type { CsvParseOptions, CsvSerializeOptions } from '../io/csv';
+export { parseJsonl, toJsonl, parseJsonlStream } from '../io/jsonl';
+export { fromReadable, lines } from '../io/streams';
+export type { FromReadableOptions, ReadableLike } from '../io/streams';
+export { createHigherOrderProxy, HIGHER_ORDER_TARGETS } from '../collection/HigherOrderProxy';
+export type { HigherOrderTarget } from '../collection/HigherOrderProxy';
+export { registerMacro, hasMacro, getMacro, flushMacros, applyMacroable } from '../macros/Macroable';
+export type { MacroableTarget } from '../macros/Macroable';
+export type { Arrayable, Jsonable, Enumerable, MacroFn, MacroableStatic } from '../contracts';
+export { isArrayable } from '../contracts';
+export { CollectionException, ItemNotFoundException, MultipleItemsFoundException, UnexpectedValueException } from '../exceptions';
+export type { PlainObject, Scalar, Comparable, Operator, SortDirection, Predicate, Iteratee, Comparator, ClassConstructor } from '../support/types';
+export type { RetrieverInput } from '../support/valueRetriever';
+export type { LazySource } from '../collection/LazyCollection';
+export * as operations from '../operations';
+export { dataGet, dataSet } from '../support/dataGet';
+export { deepEqual, looseEqual } from '../support/deepEqual';
+export { deepClone } from '../support/deepClone';
+export { valueRetriever } from '../support/valueRetriever';
+export { operatorForWhere, isOperator } from '../support/operatorForWhere';
+export { isPlainObject, isObjectLike, isFunction } from '../support/isObject';
+export default collect;

package/dist/src/io/csv.d.ts

@@ -0,0 +1,30 @@
+export interface CsvParseOptions {
+    delimiter?: string;
+    /** Treat the first row as the header. When true, returns objects keyed by header. */
+    header?: boolean;
+    /** Quote character — `"` by default. Pass empty string to disable quoting. */
+    quote?: string;
+    /** When true, all values stay as strings; otherwise simple numbers/bools are coerced. */
+    raw?: boolean;
+}
+export interface CsvSerializeOptions {
+    /** Optional explicit column order. When omitted, keys are taken from the first row. */
+    columns?: readonly string[];
+    delimiter?: string;
+    /** EOL sequence — defaults to \n. Use \r\n if Excel compat matters. */
+    eol?: string;
+    /** Include the header row at the top of the output. Default true when input is objects. */
+    header?: boolean;
+}
+/**
+ * RFC 4180-compatible CSV parser. Handles quoted fields with embedded
+ * delimiters, escaped quotes (`""`), and \r\n / \n line endings. Returns
+ * either string[][] (when `header` is false) or `Record<string, string>[]`.
+ */
+export declare function parseCsv(input: string, options?: CsvParseOptions): string[][] | Record<string, string | number | boolean | null>[];
+/**
+ * Serialize an array of objects (or rows) to a CSV string. Values that
+ * contain the delimiter, a quote, or a newline are quoted; embedded quotes
+ * are escaped by doubling.
+ */
+export declare function toCsv(rows: ReadonlyArray<Record<string, unknown>> | ReadonlyArray<readonly unknown[]>, options?: CsvSerializeOptions): string;

package/dist/src/io/index.d.ts

@@ -0,0 +1,5 @@
+export { parseCsv, toCsv } from '../../io/csv';
+export type { CsvParseOptions, CsvSerializeOptions } from '../../io/csv';
+export { parseJsonl, toJsonl, parseJsonlStream } from '../../io/jsonl';
+export { fromReadable, lines } from '../../io/streams';
+export type { FromReadableOptions, ReadableLike } from '../../io/streams';

package/dist/src/io/jsonl.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parse newline-delimited JSON. Empty lines are skipped. Each line must be
+ * a complete JSON value; otherwise a SyntaxError is thrown with the line
+ * number for diagnostics. The original parse error is attached as `cause`.
+ */
+export declare function parseJsonl<T = unknown>(input: string): T[];
+export declare function toJsonl<T>(items: ReadonlyArray<T>, eol?: string): string;
+/** Parse a JSONL stream incrementally, yielding one object per line. */
+export declare function parseJsonlStream<T = unknown>(source: AsyncIterable<string>): AsyncGenerator<T>;

package/dist/src/io/streams.d.ts

@@ -0,0 +1,27 @@
+import { AsyncCollection } from '../../async/AsyncCollection';
+/**
+ * Adapter for any Node `Readable` (or ReadableStream) that implements
+ * `AsyncIterable`. Buffers are decoded with UTF-8 by default; binary streams
+ * pass `decodeAs: undefined` to keep raw chunks.
+ */
+export interface ReadableLike<T> {
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+export interface FromReadableOptions {
+    /**
+     * Decode each chunk as text using the given encoding, or pass `false` to
+     * keep raw byte chunks (yields stringified buffers — caller likely wants a
+     * different signature in that case). Defaults to `'utf-8'`.
+     */
+    decodeAs?: 'utf8' | 'utf-8' | 'ascii' | 'latin1' | false;
+}
+/**
+ * Wrap a Node `Readable` (or any `AsyncIterable<Buffer | Uint8Array | string>`)
+ * into an `AsyncCollection<string>`. Pass `{decodeAs: false}` to skip decoding.
+ */
+export declare function fromReadable(source: ReadableLike<Buffer | Uint8Array | string>, options?: FromReadableOptions): AsyncCollection<string>;
+/**
+ * Convert an arbitrary chunk stream into a line-by-line `AsyncCollection<string>`.
+ * Handles \n and \r\n; trailing chunk without newline is emitted as the last line.
+ */
+export declare function lines(source: ReadableLike<Buffer | Uint8Array | string>): AsyncCollection<string>;

package/dist/src/macros/Macroable.d.ts

@@ -0,0 +1,20 @@
+import { MacroFn } from '../../contracts/Macroable';
+/**
+ * A reference to a class. We accept both regular and abstract constructors
+ * because some abstract base classes may also be macroable.
+ */
+export type MacroableClass = abstract new (...args: never[]) => unknown;
+export declare function registerMacro(target: MacroableClass, name: string, fn: MacroFn): void;
+export declare function hasMacro(target: MacroableClass, name: string): boolean;
+export declare function getMacro(target: MacroableClass, name: string): MacroFn | undefined;
+export declare function flushMacros(target: MacroableClass): void;
+/**
+ * Mix the static `macro`, `hasMacro`, and `flushMacros` methods onto a class.
+ * Used by `Collection` and `LazyCollection`. Avoids inheritance gymnastics.
+ */
+export interface MacroableTarget {
+    flushMacros(): void;
+    hasMacro(name: string): boolean;
+    macro(name: string, fn: MacroFn): void;
+}
+export declare function applyMacroable<C extends MacroableClass>(target: C): asserts target is C & MacroableTarget;

package/dist/src/macros/index.d.ts

@@ -0,0 +1 @@
+export { registerMacro, hasMacro, getMacro, flushMacros, applyMacroable, type MacroableTarget } from '../../macros/Macroable';

package/dist/src/operations/accessors.d.ts

@@ -0,0 +1,19 @@
+import { Operator, Predicate } from '../../support/types';
+export declare function firstOf<T>(items: readonly T[], predicate?: Predicate<T>): T | undefined;
+export declare function firstOrFailOf<T>(items: readonly T[], predicate?: Predicate<T>): T;
+export interface FirstWhereSpec {
+    operator: Operator;
+    /** Truthy check on the key when both operator and value are absent. */
+    truthy: boolean;
+    value: unknown;
+}
+export declare function buildFirstWhereSpec(operatorOrValue: Operator | unknown, value: unknown, argCount: number): FirstWhereSpec;
+export declare function firstWhereOf<T>(items: readonly T[], key: keyof T | string, spec: FirstWhereSpec): T | undefined;
+export declare function lastOf<T>(items: readonly T[], predicate?: Predicate<T>): T | undefined;
+export declare function getAt<T>(items: readonly T[], index: number, defaultValue?: T): T | undefined;
+export declare function valueOfFirst<T, R = unknown>(items: readonly T[], key: string): R | undefined;
+export declare function soleOf<T>(items: readonly T[], predicate?: Predicate<T> | keyof T | string, expected?: unknown): T;
+export declare function afterOf<T>(items: readonly T[], target: T | string | Predicate<T>, strict?: boolean): T | undefined;
+export declare function beforeOf<T>(items: readonly T[], target: T | string | Predicate<T>, strict?: boolean): T | undefined;
+export declare function hasKey<T>(items: readonly T[], keys: readonly (keyof T | string)[]): boolean;
+export declare function hasAnyKey<T>(items: readonly T[], keys: readonly (keyof T | string)[]): boolean;

package/dist/src/operations/aggregations.d.ts

@@ -0,0 +1,9 @@
+import { RetrieverInput } from '../../support/valueRetriever';
+export declare function sumOf<T>(items: readonly T[], by?: RetrieverInput<T, number>): number;
+export declare function averageOf<T>(items: readonly T[], by?: RetrieverInput<T, number>): number;
+export declare function maxOf<T, R = number>(items: readonly T[], by?: RetrieverInput<T, R>): R | undefined;
+export declare function minOf<T, R = number>(items: readonly T[], by?: RetrieverInput<T, R>): R | undefined;
+export declare function medianOf<T>(items: readonly T[], by?: RetrieverInput<T, number>): number | undefined;
+export declare function modeOf<T>(items: readonly T[], by?: RetrieverInput<T, unknown>): unknown[] | undefined;
+export declare function percentageOf<T>(items: readonly T[], predicate: (item: T, index: number) => boolean, precision?: number): number;
+export declare function countByOf<T>(items: readonly T[], by?: RetrieverInput<T, unknown>): Map<unknown, number>;

package/dist/src/operations/chunking.d.ts

@@ -0,0 +1,13 @@
+import { Predicate } from '../../support/types';
+export declare function chunkOf<T>(items: readonly T[], size: number): T[][];
+/**
+ * Group consecutive items that satisfy the predicate. The predicate receives
+ * the current item, its index, and the chunk built so far (to mirror Laravel).
+ */
+export declare function chunkWhileOf<T>(items: readonly T[], predicate: (item: T, key: number, chunk: readonly T[]) => boolean): T[][];
+export declare function slidingOf<T>(items: readonly T[], size: number, step?: number): T[][];
+export declare function splitOf<T>(items: readonly T[], groups: number): T[][];
+export declare function splitInOf<T>(items: readonly T[], groups: number): T[][];
+export declare function partitionOf<T>(items: readonly T[], predicate: Predicate<T>): [T[], T[]];
+export declare function forPageOf<T>(items: readonly T[], page: number, perPage: number): T[];
+export declare function nthOf<T>(items: readonly T[], step: number, offset?: number): T[];

package/dist/src/operations/combine.d.ts

@@ -0,0 +1,4 @@
+export declare function combineOf<K extends PropertyKey, V>(keys: readonly K[], values: readonly V[]): Record<K, V>;
+export declare function zipOf<T, U>(items: readonly T[], values: readonly U[]): [T, U | undefined][];
+/** Multi-source zip producing tuples of length N. Stops at the shortest input. */
+export declare function zipManyOf<T>(...sources: readonly (readonly T[])[]): T[][];

package/dist/src/operations/compare.d.ts

@@ -0,0 +1,29 @@
+import { Predicate } from '../../support/types';
+export type ContainsArg<T> = T | Predicate<T> | Partial<T> | {
+    [key: string]: unknown;
+};
+export type ContainsSpec<T> = {
+    kind: 'predicate';
+    predicate: Predicate<T>;
+} | {
+    kind: 'shape';
+    shape: Record<string, unknown>;
+} | {
+    kind: 'keyValue';
+    key: string;
+    value: unknown;
+} | {
+    kind: 'value';
+    value: unknown;
+};
+/** Loose match unless `strict` is true. */
+export declare function containsOf<T>(items: readonly T[], spec: ContainsSpec<T>, strict?: boolean): boolean;
+export declare function doesntContainOf<T>(items: readonly T[], spec: ContainsSpec<T>, strict?: boolean): boolean;
+/**
+ * Resolve user-supplied arguments into a normalised ContainsSpec.
+ * Used by both Collection.contains/doesntContain and their lazy counterparts.
+ */
+export declare function resolveContainsSpec<T>(target: ContainsArg<T>, value: unknown, hasValue: boolean): ContainsSpec<T>;
+export declare function everyOf<T>(items: readonly T[], predicate: Predicate<T>): boolean;
+export declare function someOf<T>(items: readonly T[], predicate: Predicate<T>): boolean;
+export declare function searchOf<T>(items: readonly T[], target: T | Predicate<T>, strict?: boolean): number | false;

package/dist/src/operations/conditionals.d.ts

@@ -0,0 +1,7 @@
+export type WhenCondition<C> = boolean | ((carrier: C) => boolean);
+export declare function resolveCondition<C>(carrier: C, condition: WhenCondition<C>): boolean;
+/**
+ * Functional `when`: invoke the matching callback and return whatever it
+ * returns, or the carrier itself when the callback returns void/undefined.
+ */
+export declare function whenOf<C>(carrier: C, condition: WhenCondition<C>, truthy: (carrier: C, value: boolean) => C | void, falsy?: (carrier: C, value: boolean) => C | void): C;

package/dist/src/operations/filters.d.ts

@@ -0,0 +1,27 @@
+import { ClassConstructor, Operator, Predicate } from '../../support/types';
+export declare function filterOf<T>(items: readonly T[], predicate?: Predicate<T>): T[];
+export declare function rejectOf<T>(items: readonly T[], predicate: Predicate<T>): T[];
+export interface WhereSpec {
+    operator: Operator;
+    strict: boolean;
+    truthy: boolean;
+    value: unknown;
+}
+export declare function buildWhereSpec(args: readonly unknown[], strict: boolean): WhereSpec;
+export declare function whereOf<T>(items: readonly T[], key: string, spec: WhereSpec): T[];
+export declare function whereInOf<T>(items: readonly T[], key: string, values: readonly unknown[], strict?: boolean): T[];
+export declare function whereNotInOf<T>(items: readonly T[], key: string, values: readonly unknown[], strict?: boolean): T[];
+export declare function whereBetweenOf<T>(items: readonly T[], key: string, range: readonly [unknown, unknown]): T[];
+export declare function whereNotBetweenOf<T>(items: readonly T[], key: string, range: readonly [unknown, unknown]): T[];
+export declare function whereNullOf<T>(items: readonly T[], key: string): T[];
+export declare function whereNotNullOf<T>(items: readonly T[], key: string): T[];
+export declare function whereInstanceOfOf<T, R>(items: readonly T[], Ctor: ClassConstructor<R> | (abstract new (...args: never[]) => R)): R[];
+/**
+ * Compile an SQL-`LIKE`-style pattern into an anchored RegExp. `%` matches any
+ * run of characters (including none) and `_` matches exactly one; every other
+ * character is matched literally. Matching is case-insensitive unless
+ * `caseSensitive` is set.
+ */
+export declare function likeToRegExp(pattern: string, caseSensitive?: boolean): RegExp;
+/** Keep items whose `key` value matches an SQL-`LIKE` pattern (or its inverse). */
+export declare function whereLikeOf<T>(items: readonly T[], key: string, pattern: string, caseSensitive?: boolean, negate?: boolean): T[];

package/dist/src/operations/grouping.d.ts

@@ -0,0 +1,5 @@
+import { RetrieverInput } from '../../support/valueRetriever';
+export declare function groupByOf<T, K extends PropertyKey = PropertyKey>(items: readonly T[], by: RetrieverInput<T, K | readonly K[]>): Record<K, T[]>;
+/** groupByMany: apply multiple grouping functions left-to-right, producing nested groups. */
+export declare function groupByManyOf<T>(items: readonly T[], groupers: readonly RetrieverInput<T>[]): Record<PropertyKey, unknown>;
+export declare function keyByOf<T, K extends PropertyKey = PropertyKey>(items: readonly T[], by: RetrieverInput<T, K>): Record<K, T>;

package/dist/src/operations/index.d.ts

@@ -0,0 +1,22 @@
+export * from '../../operations/accessors';
+export * from '../../operations/aggregations';
+export * from '../../operations/chunking';
+export * from '../../operations/compare';
+export * from '../../operations/combine';
+export * from '../../operations/conditionals';
+export * from '../../operations/filters';
+export * from '../../operations/grouping';
+export * from '../../operations/itertools';
+export * from '../../operations/joins';
+export * from '../../operations/mutations';
+export * from '../../operations/objectOps';
+export * from '../../operations/random';
+export * from '../../operations/reducers';
+export * from '../../operations/sequence';
+export * from '../../operations/setOps';
+export * from '../../operations/sliceOps';
+export * from '../../operations/sorting';
+export * from '../../operations/stats';
+export * from '../../operations/strings';
+export * from '../../operations/transformations';
+export * from '../../operations/uniqueness';

package/dist/src/operations/itertools.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Reduce that emits intermediate accumulator states. Useful for cumulative
+ * sums, state machines, and deriving "running" series.
+ */
+export declare function scanOf<T, R>(items: readonly T[], fn: (carry: R, item: T, index: number) => R, initial: R): R[];
+/** Yield consecutive pairs: `[a, b, c, d]` → `[[a,b],[b,c],[c,d]]`. */
+export declare function pairwiseOf<T>(items: readonly T[]): [T, T][];
+/** Tag each item with its index: `[a, b]` → `[[0,a],[1,b]]`. */
+export declare function enumerateOf<T>(items: readonly T[], start?: number): [number, T][];
+/**
+ * Repeat the input `n` times. If `n` is `Infinity`, returns a generator that
+ * never terminates — caller must `.take()` to bound it.
+ */
+export declare function cycleOf<T>(items: readonly T[], n?: number): Generator<T>;
+/**
+ * Round-robin interleave of multiple sources: zips the heads, then the
+ * second-positions, etc. Stops at the shortest source.
+ */
+export declare function interleaveOf<T>(...sources: readonly (readonly T[])[]): T[];
+/**
+ * Split a single iterable into `n` independent iterables that can each be
+ * consumed independently. The shared underlying iterator is buffered as
+ * needed — memory grows with the gap between fastest and slowest consumer.
+ */
+export declare function teeOf<T>(source: Iterable<T>, n: number): Generator<T>[];
+/**
+ * All r-length permutations (without repetition). For an n-element input
+ * with r = n this generates n! sequences. Order matches Python's itertools.
+ */
+export declare function permutationsOf<T>(items: readonly T[], r?: number): Generator<T[]>;
+/**
+ * All r-length combinations (without repetition). For r = n this yields a
+ * single combination — the input itself.
+ */
+export declare function combinationsOf<T>(items: readonly T[], r: number): Generator<T[]>;
+/** Power set — all 2^n subsets, in increasing-size order. */
+export declare function powerSetOf<T>(items: readonly T[]): Generator<T[]>;

package/dist/src/operations/joins.d.ts

@@ -0,0 +1,17 @@
+import { RetrieverInput } from '../../support/valueRetriever';
+export type JoinResult<L, R, M> = M extends (left: L, right: R) => infer U ? U : [L, R];
+/**
+ * Inner join: emit one row per matching pair on `leftKey` / `rightKey`. If a
+ * `merge` function is supplied its return value is emitted; otherwise tuples
+ * `[left, right]` are produced.
+ */
+export declare function joinOnOf<L, R, K extends PropertyKey, M = [L, R]>(left: readonly L[], right: readonly R[], leftKey: RetrieverInput<L, K>, rightKey: RetrieverInput<R, K>, merge?: (l: L, r: R) => M): M[];
+/**
+ * Left join: each left row appears at least once. When no right match exists,
+ * `right` is `undefined` (or supplied to `merge` as undefined).
+ */
+export declare function leftJoinOf<L, R, K extends PropertyKey, M = [L, R | undefined]>(left: readonly L[], right: readonly R[], leftKey: RetrieverInput<L, K>, rightKey: RetrieverInput<R, K>, merge?: (l: L, r: R | undefined) => M): M[];
+/** Right join — symmetrical to leftJoin. */
+export declare function rightJoinOf<L, R, K extends PropertyKey, M = [L | undefined, R]>(left: readonly L[], right: readonly R[], leftKey: RetrieverInput<L, K>, rightKey: RetrieverInput<R, K>, merge?: (l: L | undefined, r: R) => M): M[];
+/** Full outer join — every left and right row appears at least once. */
+export declare function outerJoinOf<L, R, K extends PropertyKey, M = [L | undefined, R | undefined]>(left: readonly L[], right: readonly R[], leftKey: RetrieverInput<L, K>, rightKey: RetrieverInput<R, K>, merge?: (l: L | undefined, r: R | undefined) => M): M[];