regor 1.3.7 → 1.3.9

package/dist/regor.d.ts

@@ -1,5 +1,6 @@
 // Generated by dts-bundle-generator v9.5.1
 
+export type ContextClass<TValue extends object> = abstract new (...args: never[]) => TValue;
 /**
  * Runtime metadata passed to a component's `context(head)` factory.
  *
@@ -125,6 +126,50 @@ export declare class ComponentHead<TContext extends IRegorContext | object = IRe
 	 * ```
 	 */
 	emit: (event: string, args: Record<string, unknown>) => void;
+	/**
+	 * Finds a parent context instance by constructor type from the captured
+	 * context stack.
+	 *
+	 * Matching uses `instanceof` and respects stack order.
+	 *
+	 * `occurrence` selects which matching instance to return:
+	 * - `0` (default): first match
+	 * - `1`: second match
+	 * - `2`: third match
+	 * - negative values: always `undefined`
+	 *
+	 * Example:
+	 * ```ts
+	 * // stack: [RootCtx, ParentCtx, ParentCtx]
+	 * head.findContext(ParentCtx)    // first ParentCtx
+	 * head.findContext(ParentCtx, 1) // second ParentCtx
+	 * ```
+	 *
+	 * @param constructor - Class constructor used for `instanceof` matching.
+	 * @param occurrence - Zero-based index of the matching instance to return.
+	 * @returns The matching parent context instance, or `undefined` when not found.
+	 */
+	findContext<TValue extends object>(constructor: ContextClass<TValue>, occurrence?: number): TValue | undefined;
+	/**
+	 * Returns a parent context instance by constructor type from the captured
+	 * context stack.
+	 *
+	 * The stack is scanned in order and each entry is checked with `instanceof`.
+	 * `occurrence` is zero-based (`0` = first match, `1` = second match, ...).
+	 * If no instance exists at the requested occurrence, this method throws.
+	 *
+	 * Example:
+	 * ```ts
+	 * const auth = head.requireContext(AuthContext)     // first AuthContext
+	 * const outer = head.requireContext(LayoutCtx, 1)   // second LayoutCtx
+	 * ```
+	 *
+	 * @param constructor - Class constructor used for `instanceof` matching.
+	 * @param occurrence - Zero-based index of the instance to return.
+	 * @returns The parent context instance at the requested occurrence.
+	 * @throws Error when no matching instance exists at the requested occurrence.
+	 */
+	requireContext<TValue extends object>(constructor: ContextClass<TValue>, occurrence?: number): TValue;
 	/**
 	 * Unmounts this component instance by removing nodes between `start` and `end`
 	 * and calling unmount lifecycle handlers for captured contexts.
@@ -483,6 +528,62 @@ export declare const getBindData: (node: object) => BindData;
 export declare const removeNode: (node: ChildNode) => void;
 export declare const drainUnbind: () => Promise<void>;
 export declare const unbind: (node: Node) => void;
+/**
+ * Registry for sharing typed context instances across component boundaries.
+ *
+ * Entries are keyed by the runtime constructor of each registered instance:
+ * - one active entry per concrete constructor
+ * - registering another instance of the same constructor replaces the previous
+ *
+ * Lookup is type-based and uses `instanceof`, so querying a base class can
+ * resolve a registered subclass instance.
+ */
+export declare class ContextRegistry {
+	private readonly byConstructor;
+	/**
+	 * Registers a context instance under its concrete runtime constructor.
+	 *
+	 * If an instance with the same constructor already exists, it is replaced.
+	 *
+	 * @param context - Context instance to register.
+	 */
+	register<TContext extends object>(context: TContext): void;
+	/**
+	 * Removes the entry for a constructor.
+	 *
+	 * No-op when the constructor is not registered.
+	 *
+	 * @param contextClass - Constructor key to remove.
+	 */
+	unregisterByClass<TContext extends object>(contextClass: ContextClass<TContext>): void;
+	/**
+	 * Removes a specific context instance if it is currently registered for its
+	 * constructor.
+	 *
+	 * This prevents deleting a newer replacement instance of the same class.
+	 *
+	 * @param context - Context instance to remove.
+	 */
+	unregister<TContext extends object>(context: TContext): void;
+	/**
+	 * Finds a context instance by constructor type.
+	 *
+	 * The registry is scanned in insertion order and each entry is checked with
+	 * `instanceof contextClass`.
+	 *
+	 * @param contextClass - Class to match via `instanceof`.
+	 * @returns Matching instance, or `undefined` when not found.
+	 */
+	find<TContext extends object>(contextClass: ContextClass<TContext>): TContext | undefined;
+	/**
+	 * Resolves a context instance by constructor type and guarantees a value.
+	 *
+	 * @param contextClass - Class to match via `instanceof`.
+	 * @returns Matching context instance.
+	 * @throws Error when no matching context is registered.
+	 */
+	require<TContext extends object>(contextClass: ContextClass<TContext>): TContext;
+}
 export declare const onMounted: (onMounted: OnMounted) => void;
 export declare const onUnmounted: (onUnmounted: OnUnmounted, noThrow?: boolean) => void;
 export declare const useScope: <TRegorContext extends IRegorContext | object>(context: () => TRegorContext) => Scope<TRegorContext>;

package/dist/regor.es2015.cjs.js

@@ -60,6 +60,7 @@ var __async = (__this, __arguments, generator) => {
 var index_exports = {};
 __export(index_exports, {
   ComponentHead: () => ComponentHead,
+  ContextRegistry: () => ContextRegistry,
   RegorConfig: () => RegorConfig,
   addUnbinder: () => addUnbinder,
   batch: () => batch,
@@ -357,6 +358,66 @@ var ComponentHead = class {
     this.start = start;
     this.end = end;
   }
+  /**
+   * Finds a parent context instance by constructor type from the captured
+   * context stack.
+   *
+   * Matching uses `instanceof` and respects stack order.
+   *
+   * `occurrence` selects which matching instance to return:
+   * - `0` (default): first match
+   * - `1`: second match
+   * - `2`: third match
+   * - negative values: always `undefined`
+   *
+   * Example:
+   * ```ts
+   * // stack: [RootCtx, ParentCtx, ParentCtx]
+   * head.findContext(ParentCtx)    // first ParentCtx
+   * head.findContext(ParentCtx, 1) // second ParentCtx
+   * ```
+   *
+   * @param constructor - Class constructor used for `instanceof` matching.
+   * @param occurrence - Zero-based index of the matching instance to return.
+   * @returns The matching parent context instance, or `undefined` when not found.
+   */
+  findContext(constructor, occurrence = 0) {
+    var _a;
+    if (occurrence < 0) return void 0;
+    let current = 0;
+    for (const value of (_a = this.ctx) != null ? _a : []) {
+      if (!(value instanceof constructor)) continue;
+      if (current === occurrence) return value;
+      ++current;
+    }
+    return void 0;
+  }
+  /**
+   * Returns a parent context instance by constructor type from the captured
+   * context stack.
+   *
+   * The stack is scanned in order and each entry is checked with `instanceof`.
+   * `occurrence` is zero-based (`0` = first match, `1` = second match, ...).
+   * If no instance exists at the requested occurrence, this method throws.
+   *
+   * Example:
+   * ```ts
+   * const auth = head.requireContext(AuthContext)     // first AuthContext
+   * const outer = head.requireContext(LayoutCtx, 1)   // second LayoutCtx
+   * ```
+   *
+   * @param constructor - Class constructor used for `instanceof` matching.
+   * @param occurrence - Zero-based index of the instance to return.
+   * @returns The parent context instance at the requested occurrence.
+   * @throws Error when no matching instance exists at the requested occurrence.
+   */
+  requireContext(constructor, occurrence = 0) {
+    const value = this.findContext(constructor, occurrence);
+    if (value !== void 0) return value;
+    throw new Error(
+      `${constructor} was not found in the context stack at occurrence ${occurrence}.`
+    );
+  }
   /**
    * Unmounts this component instance by removing nodes between `start` and `end`
    * and calling unmount lifecycle handlers for captured contexts.
@@ -5967,6 +6028,76 @@ var defineComponent = (template, options = {}) => {
   };
 };
 
+// src/composition/ContextRegistry.ts
+var ContextRegistry = class {
+  constructor() {
+    __publicField(this, "byConstructor", /* @__PURE__ */ new Map());
+  }
+  /**
+   * Registers a context instance under its concrete runtime constructor.
+   *
+   * If an instance with the same constructor already exists, it is replaced.
+   *
+   * @param context - Context instance to register.
+   */
+  register(context) {
+    this.byConstructor.set(context.constructor, context);
+  }
+  /**
+   * Removes the entry for a constructor.
+   *
+   * No-op when the constructor is not registered.
+   *
+   * @param contextClass - Constructor key to remove.
+   */
+  unregisterByClass(contextClass) {
+    this.byConstructor.delete(contextClass);
+  }
+  /**
+   * Removes a specific context instance if it is currently registered for its
+   * constructor.
+   *
+   * This prevents deleting a newer replacement instance of the same class.
+   *
+   * @param context - Context instance to remove.
+   */
+  unregister(context) {
+    const key = context.constructor;
+    if (this.byConstructor.get(key) === context) {
+      this.byConstructor.delete(key);
+    }
+  }
+  /**
+   * Finds a context instance by constructor type.
+   *
+   * The registry is scanned in insertion order and each entry is checked with
+   * `instanceof contextClass`.
+   *
+   * @param contextClass - Class to match via `instanceof`.
+   * @returns Matching instance, or `undefined` when not found.
+   */
+  find(contextClass) {
+    for (const value of this.byConstructor.values()) {
+      if (value instanceof contextClass) return value;
+    }
+    return void 0;
+  }
+  /**
+   * Resolves a context instance by constructor type and guarantees a value.
+   *
+   * @param contextClass - Class to match via `instanceof`.
+   * @returns Matching context instance.
+   * @throws Error when no matching context is registered.
+   */
+  require(contextClass) {
+    const value = this.find(contextClass);
+    if (value) return value;
+    throw new Error(
+      `${contextClass.name} is not registered in ContextRegistry.`
+    );
+  }
+};
+
 // src/composition/onMounted.ts
 var onMounted = (onMounted2) => {
   var _a;