tyneq 1.0.0

package/dist/index.cjs

@@ -0,0 +1,863 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_TyneqCachedTerminalOperator = require("./TyneqCachedTerminalOperator.cjs");
+const require_Lazy = require("./Lazy.cjs");
+const require_ValidationBuilder = require("./ValidationBuilder.cjs");
+//#region src/core/generators/range.ts
+var RangeEnumerator = class extends require_TyneqCachedTerminalOperator.TyneqBaseEnumerator {
+	current;
+	end;
+	constructor(start, end) {
+		super();
+		this.current = start;
+		this.end = end;
+	}
+	handleNext() {
+		if (this.current > this.end) return this.done();
+		return this.yield(this.current++);
+	}
+};
+//#endregion
+//#region src/core/generators/random.ts
+var RandomEnumerator = class extends require_TyneqCachedTerminalOperator.TyneqBaseEnumerator {
+	count;
+	randomizer;
+	yieldedCount = 0;
+	constructor(count, randomizer) {
+		super();
+		this.count = count;
+		this.randomizer = randomizer;
+	}
+	handleNext() {
+		if (this.yieldedCount >= this.count) return this.done();
+		this.yieldedCount++;
+		return this.yield(this.randomizer());
+	}
+};
+//#endregion
+//#region src/core/EnumerableAdapter.ts
+/**
+* Wraps a native `Iterable<T>` as a Tyneq {@link Enumerable}.
+*
+* @remarks
+* Used by `Tyneq.from()` to adapt arrays, sets, generators, and any other iterable.
+* Each call to `getEnumerator()` delegates to the underlying `[Symbol.iterator]()`.
+*
+* @internal
+*/
+var EnumerableAdapter = class {
+	iterable;
+	constructor(iterable) {
+		require_Lazy.ArgumentUtility.checkNotOptional({ iterable });
+		require_Lazy.ArgumentUtility.checkIterable({ iterable });
+		this.iterable = iterable;
+	}
+	[Symbol.iterator]() {
+		return this.getEnumerator();
+	}
+	getEnumerator() {
+		return this.iterable[Symbol.iterator]();
+	}
+};
+//#endregion
+//#region src/core/generators/repeat.ts
+/**
+* Yields a single value a fixed number of times.
+*
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var RepeatEnumerator = class extends require_TyneqCachedTerminalOperator.TyneqBaseEnumerator {
+	value;
+	count;
+	yieldedCount = 0;
+	constructor(value, count) {
+		super();
+		this.count = count;
+		this.value = value;
+	}
+	handleNext() {
+		if (this.yieldedCount >= this.count) return this.done();
+		this.yieldedCount++;
+		return this.yieldedCount === this.count ? this.doneWithYield(this.value) : this.yield(this.value);
+	}
+};
+//#endregion
+//#region src/core/generators/generate.ts
+/**
+* Yields a sequence produced by repeatedly applying a selector to the previous element.
+*
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var GenerateEnumerator = class extends require_TyneqCachedTerminalOperator.TyneqBaseEnumerator {
+	nextSelector;
+	count;
+	value;
+	yieldedCount = 0;
+	index = 0;
+	constructor(seed, next, count) {
+		super();
+		this.value = seed;
+		this.nextSelector = next;
+		this.count = count ?? Infinity;
+	}
+	handleNext() {
+		if (this.yieldedCount >= this.count) return this.done();
+		const result = this.nextSelector(this.value, this.index++);
+		this.value = result;
+		this.yieldedCount++;
+		return this.yield(result);
+	}
+};
+//#endregion
+//#region src/core/generators/sourceConcat.ts
+/**
+* Yields all elements from each source iterable in order.
+*
+* @group Operators
+* @category Streaming
+* @internal
+*/
+var SourceConcatEnumerator = class extends require_TyneqCachedTerminalOperator.TyneqBaseEnumerator {
+	sources;
+	currentSourceIndex = 0;
+	currentIterator = null;
+	constructor(...sources) {
+		super();
+		this.sources = sources;
+	}
+	disposeAdditional() {
+		try {
+			this.currentIterator?.return?.();
+		} catch {}
+		this.currentIterator = null;
+	}
+	handleNext() {
+		while (this.currentSourceIndex < this.sources.length) {
+			if (this.currentIterator === null) this.currentIterator = this.sources[this.currentSourceIndex][Symbol.iterator]();
+			const result = this.currentIterator.next();
+			if (!result.done) return this.yield(result.value);
+			this.currentIterator = null;
+			this.currentSourceIndex++;
+		}
+		return this.done();
+	}
+};
+//#endregion
+//#region src/core/tyneq.ts
+/**
+* Entry point for creating Tyneq sequences.
+*
+* @example
+* ```ts
+* import { Tyneq } from "tyneq";
+*
+* const sum = Tyneq.from([1, 2, 3, 4, 5])
+*   .where((x) => x % 2 === 0)
+*   .sum((x) => x); // -> 6
+* ```
+*
+* @group Classes
+*/
+var Tyneq = class Tyneq {
+	/**
+	* Creates a lazy sequence from any `Iterable<T>` (arrays, sets, generators, etc.).
+	*
+	* @throws {ArgumentNullError} When `source` is null or undefined.
+	* @throws {ArgumentTypeError} When `source` is not iterable.
+	*/
+	@require_TyneqCachedTerminalOperator.source({ source: "internal" }) static from(source) {
+		require_Lazy.ArgumentUtility.checkNotOptional({ source });
+		require_Lazy.ArgumentUtility.checkIterable({ source });
+		const sourceKind = Tyneq.resolveSourceKind(source);
+		return new require_TyneqCachedTerminalOperator.TyneqEnumerable(new EnumerableAdapter(source), new require_TyneqCachedTerminalOperator.QueryNode("from", [source], null, "source", sourceKind));
+	}
+	static resolveSourceKind(source) {
+		if (Array.isArray(source)) return "array";
+		if (source instanceof Set) return "set";
+		if (source instanceof Map) return "map";
+		if (typeof source === "string") return "string";
+		return "other";
+	}
+	/**
+	* Creates a sequence of `count` elements produced by calling `randomizer` once per element.
+	*
+	* @remarks
+	* Returns an empty sequence when `count === 0`.
+	*
+	* @throws {ArgumentOutOfRangeError} When `count` is negative.
+	* @throws {ArgumentNullError} When `randomizer` is null or undefined.
+	*/
+	@require_TyneqCachedTerminalOperator.source({ source: "internal" }) static random(count, randomizer) {
+		require_Lazy.ArgumentUtility.checkNonNegative({ count });
+		require_Lazy.ArgumentUtility.checkInteger({ count });
+		require_Lazy.ArgumentUtility.checkNotOptional({ randomizer });
+		return new require_TyneqCachedTerminalOperator.TyneqEnumerable({ getEnumerator: () => new RandomEnumerator(count, randomizer) }, new require_TyneqCachedTerminalOperator.QueryNode("random", [count, randomizer], null, "source"));
+	}
+	/**
+	* Returns `true` if `source` is `null`, `undefined`, or an iterable whose first element is `null` or `undefined`.
+	*/
+	static isNullOrEmpty(source) {
+		if (source === null || source === void 0) return true;
+		return this.from(source).isNullOrEmpty();
+	}
+	/**
+	* Creates a sequence of `count` integers starting from `start`.
+	*
+	* @remarks
+	* Returns an empty sequence when `count === 0`.
+	*
+	* @example
+	* ```ts
+	* Tyneq.range(1, 5).toArray(); // -> [1, 2, 3, 4, 5]
+	* ```
+	*
+	* @throws {ArgumentOutOfRangeError} When `count` is negative.
+	* @throws {ArgumentError} When `count` is not an integer.
+	*/
+	@require_TyneqCachedTerminalOperator.source({ source: "internal" }) static range(start, count) {
+		require_Lazy.ArgumentUtility.checkNonNegative({ count });
+		require_Lazy.ArgumentUtility.checkInteger({ count });
+		const end = start + count - 1;
+		return new require_TyneqCachedTerminalOperator.TyneqEnumerable({ getEnumerator: () => new RangeEnumerator(start, end) }, new require_TyneqCachedTerminalOperator.QueryNode("range", [start, count], null, "source"));
+	}
+	/** Returns an empty sequence with zero elements. */
+	@require_TyneqCachedTerminalOperator.source({ source: "internal" }) static empty() {
+		return new require_TyneqCachedTerminalOperator.TyneqEnumerable(new EnumerableAdapter([]), new require_TyneqCachedTerminalOperator.QueryNode("empty", [], null, "source"));
+	}
+	/**
+	* Creates a sequence that yields `value` exactly `count` times.
+	*
+	* @example
+	* ```ts
+	* Tyneq.repeat("x", 3).toArray(); // -> ["x", "x", "x"]
+	* ```
+	*
+	* @throws {ArgumentOutOfRangeError} When `count` is negative.
+	* @throws {ArgumentError} When `count` is not an integer.
+	*/
+	@require_TyneqCachedTerminalOperator.source({ source: "internal" }) static repeat(value, count) {
+		require_Lazy.ArgumentUtility.checkNonNegative({ count });
+		require_Lazy.ArgumentUtility.checkInteger({ count });
+		return new require_TyneqCachedTerminalOperator.TyneqEnumerable({ getEnumerator: () => new RepeatEnumerator(value, count) }, new require_TyneqCachedTerminalOperator.QueryNode("repeat", [value, count], null, "source"));
+	}
+	/**
+	* Creates a sequence by repeatedly applying `next` to produce each element from the previous one.
+	*
+	* @remarks
+	* The selector receives `(currentValue, index)`. Each call's return value becomes the input
+	* for the next call. Omit `count` for an infinite sequence; pair with `take` to bound it.
+	*
+	* @example
+	* ```ts
+	* Tyneq.generate(1, (x) => x * 2, 4).toArray(); // -> [2, 4, 8, 16]
+	* ```
+	*
+	* @throws {ArgumentNullError} When `next` is null or undefined.
+	* @throws {ArgumentOutOfRangeError} When `count` is negative.
+	* @throws {ArgumentError} When `count` is not an integer.
+	*/
+	@require_TyneqCachedTerminalOperator.source({ source: "internal" }) static generate(seed, next, count) {
+		require_Lazy.ArgumentUtility.checkNotOptional({ next });
+		if (count !== void 0) {
+			require_Lazy.ArgumentUtility.checkNonNegative({ count });
+			require_Lazy.ArgumentUtility.checkInteger({ count });
+		}
+		return new require_TyneqCachedTerminalOperator.TyneqEnumerable({ getEnumerator: () => new GenerateEnumerator(seed, next, count) }, new require_TyneqCachedTerminalOperator.QueryNode("generate", [
+			seed,
+			next,
+			count
+		], null, "source"));
+	}
+	/**
+	* Creates a sequence that yields all elements from each source in order.
+	*
+	* @remarks
+	* Returns an empty sequence when called with no arguments.
+	*
+	* @example
+	* ```ts
+	* Tyneq.concat([1, 2], [3, 4], [5]).toArray(); // -> [1, 2, 3, 4, 5]
+	* ```
+	* 
+	* @throws {ArgumentNullError} When any `source` is null or undefined.
+	* @throws {ArgumentTypeError} When any `source` is not iterable.
+	*/
+	@require_TyneqCachedTerminalOperator.source({ source: "internal" }) static concat(...sources) {
+		for (const source of sources) {
+			require_Lazy.ArgumentUtility.checkNotOptional({ source });
+			require_Lazy.ArgumentUtility.checkIterable({ source });
+		}
+		return new require_TyneqCachedTerminalOperator.TyneqEnumerable({ getEnumerator: () => new SourceConcatEnumerator(...sources) }, new require_TyneqCachedTerminalOperator.QueryNode("concat", sources, null, "source"));
+	}
+	/**
+	* Pairs each element with its zero-based index.
+	*
+	* @remarks
+	* Each iteration produces independent index counters - safe to re-enumerate.
+	*
+	* @example
+	* ```ts
+	* Tyneq.enumerate(["a", "b", "c"]).toArray();
+	* // -> [[0, "a"], [1, "b"], [2, "c"]]
+	* ```
+	*
+	* @throws {ArgumentNullError} When `source` is null or undefined.
+	* @throws {ArgumentTypeError} When `source` is not iterable.
+	*/
+	static enumerate(source) {
+		require_Lazy.ArgumentUtility.checkNotOptional({ source });
+		require_Lazy.ArgumentUtility.checkIterable({ source });
+		return this.from({ *[Symbol.iterator]() {
+			let index = 0;
+			for (const item of source) yield [index++, item];
+		} });
+	}
+};
+//#endregion
+//#region src/core/errors/KeyNotFoundError.ts
+/**
+* Thrown when a lookup is performed with a key that does not exist in the collection.
+*
+* @example
+* ```ts
+* try { seq.toMap((x) => x.id).get(999); }
+* catch (e) { if (e instanceof KeyNotFoundError) { ... } }
+* ```
+*
+* @see {@link TyneqError}
+* @group Errors
+*/
+var KeyNotFoundError = class extends require_Lazy.TyneqError {
+	constructor(message = "The given key was not present in the dictionary.", inner) {
+		super(message, { inner });
+	}
+};
+//#endregion
+//#region src/core/errors/NotSupportedError.ts
+/**
+* Thrown when a requested operation is not supported.
+*
+* @example
+* ```ts
+* try { iterator.throw?.(new Error()); }
+* catch (e) { if (e instanceof NotSupportedError) { ... } }
+* ```
+*
+* @see {@link TyneqError}
+* @group Errors
+*/
+var NotSupportedError = class extends require_Lazy.TyneqError {
+	constructor(message = "The requested operation is not supported.", inner) {
+		super(message, { inner });
+	}
+};
+//#endregion
+//#region src/core/errors/CompilerError.ts
+/**
+* Thrown when the query plan compiler encounters a structural or semantic error
+* while compiling a query plan into an executable sequence.
+*
+* @example
+* ```ts
+* try { compiler.compile(plan); }
+* catch (e) {
+*   if (e instanceof CompilerError) {
+*     console.log(e.operatorName, e.phase, e.message);
+*   }
+* }
+* ```
+*
+* @see {@link TyneqError}
+* @group Errors
+*/
+var CompilerError = class extends require_Lazy.TyneqError {
+	/** The name of the operator being compiled when the error occurred, if known. */
+	operatorName;
+	/**
+	* The compilation phase in which the error occurred.
+	* - `"transform"` - during query plan transformation (pre-compile)
+	* - `"source"` - while compiling a source node
+	* - `"operator"` - while applying an operator node
+	*/
+	phase;
+	constructor(message, phase, operatorName, inner) {
+		super(message, { inner });
+		this.phase = phase;
+		this.operatorName = operatorName;
+	}
+};
+//#endregion
+//#region src/queryplan/QueryPlanPrinter.ts
+/**
+* Converts a query plan tree into a human-readable multi-line string.
+*
+* Implements `QueryPlanVisitor<string>`. The output lists operators from source to
+* terminal, one per line, with indentation showing the pipeline depth.
+*
+* @example
+* ```ts
+* import { QueryPlanPrinter } from "tyneq/queryplan";
+*
+* const seq = Tyneq.range(1, 10).where(x => x % 2 === 0).select(x => x * x);
+* console.log(QueryPlanPrinter.print(seq[tyneqQueryNode]!));
+* // range(1, 10)
+* //   -> where(<fn>)
+* //   -> select(<fn>)
+* ```
+*
+* @group QueryPlan
+*/
+var QueryPlanPrinter = class QueryPlanPrinter {
+	indent;
+	arrow;
+	maxInlineArrayItems;
+	constructor(options = {}) {
+		this.indent = options.indent ?? "  ";
+		this.arrow = options.arrow ?? "->";
+		this.maxInlineArrayItems = options.maxInlineArrayItems ?? 3;
+	}
+	/** Renders the full query plan rooted at `node` as a multi-line string. */
+	visit(node) {
+		return this.buildPlan(node);
+	}
+	/** Convenience static: creates a printer with `options` and calls `visit(node)`. */
+	static print(node, options) {
+		return new QueryPlanPrinter(options).visit(node);
+	}
+	/**
+	* Formats a single operator argument for display.
+	* Override to customise how arguments appear in printed plans.
+	*/
+	formatArg(arg) {
+		if (typeof arg === "function") return "<fn>";
+		if (arg === null) return "null";
+		if (arg === void 0) return "undefined";
+		if (typeof arg === "string") return `"${arg}"`;
+		if (Array.isArray(arg)) {
+			if (arg.length === 0) return "[]";
+			if (arg.length <= this.maxInlineArrayItems) return `[${arg.map((a) => this.formatArg(a)).join(", ")}]`;
+			return `[...${arg.length} items]`;
+		}
+		if (typeof arg === "object") return "{...}";
+		return String(arg);
+	}
+	/**
+	* Formats one line of the plan output.
+	* Override to customise indentation or arrow style beyond what `QueryPlanPrinterOptions` allows.
+	*/
+	formatLine(name, argStr, isRoot) {
+		return `${isRoot ? "" : `${this.indent}${this.arrow} `}${name}(${argStr})`;
+	}
+	buildPlan(node) {
+		return this.collectNodes(node).map((n, index) => {
+			const argStr = n.args.map((a) => this.formatArg(a)).join(", ");
+			return this.formatLine(n.operatorName, argStr, index === 0);
+		}).join("\n");
+	}
+	collectNodes(node) {
+		const nodes = [];
+		let current = node;
+		while (current !== null) {
+			nodes.push(current);
+			current = current.source;
+		}
+		nodes.reverse();
+		return nodes;
+	}
+};
+//#endregion
+//#region src/queryplan/QueryPlanWalker.ts
+/**
+* Concrete base class for side-effect query plan visitors.
+*
+* @remarks
+* Traverses the node chain calling {@link QueryPlanWalker.visitNode} once per node.
+* The traversal direction defaults to `"source-to-terminal"` (bottom-up: `from` before
+* `where` before `select`) and can be changed to `"terminal-to-source"` (top-down) via
+* the options object.
+*
+* ### Usage patterns
+*
+* **Direct instantiation with a callback** - no subclass needed for simple traversals:
+* ```ts
+* const names: string[] = [];
+* new QueryPlanWalker({ callback: node => names.push(node.operatorName) }).visit(plan);
+* ```
+*
+* **Subclass** - for stateful walkers that accumulate results across nodes:
+* ```ts
+* class NodeCounter extends QueryPlanWalker {
+*     public count = 0;
+*     protected override visitNode(_node: QueryPlanNode): void { this.count++; }
+* }
+*
+* const counter = new NodeCounter();
+* counter.visit(seq[tyneqQueryNode]!);
+* console.log(counter.count); // number of operators in the pipeline
+* ```
+*
+* **Top-down traversal:**
+* ```ts
+* new QueryPlanWalker({
+*     callback: node => console.log(node.operatorName),
+*     direction: "terminal-to-source",
+* }).visit(plan);
+* ```
+*
+* **Subclass with direction override** - pass options to `super`:
+* ```ts
+* class ReverseCollector extends QueryPlanWalker {
+*     public readonly names: string[] = [];
+*     public constructor() { super({ direction: "terminal-to-source" }); }
+*     protected override visitNode(node: QueryPlanNode): void {
+*         this.names.push(node.operatorName);
+*     }
+* }
+* ```
+*
+* @group QueryPlan
+*/
+var QueryPlanWalker = class {
+	callback;
+	direction;
+	/**
+	* @param options - Optional configuration for the walker.
+	*/
+	constructor(options) {
+		this.callback = options?.callback;
+		this.direction = options?.direction ?? "source-to-terminal";
+	}
+	/**
+	* Walks the full chain rooted at `node`, calling {@link visitNode} for each node
+	* in the configured direction.
+	*/
+	visit(node) {
+		if (this.direction === "source-to-terminal") {
+			if (node.source !== null) this.visit(node.source);
+			this.visitNode(node);
+		} else {
+			this.visitNode(node);
+			if (node.source !== null) this.visit(node.source);
+		}
+	}
+	/**
+	* Called once per node during traversal.
+	*
+	* @remarks
+	* The default implementation fires the callback passed via options (if any).
+	* Override this method in a subclass to provide custom behaviour. Subclasses that
+	* override this method decide whether to call `super.visitNode(node)` to also fire
+	* the options callback.
+	*
+	* @param node - The current node being visited.
+	*/
+	visitNode(node) {
+		this.callback?.(node);
+	}
+};
+//#endregion
+//#region src/queryplan/QueryPlanTransformer.ts
+/**
+* Base class for immutable query plan rewriting.
+*
+* @remarks
+* Recursively rebuilds the node chain, calling {@link QueryPlanTransformer.transformNode}
+* once per node. The default implementation is an **identity transform** - every node is
+* reconstructed with the same data, producing a structurally equivalent copy.
+*
+* Subclasses override `transformNode` to intercept specific operators. Three rewrite
+* patterns are possible:
+*
+* - **Rewrite a node** - return a new `QueryNode` with different `operatorName` or `args`
+* - **Remove a node** - return `source` directly, skipping this node
+* - **Collapse two nodes into one** - use `source` as the new node's `source` (fusing
+*   the current node with its already-transformed predecessor)
+*
+* @example
+* ```ts
+* // Rename all 'where' nodes to 'filter' in the plan view
+* class RenameWhere extends QueryPlanTransformer {
+*     protected override transformNode(node: QueryPlanNode, source: QueryPlanNode | null): QueryPlanNode {
+*         if (node.operatorName === "where") {
+*             return new QueryNode("filter", node.args, source, node.category);
+*         }
+*         return super.transformNode(node, source);
+*     }
+* }
+* ```
+*
+* @group QueryPlan
+*/
+var QueryPlanTransformer = class {
+	/**
+	* Transforms the full chain rooted at `node` and returns the new root node.
+	*
+	* @remarks
+	* Processes source-first (bottom-up): the source chain is fully transformed before
+	* `transformNode` is called for the current node. This means `source` passed to
+	* `transformNode` is always already the transformed predecessor.
+	*/
+	visit(node) {
+		const transformedSource = node.source !== null ? this.visit(node.source) : null;
+		return this.transformNode(node, transformedSource);
+	}
+	/**
+	* Transforms a single node. Override to intercept specific operators.
+	*
+	* @remarks
+	* The default implementation reconstructs the node with identical data (identity transform).
+	* `source` is the already-transformed predecessor - use it as the `source` of any returned
+	* node to preserve chain continuity.
+	*
+	* @param node - The original node (unmodified).
+	* @param source - The transformed predecessor, or `null` for source nodes.
+	*/
+	transformNode(node, source) {
+		return new require_TyneqCachedTerminalOperator.QueryNode(node.operatorName, node.args, source, node.category, node.sourceKind);
+	}
+};
+//#endregion
+//#region src/queryplan/QueryPlanOptimizer.ts
+/**
+* A built-in {@link QueryPlanTransformer} that fuses redundant consecutive operators.
+*
+* @remarks
+* **This optimizer rewrites the query plan tree only - it does not affect execution of the
+* original sequence.** The returned `QueryPlanNode` reflects what an optimized pipeline would
+* look like; the live sequence that produced the original plan is unchanged.
+*
+* **Fusion is only semantics-preserving for pure, side-effect-free functions.**
+* If a predicate or projection has side effects (e.g. logging, mutation), fusing two nodes into
+* one changes when and how many times those effects fire. For example, in a fused `where`, the
+* second predicate is never called for items that fail the first - any mutation inside the second
+* predicate is skipped for those items. Do not use this optimizer on pipelines with impure
+* predicates or projections.
+*
+* ### Fusions applied
+*
+* | Pattern | Result |
+* |---------|--------|
+* | `where(a) -> where(b)` | `where(x => a(x) && b(x))` |
+* | `select(a) -> select(b)` | `select(x => b(a(x)))` |
+*
+* Additional fusions can be added by subclassing and overriding
+* {@link QueryPlanTransformer.transformNode}.
+*
+* @example
+* ```ts
+* import { Tyneq, tyneqQueryNode, QueryPlanOptimizer, QueryPlanPrinter } from "tyneq";
+*
+* const seq = Tyneq.from([1, 2, 3])
+*     .where(x => x > 1)
+*     .where(x => x < 3)
+*     .select(x => x * 2)
+*     .select(x => x + 1);
+*
+* const original = seq[tyneqQueryNode]!;
+* const optimized = new QueryPlanOptimizer().visit(original);
+*
+* console.log(QueryPlanPrinter.print(original));
+* // from([...])
+* //   -> where(<fn>)
+* //   -> where(<fn>)
+* //   -> select(<fn>)
+* //   -> select(<fn>)
+*
+* console.log(QueryPlanPrinter.print(optimized));
+* // from([...])
+* //   -> where(<fn>)
+* //   -> select(<fn>)
+* ```
+*
+* @group QueryPlan
+*/
+var QueryPlanOptimizer = class extends QueryPlanTransformer {
+	transformNode(node, source) {
+		if (node.operatorName === "where" && source?.operatorName === "where") return this.fuseWhere(node, source);
+		if (node.operatorName === "select" && source?.operatorName === "select") return this.fuseSelect(node, source);
+		return super.transformNode(node, source);
+	}
+	/**
+	* @remarks Fusion is only semantics-preserving for pure, side-effect-free predicates.
+	*/
+	fuseWhere(node, source) {
+		const predA = source.args[0];
+		const predB = node.args[0];
+		const fused = (x) => predA(x) && predB(x);
+		return new require_TyneqCachedTerminalOperator.QueryNode("where", [fused], source.source, "streaming");
+	}
+	/**
+	* @remarks Fusion is only semantics-preserving for pure, side-effect-free projections.
+	*/
+	fuseSelect(node, source) {
+		const projA = source.args[0];
+		const projB = node.args[0];
+		const fused = (x) => projB(projA(x));
+		return new require_TyneqCachedTerminalOperator.QueryNode("select", [fused], source.source, "streaming");
+	}
+};
+//#endregion
+//#region src/queryplan/compiler/QueryPlanCompiler.ts
+/**
+* Compiles a query plan tree into an executable `TyneqSequence`.
+*
+* @remarks
+* Walks the `QueryPlanNode` chain from source to terminal, reconstructing each operator by
+* looking it up in the `OperatorRegistry` and applying it to the compiled source.
+* An optional list of `QueryPlanTransformer` instances runs before compilation, allowing
+* optimization or rewriting of the plan.
+*
+* @example
+* ```ts
+* import { Tyneq, tyneqQueryNode, QueryPlanCompiler, QueryPlanOptimizer } from "tyneq";
+*
+* const seq = Tyneq.from([1, 2, 3]).where(x => x > 1).select(x => x * 2);
+* const compiler = new QueryPlanCompiler([new QueryPlanOptimizer()]);
+* const result = compiler.compile(seq[tyneqQueryNode]!);
+* result.toArray(); // -> [4, 6]
+* ```
+*
+* @group QueryPlan
+*/
+var QueryPlanCompiler = class {
+	transformers;
+	constructor(transformers = []) {
+		this.transformers = [...transformers];
+	}
+	/**
+	* Compile a query plan into an executable sequence.
+	*
+	* Runs all registered transformers before compiling. Use {@link compileRaw} to skip
+	* the transform phase when the plan is already optimised.
+	*
+	* @param node - The root node of the query plan to compile.
+	* @param options - Optional compile-time overrides. Use `options.source` to supply a
+	* different data source than the one stored in the plan.
+	* @returns The compiled sequence typed as `TyneqSequence<T>` by default.
+	* If you know the plan ends in an operator that returns a subtype (e.g. `orderBy` ->
+	* `TyneqOrderedSequence`, `memoize` -> `TyneqCachedSequence`), supply `TResult` explicitly:
+	* `compiler.compile<number, TyneqOrderedSequence<number>>(node)`.
+	*/
+	compile(node, options) {
+		if (node === null || node === void 0) throw new CompilerError("compile() received a null or undefined query plan node. Ensure the sequence was created via Tyneq.from(), Tyneq.range(), or another source operator before compiling.", "source");
+		const transformedNode = this.transform(node);
+		return this.compileNode(transformedNode, options);
+	}
+	/**
+	* Compile a pre-optimised query plan into an executable sequence, skipping the
+	* transform phase.
+	*
+	* @remarks
+	* Use this overload when you have already run transformers externally (or deliberately
+	* want to bypass them) and want to compile the node as-is. Equivalent to constructing
+	* a `QueryPlanCompiler` with no transformers and calling `compile()`.
+	*
+	* @param node - The root node of the already-transformed query plan to compile.
+	* @param options - Optional compile-time overrides. Use `options.source` to supply a
+	* different data source than the one stored in the plan.
+	*/
+	compileRaw(node, options) {
+		if (node === null || node === void 0) throw new CompilerError("compileRaw() received a null or undefined query plan node. Ensure the sequence was created via Tyneq.from(), Tyneq.range(), or another source operator before compiling.", "source");
+		return this.compileNode(node, options);
+	}
+	transform(node) {
+		let transformedNode = node;
+		for (const transformer of this.transformers) try {
+			transformedNode = transformer.visit(transformedNode);
+		} catch (e) {
+			throw new CompilerError(`Transformer "${transformer.constructor.name}" threw during transformation.`, "transform", void 0, e instanceof Error ? e : void 0);
+		}
+		return transformedNode;
+	}
+	compileNode(node, options) {
+		if (node.category === "source") return this.compileSource(node, options);
+		if (node.source === null) throw new CompilerError("Operator node is missing a source node. Every operator node must have a source.", "operator", node.operatorName);
+		return this.applyOperator(this.compileNode(node.source, options), node);
+	}
+	compileSource(node, options) {
+		const entry = require_TyneqCachedTerminalOperator.OperatorRegistry.getSource(node.operatorName);
+		if (!entry) throw new CompilerError(`Unknown source operator "${node.operatorName}". Register it via OperatorRegistry.registerSource() before compiling.`, "source", node.operatorName);
+		const args = options?.source !== void 0 ? [options.source, ...node.args.slice(1)] : [...node.args];
+		return entry.impl.apply(null, args);
+	}
+	applyOperator(source, node) {
+		const entry = this.findOperatorEntry(node.operatorName, source);
+		if (!entry) {
+			const sourceType = source !== null && source !== void 0 ? Object.getPrototypeOf(source)?.constructor?.name ?? typeof source : "null";
+			throw new CompilerError(require_TyneqCachedTerminalOperator.OperatorRegistry.hasOperator(node.operatorName) ? `Operator "${node.operatorName}" is not registered for sequence type ${sourceType}. Ensure the source sequence is of the correct type for this operator.` : `Operator "${node.operatorName}" is not registered. Register it via @operator, createOperator, or createGeneratorOperator before compiling.`, "operator", node.operatorName);
+		}
+		return entry.impl.apply(source, [...node.args]);
+	}
+	findOperatorEntry(operatorName, source) {
+		if (source === null || source === void 0) return;
+		let proto = Object.getPrototypeOf(source);
+		while (proto !== null) {
+			const ctor = proto.constructor;
+			if (ctor !== void 0) {
+				const entry = require_TyneqCachedTerminalOperator.OperatorRegistry.getOperator(operatorName, ctor);
+				if (entry !== void 0) return entry;
+			}
+			proto = Object.getPrototypeOf(proto);
+		}
+	}
+};
+//#endregion
+exports.ArgumentError = require_Lazy.ArgumentError;
+exports.ArgumentNullError = require_Lazy.ArgumentNullError;
+exports.ArgumentOutOfRangeError = require_Lazy.ArgumentOutOfRangeError;
+exports.ArgumentTypeError = require_Lazy.ArgumentTypeError;
+exports.ArgumentUtility = require_Lazy.ArgumentUtility;
+exports.CompilerError = CompilerError;
+exports.InvalidOperationError = require_TyneqCachedTerminalOperator.InvalidOperationError;
+exports.KeyNotFoundError = KeyNotFoundError;
+exports.Lazy = require_Lazy.Lazy;
+exports.NotSupportedError = NotSupportedError;
+exports.OperatorMetadata = require_TyneqCachedTerminalOperator.OperatorMetadata;
+exports.OperatorRegistry = require_TyneqCachedTerminalOperator.OperatorRegistry;
+exports.PluginError = require_TyneqCachedTerminalOperator.PluginError;
+exports.QueryNode = require_TyneqCachedTerminalOperator.QueryNode;
+exports.QueryPlanCompiler = QueryPlanCompiler;
+exports.QueryPlanOptimizer = QueryPlanOptimizer;
+exports.QueryPlanPrinter = QueryPlanPrinter;
+exports.QueryPlanTransformer = QueryPlanTransformer;
+exports.QueryPlanWalker = QueryPlanWalker;
+exports.ReflectionContext = require_Lazy.ReflectionContext;
+exports.ReflectionError = require_Lazy.ReflectionError;
+exports.RegistryError = require_TyneqCachedTerminalOperator.RegistryError;
+exports.SequenceContainsNoElementsError = require_TyneqCachedTerminalOperator.SequenceContainsNoElementsError;
+exports.Tyneq = Tyneq;
+exports.TyneqBaseEnumerator = require_TyneqCachedTerminalOperator.TyneqBaseEnumerator;
+exports.TyneqCachedEnumerable = require_TyneqCachedTerminalOperator.TyneqCachedEnumerable;
+exports.TyneqCachedEnumerator = require_TyneqCachedTerminalOperator.TyneqCachedEnumerator;
+exports.TyneqCachedTerminalOperator = require_TyneqCachedTerminalOperator.TyneqCachedTerminalOperator;
+exports.TyneqComparer = require_TyneqCachedTerminalOperator.TyneqComparer;
+exports.TyneqEnumerator = require_TyneqCachedTerminalOperator.TyneqEnumerator;
+exports.TyneqError = require_Lazy.TyneqError;
+exports.TyneqOrderedEnumerable = require_TyneqCachedTerminalOperator.TyneqOrderedEnumerable;
+exports.TyneqOrderedEnumerator = require_TyneqCachedTerminalOperator.TyneqOrderedEnumerator;
+exports.TyneqOrderedTerminalOperator = require_TyneqCachedTerminalOperator.TyneqOrderedTerminalOperator;
+exports.TyneqTerminalOperator = require_TyneqCachedTerminalOperator.TyneqTerminalOperator;
+exports.TypeGuardUtility = require_Lazy.TypeGuardUtility;
+exports.ValidationBuilder = require_ValidationBuilder.ValidationBuilder;
+exports.ValidationError = require_ValidationBuilder.ValidationError;
+exports.cachedOperator = require_TyneqCachedTerminalOperator.cachedOperator;
+exports.cachedTerminal = require_TyneqCachedTerminalOperator.cachedTerminal;
+exports.createCachedOperator = require_TyneqCachedTerminalOperator.createCachedOperator;
+exports.createCachedTerminalOperator = require_TyneqCachedTerminalOperator.createCachedTerminalOperator;
+exports.createGeneratorOperator = require_TyneqCachedTerminalOperator.createGeneratorOperator;
+exports.createOperator = require_TyneqCachedTerminalOperator.createOperator;
+exports.createOrderedOperator = require_TyneqCachedTerminalOperator.createOrderedOperator;
+exports.createOrderedTerminalOperator = require_TyneqCachedTerminalOperator.createOrderedTerminalOperator;
+exports.createTerminalOperator = require_TyneqCachedTerminalOperator.createTerminalOperator;
+exports.isSourceNode = require_TyneqCachedTerminalOperator.isSourceNode;
+exports.operator = require_TyneqCachedTerminalOperator.operator;
+exports.orderedOperator = require_TyneqCachedTerminalOperator.orderedOperator;
+exports.orderedTerminal = require_TyneqCachedTerminalOperator.orderedTerminal;
+exports.reflect = require_Lazy.reflect;
+exports.terminal = require_TyneqCachedTerminalOperator.terminal;
+exports.tyneqQueryNode = require_TyneqCachedTerminalOperator.tyneqQueryNode;
+
+//# sourceMappingURL=index.cjs.map