@zakkster/lite-signal 1.1.2 → 1.1.3

package/README.md

@@ -90,6 +90,7 @@ No microtask between `B` and `I`. No promise, no `queueMicrotask`. Just call sta
 - **`dispose(api)`** — universal disposal for signals, computeds, and effect handles. Cross-registry calls are silent no-ops.
 - **`batch(fn)`** — defer effect flush until the outermost batch closes.
 - **`untrack(fn)`** — read without subscribing.
+- **`isTracking()`** — `true` iff a read right now would subscribe (for lazy-allocation wrappers).
 - **`onCleanup(fn)`** — register teardown for the current computation. Works in effects *and* computeds.
 - **`createRegistry(config)`** — isolated pool for tests, plugins, sandboxing.
 - **`stats()`** — pool occupancy snapshot. Used by the demo and easy to wire into perf overlays.
@@ -273,6 +274,28 @@ const value = untrack(() => s());  // read without subscribing
 
 Useful inside computeds/effects when you need a current value but don't want it as a dependency.
 
+### isTracking
+
+```ts
+function makeLazyField(initial) {
+  let s = null, value = initial;
+  return {
+    get() {
+      if (isTracking()) {
+        if (s === null) s = signal(value);   // allocate only when subscribed
+        return s();
+      }
+      return value;
+    },
+    set(v) { value = v; if (s !== null) s.set(v); }
+  };
+}
+```
+
+Returns `true` iff a read right now would record a dependency on the current registry — an observer body is on the stack AND tracking is enabled. Mirrors the engine's own read-trap check (both flags), so it correctly returns `false` inside `untrack`, inside `subscribe` callbacks, inside `onCleanup` bodies, inside `watch` / `when` callbacks, and outside any observer.
+
+For wrapper libraries (lite-store, lite-query, lite-form) gating lazy allocation on the read path. Per-registry — call `registry.isTracking()` if your signals live in a non-default registry.
+
 ### onCleanup
 
 ```ts
@@ -547,6 +570,7 @@ Three tiers, all reproducible.
 - **`07-dispose.test.mjs`** — unified `dispose(api)` across signals, computeds and effect handles, idempotency, cross-registry isolation (per-registry Symbol prevents pool corruption), foreign-value safety, top-level helper routing, 500-cycle balanced churn leaving pool and stats stable.
 - **`08-watch.test.mjs`** — Validates the user-land observer utilities (watch, when, whenAsync). Covers lifecycle teardown, old/new value tracking, and Promise-based asynchronous state resolution.
 - **`09-conformance.test.mjs`** — Industry-standard conformance tests. Validates the engine against extreme edge cases from the johnsoncodehk reactive test suite, ensuring strict zero-GC invariants, correct cleanup isolation, and re-entrant stability.
+- **`10-is-tracking.test.mjs`** — The `isTracking()` observer-context predicate. 11 tests across 5 describe blocks: true inside effect/computed bodies; false inside `untrack`, `subscribe` callbacks, `onCleanup` bodies, and `watch` callbacks (the untracked-window cases that catch an observer-only misimplementation); false outside any observer including at the call site of an unobserved computed read; state-restoration after a thrown body; per-registry isolation; top-level binding.
 
 ```bash
 npm test

package/Signal.d.ts

@@ -133,6 +133,10 @@ export interface Registry {
     dispose(api: Disposable): void;
     batch<T>(fn: () => T): T;
     untrack<T>(fn: () => T): T;
+    /** True iff a read RIGHT NOW would record a dependency on this registry.
+     *  False inside `untrack`, `subscribe` callbacks, `onCleanup` bodies, and
+     *  outside any observer. Use for lazy-allocation wrappers like lite-store. */
+    isTracking(): boolean;
     onCleanup(fn: () => void): void;
     stats(): RegistryStats;
     /** Reset everything: nodes, links, queues, global clock. Outstanding dispose
@@ -163,6 +167,8 @@ export function effect(fn: () => void, opts?: EffectOptions): Dispose;
 export function dispose(api: Disposable): void;
 export function batch<T>(fn: () => T): T;
 export function untrack<T>(fn: () => T): T;
+/** Top-level binding of {@link Registry.isTracking} against the default registry. */
+export function isTracking(): boolean;
 export function onCleanup(fn: () => void): void;
 export function stats(): RegistryStats;
 export declare function destroy(): void;

package/Signal.js

@@ -993,6 +993,32 @@ export function createRegistry(config = {}) {
      * @param {() => T} fn
      * @returns {T}
      */
+    /**
+     * Returns true iff a read RIGHT NOW would record a dependency in the current
+     * call stack: an observer body is on the stack AND tracking is enabled.
+     *
+     * Mirrors the engine's own read-trap predicate (both flags checked). Returns
+     * false inside `untrack()`, inside `signal.subscribe`'s callback (which
+     * inlines the same untracked-notify pattern), inside `runCleanup` bodies,
+     * and outside any observer.
+     *
+     * Use case: wrapper libraries (lite-store, lite-query, lite-form) that
+     * lazily allocate reactive primitives on property reads — gating on
+     * isTracking() lets them skip allocation when reads happen outside a
+     * reactive context, preserving the zero-GC contract.
+     *
+     * Cost: two closure-variable loads, one AND, one return. ~1–2 ns.
+     *
+     * Note: per-registry. Wrappers operating against a non-default registry
+     * MUST call that registry's `isTracking()`, not the top-level one — each
+     * registry has its own tracking state.
+     *
+     * @returns {boolean}
+     */
+    function isTracking() {
+        return isTrackingDeps && currentObserver !== null;
+    }
+
     function untrack(fn) {
         const prev = isTrackingDeps;
         isTrackingDeps = false;
@@ -1101,7 +1127,7 @@ export function createRegistry(config = {}) {
         flushErrorBuffer.length = 0; // release the backing array
     }
 
-    return {signal, computed, effect, dispose, batch, untrack, onCleanup, stats, destroy};
+    return {signal, computed, effect, dispose, batch, untrack, onCleanup, stats, destroy, isTracking};
 }
 
 // ─────────────────────────────────────────────────────────────────
@@ -1150,6 +1176,15 @@ export function untrack(fn) {
     return defaultRegistry.untrack(fn);
 }
 
+/**
+ * True iff a read RIGHT NOW would record a dependency on the default registry.
+ * See {@link createRegistry} for the per-registry version. Wrappers operating
+ * against a non-default registry MUST call THAT registry's `isTracking()`.
+ */
+export function isTracking() {
+    return defaultRegistry.isTracking();
+}
+
 /** @type {Registry["onCleanup"]} */
 export function onCleanup(fn) {
     return defaultRegistry.onCleanup(fn);

package/llms.txt

@@ -19,6 +19,7 @@ triggering write — no `queueMicrotask`, no promises, no scheduler ticks.
 - **dispose(api)**: universal disposal. Accepts a signal, computed, or effect dispose handle; idempotent; cross-registry calls are silent no-ops (per-registry `Symbol("node_ptr")` keys the node-identity slot on the returned API function, foreign signals fail the lookup and fall through). Passing an unrelated value is also safe; passing an arbitrary function invokes it (effect-handle contract).
 - **Batch**: `batch(fn)` defers effect flush until the outermost batch closes. Nestable.
 - **Untrack**: `untrack(fn)` reads without subscribing.
+- **isTracking**: `isTracking()` returns true iff a read right now would record a dependency on this registry (for wrappers that lazily allocate signals).
 - **onCleanup**: registers teardown for the current computation; fires before each re-run and once on dispose. Works in effects and computeds.
 - **Registry**: `createRegistry({ maxNodes, maxLinks, onCapacityExceeded, maxFlushPasses })` creates an isolated reactive world with its own pools. Useful for tests, plugins, multi-tenant sandboxes. Top-level helpers use a default registry created at module load.
 - **CapacityError**: thrown when a fixed-size pool is exhausted under the `"throw"` policy, or when a `"grow"` policy hits the 16× starting-capacity ceiling on links.
@@ -48,6 +49,16 @@ triggering write — no `queueMicrotask`, no promises, no scheduler ticks.
 
 ## Version notes
 
+- **1.1.3**: adds `isTracking()` (top-level + per-registry). Returns true iff a
+  read right now would record a dependency (`isTrackingDeps && currentObserver !== null`).
+  False inside `untrack`, `subscribe` callbacks, `onCleanup` bodies, `watch` /
+  `when` callbacks, and outside any observer. ~1–2 ns. For wrapper libraries
+  (lite-store, lite-query, lite-form) that allocate reactive primitives lazily
+  on property reads. Per-registry: wrappers operating against a non-default
+  registry must call THAT registry's `isTracking()`, not the top-level one.
+  No behavior or engine changes.
+
+
 - **1.1.2** (current): hot-path micro-optimizations, no behavior/API change.
   Inlined cursor fast-path in `signal`/`computed` reads (stable-order reads skip
   the `allocateLink` call); zero-allocation creation path (`opts` read defensively
@@ -79,6 +90,7 @@ function effect(fn: () => void, opts?: { scheduler?: (run: () => void) => void }
 function dispose(api: Signal<any> | Computed<any> | Dispose): void;
 function batch<T>(fn: () => T): T;
 function untrack<T>(fn: () => T): T;
+function isTracking(): boolean;
 function onCleanup(fn: () => void): void;
 function stats(): RegistryStats;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-signal",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Zero-GC reactive graph. Monomorphic object pool, versioned push-pull propagation, 32-bit modular versioning. Built for hot paths and long-running processes.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",