tyneq 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1038 @@
+import { $ as Predicate, A as SourceKind, B as Func, C as QueryNode, D as QueryPlanTraversalDirection, E as QueryPlanPrinterOptions, F as BoundMethod, G as ItemPredicate, H as HasLength, I as Cast, J as Method, K as ItemSelector, L as Constructor, M as tyneqQueryNode, N as Action, O as QueryPlanVisitor, P as Assume, Q as Optional, R as Factory, T as QueryPlanNode, U as InstanceOf, V as GenericFunction, W as ItemAction, X as NoInfer, Y as MethodKeys, Z as Nullable, _ as TyneqCachedSequence, a as Enumerator, b as TyneqSequence, c as IteratorFactory, d as OperatorEntry, et as WithProperties, f as OperatorKind, g as SequenceFactory, h as SequenceConstructor, i as Enumerable, j as isSourceNode, k as QueryPlanWalkerOptions, l as KeyValuePair, m as OrderedEnumerable, n as CachedEnumerable, o as EnumeratorFactory, p as OperatorSource, q as Maybe, r as Comparer, s as EqualityComparer, t as CacheResult, u as MinMaxResult, v as TyneqEnumerableFactory, w as OperatorCategory, x as OperatorMetadata, y as TyneqOrderedSequence, z as FieldKeys } from "./core.js";
+import { a as reflect, c as MemberDescriptor, d as ArgumentUtility, i as ReflectionContext, l as MethodDescriptor, n as Lazy, o as AccessorDescriptor, r as TypeGuardUtility, s as DataDescriptor, t as ValidationBuilder, u as ReflectOptions } from "./ValidationBuilder.js";
+import { S as operator, _ as cachedTerminal, a as TyneqOrderedEnumerator, b as cachedOperator, c as createCachedTerminalOperator, d as createCachedOperator, f as TyneqCachedEnumerable, g as createOperator, h as createGeneratorOperator, i as TyneqCachedEnumerator, l as createOrderedTerminalOperator, m as TyneqOrderedEnumerable, n as TyneqOrderedTerminalOperator, o as TyneqEnumerator, p as createOrderedOperator, r as TyneqTerminalOperator, s as TyneqBaseEnumerator, t as TyneqCachedTerminalOperator, u as createTerminalOperator, v as orderedTerminal, x as orderedOperator, y as terminal } from "./TyneqCachedTerminalOperator.js";
+
+//#region src/core/tyneq.d.ts
+/**
+ * Entry point for creating Tyneq sequences.
+ *
+ * @example
+ * ```ts
+ * import { Tyneq } from "tyneq";
+ *
+ * const sum = Tyneq.from([1, 2, 3, 4, 5])
+ *   .where((x) => x % 2 === 0)
+ *   .sum((x) => x); // -> 6
+ * ```
+ *
+ * @group Classes
+ */
+declare class Tyneq {
+  /**
+   * Creates a lazy sequence from any `Iterable<T>` (arrays, sets, generators, etc.).
+   *
+   * @throws {ArgumentNullError} When `source` is null or undefined.
+   * @throws {ArgumentTypeError} When `source` is not iterable.
+   */
+  static from<TSource>(source: Iterable<TSource>): TyneqSequence<TSource>;
+  private static resolveSourceKind;
+  /**
+   * Creates a sequence of `count` elements produced by calling `randomizer` once per element.
+   *
+   * @remarks
+   * Returns an empty sequence when `count === 0`.
+   *
+   * @throws {ArgumentOutOfRangeError} When `count` is negative.
+   * @throws {ArgumentNullError} When `randomizer` is null or undefined.
+   */
+  static random<TSource>(count: number, randomizer: () => TSource): TyneqSequence<TSource>;
+  /**
+   * Returns `true` if `source` is `null`, `undefined`, or an iterable whose first element is `null` or `undefined`.
+   */
+  static isNullOrEmpty<TSource>(source: Optional<Iterable<TSource>>): boolean;
+  /**
+   * Creates a sequence of `count` integers starting from `start`.
+   *
+   * @remarks
+   * Returns an empty sequence when `count === 0`.
+   *
+   * @example
+   * ```ts
+   * Tyneq.range(1, 5).toArray(); // -> [1, 2, 3, 4, 5]
+   * ```
+   *
+   * @throws {ArgumentOutOfRangeError} When `count` is negative.
+   * @throws {ArgumentError} When `count` is not an integer.
+   */
+  static range(start: number, count: number): TyneqSequence<number>;
+  /** Returns an empty sequence with zero elements. */
+  static empty<TSource>(): TyneqSequence<TSource>;
+  /**
+   * Creates a sequence that yields `value` exactly `count` times.
+   *
+   * @example
+   * ```ts
+   * Tyneq.repeat("x", 3).toArray(); // -> ["x", "x", "x"]
+   * ```
+   *
+   * @throws {ArgumentOutOfRangeError} When `count` is negative.
+   * @throws {ArgumentError} When `count` is not an integer.
+   */
+  static repeat<TSource>(value: TSource, count: number): TyneqSequence<TSource>;
+  /**
+   * Creates a sequence by repeatedly applying `next` to produce each element from the previous one.
+   *
+   * @remarks
+   * The selector receives `(currentValue, index)`. Each call's return value becomes the input
+   * for the next call. Omit `count` for an infinite sequence; pair with `take` to bound it.
+   *
+   * @example
+   * ```ts
+   * Tyneq.generate(1, (x) => x * 2, 4).toArray(); // -> [2, 4, 8, 16]
+   * ```
+   *
+   * @throws {ArgumentNullError} When `next` is null or undefined.
+   * @throws {ArgumentOutOfRangeError} When `count` is negative.
+   * @throws {ArgumentError} When `count` is not an integer.
+   */
+  static generate<TSource, TResult extends TSource>(seed: TSource, next: ItemSelector<TSource, TResult>, count?: number): TyneqSequence<TResult>;
+  /**
+   * Creates a sequence that yields all elements from each source in order.
+   *
+   * @remarks
+   * Returns an empty sequence when called with no arguments.
+   *
+   * @example
+   * ```ts
+   * Tyneq.concat([1, 2], [3, 4], [5]).toArray(); // -> [1, 2, 3, 4, 5]
+   * ```
+   *
+   * @throws {ArgumentNullError} When any `source` is null or undefined.
+   * @throws {ArgumentTypeError} When any `source` is not iterable.
+   */
+  static concat<TSource>(...sources: Iterable<TSource>[]): TyneqSequence<TSource>;
+  /**
+   * Pairs each element with its zero-based index.
+   *
+   * @remarks
+   * Each iteration produces independent index counters - safe to re-enumerate.
+   *
+   * @example
+   * ```ts
+   * Tyneq.enumerate(["a", "b", "c"]).toArray();
+   * // -> [[0, "a"], [1, "b"], [2, "c"]]
+   * ```
+   *
+   * @throws {ArgumentNullError} When `source` is null or undefined.
+   * @throws {ArgumentTypeError} When `source` is not iterable.
+   */
+  static enumerate<TSource>(source: Iterable<TSource>): TyneqSequence<[number, TSource]>;
+}
+//#endregion
+//#region src/core/TyneqComparer.d.ts
+/**
+ * Built-in comparers and equality comparers used by ordering and equality operators.
+ *
+ * @remarks
+ * All members are static. This class cannot be instantiated.
+ *
+ * @group Utilities
+ */
+declare class TyneqComparer {
+  private constructor();
+  /**
+   * Natural-order comparer using `<` and `>`.
+   *
+   * @remarks
+   * Works correctly for numbers, strings, dates, and any type that supports the relational operators.
+   *
+   * @returns Negative if `a < b`, positive if `a > b`, `0` if equal.
+   */
+  static defaultComparer<T>(a: T, b: T): number;
+  /** Strict equality comparer using `===`. */
+  static defaultEqualityComparer<T>(a: T, b: T): boolean;
+  /**
+   * Returns a comparer that reverses the order of `comparer`.
+   *
+   * @remarks
+   * Use this to invert any custom comparer - for example, to sort by a locale-aware comparer
+   * in descending order without rewriting it.
+   *
+   * @example
+   * ```ts
+   * const desc = TyneqComparer.reverse(TyneqComparer.createLocaleComparer("en"));
+   * seq.orderBy((s) => s, desc);
+   * ```
+   */
+  static reverse<T>(comparer: Comparer<T>): Comparer<T>;
+  /**
+   * Returns a locale-aware string comparer backed by `Intl.Collator`.
+   *
+   * @remarks
+   * Pass a `locale` and optional `options` for deterministic cross-environment ordering.
+   * Without arguments the comparer uses the runtime locale, which may vary across environments.
+   *
+   * @example
+   * ```ts
+   * seq.orderBy((s) => s, TyneqComparer.createLocaleComparer("en"));
+   * ```
+   *
+   * @param locale - BCP 47 language tag(s) passed to `Intl.Collator`.
+   * @param options - `Intl.CollatorOptions` passed to `Intl.Collator`.
+   *
+   * @see {@link caseInsensitiveComparer} for a locale-independent case-insensitive ordering comparer.
+   */
+  static createLocaleComparer(locale?: string | string[], options?: Intl.CollatorOptions): Comparer<string>;
+  /**
+   * Case-insensitive string equality comparer.
+   *
+   * @remarks
+   * Converts both values to lower-case with `toLowerCase()` before comparing with `===`.
+   * Locale-independent: results are consistent across environments.
+   *
+   * Use {@link createLocaleComparer} with `{ sensitivity: "base" }` for locale-aware
+   * case-insensitive equality.
+   *
+   * @see {@link caseInsensitiveComparer} for the ordering (negative/zero/positive) counterpart.
+   */
+  static caseInsensitiveEqualityComparer(a: string, b: string): boolean;
+  /**
+   * Case-insensitive ordering comparer.
+   *
+   * @remarks
+   * Converts both values to lower-case with `toLowerCase()` and compares with `<` / `>`.
+   * Locale-independent: results are consistent across environments and match
+   * {@link caseInsensitiveEqualityComparer} - strings that compare equal here return `true`
+   * there, and vice versa.
+   *
+   * Use {@link createLocaleComparer} when you need locale-aware case-insensitive ordering.
+   *
+   * @example
+   * ```ts
+   * seq.orderBy((s) => s, TyneqComparer.caseInsensitiveComparer)
+   * ```
+   *
+   * @see {@link caseInsensitiveEqualityComparer} for the boolean equality counterpart.
+   * @see {@link createLocaleComparer} for locale-aware ordering.
+   */
+  static caseInsensitiveComparer(a: string, b: string): number;
+}
+//#endregion
+//#region src/core/errors/TyneqError.d.ts
+/**
+ * Base class for all errors thrown by Tyneq.
+ *
+ * @example
+ * ```ts
+ * try { Tyneq.from([]).first(); }
+ * catch (e) { if (e instanceof TyneqError) { console.log(e.message); } }
+ * ```
+ *
+ * @group Errors
+ */
+declare class TyneqError extends Error {
+  /** The underlying error that caused this error, if any. */
+  inner: Maybe<Error>;
+  constructor(message: string, options?: {
+    inner?: Error;
+  });
+}
+//#endregion
+//#region src/core/errors/InvalidOperationError.d.ts
+/**
+ * Thrown when a method call is invalid for the current state of the object.
+ *
+ * @example
+ * ```ts
+ * try { Tyneq.from([1, 2]).single(); }
+ * catch (e) { if (e instanceof InvalidOperationError) { ... } }
+ * ```
+ *
+ * @see {@link TyneqError}
+ * @group Errors
+ */
+declare class InvalidOperationError extends TyneqError {
+  constructor(message?: string, inner?: Error);
+}
+//#endregion
+//#region src/core/errors/KeyNotFoundError.d.ts
+/**
+ * Thrown when a lookup is performed with a key that does not exist in the collection.
+ *
+ * @example
+ * ```ts
+ * try { seq.toMap((x) => x.id).get(999); }
+ * catch (e) { if (e instanceof KeyNotFoundError) { ... } }
+ * ```
+ *
+ * @see {@link TyneqError}
+ * @group Errors
+ */
+declare class KeyNotFoundError extends TyneqError {
+  constructor(message?: string, inner?: Error);
+}
+//#endregion
+//#region src/core/errors/NotSupportedError.d.ts
+/**
+ * Thrown when a requested operation is not supported.
+ *
+ * @example
+ * ```ts
+ * try { iterator.throw?.(new Error()); }
+ * catch (e) { if (e instanceof NotSupportedError) { ... } }
+ * ```
+ *
+ * @see {@link TyneqError}
+ * @group Errors
+ */
+declare class NotSupportedError extends TyneqError {
+  constructor(message?: string, inner?: Error);
+}
+//#endregion
+//#region src/core/errors/SequenceContainsNoElementsError.d.ts
+/**
+ * Thrown when an element is required from a sequence that contains no elements.
+ *
+ * @example
+ * ```ts
+ * try { Tyneq.from([]).first(); }
+ * catch (e) { if (e instanceof SequenceContainsNoElementsError) { ... } }
+ * ```
+ *
+ * @see {@link InvalidOperationError}
+ * @group Errors
+ */
+declare class SequenceContainsNoElementsError extends InvalidOperationError {
+  readonly operatorName: Maybe<string>;
+  constructor(operatorName?: string, inner?: Error);
+}
+//#endregion
+//#region src/core/errors/argument/ArgumentError.d.ts
+/**
+ * Thrown when a method argument fails validation.
+ *
+ * @example
+ * ```ts
+ * try { Tyneq.from([]).take(-1); }
+ * catch (e) { if (e instanceof ArgumentError) { console.log(e.paramName); } }
+ * ```
+ *
+ * @see {@link TyneqError}
+ * @group Errors
+ */
+declare class ArgumentError extends TyneqError {
+  /** The name of the parameter that caused the error. */
+  readonly paramName?: string;
+  constructor(message: string, paramName?: string, inner?: Error);
+}
+//#endregion
+//#region src/core/errors/argument/ArgumentNullError.d.ts
+/**
+ * Thrown when a required argument is `null`.
+ *
+ * @example
+ * ```ts
+ * try { Tyneq.from([1, 2]).select(null as any); }
+ * catch (e) { if (e instanceof ArgumentNullError) { console.log(e.paramName); } }
+ * ```
+ *
+ * @see {@link ArgumentError}
+ * @group Errors
+ */
+declare class ArgumentNullError extends ArgumentError {
+  constructor(paramName: string, inner?: Error);
+}
+//#endregion
+//#region src/core/errors/argument/ArgumentOutOfRangeError.d.ts
+/**
+ * Thrown when an argument is outside the valid range.
+ *
+ * @example
+ * ```ts
+ * try { Tyneq.from([1, 2]).take(-1); }
+ * catch (e) { if (e instanceof ArgumentOutOfRangeError) { console.log(e.actualValue); } }
+ * ```
+ *
+ * @see {@link ArgumentError}
+ * @group Errors
+ */
+declare class ArgumentOutOfRangeError extends ArgumentError {
+  /** The actual value that was out of range. */
+  readonly actualValue?: unknown;
+  constructor(paramName: string, message?: string, actualValue?: unknown, inner?: Error);
+}
+//#endregion
+//#region src/core/errors/argument/ArgumentTypeError.d.ts
+/**
+ * Thrown when an argument has the wrong type.
+ *
+ * @example
+ * ```ts
+ * try { Tyneq.from([1, 2]).where("not a function" as any); }
+ * catch (e) { if (e instanceof ArgumentTypeError) { console.log(e.expectedType, e.actualType); } }
+ * ```
+ *
+ * @see {@link ArgumentError}
+ * @group Errors
+ */
+declare class ArgumentTypeError extends ArgumentError {
+  /** The expected type name. */
+  readonly expectedType?: string;
+  /** The actual type name received. */
+  readonly actualType?: string;
+  constructor(paramName: string, expectedType?: string, actualType?: string, message?: string, inner?: Error);
+}
+//#endregion
+//#region src/core/errors/argument/ValidationError.d.ts
+/**
+ * Thrown when multiple argument validations fail simultaneously.
+ *
+ * @remarks
+ * `errors` contains one message per failed validation.
+ * Thrown by `ValidationBuilder.throwIfAny()` when at least one check failed.
+ *
+ * @example
+ * ```ts
+ * try { seq.someOperator(badArg1, badArg2); }
+ * catch (e) { if (e instanceof ValidationError) { console.log(e.errors); } }
+ * ```
+ *
+ * @see {@link ArgumentError}
+ * @group Errors
+ */
+declare class ValidationError extends ArgumentError {
+  /** The individual validation failure messages. */
+  readonly errors: readonly string[];
+  constructor(errors: readonly string[]);
+}
+//#endregion
+//#region src/core/errors/CompilerError.d.ts
+/**
+ * Thrown when the query plan compiler encounters a structural or semantic error
+ * while compiling a query plan into an executable sequence.
+ *
+ * @example
+ * ```ts
+ * try { compiler.compile(plan); }
+ * catch (e) {
+ *   if (e instanceof CompilerError) {
+ *     console.log(e.operatorName, e.phase, e.message);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link TyneqError}
+ * @group Errors
+ */
+declare class CompilerError extends TyneqError {
+  /** The name of the operator being compiled when the error occurred, if known. */
+  readonly operatorName: Maybe<string>;
+  /**
+   * The compilation phase in which the error occurred.
+   * - `"transform"` - during query plan transformation (pre-compile)
+   * - `"source"` - while compiling a source node
+   * - `"operator"` - while applying an operator node
+   */
+  readonly phase: "transform" | "source" | "operator";
+  constructor(message: string, phase: "transform" | "source" | "operator", operatorName?: string, inner?: Error);
+}
+//#endregion
+//#region src/core/errors/RegistryError.d.ts
+/**
+ * Thrown when the operator registry encounters a conflict or invalid state
+ * during operator registration or invocation.
+ *
+ * @example
+ * ```ts
+ * try { OperatorRegistry.register(entry); }
+ * catch (e) {
+ *   if (e instanceof RegistryError) {
+ *     console.log(e.operatorName, e.conflictingKind, e.message);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link TyneqError}
+ * @group Errors
+ */
+declare class RegistryError extends TyneqError {
+  /** The name of the operator involved in the error. */
+  readonly operatorName: string;
+  /**
+   * The kind of the operator that was being registered or invoked.
+   * `undefined` if the kind is not applicable to this error.
+   */
+  readonly kind: Maybe<OperatorMetadata["kind"]>;
+  /**
+   * The kind already present in the registry for this name, when there is a conflict.
+   * `undefined` when the error is not a duplicate-registration conflict.
+   */
+  readonly conflictingKind: Maybe<OperatorMetadata["kind"]>;
+  /**
+   * The source that originally registered the conflicting operator.
+   * `undefined` when the error is not a duplicate-registration conflict.
+   */
+  readonly conflictingSource: Maybe<OperatorMetadata["source"]>;
+  constructor(message: string, operatorName: string, kind?: OperatorMetadata["kind"], conflict?: {
+    kind: OperatorMetadata["kind"];
+    source: OperatorMetadata["source"];
+  }, inner?: Error);
+}
+//#endregion
+//#region src/core/errors/PluginError.d.ts
+/**
+ * Thrown when a plugin, decorator (`@operator`, `@terminal`), or factory
+ * (`createOperator`, `createTerminalOperator`) is used incorrectly.
+ *
+ * @example
+ * ```ts
+ * // @operator('myOp') applied to a class that doesn't extend TyneqEnumerator
+ * // throws PluginError with decoratorName = "operator" and targetName = "MyOp"
+ * ```
+ *
+ * @see {@link TyneqError}
+ * @group Errors
+ */
+declare class PluginError extends TyneqError {
+  /**
+   * The name of the decorator or factory that produced the error.
+   * e.g. `"operator"`, `"terminal"`, `"createOperator"`.
+   */
+  readonly decoratorName: string;
+  /**
+   * The name of the class or function the decorator was applied to, if available.
+   */
+  readonly targetName: Maybe<string>;
+  constructor(message: string, decoratorName: string, targetName?: string, inner?: Error);
+}
+//#endregion
+//#region src/core/errors/ReflectionError.d.ts
+/**
+ * Thrown when a prototype reflection operation fails - for example, when a
+ * method that is expected to exist on a prototype cannot be found.
+ *
+ * @example
+ * ```ts
+ * try { reflect(proto).getMethod("missing"); }
+ * catch (e) {
+ *   if (e instanceof ReflectionError) {
+ *     console.log(e.methodName, e.prototypeName, e.message);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link TyneqError}
+ * @group Errors
+ */
+declare class ReflectionError extends TyneqError {
+  /** The name of the method that could not be found. */
+  readonly methodName: string;
+  /** The name of the prototype/class that was searched. */
+  readonly prototypeName: Maybe<string>;
+  constructor(message: string, methodName: string, prototypeName?: string, inner?: Error);
+}
+//#endregion
+//#region src/core/registry/TyneqOperatorRegistry.d.ts
+/**
+ * Central registry for all Tyneq operators.
+ *
+ * Every registration path - `@operator`, `@terminal`, `createOperator`,
+ * `createGeneratorOperator`, `createTerminalOperator` - flows through this class.
+ * It is the single source of truth for which operators exist, their kind, and their
+ * prototype-level implementation.
+ *
+ * Internally the registry maintains two separate namespaces:
+ * - Source factories (`Tyneq.from`, `Tyneq.range`, etc.) - keyed by name alone.
+ * - Instance operators (`.where`, `.select`, etc.) - keyed by (name, targetClass).
+ *
+ * This means a source factory and an instance method can share a name without
+ * conflict (e.g. `Tyneq.concat` and `seq.concat`), and two instance operators
+ * with the same name on different prototype chains (e.g. `ordered.foo` and
+ * `cached.foo`) also coexist without conflict.
+ *
+ * @example
+ * ```ts
+ * import { OperatorRegistry } from "tyneq/plugin";
+ *
+ * OperatorRegistry.has("where"); // -> true
+ * OperatorRegistry.list(); // -> OperatorMetadata[]
+ * ```
+ *
+ * @group Classes
+ */
+declare class OperatorRegistry {
+  private static readonly _sources;
+  private static readonly _operators;
+  private static readonly _registrationHooks;
+  private static readonly _registrationGuards;
+  /**
+   * Registers an operator entry and patches the method onto `entry.metadata.targetClass.prototype`.
+   *
+   * @throws {RegistryError} When an operator with the same name is already registered on the same targetClass.
+   */
+  static register(input: OperatorEntry): void;
+  /**
+   * Removes an operator registration and deletes the prototype method for external operators.
+   *
+   * Checks the instance operator namespace first, then the source namespace.
+   *
+   * @returns `true` if the operator was found and removed; `false` if no operator with that name existed.
+   * @remarks
+   * Internal operators (source `"internal"`) are not removed from the prototype - only
+   * their registry entry is deleted.
+   *
+   * For targeted removal use {@link unregisterOperator} or {@link unregisterSource}.
+   */
+  static unregister(name: string): boolean;
+  /**
+   * Removes a specific instance operator registration for a given (name, targetClass) pair
+   * and deletes the prototype method for external operators.
+   *
+   * @returns `true` if the entry was found and removed; `false` otherwise.
+   */
+  static unregisterOperator(name: string, targetClass: SequenceConstructor): boolean;
+  /**
+   * Removes a source factory registration.
+   *
+   * @returns `true` if the source was found and removed; `false` otherwise.
+   */
+  static unregisterSource(name: string): boolean;
+  /**
+   * Registers a hook called after every successful operator registration (both namespaces).
+   *
+   * @returns A function that removes the hook when called.
+   */
+  static onRegister(hook: (entry: OperatorEntry) => void): () => void;
+  /**
+   * Registers a guard called before every registration (both namespaces).
+   * Throw from the guard to reject the registration.
+   *
+   * @returns A function that removes the guard when called.
+   */
+  static addGuard(guard: (entry: OperatorEntry) => void): () => void;
+  /**
+   * Returns `true` if a name exists in either the source or instance operator namespace.
+   * Use {@link hasSource} or {@link hasOperator} for namespace-specific checks.
+   */
+  static has(name: string): boolean;
+  /**
+   * Returns `true` if a source factory with `name` is registered.
+   */
+  static hasSource(name: string): boolean;
+  /**
+   * Returns `true` if an instance operator with `name` is registered.
+   * When `targetClass` is provided, checks only that specific (name, targetClass) pair.
+   * When omitted, returns `true` if any target has an operator with that name.
+   */
+  static hasOperator(name: string, targetClass?: SequenceConstructor): boolean;
+  /**
+   * Returns the operator entry for `name` from either namespace, or `undefined` if not found.
+   * Checks the instance operator namespace first, then the source namespace.
+   * For namespace-specific retrieval use {@link getSource} or {@link getOperator}.
+   */
+  static get(name: string): Maybe<OperatorEntry>;
+  /**
+   * Returns the source factory entry for `name`, or `undefined` if not registered.
+   */
+  static getSource(name: string): Maybe<OperatorEntry>;
+  /**
+   * Returns the instance operator entry for `name` on `targetClass`, or `undefined`.
+   * When `targetClass` is omitted, returns the first entry found across all targets.
+   */
+  static getOperator(name: string, targetClass?: SequenceConstructor): Maybe<OperatorEntry>;
+  /**
+   * Returns the metadata for `name` from either namespace, or `undefined` if not found.
+   * Checks instance operators first, then sources.
+   */
+  static getMetadata(name: string): Maybe<OperatorMetadata>;
+  /**
+   * Returns metadata for all registered operators and source factories.
+   * Use {@link listOperators} or {@link listSources} for namespace-specific lists.
+   */
+  static list(): readonly OperatorMetadata[];
+  /**
+   * Returns metadata for all registered source factories.
+   */
+  static listSources(): readonly OperatorMetadata[];
+  /**
+   * Returns metadata for all registered instance operators.
+   * When `targetClass` is provided, returns only entries for that specific target class.
+   */
+  static listOperators(targetClass?: SequenceConstructor): readonly OperatorMetadata[];
+  /** Returns metadata for all operators of `kind` across both namespaces. */
+  static listByKind(kind: OperatorMetadata["kind"]): readonly OperatorMetadata[];
+  /** Returns metadata for all operators from `source` across both namespaces. */
+  static listBySource(source: OperatorMetadata["source"]): readonly OperatorMetadata[];
+  /** Returns the total number of registered operators across both namespaces. */
+  static count(): number;
+  /**
+   * Registers a source operator (a static factory, not a prototype method).
+   *
+   * @remarks
+   * Source operators differ from prototype operators in two ways:
+   * - They are called with `null` as `this` - they have no instance.
+   * - They are looked up by the compiler via {@link getSource} rather than
+   *   being patched onto a prototype.
+   *
+   * The entry is stored in the source namespace and is never patched onto any prototype.
+   * Registration guards run for `"external"` sources (same policy as {@link register}).
+  * Guards are skipped for `"internal"` sources (same policy used for internal builtins).
+   *
+   * Third-party source operators registered here are automatically compiled by
+   * `QueryPlanCompiler` without any changes to the compiler.
+   *
+   * @param name - The operator name, matching the `operatorName` on the `QueryPlanNode`.
+   * @param factory - The factory function; receives the node args in order, `this` is `null`.
+   * @param source - Whether this is a built-in or external source operator. Defaults to `"external"`.
+   *
+   * @example
+   * ```ts
+   * import { OperatorRegistry } from "tyneq/plugin";
+   * import { Tyneq } from "tyneq";
+   *
+   * OperatorRegistry.registerSource("fibonacci", (count) => {
+   *     // return a Tyneq sequence of fibonacci numbers
+   * });
+   * ```
+   *
+   * @group Classes
+   */
+  static registerSource(name: string, factory: (...args: unknown[]) => unknown, source?: OperatorSource): void;
+  /**
+   * Records a built-in operator in the instance operator namespace without patching the prototype.
+   * Built-in operators already live as direct methods on their target class.
+   *
+   * @remarks
+   * Registration guards are intentionally skipped - builtins are internal and
+   * trusted; guards exist to validate external plugin registrations only.
+   *
+   * @internal
+   */
+  static registerBuiltin(name: string, kind: OperatorMetadata["kind"], targetClass: SequenceConstructor): void;
+}
+//#endregion
+//#region src/queryplan/QueryPlanPrinter.d.ts
+/**
+ * Converts a query plan tree into a human-readable multi-line string.
+ *
+ * Implements `QueryPlanVisitor<string>`. The output lists operators from source to
+ * terminal, one per line, with indentation showing the pipeline depth.
+ *
+ * @example
+ * ```ts
+ * import { QueryPlanPrinter } from "tyneq/queryplan";
+ *
+ * const seq = Tyneq.range(1, 10).where(x => x % 2 === 0).select(x => x * x);
+ * console.log(QueryPlanPrinter.print(seq[tyneqQueryNode]!));
+ * // range(1, 10)
+ * //   -> where(<fn>)
+ * //   -> select(<fn>)
+ * ```
+ *
+ * @group QueryPlan
+ */
+declare class QueryPlanPrinter implements QueryPlanVisitor<string> {
+  protected readonly indent: string;
+  protected readonly arrow: string;
+  protected readonly maxInlineArrayItems: number;
+  constructor(options?: QueryPlanPrinterOptions);
+  /** Renders the full query plan rooted at `node` as a multi-line string. */
+  visit(node: QueryPlanNode): string;
+  /** Convenience static: creates a printer with `options` and calls `visit(node)`. */
+  static print(node: QueryPlanNode, options?: QueryPlanPrinterOptions): string;
+  /**
+   * Formats a single operator argument for display.
+   * Override to customise how arguments appear in printed plans.
+   */
+  protected formatArg(arg: unknown): string;
+  /**
+   * Formats one line of the plan output.
+   * Override to customise indentation or arrow style beyond what `QueryPlanPrinterOptions` allows.
+   */
+  protected formatLine(name: string, argStr: string, isRoot: boolean): string;
+  private buildPlan;
+  private collectNodes;
+}
+//#endregion
+//#region src/queryplan/QueryPlanWalker.d.ts
+/**
+ * Concrete base class for side-effect query plan visitors.
+ *
+ * @remarks
+ * Traverses the node chain calling {@link QueryPlanWalker.visitNode} once per node.
+ * The traversal direction defaults to `"source-to-terminal"` (bottom-up: `from` before
+ * `where` before `select`) and can be changed to `"terminal-to-source"` (top-down) via
+ * the options object.
+ *
+ * ### Usage patterns
+ *
+ * **Direct instantiation with a callback** - no subclass needed for simple traversals:
+ * ```ts
+ * const names: string[] = [];
+ * new QueryPlanWalker({ callback: node => names.push(node.operatorName) }).visit(plan);
+ * ```
+ *
+ * **Subclass** - for stateful walkers that accumulate results across nodes:
+ * ```ts
+ * class NodeCounter extends QueryPlanWalker {
+ *     public count = 0;
+ *     protected override visitNode(_node: QueryPlanNode): void { this.count++; }
+ * }
+ *
+ * const counter = new NodeCounter();
+ * counter.visit(seq[tyneqQueryNode]!);
+ * console.log(counter.count); // number of operators in the pipeline
+ * ```
+ *
+ * **Top-down traversal:**
+ * ```ts
+ * new QueryPlanWalker({
+ *     callback: node => console.log(node.operatorName),
+ *     direction: "terminal-to-source",
+ * }).visit(plan);
+ * ```
+ *
+ * **Subclass with direction override** - pass options to `super`:
+ * ```ts
+ * class ReverseCollector extends QueryPlanWalker {
+ *     public readonly names: string[] = [];
+ *     public constructor() { super({ direction: "terminal-to-source" }); }
+ *     protected override visitNode(node: QueryPlanNode): void {
+ *         this.names.push(node.operatorName);
+ *     }
+ * }
+ * ```
+ *
+ * @group QueryPlan
+ */
+declare class QueryPlanWalker implements QueryPlanVisitor<void> {
+  private readonly callback;
+  private readonly direction;
+  /**
+   * @param options - Optional configuration for the walker.
+   */
+  constructor(options?: QueryPlanWalkerOptions);
+  /**
+   * Walks the full chain rooted at `node`, calling {@link visitNode} for each node
+   * in the configured direction.
+   */
+  visit(node: QueryPlanNode): void;
+  /**
+   * Called once per node during traversal.
+   *
+   * @remarks
+   * The default implementation fires the callback passed via options (if any).
+   * Override this method in a subclass to provide custom behaviour. Subclasses that
+   * override this method decide whether to call `super.visitNode(node)` to also fire
+   * the options callback.
+   *
+   * @param node - The current node being visited.
+   */
+  protected visitNode(node: QueryPlanNode): void;
+}
+//#endregion
+//#region src/queryplan/QueryPlanTransformer.d.ts
+/**
+ * Base class for immutable query plan rewriting.
+ *
+ * @remarks
+ * Recursively rebuilds the node chain, calling {@link QueryPlanTransformer.transformNode}
+ * once per node. The default implementation is an **identity transform** - every node is
+ * reconstructed with the same data, producing a structurally equivalent copy.
+ *
+ * Subclasses override `transformNode` to intercept specific operators. Three rewrite
+ * patterns are possible:
+ *
+ * - **Rewrite a node** - return a new `QueryNode` with different `operatorName` or `args`
+ * - **Remove a node** - return `source` directly, skipping this node
+ * - **Collapse two nodes into one** - use `source` as the new node's `source` (fusing
+ *   the current node with its already-transformed predecessor)
+ *
+ * @example
+ * ```ts
+ * // Rename all 'where' nodes to 'filter' in the plan view
+ * class RenameWhere extends QueryPlanTransformer {
+ *     protected override transformNode(node: QueryPlanNode, source: QueryPlanNode | null): QueryPlanNode {
+ *         if (node.operatorName === "where") {
+ *             return new QueryNode("filter", node.args, source, node.category);
+ *         }
+ *         return super.transformNode(node, source);
+ *     }
+ * }
+ * ```
+ *
+ * @group QueryPlan
+ */
+declare class QueryPlanTransformer implements QueryPlanVisitor<QueryPlanNode> {
+  /**
+   * Transforms the full chain rooted at `node` and returns the new root node.
+   *
+   * @remarks
+   * Processes source-first (bottom-up): the source chain is fully transformed before
+   * `transformNode` is called for the current node. This means `source` passed to
+   * `transformNode` is always already the transformed predecessor.
+   */
+  visit(node: QueryPlanNode): QueryPlanNode;
+  /**
+   * Transforms a single node. Override to intercept specific operators.
+   *
+   * @remarks
+   * The default implementation reconstructs the node with identical data (identity transform).
+   * `source` is the already-transformed predecessor - use it as the `source` of any returned
+   * node to preserve chain continuity.
+   *
+   * @param node - The original node (unmodified).
+   * @param source - The transformed predecessor, or `null` for source nodes.
+   */
+  protected transformNode(node: QueryPlanNode, source: Nullable<QueryPlanNode>): QueryPlanNode;
+}
+//#endregion
+//#region src/queryplan/QueryPlanOptimizer.d.ts
+/**
+ * A built-in {@link QueryPlanTransformer} that fuses redundant consecutive operators.
+ *
+ * @remarks
+ * **This optimizer rewrites the query plan tree only - it does not affect execution of the
+ * original sequence.** The returned `QueryPlanNode` reflects what an optimized pipeline would
+ * look like; the live sequence that produced the original plan is unchanged.
+ *
+ * **Fusion is only semantics-preserving for pure, side-effect-free functions.**
+ * If a predicate or projection has side effects (e.g. logging, mutation), fusing two nodes into
+ * one changes when and how many times those effects fire. For example, in a fused `where`, the
+ * second predicate is never called for items that fail the first - any mutation inside the second
+ * predicate is skipped for those items. Do not use this optimizer on pipelines with impure
+ * predicates or projections.
+ *
+ * ### Fusions applied
+ *
+ * | Pattern | Result |
+ * |---------|--------|
+ * | `where(a) -> where(b)` | `where(x => a(x) && b(x))` |
+ * | `select(a) -> select(b)` | `select(x => b(a(x)))` |
+ *
+ * Additional fusions can be added by subclassing and overriding
+ * {@link QueryPlanTransformer.transformNode}.
+ *
+ * @example
+ * ```ts
+ * import { Tyneq, tyneqQueryNode, QueryPlanOptimizer, QueryPlanPrinter } from "tyneq";
+ *
+ * const seq = Tyneq.from([1, 2, 3])
+ *     .where(x => x > 1)
+ *     .where(x => x < 3)
+ *     .select(x => x * 2)
+ *     .select(x => x + 1);
+ *
+ * const original = seq[tyneqQueryNode]!;
+ * const optimized = new QueryPlanOptimizer().visit(original);
+ *
+ * console.log(QueryPlanPrinter.print(original));
+ * // from([...])
+ * //   -> where(<fn>)
+ * //   -> where(<fn>)
+ * //   -> select(<fn>)
+ * //   -> select(<fn>)
+ *
+ * console.log(QueryPlanPrinter.print(optimized));
+ * // from([...])
+ * //   -> where(<fn>)
+ * //   -> select(<fn>)
+ * ```
+ *
+ * @group QueryPlan
+ */
+declare class QueryPlanOptimizer extends QueryPlanTransformer {
+  protected transformNode(node: QueryPlanNode, source: Nullable<QueryPlanNode>): QueryPlanNode;
+  /**
+   * @remarks Fusion is only semantics-preserving for pure, side-effect-free predicates.
+   */
+  private fuseWhere;
+  /**
+   * @remarks Fusion is only semantics-preserving for pure, side-effect-free projections.
+   */
+  private fuseSelect;
+}
+//#endregion
+//#region src/queryplan/compiler/QueryPlanCompiler.d.ts
+/**
+ * Options for {@link QueryPlanCompiler.compile} and {@link QueryPlanCompiler.compileRaw}.
+ *
+ * @group QueryPlan
+ */
+interface CompileOptions {
+  /**
+   * Replaces the source data when compiling.
+   *
+   * When provided, the compiler passes this value as the first argument to the source
+   * operator instead of the value stored in the plan node's `args`. This lets you reuse
+   * the same pipeline structure (operators, predicates, projections) against a different
+   * data set without rebuilding the sequence.
+   *
+   * @example
+   * ```ts
+   * const plan = Tyneq.from([1, 2, 3]).where(x => x > 1).select(x => x * 2)[tyneqQueryNode]!;
+   * const compiler = new QueryPlanCompiler();
+   *
+   * compiler.compile(plan).toArray();                         // -> [4, 6]
+   * compiler.compile(plan, { source: [10, 20, 30] }).toArray(); // -> [40, 60]
+   * ```
+   *
+   * @remarks
+   * Only affects source nodes (the root of the plan). All operator nodes are replayed
+   * exactly as recorded. If the plan has no source node (e.g. it starts from an operator
+   * node with a missing parent), this option has no effect.
+   */
+  readonly source?: Iterable<unknown>;
+}
+/**
+ * Compiles a query plan tree into an executable `TyneqSequence`.
+ *
+ * @remarks
+ * Walks the `QueryPlanNode` chain from source to terminal, reconstructing each operator by
+ * looking it up in the `OperatorRegistry` and applying it to the compiled source.
+ * An optional list of `QueryPlanTransformer` instances runs before compilation, allowing
+ * optimization or rewriting of the plan.
+ *
+ * @example
+ * ```ts
+ * import { Tyneq, tyneqQueryNode, QueryPlanCompiler, QueryPlanOptimizer } from "tyneq";
+ *
+ * const seq = Tyneq.from([1, 2, 3]).where(x => x > 1).select(x => x * 2);
+ * const compiler = new QueryPlanCompiler([new QueryPlanOptimizer()]);
+ * const result = compiler.compile(seq[tyneqQueryNode]!);
+ * result.toArray(); // -> [4, 6]
+ * ```
+ *
+ * @group QueryPlan
+ */
+declare class QueryPlanCompiler {
+  private readonly transformers;
+  constructor(transformers?: Iterable<QueryPlanTransformer>);
+  /**
+   * Compile a query plan into an executable sequence.
+   *
+   * Runs all registered transformers before compiling. Use {@link compileRaw} to skip
+   * the transform phase when the plan is already optimised.
+   *
+   * @param node - The root node of the query plan to compile.
+   * @param options - Optional compile-time overrides. Use `options.source` to supply a
+   * different data source than the one stored in the plan.
+   * @returns The compiled sequence typed as `TyneqSequence<T>` by default.
+   * If you know the plan ends in an operator that returns a subtype (e.g. `orderBy` ->
+   * `TyneqOrderedSequence`, `memoize` -> `TyneqCachedSequence`), supply `TResult` explicitly:
+   * `compiler.compile<number, TyneqOrderedSequence<number>>(node)`.
+   */
+  compile<T = unknown, TResult extends TyneqSequence<T> = TyneqSequence<T>>(node: QueryPlanNode, options?: CompileOptions): TResult;
+  /**
+   * Compile a pre-optimised query plan into an executable sequence, skipping the
+   * transform phase.
+   *
+   * @remarks
+   * Use this overload when you have already run transformers externally (or deliberately
+   * want to bypass them) and want to compile the node as-is. Equivalent to constructing
+   * a `QueryPlanCompiler` with no transformers and calling `compile()`.
+   *
+   * @param node - The root node of the already-transformed query plan to compile.
+   * @param options - Optional compile-time overrides. Use `options.source` to supply a
+   * different data source than the one stored in the plan.
+   */
+  compileRaw<T = unknown, TResult extends TyneqSequence<T> = TyneqSequence<T>>(node: QueryPlanNode, options?: CompileOptions): TResult;
+  private transform;
+  private compileNode;
+  private compileSource;
+  private applyOperator;
+  private findOperatorEntry;
+}
+//#endregion
+export { type AccessorDescriptor, Action, ArgumentError, ArgumentNullError, ArgumentOutOfRangeError, ArgumentTypeError, ArgumentUtility, Assume, BoundMethod, CacheResult, CachedEnumerable, Cast, Comparer, type CompileOptions, CompilerError, Constructor, type DataDescriptor, Enumerable, Enumerator, EnumeratorFactory, EqualityComparer, Factory, FieldKeys, Func, GenericFunction, HasLength, type QueryPlanNode as IQueryNode, InstanceOf, InvalidOperationError, ItemAction, ItemPredicate, ItemSelector, IteratorFactory, KeyNotFoundError, KeyValuePair, Lazy, Maybe, type MemberDescriptor, Method, type MethodDescriptor, MethodKeys, MinMaxResult, NoInfer, NotSupportedError, Nullable, type OperatorCategory, type OperatorEntry, OperatorKind, OperatorMetadata, OperatorRegistry, OperatorSource, Optional, OrderedEnumerable, PluginError, Predicate, QueryNode, QueryPlanCompiler, QueryPlanOptimizer, QueryPlanPrinter, type QueryPlanPrinterOptions, QueryPlanTransformer, type QueryPlanTraversalDirection, type QueryPlanVisitor, QueryPlanWalker, type QueryPlanWalkerOptions, type ReflectOptions, ReflectionContext, ReflectionError, RegistryError, SequenceConstructor, SequenceContainsNoElementsError, SequenceFactory, type SourceKind, Tyneq, TyneqBaseEnumerator, TyneqCachedEnumerable, TyneqCachedEnumerator, TyneqCachedSequence, TyneqCachedTerminalOperator, TyneqComparer, TyneqEnumerableFactory, TyneqEnumerator, TyneqError, TyneqOrderedEnumerable, TyneqOrderedEnumerator, TyneqOrderedSequence, TyneqOrderedTerminalOperator, TyneqSequence, TyneqTerminalOperator, TypeGuardUtility, ValidationBuilder, ValidationError, WithProperties, cachedOperator, cachedTerminal, createCachedOperator, createCachedTerminalOperator, createGeneratorOperator, createOperator, createOrderedOperator, createOrderedTerminalOperator, createTerminalOperator, isSourceNode, operator, orderedOperator, orderedTerminal, reflect, terminal, tyneqQueryNode };
+//# sourceMappingURL=index.d.ts.map