@zakkster/lite-signal 1.2.0 → 1.2.2

package/Signal.d.ts

@@ -1,10 +1,10 @@
 /**
- * @zakkster/lite-signal — zero-GC reactive graph.
+ * @zakkster/lite-signal -- zero-GC reactive graph.
  *
  * Public type surface for the JavaScript implementation in `Signal.js`.
  */
 
-// ─── Options ──────────────────────────────────────────────────────────────────
+// --- Options ------------------------------------------------------------------
 
 /** Equality predicate. Returning `true` halts propagation. */
 export type EqualsFn<T> = (a: T, b: T) => boolean;
@@ -45,7 +45,7 @@ export type Dispose = () => void;
  */
 export type Disposable<T = unknown> = Signal<T> | Computed<T> | Dispose;
 
-// ─── Reactive primitive shapes ────────────────────────────────────────────────
+// --- Reactive primitive shapes ------------------------------------------------
 
 /** Reactive source of truth. */
 export interface Signal<T> {
@@ -71,7 +71,7 @@ export interface Computed<T> {
     subscribe(fn: (value: T) => void): Dispose;
 }
 
-// ─── Diagnostics ──────────────────────────────────────────────────────────────
+// --- Diagnostics --------------------------------------------------------------
 
 export interface RegistryStats {
     /** Number of signals created in this registry's lifetime. */
@@ -92,7 +92,7 @@ export interface RegistryStats {
     activeNodes: number;
 }
 
-// ─── Observer-lifecycle introspection (1.1.4) ─────────────────────────────────
+// --- Observer-lifecycle introspection (1.1.4) ---------------------------------
 
 /** Whether a described node is a signal, a computed, or an effect. */
 export type NodeKind = "signal" | "computed" | "effect";
@@ -109,9 +109,9 @@ export interface NodeDescriptor {
 
 /** Transition callbacks for {@link Registry.observeObservers}. */
 export interface ObserveObserversHooks {
-    /** Fired on the 0→1 observer transition (after registration). */
+    /** Fired on the 0->1 observer transition (after registration). */
     onConnect?: () => void;
-    /** Fired on the 1→0 observer transition. */
+    /** Fired on the 1->0 observer transition. */
     onDisconnect?: () => void;
 }
 
@@ -121,7 +121,36 @@ export type Unobserve = () => void;
 /** Anything carrying a node identity that the introspection surface can read. */
 export type ReactiveHandle = Signal<any> | Computed<any>;
 
-// ─── Errors ───────────────────────────────────────────────────────────────────
+// --- Graph-mutation hook (1.2.1) ----------------------------------------------
+
+/**
+ * Opcode passed as the first argument to a {@link GraphMutationListener}.
+ *
+ *  - `1` node create.    `(intA, intB) = (node.id, node.flags)`.
+ *  - `2` node dispose.   `(intA, intB) = (node.id, node.flags)` -- fires for every node
+ *                        disposed, including cascaded owner-tree children.
+ *  - `3` link add.       `(intA, intB) = (source.id, target.id)`.
+ *  - `4` link remove.    `(intA, intB) = (source.id, target.id)` -- `-1` if the link
+ *                        was already nulled (defensive, rare).
+ *  - `5` recompute.      `(intA, intB) = (node.id, 0)` -- fires just before an effect
+ *                        re-run or a computed re-eval.
+ */
+export type GraphMutationOpcode = 1 | 2 | 3 | 4 | 5;
+
+/**
+ * Listener registered with {@link Registry.onGraphMutation}. Called synchronously
+ * inside each mutation point with three integers -- no objects allocated.
+ *
+ * **Contract: observe only.** Listeners MUST NOT throw and MUST NOT mutate the
+ * graph from inside the callback. Both will corrupt the engine's state. Wrap any
+ * downstream work in a microtask if it could touch the registry.
+ */
+export type GraphMutationListener = (opcode: GraphMutationOpcode, intA: number, intB: number) => void;
+
+/** Idempotent unsubscriber returned by {@link Registry.onGraphMutation}. */
+export type GraphMutationUnsubscribe = () => void;
+
+// --- Errors -------------------------------------------------------------------
 
 /** Thrown when a pool ceiling is hit. */
 export class CapacityError extends Error {
@@ -131,7 +160,7 @@ export class CapacityError extends Error {
     constructor(kind: "nodes" | "links", capacity: number);
 }
 
-// ─── Registry ─────────────────────────────────────────────────────────────────
+// --- Registry -----------------------------------------------------------------
 
 export interface RegistryConfig {
     /** Initial node-pool capacity. Default: 1024. */
@@ -168,8 +197,8 @@ export interface Registry {
     isTracking(): boolean;
     /** O(1): does this source have at least one live observer right now? A `peek` does not count. */
     hasObservers(handle: ReactiveHandle): boolean;
-    /** Auto-pause hook: fires `onConnect` on the 0→1 observer transition and `onDisconnect`
-     *  on 1→0, after registration (transition-only — no immediate fire if already observed).
+    /** Auto-pause hook: fires `onConnect` on the 0->1 observer transition and `onDisconnect`
+     *  on 1->0, after registration (transition-only -- no immediate fire if already observed).
      *  Re-tracking a persistently-read source does not churn. Returns an idempotent unobserve.
      *  @throws TypeError if `handle` is not a reactive handle. */
     observeObservers(handle: ReactiveHandle, hooks?: ObserveObserversHooks): Unobserve;
@@ -177,16 +206,35 @@ export interface Registry {
     forEachObserver(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
     /** Walk the sources (dependencies) of `handle`. No-op on a non-handle. */
     forEachSource(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
-    /** Stable node id of `handle` (1.1.5+), or undefined for a non-handle. */
+    /** Walk the owned children of `handle` -- nodes whose lifetime is bound to this
+     *  one by the 1.2 owner tree (1.2.1+). Top-level handles and signals have no
+     *  owned children; effects/computeds may own nested observers created inside
+     *  their bodies. No-op on a non-handle or stale handle. */
+    forEachOwned(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
+    /** Descriptor of `handle`'s owner, or `undefined` for top-level handles, stale
+     *  handles, or non-handles (1.2.1+). The owner is the effect or computed inside
+     *  whose body `handle` was created -- the node that will cascade-dispose it
+     *  on re-run or explicit dispose. */
+    ownerOf(handle: ReactiveHandle): NodeDescriptor | undefined;
+    /** Stable node id of `handle` (1.1.5+), or undefined for a non-handle or stale handle. */
     nodeId(handle: ReactiveHandle): number | undefined;
-    /** The own descriptor of `handle` (1.1.5+), or undefined for a non-handle. Re-walkable:
-     *  the returned descriptor may be passed back into forEachObserver/forEachSource. */
+    /** The own descriptor of `handle` (1.1.5+), or undefined for a non-handle or stale handle.
+     *  Re-walkable: the returned descriptor may be passed back into forEachObserver/
+     *  forEachSource/forEachOwned/ownerOf. Descriptors are gen-stamped (1.2.1+): a
+     *  descriptor obtained pre-recycle goes stale and walks as undefined post-recycle. */
     describe(handle: ReactiveHandle): NodeDescriptor | undefined;
+    /** Register a single graph-mutation listener (1.2.1+). Replaces any existing
+     *  listener and returns an unsubscribe that restores the previous one on call.
+     *  Listener is invoked synchronously at each mutation point with three integers:
+     *  `(opcode, intA, intB)` -- see {@link GraphMutationOpcode}. Cost when no
+     *  listener is registered: one branch-predicted `null` check per mutation point.
+     *  @throws TypeError if `fn` is not a function or null. */
+    onGraphMutation(fn: GraphMutationListener | null): GraphMutationUnsubscribe;
     onCleanup(fn: () => void): void;
     stats(): RegistryStats;
     /** Reset everything: nodes, links, queues, global clock. Outstanding dispose
      *  closures become safe no-ops. Outstanding read/set closures still reference
-     *  pool slots — they will silently misbehave; use a fresh registry afterwards. */
+     *  pool slots -- they will silently misbehave; use a fresh registry afterwards. */
     destroy(): void;
 }
 
@@ -203,12 +251,12 @@ export function createRegistry(config?: RegistryConfig): Registry;
 /** Replace the default registry backing the top-level helpers. */
 export function setDefaultRegistry(registry: Registry): void;
 
-// ─── Top-level helpers (delegate to default registry) ────────────────────────
+// --- Top-level helpers (delegate to default registry) ------------------------
 
 export function signal<T>(initial: T, opts?: SignalOptions<T>): Signal<T>;
 export function computed<T>(fn: () => T, opts?: ComputedOptions<T>): Computed<T>;
 export function effect(fn: () => void, opts?: EffectOptions): Dispose;
-/** Universal disposal — see {@link Registry.dispose}. */
+/** Universal disposal -- see {@link Registry.dispose}. */
 export function dispose(api: Disposable): void;
 export function batch<T>(fn: () => T): T;
 export function untrack<T>(fn: () => T): T;
@@ -222,10 +270,16 @@ export function observeObservers(handle: ReactiveHandle, hooks?: ObserveObserver
 export function forEachObserver(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
 /** Top-level binding of {@link Registry.forEachSource}. */
 export function forEachSource(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
+/** Top-level binding of {@link Registry.forEachOwned} (1.2.1+). */
+export function forEachOwned(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
+/** Top-level binding of {@link Registry.ownerOf} (1.2.1+). */
+export function ownerOf(handle: ReactiveHandle): NodeDescriptor | undefined;
 /** Top-level binding of {@link Registry.nodeId}. */
 export function nodeId(handle: ReactiveHandle): number | undefined;
 /** Top-level binding of {@link Registry.describe}. */
 export function describe(handle: ReactiveHandle): NodeDescriptor | undefined;
+/** Top-level binding of {@link Registry.onGraphMutation} (1.2.1+). */
+export function onGraphMutation(fn: GraphMutationListener | null): GraphMutationUnsubscribe;
 export function onCleanup(fn: () => void): void;
 export function stats(): RegistryStats;
 export declare function destroy(): void;
@@ -242,7 +296,7 @@ export interface WatchOptions {
 
 /**
  * Track a reactive source and run a callback whenever its projected value
- * changes. The callback receives `(newValue, oldValue, stop)` — the third
+ * changes. The callback receives `(newValue, oldValue, stop)` -- the third
  * argument is a dispose function that can be called from inside the callback
  * to terminate the watcher.
  *
@@ -282,10 +336,10 @@ export function when(
  * Promise-returning variant of {@link when}. The returned promise resolves
  * when `predicate` first returns a truthy value.
  *
- * ⚠️ **HOT-PATH WARNING — DO NOT USE PER FRAME.** This function calls
+ * ! **HOT-PATH WARNING -- DO NOT USE PER FRAME.** This function calls
  * `new Promise(...)`, which is a heap allocation (one Promise object plus
  * executor closure plus internal infrastructure per call). Promises require
- * heap allocation by the language spec — this cost is unavoidable.
+ * heap allocation by the language spec -- this cost is unavoidable.
  *
  * **Use for:** high-level scene/UI orchestration, boot sequences, awaiting
  * user input or network state, level transitions. Anything that runs once