tyneq 1.0.0 → 1.0.2

package/dist/core-C54TSmgW.d.cts

@@ -0,0 +1,1390 @@
+/**
+ * Abstract base for multi-key stable sorters used by the ordering infrastructure.
+ *
+ * @remarks
+ * `computeKeys()` pre-computes sort keys for each element; `compareKeys()` compares by index.
+ * Sorters chain together via the `next` field on {@link TyneqEnumerableSorter} to implement
+ * multi-key (thenBy) sorting.
+ *
+ * @internal
+ */
+declare abstract class BaseEnumerableSorter<TSource> {
+    /** Pre-computes the sort key for each element in `source[0..count-1]`. */
+    abstract computeKeys(source: TSource[], count: number): void;
+    /** Compares the sort keys at indices `i` and `j`. Returns negative, zero, or positive. */
+    abstract compareKeys(i: number, j: number): number;
+    /**
+     * Returns a stable sorted index map for `source[0..count-1]`.
+     *
+     * @returns An array of indices sorted by the key order defined by this sorter chain.
+     */
+    sort(source: TSource[], count: number): number[];
+}
+
+/** `T | null` */
+type Nullable<T> = T | null;
+/** `T | undefined` */
+type Maybe<T> = T | undefined;
+/** `T | null | undefined` */
+type Optional<T> = T | null | undefined;
+/** Any object with a `length` property. */
+type HasLength = {
+    length: number;
+};
+/** Any function with any number of arguments. */
+type GenericFunction = (...x: never[]) => unknown;
+/** A constructor type that can be instantiated with `new`. */
+type Constructor<TInstance = unknown, TArgs extends readonly any[] = any[]> = new (...args: TArgs) => TInstance;
+/** A type that extracts the instance type from a constructor. */
+type InstanceOf<C> = C extends Constructor<infer TInstance> ? TInstance : never;
+/** A type that prevents inference of `T` in generic functions. */
+type NoInfer<T> = [T][T extends any ? 0 : never];
+/** A function that takes arguments of type `TArgs` (tuple) and returns void. */
+type Action<TArgs extends readonly unknown[] = []> = (...args: TArgs) => void;
+/** A function that takes arguments of type `TArgs` (tuple) and returns a boolean. */
+type Predicate<TArgs extends readonly unknown[] = []> = (...args: TArgs) => boolean;
+/** A predicate over a sequence element and its zero-based index. */
+type ItemPredicate<T> = (item: T, index: number) => boolean;
+/** A projection over a sequence element and its zero-based index. */
+type ItemSelector<T, TResult> = (item: T, index: number) => TResult;
+/** A side-effect action over a sequence element and its zero-based index. */
+type ItemAction<T> = (item: T, index: number) => void;
+/** A function that takes arguments of type `TArgs` (tuple) and returns a value of type `TResult`. */
+type Func<TArgs extends readonly unknown[] = [], TResult = unknown> = (...args: TArgs) => TResult;
+/** A method callable on a specific `this` context, returning `TReturn`. */
+type BoundMethod<TThis = unknown, TReturn = unknown> = (this: TThis, ...args: any[]) => TReturn;
+/** A method callable on any `this` context with unknown arguments. */
+type Method = BoundMethod<unknown>;
+/** A factory function that creates an instance of type `TInstance` given arguments of type `TArgs`. */
+type Factory<TInstance = unknown, TArgs extends readonly any[] = any[]> = (...args: TArgs) => TInstance;
+/**
+ * Narrows `T` to `U` if `T extends U`; otherwise falls back to `U`.
+ *
+ * @remarks
+ * Use this when you have a type variable `T` that you know satisfies `U` in context
+ * but TypeScript cannot prove it statically. `Assume<T, U>` resolves to `T` when the
+ * constraint holds and to `U` as a safe fallback when it does not - avoiding `any`.
+ *
+ * @example
+ * ```ts
+ * // Generic return type constrained to the concrete key type:
+ * type ValueAt<T, K extends keyof T> = Assume<T[K], string>;
+ * // T[K] is string -> resolves to T[K] (the specific type is kept)
+ * // T[K] is number -> resolves to string (falls back to the bound)
+ * ```
+ *
+ * @group Types
+ */
+type Assume<T, U> = T extends U ? T : U;
+/**
+ * Identity type - preserves `T` as-is with no structural transformation.
+ *
+ * @remarks
+ * Use `Cast<T>` as an explicit annotation in generic contexts where inference would
+ * widen or lose the type, or where you want to document that a type is intentionally
+ * passed through unchanged. It is a zero-cost no-op at both compile time and runtime.
+ *
+ * @example
+ * ```ts
+ * // Annotate a computed property type without changing it:
+ * type Passthrough<T> = Cast<{ [K in keyof T]: T[K] }>;
+ *
+ * // Use as a readable annotation instead of a bare type parameter:
+ * function identity<T>(value: Cast<T>): T { return value; }
+ * ```
+ *
+ * @group Types
+ */
+type Cast<T> = T;
+/** A type representing an object with assignable properties. */
+type WithProperties<K extends PropertyKey, V> = {
+    [P in K]?: V;
+} & Record<PropertyKey, unknown>;
+/**
+ * Extracts the keys of `T` whose value type extends `Function` (i.e. methods).
+ *
+ * @group Types
+ */
+type MethodKeys<T> = {
+    [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;
+}[keyof T];
+/**
+ * Extracts the keys of `T` whose value type does NOT extend `Function` (i.e. data fields).
+ *
+ * @group Types
+ */
+type FieldKeys<T> = {
+    [K in keyof T]: T[K] extends (...args: any[]) => any ? never : K;
+}[keyof T];
+
+/**
+ * Symbol key used to access the {@link QueryPlanNode} on a `TyneqSequence`.
+ *
+ * @example
+ * ```ts
+ * import { tyneqQueryNode } from "tyneq";
+ * const node = seq[tyneqQueryNode]; // QueryPlanNode | null
+ * ```
+ *
+ * @group QueryPlan
+ */
+declare const tyneqQueryNode: unique symbol;
+/**
+ * Categories of operators.
+ *
+ * @remarks
+ * String literal types used to classify operator behaviour.
+ *
+ * @group QueryPlan
+ */
+type OperatorCategory = "source" | "streaming" | "buffer" | "terminal";
+/**
+ * The JavaScript collection type that backs a source node.
+ *
+ * @group QueryPlan
+ */
+type SourceKind = "array" | "set" | "map" | "string" | "other";
+/**
+ * A node in the query plan tree representing one operator in a pipeline.
+ *
+ * @remarks
+ * Nodes form a linked list via `source`. The head node has `source === null` and represents the data source.
+ *
+ * @group QueryPlan
+ */
+interface QueryPlanNode {
+    /** The operator name as registered with the registry. */
+    readonly operatorName: string;
+    /** The arguments passed to the operator. Functions render as `<fn>` in printed output. */
+    readonly args: readonly unknown[];
+    /** The upstream node, or `null` for source nodes. */
+    readonly source: Nullable<QueryPlanNode>;
+    /**
+     * Operator category describing behaviour (`"source" | "streaming" | "buffer" | "terminal").
+     */
+    readonly category: OperatorCategory;
+    /**
+     * The backing JavaScript collection type for source nodes.
+     *
+     * @remarks
+     * Only meaningful when `category === "source"`. For all other categories this field is
+     * `undefined`. Use {@link isSourceNode} to narrow the type before reading this field.
+     */
+    readonly sourceKind?: SourceKind;
+    /**
+     * Accepts a visitor and returns its result.
+     *
+     * @param visitor - The visitor to invoke.
+     */
+    accept<T>(visitor: QueryPlanVisitor<T>): T;
+}
+/**
+ * Narrows a `QueryPlanNode` to one that is guaranteed to have a `sourceKind`.
+ *
+ * @remarks
+ * `sourceKind` is only present on source nodes (`category === "source"`). Reading it on any
+ * other node returns `undefined`. Use this guard before accessing `node.sourceKind` to get
+ * proper type narrowing and avoid ambiguous `undefined`.
+ *
+ * @example
+ * ```ts
+ * if (isSourceNode(node)) {
+ *     console.log(node.sourceKind); // "array" | "set" | "map" | "string" | "other"
+ * }
+ * ```
+ *
+ * @group QueryPlan
+ */
+declare function isSourceNode(node: QueryPlanNode): node is QueryPlanNode & {
+    sourceKind: SourceKind;
+};
+/**
+ * Traversal direction for {@link QueryPlanWalker}.
+ *
+ * - `"source-to-terminal"` - visits from the source node up to the terminal (bottom-up).
+ *   `from` is visited before `where`, `where` before `select`. This is the default.
+ * - `"terminal-to-source"` - visits from the terminal node down to the source (top-down).
+ *   `select` is visited before `where`, `where` before `from`.
+ *
+ * @group QueryPlan
+ */
+type QueryPlanTraversalDirection = "source-to-terminal" | "terminal-to-source";
+/**
+ * Options for {@link QueryPlanWalker}.
+ *
+ * @group QueryPlan
+ */
+interface QueryPlanWalkerOptions {
+    /**
+     * Callback invoked by the default `visitNode` implementation for each node.
+     * Ignored when `visitNode` is overridden in a subclass without calling `super.visitNode`.
+     */
+    callback?: (node: QueryPlanNode) => void;
+    /**
+     * Traversal direction. Defaults to `"source-to-terminal"`.
+     */
+    direction?: QueryPlanTraversalDirection;
+}
+/**
+ * Visitor for traversing a query plan tree.
+ *
+ * @typeParam T - The value produced by visiting a node.
+ * @group QueryPlan
+ */
+interface QueryPlanVisitor<T> {
+    /** Called for each node during traversal. */
+    visit(node: QueryPlanNode): T;
+}
+/**
+ * Options for {@link QueryPlanPrinter}.
+ *
+ * @group QueryPlan
+ */
+interface QueryPlanPrinterOptions {
+    /** Indentation string per nesting level. Defaults to `"  "` (two spaces). */
+    indent?: string;
+    /** Arrow string between levels. Defaults to `"->"`. */
+    arrow?: string;
+    /** Maximum number of array items to render inline. Defaults to `3`. */
+    maxInlineArrayItems?: number;
+}
+
+/**
+ * Concrete `QueryPlanNode` implementation.
+ * One node is created per operator call and linked to its upstream source node,
+ * forming a singly-linked list that represents the full query plan.
+ *
+ * @group QueryPlan
+ * @internal
+ */
+declare class QueryNode implements QueryPlanNode {
+    readonly operatorName: string;
+    readonly args: readonly unknown[];
+    readonly source: Nullable<QueryPlanNode>;
+    readonly category: OperatorCategory;
+    readonly sourceKind?: SourceKind | undefined;
+    constructor(operatorName: string, args: readonly unknown[], source: Nullable<QueryPlanNode>, category: OperatorCategory, sourceKind?: SourceKind | undefined);
+    accept<T>(visitor: QueryPlanVisitor<T>): T;
+}
+
+/**
+ * Abstract base that adds `orderBy`, `orderByDescending`, `memoize`, and `pipe` to a sequence.
+ *
+ * @remarks
+ * All four methods build `QueryNode`s and delegate to abstract factory methods, allowing
+ * subclasses to control which concrete sequence types are produced.
+ *
+ * @internal
+ */
+declare abstract class TyneqEnumerableCore<TSource> {
+    abstract readonly [tyneqQueryNode]: Nullable<QueryPlanNode>;
+    [Symbol.iterator](): Enumerator<TSource>;
+    abstract getEnumerator(): Enumerator<TSource>;
+    orderBy<TKey>(keySelector: (item: TSource) => TKey, comparer?: Comparer<TKey>): TyneqOrderedSequence<TSource>;
+    orderByDescending<TKey>(keySelector: (item: TSource) => TKey, comparer?: Comparer<TKey>): TyneqOrderedSequence<TSource>;
+    memoize(): TyneqCachedSequence<TSource>;
+    pipe<TResult>(factory: (source: Iterable<TSource>) => Enumerator<TResult> | IterableIterator<TResult>): TyneqSequence<TResult>;
+    /**
+     * Helper that creates a new sequence with the provided enumerator factory and query node.
+     * @param factory The factory function that produces an enumerator for the new sequence.
+     * @param node The query plan node associated with the new sequence.
+     * @returns A new TyneqSequence instance.
+     */
+    protected createSequence<TResult>(factory: () => Enumerator<TResult>, node: QueryPlanNode): TyneqSequence<TResult>;
+    /**
+     * Helper for creating a query node with the current sequence's node as its parent.
+     * @param name The name of the query node.
+     * @param category The category of the operator.
+     * @param args The arguments for the query node.
+     * @returns A new QueryNode instance.
+     */
+    protected createNode(name: string, category: OperatorCategory, args?: unknown[]): QueryNode;
+    protected abstract createEnumerable<TResult>(factory: EnumeratorFactory<TResult>, node: Nullable<QueryPlanNode>): TyneqSequence<TResult>;
+    protected abstract createOrderedEnumerable<TKey>(keySelector: (x: TSource) => TKey, comparer: Comparer<TKey>, descending: boolean, node: Nullable<QueryPlanNode>): TyneqOrderedSequence<TSource>;
+    protected abstract createCachedEnumerable(source: TyneqSequence<TSource>, node: Nullable<QueryPlanNode>): TyneqCachedSequence<TSource>;
+}
+
+/**
+ * Abstract base class that implements all {@link TyneqSequence} operator methods.
+ *
+ * @remarks
+ * All operator methods delegate to the corresponding operator class registered via
+ * `@operator`, `@terminal`, or the functional registration APIs.
+ * Subclasses implement `createEnumerable`, `createOrderedEnumerable`, and `createCachedEnumerable`
+ * to control which concrete sequence types are returned.
+ *
+ * @internal
+ */
+declare abstract class TyneqEnumerableBase<TSource> extends TyneqEnumerableCore<TSource> implements TyneqSequence<TSource> {
+    aggregate<UAccumulate, VResult>(seed: UAccumulate, func: (accumulate: UAccumulate, item: TSource) => UAccumulate, resultSelector: (accumulate: UAccumulate) => VResult): VResult;
+    all(predicate: ItemPredicate<TSource>): boolean;
+    any(predicate: ItemPredicate<TSource>): boolean;
+    average(selector: (item: TSource) => number): number;
+    consume(): void;
+    contains(value: TSource, equalityComparer?: EqualityComparer<TSource>): boolean;
+    count(): number;
+    countBy(predicate: ItemPredicate<TSource>): number;
+    elementAt(index: number): TSource;
+    elementAtOrDefault(index: number, defaultValue: TSource): TSource;
+    first(predicate: ItemPredicate<TSource>): TSource;
+    firstOrDefault(predicate: ItemPredicate<TSource>, defaultValue: TSource): TSource;
+    indexOf(predicate: ItemPredicate<TSource>, startIndex?: number): number;
+    isNullOrEmpty(): boolean;
+    last(predicate: ItemPredicate<TSource>): TSource;
+    lastOrDefault(predicate: ItemPredicate<TSource>, defaultValue: TSource): TSource;
+    max(comparer?: Comparer<TSource>): TSource;
+    maxBy<TKey>(keySelector: (element: TSource) => TKey, comparer?: Comparer<TKey>): TSource;
+    min(comparer?: Comparer<TSource>): TSource;
+    minBy<TKey>(keySelector: (element: TSource) => TKey, comparer?: Comparer<TKey>): TSource;
+    minMax(comparer?: Comparer<TSource>): MinMaxResult<TSource>;
+    sequenceEqual(other: Iterable<TSource>, equalityComparer?: EqualityComparer<TSource>): boolean;
+    single(predicate: ItemPredicate<TSource>): TSource;
+    singleOrDefault(predicate: ItemPredicate<TSource>, defaultValue: TSource): TSource;
+    endsWith(sequence: Iterable<TSource>, equalityComparer?: EqualityComparer<TSource>): boolean;
+    startsWith(sequence: Iterable<TSource>, equalityComparer?: EqualityComparer<TSource>): boolean;
+    sum(selector: (item: TSource) => number): number;
+    toArray(): TSource[];
+    toAsync(): AsyncIterable<TSource>;
+    toMap<TKey, TValue>(selector: (item: TSource) => KeyValuePair<TKey, TValue>): Map<TKey, TValue>;
+    toRecord<TKey extends string | number | symbol, TValue>(selector: (item: TSource) => KeyValuePair<TKey, TValue>): Record<TKey, TValue>;
+    toSet(): Set<TSource>;
+    ofType<U extends TSource>(guard: (value: TSource) => value is U): TyneqSequence<U>;
+    append(item: TSource): TyneqSequence<TSource>;
+    chunk(size: number): TyneqSequence<TSource[]>;
+    concat(other: Iterable<TSource>): TyneqSequence<TSource>;
+    defaultIfEmpty(defaultValue: TSource): TyneqSequence<TSource>;
+    flatten<TInner>(): TyneqSequence<TInner>;
+    pairwise(): TyneqSequence<[TSource, TSource]>;
+    populate<TValue>(value: TValue): TyneqSequence<TValue>;
+    prepend(item: TSource): TyneqSequence<TSource>;
+    scan<TResult>(seed: TResult, accumulator: (acc: TResult, item: TSource) => TResult): TyneqSequence<TResult>;
+    select<TResult>(selector: ItemSelector<TSource, TResult>): TyneqSequence<TResult>;
+    selectMany<TResult>(selector: (item: TSource) => Iterable<TResult>): TyneqSequence<TResult>;
+    window(size: number, step?: number): TyneqSequence<TSource[]>;
+    repeat(count: number): TyneqSequence<TSource>;
+    skip(count: number): TyneqSequence<TSource>;
+    skipLast(count: number): TyneqSequence<TSource>;
+    skipUntil(predicate: ItemPredicate<TSource>): TyneqSequence<TSource>;
+    skipWhile(predicate: ItemPredicate<TSource>): TyneqSequence<TSource>;
+    slice(start: number, end?: number): TyneqSequence<TSource>;
+    split(splitOn: (item: TSource) => boolean): TyneqSequence<TSource[]>;
+    take(count: number): TyneqSequence<TSource>;
+    takeUntil(predicate: ItemPredicate<TSource>): TyneqSequence<TSource>;
+    takeWhile(predicate: ItemPredicate<TSource>): TyneqSequence<TSource>;
+    tap(action: ItemAction<TSource>): TyneqSequence<TSource>;
+    tapIf(action: ItemAction<TSource>, predicate: () => boolean): TyneqSequence<TSource>;
+    throttle(count: number): TyneqSequence<TSource>;
+    where(predicate: ItemPredicate<TSource>): TyneqSequence<TSource>;
+    zip<TOther, TResult>(other: Iterable<TOther>, selector: (first: TSource, second: TOther) => TResult): TyneqSequence<TResult>;
+    backsert(index: number, other: Iterable<TSource>): TyneqSequence<TSource>;
+    distinct(): TyneqSequence<TSource>;
+    distinctBy<TKey>(keySelector: (item: TSource) => TKey): TyneqSequence<TSource>;
+    except(excludedValues: Iterable<TSource>): TyneqSequence<TSource>;
+    exceptBy<TKey>(excludedKeys: Iterable<TKey>, keySelector: (item: TSource) => TKey): TyneqSequence<TSource>;
+    groupBy<TKey, TValue, TResult>(keySelector: (item: TSource) => TKey, valueSelector: (item: TSource) => TValue, resultSelector: (key: TKey, values: TyneqSequence<TValue>) => TResult): TyneqSequence<TResult>;
+    groupJoin<TInner, TKey, TResult>(inner: Iterable<TInner>, outerKeySelector: (outer: TSource) => TKey, innerKeySelector: (inner: TInner) => TKey, resultSelector: (outer: TSource, group: TyneqSequence<TInner>) => TResult): TyneqSequence<TResult>;
+    intersect(intersectedValues: Iterable<TSource>): TyneqSequence<TSource>;
+    intersectBy<TKey>(intersectedKeys: Iterable<TKey>, keySelector: (item: TSource) => TKey): TyneqSequence<TSource>;
+    join<TInner, TKey, TResult>(inner: Iterable<TInner>, outerKeySelector: (outer: TSource) => TKey, innerKeySelector: (inner: TInner) => TKey, resultSelector: (outer: TSource, inner: TInner) => TResult): TyneqSequence<TResult>;
+    permutations(): TyneqSequence<TSource[]>;
+    reverse(): TyneqSequence<TSource>;
+    shuffle(): TyneqSequence<TSource>;
+    union(otherValues: Iterable<TSource>): TyneqSequence<TSource>;
+    unionBy<TKey>(otherValues: Iterable<TSource>, keySelector: (item: TSource) => TKey): TyneqSequence<TSource>;
+}
+
+/**
+ * Metadata describing a registered operator.
+ *
+ * @group Classes
+ */
+declare class OperatorMetadata {
+    readonly name: string;
+    readonly kind: OperatorKind;
+    readonly source: OperatorSource;
+    readonly targetClass: Maybe<SequenceConstructor>;
+    readonly extensions: Readonly<Record<string, unknown>>;
+    constructor(name: string, kind: OperatorKind, source?: OperatorSource, targetClass?: Maybe<SequenceConstructor>, extensions?: Readonly<Record<string, unknown>>);
+    /**
+     * Creates metadata for a source operator.
+     *
+     * @remarks
+     * `targetClass` is always `undefined` for source operators - they are static
+     * factories with no prototype and are never patched onto a class instance.
+     */
+    static source(name: string, src?: OperatorSource): OperatorMetadata;
+    /** Creates metadata for a streaming operator. Defaults targetClass to TyneqEnumerableBase. */
+    static streaming(name: string, targetClass?: SequenceConstructor, source?: OperatorSource, extensions?: Record<string, unknown>): OperatorMetadata;
+    /** Creates metadata for a buffering operator. Defaults targetClass to TyneqEnumerableBase. */
+    static buffer(name: string, targetClass?: SequenceConstructor, source?: OperatorSource, extensions?: Record<string, unknown>): OperatorMetadata;
+    /** Creates metadata for a terminal operator. Defaults targetClass to TyneqEnumerableBase. */
+    static terminal(name: string, targetClass?: SequenceConstructor, source?: OperatorSource, extensions?: Record<string, unknown>): OperatorMetadata;
+    /**
+     * Creates metadata for a streaming or buffer operator determined at runtime.
+     *
+     * @remarks
+     * Use when the category is a variable rather than a compile-time literal --
+     * for example in `@operator` and `@orderedOperator` whose `category` parameter
+     * is provided by the caller. For compile-time-known categories prefer the
+     * dedicated {@link streaming} / {@link buffer} / {@link terminal} statics.
+     *
+     * Only `"streaming"` and `"buffer"` are valid; passing `"terminal"` or `"source"` throws.
+     */
+    static forCategory(category: "streaming" | "buffer", name: string, targetClass?: SequenceConstructor, source?: OperatorSource, extensions?: Record<string, unknown>): OperatorMetadata;
+}
+
+/**
+ * A pull-based iterator over a sequence.
+ *
+ * @remarks
+ * Extends the native `Iterator<T>` protocol. `return()` disposes the iterator early;
+ * `throw()` is not supported and throws {@link NotSupportedError} if called.
+ *
+ * @typeParam T - Element type.
+ * @group Interfaces
+ */
+interface Enumerator<T> extends Iterator<T> {
+    next(): IteratorResult<T>;
+    /**
+     * Terminates the iterator early and releases resources.
+     *
+     * @remarks
+     * Idempotent - safe to call multiple times. Calling `next()` after `return()` returns `{ done: true }`.
+     */
+    return?(value?: unknown): IteratorResult<T>;
+}
+/**
+ * A factory that produces a fresh {@link Enumerator} on demand.
+ *
+ * @typeParam T - Element type.
+ * @group Interfaces
+ */
+interface EnumeratorFactory<T> {
+    /** Returns a new, independent enumerator starting at the beginning of the sequence. */
+    getEnumerator(): Enumerator<T>;
+}
+/**
+ * A function that compares two values for ordering.
+ *
+ * @remarks
+ * Must return a negative number when `a < b`, a positive number when `a > b`, and `0` when equal.
+ * Matches the signature expected by `Array.prototype.sort`.
+ *
+ * @typeParam T - The type of values being compared.
+ * @group Types
+ */
+type Comparer<T> = (a: T, b: T) => number;
+/**
+ * A function that tests two values for equality.
+ *
+ * @typeParam T - The type of values being compared.
+ * @group Types
+ */
+type EqualityComparer<T> = (a: T, b: T) => boolean;
+/**
+ * A lazy, re-iterable sequence.
+ *
+ * @remarks
+ * Each call to `[Symbol.iterator]()` or `getEnumerator()` produces a fresh enumerator with
+ * independent state, allowing the same sequence to be iterated multiple times.
+ *
+ * @typeParam T - Element type.
+ * @group Interfaces
+ */
+interface Enumerable<T> extends Iterable<T>, EnumeratorFactory<T> {
+    [Symbol.iterator](): Enumerator<T>;
+}
+/**
+ * Function that produces a fresh {@link Enumerator} each time it is called.
+ *
+ * @group Types
+ */
+type IteratorFactory<T> = () => Enumerator<T>;
+/**
+ * Function that wraps an iterator factory in a concrete `TyneqSequence` subclass.
+ *
+ * @group Types
+ * @internal
+ */
+type TyneqEnumerableFactory<TSource, TEnumerable extends TyneqSequence<TSource>> = (iteratorFactory: IteratorFactory<TSource>) => TEnumerable;
+/**
+ * The primary public API for a lazy sequence - the type returned by all Tyneq operators.
+ *
+ * @remarks
+ * Every operator method returns a new `TyneqSequence` without consuming the source.
+ * The source is not iterated until the returned sequence is iterated.
+ *
+ * @typeParam TSource - Element type.
+ * @group Interfaces
+ */
+interface TyneqSequence<TSource> extends Enumerable<TSource> {
+    /**
+     * The query plan node for this sequence, or `null` if no plan is available.
+     *
+     * @remarks
+     * Use {@link QueryPlanPrinter} to render this as a string.
+     * Sequences created via `pipe()` always have `null` here.
+     */
+    readonly [tyneqQueryNode]: Nullable<QueryPlanNode>;
+    /**
+     * Returns `true` if any element satisfies the predicate.
+     *
+     * @remarks
+     * Returns `false` for an empty sequence.
+     * The predicate receives each element and its zero-based index.
+     *
+     * @throws {ArgumentNullError} When `predicate` is null.
+     * @throws {ArgumentError} When `predicate` is undefined.
+     */
+    any(predicate: ItemPredicate<TSource>): boolean;
+    /**
+     * Returns `true` if all elements satisfy the predicate.
+     *
+     * @remarks
+     * Returns `true` for an empty sequence (vacuous truth).
+     * The predicate receives each element and its zero-based index.
+     *
+     * @throws {ArgumentNullError} When `predicate` is null.
+     * @throws {ArgumentError} When `predicate` is undefined.
+     */
+    all(predicate: ItemPredicate<TSource>): boolean;
+    /**
+     * Returns `true` if the source sequence contains `value`.
+     *
+     * @remarks
+     * Uses `equalityComparer` for element comparison, or `===` when omitted.
+     * Returns `false` for an empty sequence.
+     * Enumerates the source until a match is found or the sequence is exhausted.
+     *
+     * @throws {ArgumentNullError} When `equalityComparer` is null (undefined is allowed).
+     */
+    contains(value: TSource, equalityComparer?: EqualityComparer<TSource>): boolean;
+    /**
+     * Returns the number of elements.
+     *
+     * @remarks
+     * Returns `0` for an empty sequence.
+     */
+    count(): number;
+    /**
+     * Returns the number of elements that satisfy the predicate.
+     *
+     * @remarks
+     * Returns `0` if no elements match or the sequence is empty.
+     * The predicate receives each element and its zero-based index.
+     *
+     * @throws {ArgumentNullError} When `predicate` is null.
+     * @throws {ArgumentError} When `predicate` is undefined.
+     */
+    countBy(predicate: ItemPredicate<TSource>): number;
+    /**
+     * Iterates the entire sequence and discards all elements.
+     *
+     * @remarks
+     * Useful for triggering side effects (e.g., after `tap`).
+     */
+    consume(): void;
+    /**
+     * Returns `true` if the sequence is empty or if the first element is `null` or `undefined`.
+     */
+    isNullOrEmpty(): boolean;
+    /**
+     * Returns the element at `index`.
+     *
+     * @throws {ArgumentError} When `index` is not a safe integer.
+     * @throws {ArgumentOutOfRangeError} When `index` is negative or greater than or equal to the sequence length.
+     */
+    elementAt(index: number): TSource;
+    /**
+     * Returns the element at `index`, or `defaultValue` if the index is out of range.
+     *
+     * @throws {ArgumentError} When `index` is not a safe integer.
+     * @throws {ArgumentOutOfRangeError} When `index` is negative.
+     */
+    elementAtOrDefault(index: number, defaultValue: TSource): TSource;
+    /**
+     * Returns the first element that satisfies the predicate.
+     *
+     * @remarks
+     * The predicate receives each element and its zero-based index.
+     *
+     * @throws {ArgumentNullError} When `predicate` is null.
+     * @throws {ArgumentError} When `predicate` is undefined.
+     * @throws {InvalidOperationError} When no element satisfies the predicate.
+     */
+    first(predicate: ItemPredicate<TSource>): TSource;
+    /**
+     * Returns the first element that satisfies the predicate, or `defaultValue` if none does.
+     *
+     * @remarks
+     * The predicate receives each element and its zero-based index.
+     *
+     * @throws {ArgumentNullError} When `predicate` is null.
+     * @throws {ArgumentError} When `predicate` is undefined.
+     */
+    firstOrDefault(predicate: ItemPredicate<TSource>, defaultValue: TSource): TSource;
+    /**
+     * Returns the zero-based index of the first element that satisfies the predicate.
+     *
+     * @remarks
+     * Returns `-1` if no element satisfies the predicate.
+     * When `startIndex` is provided, the search starts at that index.
+     * The predicate receives each element and its zero-based index within the full sequence.
+     *
+     * @throws {ArgumentNullError} When `predicate` is null.
+     * @throws {ArgumentError} When `predicate` is undefined.
+     * @throws {ArgumentOutOfRangeError} When `startIndex` is negative.
+     */
+    indexOf(predicate: ItemPredicate<TSource>, startIndex?: number): number;
+    /**
+     * Returns the last element that satisfies the predicate.
+     *
+     * @remarks
+     * The predicate receives each element and its zero-based index.
+     *
+     * @throws {ArgumentNullError} When `predicate` is null.
+     * @throws {ArgumentError} When `predicate` is undefined.
+     * @throws {InvalidOperationError} When no element satisfies the predicate.
+     */
+    last(predicate: ItemPredicate<TSource>): TSource;
+    /**
+     * Returns the last element that satisfies the predicate, or `defaultValue` if none does.
+     *
+     * @remarks
+     * The predicate receives each element and its zero-based index.
+     *
+     * @throws {ArgumentNullError} When `predicate` is null.
+     * @throws {ArgumentError} When `predicate` is undefined.
+     */
+    lastOrDefault(predicate: ItemPredicate<TSource>, defaultValue: TSource): TSource;
+    /**
+     * Returns the maximum element according to the comparer.
+     *
+     * @remarks
+     * Uses the natural `>` operator when no comparer is provided.
+     *
+     * @throws {SequenceContainsNoElementsError} When the sequence is empty.
+     */
+    max(comparer?: Comparer<TSource>): TSource;
+    /**
+     * Returns the element with the maximum key.
+     *
+     * @throws {SequenceContainsNoElementsError} When the sequence is empty.
+     * @throws {ArgumentNullError} When `keySelector` is null.
+     * @throws {ArgumentError} When `keySelector` is undefined.
+     */
+    maxBy<TKey>(keySelector: (element: TSource) => TKey, comparer?: Comparer<TKey>): TSource;
+    /**
+     * Returns the minimum element according to the comparer.
+     *
+     * @remarks
+     * Uses the natural `<` operator when no comparer is provided.
+     *
+     * @throws {SequenceContainsNoElementsError} When the sequence is empty.
+     */
+    min(comparer?: Comparer<TSource>): TSource;
+    /**
+     * Returns the element with the minimum key.
+     *
+     * @throws {SequenceContainsNoElementsError} When the sequence is empty.
+     * @throws {ArgumentNullError} When `keySelector` is null.
+     * @throws {ArgumentError} When `keySelector` is undefined.
+     */
+    minBy<TKey>(keySelector: (element: TSource) => TKey, comparer?: Comparer<TKey>): TSource;
+    /**
+     * Returns `true` if this sequence and `other` have the same elements in the same order.
+     *
+     * @remarks
+     * Uses `equalityComparer` for element comparison, or `===` when omitted.
+     * Returns `true` if both sequences are empty.
+     */
+    sequenceEqual(other: Iterable<TSource>, equalityComparer?: EqualityComparer<TSource>): boolean;
+    /**
+     * Returns the only element that satisfies the predicate.
+     *
+     * @remarks
+     * The predicate receives each element and its zero-based index.
+     *
+     * @throws {ArgumentNullError} When `predicate` is null.
+     * @throws {ArgumentError} When `predicate` is undefined.
+     * @throws {InvalidOperationError} When no element satisfies the predicate, or when more than one does.
+     */
+    single(predicate: ItemPredicate<TSource>): TSource;
+    /**
+     * Returns the only element that satisfies the predicate, or `defaultValue` if none does.
+     *
+     * @remarks
+     * The predicate receives each element and its zero-based index.
+     *
+     * @throws {ArgumentNullError} When `predicate` is null.
+     * @throws {ArgumentError} When `predicate` is undefined.
+     * @throws {InvalidOperationError} When more than one element satisfies the predicate.
+     */
+    singleOrDefault(predicate: ItemPredicate<TSource>, defaultValue: TSource): TSource;
+    /**
+     * Returns `true` if this sequence ends with all elements of `sequence` in order.
+     *
+     * @remarks
+     * Uses `equalityComparer` for element comparison, or `===` when omitted.
+     * Returns `true` when `sequence` is empty (vacuous truth).
+     * Returns `false` when `sequence` is longer than the source.
+     *
+     * @example
+     * ```ts
+     * Tyneq.from([1, 2, 3, 4, 5]).endsWith([4, 5]);        // true
+     * Tyneq.from([1, 2, 3, 4, 5]).endsWith([3, 5]);        // false
+     * Tyneq.from([1, 2, 3]).endsWith([]);                   // true
+     * Tyneq.from([1, 2]).endsWith([1, 2, 3]);               // false
+     *
+     * // Custom equality
+     * Tyneq.from(["A", "B", "C"]).endsWith(
+     *   ["b", "c"],
+     *   (a, b) => a.toLowerCase() === b.toLowerCase()
+     * ); // true
+     * ```
+     *
+     * @throws {ArgumentNullError} When `sequence` is null.
+     * @throws {ArgumentError} When `sequence` is undefined.
+     * @throws {ArgumentTypeError} When `sequence` is not iterable.
+     * @throws {ArgumentNullError} When `equalityComparer` is null (undefined is allowed).
+     */
+    endsWith(sequence: Iterable<TSource>, equalityComparer?: EqualityComparer<TSource>): boolean;
+    /**
+     * Returns `true` if this sequence starts with all elements of `sequence` in order.
+     *
+     * @remarks
+     * Uses `equalityComparer` for element comparison, or `===` when omitted.
+     * Returns `true` when `sequence` is empty (vacuous truth).
+     * Returns `false` when `sequence` is longer than the source.
+     *
+     * @throws {ArgumentNullError} When `sequence` is null.
+     * @throws {ArgumentError} When `sequence` is undefined.
+     * @throws {ArgumentTypeError} When `sequence` is not iterable.
+     * @throws {ArgumentNullError} When `equalityComparer` is null (undefined is allowed).
+     */
+    startsWith(sequence: Iterable<TSource>, equalityComparer?: EqualityComparer<TSource>): boolean;
+    /**
+     * Returns the sum of `selector` applied to each element.
+     *
+     * @remarks
+     * Returns `0` for an empty sequence.
+     *
+     * @throws {ArgumentNullError} When `selector` is null.
+     * @throws {ArgumentError} When `selector` is undefined.
+     */
+    sum(selector: (item: TSource) => number): number;
+    /**
+     * Materializes the sequence into an array.
+     *
+     * @remarks
+     * Returns `[]` for an empty sequence.
+     */
+    toArray(): TSource[];
+    /**
+     * Returns an `AsyncIterable` that iterates this sequence asynchronously.
+     *
+     * @remarks
+     * Deferred - each `for await...of` loop produces a fresh traversal of the source.
+     */
+    toAsync(): AsyncIterable<TSource>;
+    /**
+     * Materializes the sequence into a `Map`.
+     *
+     * @throws {ArgumentNullError} When `selector` is null.
+     * @throws {ArgumentError} When `selector` is undefined.
+     */
+    toMap<TKey, TValue>(selector: (item: TSource) => KeyValuePair<TKey, TValue>): Map<TKey, TValue>;
+    /**
+     * Materializes the sequence into a plain object record.
+     *
+     * @throws {ArgumentNullError} When `selector` is null.
+     * @throws {ArgumentError} When `selector` is undefined.
+     */
+    toRecord<TKey extends string | number | symbol, TValue>(selector: (item: TSource) => KeyValuePair<TKey, TValue>): Record<TKey, TValue>;
+    /**
+     * Materializes the sequence into a `Set`.
+     *
+     * @remarks
+     * Duplicate elements are deduplicated using `Set` identity semantics.
+     */
+    toSet(): Set<TSource>;
+    /**
+     * Returns the arithmetic mean of `selector` applied to each element.
+     *
+     * @throws {SequenceContainsNoElementsError} When the sequence is empty.
+     * @throws {ArgumentNullError} When `selector` is null.
+     * @throws {ArgumentError} When `selector` is undefined.
+     */
+    average(selector: (item: TSource) => number): number;
+    /**
+     * Folds the sequence into a single result value.
+     *
+     * @remarks
+     * Applies `func` to each element in order, starting from `seed`. Returns `resultSelector(seed)` for an empty sequence.
+     *
+     * @throws {ArgumentNullError} When `func` or `resultSelector` is null.
+     * @throws {ArgumentError} When `func` or `resultSelector` is undefined.
+     */
+    aggregate<UAccumulate, VResult>(seed: UAccumulate, func: (accumulate: UAccumulate, item: TSource) => UAccumulate, resultSelector: (accumulate: UAccumulate) => VResult): VResult;
+    /** Returns a new sequence with `item` appended after all source elements. */
+    append(item: TSource): TyneqSequence<TSource>;
+    /**
+     * Partitions the sequence into non-overlapping arrays of length `size`.
+     *
+     * @remarks
+     * The last chunk may be shorter than `size` if the sequence length is not divisible by `size`.
+     *
+     * @throws {ArgumentError} When `size` is not a safe integer.
+     * @throws {ArgumentOutOfRangeError} When `size` is less than or equal to `0`.
+     */
+    chunk(size: number): TyneqSequence<TSource[]>;
+    /** Returns a new sequence with the elements of `other` appended after the source. */
+    concat(other: Iterable<TSource>): TyneqSequence<TSource>;
+    /**
+     * Returns a sequence that yields `defaultValue` when the source is empty.
+     *
+     * @remarks
+     * Passes source elements through unchanged when the source is non-empty.
+     */
+    defaultIfEmpty(defaultValue: TSource): TyneqSequence<TSource>;
+    /**
+     * Flattens one level of nesting from a sequence of iterables.
+     *
+     * @remarks
+     * Deferred. Each inner iterable is consumed lazily as the outer sequence advances.
+     * Returns an empty sequence when the source is empty.
+     * Equivalent to `selectMany(x => x)` but without requiring a selector.
+     *
+     * @example
+     * ```ts
+     * Tyneq.from([[1, 2], [3, 4], [5]]).flatten().toArray();
+     * // [1, 2, 3, 4, 5]
+     *
+     * Tyneq.from(["hello", "world"]).flatten().toArray();
+     * // ["h", "e", "l", "l", "o", "w", "o", "r", "l", "d"]
+     * ```
+     */
+    flatten<TInner>(this: TyneqSequence<Iterable<TInner>>): TyneqSequence<TInner>;
+    /**
+     * Returns consecutive overlapping pairs of elements: `[e0,e1]`, `[e1,e2]`, ...
+     *
+     * @remarks
+     * Returns an empty sequence when the source has fewer than two elements.
+     */
+    pairwise(): TyneqSequence<[TSource, TSource]>;
+    /**
+     * Filters elements to those for which `guard` returns `true`, narrowing the type to `U`.
+     *
+     * @throws {ArgumentNullError} When `guard` is null.
+     * @throws {ArgumentError} When `guard` is undefined.
+     */
+    ofType<U extends TSource>(guard: (value: TSource) => value is U): TyneqSequence<U>;
+    /** Returns a new sequence with `item` prepended before all source elements. */
+    prepend(item: TSource): TyneqSequence<TSource>;
+    /**
+     * Repeats the source sequence `count` times.
+     *
+     * @remarks
+     * Deferred. Re-enumerates the source from the beginning for each repetition.
+     * Returns an empty sequence when `count` is `0`.
+     *
+     * @example
+     * ```ts
+     * Tyneq.from([1, 2]).repeat(3).toArray();
+     * // [1, 2, 1, 2, 1, 2]
+     *
+     * Tyneq.from([1, 2]).repeat(0).toArray();
+     * // []
+     * ```
+     *
+     * @throws {ArgumentOutOfRangeError} When `count` is negative.
+     * @throws {ArgumentError} When `count` is not an integer.
+     */
+    repeat(count: number): TyneqSequence<TSource>;
+    /**
+     * Replaces each element with `value`, keeping the same sequence length.
+     *
+     * @remarks
+     * Useful for generating a sequence of a fixed value with a known length derived from the source.
+     */
+    populate<TValue>(value: TValue): TyneqSequence<TValue>;
+    /**
+     * Projects each element through `selector`.
+     *
+     * @remarks
+     * The selector receives each element and its zero-based index.
+     *
+     * @throws {ArgumentNullError} When `selector` is null.
+     * @throws {ArgumentError} When `selector` is undefined.
+     */
+    select<TResult>(selector: ItemSelector<TSource, TResult>): TyneqSequence<TResult>;
+    /**
+     * Projects each element to an iterable and flattens the results into a single sequence.
+     *
+     * @throws {ArgumentNullError} When `selector` is null.
+     * @throws {ArgumentError} When `selector` is undefined.
+     */
+    selectMany<TResult>(selector: (item: TSource) => Iterable<TResult>): TyneqSequence<TResult>;
+    /**
+     * Yields fixed-size windows (sub-arrays) over the source sequence.
+     *
+     * @remarks
+     * Deferred. O(`size`) memory - only the current window is held in memory.
+     * When `step` is 1 (the default), windows slide one element at a time (overlapping).
+     * When `step` equals `size`, windows are non-overlapping (tumbling).
+     * When `step` exceeds `size`, elements between windows are skipped (gaps).
+     * Yields no windows when the source has fewer than `size` elements.
+     * Each yielded array is a snapshot - mutating it does not affect subsequent windows.
+     *
+     * @example
+     * ```ts
+     * // Sliding (default step = 1)
+     * Tyneq.range(1, 5).window(3).toArray();
+     * // [[1,2,3], [2,3,4], [3,4,5]]
+     *
+     * // Tumbling (step = size)
+     * Tyneq.range(1, 6).window(2, 2).toArray();
+     * // [[1,2], [3,4], [5,6]]
+     * ```
+     *
+     * @throws {ArgumentError} When `size` or `step` is not a safe integer.
+     * @throws {ArgumentOutOfRangeError} When `size` is less than `1`.
+     * @throws {ArgumentOutOfRangeError} When `step` is less than `1`.
+     */
+    window(size: number, step?: number): TyneqSequence<TSource[]>;
+    /**
+     * Skips the first `count` elements.
+     *
+     * @remarks
+     * Returns an empty sequence when `count` exceeds the sequence length.
+     * `count` must be non-negative.
+     *
+     * @throws {ArgumentError} When `count` is not a safe integer.
+     * @throws {ArgumentOutOfRangeError} When `count` is negative.
+     */
+    skip(count: number): TyneqSequence<TSource>;
+    /**
+     * Skips the last `count` elements.
+     *
+     * @remarks
+     * Buffers `count` elements to determine the cutoff.
+     *
+     * @throws {ArgumentError} When `count` is not a safe integer.
+     * @throws {ArgumentOutOfRangeError} When `count` is negative.
+     */
+    skipLast(count: number): TyneqSequence<TSource>;
+    /**
+     * Skips elements until `predicate` returns `true`, then yields all remaining elements
+     * including the one that triggered the predicate.
+     *
+     * @remarks
+     * The predicate receives each element and its zero-based index.
+     * Once the predicate returns `true` it is never called again.
+     *
+     * @throws {ArgumentNullError} When `predicate` is null.
+     * @throws {ArgumentError} When `predicate` is undefined.
+     */
+    skipUntil(predicate: ItemPredicate<TSource>): TyneqSequence<TSource>;
+    /**
+     * Skips elements while `predicate` returns `true`, then yields the rest.
+     *
+     * @remarks
+     * The predicate receives each element and its zero-based index.
+     *
+     * @throws {ArgumentNullError} When `predicate` is null.
+     * @throws {ArgumentError} When `predicate` is undefined.
+     */
+    skipWhile(predicate: ItemPredicate<TSource>): TyneqSequence<TSource>;
+    /**
+     * Yields elements between `start` (inclusive) and `end` (exclusive) by index.
+     *
+     * @remarks
+     * Deferred. Enumerates only as far as `end`.
+     * When `end` is omitted, yields all elements from `start` to the end of the sequence.
+     * Returns an empty sequence when `start` is beyond the sequence length.
+     *
+     * @example
+     * ```ts
+     * Tyneq.from([0, 1, 2, 3, 4]).slice(1, 4).toArray();
+     * // [1, 2, 3]
+     *
+     * Tyneq.from([0, 1, 2, 3, 4]).slice(2).toArray();
+     * // [2, 3, 4]
+     * ```
+     *
+     * @throws {ArgumentOutOfRangeError} When `start` is negative.
+     * @throws {ArgumentOutOfRangeError} When `end` is negative or less than `start`.
+     */
+    slice(start: number, end?: number): TyneqSequence<TSource>;
+    /**
+     * Splits the sequence at elements where `splitOn` returns `true`.
+     *
+     * @remarks
+     * The delimiter elements are consumed and not included in any sub-array.
+     *
+     * @throws {ArgumentNullError} When `splitOn` is null.
+     * @throws {ArgumentError} When `splitOn` is undefined.
+     */
+    split(splitOn: (item: TSource) => boolean): TyneqSequence<TSource[]>;
+    /**
+     * Takes at most the first `count` elements.
+     *
+     * @throws {ArgumentError} When `count` is not a safe integer.
+     * @throws {ArgumentOutOfRangeError} When `count` is negative.
+     */
+    take(count: number): TyneqSequence<TSource>;
+    /**
+     * Yields elements until `predicate` returns `true`, then stops.
+     * The element that triggered the predicate is not included.
+     *
+     * @remarks
+     * The predicate receives each element and its zero-based index.
+     * Once the predicate returns `true` the sequence ends immediately.
+     *
+     * @throws {ArgumentNullError} When `predicate` is null.
+     * @throws {ArgumentError} When `predicate` is undefined.
+     */
+    takeUntil(predicate: ItemPredicate<TSource>): TyneqSequence<TSource>;
+    /**
+     * Takes elements while `predicate` returns `true`, then stops.
+     *
+     * @remarks
+     * The predicate receives each element and its zero-based index.
+     *
+     * @throws {ArgumentNullError} When `predicate` is null.
+     * @throws {ArgumentError} When `predicate` is undefined.
+     */
+    takeWhile(predicate: ItemPredicate<TSource>): TyneqSequence<TSource>;
+    /**
+     * Executes `action` for each element as it passes through the pipeline, then yields it unchanged.
+     *
+     * @remarks
+     * The action receives each element and its zero-based index.
+     *
+     * @throws {ArgumentNullError} When `action` is null.
+     * @throws {ArgumentError} When `action` is undefined.
+     */
+    tap(action: ItemAction<TSource>): TyneqSequence<TSource>;
+    /**
+     * Executes `action` for each element only while `predicate()` returns `true`.
+     *
+     * @remarks
+     * The action receives each element and its zero-based index.
+     *
+     * @throws {ArgumentNullError} When `action` or `predicate` is null.
+     * @throws {ArgumentError} When `action` or `predicate` is undefined.
+     */
+    tapIf(action: ItemAction<TSource>, predicate: () => boolean): TyneqSequence<TSource>;
+    /**
+     * Yields every `count`-th element (i.e. elements at indices 0, `count`, `2*count`, ...).
+     *
+     * @throws {ArgumentError} When `count` is not a safe integer.
+     * @throws {ArgumentOutOfRangeError} When `count` is less than or equal to `0`.
+     */
+    throttle(count: number): TyneqSequence<TSource>;
+    /**
+     * Yields only elements for which `predicate` returns `true`.
+     *
+     * @remarks
+     * The predicate receives each element and its zero-based index.
+     *
+     * @throws {ArgumentNullError} When `predicate` is null.
+     * @throws {ArgumentError} When `predicate` is undefined.
+     */
+    where(predicate: ItemPredicate<TSource>): TyneqSequence<TSource>;
+    /**
+     * Pairs each element with the corresponding element from `other` using `selector`.
+     *
+     * @remarks
+     * Stops at the shorter of the two sequences.
+     *
+     * @throws {ArgumentNullError} When `other` or `selector` is null.
+     * @throws {ArgumentError} When `other` or `selector` is undefined.
+     * @throws {ArgumentTypeError} When `other` is not iterable.
+     */
+    zip<TOther, TResult>(other: Iterable<TOther>, selector: (first: TSource, second: TOther) => TResult): TyneqSequence<TResult>;
+    /** Returns the sequence without duplicate elements, using SameValueZero (Set) equality. */
+    distinct(): TyneqSequence<TSource>;
+    /**
+     * Returns the sequence without duplicate elements, comparing by the result of `keySelector`.
+     *
+     * @throws {ArgumentNullError} When `keySelector` is null.
+     * @throws {ArgumentError} When `keySelector` is undefined.
+     */
+    distinctBy<TKey>(keySelector: (item: TSource) => TKey): TyneqSequence<TSource>;
+    /** Returns elements not present in `excludedValues`, using SameValueZero (Set) equality. */
+    except(excludedValues: Iterable<TSource>): TyneqSequence<TSource>;
+    /**
+     * Returns elements whose key (via `keySelector`) is not found in `excludedKeys`.
+     *
+     * @throws {ArgumentNullError} When `keySelector` is null.
+     * @throws {ArgumentError} When `keySelector` is undefined.
+     */
+    exceptBy<TKey>(excludedKeys: Iterable<TKey>, keySelector: (item: TSource) => TKey): TyneqSequence<TSource>;
+    /**
+     * Groups elements by key and projects each group with `resultSelector`.
+     *
+     * @throws {ArgumentNullError} When `keySelector`, `valueSelector`, or `resultSelector` is null.
+     * @throws {ArgumentError} When `keySelector`, `valueSelector`, or `resultSelector` is undefined.
+     */
+    groupBy<TKey, TValue, TResult>(keySelector: (item: TSource) => TKey, valueSelector: (item: TSource) => TValue, resultSelector: (key: TKey, values: TyneqSequence<TValue>) => TResult): TyneqSequence<TResult>;
+    /**
+     * Performs a left outer join: each outer element is paired with its matching inner group.
+     *
+     * @remarks
+     * Elements with no match in `inner` receive an empty group.
+     *
+     * @throws {ArgumentNullError} When any selector is null.
+     * @throws {ArgumentError} When any selector is undefined.
+     * @throws {ArgumentTypeError} When `inner` is not iterable.
+     */
+    groupJoin<TInner, TKey, TResult>(inner: Iterable<TInner>, outerKeySelector: (outer: TSource) => TKey, innerKeySelector: (inner: TInner) => TKey, resultSelector: (outer: TSource, group: TyneqSequence<TInner>) => TResult): TyneqSequence<TResult>;
+    /** Returns elements that are also present in `intersectedValues`, using SameValueZero (Set) equality. */
+    intersect(intersectedValues: Iterable<TSource>): TyneqSequence<TSource>;
+    /**
+     * Returns elements whose key (via `keySelector`) is found in `intersectedKeys`.
+     *
+     * @throws {ArgumentNullError} When `keySelector` is null.
+     * @throws {ArgumentError} When `keySelector` is undefined.
+     */
+    intersectBy<TKey>(intersectedKeys: Iterable<TKey>, keySelector: (item: TSource) => TKey): TyneqSequence<TSource>;
+    /**
+     * Performs an inner join: produces one result for each matching pair of outer and inner elements.
+     *
+     * @throws {ArgumentNullError} When any selector is null.
+     * @throws {ArgumentError} When any selector is undefined.
+     */
+    join<TInner, TKey, TResult>(inner: Iterable<TInner>, outerKeySelector: (outer: TSource) => TKey, innerKeySelector: (inner: TInner) => TKey, resultSelector: (outer: TSource, inner: TInner) => TResult): TyneqSequence<TResult>;
+    /**
+     * Returns a sequence that caches elements incrementally as they are iterated.
+     *
+     * @remarks
+     * Subsequent iterations replay the cache; the source is only iterated once.
+     * Call `refresh()` on the returned sequence to clear the cache and re-enumerate the source.
+     */
+    memoize(): TyneqCachedSequence<TSource>;
+    /**
+     * Returns the sequence sorted in ascending order by `keySelector`.
+     *
+     * @remarks
+     * Stable sort. Append `thenBy`/`thenByDescending` for multi-key sorting.
+     *
+     * @throws {ArgumentNullError} When `keySelector` is null.
+     * @throws {ArgumentError} When `keySelector` is undefined.
+     */
+    orderBy<TKey>(keySelector: (item: TSource) => TKey, comparer?: Comparer<TKey>): TyneqOrderedSequence<TSource>;
+    /**
+     * Returns the sequence sorted in descending order by `keySelector`.
+     *
+     * @remarks
+     * Stable sort. Append `thenBy`/`thenByDescending` for multi-key sorting.
+     *
+     * @throws {ArgumentNullError} When `keySelector` is null.
+     * @throws {ArgumentError} When `keySelector` is undefined.
+     */
+    orderByDescending<TKey>(keySelector: (item: TSource) => TKey, comparer?: Comparer<TKey>): TyneqOrderedSequence<TSource>;
+    /**
+     * Returns all possible permutations of the sequence.
+     *
+     * @remarks
+     * O(n!) time and O(n) auxiliary memory. Use only on short sequences.
+     * For a sequence of length n, produces n! result arrays, each of length n.
+     */
+    permutations(): TyneqSequence<TSource[]>;
+    /** Returns the sequence in reverse order. */
+    reverse(): TyneqSequence<TSource>;
+    /**
+     * Returns the sequence in random order using `Math.random()`.
+     *
+     * @remarks
+     * Uses the Fisher-Yates shuffle. Not cryptographically secure.
+     */
+    shuffle(): TyneqSequence<TSource>;
+    /**
+     * Inserts elements from `other` into the sequence at `index`.
+     *
+     * @remarks
+     * `index` is zero-based and counts from the end of the sequence.
+     * Use `0` to append after the last element, `1` to insert before the last element.
+     *
+     * @example
+     * ```ts
+     * Tyneq.from([1, 2, 3]).backsert(0, [4, 5]).toArray();
+     * // [1, 2, 3, 4, 5]  (appended)
+     *
+     * Tyneq.from([1, 2, 3]).backsert(1, [99]).toArray();
+     * // [1, 2, 99, 3]  (inserted before the last element)
+     * ```
+     *
+     * @throws {ArgumentOutOfRangeError} When `index` is negative.
+     */
+    backsert(index: number, other: Iterable<TSource>): TyneqSequence<TSource>;
+    /** Returns the distinct elements from both this sequence and `otherValues`, using SameValueZero (Set) equality. */
+    union(otherValues: Iterable<TSource>): TyneqSequence<TSource>;
+    /**
+     * Returns the elements from both sequences whose keys are distinct.
+     *
+     * @throws {ArgumentNullError} When `keySelector` is null.
+     * @throws {ArgumentError} When `keySelector` is undefined.
+     */
+    unionBy<TKey>(otherValues: Iterable<TSource>, keySelector: (item: TSource) => TKey): TyneqSequence<TSource>;
+    /**
+     * Passes this sequence through a custom `factory` function and wraps the result.
+     *
+     * @remarks
+     * The returned sequence tracks a `"pipe"` node in the query plan, with `factory` recorded
+     * as the argument. Use this for one-off operator compositions that do not need to be
+     * registered via the plugin API.
+     *
+     * @throws {ArgumentNullError} When `factory` is null.
+     * @throws {ArgumentError} When `factory` is undefined.
+     */
+    pipe<TResult>(factory: (source: Iterable<TSource>) => Enumerator<TResult> | IterableIterator<TResult>): TyneqSequence<TResult>;
+    /**
+     * Returns a sequence of running aggregates.
+     *
+     * @remarks
+     * The first element of the output is `accumulator(seed, source[0])`. Returns an empty sequence when the source is empty.
+     *
+     * @throws {ArgumentNullError} When `accumulator` is null.
+     * @throws {ArgumentError} When `accumulator` is undefined.
+     */
+    scan<TResult>(seed: TResult, accumulator: (acc: TResult, item: TSource) => TResult): TyneqSequence<TResult>;
+    /**
+     * Returns the minimum and maximum element in one pass.
+     *
+     * @remarks
+     * Uses the natural `<` / `>` operators when no comparer is provided.
+     *
+     * @throws {SequenceContainsNoElementsError} When the sequence is empty.
+     */
+    minMax(comparer?: Comparer<TSource>): MinMaxResult<TSource>;
+}
+/**
+ * A `TyneqSequence` with additional secondary sort keys applied.
+ *
+ * @remarks
+ * Produced by `orderBy` / `orderByDescending`. Chain `thenBy` / `thenByDescending` to add secondary sort criteria.
+ *
+ * @typeParam TSource - Element type.
+ * @group Interfaces
+ */
+interface TyneqOrderedSequence<TSource> extends TyneqSequence<TSource> {
+    /**
+     * Adds an ascending secondary sort key.
+     *
+     * @throws {ArgumentNullError} When `keySelector` is null.
+     * @throws {ArgumentError} When `keySelector` is undefined.
+     */
+    thenBy<TKey>(keySelector: (item: TSource) => TKey, comparer?: Comparer<TKey>): TyneqOrderedSequence<TSource>;
+    /**
+     * Adds a descending secondary sort key.
+     *
+     * @throws {ArgumentNullError} When `keySelector` is null.
+     * @throws {ArgumentError} When `keySelector` is undefined.
+     */
+    thenByDescending<TKey>(keySelector: (item: TSource) => TKey, comparer?: Comparer<TKey>): TyneqOrderedSequence<TSource>;
+    /** Sets the ordering to ascending according to the current sort keys. */
+    asc(): TyneqOrderedSequence<TSource>;
+    /** Sets the ordering to descending according to the current sort keys. */
+    desc(): TyneqOrderedSequence<TSource>;
+}
+/**
+ * A `TyneqSequence` that caches elements as they are iterated.
+ *
+ * @remarks
+ * Produced by `memoize()`. Call `refresh()` to clear the cache and allow re-enumeration from the source.
+ *
+ * @typeParam TSource - Element type.
+ * @group Interfaces
+ */
+interface TyneqCachedSequence<TSource> extends TyneqSequence<TSource> {
+    /**
+     * Clears the element cache and returns a new `TyneqCachedSequence` that will re-enumerate from the source.
+     */
+    refresh(): TyneqCachedSequence<TSource>;
+}
+/**
+ * Low-level interface for a sequence that supports incremental cache access.
+ *
+ * @typeParam TSource - Element type.
+ * @group Interfaces
+ * @internal
+ */
+interface CachedEnumerable<TSource> extends Enumerable<TSource> {
+    /**
+     * Attempts to return the cached element at `index`.
+     *
+     * @returns `{ has: true, value }` if cached, `{ has: false }` otherwise.
+     */
+    tryGetAtFromCache(index: number): CacheResult<TSource>;
+}
+/** Result returned by the cache-lookup method on a memoized sequence. */
+type CacheResult<TSource> = {
+    has: true;
+    value: TSource;
+} | {
+    has: false;
+};
+/**
+ * Low-level interface for a sequence that can produce a sort comparator.
+ *
+ * @remarks
+ * Implemented by `TyneqOrderedEnumerable`. Consumed by the ordering infrastructure.
+ *
+ * @typeParam TSource - Element type.
+ * @group Interfaces
+ * @internal
+ */
+interface OrderedEnumerable<TSource> extends Enumerable<TSource> {
+    source: TyneqSequence<TSource>;
+    /** The parent ordering level, or `null` for the primary sort. */
+    parent: Nullable<OrderedEnumerable<TSource>>;
+    /**
+     * Produces a sorter chain that combines this level with any chained levels.
+     *
+     * @param next - The child sorter, or `null` if this is the innermost level.
+     */
+    getSorter(next: Nullable<BaseEnumerableSorter<TSource>>): BaseEnumerableSorter<TSource>;
+}
+/** Result of `minMax()`, containing both the minimum and maximum elements. */
+type MinMaxResult<T> = {
+    readonly min: T;
+    readonly max: T;
+};
+/** A key-value pair used by `toMap()` and `toRecord()` selectors. */
+type KeyValuePair<TKey, TValue> = {
+    key: TKey;
+    value: TValue;
+};
+/**
+ * Structural interface used by registration machinery to call the protected factory methods
+ * on sequence classes without exposing them publicly.
+ *
+ * The double-cast `(this as unknown as SequenceFactory<T>)` is intentional:
+ * these methods are `protected`, so the cast is the only way to call them from
+ * outside the class hierarchy without changing their access modifier.
+ *
+ * @internal
+ */
+interface SequenceFactory<TSource> {
+    readonly [tyneqQueryNode]: Nullable<QueryPlanNode>;
+    createEnumerable(factory: {
+        getEnumerator(): unknown;
+    }, node?: Nullable<QueryPlanNode>): unknown;
+    createOrderedEnumerable<TKey>(keySelector: (x: TSource) => TKey, comparer: Comparer<TKey>, descending: boolean, node?: Nullable<QueryPlanNode>): TyneqOrderedSequence<TSource>;
+    createCachedEnumerable(source: TyneqSequence<TSource>, node?: Nullable<QueryPlanNode>): TyneqCachedSequence<TSource>;
+}
+/** A fully resolved operator entry: metadata plus the prototype-level implementation. */
+interface OperatorEntry {
+    readonly metadata: OperatorMetadata;
+    readonly impl: BoundMethod<TyneqEnumerableBase<unknown>>;
+}
+/** Source of an operator implementation, used internally to track where operators come from. */
+type OperatorSource = "internal" | "external";
+/** Kind of an operator, used internally to categorize operators. Extends `OperatorCategory` with registry-only kinds. */
+type OperatorKind = OperatorCategory | "cache" | "extension" | "unknown";
+/** Constructor type for a sequence class. */
+type SequenceConstructor = abstract new (...args: any[]) => TyneqEnumerableCore<unknown>;
+
+export { TyneqEnumerableBase as $, type Action as A, type BoundMethod as B, type Comparer as C, type OrderedEnumerable as D, type Enumerator as E, type Factory as F, type GenericFunction as G, type HasLength as H, type ItemSelector as I, QueryNode as J, type KeyValuePair as K, type QueryPlanTraversalDirection as L, type Maybe as M, type Nullable as N, type OperatorSource as O, type Predicate as P, type QueryPlanVisitor as Q, type SequenceFactory as R, type SequenceConstructor as S, type TyneqSequence as T, type SourceKind as U, type TyneqCachedSequence as V, type TyneqEnumerableFactory as W, type TyneqOrderedSequence as X, type WithProperties as Y, isSourceNode as Z, tyneqQueryNode as _, type Optional as a, BaseEnumerableSorter as a0, OperatorMetadata as b, type QueryPlanPrinterOptions as c, type QueryPlanNode as d, type QueryPlanWalkerOptions as e, type Assume as f, type CacheResult as g, type CachedEnumerable as h, type Cast as i, type Constructor as j, type Enumerable as k, type EnumeratorFactory as l, type EqualityComparer as m, type FieldKeys as n, type Func as o, type InstanceOf as p, type ItemAction as q, type ItemPredicate as r, type IteratorFactory as s, type Method as t, type MethodKeys as u, type MinMaxResult as v, type NoInfer as w, type OperatorCategory as x, type OperatorEntry as y, type OperatorKind as z };