tyneq 1.0.0

package/dist/TyneqCachedTerminalOperator.js

@@ -0,0 +1,4741 @@
+import { a as ArgumentUtility, c as ArgumentOutOfRangeError, d as TyneqError, f as nameof, r as reflect, t as Lazy } from "./Lazy.js";
+//#region src/core/enumerators/TyneqBaseEnumerator.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
+*/
+var TyneqBaseEnumerator = class {
+	_initialized = false;
+	_completed = false;
+	constructor() {}
+	/** Advances the iterator, calling `initialize()` on first call. Idempotent after completion. */
+	next() {
+		if (this._completed) return this.done();
+		if (!this._initialized) {
+			this.initialize();
+			this._initialized = true;
+		}
+		const result = this.handleNext();
+		if (result.done) {
+			if (!this._completed) {
+				this.dispose();
+				this._completed = true;
+			}
+			return this.done();
+		}
+		return result;
+	}
+	/** Terminates iteration early, disposes resources, and marks completed. Idempotent. */
+	return(value) {
+		if (!this._completed) {
+			this.dispose(value);
+			this._completed = true;
+		}
+		return this.done();
+	}
+	/** Called once before the first `handleNext()` invocation. Override to set up state. */
+	initialize() {}
+	/** Wraps `value` in a non-done `IteratorResult`. */
+	yield(value) {
+		return {
+			done: false,
+			value
+		};
+	}
+	/** Returns a done `IteratorResult`. */
+	done() {
+		return {
+			done: true,
+			value: void 0
+		};
+	}
+	/**
+	* 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.
+	*/
+	doneWithYield(value) {
+		this.dispose();
+		this._completed = true;
+		return this.yield(value);
+	}
+	/**
+	* Disposes resources, marks completed, and returns a done result.
+	*
+	* @remarks
+	* Use inside `handleNext()` to terminate iteration before the source is exhausted.
+	*/
+	earlyComplete(reason) {
+		this.dispose(reason);
+		this._completed = true;
+		return this.done();
+	}
+	/** Calls `disposeSource()` then `disposeAdditional()`. */
+	dispose(value) {
+		this.disposeSource();
+		this.disposeAdditional(value);
+	}
+	/** Override to dispose the upstream source enumerator. */
+	disposeSource() {}
+	/**
+	* 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.
+	*/
+	disposeAdditional(_value) {}
+};
+//#endregion
+//#region src/core/TyneqComparer.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
+*/
+var TyneqComparer = class {
+	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(a, b) {
+		return a > b ? 1 : a < b ? -1 : 0;
+	}
+	/** Strict equality comparer using `===`. */
+	static defaultEqualityComparer(a, b) {
+		return a === b;
+	}
+	/**
+	* 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(comparer) {
+		return (a, b) => comparer(b, a);
+	}
+	/**
+	* 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, options) {
+		const collator = new Intl.Collator(locale, options);
+		return (a, b) => collator.compare(a, b);
+	}
+	/**
+	* 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, b) {
+		return a.toLowerCase() === b.toLowerCase();
+	}
+	/**
+	* 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, b) {
+		const la = a.toLowerCase();
+		const lb = b.toLowerCase();
+		return la > lb ? 1 : la < lb ? -1 : 0;
+	}
+};
+//#endregion
+//#region src/types/queryplan.ts
+/**
+* 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
+*/
+const tyneqQueryNode = Symbol("tyneq.queryNode");
+/**
+* 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
+*/
+function isSourceNode(node) {
+	return node.category === "source";
+}
+//#endregion
+//#region src/queryplan/QueryNode.ts
+/**
+* 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
+*/
+var QueryNode = class {
+	constructor(operatorName, args, source, category, sourceKind) {
+		this.operatorName = operatorName;
+		this.args = args;
+		this.source = source;
+		this.category = category;
+		this.sourceKind = sourceKind;
+	}
+	accept(visitor) {
+		return visitor.visit(this);
+	}
+};
+//#endregion
+//#region src/plugin/decorators/builtin.ts
+const builtinMeta = Symbol("tyneq.builtinMetadata");
+/**
+* Method decorator - declares this method as a built-in operator.
+*
+* Stores `BuiltinOptions` on the function object so `@sequence` can find it.
+* Does NOT register anything by itself - registration happens in `@sequence`.
+*
+* @remarks
+* This is one half of a two-decorator pattern. Apply `@builtin` to each method on a class
+* decorated with `@sequence`. When the module is evaluated, `@sequence` will scan all
+* `@builtin`-tagged methods and call `OperatorRegistry.registerBuiltin` for each.
+*
+* Only use on methods of `TyneqEnumerableCore` or `TyneqEnumerableBase`. Third-party
+* operators should use `@operator`, `@terminal`, or the `createOperator` factory instead.
+*
+* @internal
+*/
+function builtin(options) {
+	return function(value, context) {
+		value[builtinMeta] = {
+			name: context.name,
+			kind: options.kind
+		};
+		return value;
+	};
+}
+//#endregion
+//#region src/core/errors/PluginError.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
+*/
+var PluginError = class extends TyneqError {
+	/**
+	* The name of the decorator or factory that produced the error.
+	* e.g. `"operator"`, `"terminal"`, `"createOperator"`.
+	*/
+	decoratorName;
+	/**
+	* The name of the class or function the decorator was applied to, if available.
+	*/
+	targetName;
+	constructor(message, decoratorName, targetName, inner) {
+		super(message, { inner });
+		this.decoratorName = decoratorName;
+		this.targetName = targetName;
+	}
+};
+//#endregion
+//#region src/core/OperatorMetadata.ts
+/**
+* Metadata describing a registered operator.
+*
+* @group Classes
+*/
+var OperatorMetadata = class OperatorMetadata {
+	name;
+	kind;
+	source;
+	targetClass;
+	extensions;
+	constructor(name, kind, source = "external", targetClass, extensions = {}) {
+		this.name = name;
+		this.kind = kind;
+		this.source = source;
+		this.targetClass = arguments.length < 4 ? TyneqEnumerableBase : targetClass;
+		this.extensions = extensions;
+	}
+	/**
+	* 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, src = "external") {
+		return new OperatorMetadata(name, "source", src, void 0);
+	}
+	/** Creates metadata for a streaming operator. Defaults targetClass to TyneqEnumerableBase. */
+	static streaming(name, targetClass = TyneqEnumerableBase, source, extensions) {
+		return new OperatorMetadata(name, "streaming", source ?? "external", targetClass, extensions);
+	}
+	/** Creates metadata for a buffering operator. Defaults targetClass to TyneqEnumerableBase. */
+	static buffer(name, targetClass = TyneqEnumerableBase, source, extensions) {
+		return new OperatorMetadata(name, "buffer", source ?? "external", targetClass, extensions);
+	}
+	/** Creates metadata for a terminal operator. Defaults targetClass to TyneqEnumerableBase. */
+	static terminal(name, targetClass = TyneqEnumerableBase, source, extensions) {
+		return new OperatorMetadata(name, "terminal", source ?? "external", targetClass, extensions);
+	}
+	/**
+	* 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, name, targetClass = TyneqEnumerableBase, source, extensions) {
+		if (category === "streaming") return OperatorMetadata.streaming(name, targetClass, source, extensions);
+		if (category === "buffer") return OperatorMetadata.buffer(name, targetClass, source, extensions);
+		throw new PluginError(`OperatorMetadata.forCategory: unsupported category "${category}". Use .terminal() or .source() directly.`, "forCategory", name);
+	}
+};
+//#endregion
+//#region src/core/errors/RegistryError.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
+*/
+var RegistryError = class extends TyneqError {
+	/** The name of the operator involved in the error. */
+	operatorName;
+	/**
+	* The kind of the operator that was being registered or invoked.
+	* `undefined` if the kind is not applicable to this error.
+	*/
+	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.
+	*/
+	conflictingKind;
+	/**
+	* The source that originally registered the conflicting operator.
+	* `undefined` when the error is not a duplicate-registration conflict.
+	*/
+	conflictingSource;
+	constructor(message, operatorName, kind, conflict, inner) {
+		super(message, { inner });
+		this.operatorName = operatorName;
+		this.kind = kind;
+		this.conflictingKind = conflict?.kind;
+		this.conflictingSource = conflict?.source;
+	}
+};
+//#endregion
+//#region src/core/registry/TyneqOperatorRegistry.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
+*/
+var OperatorRegistry = class {
+	static _sources = /* @__PURE__ */ new Map();
+	static _operators = /* @__PURE__ */ new Map();
+	static _registrationHooks = [];
+	static _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) {
+		const { name } = input.metadata;
+		if (input.metadata.targetClass === void 0) throw new RegistryError(`Cannot register "${name}": targetClass is required for prototype-patching operators. Use registerSource() for source operators.`, name, input.metadata.kind);
+		const targetMap = this._operators.get(name);
+		if (targetMap?.has(input.metadata.targetClass)) {
+			const existing = targetMap.get(input.metadata.targetClass).metadata;
+			throw new RegistryError(`Cannot register "${name}" (${input.metadata.kind}) on ${input.metadata.targetClass.name}: already registered as "${existing.kind}" from source "${existing.source}".`, name, input.metadata.kind, {
+				kind: existing.kind,
+				source: existing.source
+			});
+		}
+		for (const guard of this._registrationGuards) guard(input);
+		if (!this._operators.has(name)) this._operators.set(name, /* @__PURE__ */ new Map());
+		this._operators.get(name).set(input.metadata.targetClass, input);
+		input.metadata.targetClass.prototype[name] = input.impl;
+		for (const hook of this._registrationHooks) hook(input);
+	}
+	/**
+	* 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) {
+		if (this._operators.has(name)) {
+			const targetMap = this._operators.get(name);
+			for (const [targetClass, entry] of targetMap) if (entry.metadata.source !== "internal" && targetClass !== void 0) delete targetClass.prototype[name];
+			this._operators.delete(name);
+			return true;
+		}
+		if (this._sources.has(name)) {
+			this._sources.delete(name);
+			return true;
+		}
+		return false;
+	}
+	/**
+	* 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, targetClass) {
+		const targetMap = this._operators.get(name);
+		if (!targetMap?.has(targetClass)) return false;
+		if (targetMap.get(targetClass).metadata.source !== "internal") delete targetClass.prototype[name];
+		targetMap.delete(targetClass);
+		if (targetMap.size === 0) this._operators.delete(name);
+		return true;
+	}
+	/**
+	* Removes a source factory registration.
+	*
+	* @returns `true` if the source was found and removed; `false` otherwise.
+	*/
+	static unregisterSource(name) {
+		return this._sources.delete(name);
+	}
+	/**
+	* Registers a hook called after every successful operator registration (both namespaces).
+	*
+	* @returns A function that removes the hook when called.
+	*/
+	static onRegister(hook) {
+		this._registrationHooks.push(hook);
+		return () => {
+			const i = this._registrationHooks.indexOf(hook);
+			if (i !== -1) this._registrationHooks.splice(i, 1);
+		};
+	}
+	/**
+	* 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) {
+		this._registrationGuards.push(guard);
+		return () => {
+			const i = this._registrationGuards.indexOf(guard);
+			if (i !== -1) this._registrationGuards.splice(i, 1);
+		};
+	}
+	/**
+	* 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) {
+		return this._sources.has(name) || this._operators.has(name);
+	}
+	/**
+	* Returns `true` if a source factory with `name` is registered.
+	*/
+	static hasSource(name) {
+		return this._sources.has(name);
+	}
+	/**
+	* 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, targetClass) {
+		if (targetClass !== void 0) return this._operators.get(name)?.has(targetClass) ?? false;
+		return this._operators.has(name);
+	}
+	/**
+	* 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) {
+		const targetMap = this._operators.get(name);
+		if (targetMap !== void 0) return targetMap.values().next().value;
+		return this._sources.get(name);
+	}
+	/**
+	* Returns the source factory entry for `name`, or `undefined` if not registered.
+	*/
+	static getSource(name) {
+		return this._sources.get(name);
+	}
+	/**
+	* 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, targetClass) {
+		const targetMap = this._operators.get(name);
+		if (targetMap === void 0) return;
+		if (targetClass !== void 0) return targetMap.get(targetClass);
+		return targetMap.values().next().value;
+	}
+	/**
+	* Returns the metadata for `name` from either namespace, or `undefined` if not found.
+	* Checks instance operators first, then sources.
+	*/
+	static getMetadata(name) {
+		return this.get(name)?.metadata;
+	}
+	/**
+	* Returns metadata for all registered operators and source factories.
+	* Use {@link listOperators} or {@link listSources} for namespace-specific lists.
+	*/
+	static list() {
+		return [...this.listSources(), ...this.listOperators()];
+	}
+	/**
+	* Returns metadata for all registered source factories.
+	*/
+	static listSources() {
+		return [...this._sources.values()].map((e) => e.metadata);
+	}
+	/**
+	* Returns metadata for all registered instance operators.
+	* When `targetClass` is provided, returns only entries for that specific target class.
+	*/
+	static listOperators(targetClass) {
+		const all = [];
+		for (const targetMap of this._operators.values()) if (targetClass !== void 0) {
+			const entry = targetMap.get(targetClass);
+			if (entry !== void 0) all.push(entry.metadata);
+		} else for (const entry of targetMap.values()) all.push(entry.metadata);
+		return all;
+	}
+	/** Returns metadata for all operators of `kind` across both namespaces. */
+	static listByKind(kind) {
+		return this.list().filter((m) => m.kind === kind);
+	}
+	/** Returns metadata for all operators from `source` across both namespaces. */
+	static listBySource(source) {
+		return this.list().filter((m) => m.source === source);
+	}
+	/** Returns the total number of registered operators across both namespaces. */
+	static count() {
+		let operatorCount = 0;
+		for (const targetMap of this._operators.values()) operatorCount += targetMap.size;
+		return this._sources.size + operatorCount;
+	}
+	/**
+	* 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, factory, source = "external") {
+		if (this._sources.has(name)) {
+			const existing = this._sources.get(name).metadata;
+			throw new RegistryError(`Cannot register source "${name}": already registered as "${existing.kind}" from source "${existing.source}".`, name, "source", {
+				kind: existing.kind,
+				source: existing.source
+			});
+		}
+		const entry = {
+			metadata: OperatorMetadata.source(name, source),
+			impl: function(...args) {
+				return factory(...args);
+			}
+		};
+		if (source !== "internal") for (const guard of this._registrationGuards) guard(entry);
+		this._sources.set(name, entry);
+		for (const hook of this._registrationHooks) hook(entry);
+	}
+	/**
+	* 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, kind, targetClass) {
+		const targetMap = this._operators.get(name);
+		if (targetMap?.has(targetClass)) {
+			const existing = targetMap.get(targetClass).metadata;
+			throw new RegistryError(`Cannot register builtin "${name}" (${kind}) on ${targetClass.name}: already registered as "${existing.kind}" from source "${existing.source}".`, name, kind, {
+				kind: existing.kind,
+				source: existing.source
+			});
+		}
+		const lazyMethod = new Lazy(() => reflect(targetClass.prototype).tryGetMethod(name)?.value);
+		const entry = {
+			metadata: new OperatorMetadata(name, kind, "internal", targetClass),
+			impl: function(...args) {
+				const method = lazyMethod.value;
+				if (!method) throw new RegistryError(`Cannot invoke builtin "${name}" (${kind}): method not found on prototype. Ensure the method exists on the target class before registering.`, name, kind);
+				return method.apply(this, args);
+			}
+		};
+		if (!this._operators.has(name)) this._operators.set(name, /* @__PURE__ */ new Map());
+		this._operators.get(name).set(targetClass, entry);
+		for (const hook of this._registrationHooks) hook(entry);
+	}
+};
+//#endregion
+//#region src/plugin/decorators/sequence.ts
+/**
+* Class decorator - declares this class as a sequence whose `@builtin` methods are operators.
+*
+* Scans the prototype for `@builtin`-tagged methods and registers each one via
+* `OperatorRegistry.registerBuiltin`, passing this class as `targetClass`.
+*
+* @remarks
+* Works in tandem with `@builtin`. The two-decorator pattern:
+* 1. Decorate each built-in method with `@builtin({ kind: "streaming" | "buffer" })`.
+*    `@builtin` stamps a `builtinMeta` symbol onto the function object - it does NOT register.
+* 2. Decorate the containing class with `@sequence`.
+*    `@sequence` scans the prototype, finds all `@builtin`-tagged methods, and calls
+*    `OperatorRegistry.registerBuiltin` for each one.
+*
+* Apply only to `TyneqEnumerableCore` and `TyneqEnumerableBase` - the two base classes
+* whose methods form the built-in operator surface. Never use on third-party or test classes.
+*
+* @internal
+*/
+function sequence(target, _context) {
+	for (const key of Object.getOwnPropertyNames(target.prototype)) {
+		const method = reflect(target.prototype).tryGetMethod(key)?.value;
+		if (method && builtinMeta in method) {
+			const metadata = method[builtinMeta];
+			OperatorRegistry.registerBuiltin(metadata.name, metadata.kind, target);
+		}
+	}
+}
+//#endregion
+//#region src/core/TyneqEnumerableCore.ts
+var TyneqEnumerableCore = @sequence class {
+	[Symbol.iterator]() {
+		return this.getEnumerator();
+	}
+	@builtin({ kind: "buffer" }) orderBy(keySelector, comparer) {
+		ArgumentUtility.checkNotOptional({ keySelector });
+		const orderByArgs = comparer !== void 0 ? [keySelector, comparer] : [keySelector];
+		return this.createOrderedEnumerable(keySelector, comparer ?? TyneqComparer.defaultComparer, false, this.createNode("orderBy", "buffer", orderByArgs));
+	}
+	@builtin({ kind: "buffer" }) orderByDescending(keySelector, comparer) {
+		ArgumentUtility.checkNotOptional({ keySelector });
+		const orderByDescArgs = comparer !== void 0 ? [keySelector, comparer] : [keySelector];
+		return this.createOrderedEnumerable(keySelector, comparer ?? TyneqComparer.defaultComparer, true, this.createNode("orderByDescending", "buffer", orderByDescArgs));
+	}
+	@builtin({ kind: "cache" }) memoize() {
+		return this.createCachedEnumerable(this, this.createNode("memoize", "buffer"));
+	}
+	@builtin({ kind: "extension" }) pipe(factory) {
+		ArgumentUtility.checkNotOptional({ factory });
+		const self = this;
+		return this.createSequence(() => factory(self), this.createNode("pipe", "streaming", [factory]));
+	}
+	/**
+	* 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.
+	*/
+	createSequence(factory, node) {
+		return this.createEnumerable({ getEnumerator: factory }, node);
+	}
+	/**
+	* 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.
+	*/
+	createNode(name, category, args = []) {
+		return new QueryNode(name, args, this[tyneqQueryNode], category);
+	}
+};
+//#endregion
+//#region src/core/terminal/TyneqTerminalOperator.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
+*/
+var TyneqTerminalOperator = class {
+	source;
+	constructor(source) {
+		ArgumentUtility.checkNotOptional({ source });
+		this.source = source;
+	}
+};
+//#endregion
+//#region src/operators/aggregate.ts
+/**
+* Applies an accumulator over the sequence and transforms the final result through a selector.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.aggregate}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var AggregateOperator = class extends TyneqTerminalOperator {
+	seed;
+	func;
+	resultSelector;
+	constructor(source, seed, func, resultSelector) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ func });
+		ArgumentUtility.checkNotOptional({ resultSelector });
+		this.seed = seed;
+		this.func = func;
+		this.resultSelector = resultSelector;
+	}
+	process() {
+		let accumulate = this.seed;
+		for (const item of this.source) accumulate = this.func(accumulate, item);
+		return this.resultSelector(accumulate);
+	}
+};
+//#endregion
+//#region src/operators/all.ts
+/**
+* Returns true if every element satisfies a predicate.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.all}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var AllOperator = class extends TyneqTerminalOperator {
+	predicate;
+	constructor(source, predicate) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ predicate });
+		this.predicate = predicate;
+	}
+	process() {
+		let index = 0;
+		for (const item of this.source) if (!this.predicate(item, index++)) return false;
+		return true;
+	}
+};
+//#endregion
+//#region src/operators/any.ts
+/**
+* Returns true if any element satisfies a predicate.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.any}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var AnyOperator = class extends TyneqTerminalOperator {
+	predicate;
+	constructor(source, predicate) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ predicate });
+		this.predicate = predicate;
+	}
+	process() {
+		let index = 0;
+		for (const item of this.source) if (this.predicate(item, index++)) return true;
+		return false;
+	}
+};
+//#endregion
+//#region src/operators/average.ts
+/**
+* Returns the average of all elements projected through a selector.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.average}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var AverageOperator = class extends TyneqTerminalOperator {
+	selector;
+	constructor(source, selector) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ selector });
+		this.selector = selector;
+	}
+	process() {
+		let count = 0;
+		let sum = 0;
+		for (const item of this.source) {
+			sum += this.selector(item);
+			count++;
+		}
+		return count === 0 ? 0 : sum / count;
+	}
+};
+//#endregion
+//#region src/operators/consume.ts
+/**
+* Iterates the source sequence and discards all elements.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.consume}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var ConsumeOperator = class extends TyneqTerminalOperator {
+	constructor(source) {
+		super(source);
+	}
+	process() {
+		for (const _ of this.source);
+	}
+};
+//#endregion
+//#region src/operators/contains.ts
+/**
+* Returns `true` if the source sequence contains `value`.
+*
+* @remarks
+* Immediate. Enumerates the source until a match is found or the sequence is exhausted.
+* Uses `equalityComparer` for element comparison, or `===` when omitted.
+* Returns `false` for an empty sequence.
+*
+* @see {@link TyneqSequence.contains}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var ContainsOperator = class extends TyneqTerminalOperator {
+	value;
+	equalityComparer;
+	constructor(source, value, equalityComparer) {
+		super(source);
+		ArgumentUtility.checkNotNull({ equalityComparer });
+		this.value = value;
+		this.equalityComparer = equalityComparer ?? TyneqComparer.defaultEqualityComparer;
+	}
+	process() {
+		for (const item of this.source) if (this.equalityComparer(item, this.value)) return true;
+		return false;
+	}
+};
+//#endregion
+//#region src/operators/count.ts
+/**
+* Returns the total number of elements in the sequence.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.count}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var CountOperator = class extends TyneqTerminalOperator {
+	constructor(source) {
+		super(source);
+	}
+	process() {
+		if (Array.isArray(this.source)) return this.source.length;
+		let count = 0;
+		for (const _ of this.source) count++;
+		return count;
+	}
+};
+//#endregion
+//#region src/operators/countBy.ts
+/**
+* Returns the number of elements that satisfy a predicate.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.countBy}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var CountByOperator = class extends TyneqTerminalOperator {
+	predicate;
+	constructor(source, predicate) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ predicate });
+		this.predicate = predicate;
+	}
+	process() {
+		let count = 0;
+		let index = 0;
+		for (const item of this.source) if (this.predicate(item, index++)) count++;
+		return count;
+	}
+};
+//#endregion
+//#region src/operators/elementAt.ts
+/**
+* Returns the element at a specified index, or throws if the index is out of range.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.elementAt}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var ElementAtOperator = class extends TyneqTerminalOperator {
+	index;
+	constructor(source, index) {
+		super(source);
+		this.index = index;
+	}
+	process() {
+		const index = this.index;
+		let currentIndex = 0;
+		for (const element of this.source) {
+			if (currentIndex === index) return element;
+			currentIndex++;
+		}
+		throw new ArgumentOutOfRangeError(nameof({ index })[0]);
+	}
+};
+//#endregion
+//#region src/operators/elementAtOrDefault.ts
+/**
+* Returns the element at a specified index, or a default value if the index is out of range.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.elementAtOrDefault}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var ElementAtOrDefaultOperator = class extends TyneqTerminalOperator {
+	index;
+	defaultValue;
+	constructor(source, index, defaultValue) {
+		super(source);
+		this.index = index;
+		this.defaultValue = defaultValue;
+	}
+	process() {
+		const index = this.index;
+		let currentIndex = 0;
+		for (const element of this.source) {
+			if (currentIndex === index) return element;
+			currentIndex++;
+		}
+		return this.defaultValue;
+	}
+};
+//#endregion
+//#region src/core/errors/InvalidOperationError.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
+*/
+var InvalidOperationError = class extends TyneqError {
+	constructor(message = "The operation is invalid in the current state.", inner) {
+		super(message, { inner });
+	}
+};
+//#endregion
+//#region src/operators/first.ts
+/**
+* Returns the first element matching a predicate, or throws if no match is found.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.first}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var FirstOperator = class extends TyneqTerminalOperator {
+	predicate;
+	constructor(source, predicate) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ predicate });
+		this.predicate = predicate;
+	}
+	process() {
+		let index = 0;
+		for (const element of this.source) if (this.predicate(element, index++)) return element;
+		throw new InvalidOperationError("Sequence contains no matching element");
+	}
+};
+//#endregion
+//#region src/operators/firstOrDefault.ts
+/**
+* Returns the first element matching a predicate, or a default value if no match is found.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.firstOrDefault}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var FirstOrDefaultOperator = class extends TyneqTerminalOperator {
+	predicate;
+	defaultValue;
+	constructor(source, predicate, defaultValue) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ predicate });
+		this.predicate = predicate;
+		this.defaultValue = defaultValue;
+	}
+	process() {
+		let index = 0;
+		for (const element of this.source) if (this.predicate(element, index++)) return element;
+		return this.defaultValue;
+	}
+};
+//#endregion
+//#region src/operators/indexOf.ts
+/**
+* Returns the zero-based index of the first element matching a predicate, or -1 if not found.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.indexOf}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var IndexOfOperator = class extends TyneqTerminalOperator {
+	predicate;
+	startIndex;
+	constructor(source, predicate, startIndex = 0) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ predicate });
+		ArgumentUtility.checkNonNegative({ startIndex });
+		this.predicate = predicate;
+		this.startIndex = startIndex;
+	}
+	process() {
+		let index = -1;
+		for (const item of this.source) {
+			index++;
+			if (index < this.startIndex) continue;
+			if (this.predicate(item, index)) return index;
+		}
+		return -1;
+	}
+};
+//#endregion
+//#region src/utility/EnumeratorUtility.ts
+/**
+* Low-level helpers for working with `Enumerator<T>` objects inside custom operator enumerators.
+*
+* Import from `"tyneq/plugin"` when writing class-based operators that need to convert
+* between `Iterable<T>` and `Enumerator<T>`, or that need safe cleanup via `tryDispose`.
+*
+* @group Plugin Utilities
+*/
+var EnumeratorUtility = class {
+	constructor() {}
+	/**
+	* Calls `enumerator.return()` if it exists, swallowing any error.
+	* Safe to call on `null` or `undefined`.
+	*/
+	static tryDispose(enumerator) {
+		try {
+			enumerator?.return?.();
+		} catch {}
+	}
+	/** Wraps an `Enumerator<T>` in a minimal `Iterable<T>` adapter (no buffering). */
+	static toIterable(enumerator) {
+		return { [Symbol.iterator]: () => enumerator };
+	}
+	/** Gets an `Enumerator<T>` from any `Iterable<T>`. */
+	static fromIterable(iterable) {
+		return iterable[Symbol.iterator]();
+	}
+	/**
+	* Advances the enumerator by one position and returns `true` if that position was done.
+	*
+	* **Warning:** this calls `next()` and irrevocably consumes one element.
+	* If the enumerator is not exhausted, the yielded element is discarded.
+	* Only call this when advancing past the current position is intentional.
+	*/
+	static checkAndConsume(enumerator) {
+		return enumerator.next().done === true;
+	}
+};
+//#endregion
+//#region src/operators/isNullOrEmpty.ts
+/**
+* Returns true if the sequence has no elements, or if its first element is null or undefined.
+*
+* @remarks
+* Immediate. Reads at most one element from the source (O(1) enumeration) and then disposes the iterator.
+*
+* @see {@link TyneqSequence.isNullOrEmpty}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var IsNullOrEmptyOperator = class extends TyneqTerminalOperator {
+	constructor(source) {
+		super(source);
+	}
+	process() {
+		const iterator = this.source[Symbol.iterator]();
+		const first = iterator.next();
+		EnumeratorUtility.tryDispose(iterator);
+		return first.done === true || first.value === null || first.value === void 0;
+	}
+};
+//#endregion
+//#region src/operators/last.ts
+/**
+* Returns the last element matching a predicate, or throws if no match is found.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.last}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var LastOperator = class extends TyneqTerminalOperator {
+	predicate;
+	constructor(source, predicate) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ predicate });
+		this.predicate = predicate;
+	}
+	process() {
+		let lastMatchingElement = null;
+		let found = false;
+		let index = 0;
+		for (const element of this.source) if (this.predicate(element, index++)) {
+			lastMatchingElement = element;
+			found = true;
+		}
+		if (!found) throw new InvalidOperationError("Sequence contains no matching element");
+		return lastMatchingElement;
+	}
+};
+//#endregion
+//#region src/operators/lastOrDefault.ts
+/**
+* Returns the last element matching a predicate, or a default value if no match is found.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.lastOrDefault}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var LastOrDefaultOperator = class extends TyneqTerminalOperator {
+	predicate;
+	defaultValue;
+	constructor(source, predicate, defaultValue) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ predicate });
+		this.predicate = predicate;
+		this.defaultValue = defaultValue;
+	}
+	process() {
+		let lastMatchingElement = null;
+		let found = false;
+		let index = 0;
+		for (const element of this.source) if (this.predicate(element, index++)) {
+			lastMatchingElement = element;
+			found = true;
+		}
+		if (!found) return this.defaultValue;
+		return lastMatchingElement;
+	}
+};
+//#endregion
+//#region src/core/errors/SequenceContainsNoElementsError.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
+*/
+var SequenceContainsNoElementsError = class extends InvalidOperationError {
+	operatorName;
+	constructor(operatorName, inner) {
+		const message = operatorName ? `Sequence contains no elements (in "${operatorName}").` : "Sequence contains no elements.";
+		super(message, inner);
+		this.operatorName = operatorName;
+	}
+};
+//#endregion
+//#region src/operators/extremum.ts
+/**
+* Returns the minimum or maximum element in the sequence using a comparer.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+* Parameterised by direction to avoid duplicating the iteration logic
+* across separate min and max operators.
+*
+* @see {@link TyneqSequence.min}
+* @see {@link TyneqSequence.max}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var ExtremumOperator = class extends TyneqTerminalOperator {
+	comparer;
+	direction;
+	operatorName;
+	constructor(source, direction, operatorName, comparer) {
+		super(source);
+		this.comparer = comparer ?? TyneqComparer.defaultComparer;
+		this.direction = direction;
+		this.operatorName = operatorName;
+	}
+	process() {
+		let best = null;
+		let hasElement = false;
+		for (const element of this.source) if (!hasElement || this.comparer(element, best) * this.direction > 0) {
+			best = element;
+			hasElement = true;
+		}
+		if (!hasElement) throw new SequenceContainsNoElementsError(this.operatorName);
+		return best;
+	}
+};
+/**
+* Returns the element with the minimum or maximum key as determined by a key selector.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+* Parameterised by direction to avoid duplicating the iteration logic
+* across separate minBy and maxBy operators.
+*
+* @see {@link TyneqSequence.minBy}
+* @see {@link TyneqSequence.maxBy}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var ExtremumByOperator = class extends TyneqTerminalOperator {
+	comparer;
+	keySelector;
+	direction;
+	operatorName;
+	constructor(source, keySelector, direction, operatorName, comparer) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ keySelector });
+		this.comparer = comparer ?? TyneqComparer.defaultComparer;
+		this.keySelector = keySelector;
+		this.direction = direction;
+		this.operatorName = operatorName;
+	}
+	process() {
+		let bestElement = null;
+		let bestKey = null;
+		let hasElement = false;
+		for (const element of this.source) {
+			const key = this.keySelector(element);
+			if (!hasElement || this.comparer(key, bestKey) * this.direction > 0) {
+				bestElement = element;
+				bestKey = key;
+				hasElement = true;
+			}
+		}
+		if (!hasElement) throw new SequenceContainsNoElementsError(this.operatorName);
+		return bestElement;
+	}
+};
+//#endregion
+//#region src/operators/minMax.ts
+/**
+* Returns both the minimum and maximum elements of the sequence in a single pass.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.minMax}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var MinMaxOperator = class extends TyneqTerminalOperator {
+	comparer;
+	constructor(source, comparer) {
+		super(source);
+		this.comparer = comparer ?? TyneqComparer.defaultComparer;
+	}
+	process() {
+		let min;
+		let max;
+		let hasElements = false;
+		for (const item of this.source) if (!hasElements) {
+			min = item;
+			max = item;
+			hasElements = true;
+		} else {
+			if (this.comparer(item, min) < 0) min = item;
+			if (this.comparer(item, max) > 0) max = item;
+		}
+		if (!hasElements) throw new SequenceContainsNoElementsError("minMax");
+		return {
+			min,
+			max
+		};
+	}
+};
+//#endregion
+//#region src/operators/sequenceEqual.ts
+/**
+* Returns true if the source and a second sequence contain equal elements in the same order.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.sequenceEqual}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var SequenceEqualOperator = class extends TyneqTerminalOperator {
+	other;
+	equalityComparer;
+	constructor(source, other, equalityComparer) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ other });
+		ArgumentUtility.checkNotNull({ equalityComparer });
+		this.equalityComparer = equalityComparer ?? TyneqComparer.defaultEqualityComparer;
+		this.other = other;
+	}
+	process() {
+		const sourceIterator = this.source[Symbol.iterator]();
+		const otherIterator = this.other[Symbol.iterator]();
+		while (true) {
+			const sourceNext = sourceIterator.next();
+			const otherNext = otherIterator.next();
+			if (sourceNext.done && otherNext.done) break;
+			if (sourceNext.done !== otherNext.done) return false;
+			if (!this.equalityComparer(sourceNext.value, otherNext.value)) return false;
+		}
+		return true;
+	}
+};
+//#endregion
+//#region src/operators/single.ts
+/**
+* Returns the single element matching a predicate, or throws if there is not exactly one match.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.single}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var SingleOperator = class extends TyneqTerminalOperator {
+	predicate;
+	constructor(source, predicate) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ predicate });
+		this.predicate = predicate;
+	}
+	process() {
+		let found = false;
+		let single = null;
+		let index = 0;
+		for (const element of this.source) if (this.predicate(element, index++)) {
+			if (found) throw new InvalidOperationError("Sequence contains more than one matching element");
+			found = true;
+			single = element;
+		}
+		if (!found) throw new InvalidOperationError("Sequence contains no matching element");
+		return single;
+	}
+};
+//#endregion
+//#region src/operators/singleOrDefault.ts
+/**
+* Returns the single element matching a predicate, or a default value if no match is found.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.singleOrDefault}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var SingleOrDefaultOperator = class extends TyneqTerminalOperator {
+	predicate;
+	defaultValue;
+	constructor(source, predicate, defaultValue) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ predicate });
+		this.predicate = predicate;
+		this.defaultValue = defaultValue;
+	}
+	process() {
+		let found = false;
+		let single = null;
+		let index = 0;
+		for (const element of this.source) if (this.predicate(element, index++)) {
+			if (found) throw new InvalidOperationError("Sequence contains more than one matching element");
+			found = true;
+			single = element;
+		}
+		if (!found) return this.defaultValue;
+		return single;
+	}
+};
+//#endregion
+//#region src/operators/endsWith.ts
+var EndsWithOperator = class extends TyneqTerminalOperator {
+	sequence;
+	equalityComparer;
+	constructor(source, sequence, equalityComparer) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ sequence });
+		ArgumentUtility.checkIterable({ sequence });
+		ArgumentUtility.checkNotNull({ equalityComparer });
+		this.sequence = sequence;
+		this.equalityComparer = equalityComparer ?? TyneqComparer.defaultEqualityComparer;
+	}
+	process() {
+		const suffixElements = Array.from(this.sequence);
+		if (suffixElements.length === 0) return true;
+		const bufferResult = this.fillCircularBuffer(this.source, suffixElements.length);
+		if (bufferResult === null) return false;
+		const { buffer, readIndex } = bufferResult;
+		for (let i = 0; i < suffixElements.length; i++) if (!this.equalityComparer(buffer[(readIndex + i) % buffer.length], suffixElements[i])) return false;
+		return true;
+	}
+	fillCircularBuffer(elements, windowSize) {
+		const buffer = new Array(windowSize);
+		let writeIndex = 0;
+		for (const item of elements) {
+			buffer[writeIndex % windowSize] = item;
+			writeIndex++;
+		}
+		if (writeIndex < windowSize) return null;
+		return {
+			buffer,
+			readIndex: writeIndex % windowSize
+		};
+	}
+};
+//#endregion
+//#region src/operators/startsWith.ts
+/**
+* Returns `true` if the source sequence begins with all elements of `sequence` in order.
+*
+* @remarks
+* Immediate. Enumerates the source only until the result is determined.
+* 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.
+*
+* @see {@link TyneqSequence.startsWith}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var StartsWithOperator = class extends TyneqTerminalOperator {
+	sequence;
+	equalityComparer;
+	constructor(source, sequence, equalityComparer) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ sequence });
+		ArgumentUtility.checkIterable({ sequence });
+		ArgumentUtility.checkNotNull({ equalityComparer });
+		this.sequence = sequence;
+		this.equalityComparer = equalityComparer ?? TyneqComparer.defaultEqualityComparer;
+	}
+	process() {
+		const sourceEnumerator = this.source[Symbol.iterator]();
+		const sequenceEnumerator = this.sequence[Symbol.iterator]();
+		while (true) {
+			const { value: sourceValue, done: sourceDone } = sourceEnumerator.next();
+			const { value: sequenceValue, done: sequenceDone } = sequenceEnumerator.next();
+			if (sequenceDone) return true;
+			if (sourceDone || !this.equalityComparer(sourceValue, sequenceValue)) return false;
+		}
+	}
+};
+//#endregion
+//#region src/operators/sum.ts
+/**
+* Returns the sum of all elements projected through a selector.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.sum}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var SumOperator = class extends TyneqTerminalOperator {
+	selector;
+	constructor(source, selector) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ selector });
+		this.selector = selector;
+	}
+	process() {
+		let sum = 0;
+		for (const item of this.source) sum += this.selector(item);
+		return sum;
+	}
+};
+//#endregion
+//#region src/operators/toArray.ts
+/**
+* Collects all elements into an array.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.toArray}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var ToArrayOperator = class extends TyneqTerminalOperator {
+	constructor(source) {
+		super(source);
+	}
+	process() {
+		return Array.from(this.source);
+	}
+};
+//#endregion
+//#region src/operators/toAsync.ts
+/**
+* Wraps the source sequence as an async iterable.
+*
+* @remarks
+* Deferred. The source is enumerated lazily as the returned async iterable is iterated.
+*
+* @see {@link TyneqSequence.toAsync}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var ToAsyncOperator = class extends TyneqTerminalOperator {
+	constructor(source) {
+		super(source);
+	}
+	process() {
+		const source = this.source;
+		return { async *[Symbol.asyncIterator]() {
+			for (const item of source) yield item;
+		} };
+	}
+};
+//#endregion
+//#region src/operators/toMap.ts
+/**
+* Collects all elements into a Map using a key-value selector.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.toMap}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var ToMapOperator = class extends TyneqTerminalOperator {
+	selector;
+	constructor(source, selector) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ selector });
+		this.selector = selector;
+	}
+	process() {
+		return new Map(Array.from(this.source, (item) => {
+			const pair = this.selector(item);
+			return this.transformPairToTuple(pair);
+		}));
+	}
+	transformPairToTuple(pair) {
+		return [pair.key, pair.value];
+	}
+};
+//#endregion
+//#region src/operators/toRecord.ts
+/**
+* Collects all elements into a plain object record using a key-value selector.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.toRecord}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var ToRecordOperator = class extends TyneqTerminalOperator {
+	selector;
+	constructor(source, selector) {
+		super(source);
+		ArgumentUtility.checkNotOptional({ selector });
+		this.selector = selector;
+	}
+	process() {
+		const result = {};
+		for (const item of this.source) {
+			const pair = this.selector(item);
+			result[pair.key] = pair.value;
+		}
+		return result;
+	}
+};
+//#endregion
+//#region src/operators/toSet.ts
+/**
+* Collects all elements into a Set.
+*
+* @remarks
+* Immediate. Source is fully enumerated when this method is called.
+*
+* @see {@link TyneqSequence.toSet}
+* @group Operators
+* @category Terminal
+* @internal
+*/
+var ToSetOperator = class extends TyneqTerminalOperator {
+	constructor(source) {
+		super(source);
+	}
+	process() {
+		return new Set(this.source);
+	}
+};
+//#endregion
+//#region src/core/enumerators/TyneqEnumerator.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
+*/
+var TyneqEnumerator = class extends TyneqBaseEnumerator {
+	sourceEnumerator;
+	sourceDisposed = false;
+	constructor(sourceEnumerator) {
+		super();
+		ArgumentUtility.checkNotOptional({ sourceEnumerator });
+		this.sourceEnumerator = sourceEnumerator;
+	}
+	disposeSource() {
+		if (this.sourceDisposed) return;
+		this.sourceDisposed = true;
+		EnumeratorUtility.tryDispose(this.sourceEnumerator);
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/append.ts
+/**
+* Appends a single element to the end of the source sequence.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.append}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var AppendEnumerator = class extends TyneqEnumerator {
+	isSourceDone = false;
+	appended = false;
+	item;
+	constructor(sourceEnumerator, item) {
+		super(sourceEnumerator);
+		this.item = item;
+	}
+	handleNext() {
+		if (!this.isSourceDone) {
+			const sourceNext = this.sourceEnumerator.next();
+			if (!sourceNext.done) return this.yield(sourceNext.value);
+			this.isSourceDone = true;
+		}
+		if (!this.appended) {
+			this.appended = true;
+			return this.yield(this.item);
+		}
+		return this.done();
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/chunk.ts
+/**
+* Splits the source sequence into non-overlapping chunks of a fixed size.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.chunk}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var ChunkEnumerator = class extends TyneqEnumerator {
+	size;
+	currentChunk = [];
+	constructor(sourceEnumerator, size) {
+		super(sourceEnumerator);
+		this.size = size;
+	}
+	handleNext() {
+		while (this.currentChunk.length < this.size) {
+			const next = this.sourceEnumerator.next();
+			if (next.done) break;
+			this.currentChunk.push(next.value);
+		}
+		if (this.currentChunk.length === 0) return this.done();
+		const chunk = this.currentChunk;
+		this.currentChunk = [];
+		return this.yield(chunk);
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/concat.ts
+/**
+* Concatenates a second sequence after the source sequence.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.concat}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var ConcatEnumerator = class extends TyneqEnumerator {
+	otherEnumerator;
+	isSourceDone = false;
+	constructor(sourceEnumerator, other) {
+		super(sourceEnumerator);
+		this.otherEnumerator = other[Symbol.iterator]();
+	}
+	disposeAdditional() {
+		EnumeratorUtility.tryDispose(this.otherEnumerator);
+	}
+	handleNext() {
+		if (!this.isSourceDone) {
+			const next = this.sourceEnumerator.next();
+			if (!next.done) return this.yield(next.value);
+			this.isSourceDone = true;
+		}
+		const next = this.otherEnumerator.next();
+		if (!next.done) return this.yield(next.value);
+		return this.done();
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/flatten.ts
+/**
+* Flattens one level of nesting from a sequence of iterables.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+* Each inner iterable is consumed lazily as the outer sequence advances.
+*
+* @see {@link TyneqSequence.flatten}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var FlattenEnumerator = class extends TyneqEnumerator {
+	innerEnumerator = null;
+	constructor(sourceEnumerator) {
+		super(sourceEnumerator);
+	}
+	handleNext() {
+		while (true) {
+			if (this.innerEnumerator !== null) {
+				const innerNext = this.innerEnumerator.next();
+				if (!innerNext.done) return this.yield(innerNext.value);
+				this.innerEnumerator = null;
+			}
+			const sourceNext = this.sourceEnumerator.next();
+			if (sourceNext.done) return this.done();
+			this.innerEnumerator = sourceNext.value[Symbol.iterator]();
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/defaultIfEmpty.ts
+/**
+* Returns the source sequence, or a single default element if the source is empty.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.defaultIfEmpty}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var DefaultIfEmptyEnumerator = class extends TyneqEnumerator {
+	defaultValue;
+	sourceDone = false;
+	hasYieldedAny = false;
+	defaultYielded = false;
+	constructor(sourceEnumerator, defaultValue) {
+		super(sourceEnumerator);
+		this.defaultValue = defaultValue;
+	}
+	handleNext() {
+		if (!this.sourceDone) {
+			const next = this.sourceEnumerator.next();
+			if (!next.done) {
+				this.hasYieldedAny = true;
+				return this.yield(next.value);
+			}
+			this.sourceDone = true;
+		}
+		if (!this.hasYieldedAny && !this.defaultYielded) {
+			this.defaultYielded = true;
+			return this.doneWithYield(this.defaultValue);
+		}
+		return this.done();
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/ofType.ts
+/**
+* Filters elements to only those matching a type guard.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.ofType}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var OfTypeEnumerator = class extends TyneqEnumerator {
+	guard;
+	constructor(sourceEnumerator, guard) {
+		super(sourceEnumerator);
+		this.guard = guard;
+	}
+	handleNext() {
+		while (true) {
+			const { value, done } = this.sourceEnumerator.next();
+			if (done) return this.done();
+			if (this.guard(value)) return this.yield(value);
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/pairwise.ts
+/**
+* Projects each consecutive pair of elements as a two-element tuple.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.pairwise}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var PairwiseEnumerator = class extends TyneqEnumerator {
+	hasPrevious = false;
+	previous;
+	constructor(sourceEnumerator) {
+		super(sourceEnumerator);
+	}
+	handleNext() {
+		while (true) {
+			const next = this.sourceEnumerator.next();
+			if (next.done) return this.done();
+			if (!this.hasPrevious) {
+				this.previous = next.value;
+				this.hasPrevious = true;
+				continue;
+			}
+			const pair = [this.previous, next.value];
+			this.previous = next.value;
+			return this.yield(pair);
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/populate.ts
+/**
+* Replaces every element in the source with a fixed value.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.populate}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var PopulateEnumerator = class extends TyneqEnumerator {
+	value;
+	constructor(sourceEnumerator, value) {
+		super(sourceEnumerator);
+		this.value = value;
+	}
+	handleNext() {
+		while (true) {
+			const { done } = this.sourceEnumerator.next();
+			if (done) return this.done();
+			return this.yield(this.value);
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/prepend.ts
+/**
+* Prepends a single element to the beginning of the source sequence.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.prepend}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var PrependEnumerator = class extends TyneqEnumerator {
+	prepended = false;
+	item;
+	constructor(sourceEnumerator, item) {
+		super(sourceEnumerator);
+		this.item = item;
+	}
+	handleNext() {
+		if (!this.prepended) {
+			this.prepended = true;
+			return this.yield(this.item);
+		}
+		const nextItem = this.sourceEnumerator.next();
+		if (!nextItem.done) return this.yield(nextItem.value);
+		return this.done();
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/scan.ts
+/**
+* Applies an accumulator function and yields the running result after each element.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.scan}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var ScanEnumerator = class extends TyneqEnumerator {
+	accumulator;
+	current;
+	constructor(sourceEnumerator, seed, accumulator) {
+		super(sourceEnumerator);
+		this.current = seed;
+		this.accumulator = accumulator;
+	}
+	handleNext() {
+		const { value, done } = this.sourceEnumerator.next();
+		if (done) return this.done();
+		this.current = this.accumulator(this.current, value);
+		return this.yield(this.current);
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/select.ts
+/**
+* Projects each element through a selector.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.select}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var SelectEnumerator = class extends TyneqEnumerator {
+	selector;
+	index = 0;
+	constructor(sourceEnumerator, selector) {
+		super(sourceEnumerator);
+		this.selector = selector;
+	}
+	handleNext() {
+		const next = this.sourceEnumerator.next();
+		if (next.done) return this.done();
+		return this.yield(this.selector(next.value, this.index++));
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/selectMany.ts
+/**
+* Flattens each element into a sub-sequence and yields each element of those sub-sequences.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.selectMany}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var SelectManyEnumerator = class extends TyneqEnumerator {
+	selector;
+	innerEnumerator = null;
+	constructor(sourceEnumerator, selector) {
+		super(sourceEnumerator);
+		this.selector = selector;
+	}
+	handleNext() {
+		while (true) {
+			if (this.innerEnumerator !== null) {
+				const innerNext = this.innerEnumerator.next();
+				if (!innerNext.done) return this.yield(innerNext.value);
+				this.innerEnumerator = null;
+			}
+			const sourceNext = this.sourceEnumerator.next();
+			if (sourceNext.done) return this.done();
+			this.innerEnumerator = this.selector(sourceNext.value)[Symbol.iterator]();
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/repeatSequence.ts
+/**
+* Repeats the source sequence a specified number of times.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+* Re-enumerates the source from the beginning for each repetition.
+* Returns an empty sequence when `count` is 0.
+*
+* @see {@link TyneqSequence.repeat}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var RepeatSequenceEnumerator = class extends TyneqEnumerator {
+	source;
+	count;
+	repetition = 0;
+	currentEnumerator;
+	constructor(sourceEnumerator, source, count) {
+		super(sourceEnumerator);
+		this.source = source;
+		this.count = count;
+		this.currentEnumerator = sourceEnumerator;
+	}
+	disposeAdditional() {
+		if (this.currentEnumerator !== this.sourceEnumerator) EnumeratorUtility.tryDispose(this.currentEnumerator);
+	}
+	handleNext() {
+		while (this.repetition < this.count) {
+			const next = this.currentEnumerator.next();
+			if (!next.done) return this.yield(next.value);
+			this.repetition++;
+			if (this.repetition < this.count) {
+				const fresh = this.source[Symbol.iterator]();
+				const probe = fresh.next();
+				if (probe.done) {
+					this.repetition = this.count;
+					return this.done();
+				}
+				this.currentEnumerator = fresh;
+				return this.yield(probe.value);
+			}
+		}
+		return this.done();
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/skip.ts
+/**
+* Skips a specified number of elements from the beginning of the source sequence.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.skip}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var SkipEnumerator = class extends TyneqEnumerator {
+	count;
+	skipped = false;
+	constructor(sourceEnumerator, count) {
+		super(sourceEnumerator);
+		this.count = count;
+	}
+	handleNext() {
+		if (!this.skipped) {
+			let skippedCount = 0;
+			while (skippedCount < this.count) {
+				if (this.sourceEnumerator.next().done) return this.done();
+				skippedCount++;
+			}
+			this.skipped = true;
+		}
+		const sourceNext = this.sourceEnumerator.next();
+		if (sourceNext.done) return this.done();
+		return this.yield(sourceNext.value);
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/skipLast.ts
+/**
+* Skips a specified number of elements from the end of the source sequence.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.skipLast}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var SkipLastEnumerator = class extends TyneqEnumerator {
+	count;
+	buffer;
+	writeIndex = 0;
+	filledCount = 0;
+	constructor(sourceEnumerator, count) {
+		super(sourceEnumerator);
+		this.count = count;
+		this.buffer = new Array(this.count);
+	}
+	handleNext() {
+		if (this.count === 0) {
+			const current = this.sourceEnumerator.next();
+			if (current.done) return this.done();
+			else return this.yield(current.value);
+		}
+		while (true) {
+			const current = this.sourceEnumerator.next();
+			if (current.done) return this.done();
+			if (this.filledCount < this.count) {
+				this.buffer[this.writeIndex] = current.value;
+				this.writeIndex = (this.writeIndex + 1) % this.count;
+				this.filledCount++;
+				continue;
+			}
+			const oldest = this.buffer[this.writeIndex];
+			this.buffer[this.writeIndex] = current.value;
+			this.writeIndex = (this.writeIndex + 1) % this.count;
+			return this.yield(oldest);
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/skipUntil.ts
+/**
+* Skips elements from the beginning of the source sequence until a predicate returns `true`,
+* then yields all remaining elements including the one that triggered the predicate.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.skipUntil}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var SkipUntilEnumerator = class extends TyneqEnumerator {
+	predicate;
+	index = 0;
+	triggered = false;
+	constructor(sourceEnumerator, predicate) {
+		super(sourceEnumerator);
+		this.predicate = predicate;
+	}
+	handleNext() {
+		while (true) {
+			const next = this.sourceEnumerator.next();
+			if (next.done) return this.done();
+			if (!this.triggered) this.triggered = this.predicate(next.value, this.index++);
+			if (this.triggered) return this.yield(next.value);
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/skipWhile.ts
+/**
+* Skips elements from the beginning of the source sequence as long as a predicate is true.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.skipWhile}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var SkipWhileEnumerator = class extends TyneqEnumerator {
+	predicate;
+	index = 0;
+	isSkipping = true;
+	constructor(sourceEnumerator, predicate) {
+		super(sourceEnumerator);
+		this.predicate = predicate;
+	}
+	handleNext() {
+		while (true) {
+			const next = this.sourceEnumerator.next();
+			if (next.done) return this.done();
+			this.isSkipping = this.isSkipping && this.predicate(next.value, this.index++);
+			if (!this.isSkipping) return this.yield(next.value);
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/slice.ts
+/**
+* Yields elements between a start index (inclusive) and an end index (exclusive).
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.slice}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var SliceEnumerator = class extends TyneqEnumerator {
+	start;
+	end;
+	index = 0;
+	started = false;
+	constructor(sourceEnumerator, start, end) {
+		super(sourceEnumerator);
+		this.start = start;
+		this.end = end;
+	}
+	handleNext() {
+		if (!this.started) {
+			this.started = true;
+			while (this.index < this.start) {
+				if (this.sourceEnumerator.next().done) return this.done();
+				this.index++;
+			}
+		}
+		if (this.index >= this.end) return this.earlyComplete();
+		const next = this.sourceEnumerator.next();
+		if (next.done) return this.done();
+		this.index++;
+		return this.yield(next.value);
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/split.ts
+/**
+* Splits the source sequence into sub-arrays at each element matching a predicate.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.split}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var SplitEnumerator = class extends TyneqEnumerator {
+	splitOn;
+	constructor(sourceEnumerator, splitOn) {
+		super(sourceEnumerator);
+		this.splitOn = splitOn;
+	}
+	handleNext() {
+		const currentSplit = [];
+		while (true) {
+			const { value, done } = this.sourceEnumerator.next();
+			if (done) {
+				if (currentSplit.length > 0) return this.doneWithYield(currentSplit);
+				return this.done();
+			}
+			if (this.splitOn(value)) {
+				if (currentSplit.length > 0) return this.yield(currentSplit);
+			} else currentSplit.push(value);
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/take.ts
+/**
+* Returns a specified number of elements from the beginning of the source sequence.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.take}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var TakeEnumerator = class extends TyneqEnumerator {
+	count;
+	takenCount = 0;
+	constructor(sourceEnumerator, count) {
+		super(sourceEnumerator);
+		this.count = count;
+	}
+	handleNext() {
+		if (this.takenCount >= this.count) return this.earlyComplete();
+		const result = this.sourceEnumerator.next();
+		if (result.done) return this.done();
+		this.takenCount++;
+		return this.yield(result.value);
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/takeUntil.ts
+/**
+* Yields elements from the beginning of the source sequence until a predicate returns `true`,
+* then stops. The element that triggered the predicate is not included.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.takeUntil}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var TakeUntilEnumerator = class extends TyneqEnumerator {
+	predicate;
+	index = 0;
+	constructor(sourceEnumerator, predicate) {
+		super(sourceEnumerator);
+		this.predicate = predicate;
+	}
+	handleNext() {
+		const next = this.sourceEnumerator.next();
+		if (next.done) return this.done();
+		if (this.predicate(next.value, this.index++)) return this.earlyComplete();
+		return this.yield(next.value);
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/takeWhile.ts
+/**
+* Yields elements from the beginning of the source sequence as long as a predicate is true.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.takeWhile}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var TakeWhileEnumerator = class extends TyneqEnumerator {
+	predicate;
+	index = 0;
+	constructor(sourceEnumerator, predicate) {
+		super(sourceEnumerator);
+		this.predicate = predicate;
+	}
+	handleNext() {
+		const result = this.sourceEnumerator.next();
+		if (result.done) return this.done();
+		if (this.predicate(result.value, this.index++)) return this.yield(result.value);
+		return this.earlyComplete();
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/tap.ts
+/**
+* Invokes a side-effect action for each element without modifying the sequence.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.tap}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var TapEnumerator = class extends TyneqEnumerator {
+	action;
+	index = 0;
+	constructor(sourceEnumerator, action) {
+		super(sourceEnumerator);
+		this.action = action;
+	}
+	handleNext() {
+		const next = this.sourceEnumerator.next();
+		if (next.done) return this.done();
+		this.action(next.value, this.index++);
+		return this.yield(next.value);
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/tapIf.ts
+/**
+* Conditionally invokes a side-effect action for each element based on a predicate.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.tapIf}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var TapIfEnumerator = class extends TyneqEnumerator {
+	action;
+	predicate;
+	index = 0;
+	constructor(sourceEnumerator, action, predicate) {
+		super(sourceEnumerator);
+		this.action = action;
+		this.predicate = predicate;
+	}
+	handleNext() {
+		const next = this.sourceEnumerator.next();
+		if (next.done) return this.done();
+		if (this.predicate()) this.action(next.value, this.index);
+		this.index++;
+		return this.yield(next.value);
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/throttle.ts
+/**
+* Yields every nth element from the source sequence.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.throttle}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var ThrottleEnumerator = class extends TyneqEnumerator {
+	count;
+	index = -1;
+	constructor(sourceEnumerator, count) {
+		super(sourceEnumerator);
+		this.count = count;
+	}
+	handleNext() {
+		while (true) {
+			const { value, done } = this.sourceEnumerator.next();
+			if (done) return this.done();
+			this.index++;
+			if (this.index % this.count === 0) return this.yield(value);
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/where.ts
+/**
+* Filters elements using a predicate.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.where}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var WhereEnumerator = class extends TyneqEnumerator {
+	index = 0;
+	predicate;
+	constructor(sourceEnumerator, predicate) {
+		super(sourceEnumerator);
+		this.predicate = predicate;
+	}
+	handleNext() {
+		while (true) {
+			const { value, done } = this.sourceEnumerator.next();
+			if (done) return this.done();
+			if (this.predicate(value, this.index++)) return this.yield(value);
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/window.ts
+/**
+* Yields overlapping or tumbling windows (fixed-size sub-arrays) over the source sequence.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+* Windows with fewer elements than `size` are not yielded.
+* Each yielded array is a snapshot - mutating it does not affect subsequent windows.
+*
+* @see {@link TyneqSequence.window}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var WindowEnumerator = class extends TyneqEnumerator {
+	size;
+	step;
+	buffer = [];
+	started = false;
+	constructor(sourceEnumerator, size, step) {
+		super(sourceEnumerator);
+		this.size = size;
+		this.step = step;
+	}
+	handleNext() {
+		if (!this.started) {
+			this.started = true;
+			while (this.buffer.length < this.size) {
+				const next = this.sourceEnumerator.next();
+				if (next.done) return this.done();
+				this.buffer.push(next.value);
+			}
+			return this.yield(this.buffer.slice());
+		}
+		if (this.step <= this.size) this.buffer = this.buffer.slice(this.step);
+		else {
+			this.buffer = [];
+			const toSkip = this.step - this.size;
+			for (let i = 0; i < toSkip; i++) if (this.sourceEnumerator.next().done) return this.done();
+		}
+		while (this.buffer.length < this.size) {
+			const next = this.sourceEnumerator.next();
+			if (next.done) return this.done();
+			this.buffer.push(next.value);
+		}
+		return this.yield(this.buffer.slice());
+	}
+};
+//#endregion
+//#region src/enumerators/streaming/zip.ts
+/**
+* Merges two sequences element-by-element using a selector.
+*
+* @remarks
+* Deferred. Source is not enumerated until the returned sequence is iterated.
+*
+* @see {@link TyneqSequence.zip}
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var ZipEnumerator = class extends TyneqEnumerator {
+	otherEnumerator;
+	selector;
+	constructor(sourceEnumerator, other, selector) {
+		super(sourceEnumerator);
+		this.otherEnumerator = other[Symbol.iterator]();
+		this.selector = selector;
+	}
+	handleNext() {
+		const first = this.sourceEnumerator.next();
+		if (first.done) {
+			this.disposeAdditional();
+			return this.done();
+		}
+		const second = this.otherEnumerator.next();
+		if (second.done) return this.earlyComplete();
+		return this.yield(this.selector(first.value, second.value));
+	}
+	disposeAdditional() {
+		EnumeratorUtility.tryDispose(this.otherEnumerator);
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/backsert.ts
+/**
+* Inserts a second sequence at a specified offset from the end of the source sequence.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.backsert}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var BacksertEnumerator = class extends TyneqEnumerator {
+	other;
+	backIndex;
+	buffer = [];
+	current = 0;
+	constructor(sourceEnumerator, backIndex, other) {
+		super(sourceEnumerator);
+		this.backIndex = backIndex;
+		this.other = other;
+	}
+	initialize() {
+		const source = Array.from(EnumeratorUtility.toIterable(this.sourceEnumerator));
+		const other = Array.from(this.other);
+		const insertionIndex = Math.max(0, source.length - this.backIndex);
+		this.buffer = [
+			...source.slice(0, insertionIndex),
+			...other,
+			...source.slice(insertionIndex)
+		];
+		this.current = 0;
+	}
+	handleNext() {
+		if (this.current >= this.buffer.length) return this.done();
+		return this.yield(this.buffer[this.current++]);
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/distinct.ts
+/**
+* Returns distinct elements by eliminating duplicates.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.distinct}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var DistinctEnumerator = class extends TyneqEnumerator {
+	seenValues = /* @__PURE__ */ new Set();
+	constructor(sourceEnumerator) {
+		super(sourceEnumerator);
+	}
+	handleNext() {
+		while (true) {
+			const { done, value } = this.sourceEnumerator.next();
+			if (done) return this.done();
+			if (!this.seenValues.has(value)) {
+				this.seenValues.add(value);
+				return this.yield(value);
+			}
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/distinctBy.ts
+/**
+* Returns distinct elements by eliminating duplicates based on a key selector.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.distinctBy}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var DistinctByEnumerator = class extends TyneqEnumerator {
+	seenValues = /* @__PURE__ */ new Set();
+	keySelector;
+	constructor(sourceEnumerator, keySelector) {
+		super(sourceEnumerator);
+		this.keySelector = keySelector;
+	}
+	handleNext() {
+		while (true) {
+			const { done, value } = this.sourceEnumerator.next();
+			if (done) return this.done();
+			const key = this.keySelector(value);
+			if (!this.seenValues.has(key)) {
+				this.seenValues.add(key);
+				return this.yield(value);
+			}
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/except.ts
+/**
+* Returns elements from the source sequence that are not present in a second sequence.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.except}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var ExceptEnumerator = class extends TyneqEnumerator {
+	excludedValues;
+	excludeSet = /* @__PURE__ */ new Set();
+	constructor(sourceEnumerator, excludedValues) {
+		super(sourceEnumerator);
+		this.excludedValues = excludedValues;
+	}
+	initialize() {
+		this.excludeSet = new Set(this.excludedValues);
+	}
+	handleNext() {
+		while (true) {
+			const { done, value } = this.sourceEnumerator.next();
+			if (done) return this.done();
+			if (!this.excludeSet.has(value)) {
+				this.excludeSet.add(value);
+				return this.yield(value);
+			}
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/exceptBy.ts
+/**
+* Returns elements from the source sequence whose keys are not present in a second key sequence.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.exceptBy}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var ExceptByEnumerator = class extends TyneqEnumerator {
+	excludedKeys;
+	excludeSet = /* @__PURE__ */ new Set();
+	keySelector;
+	constructor(sourceEnumerator, excludedKeys, keySelector) {
+		super(sourceEnumerator);
+		this.excludedKeys = excludedKeys;
+		this.keySelector = keySelector;
+	}
+	initialize() {
+		this.excludeSet = new Set(this.excludedKeys);
+	}
+	handleNext() {
+		while (true) {
+			const { done, value } = this.sourceEnumerator.next();
+			if (done) return this.done();
+			const key = this.keySelector(value);
+			if (!this.excludeSet.has(key)) {
+				this.excludeSet.add(key);
+				return this.yield(value);
+			}
+		}
+	}
+};
+//#endregion
+//#region src/utility/DefaultingMap.ts
+/**
+* `Map` subclass with convenience helpers for initialise-on-first-access patterns.
+*
+* @internal
+*/
+var DefaultingMap = class extends Map {
+	/** Returns the value for `key`, or initialises and stores it via `initValue()` if absent. */
+	getOrInit(key, initValue) {
+		if (!this.has(key)) this.set(key, initValue());
+		return this.get(key);
+	}
+	/** Sets `key` to `initValue` if absent; otherwise replaces the current value with `updateValue(current)`. */
+	setOrUpdate(key, updateValue, initValue) {
+		if (!this.has(key)) {
+			this.set(key, initValue);
+			return;
+		}
+		this.set(key, updateValue(this.get(key)));
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/groupBy.ts
+/**
+* Groups elements by a key selector and projects each group through a result selector.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.groupBy}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var GroupByEnumerator = class extends TyneqEnumerator {
+	keySelector;
+	valueSelector;
+	resultSelector;
+	groupFactory;
+	lookupEnumerator;
+	lookup = new DefaultingMap();
+	constructor(sourceEnumerator, keySelector, valueSelector, resultSelector, groupFactory) {
+		super(sourceEnumerator);
+		this.keySelector = keySelector;
+		this.valueSelector = valueSelector;
+		this.resultSelector = resultSelector;
+		this.groupFactory = groupFactory;
+	}
+	initialize() {
+		while (true) {
+			const { done, value } = this.sourceEnumerator.next();
+			if (done) break;
+			const key = this.keySelector(value);
+			const mappedValue = this.valueSelector(value);
+			this.lookup.getOrInit(key, () => []).push(mappedValue);
+		}
+		this.lookupEnumerator = this.lookup.entries();
+	}
+	handleNext() {
+		if (this.lookupEnumerator === void 0) return this.done();
+		const { done, value } = this.lookupEnumerator.next();
+		if (done) return this.done();
+		const [key, values] = value;
+		const result = this.resultSelector(key, this.groupFactory(values));
+		return this.yield(result);
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/groupJoin.ts
+/**
+* Correlates outer elements with groups of matching inner elements.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.groupJoin}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var GroupJoinEnumerator = class extends TyneqEnumerator {
+	innerSource;
+	outerKeySelector;
+	innerKeySelector;
+	resultSelector;
+	groupFactory;
+	innerLookup = new DefaultingMap();
+	constructor(sourceEnumerator, innerSource, outerKeySelector, innerKeySelector, resultSelector, groupFactory) {
+		super(sourceEnumerator);
+		this.innerSource = innerSource;
+		this.outerKeySelector = outerKeySelector;
+		this.innerKeySelector = innerKeySelector;
+		this.resultSelector = resultSelector;
+		this.groupFactory = groupFactory;
+	}
+	initialize() {
+		for (const innerItem of this.innerSource) {
+			const key = this.innerKeySelector(innerItem);
+			this.innerLookup.getOrInit(key, () => []).push(innerItem);
+		}
+	}
+	handleNext() {
+		const { done, value: outerItem } = this.sourceEnumerator.next();
+		if (done) return this.done();
+		const outerKey = this.outerKeySelector(outerItem);
+		const innerItems = this.innerLookup.get(outerKey) ?? [];
+		const resultItem = this.resultSelector(outerItem, this.groupFactory(innerItems));
+		return this.yield(resultItem);
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/intersect.ts
+/**
+* Returns elements that are present in both the source and a second sequence.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.intersect}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var IntersectEnumerator = class extends TyneqEnumerator {
+	otherValues;
+	intersectionValues = /* @__PURE__ */ new Set();
+	bufferedValues = /* @__PURE__ */ new Set();
+	constructor(sourceEnumerator, otherValues) {
+		super(sourceEnumerator);
+		this.otherValues = otherValues;
+	}
+	initialize() {
+		this.intersectionValues = new Set(this.otherValues);
+	}
+	handleNext() {
+		while (true) {
+			const { done, value } = this.sourceEnumerator.next();
+			if (done) return this.done();
+			if (this.intersectionValues.has(value) && !this.bufferedValues.has(value)) {
+				this.bufferedValues.add(value);
+				return this.yield(value);
+			}
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/intersectBy.ts
+/**
+* Returns elements whose keys appear in both the source and a second key sequence.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.intersectBy}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var IntersectByEnumerator = class extends TyneqEnumerator {
+	otherValues;
+	keySelector;
+	intersectionKeys = /* @__PURE__ */ new Set();
+	bufferedKeys = /* @__PURE__ */ new Set();
+	constructor(sourceEnumerator, otherValues, keySelector) {
+		super(sourceEnumerator);
+		this.otherValues = otherValues;
+		this.keySelector = keySelector;
+	}
+	initialize() {
+		this.intersectionKeys = new Set(this.otherValues);
+	}
+	handleNext() {
+		while (true) {
+			const { done, value } = this.sourceEnumerator.next();
+			if (done) return this.done();
+			const key = this.keySelector(value);
+			if (this.intersectionKeys.has(key) && !this.bufferedKeys.has(key)) {
+				this.bufferedKeys.add(key);
+				return this.yield(value);
+			}
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/join.ts
+/**
+* Correlates outer elements with matching inner elements using a key equality comparison.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.join}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var JoinEnumerator = class extends TyneqEnumerator {
+	innerSource;
+	outerKeySelector;
+	innerKeySelector;
+	resultSelector;
+	innerLookup = new DefaultingMap();
+	pendingOuter;
+	pendingMatches = null;
+	pendingIndex = 0;
+	constructor(sourceEnumerator, innerSource, outerKeySelector, innerKeySelector, resultSelector) {
+		super(sourceEnumerator);
+		this.innerSource = innerSource;
+		this.outerKeySelector = outerKeySelector;
+		this.innerKeySelector = innerKeySelector;
+		this.resultSelector = resultSelector;
+	}
+	initialize() {
+		for (const innerItem of this.innerSource) {
+			const key = this.innerKeySelector(innerItem);
+			this.innerLookup.getOrInit(key, () => []).push(innerItem);
+		}
+	}
+	handleNext() {
+		while (true) {
+			if (this.pendingMatches !== null) {
+				if (this.pendingIndex < this.pendingMatches.length) return this.yield(this.resultSelector(this.pendingOuter, this.pendingMatches[this.pendingIndex++]));
+				this.pendingMatches = null;
+			}
+			const nextOuter = this.sourceEnumerator.next();
+			if (nextOuter.done) return this.done();
+			const outerItem = nextOuter.value;
+			const outerKey = this.outerKeySelector(outerItem);
+			const innerItems = this.innerLookup.get(outerKey);
+			if (innerItems === void 0 || innerItems.length === 0) continue;
+			this.pendingOuter = outerItem;
+			this.pendingMatches = innerItems;
+			this.pendingIndex = 0;
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/reverse.ts
+/**
+* Reverses the order of elements in the source sequence.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.reverse}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var ReverseEnumerator = class extends TyneqEnumerator {
+	buffer = [];
+	index = -1;
+	constructor(sourceEnumerator) {
+		super(sourceEnumerator);
+	}
+	initialize() {
+		while (true) {
+			const { done, value } = this.sourceEnumerator.next();
+			if (done) {
+				this.index = this.buffer.length - 1;
+				break;
+			}
+			this.buffer.push(value);
+		}
+	}
+	handleNext() {
+		if (this.index < 0) return this.done();
+		return this.yield(this.buffer[this.index--]);
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/shuffle.ts
+/**
+* Returns the elements of the source sequence in a random order.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.shuffle}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var ShuffleEnumerator = class extends TyneqEnumerator {
+	buffer = [];
+	currentIndex = 0;
+	constructor(sourceEnumerator) {
+		super(sourceEnumerator);
+	}
+	initialize() {
+		const buffer = Array.from(this.toIterable(this.sourceEnumerator));
+		this.shuffle(buffer);
+		this.buffer = buffer;
+	}
+	handleNext() {
+		if (this.buffer.length <= this.currentIndex) return this.done();
+		const result = this.buffer[this.currentIndex];
+		this.currentIndex++;
+		return this.yield(result);
+	}
+	shuffle(array) {
+		for (let i = array.length - 1; i > 0; i--) {
+			const j = Math.floor(Math.random() * (i + 1));
+			[array[i], array[j]] = [array[j], array[i]];
+		}
+		return array;
+	}
+	toIterable(sourceEnumerator) {
+		return { [Symbol.iterator]: () => sourceEnumerator };
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/union.ts
+/**
+* Returns the set union of the source and a second sequence, eliminating duplicates.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.union}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var UnionEnumerator = class extends TyneqEnumerator {
+	otherValues;
+	bufferedValues = /* @__PURE__ */ new Set();
+	currentEnumerator;
+	isSourceDone = false;
+	constructor(sourceEnumerator, otherValues) {
+		super(sourceEnumerator);
+		this.otherValues = otherValues;
+		this.currentEnumerator = this.sourceEnumerator;
+	}
+	handleNext() {
+		while (true) {
+			const { done, value } = this.currentEnumerator.next();
+			if (done) {
+				if (this.isSourceDone) return this.done();
+				this.isSourceDone = true;
+				this.currentEnumerator = this.otherValues[Symbol.iterator]();
+				continue;
+			}
+			if (!this.bufferedValues.has(value)) {
+				this.bufferedValues.add(value);
+				return this.yield(value);
+			}
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/unionBy.ts
+/**
+* Returns the set union of the source and a second sequence, eliminating duplicates by key.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.unionBy}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var UnionByEnumerator = class extends TyneqEnumerator {
+	otherValues;
+	bufferedKeys = /* @__PURE__ */ new Set();
+	keySelector;
+	currentEnumerator;
+	isSourceDone = false;
+	constructor(sourceEnumerator, otherValues, keySelector) {
+		super(sourceEnumerator);
+		this.otherValues = otherValues;
+		this.currentEnumerator = this.sourceEnumerator;
+		this.keySelector = keySelector;
+	}
+	handleNext() {
+		while (true) {
+			const { done, value } = this.currentEnumerator.next();
+			if (done) {
+				if (this.isSourceDone) return this.done();
+				this.isSourceDone = true;
+				this.currentEnumerator = this.otherValues[Symbol.iterator]();
+				continue;
+			}
+			const key = this.keySelector(value);
+			if (!this.bufferedKeys.has(key)) {
+				this.bufferedKeys.add(key);
+				return this.yield(value);
+			}
+		}
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/permutations.ts
+/**
+* Yields all permutations of the elements in the source sequence.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.permutations}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var PermutationsEnumerator = class extends TyneqEnumerator {
+	buffer = [];
+	c = [];
+	n = 0;
+	i = -1;
+	initialize() {
+		this.buffer = Array.from(EnumeratorUtility.toIterable(this.sourceEnumerator));
+		this.n = this.buffer.length;
+		this.c = new Array(this.n).fill(0);
+	}
+	handleNext() {
+		if (this.i === -1) {
+			this.i = 1;
+			return this.yield([...this.buffer]);
+		}
+		while (this.i < this.n) if (this.c[this.i] < this.i) {
+			const swapIndex = this.i % 2 === 0 ? 0 : this.c[this.i];
+			[this.buffer[swapIndex], this.buffer[this.i]] = [this.buffer[this.i], this.buffer[swapIndex]];
+			this.c[this.i]++;
+			this.i = 1;
+			return this.yield([...this.buffer]);
+		} else {
+			this.c[this.i] = 0;
+			this.i++;
+		}
+		return this.done();
+	}
+};
+//#endregion
+//#region src/core/TyneqEnumerableBase.ts
+var TyneqEnumerableBase = @sequence class extends TyneqEnumerableCore {
+	@builtin({ kind: "terminal" }) aggregate(seed, func, resultSelector) {
+		return new AggregateOperator(this, seed, func, resultSelector).process();
+	}
+	@builtin({ kind: "terminal" }) all(predicate) {
+		return new AllOperator(this, predicate).process();
+	}
+	@builtin({ kind: "terminal" }) any(predicate) {
+		return new AnyOperator(this, predicate).process();
+	}
+	@builtin({ kind: "terminal" }) average(selector) {
+		return new AverageOperator(this, selector).process();
+	}
+	@builtin({ kind: "terminal" }) consume() {
+		new ConsumeOperator(this).process();
+	}
+	@builtin({ kind: "terminal" }) contains(value, equalityComparer) {
+		return new ContainsOperator(this, value, equalityComparer).process();
+	}
+	@builtin({ kind: "terminal" }) count() {
+		return new CountOperator(this).process();
+	}
+	@builtin({ kind: "terminal" }) countBy(predicate) {
+		return new CountByOperator(this, predicate).process();
+	}
+	@builtin({ kind: "terminal" }) elementAt(index) {
+		ArgumentUtility.checkSafeInteger({ index });
+		ArgumentUtility.checkNonNegative({ index });
+		return new ElementAtOperator(this, index).process();
+	}
+	@builtin({ kind: "terminal" }) elementAtOrDefault(index, defaultValue) {
+		ArgumentUtility.checkSafeInteger({ index });
+		ArgumentUtility.checkNonNegative({ index });
+		return new ElementAtOrDefaultOperator(this, index, defaultValue).process();
+	}
+	@builtin({ kind: "terminal" }) first(predicate) {
+		return new FirstOperator(this, predicate).process();
+	}
+	@builtin({ kind: "terminal" }) firstOrDefault(predicate, defaultValue) {
+		return new FirstOrDefaultOperator(this, predicate, defaultValue).process();
+	}
+	@builtin({ kind: "terminal" }) indexOf(predicate, startIndex = 0) {
+		return new IndexOfOperator(this, predicate, startIndex).process();
+	}
+	@builtin({ kind: "terminal" }) isNullOrEmpty() {
+		return new IsNullOrEmptyOperator(this).process();
+	}
+	@builtin({ kind: "terminal" }) last(predicate) {
+		return new LastOperator(this, predicate).process();
+	}
+	@builtin({ kind: "terminal" }) lastOrDefault(predicate, defaultValue) {
+		return new LastOrDefaultOperator(this, predicate, defaultValue).process();
+	}
+	@builtin({ kind: "terminal" }) max(comparer) {
+		return new ExtremumOperator(this, 1, "max", comparer).process();
+	}
+	@builtin({ kind: "terminal" }) maxBy(keySelector, comparer) {
+		return new ExtremumByOperator(this, keySelector, 1, "maxBy", comparer).process();
+	}
+	@builtin({ kind: "terminal" }) min(comparer) {
+		return new ExtremumOperator(this, -1, "min", comparer).process();
+	}
+	@builtin({ kind: "terminal" }) minBy(keySelector, comparer) {
+		return new ExtremumByOperator(this, keySelector, -1, "minBy", comparer).process();
+	}
+	@builtin({ kind: "terminal" }) minMax(comparer) {
+		return new MinMaxOperator(this, comparer).process();
+	}
+	@builtin({ kind: "terminal" }) sequenceEqual(other, equalityComparer) {
+		return new SequenceEqualOperator(this, other, equalityComparer).process();
+	}
+	@builtin({ kind: "terminal" }) single(predicate) {
+		return new SingleOperator(this, predicate).process();
+	}
+	@builtin({ kind: "terminal" }) singleOrDefault(predicate, defaultValue) {
+		return new SingleOrDefaultOperator(this, predicate, defaultValue).process();
+	}
+	@builtin({ kind: "terminal" }) endsWith(sequence, equalityComparer) {
+		return new EndsWithOperator(this, sequence, equalityComparer).process();
+	}
+	@builtin({ kind: "terminal" }) startsWith(sequence, equalityComparer) {
+		return new StartsWithOperator(this, sequence, equalityComparer).process();
+	}
+	@builtin({ kind: "terminal" }) sum(selector) {
+		return new SumOperator(this, selector).process();
+	}
+	@builtin({ kind: "terminal" }) toArray() {
+		return new ToArrayOperator(this).process();
+	}
+	@builtin({ kind: "terminal" }) toAsync() {
+		return new ToAsyncOperator(this).process();
+	}
+	@builtin({ kind: "terminal" }) toMap(selector) {
+		return new ToMapOperator(this, selector).process();
+	}
+	@builtin({ kind: "terminal" }) toRecord(selector) {
+		return new ToRecordOperator(this, selector).process();
+	}
+	@builtin({ kind: "terminal" }) toSet() {
+		return new ToSetOperator(this).process();
+	}
+	@builtin({ kind: "streaming" }) ofType(guard) {
+		ArgumentUtility.checkNotOptional({ guard });
+		return this.createSequence(() => new OfTypeEnumerator(this.getEnumerator(), guard), this.createNode("ofType", "streaming", [guard]));
+	}
+	@builtin({ kind: "streaming" }) append(item) {
+		return this.createSequence(() => new AppendEnumerator(this.getEnumerator(), item), this.createNode("append", "streaming", [item]));
+	}
+	@builtin({ kind: "streaming" }) chunk(size) {
+		ArgumentUtility.checkSafeInteger({ size });
+		ArgumentUtility.checkPositive({ size });
+		return this.createSequence(() => new ChunkEnumerator(this.getEnumerator(), size), this.createNode("chunk", "streaming", [size]));
+	}
+	@builtin({ kind: "streaming" }) concat(other) {
+		ArgumentUtility.checkNotOptional({ other });
+		ArgumentUtility.checkIterable({ other });
+		return this.createSequence(() => new ConcatEnumerator(this.getEnumerator(), other), this.createNode("concat", "streaming", [other]));
+	}
+	@builtin({ kind: "streaming" }) defaultIfEmpty(defaultValue) {
+		return this.createSequence(() => new DefaultIfEmptyEnumerator(this.getEnumerator(), defaultValue), this.createNode("defaultIfEmpty", "streaming", [defaultValue]));
+	}
+	@builtin({ kind: "streaming" }) flatten() {
+		const self = this;
+		return self.createSequence(() => new FlattenEnumerator(self.getEnumerator()), self.createNode("flatten", "streaming"));
+	}
+	@builtin({ kind: "streaming" }) pairwise() {
+		return this.createSequence(() => new PairwiseEnumerator(this.getEnumerator()), this.createNode("pairwise", "streaming"));
+	}
+	@builtin({ kind: "streaming" }) populate(value) {
+		return this.createSequence(() => new PopulateEnumerator(this.getEnumerator(), value), this.createNode("populate", "streaming", [value]));
+	}
+	@builtin({ kind: "streaming" }) prepend(item) {
+		return this.createSequence(() => new PrependEnumerator(this.getEnumerator(), item), this.createNode("prepend", "streaming", [item]));
+	}
+	@builtin({ kind: "streaming" }) scan(seed, accumulator) {
+		ArgumentUtility.checkNotOptional({ accumulator });
+		ArgumentUtility.checkFunction({ accumulator });
+		return this.createSequence(() => new ScanEnumerator(this.getEnumerator(), seed, accumulator), this.createNode("scan", "streaming", [seed, accumulator]));
+	}
+	@builtin({ kind: "streaming" }) select(selector) {
+		ArgumentUtility.checkNotOptional({ selector });
+		return this.createSequence(() => new SelectEnumerator(this.getEnumerator(), selector), this.createNode("select", "streaming", [selector]));
+	}
+	@builtin({ kind: "streaming" }) selectMany(selector) {
+		ArgumentUtility.checkNotOptional({ selector });
+		return this.createSequence(() => new SelectManyEnumerator(this.getEnumerator(), selector), this.createNode("selectMany", "streaming", [selector]));
+	}
+	@builtin({ kind: "streaming" }) window(size, step = 1) {
+		ArgumentUtility.checkSafeInteger({ size });
+		ArgumentUtility.checkPositive({ size });
+		ArgumentUtility.checkSafeInteger({ step });
+		ArgumentUtility.checkPositive({ step });
+		return this.createSequence(() => new WindowEnumerator(this.getEnumerator(), size, step), this.createNode("window", "streaming", [size, step]));
+	}
+	@builtin({ kind: "streaming" }) repeat(count) {
+		ArgumentUtility.checkNonNegative({ count });
+		ArgumentUtility.checkInteger({ count });
+		return this.createSequence(() => new RepeatSequenceEnumerator(this.getEnumerator(), this, count), this.createNode("repeat", "streaming", [count]));
+	}
+	@builtin({ kind: "streaming" }) skip(count) {
+		ArgumentUtility.checkSafeInteger({ count });
+		ArgumentUtility.checkNonNegative({ count });
+		return this.createSequence(() => new SkipEnumerator(this.getEnumerator(), count), this.createNode("skip", "streaming", [count]));
+	}
+	@builtin({ kind: "streaming" }) skipLast(count) {
+		ArgumentUtility.checkSafeInteger({ count });
+		ArgumentUtility.checkNonNegative({ count });
+		return this.createSequence(() => new SkipLastEnumerator(this.getEnumerator(), count), this.createNode("skipLast", "streaming", [count]));
+	}
+	@builtin({ kind: "streaming" }) skipUntil(predicate) {
+		ArgumentUtility.checkNotOptional({ predicate });
+		return this.createSequence(() => new SkipUntilEnumerator(this.getEnumerator(), predicate), this.createNode("skipUntil", "streaming", [predicate]));
+	}
+	@builtin({ kind: "streaming" }) skipWhile(predicate) {
+		ArgumentUtility.checkNotOptional({ predicate });
+		return this.createSequence(() => new SkipWhileEnumerator(this.getEnumerator(), predicate), this.createNode("skipWhile", "streaming", [predicate]));
+	}
+	@builtin({ kind: "streaming" }) slice(start, end) {
+		ArgumentUtility.checkNonNegative({ start });
+		ArgumentUtility.checkSafeInteger({ start });
+		if (end !== void 0) {
+			ArgumentUtility.checkNonNegative({ end });
+			ArgumentUtility.checkSafeInteger({ end });
+			if (end < start) throw new ArgumentOutOfRangeError("end", "`end` must be greater than or equal to `start`.");
+		}
+		const resolvedEnd = end ?? Number.MAX_SAFE_INTEGER;
+		return this.createSequence(() => new SliceEnumerator(this.getEnumerator(), start, resolvedEnd), this.createNode("slice", "streaming", [start, end]));
+	}
+	@builtin({ kind: "streaming" }) split(splitOn) {
+		ArgumentUtility.checkNotOptional({ splitOn });
+		return this.createSequence(() => new SplitEnumerator(this.getEnumerator(), splitOn), this.createNode("split", "streaming", [splitOn]));
+	}
+	@builtin({ kind: "streaming" }) take(count) {
+		ArgumentUtility.checkSafeInteger({ count });
+		ArgumentUtility.checkNonNegative({ count });
+		return this.createSequence(() => new TakeEnumerator(this.getEnumerator(), count), this.createNode("take", "streaming", [count]));
+	}
+	@builtin({ kind: "streaming" }) takeUntil(predicate) {
+		ArgumentUtility.checkNotOptional({ predicate });
+		return this.createSequence(() => new TakeUntilEnumerator(this.getEnumerator(), predicate), this.createNode("takeUntil", "streaming", [predicate]));
+	}
+	@builtin({ kind: "streaming" }) takeWhile(predicate) {
+		ArgumentUtility.checkNotOptional({ predicate });
+		return this.createSequence(() => new TakeWhileEnumerator(this.getEnumerator(), predicate), this.createNode("takeWhile", "streaming", [predicate]));
+	}
+	@builtin({ kind: "streaming" }) tap(action) {
+		ArgumentUtility.checkNotOptional({ action });
+		return this.createSequence(() => new TapEnumerator(this.getEnumerator(), action), this.createNode("tap", "streaming", [action]));
+	}
+	@builtin({ kind: "streaming" }) tapIf(action, predicate) {
+		ArgumentUtility.checkNotOptional({ action });
+		ArgumentUtility.checkNotOptional({ predicate });
+		return this.createSequence(() => new TapIfEnumerator(this.getEnumerator(), action, predicate), this.createNode("tapIf", "streaming", [action, predicate]));
+	}
+	@builtin({ kind: "streaming" }) throttle(count) {
+		ArgumentUtility.checkSafeInteger({ count });
+		ArgumentUtility.checkPositive({ count });
+		return this.createSequence(() => new ThrottleEnumerator(this.getEnumerator(), count), this.createNode("throttle", "streaming", [count]));
+	}
+	@builtin({ kind: "streaming" }) where(predicate) {
+		ArgumentUtility.checkNotOptional({ predicate });
+		return this.createSequence(() => new WhereEnumerator(this.getEnumerator(), predicate), this.createNode("where", "streaming", [predicate]));
+	}
+	@builtin({ kind: "streaming" }) zip(other, selector) {
+		ArgumentUtility.checkNotOptional({ other });
+		ArgumentUtility.checkIterable({ other });
+		ArgumentUtility.checkNotOptional({ selector });
+		return this.createSequence(() => new ZipEnumerator(this.getEnumerator(), other, selector), this.createNode("zip", "streaming", [other, selector]));
+	}
+	@builtin({ kind: "buffer" }) backsert(index, other) {
+		ArgumentUtility.checkNotOptional({ other });
+		ArgumentUtility.checkSafeInteger({ index });
+		ArgumentUtility.checkNonNegative({ index });
+		ArgumentUtility.checkIterable({ other });
+		return this.createSequence(() => new BacksertEnumerator(this.getEnumerator(), index, other), this.createNode("backsert", "buffer", [index, other]));
+	}
+	@builtin({ kind: "buffer" }) distinct() {
+		return this.createSequence(() => new DistinctEnumerator(this.getEnumerator()), this.createNode("distinct", "buffer"));
+	}
+	@builtin({ kind: "buffer" }) distinctBy(keySelector) {
+		ArgumentUtility.checkNotOptional({ keySelector });
+		return this.createSequence(() => new DistinctByEnumerator(this.getEnumerator(), keySelector), this.createNode("distinctBy", "buffer", [keySelector]));
+	}
+	@builtin({ kind: "buffer" }) except(excludedValues) {
+		ArgumentUtility.checkNotOptional({ excludedValues });
+		ArgumentUtility.checkIterable({ excludedValues });
+		return this.createSequence(() => new ExceptEnumerator(this.getEnumerator(), excludedValues), this.createNode("except", "buffer", [excludedValues]));
+	}
+	@builtin({ kind: "buffer" }) exceptBy(excludedKeys, keySelector) {
+		ArgumentUtility.checkNotOptional({ excludedKeys });
+		ArgumentUtility.checkIterable({ excludedKeys });
+		ArgumentUtility.checkNotOptional({ keySelector });
+		return this.createSequence(() => new ExceptByEnumerator(this.getEnumerator(), excludedKeys, keySelector), this.createNode("exceptBy", "buffer", [excludedKeys, keySelector]));
+	}
+	@builtin({ kind: "buffer" }) groupBy(keySelector, valueSelector, resultSelector) {
+		ArgumentUtility.checkNotOptional({ keySelector });
+		ArgumentUtility.checkNotOptional({ valueSelector });
+		ArgumentUtility.checkNotOptional({ resultSelector });
+		const groupFactory = (values) => this.createEnumerable({ getEnumerator: () => values[Symbol.iterator]() }, null);
+		return this.createSequence(() => new GroupByEnumerator(this.getEnumerator(), keySelector, valueSelector, resultSelector, groupFactory), this.createNode("groupBy", "buffer", [
+			keySelector,
+			valueSelector,
+			resultSelector
+		]));
+	}
+	@builtin({ kind: "buffer" }) groupJoin(inner, outerKeySelector, innerKeySelector, resultSelector) {
+		ArgumentUtility.checkNotOptional({ inner });
+		ArgumentUtility.checkIterable({ inner });
+		ArgumentUtility.checkNotOptional({ outerKeySelector });
+		ArgumentUtility.checkNotOptional({ innerKeySelector });
+		ArgumentUtility.checkNotOptional({ resultSelector });
+		const groupFactory = (values) => this.createEnumerable({ getEnumerator: () => values[Symbol.iterator]() }, null);
+		return this.createSequence(() => new GroupJoinEnumerator(this.getEnumerator(), inner, outerKeySelector, innerKeySelector, resultSelector, groupFactory), this.createNode("groupJoin", "buffer", [
+			inner,
+			outerKeySelector,
+			innerKeySelector,
+			resultSelector
+		]));
+	}
+	@builtin({ kind: "buffer" }) intersect(intersectedValues) {
+		ArgumentUtility.checkNotOptional({ intersectedValues });
+		ArgumentUtility.checkIterable({ intersectedValues });
+		return this.createSequence(() => new IntersectEnumerator(this.getEnumerator(), intersectedValues), this.createNode("intersect", "buffer", [intersectedValues]));
+	}
+	@builtin({ kind: "buffer" }) intersectBy(intersectedKeys, keySelector) {
+		ArgumentUtility.checkNotOptional({ intersectedKeys });
+		ArgumentUtility.checkIterable({ intersectedKeys });
+		ArgumentUtility.checkNotOptional({ keySelector });
+		return this.createSequence(() => new IntersectByEnumerator(this.getEnumerator(), intersectedKeys, keySelector), this.createNode("intersectBy", "buffer", [intersectedKeys, keySelector]));
+	}
+	@builtin({ kind: "buffer" }) join(inner, outerKeySelector, innerKeySelector, resultSelector) {
+		ArgumentUtility.checkNotOptional({ inner });
+		ArgumentUtility.checkIterable({ inner });
+		ArgumentUtility.checkNotOptional({ outerKeySelector });
+		ArgumentUtility.checkNotOptional({ innerKeySelector });
+		ArgumentUtility.checkNotOptional({ resultSelector });
+		return this.createSequence(() => new JoinEnumerator(this.getEnumerator(), inner, outerKeySelector, innerKeySelector, resultSelector), this.createNode("join", "buffer", [
+			inner,
+			outerKeySelector,
+			innerKeySelector,
+			resultSelector
+		]));
+	}
+	@builtin({ kind: "buffer" }) permutations() {
+		return this.createSequence(() => new PermutationsEnumerator(this.getEnumerator()), this.createNode("permutations", "buffer"));
+	}
+	@builtin({ kind: "buffer" }) reverse() {
+		return this.createSequence(() => new ReverseEnumerator(this.getEnumerator()), this.createNode("reverse", "buffer"));
+	}
+	@builtin({ kind: "buffer" }) shuffle() {
+		return this.createSequence(() => new ShuffleEnumerator(this.getEnumerator()), this.createNode("shuffle", "buffer"));
+	}
+	@builtin({ kind: "buffer" }) union(otherValues) {
+		ArgumentUtility.checkNotOptional({ otherValues });
+		ArgumentUtility.checkIterable({ otherValues });
+		return this.createSequence(() => new UnionEnumerator(this.getEnumerator(), otherValues), this.createNode("union", "buffer", [otherValues]));
+	}
+	@builtin({ kind: "buffer" }) unionBy(otherValues, keySelector) {
+		ArgumentUtility.checkNotOptional({ otherValues });
+		ArgumentUtility.checkIterable({ otherValues });
+		ArgumentUtility.checkNotOptional({ keySelector });
+		return this.createSequence(() => new UnionByEnumerator(this.getEnumerator(), otherValues, keySelector), this.createNode("unionBy", "buffer", [otherValues, keySelector]));
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/memoize.ts
+/**
+* Iterates a cached enumerable, replaying previously computed elements on subsequent iterations.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.memoize}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var MemoizeEnumerator = class extends TyneqBaseEnumerator {
+	cachedEnumerable;
+	index = 0;
+	constructor(cachedEnumerable) {
+		super();
+		this.cachedEnumerable = cachedEnumerable;
+	}
+	disposeSource() {}
+	handleNext() {
+		const result = this.cachedEnumerable.tryGetAtFromCache(this.index);
+		if (!result.has) return this.done();
+		this.index++;
+		return this.yield(result.value);
+	}
+};
+//#endregion
+//#region src/core/ordering/BaseEnumerableSorter.ts
+/**
+* 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
+*/
+var BaseEnumerableSorter = class {
+	/**
+	* 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, count) {
+		this.computeKeys([...source], count);
+		const indexMap = Array.from({ length: count }, (_, i) => i);
+		indexMap.sort((a, b) => this.compareKeys(a, b));
+		return indexMap;
+	}
+};
+//#endregion
+//#region src/core/ordering/TyneqEnumerableSorter.ts
+/**
+* Concrete sorter that extracts keys via a selector and compares them with a comparer.
+*
+* @remarks
+* Chains to a `next` sorter for secondary sort keys (thenBy). Stability is preserved by
+* falling back to index comparison when keys are equal at the innermost sorter level.
+*
+* @internal
+*/
+var TyneqEnumerableSorter = class extends BaseEnumerableSorter {
+	keys = [];
+	keySelector;
+	comparer;
+	descending;
+	next = null;
+	constructor(keySelector, comparer, descending, next) {
+		super();
+		ArgumentUtility.checkNotOptional({ keySelector });
+		ArgumentUtility.checkNotOptional({ comparer });
+		this.keySelector = keySelector;
+		this.comparer = comparer;
+		this.descending = descending ? -1 : 1;
+		this.next = next ?? null;
+	}
+	computeKeys(source, count) {
+		this.keys = new Array(count);
+		for (let i = 0; i < count; i++) this.keys[i] = this.keySelector(source[i]);
+		this.next?.computeKeys(source, count);
+	}
+	compareKeys(i, j) {
+		const result = this.comparer(this.keys[i], this.keys[j]) * this.descending;
+		if (result !== 0) return result;
+		if (this.next === null) return this.stabilityCompare(i, j);
+		return this.next.compareKeys(i, j);
+	}
+	stabilityCompare(i, j) {
+		return i - j;
+	}
+};
+//#endregion
+//#region src/enumerators/buffer/orderBy.ts
+/**
+* Yields the elements of an ordered sequence in sorted order.
+*
+* @remarks
+* Deferred. Source is fully buffered on the first iteration of the returned sequence.
+*
+* @see {@link TyneqSequence.orderBy}
+* @group Operators
+* @category Buffering
+* @internal
+*/
+var OrderByEnumerator = class extends TyneqBaseEnumerator {
+	buffer = [];
+	indexMap = [];
+	currentIndex = 0;
+	orderedEnumerable;
+	constructor(orderedEnumerable) {
+		super();
+		this.orderedEnumerable = orderedEnumerable;
+	}
+	initialize() {
+		this.buffer = Array.from(this.orderedEnumerable.source);
+		const sorter = this.getSorter(this.orderedEnumerable);
+		this.indexMap = sorter.sort(this.buffer, this.buffer.length);
+	}
+	handleNext() {
+		if (this.currentIndex >= this.indexMap.length) return this.done();
+		const index = this.indexMap[this.currentIndex++];
+		return this.yield(this.buffer[index]);
+	}
+	getSorter(base) {
+		let sorter = null;
+		for (let enumerable = base; enumerable !== null; enumerable = enumerable.parent) sorter = enumerable.getSorter(sorter);
+		return sorter;
+	}
+};
+//#endregion
+//#region src/core/ordering/TyneqOrderedEnumerable.ts
+const ASC_TO_DESC = {
+	"orderBy": "orderByDescending",
+	"thenBy": "thenByDescending"
+};
+const DESC_TO_ASC = {
+	"orderByDescending": "orderBy",
+	"thenByDescending": "thenBy"
+};
+var TyneqOrderedEnumerable = @sequence class TyneqOrderedEnumerable extends TyneqEnumerableBase {
+	keySelector;
+	comparer;
+	descending;
+	source;
+	parent;
+	[tyneqQueryNode];
+	constructor(source, keySelector, comparer, descending, parent, node) {
+		super();
+		ArgumentUtility.checkNotOptional({ source });
+		ArgumentUtility.checkNotOptional({ keySelector });
+		ArgumentUtility.checkNotOptional({ comparer });
+		this.source = source;
+		this.keySelector = keySelector;
+		this.comparer = comparer;
+		this.descending = descending;
+		this.parent = parent ?? null;
+		this[tyneqQueryNode] = node ?? null;
+	}
+	asc() {
+		if (!this.descending) return this;
+		const currentNode = this[tyneqQueryNode];
+		const node = currentNode ? new QueryNode(DESC_TO_ASC[currentNode.operatorName] ?? currentNode.operatorName, currentNode.args, currentNode.source, currentNode.category, currentNode.sourceKind) : null;
+		return new TyneqOrderedEnumerable(this.source, this.keySelector, this.comparer, false, this.parent ?? void 0, node);
+	}
+	desc() {
+		if (this.descending) return this;
+		const currentNode = this[tyneqQueryNode];
+		const node = currentNode ? new QueryNode(ASC_TO_DESC[currentNode.operatorName] ?? currentNode.operatorName, currentNode.args, currentNode.source, currentNode.category, currentNode.sourceKind) : null;
+		return new TyneqOrderedEnumerable(this.source, this.keySelector, this.comparer, true, this.parent ?? void 0, node);
+	}
+	getEnumerator() {
+		return new OrderByEnumerator(this);
+	}
+	getSorter(next) {
+		return new TyneqEnumerableSorter(this.keySelector, this.comparer, this.descending, next ?? void 0);
+	}
+	@builtin({ kind: "buffer" }) thenBy(keySelector, comparer) {
+		const node = new QueryNode("thenBy", comparer !== void 0 ? [keySelector, comparer] : [keySelector], this[tyneqQueryNode], "buffer");
+		return new TyneqOrderedEnumerable(this.source, keySelector, comparer ?? TyneqComparer.defaultComparer, false, this, node);
+	}
+	@builtin({ kind: "buffer" }) thenByDescending(keySelector, comparer) {
+		const node = new QueryNode("thenByDescending", comparer !== void 0 ? [keySelector, comparer] : [keySelector], this[tyneqQueryNode], "buffer");
+		return new TyneqOrderedEnumerable(this.source, keySelector, comparer ?? TyneqComparer.defaultComparer, true, this, node);
+	}
+	createEnumerable(factory, node) {
+		return new TyneqEnumerable(factory, node);
+	}
+	createOrderedEnumerable(keySelector, comparer, descending, node) {
+		return new TyneqOrderedEnumerable(this.source, keySelector, comparer, descending, this, node);
+	}
+	createCachedEnumerable(source, node) {
+		return new TyneqCachedEnumerable(source, node);
+	}
+};
+//#endregion
+//#region src/core/TyneqCachedEnumerable.ts
+var TyneqCachedEnumerable = @sequence class TyneqCachedEnumerable extends TyneqEnumerableBase {
+	source;
+	cache = [];
+	done = false;
+	sourceEnumerator = null;
+	[tyneqQueryNode];
+	constructor(source, node) {
+		super();
+		this.source = source;
+		this[tyneqQueryNode] = node ?? null;
+	}
+	getEnumerator() {
+		return new MemoizeEnumerator(this);
+	}
+	@builtin({ kind: "cache" }) refresh() {
+		this.cache = [];
+		this.done = false;
+		this.sourceEnumerator?.return?.();
+		this.sourceEnumerator = null;
+		return this;
+	}
+	tryGetAtFromCache(index) {
+		if (index < this.cache.length) return {
+			has: true,
+			value: this.cache[index]
+		};
+		if (this.done) return { has: false };
+		if (this.sourceEnumerator === null) this.sourceEnumerator = this.source.getEnumerator();
+		const next = this.sourceEnumerator.next();
+		if (!next.done) {
+			const value = next.value;
+			this.cache.push(value);
+			return {
+				has: true,
+				value
+			};
+		}
+		this.done = true;
+		this.sourceEnumerator.return?.();
+		this.sourceEnumerator = null;
+		return { has: false };
+	}
+	createEnumerable(factory, node) {
+		return new TyneqEnumerable(factory, node);
+	}
+	createOrderedEnumerable(keySelector, comparer, descending, node) {
+		return new TyneqOrderedEnumerable(this, keySelector, comparer, descending, void 0, node);
+	}
+	createCachedEnumerable(source, node) {
+		return new TyneqCachedEnumerable(source, node);
+	}
+};
+//#endregion
+//#region src/core/TyneqEnumerable.ts
+/**
+* The standard concrete implementation of {@link TyneqSequence}.
+*
+* @remarks
+* Created by operator methods in {@link TyneqEnumerableBase} and by the `Tyneq` factory.
+* Delegates element production to the `EnumeratorFactory` passed at construction.
+*
+* @internal
+*/
+var TyneqEnumerable = class TyneqEnumerable extends TyneqEnumerableBase {
+	enumeratorFactory;
+	[tyneqQueryNode];
+	constructor(enumeratorFactory, node) {
+		super();
+		ArgumentUtility.checkNotOptional({ enumeratorFactory });
+		this.enumeratorFactory = enumeratorFactory;
+		this[tyneqQueryNode] = node ?? null;
+	}
+	getEnumerator() {
+		return this.enumeratorFactory.getEnumerator();
+	}
+	createEnumerable(factory, node) {
+		return new TyneqEnumerable(factory, node);
+	}
+	createOrderedEnumerable(keySelector, comparer, descending, node) {
+		return new TyneqOrderedEnumerable(this, keySelector, comparer, descending, void 0, node);
+	}
+	createCachedEnumerable(source, node) {
+		return new TyneqCachedEnumerable(source, node);
+	}
+};
+//#endregion
+//#region src/plugin/decorators/source.ts
+/**
+* Static method decorator that registers the decorated method as a source operator.
+*
+* The method itself becomes the factory: when the compiler resolves a source node
+* whose `operatorName` matches the registered name, it calls the method with the
+* node's `args`. No duplication of implementation - the registration points directly
+* at the method.
+*
+* The operator name defaults to the method name, so `@source()` is sufficient when
+* they match.
+*
+* @param options - Optional config. Omit entirely to use all defaults.
+*
+* @example
+* ```ts
+* import { source } from "tyneq/plugin";
+* import { Tyneq } from "tyneq";
+*
+* class MySources {
+*     @source()
+*     public static fibonacci(count: number): ReturnType<typeof Tyneq.range> {
+*         // registered as "fibonacci"
+*     }
+*
+*     @source({ name: "fib2", source: "external" })
+*     public static fibonacci2(count: number): ReturnType<typeof Tyneq.range> {
+*         // registered as "fib2"
+*     }
+* }
+* ```
+*
+* @group Decorators
+*/
+function source(options = {}) {
+	return function(method, context) {
+		const operatorName = options.name ?? context.name;
+		const operatorSource = options.source ?? "external";
+		OperatorRegistry.registerSource(operatorName, method, operatorSource);
+	};
+}
+//#endregion
+//#region src/plugin/RegistrationUtility.ts
+/**
+* Low-level helpers used by every decorator and registration function in `src/plugin`.
+*
+* @remarks
+* These methods centralise two patterns that would otherwise be copy-pasted into every
+* operator `impl` closure:
+*
+* - {@link buildEnumerable} - validate, create a query node, then call
+*   `createEnumerable`. Used by every standard operator decorator and factory.
+* - {@link buildQueryNode} - create a query node only. Used by `createOrderedOperator`
+*   and `createCachedOperator`, which construct the result sequence themselves.
+*
+* `asSequenceFactory` is kept private to this class; it exists only to resolve the
+* `protected` access modifier on `createEnumerable` via a structural double-cast.
+*
+* @internal
+*/
+var RegistrationUtility = class RegistrationUtility {
+	constructor() {}
+	/**
+	* Builds a new sequence from an enumerator factory and registers a query plan node.
+	*
+	* @remarks
+	* Every standard (non-terminal, non-ordered, non-cached) operator `impl` follows
+	* the same pattern: get the `SequenceFactory` view of `this`, create a `QueryNode`,
+	* then call `factory.createEnumerable(enumeratorFactory, node)`. This method
+	* centralises that pattern so decorator and factory `impl` bodies stay minimal.
+	*
+	* @param sequence - The current sequence (`this` inside an `impl` function).
+	* @param name - Operator name, used as the query node label.
+	* @param userArgs - Arguments passed by the caller, captured in the query node.
+	* @param category - Operator category for the query node.
+	* @param enumeratorFactory - The factory that produces the new enumerator.
+	*/
+	static buildEnumerable(sequence, name, userArgs, category, enumeratorFactory) {
+		const factory = RegistrationUtility.asSequenceFactory(sequence);
+		const node = new QueryNode(name, userArgs, factory[tyneqQueryNode], category);
+		return factory.createEnumerable(enumeratorFactory, node);
+	}
+	/**
+	* Creates a `QueryPlanNode` for an operator, linked to the upstream node on `sequence`.
+	*
+	* @remarks
+	* Used by `createOrderedOperator` and `createCachedOperator`, which hand the node
+	* directly to their own factory function (because those factories construct the result
+	* sequence themselves rather than delegating to `createEnumerable`).
+	*
+	* @param sequence - The current sequence (`this` inside an `impl` function).
+	* @param name - Operator name, used as the query node label.
+	* @param userArgs - Arguments passed by the caller, captured in the query node.
+	* @param category - Operator category for the query node.
+	*/
+	static buildQueryNode(sequence, name, userArgs, category) {
+		return new QueryNode(name, userArgs, RegistrationUtility.asSequenceFactory(sequence)[tyneqQueryNode], category);
+	}
+	/**
+	* Narrows a `TyneqEnumerableBase` to its `SequenceFactory` view.
+	*
+	* @remarks
+	* The double-cast (`as unknown as SequenceFactory`) is required because
+	* `createEnumerable` and `createCachedEnumerable` are `protected` on the
+	* class hierarchy. `SequenceFactory` is a structural interface that describes
+	* the same shape, allowing registration-time closures to call factory methods
+	* without changing their access modifier. This is a known architectural trade-off
+	* documented in `tasks/lessons.md` under "Architecture Decisions".
+	*/
+	static asSequenceFactory(sequence) {
+		return sequence;
+	}
+};
+//#endregion
+//#region src/plugin/decorators/operator.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
+*/
+function operator(name, category, validate) {
+	return function(target, _context) {
+		if (!reflect(target.prototype).hasMethod("handleNext")) throw new PluginError(`@operator("${name}"): class "${target.name}" must define a protected handleNext(): IteratorResult<T> method. Ensure the class extends TyneqEnumerator<TInput, TOutput>.`, "operator", target.name);
+		OperatorRegistry.register({
+			metadata: OperatorMetadata.forCategory(category, name, TyneqEnumerableBase),
+			impl: function(...userArgs) {
+				validate?.(...userArgs);
+				const base = this;
+				return RegistrationUtility.buildEnumerable(this, name, userArgs, category, { getEnumerator() {
+					return new target(base.getEnumerator(), ...userArgs);
+				} });
+			}
+		});
+		return target;
+	};
+}
+//#endregion
+//#region src/plugin/decorators/orderedOperator.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
+*/
+function orderedOperator(name, category, validate) {
+	return function(target, _context) {
+		if (!reflect(target.prototype).hasMethod("handleNext")) throw new PluginError(`@orderedOperator("${name}"): class "${target.name}" must define a protected handleNext(): IteratorResult<T> method. Ensure the class extends TyneqOrderedEnumerator<T>.`, "orderedOperator", target.name);
+		OperatorRegistry.register({
+			metadata: OperatorMetadata.forCategory(category, name, TyneqOrderedEnumerable),
+			impl: function(...userArgs) {
+				validate?.(...userArgs);
+				const base = this;
+				return RegistrationUtility.buildEnumerable(this, name, userArgs, category, { getEnumerator: () => new target(base, ...userArgs) });
+			}
+		});
+		return target;
+	};
+}
+//#endregion
+//#region src/plugin/decorators/cachedOperator.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
+*/
+function cachedOperator(name, category, validate) {
+	return function(target, _context) {
+		if (!reflect(target.prototype).hasMethod("handleNext")) throw new PluginError(`@cachedOperator("${name}"): class "${target.name}" must define a protected handleNext(): IteratorResult<T> method. Ensure the class extends TyneqCachedEnumerator<T>.`, "cachedOperator", target.name);
+		OperatorRegistry.register({
+			metadata: OperatorMetadata.forCategory(category, name, TyneqCachedEnumerable),
+			impl: function(...userArgs) {
+				validate?.(...userArgs);
+				const base = this;
+				return RegistrationUtility.buildEnumerable(this, name, userArgs, category, { getEnumerator: () => new target(base, ...userArgs) });
+			}
+		});
+		return target;
+	};
+}
+//#endregion
+//#region src/plugin/decorators/terminal.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
+*/
+function terminal(name, validate) {
+	return function(target, _context) {
+		if (!reflect(target.prototype).hasMethod("process")) throw new PluginError(`@terminal("${name}"): class "${target.name}" must define a public process(): TResult method. Ensure the class extends TyneqTerminalOperator<TSource, TResult>.`, "terminal", target.name);
+		OperatorRegistry.register({
+			metadata: OperatorMetadata.terminal(name, TyneqEnumerableBase),
+			impl: function(...userArgs) {
+				validate?.(...userArgs);
+				return new target(this, ...userArgs).process();
+			}
+		});
+		return target;
+	};
+}
+//#endregion
+//#region src/plugin/decorators/orderedTerminal.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
+*/
+function orderedTerminal(name, validate) {
+	return function(target, _context) {
+		OperatorRegistry.register({
+			metadata: OperatorMetadata.terminal(name, TyneqOrderedEnumerable),
+			impl: function(...userArgs) {
+				validate?.(...userArgs);
+				return new target(this, ...userArgs).process();
+			}
+		});
+		return target;
+	};
+}
+//#endregion
+//#region src/plugin/decorators/cachedTerminal.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
+*/
+function cachedTerminal(name, validate) {
+	return function(target, _context) {
+		OperatorRegistry.register({
+			metadata: OperatorMetadata.terminal(name, TyneqCachedEnumerable),
+			impl: function(...userArgs) {
+				validate?.(...userArgs);
+				return new target(this, ...userArgs).process();
+			}
+		});
+		return target;
+	};
+}
+//#endregion
+//#region src/plugin/registration/createOperator.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
+*/
+function createOperator(config) {
+	OperatorRegistry.register({
+		metadata: OperatorMetadata.forCategory(config.category, config.name, TyneqEnumerableBase, config.source),
+		impl: function(...args) {
+			config.validate?.(...args);
+			return RegistrationUtility.buildEnumerable(this, config.name, args, config.category, config.factory(this, ...args));
+		}
+	});
+}
+//#endregion
+//#region src/plugin/registration/createGeneratorOperator.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
+*/
+function createGeneratorOperator(config) {
+	const category = config.category ?? "streaming";
+	OperatorRegistry.register({
+		metadata: OperatorMetadata.forCategory(category, config.name, TyneqEnumerableBase, config.source),
+		impl: function(...args) {
+			config.validate?.(...args);
+			const source = this;
+			return RegistrationUtility.buildEnumerable(this, config.name, args, category, { getEnumerator: () => config.generator(source, ...args) });
+		}
+	});
+}
+//#endregion
+//#region src/plugin/registration/createOrderedOperator.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
+*/
+function createOrderedOperator(config) {
+	OperatorRegistry.register({
+		metadata: OperatorMetadata.forCategory(config.category, config.name, TyneqOrderedEnumerable, config.source),
+		impl: function(...userArgs) {
+			config.validate?.(...userArgs);
+			const source = this;
+			const node = RegistrationUtility.buildQueryNode(this, config.name, userArgs, config.category);
+			return config.factory(source, node, ...userArgs);
+		}
+	});
+}
+//#endregion
+//#region src/plugin/registration/createCachedOperator.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
+*/
+function createCachedOperator(config) {
+	OperatorRegistry.register({
+		metadata: OperatorMetadata.forCategory(config.category, config.name, TyneqCachedEnumerable, config.source),
+		impl: function(...userArgs) {
+			config.validate?.(...userArgs);
+			const source = this;
+			const node = RegistrationUtility.buildQueryNode(this, config.name, userArgs, config.category);
+			return config.factory(source, node, ...userArgs);
+		}
+	});
+}
+//#endregion
+//#region src/plugin/registration/createTerminalOperator.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
+*/
+function createTerminalOperator(config) {
+	OperatorRegistry.register({
+		metadata: OperatorMetadata.terminal(config.name, TyneqEnumerableBase, config.source),
+		impl: function(...args) {
+			config.validate?.(...args);
+			return config.execute(this, ...args);
+		}
+	});
+}
+//#endregion
+//#region src/plugin/registration/createOrderedTerminalOperator.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
+*/
+function createOrderedTerminalOperator(config) {
+	OperatorRegistry.register({
+		metadata: OperatorMetadata.terminal(config.name, TyneqOrderedEnumerable, config.source),
+		impl: function(...args) {
+			config.validate?.(...args);
+			return config.execute(this, ...args);
+		}
+	});
+}
+//#endregion
+//#region src/plugin/registration/createCachedTerminalOperator.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
+*/
+function createCachedTerminalOperator(config) {
+	OperatorRegistry.register({
+		metadata: OperatorMetadata.terminal(config.name, TyneqCachedEnumerable, config.source),
+		impl: function(...args) {
+			config.validate?.(...args);
+			return config.execute(this, ...args);
+		}
+	});
+}
+//#endregion
+//#region src/core/enumerators/TyneqOrderedEnumerator.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
+*/
+var TyneqOrderedEnumerator = class extends TyneqBaseEnumerator {
+	constructor(orderedSource) {
+		super();
+		this.orderedSource = orderedSource;
+	}
+	disposeSource() {}
+};
+//#endregion
+//#region src/core/enumerators/TyneqCachedEnumerator.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
+*/
+var TyneqCachedEnumerator = class extends TyneqBaseEnumerator {
+	constructor(cachedSource) {
+		super();
+		this.cachedSource = cachedSource;
+	}
+	disposeSource() {}
+};
+//#endregion
+//#region src/core/terminal/TyneqOrderedTerminalOperator.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
+*/
+var TyneqOrderedTerminalOperator = class {
+	source;
+	constructor(source) {
+		ArgumentUtility.checkNotOptional({ source });
+		this.source = source;
+	}
+};
+//#endregion
+//#region src/core/terminal/TyneqCachedTerminalOperator.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
+*/
+var TyneqCachedTerminalOperator = class {
+	source;
+	constructor(source) {
+		ArgumentUtility.checkNotOptional({ source });
+		this.source = source;
+	}
+};
+//#endregion
+export { PluginError as A, SequenceContainsNoElementsError as C, OperatorRegistry as D, TyneqTerminalOperator as E, TyneqBaseEnumerator as F, isSourceNode as M, tyneqQueryNode as N, RegistryError as O, TyneqComparer as P, TyneqEnumerator as S, InvalidOperationError as T, operator as _, createCachedTerminalOperator as a, TyneqCachedEnumerable as b, createCachedOperator as c, createOperator as d, cachedTerminal as f, orderedOperator as g, cachedOperator as h, TyneqOrderedEnumerator as i, QueryNode as j, OperatorMetadata as k, createOrderedOperator as l, terminal as m, TyneqOrderedTerminalOperator as n, createOrderedTerminalOperator as o, orderedTerminal as p, TyneqCachedEnumerator as r, createTerminalOperator as s, TyneqCachedTerminalOperator as t, createGeneratorOperator as u, source as v, EnumeratorUtility as w, TyneqOrderedEnumerable as x, TyneqEnumerable as y };
+
+//# sourceMappingURL=TyneqCachedTerminalOperator.js.map