tyneq 1.0.0

package/dist/TyneqCachedTerminalOperator.d.cts

@@ -0,0 +1,724 @@
+import { L as Constructor, M as tyneqQueryNode, S as TyneqEnumerableBase, T as QueryPlanNode, Z as Nullable, _ as TyneqCachedSequence, a as Enumerator, b as TyneqSequence, i as Enumerable, m as OrderedEnumerable, n as CachedEnumerable, o as EnumeratorFactory, p as OperatorSource, r as Comparer, t as CacheResult, tt as BaseEnumerableSorter, y as TyneqOrderedSequence } from "./core.cjs";
+
+//#region src/plugin/decorators/operator.d.ts
+/**
+ * Class decorator that registers a `TyneqEnumerator` subclass as an operator on every sequence.
+ *
+ * Validation runs eagerly at the call site, before the lazy enumerator is created.
+ *
+ * @param name - Method name to expose on every sequence.
+ * @param category - Operator kind (`"streaming"` | `"buffer"`).
+ * @param validate - Optional eager validation function for user-supplied arguments.
+ *
+ * @example
+ * ```ts
+ * import { operator, TyneqEnumerator } from "tyneq/plugin";
+ * import type { Enumerator } from "tyneq";
+ *
+ * @operator<[predicate: (item: unknown) => boolean]>("myFilter", "streaming", (predicate) => {
+ *     if (typeof predicate !== "function") throw new Error("predicate must be a function");
+ * })
+ * class MyFilterEnumerator<T> extends TyneqEnumerator<T> {
+ *     public constructor(source: Enumerator<T>, private readonly predicate: (item: T) => boolean) {
+ *         super(source);
+ *     }
+ *     protected handleNext(): IteratorResult<T> {
+ *         while (true) {
+ *             const next = this.sourceEnumerator.next();
+ *             if (next.done || this.predicate(next.value)) return next;
+ *         }
+ *     }
+ * }
+ * ```
+ *
+ * @group Decorators
+ */
+declare function operator<TArgs extends unknown[] = never>(name: string, category: "streaming" | "buffer", validate?: (...args: TArgs) => void): <TClass extends new (...args: any[]) => any>(target: TClass, _context: ClassDecoratorContext) => TClass;
+//#endregion
+//#region src/plugin/decorators/orderedOperator.d.ts
+/**
+ * Class decorator that registers a `TyneqOrderedEnumerator` subclass as an operator
+ * available only on ordered sequences.
+ *
+ * The enumerator constructor receives the full `TyneqOrderedEnumerable` as its first
+ * argument (not just an `Enumerator<T>`).
+ *
+ * @param name - Method name to expose on ordered sequences.
+ * @param category - Operator kind (`"streaming"` | `"buffer"`).
+ * @param validate - Optional eager validation function for user-supplied arguments.
+ *
+ * @example
+ * ```ts
+ * import { orderedOperator, TyneqOrderedEnumerator } from "tyneq/plugin";
+ *
+ * @orderedOperator("myThenBy", "buffer", (keySelector) => {
+ *     if (typeof keySelector !== "function") throw new Error("keySelector must be a function");
+ * })
+ * class MyThenByEnumerator<T> extends TyneqOrderedEnumerator<T> {
+ *     private readonly iter: Enumerator<T>;
+ *     public constructor(source: OrderedEnumerable<T>, private readonly keySelector: (item: T) => unknown) {
+ *         super(source);
+ *         this.iter = this.orderedSource.getEnumerator();
+ *     }
+ *     protected handleNext(): IteratorResult<T> {
+ *         // this.orderedSource gives access to the full OrderedEnumerable
+ *         return this.iter.next();
+ *     }
+ * }
+ * ```
+ *
+ * @group Decorators
+ */
+declare function orderedOperator<TArgs extends unknown[] = never>(name: string, category: "streaming" | "buffer", validate?: (...args: TArgs) => void): <TClass extends Constructor<any>>(target: TClass, _context: ClassDecoratorContext<TClass>) => TClass;
+//#endregion
+//#region src/plugin/decorators/cachedOperator.d.ts
+/**
+ * Class decorator that registers a `TyneqCachedEnumerator` subclass as an operator
+ * available only on cached sequences.
+ *
+ * The enumerator constructor receives the full `TyneqCachedEnumerable` as its first
+ * argument (not just an `Enumerator<T>`).
+ *
+ * @param name - Method name to expose on cached sequences.
+ * @param category - Operator kind (`"streaming"` | `"buffer"`).
+ * @param validate - Optional eager validation function for user-supplied arguments.
+ *
+ * @example
+ * ```ts
+ * import { cachedOperator, TyneqCachedEnumerator } from "tyneq/plugin";
+ *
+ * @cachedOperator("myRefresh", "buffer")
+ * class MyRefreshEnumerator<T> extends TyneqCachedEnumerator<T> {
+ *     private readonly iter: Enumerator<T>;
+ *     public constructor(source: CachedEnumerable<T>) {
+ *         super(source);
+ *         this.iter = this.cachedSource.getEnumerator();
+ *     }
+ *     protected handleNext(): IteratorResult<T> {
+ *         // this.cachedSource gives access to the full CachedEnumerable
+ *         return this.iter.next();
+ *     }
+ * }
+ * ```
+ *
+ * @group Decorators
+ */
+declare function cachedOperator<TArgs extends unknown[] = never>(name: string, category: "streaming" | "buffer", validate?: (...args: TArgs) => void): <TClass extends Constructor<any>>(target: TClass, _context: ClassDecoratorContext<TClass>) => TClass;
+//#endregion
+//#region src/plugin/decorators/terminal.d.ts
+/**
+ * Class decorator that registers a class as a terminal operator.
+ *
+ * The class must have a `process()` method returning the result.
+ * Validation runs eagerly at the call site before the class is instantiated.
+ *
+ * @param name - Method name to expose on every sequence.
+ * @param validate - Optional eager validation function for user-supplied arguments.
+ *
+ * @example
+ * ```ts
+ * import { terminal } from "tyneq/plugin";
+ * import { TyneqTerminalOperator } from "tyneq/plugin";
+ * import type { Enumerable } from "tyneq";
+ *
+ * @terminal("product")
+ * class ProductOperator extends TyneqTerminalOperator<number, number> {
+ *     public process(): number {
+ *         let result = 1;
+ *         for (const item of this.source) result *= item;
+ *         return result;
+ *     }
+ * }
+ * ```
+ *
+ * @group Decorators
+ */
+declare function terminal<TArgs extends unknown[] = never>(name: string, validate?: (...args: TArgs) => void): <TClass extends new (...args: any[]) => {
+  process(): unknown;
+}>(target: TClass, _context: ClassDecoratorContext) => TClass;
+//#endregion
+//#region src/plugin/decorators/orderedTerminal.d.ts
+/**
+ * Class decorator that registers a `TyneqOrderedTerminalOperator` subclass as a terminal
+ * operator available only on ordered sequences.
+ *
+ * The class constructor receives the full `OrderedEnumerable` as its first argument,
+ * giving access to ordered-sequence members (comparers, parent chain, etc.).
+ *
+ * @param name - Method name to expose on ordered sequences.
+ * @param validate - Optional eager validation function for user-supplied arguments.
+ *
+ * @example
+ * ```ts
+ * @orderedTerminal("isSorted")
+ * class IsSortedOperator<T> extends TyneqOrderedTerminalOperator<T, boolean> {
+ *     process(): boolean {
+ *         const items = [...this.source];
+ *         for (let i = 1; i < items.length; i++) {
+ *             if (this.source.comparer(items[i - 1], items[i]) > 0) return false;
+ *         }
+ *         return true;
+ *     }
+ * }
+ * ```
+ *
+ * @group Decorators
+ */
+declare function orderedTerminal<TArgs extends unknown[] = never>(name: string, validate?: (...args: TArgs) => void): <TClass extends Constructor<{
+  process(): unknown;
+}>>(target: TClass, _context: ClassDecoratorContext<TClass>) => TClass;
+//#endregion
+//#region src/plugin/decorators/cachedTerminal.d.ts
+/**
+ * Class decorator that registers a `TyneqCachedTerminalOperator` subclass as a terminal
+ * operator available only on cached sequences.
+ *
+ * The class constructor receives the full `CachedEnumerable` as its first argument,
+ * giving access to cached-sequence members (`refresh()`, internal cache, etc.).
+ *
+ * @param name - Method name to expose on cached sequences.
+ * @param validate - Optional eager validation function for user-supplied arguments.
+ *
+ * @example
+ * ```ts
+ * @cachedTerminal("cacheSize")
+ * class CacheSizeOperator<T> extends TyneqCachedTerminalOperator<T, number> {
+ *     process(): number {
+ *         return [...this.source].length;
+ *     }
+ * }
+ * ```
+ *
+ * @group Decorators
+ */
+declare function cachedTerminal<TArgs extends unknown[] = never>(name: string, validate?: (...args: TArgs) => void): <TClass extends Constructor<{
+  process(): unknown;
+}>>(target: TClass, _context: ClassDecoratorContext<TClass>) => TClass;
+//#endregion
+//#region src/plugin/registration/createOperator.d.ts
+/**
+ * Registers a streaming or buffering operator using a factory function.
+ *
+ * Use this when the operator requires a class-level enumerator with custom state
+ * but you want to avoid writing the decorator boilerplate. For simpler generator-based
+ * operators, prefer {@link createGeneratorOperator}.
+ *
+ * @param config.name - Method name to expose on every sequence.
+ * @param config.category - `"streaming"` or `"buffer"`.
+ * @param config.factory - Returns an `EnumeratorFactory` given the source and arguments.
+ * @param config.validate - Optional eager validation for user-supplied arguments.
+ *
+ * @example
+ * ```ts
+ * import { createOperator } from "tyneq/plugin";
+ * import type { Enumerator } from "tyneq";
+ *
+ * createOperator({
+ *     name: "everyOther",
+ *     category: "streaming",
+ *     factory: <T>(source: Enumerable<T>) => ({
+ *         getEnumerator(): Enumerator<T> {
+ *             let skip = false;
+ *             const iter = source[Symbol.iterator]();
+ *             return {
+ *                 next(): IteratorResult<T> {
+ *                     while (true) {
+ *                         const r = iter.next();
+ *                         if (r.done) return r;
+ *                         if (!skip) { skip = true; return r; }
+ *                         skip = false;
+ *                     }
+ *                 }
+ *             };
+ *         }
+ *     })
+ * });
+ * ```
+ *
+ * @group Factory Functions
+ */
+declare function createOperator<TSource, TArgs extends unknown[], TResult>(config: {
+  name: string;
+  category: "streaming" | "buffer";
+  factory: (source: Enumerable<TSource>, ...args: TArgs) => EnumeratorFactory<TResult>;
+  validate?: (...args: NoInfer<TArgs>) => void;
+  source?: OperatorSource;
+}): void;
+//#endregion
+//#region src/plugin/registration/createGeneratorOperator.d.ts
+/**
+ * Registers an operator using a generator function.
+ *
+ * The generator receives the source as an `Iterable<T>` and any user arguments.
+ * This is the simplest functional registration path and works for both streaming
+ * and buffering use cases:
+ *
+ * - **Streaming**: yield elements one at a time as they arrive. The downstream
+ *   sequence only pulls the next element when needed.
+ * - **Buffering**: collect all input first, then yield the transformed output.
+ *   Pass `category: "buffer"` to tell the query plan that this operator
+ *   materialises the entire upstream before yielding.
+ *
+ * For class-based enumerators with custom stateful logic, prefer {@link createOperator}.
+ *
+ * @param config.name - Method name to expose on every sequence.
+ * @param config.category - `"streaming"` (default) or `"buffer"`.
+ * @param config.generator - Generator that yields transformed elements from `source`.
+ * @param config.validate - Optional eager validation for user-supplied arguments.
+ *
+ * @example Streaming - yield elements lazily one at a time:
+ * ```ts
+ * import { createGeneratorOperator } from "tyneq/plugin";
+ *
+ * createGeneratorOperator({
+ *     name: "everyOther",
+ *     *generator(source) {
+ *         let skip = false;
+ *         for (const item of source) {
+ *             if (!skip) yield item;
+ *             skip = !skip;
+ *         }
+ *     }
+ * });
+ * ```
+ *
+ * @example Buffering - materialise the entire input first, then yield results:
+ * ```ts
+ * import { createGeneratorOperator } from "tyneq/plugin";
+ *
+ * createGeneratorOperator({
+ *     name: "sortedBy",
+ *     category: "buffer",
+ *     *generator(source, keyFn: (x: number) => number) {
+ *         const items = [...source].sort((a, b) => keyFn(a) - keyFn(b));
+ *         for (const item of items) yield item;
+ *     }
+ * });
+ * ```
+ *
+ * @group Factory Functions
+ */
+declare function createGeneratorOperator<TSource, TArgs extends unknown[], TResult>(config: {
+  name: string;
+  category?: "streaming" | "buffer";
+  generator: (source: Iterable<TSource>, ...args: TArgs) => IterableIterator<TResult>;
+  validate?: (...args: NoInfer<TArgs>) => void;
+  source?: OperatorSource;
+}): void;
+//#endregion
+//#region src/core/ordering/TyneqOrderedEnumerable.d.ts
+/**
+ * Concrete implementation of {@link TyneqOrderedSequence}.
+ *
+ * @remarks
+ * Created by `orderBy` and `orderByDescending`. Chains to a parent `TyneqOrderedEnumerable`
+ * via `thenBy` / `thenByDescending` to build a multi-key sorter.
+ *
+ * @internal
+ */
+declare class TyneqOrderedEnumerable<TSource, TKey> extends TyneqEnumerableBase<TSource> implements TyneqOrderedSequence<TSource> {
+  private readonly keySelector;
+  private readonly comparer;
+  private readonly descending;
+  readonly source: TyneqSequence<TSource>;
+  readonly parent: Nullable<OrderedEnumerable<TSource>>;
+  readonly [tyneqQueryNode]: Nullable<QueryPlanNode>;
+  constructor(source: TyneqSequence<TSource>, keySelector: (item: TSource) => TKey, comparer: Comparer<TKey>, descending: boolean, parent?: OrderedEnumerable<TSource>, node?: Nullable<QueryPlanNode>);
+  asc(): TyneqOrderedSequence<TSource>;
+  desc(): TyneqOrderedSequence<TSource>;
+  getEnumerator(): Enumerator<TSource>;
+  getSorter(next: Nullable<BaseEnumerableSorter<TSource>>): BaseEnumerableSorter<TSource>;
+  thenBy<UKey>(keySelector: (item: TSource) => UKey, comparer?: Comparer<UKey>): TyneqOrderedSequence<TSource>;
+  thenByDescending<UKey>(keySelector: (item: TSource) => UKey, comparer?: Comparer<UKey>): TyneqOrderedSequence<TSource>;
+  protected createEnumerable<TResult>(factory: EnumeratorFactory<TResult>, node: Nullable<QueryPlanNode>): TyneqSequence<TResult>;
+  protected createOrderedEnumerable<TKey>(keySelector: (x: TSource) => TKey, comparer: Comparer<TKey>, descending: boolean, node: Nullable<QueryPlanNode>): TyneqOrderedSequence<TSource>;
+  protected createCachedEnumerable(source: TyneqSequence<TSource>, node: Nullable<QueryPlanNode>): TyneqCachedSequence<TSource>;
+}
+//#endregion
+//#region src/plugin/registration/createOrderedOperator.d.ts
+/**
+ * Registers a factory function as an operator available only on ordered sequences,
+ * where the factory fully controls the return type.
+ *
+ * Use this when the operator must return a `TyneqOrderedSequence` (e.g. a `thenBy` variant).
+ * The factory receives the ordered source and a query plan node. It is responsible for
+ * constructing and returning the result sequence - typically by instantiating
+ * `TyneqOrderedEnumerable` directly.
+ *
+ * For operators that return a plain sequence from an enumerator class, use `@orderedOperator`.
+ *
+ * @param config.name - Method name to expose on ordered sequences.
+ * @param config.category - Operator kind (`"streaming"` | `"buffer"`).
+ * @param config.factory - Constructs the result sequence from `(source, node, ...userArgs)`.
+ * @param config.validate - Optional eager validation function for user-supplied arguments.
+ *
+ * @example
+ * ```ts
+ * createOrderedOperator({
+ *     name: "thenByLocale",
+ *     category: "buffer",
+ *     factory: (source, node, locale: string, keySelector: (item: unknown) => string) =>
+ *         new TyneqOrderedEnumerable(
+ *             source.source,
+ *             keySelector,
+ *             (a, b) => a.localeCompare(b, locale),
+ *             false,
+ *             source,
+ *             node
+ *         ),
+ *     validate: (locale, keySelector) => {
+ *         if (typeof locale !== "string") throw new Error("locale must be a string");
+ *         if (typeof keySelector !== "function") throw new Error("keySelector must be a function");
+ *     }
+ * });
+ * ```
+ *
+ * @group Factory Functions
+ */
+declare function createOrderedOperator<TSource, TArgs extends unknown[]>(config: {
+  name: string;
+  category: "streaming" | "buffer";
+  factory: (source: TyneqOrderedEnumerable<TSource, unknown>, node: QueryPlanNode, ...args: TArgs) => TyneqOrderedSequence<TSource>;
+  validate?: (...args: NoInfer<TArgs>) => void;
+  source?: OperatorSource;
+}): void;
+//#endregion
+//#region src/core/TyneqCachedEnumerable.d.ts
+/**
+ * Concrete implementation of {@link TyneqCachedSequence} - caches elements incrementally.
+ *
+ * @remarks
+ * Created by `memoize()`. On the first iteration the source is enumerated one element at a time
+ * and each element is appended to an internal array. Subsequent iterations replay the cache;
+ * the source is not re-enumerated. Call `refresh()` to clear the cache and start over.
+ *
+ * @internal
+ */
+declare class TyneqCachedEnumerable<TSource> extends TyneqEnumerableBase<TSource> implements TyneqCachedSequence<TSource>, CachedEnumerable<TSource> {
+  private source;
+  private cache;
+  private done;
+  private sourceEnumerator;
+  readonly [tyneqQueryNode]: Nullable<QueryPlanNode>;
+  constructor(source: TyneqSequence<TSource>, node?: Nullable<QueryPlanNode>);
+  getEnumerator(): Enumerator<TSource>;
+  refresh(): TyneqCachedSequence<TSource>;
+  tryGetAtFromCache(index: number): CacheResult<TSource>;
+  protected createEnumerable<TResult>(factory: EnumeratorFactory<TResult>, node: Nullable<QueryPlanNode>): TyneqSequence<TResult>;
+  protected createOrderedEnumerable<TKey>(keySelector: (x: TSource) => TKey, comparer: Comparer<TKey>, descending: boolean, node: Nullable<QueryPlanNode>): TyneqOrderedSequence<TSource>;
+  protected createCachedEnumerable(source: TyneqSequence<TSource>, node: Nullable<QueryPlanNode>): TyneqCachedSequence<TSource>;
+}
+//#endregion
+//#region src/plugin/registration/createCachedOperator.d.ts
+/**
+ * Registers a factory function as an operator available only on cached sequences,
+ * where the factory fully controls the return type.
+ *
+ * Use this when the operator must return a `TyneqCachedSequence`. The factory
+ * receives the cached source and a query plan node. It is responsible for
+ * constructing and returning the result sequence.
+ *
+ * For operators that return a plain sequence from an enumerator class, use `@cachedOperator`.
+ *
+ * @param config.name - Method name to expose on cached sequences.
+ * @param config.category - Operator kind (`"streaming"` | `"buffer"`).
+ * @param config.factory - Constructs the result sequence from `(source, node, ...userArgs)`.
+ * @param config.validate - Optional eager validation function for user-supplied arguments.
+ *
+ * @example
+ * ```ts
+ * createCachedOperator({
+ *     name: "refreshWith",
+ *     category: "buffer",
+ *     factory: (source, node, newSource: Iterable<unknown>) => {
+ *         const seq = tyneqFrom(newSource);
+ *         return new TyneqCachedEnumerable(seq, node);
+ *     },
+ *     validate: (newSource) => {
+ *         if (newSource == null) throw new Error("newSource must not be null");
+ *     }
+ * });
+ * ```
+ *
+ * @group Factory Functions
+ */
+declare function createCachedOperator<TSource, TArgs extends unknown[]>(config: {
+  name: string;
+  category: "streaming" | "buffer";
+  factory: (source: TyneqCachedEnumerable<TSource>, node: QueryPlanNode, ...args: TArgs) => TyneqCachedSequence<TSource>;
+  validate?: (...args: NoInfer<TArgs>) => void;
+  source?: OperatorSource;
+}): void;
+//#endregion
+//#region src/plugin/registration/createTerminalOperator.d.ts
+/**
+ * Registers a terminal operator using a plain function.
+ *
+ * The simplest registration API for terminal operators.
+ * `execute` receives the full source sequence and any user arguments and returns a concrete value.
+ *
+ * @param config.name - Method name to expose on every sequence.
+ * @param config.execute - Function that consumes the source and returns a result.
+ * @param config.validate - Optional eager validation for user-supplied arguments.
+ *
+ * @example
+ * ```ts
+ * import { createTerminalOperator } from "tyneq/plugin";
+ *
+ * createTerminalOperator({
+ *     name: "product",
+ *     execute(source: Iterable<number>): number {
+ *         let result = 1;
+ *         for (const item of source) result *= item;
+ *         return result;
+ *     }
+ * });
+ * ```
+ *
+ * @group Factory Functions
+ */
+declare function createTerminalOperator<TSource, TArgs extends unknown[], TResult>(config: {
+  name: string;
+  execute: (source: Enumerable<TSource>, ...args: TArgs) => TResult;
+  validate?: (...args: NoInfer<TArgs>) => void;
+  source?: OperatorSource;
+}): void;
+//#endregion
+//#region src/plugin/registration/createOrderedTerminalOperator.d.ts
+/**
+ * Registers a terminal operator available only on ordered sequences.
+ *
+ * The `execute` function receives the full `OrderedEnumerable` as its first argument,
+ * giving access to ordered-sequence members (comparers, parent chain, etc.).
+ *
+ * @param config.name - Method name to expose on ordered sequences.
+ * @param config.execute - Function that consumes the ordered source and returns a result.
+ * @param config.validate - Optional eager validation for user-supplied arguments.
+ *
+ * @example
+ * ```ts
+ * createOrderedTerminalOperator({
+ *     name: "isSorted",
+ *     execute(source: OrderedEnumerable<number>): boolean {
+ *         const items = [...source];
+ *         for (let i = 1; i < items.length; i++) {
+ *             if (items[i - 1] > items[i]) return false;
+ *         }
+ *         return true;
+ *     }
+ * });
+ * ```
+ *
+ * @group Factory Functions
+ */
+declare function createOrderedTerminalOperator<TSource, TArgs extends unknown[], TResult>(config: {
+  name: string;
+  execute: (source: OrderedEnumerable<TSource>, ...args: TArgs) => TResult;
+  validate?: (...args: NoInfer<TArgs>) => void;
+  source?: OperatorSource;
+}): void;
+//#endregion
+//#region src/plugin/registration/createCachedTerminalOperator.d.ts
+/**
+ * Registers a terminal operator available only on cached sequences.
+ *
+ * The `execute` function receives the full `CachedEnumerable` as its first argument,
+ * giving access to cached-sequence members (`refresh()`, internal cache, etc.).
+ *
+ * @param config.name - Method name to expose on cached sequences.
+ * @param config.execute - Function that consumes the cached source and returns a result.
+ * @param config.validate - Optional eager validation for user-supplied arguments.
+ *
+ * @example
+ * ```ts
+ * createCachedTerminalOperator({
+ *     name: "cacheSize",
+ *     execute(source: CachedEnumerable<unknown>): number {
+ *         return [...source].length;
+ *     }
+ * });
+ * ```
+ *
+ * @group Factory Functions
+ */
+declare function createCachedTerminalOperator<TSource, TArgs extends unknown[], TResult>(config: {
+  name: string;
+  execute: (source: CachedEnumerable<TSource>, ...args: TArgs) => TResult;
+  validate?: (...args: NoInfer<TArgs>) => void;
+  source?: OperatorSource;
+}): void;
+//#endregion
+//#region src/core/enumerators/TyneqBaseEnumerator.d.ts
+/**
+ * Abstract base class implementing the pull-iterator lifecycle for all Tyneq enumerators.
+ *
+ * @remarks
+ * State machine:
+ * - `next()` calls `initialize()` on the first invocation, then delegates to `handleNext()`.
+ * - When `handleNext()` returns `{ done: true }`, `dispose()` is called then the enumerator marks itself completed.
+ * - `doneWithYield(value)` emits one final element, calls `dispose()`, then marks completed.
+ * - `earlyComplete()` calls `dispose()` and marks completed without yielding.
+ * - `return()` triggers early termination: calls `dispose()` then marks completed. Idempotent.
+ * - Once completed, all `next()` calls return `{ done: true }` without re-invoking `handleNext()`.
+ *
+ * Subclasses must implement `handleNext()`. Override `initialize()`, `disposeSource()`, and
+ * `disposeAdditional()` as needed.
+ *
+ * @typeParam TInput - Source element type.
+ * @typeParam TOutput - Output element type (defaults to `TInput`).
+ * @group Plugin
+ */
+declare abstract class TyneqBaseEnumerator<TInput, TOutput = TInput> implements Enumerator<TOutput> {
+  private _initialized;
+  private _completed;
+  constructor();
+  /** Advances the iterator, calling `initialize()` on first call. Idempotent after completion. */
+  next(): IteratorResult<TOutput>;
+  /** Terminates iteration early, disposes resources, and marks completed. Idempotent. */
+  return(value?: unknown): IteratorResult<TOutput>;
+  /** Called once before the first `handleNext()` invocation. Override to set up state. */
+  protected initialize(): void;
+  /** Wraps `value` in a non-done `IteratorResult`. */
+  protected yield(value: TOutput): IteratorResult<TOutput>;
+  /** Returns a done `IteratorResult`. */
+  protected done(): IteratorResult<TOutput>;
+  /**
+   * Marks the enumerator completed and yields `value` as the final element.
+   *
+   * @remarks
+   * Use when the last element must be emitted together with completion in one step.
+   */
+  protected doneWithYield(value: TOutput): IteratorResult<TOutput>;
+  /**
+   * Disposes resources, marks completed, and returns a done result.
+   *
+   * @remarks
+   * Use inside `handleNext()` to terminate iteration before the source is exhausted.
+   */
+  protected earlyComplete(reason?: unknown): IteratorResult<TOutput>;
+  /** Calls `disposeSource()` then `disposeAdditional()`. */
+  protected dispose(value?: unknown): void;
+  /** Override to dispose the upstream source enumerator. */
+  protected disposeSource(): void;
+  /**
+   * Override to release any additional resources.
+   *
+   * @remarks
+   * Called after `disposeSource()`. `value` is the return value passed to `return()`.
+   * Must be idempotent and must not throw.
+   */
+  protected disposeAdditional(_value?: unknown): void;
+  /** Produces the next element. Return `{ done: true }` to signal exhaustion. */
+  protected abstract handleNext(): IteratorResult<TOutput>;
+}
+//#endregion
+//#region src/core/enumerators/TyneqEnumerator.d.ts
+/**
+ * Base class for all pipeline operator enumerators (streaming and buffering).
+ *
+ * @remarks
+ * Extends {@link TyneqBaseEnumerator} with a typed source enumerator.
+ * Override `initialize()` to buffer or prepare state before the first `handleNext()`.
+ * Override `disposeAdditional()` to release resources beyond the source enumerator.
+ *
+ * @typeParam TInput - Source element type.
+ * @typeParam TOutput - Output element type (defaults to `TInput`).
+ * @group Plugin
+ */
+declare abstract class TyneqEnumerator<TInput, TOutput = TInput> extends TyneqBaseEnumerator<TInput, TOutput> {
+  protected readonly sourceEnumerator: Enumerator<TInput>;
+  private sourceDisposed;
+  constructor(sourceEnumerator: Enumerator<TInput>);
+  protected disposeSource(): void;
+}
+//#endregion
+//#region src/core/enumerators/TyneqOrderedEnumerator.d.ts
+/**
+ * Base class for enumerators that need the full ordered sequence (not just an Enumerator<T>).
+ * Lifecycle of the source is owned by the sequence, not the enumerator.
+ *
+ * @group Plugin
+ * @internal
+ */
+declare abstract class TyneqOrderedEnumerator<TSource> extends TyneqBaseEnumerator<TSource> {
+  protected readonly orderedSource: OrderedEnumerable<TSource>;
+  constructor(orderedSource: OrderedEnumerable<TSource>);
+  protected disposeSource(): void;
+}
+//#endregion
+//#region src/core/enumerators/TyneqCachedEnumerator.d.ts
+/**
+ * Base class for enumerators that need the full cached sequence (not just an Enumerator<T>).
+ * Lifecycle of the source is owned by the sequence, not the enumerator.
+ *
+ * @group Plugin
+ * @internal
+ */
+declare abstract class TyneqCachedEnumerator<TSource> extends TyneqBaseEnumerator<TSource> {
+  protected readonly cachedSource: CachedEnumerable<TSource>;
+  constructor(cachedSource: CachedEnumerable<TSource>);
+  protected disposeSource(): void;
+}
+//#endregion
+//#region src/core/terminal/TyneqTerminalOperator.d.ts
+/**
+ * Abstract base for all terminal operators.
+ *
+ * @remarks
+ * Terminal operators consume a sequence and return a concrete value.
+ * Subclasses implement `process()` which enumerates `this.source` and returns the result.
+ * Register with `@terminal` or `createTerminalOperator`.
+ *
+ * @typeParam TSource - Element type of the source sequence.
+ * @typeParam TResult - The return type of `process()`.
+ * @group Plugin
+ */
+declare abstract class TyneqTerminalOperator<TSource, TResult = TSource> {
+  protected readonly source: Enumerable<TSource>;
+  constructor(source: Enumerable<TSource>);
+  /** Executes the terminal operation and returns the result. */
+  abstract process(): TResult;
+}
+//#endregion
+//#region src/core/terminal/TyneqOrderedTerminalOperator.d.ts
+/**
+ * Abstract base for terminal operators that require a fully ordered sequence.
+ *
+ * @remarks
+ * Use this when your terminal operator needs access to ordered-sequence members
+ * (comparers, parent chain, etc.). Register with `@orderedTerminal` or
+ * `createOrderedTerminalOperator`.
+ *
+ * @typeParam TSource - Element type of the source sequence.
+ * @typeParam TResult - The return type of `process()`.
+ * @group Plugin
+ */
+declare abstract class TyneqOrderedTerminalOperator<TSource, TResult = TSource> {
+  protected readonly source: OrderedEnumerable<TSource>;
+  constructor(source: OrderedEnumerable<TSource>);
+  /** Executes the terminal operation and returns the result. */
+  abstract process(): TResult;
+}
+//#endregion
+//#region src/core/terminal/TyneqCachedTerminalOperator.d.ts
+/**
+ * Abstract base for terminal operators that require a fully cached sequence.
+ *
+ * @remarks
+ * Use this when your terminal operator needs access to cached-sequence members
+ * (the internal cache, `refresh()`, etc.). Register with `@cachedTerminal` or
+ * `createCachedTerminalOperator`.
+ *
+ * @typeParam TSource - Element type of the source sequence.
+ * @typeParam TResult - The return type of `process()`.
+ * @group Plugin
+ */
+declare abstract class TyneqCachedTerminalOperator<TSource, TResult = TSource> {
+  protected readonly source: CachedEnumerable<TSource>;
+  constructor(source: CachedEnumerable<TSource>);
+  /** Executes the terminal operation and returns the result. */
+  abstract process(): TResult;
+}
+//#endregion
+export { operator as S, cachedTerminal as _, TyneqOrderedEnumerator as a, cachedOperator as b, createCachedTerminalOperator as c, createCachedOperator as d, TyneqCachedEnumerable as f, createOperator as g, createGeneratorOperator as h, TyneqCachedEnumerator as i, createOrderedTerminalOperator as l, TyneqOrderedEnumerable as m, TyneqOrderedTerminalOperator as n, TyneqEnumerator as o, createOrderedOperator as p, TyneqTerminalOperator as r, TyneqBaseEnumerator as s, TyneqCachedTerminalOperator as t, createTerminalOperator as u, orderedTerminal as v, orderedOperator as x, terminal as y };
+//# sourceMappingURL=TyneqCachedTerminalOperator.d.cts.map