tyneq 1.0.1 → 1.0.2

package/dist/{TyneqCachedTerminalOperator-DTVuBGMn.d.ts → TyneqCachedTerminalOperator-BrW77zIy.d.ts}

@@ -1,4 +1,182 @@
-import { k as Constructor, l as Enumerable, m as EnumeratorFactory, O as OperatorSource, $ as TyneqEnumerableBase, X as TyneqOrderedSequence, T as TyneqSequence, N as Nullable, D as OrderedEnumerable, _ as tyneqQueryNode, e as QueryPlanNode, C as Comparer, E as Enumerator, a0 as BaseEnumerableSorter, V as TyneqCachedSequence, i as CachedEnumerable, h as CacheResult } from './core-DR17XN89.js';
+import { y as OperatorEntry, S as SequenceConstructor, M as Maybe, b as OperatorMetadata, O as OperatorSource, j as Constructor, k as Enumerable, l as EnumeratorFactory, $ as TyneqEnumerableBase, X as TyneqOrderedSequence, T as TyneqSequence, N as Nullable, D as OrderedEnumerable, _ as tyneqQueryNode, d as QueryPlanNode, C as Comparer, E as Enumerator, a0 as BaseEnumerableSorter, V as TyneqCachedSequence, h as CachedEnumerable, g as CacheResult } from './core-C54TSmgW.js';
+
+/**
+ * Central registry for all Tyneq operators.
+ *
+ * Every registration path - `@operator`, `@terminal`, `createOperator`,
+ * `createGeneratorOperator`, `createTerminalOperator` - flows through this class.
+ * It is the single source of truth for which operators exist, their kind, and their
+ * prototype-level implementation.
+ *
+ * Internally the registry maintains two separate namespaces:
+ * - Source factories (`Tyneq.from`, `Tyneq.range`, etc.) - keyed by name alone.
+ * - Instance operators (`.where`, `.select`, etc.) - keyed by (name, targetClass).
+ *
+ * This means a source factory and an instance method can share a name without
+ * conflict (e.g. `Tyneq.concat` and `seq.concat`), and two instance operators
+ * with the same name on different prototype chains (e.g. `ordered.foo` and
+ * `cached.foo`) also coexist without conflict.
+ *
+ * @example
+ * ```ts
+ * import { OperatorRegistry } from "tyneq/plugin";
+ *
+ * OperatorRegistry.has("where"); // -> true
+ * OperatorRegistry.list(); // -> OperatorMetadata[]
+ * ```
+ *
+ * @group Classes
+ */
+declare class OperatorRegistry {
+    private static readonly _sources;
+    private static readonly _operators;
+    private static readonly _registrationHooks;
+    private static readonly _registrationGuards;
+    /**
+     * Registers an operator entry and patches the method onto `entry.metadata.targetClass.prototype`.
+     *
+     * @throws {RegistryError} When an operator with the same name is already registered on the same targetClass.
+     */
+    static register(input: OperatorEntry): void;
+    /**
+     * Removes an operator registration and deletes the prototype method for external operators.
+     *
+     * Checks the instance operator namespace first, then the source namespace.
+     *
+     * @returns `true` if the operator was found and removed; `false` if no operator with that name existed.
+     * @remarks
+     * Internal operators (source `"internal"`) are not removed from the prototype - only
+     * their registry entry is deleted.
+     *
+     * For targeted removal use {@link unregisterOperator} or {@link unregisterSource}.
+     */
+    static unregister(name: string): boolean;
+    /**
+     * Removes a specific instance operator registration for a given (name, targetClass) pair
+     * and deletes the prototype method for external operators.
+     *
+     * @returns `true` if the entry was found and removed; `false` otherwise.
+     */
+    static unregisterOperator(name: string, targetClass: SequenceConstructor): boolean;
+    /**
+     * Removes a source factory registration.
+     *
+     * @returns `true` if the source was found and removed; `false` otherwise.
+     */
+    static unregisterSource(name: string): boolean;
+    /**
+     * Registers a hook called after every successful operator registration (both namespaces).
+     *
+     * @returns A function that removes the hook when called.
+     */
+    static onRegister(hook: (entry: OperatorEntry) => void): () => void;
+    /**
+     * Registers a guard called before every registration (both namespaces).
+     * Throw from the guard to reject the registration.
+     *
+     * @returns A function that removes the guard when called.
+     */
+    static addGuard(guard: (entry: OperatorEntry) => void): () => void;
+    /**
+     * Returns `true` if a name exists in either the source or instance operator namespace.
+     * Use {@link hasSource} or {@link hasOperator} for namespace-specific checks.
+     */
+    static has(name: string): boolean;
+    /**
+     * Returns `true` if a source factory with `name` is registered.
+     */
+    static hasSource(name: string): boolean;
+    /**
+     * Returns `true` if an instance operator with `name` is registered.
+     * When `targetClass` is provided, checks only that specific (name, targetClass) pair.
+     * When omitted, returns `true` if any target has an operator with that name.
+     */
+    static hasOperator(name: string, targetClass?: SequenceConstructor): boolean;
+    /**
+     * Returns the operator entry for `name` from either namespace, or `undefined` if not found.
+     * Checks the instance operator namespace first, then the source namespace.
+     * For namespace-specific retrieval use {@link getSource} or {@link getOperator}.
+     */
+    static get(name: string): Maybe<OperatorEntry>;
+    /**
+     * Returns the source factory entry for `name`, or `undefined` if not registered.
+     */
+    static getSource(name: string): Maybe<OperatorEntry>;
+    /**
+     * Returns the instance operator entry for `name` on `targetClass`, or `undefined`.
+     * When `targetClass` is omitted, returns the first entry found across all targets.
+     */
+    static getOperator(name: string, targetClass?: SequenceConstructor): Maybe<OperatorEntry>;
+    /**
+     * Returns the metadata for `name` from either namespace, or `undefined` if not found.
+     * Checks instance operators first, then sources.
+     */
+    static getMetadata(name: string): Maybe<OperatorMetadata>;
+    /**
+     * Returns metadata for all registered operators and source factories.
+     * Use {@link listOperators} or {@link listSources} for namespace-specific lists.
+     */
+    static list(): readonly OperatorMetadata[];
+    /**
+     * Returns metadata for all registered source factories.
+     */
+    static listSources(): readonly OperatorMetadata[];
+    /**
+     * Returns metadata for all registered instance operators.
+     * When `targetClass` is provided, returns only entries for that specific target class.
+     */
+    static listOperators(targetClass?: SequenceConstructor): readonly OperatorMetadata[];
+    /** Returns metadata for all operators of `kind` across both namespaces. */
+    static listByKind(kind: OperatorMetadata["kind"]): readonly OperatorMetadata[];
+    /** Returns metadata for all operators from `source` across both namespaces. */
+    static listBySource(source: OperatorMetadata["source"]): readonly OperatorMetadata[];
+    /** Returns the total number of registered operators across both namespaces. */
+    static count(): number;
+    /**
+     * Registers a source operator (a static factory, not a prototype method).
+     *
+     * @remarks
+     * Source operators differ from prototype operators in two ways:
+     * - They are called with `null` as `this` - they have no instance.
+     * - They are looked up by the compiler via {@link getSource} rather than
+     *   being patched onto a prototype.
+     *
+     * The entry is stored in the source namespace and is never patched onto any prototype.
+     * Registration guards run for `"external"` sources (same policy as {@link register}).
+    * Guards are skipped for `"internal"` sources (same policy used for internal builtins).
+     *
+     * Third-party source operators registered here are automatically compiled by
+     * `QueryPlanCompiler` without any changes to the compiler.
+     *
+     * @param name - The operator name, matching the `operatorName` on the `QueryPlanNode`.
+     * @param factory - The factory function; receives the node args in order, `this` is `null`.
+     * @param source - Whether this is a built-in or external source operator. Defaults to `"external"`.
+     *
+     * @example
+     * ```ts
+     * import { OperatorRegistry } from "tyneq/plugin";
+     * import { Tyneq } from "tyneq";
+     *
+     * OperatorRegistry.registerSource("fibonacci", (count) => {
+     *     // return a Tyneq sequence of fibonacci numbers
+     * });
+     * ```
+     *
+     * @group Classes
+     */
+    static registerSource(name: string, factory: (...args: unknown[]) => unknown, source?: OperatorSource): void;
+    /**
+     * Records a built-in operator in the instance operator namespace without patching the prototype.
+     * Built-in operators already live as direct methods on their target class.
+     *
+     * @remarks
+     * Registration guards are intentionally skipped - builtins are internal and
+     * trusted; guards exist to validate external plugin registrations only.
+     *
+     * @internal
+     */
+    static registerBuiltin(name: string, kind: OperatorMetadata["kind"], targetClass: SequenceConstructor): void;
+}
 
 /**
  * Class decorator that registers a `TyneqEnumerator` subclass as an operator on every sequence.
@@ -698,4 +876,4 @@ declare abstract class TyneqCachedTerminalOperator<TSource, TResult = TSource> {
     abstract process(): TResult;
 }
 
-export { TyneqBaseEnumerator as T, TyneqCachedEnumerator as a, TyneqCachedTerminalOperator as b, TyneqEnumerator as c, TyneqOrderedEnumerator as d, TyneqOrderedTerminalOperator as e, TyneqTerminalOperator as f, cachedOperator as g, cachedTerminal as h, createCachedOperator as i, createCachedTerminalOperator as j, createGeneratorOperator as k, createOperator as l, createOrderedOperator as m, createOrderedTerminalOperator as n, createTerminalOperator as o, operator as p, orderedOperator as q, orderedTerminal as r, TyneqCachedEnumerable as s, terminal as t, TyneqOrderedEnumerable as u };
+export { OperatorRegistry as O, TyneqBaseEnumerator as T, TyneqCachedEnumerator as a, TyneqCachedTerminalOperator as b, TyneqEnumerator as c, TyneqOrderedEnumerator as d, TyneqOrderedTerminalOperator as e, TyneqTerminalOperator as f, cachedOperator as g, cachedTerminal as h, createCachedOperator as i, createCachedTerminalOperator as j, createGeneratorOperator as k, createOperator as l, createOrderedOperator as m, createOrderedTerminalOperator as n, createTerminalOperator as o, operator as p, orderedOperator as q, orderedTerminal as r, TyneqCachedEnumerable as s, terminal as t, TyneqOrderedEnumerable as u };

package/dist/{TyneqCachedTerminalOperator-QzqAHJSE.d.cts → TyneqCachedTerminalOperator-EaNiNt61.d.cts}

@@ -1,4 +1,182 @@
-import { k as Constructor, l as Enumerable, m as EnumeratorFactory, O as OperatorSource, $ as TyneqEnumerableBase, X as TyneqOrderedSequence, T as TyneqSequence, N as Nullable, D as OrderedEnumerable, _ as tyneqQueryNode, e as QueryPlanNode, C as Comparer, E as Enumerator, a0 as BaseEnumerableSorter, V as TyneqCachedSequence, i as CachedEnumerable, h as CacheResult } from './core-DR17XN89.cjs';
+import { y as OperatorEntry, S as SequenceConstructor, M as Maybe, b as OperatorMetadata, O as OperatorSource, j as Constructor, k as Enumerable, l as EnumeratorFactory, $ as TyneqEnumerableBase, X as TyneqOrderedSequence, T as TyneqSequence, N as Nullable, D as OrderedEnumerable, _ as tyneqQueryNode, d as QueryPlanNode, C as Comparer, E as Enumerator, a0 as BaseEnumerableSorter, V as TyneqCachedSequence, h as CachedEnumerable, g as CacheResult } from './core-C54TSmgW.cjs';
+
+/**
+ * Central registry for all Tyneq operators.
+ *
+ * Every registration path - `@operator`, `@terminal`, `createOperator`,
+ * `createGeneratorOperator`, `createTerminalOperator` - flows through this class.
+ * It is the single source of truth for which operators exist, their kind, and their
+ * prototype-level implementation.
+ *
+ * Internally the registry maintains two separate namespaces:
+ * - Source factories (`Tyneq.from`, `Tyneq.range`, etc.) - keyed by name alone.
+ * - Instance operators (`.where`, `.select`, etc.) - keyed by (name, targetClass).
+ *
+ * This means a source factory and an instance method can share a name without
+ * conflict (e.g. `Tyneq.concat` and `seq.concat`), and two instance operators
+ * with the same name on different prototype chains (e.g. `ordered.foo` and
+ * `cached.foo`) also coexist without conflict.
+ *
+ * @example
+ * ```ts
+ * import { OperatorRegistry } from "tyneq/plugin";
+ *
+ * OperatorRegistry.has("where"); // -> true
+ * OperatorRegistry.list(); // -> OperatorMetadata[]
+ * ```
+ *
+ * @group Classes
+ */
+declare class OperatorRegistry {
+    private static readonly _sources;
+    private static readonly _operators;
+    private static readonly _registrationHooks;
+    private static readonly _registrationGuards;
+    /**
+     * Registers an operator entry and patches the method onto `entry.metadata.targetClass.prototype`.
+     *
+     * @throws {RegistryError} When an operator with the same name is already registered on the same targetClass.
+     */
+    static register(input: OperatorEntry): void;
+    /**
+     * Removes an operator registration and deletes the prototype method for external operators.
+     *
+     * Checks the instance operator namespace first, then the source namespace.
+     *
+     * @returns `true` if the operator was found and removed; `false` if no operator with that name existed.
+     * @remarks
+     * Internal operators (source `"internal"`) are not removed from the prototype - only
+     * their registry entry is deleted.
+     *
+     * For targeted removal use {@link unregisterOperator} or {@link unregisterSource}.
+     */
+    static unregister(name: string): boolean;
+    /**
+     * Removes a specific instance operator registration for a given (name, targetClass) pair
+     * and deletes the prototype method for external operators.
+     *
+     * @returns `true` if the entry was found and removed; `false` otherwise.
+     */
+    static unregisterOperator(name: string, targetClass: SequenceConstructor): boolean;
+    /**
+     * Removes a source factory registration.
+     *
+     * @returns `true` if the source was found and removed; `false` otherwise.
+     */
+    static unregisterSource(name: string): boolean;
+    /**
+     * Registers a hook called after every successful operator registration (both namespaces).
+     *
+     * @returns A function that removes the hook when called.
+     */
+    static onRegister(hook: (entry: OperatorEntry) => void): () => void;
+    /**
+     * Registers a guard called before every registration (both namespaces).
+     * Throw from the guard to reject the registration.
+     *
+     * @returns A function that removes the guard when called.
+     */
+    static addGuard(guard: (entry: OperatorEntry) => void): () => void;
+    /**
+     * Returns `true` if a name exists in either the source or instance operator namespace.
+     * Use {@link hasSource} or {@link hasOperator} for namespace-specific checks.
+     */
+    static has(name: string): boolean;
+    /**
+     * Returns `true` if a source factory with `name` is registered.
+     */
+    static hasSource(name: string): boolean;
+    /**
+     * Returns `true` if an instance operator with `name` is registered.
+     * When `targetClass` is provided, checks only that specific (name, targetClass) pair.
+     * When omitted, returns `true` if any target has an operator with that name.
+     */
+    static hasOperator(name: string, targetClass?: SequenceConstructor): boolean;
+    /**
+     * Returns the operator entry for `name` from either namespace, or `undefined` if not found.
+     * Checks the instance operator namespace first, then the source namespace.
+     * For namespace-specific retrieval use {@link getSource} or {@link getOperator}.
+     */
+    static get(name: string): Maybe<OperatorEntry>;
+    /**
+     * Returns the source factory entry for `name`, or `undefined` if not registered.
+     */
+    static getSource(name: string): Maybe<OperatorEntry>;
+    /**
+     * Returns the instance operator entry for `name` on `targetClass`, or `undefined`.
+     * When `targetClass` is omitted, returns the first entry found across all targets.
+     */
+    static getOperator(name: string, targetClass?: SequenceConstructor): Maybe<OperatorEntry>;
+    /**
+     * Returns the metadata for `name` from either namespace, or `undefined` if not found.
+     * Checks instance operators first, then sources.
+     */
+    static getMetadata(name: string): Maybe<OperatorMetadata>;
+    /**
+     * Returns metadata for all registered operators and source factories.
+     * Use {@link listOperators} or {@link listSources} for namespace-specific lists.
+     */
+    static list(): readonly OperatorMetadata[];
+    /**
+     * Returns metadata for all registered source factories.
+     */
+    static listSources(): readonly OperatorMetadata[];
+    /**
+     * Returns metadata for all registered instance operators.
+     * When `targetClass` is provided, returns only entries for that specific target class.
+     */
+    static listOperators(targetClass?: SequenceConstructor): readonly OperatorMetadata[];
+    /** Returns metadata for all operators of `kind` across both namespaces. */
+    static listByKind(kind: OperatorMetadata["kind"]): readonly OperatorMetadata[];
+    /** Returns metadata for all operators from `source` across both namespaces. */
+    static listBySource(source: OperatorMetadata["source"]): readonly OperatorMetadata[];
+    /** Returns the total number of registered operators across both namespaces. */
+    static count(): number;
+    /**
+     * Registers a source operator (a static factory, not a prototype method).
+     *
+     * @remarks
+     * Source operators differ from prototype operators in two ways:
+     * - They are called with `null` as `this` - they have no instance.
+     * - They are looked up by the compiler via {@link getSource} rather than
+     *   being patched onto a prototype.
+     *
+     * The entry is stored in the source namespace and is never patched onto any prototype.
+     * Registration guards run for `"external"` sources (same policy as {@link register}).
+    * Guards are skipped for `"internal"` sources (same policy used for internal builtins).
+     *
+     * Third-party source operators registered here are automatically compiled by
+     * `QueryPlanCompiler` without any changes to the compiler.
+     *
+     * @param name - The operator name, matching the `operatorName` on the `QueryPlanNode`.
+     * @param factory - The factory function; receives the node args in order, `this` is `null`.
+     * @param source - Whether this is a built-in or external source operator. Defaults to `"external"`.
+     *
+     * @example
+     * ```ts
+     * import { OperatorRegistry } from "tyneq/plugin";
+     * import { Tyneq } from "tyneq";
+     *
+     * OperatorRegistry.registerSource("fibonacci", (count) => {
+     *     // return a Tyneq sequence of fibonacci numbers
+     * });
+     * ```
+     *
+     * @group Classes
+     */
+    static registerSource(name: string, factory: (...args: unknown[]) => unknown, source?: OperatorSource): void;
+    /**
+     * Records a built-in operator in the instance operator namespace without patching the prototype.
+     * Built-in operators already live as direct methods on their target class.
+     *
+     * @remarks
+     * Registration guards are intentionally skipped - builtins are internal and
+     * trusted; guards exist to validate external plugin registrations only.
+     *
+     * @internal
+     */
+    static registerBuiltin(name: string, kind: OperatorMetadata["kind"], targetClass: SequenceConstructor): void;
+}
 
 /**
  * Class decorator that registers a `TyneqEnumerator` subclass as an operator on every sequence.
@@ -698,4 +876,4 @@ declare abstract class TyneqCachedTerminalOperator<TSource, TResult = TSource> {
     abstract process(): TResult;
 }
 
-export { TyneqBaseEnumerator as T, TyneqCachedEnumerator as a, TyneqCachedTerminalOperator as b, TyneqEnumerator as c, TyneqOrderedEnumerator as d, TyneqOrderedTerminalOperator as e, TyneqTerminalOperator as f, cachedOperator as g, cachedTerminal as h, createCachedOperator as i, createCachedTerminalOperator as j, createGeneratorOperator as k, createOperator as l, createOrderedOperator as m, createOrderedTerminalOperator as n, createTerminalOperator as o, operator as p, orderedOperator as q, orderedTerminal as r, TyneqCachedEnumerable as s, terminal as t, TyneqOrderedEnumerable as u };
+export { OperatorRegistry as O, TyneqBaseEnumerator as T, TyneqCachedEnumerator as a, TyneqCachedTerminalOperator as b, TyneqEnumerator as c, TyneqOrderedEnumerator as d, TyneqOrderedTerminalOperator as e, TyneqTerminalOperator as f, cachedOperator as g, cachedTerminal as h, createCachedOperator as i, createCachedTerminalOperator as j, createGeneratorOperator as k, createOperator as l, createOrderedOperator as m, createOrderedTerminalOperator as n, createTerminalOperator as o, operator as p, orderedOperator as q, orderedTerminal as r, TyneqCachedEnumerable as s, terminal as t, TyneqOrderedEnumerable as u };

package/dist/{chunk-KT2G2VJZ.js → chunk-5R4AALC7.js}

@@ -678,4 +678,3 @@ export {
   reflect,
   Lazy
 };
-//# sourceMappingURL=chunk-KT2G2VJZ.js.map

package/dist/{chunk-D2KVCXTF.cjs → chunk-C5PBY3ZU.cjs}

@@ -1,9 +1,9 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunk6QXGRDROcjs = require('./chunk-6QXGRDRO.cjs');
+var _chunkOWKUE3ACcjs = require('./chunk-OWKUE3AC.cjs');
 
 // src/core/errors/argument/ValidationError.ts
-var ValidationError = class extends _chunk6QXGRDROcjs.ArgumentError {
+var ValidationError = class extends _chunkOWKUE3ACcjs.ArgumentError {
   constructor(errors) {
     super(
       `${errors.length} validation error(s):
@@ -44,4 +44,3 @@ var ValidationBuilder = class {
 
 
 exports.ValidationError = ValidationError; exports.ValidationBuilder = ValidationBuilder;
-//# sourceMappingURL=chunk-D2KVCXTF.cjs.map

package/dist/{chunk-6QXGRDRO.cjs → chunk-OWKUE3AC.cjs}

@@ -678,4 +678,3 @@ var Lazy = class {
 
 
 exports.__decoratorStart = __decoratorStart; exports.__decoratorMetadata = __decoratorMetadata; exports.__runInitializers = __runInitializers; exports.__decorateElement = __decorateElement; exports.__asyncGenerator = __asyncGenerator; exports.nameof = nameof; exports.TyneqError = TyneqError; exports.ArgumentError = ArgumentError; exports.ArgumentNullError = ArgumentNullError; exports.ArgumentOutOfRangeError = ArgumentOutOfRangeError; exports.ArgumentTypeError = ArgumentTypeError; exports.TypeGuardUtility = TypeGuardUtility; exports.ArgumentUtility = ArgumentUtility; exports.ReflectionError = ReflectionError; exports.ReflectionContext = ReflectionContext; exports.reflect = reflect; exports.Lazy = Lazy;
-//# sourceMappingURL=chunk-6QXGRDRO.cjs.map

package/dist/{chunk-DVHUFMNJ.js → chunk-PCBN5AFG.js}

@@ -1,6 +1,6 @@
 import {
   ArgumentError
-} from "./chunk-KT2G2VJZ.js";
+} from "./chunk-5R4AALC7.js";
 
 // src/core/errors/argument/ValidationError.ts
 var ValidationError = class extends ArgumentError {
@@ -44,4 +44,3 @@ export {
   ValidationError,
   ValidationBuilder
 };
-//# sourceMappingURL=chunk-DVHUFMNJ.js.map