j-templates 8.0.19 → 8.0.21

package/Store/Tree/observableScope.d.ts

@@ -92,26 +92,24 @@ export declare function MappedScope<D, T>(data: D, callback: (data: D) => T | Pr
  */
 export declare function GateScope<T>(callback: () => T | Promise<T>, idOverride?: string): T;
 /**
- * Creates a computed scope that isn't registered as a dependency with the parent.
+ * Invokes a callback with dependency tracking suspended.
  * Use this function to read reactive data without subscribing to changes
  * to that data.
  *
- * Unlike GateScope, PeekScope does not register itself as a dependency, meaning
- * changes to the data accessed within the callback will not trigger recomputation
- * of the parent scope. The scope is still memoized by ID within the watch context
- * to avoid redundant computation during the same evaluation.
+ * No scope is created: the callback runs immediately on every call and nothing
+ * is memoized. Reactive values read inside the callback are not registered with
+ * the current watch context, so changes to them will not trigger recomputation
+ * of the parent scope. The previous watch context is restored afterwards, even
+ * if the callback throws.
  *
- * Supports async callbacks — Promise<T> is resolved and the resolved value is returned.
- *
- * Only works within a watch context (during another scope's execution).
- * Throws if called outside a watch context.
- * @template T The type of value returned by the callback (extracted from Promise if async).
- * @param callback The function to compute the derived value.
- * @param idOverride Optional custom ID for memoization when using multiple peek calls.
- * @returns The computed value, reusing existing scope if available.
- * @throws Error if called outside a watch context.
+ * Can be called anywhere, inside or outside a watch context. Because tracking is
+ * suspended, InlineScope, GateScope and MappedScope throw if called from within
+ * the callback. Async callbacks are not awaited; the Promise is returned as-is.
+ * @template T The type of value returned by the callback.
+ * @param callback The function to invoke without dependency tracking.
+ * @returns The value returned by the callback.
  */
-export declare function PeekScope<T>(callback: () => T | Promise<T>, idOverride?: string): T;
+export declare function PeekCallback<T>(callback: () => T): T;
 export declare namespace ObservableScope {
     /**
      * Creates a new observable scope from a value function.
@@ -178,6 +176,8 @@ export declare namespace ObservableScope {
     /**
      * Subscribes to changes on a dynamic scope.
      * @template T The type of value stored in the scope.
+     * The callback must not cause the same scope to emit again (for example by calling
+     * `Update(scope)`): re-entrant emits throw.
      * @param scope The scope to watch for changes.
      * @param callback Function to invoke when the scope's value changes.
      */

package/Store/Tree/observableScope.js

@@ -268,11 +268,7 @@ function ExecuteScope(scope) {
     }
 }
 function ExecuteBasicScope(scope) {
-    const parent = watchState;
-    watchState = null;
-    const result = scope.getFunction();
-    watchState = parent;
-    return result;
+    return PeekCallback(scope.getFunction);
 }
 /**
  * Creates a scope from a function, choosing between static and dynamic based on dependencies.
@@ -355,7 +351,6 @@ function MappedScopeHelper(callback, data, onUpdated, onDestroyed) {
 }
 const SCOPE_DEFAULT = Symbol("SCOPE_DEFAULT");
 const GATE_DEFAULT = Symbol("GATE_DEFAULT");
-const PEEK_DEFAULT = Symbol("PEEK_DEFAULT");
 /**
  * Creates an inline computed scope registered as a dependency of the parent.
  * The scope is memoized by ID and reused across reads within the same parent evaluation.
@@ -417,32 +412,32 @@ export function GateScope(callback, idOverride) {
     return GetScopeValue(scope);
 }
 /**
- * Creates a computed scope that isn't registered as a dependency with the parent.
+ * Invokes a callback with dependency tracking suspended.
  * Use this function to read reactive data without subscribing to changes
  * to that data.
  *
- * Unlike GateScope, PeekScope does not register itself as a dependency, meaning
- * changes to the data accessed within the callback will not trigger recomputation
- * of the parent scope. The scope is still memoized by ID within the watch context
- * to avoid redundant computation during the same evaluation.
+ * No scope is created: the callback runs immediately on every call and nothing
+ * is memoized. Reactive values read inside the callback are not registered with
+ * the current watch context, so changes to them will not trigger recomputation
+ * of the parent scope. The previous watch context is restored afterwards, even
+ * if the callback throws.
  *
- * Supports async callbacks — Promise<T> is resolved and the resolved value is returned.
- *
- * Only works within a watch context (during another scope's execution).
- * Throws if called outside a watch context.
- * @template T The type of value returned by the callback (extracted from Promise if async).
- * @param callback The function to compute the derived value.
- * @param idOverride Optional custom ID for memoization when using multiple peek calls.
- * @returns The computed value, reusing existing scope if available.
- * @throws Error if called outside a watch context.
+ * Can be called anywhere, inside or outside a watch context. Because tracking is
+ * suspended, InlineScope, GateScope and MappedScope throw if called from within
+ * the callback. Async callbacks are not awaited; the Promise is returned as-is.
+ * @template T The type of value returned by the callback.
+ * @param callback The function to invoke without dependency tracking.
+ * @returns The value returned by the callback.
  */
-export function PeekScope(callback, idOverride) {
-    if (watchState === null) {
-        throw new Error("peek() must be called within a watch context");
+export function PeekCallback(callback) {
+    const parent = watchState;
+    watchState = null;
+    try {
+        return callback();
+    }
+    finally {
+        watchState = parent;
     }
-    const id = idOverride ?? PEEK_DEFAULT;
-    const scope = ScopeHelper(callback, id, false);
-    return GetScopeValue(scope);
 }
 /**
  * Updates a scope's dependency emitters using efficient diffing.
@@ -621,6 +616,8 @@ export var ObservableScope;
     /**
      * Subscribes to changes on a dynamic scope.
      * @template T The type of value stored in the scope.
+     * The callback must not cause the same scope to emit again (for example by calling
+     * `Update(scope)`): re-entrant emits throw.
      * @param scope The scope to watch for changes.
      * @param callback Function to invoke when the scope's value changes.
      */

package/Utils/decorators.d.ts

@@ -39,13 +39,13 @@
  * | Aspect | @Computed | @Scope |
  * |--------|-----------|--------|
  * | Caching | ✅ Yes | ✅ Yes |
- * | Object identity preserved | ✅ Yes (ApplyDiff) | ❌ No (new object) |
+ * | Object identity preserved | ✅ Yes (Apply) | ❌ No (new object) |
  * | Overhead | Store + diff | Single scope |
  * | Best for | Complex objects | Primitives/simple values |
  *
  * Object Identity (Key Difference):
  * ---------------------------------
- * @Computed: Same object reference, in-place updates via ObservableNode.ApplyDiff
+ * @Computed: Same object reference, in-place updates via ObservableNode.Apply
  * @Scope: New object reference on every update
  *
  * Example:
@@ -104,13 +104,16 @@ import { Injector } from "./injector";
  * @remarks
  * The @Computed decorator uses a Gated getter scope driving a persistent observable node:
  * 1. Getter scope (Gated): Re-evaluates the getter when dependencies change, batched via
- *    the microtask queue. If the result deep-equals the previous value, no update is emitted.
+ *    the microtask queue, and returns a clone of the result. A watcher on this scope
+ *    applies each new clone to the node.
  * 2. ObservableNode.Apply: Diffs the fresh value against the node's current root and applies
- *    only the changed paths in-place, preserving the node's object identity.
- * 3. Downstream notification: Per-property scopes are fired for each changed path, so scopes
- *    reading sub-properties update directly. If the diff collapses to a full root replacement
- *    (type change or removed keys), the root value gets a new identity and the Gated scope
- *    emits, notifying top-level subscribers.
+ *    only the changed paths in-place, preserving the node's object identity. If the result
+ *    deep-equals the previous value, nothing is changed and nothing is emitted.
+ * 3. Downstream notification: Per-property emitters fire for each changed path, so scopes
+ *    reading sub-properties update directly. The property itself is backed by a separate
+ *    scope that reads the node's root; it emits, notifying top-level subscribers, only when
+ *    the diff collapses to a full root replacement (type change or removed keys) and the
+ *    root value gets a new identity.
  *
  * **Initialization**: @Computed uses lazy initialization - the scopes are created on first access:
  * ```typescript
@@ -127,7 +130,7 @@ import { Injector } from "./injector";
  * dependencies change. The key difference is what happens during re-evaluation:
  *
  * **Key benefit - Object Reuse**: The returned object maintains its identity across updates.
- * Only the changed properties are modified in-place using ObservableNode.ApplyDiff. This enables:
+ * Only the changed properties are modified in-place using ObservableNode.Apply. This enables:
  * - DOM reference preservation (no unnecessary re-renders)
  * - Existing proxy reuse (no proxy recreation overhead)
  * - Identity checks (===) remain stable across updates
@@ -156,7 +159,7 @@ import { Injector } from "./injector";
  * @see {@link Scope} for simple getter-based reactive properties (caches but new reference)
  * @see {@link ComputedAsync} for async computed properties
  * @see {@link ObservableNode.Apply} for how diffs are applied in-place to maintain object identity
- * @see {@link ObservableScope} for the Gated scope mechanism (batched, ===-gated updates)
+ * @see {@link ObservableScope} for the Gated scope mechanism (batched updates)
  * @see {@link StoreSync} for the store-backed variant used by @ComputedAsync
  */
 export declare function Computed<T extends WeakKey, K extends keyof T, D extends T[K]>(): (target: T, propertyKey: K, descriptor: PropertyDescriptor) => PropertyDescriptor;
@@ -488,7 +491,7 @@ export declare function Value(): any;
  *
  * @see {@link Computed} for cached computed properties with object reuse
  * @see {@link ComputedAsync} for sync getters with StoreAsync backend
- * @see {@link ObservableNode.ApplyDiff} for how @Computed maintains object identity
+ * @see {@link ObservableNode.Apply} for how @Computed maintains object identity
  * @see {@link ObservableScope} for the scope-based reactivity system
  * @see {@link scope} for inline computed scopes within @Scope
  */

package/Utils/decorators.js

@@ -39,13 +39,13 @@
  * | Aspect | @Computed | @Scope |
  * |--------|-----------|--------|
  * | Caching | ✅ Yes | ✅ Yes |
- * | Object identity preserved | ✅ Yes (ApplyDiff) | ❌ No (new object) |
+ * | Object identity preserved | ✅ Yes (Apply) | ❌ No (new object) |
  * | Overhead | Store + diff | Single scope |
  * | Best for | Complex objects | Primitives/simple values |
  *
  * Object Identity (Key Difference):
  * ---------------------------------
- * @Computed: Same object reference, in-place updates via ObservableNode.ApplyDiff
+ * @Computed: Same object reference, in-place updates via ObservableNode.Apply
  * @Scope: New object reference on every update
  *
  * Example:
@@ -56,7 +56,7 @@
  * console.log(list === list2);    // @Computed: true, @Scope: false
  * ```
  */
-import { ObservableScope, } from "../Store/Tree/observableScope";
+import { ObservableScope, PeekCallback, } from "../Store/Tree/observableScope";
 import { ObservableNode } from "../Store/Tree/observableNode";
 import { StoreAsync } from "../Store";
 /**
@@ -144,29 +144,43 @@ function CreateStoreScope(getter, store, defaultValue) {
     return propertyScope;
 }
 /**
- * Creates a Gated observable scope that exposes a getter's value through a persistent
+ * Creates an observable scope that exposes a getter's value through a persistent
  * observable node, preserving the value's object identity across updates.
  *
- * On each re-evaluation the getter's value is cloned and merged into the node in-place
- * via ObservableNode.Apply:
+ * The getter runs in a Gated scope that returns a clone of its value. A watcher on that
+ * scope merges each new clone into the node in-place via ObservableNode.Apply, with
+ * dependency tracking suspended. The returned scope reads the node's root:
  * - Content changes (same structure, changed properties) fire only the affected
- *   per-property scopes - the top-level scope does not emit.
+ *   per-property emitters - the returned scope does not emit.
  * - Structural changes (type change or removed keys) replace the root value with a new
- *   identity, which the Gated scope detects and emits for.
- * - Deep-equal results are suppressed entirely by the Gated ===-gating.
+ *   identity; the root's emitter fires and the returned scope emits.
+ * - Deep-equal results change nothing in the node, so nothing downstream is notified.
+ *
+ * Destroying the returned scope also destroys the Gated getter scope.
  *
  * @param getter Function computing the value. May read reactive dependencies.
- * @returns The Gated scope whose value is the observable root node.
+ * @returns A scope whose value is the observable node's root.
  */
 function CreateNodeScope(getter) {
-    const observableNode = ObservableNode.Create({ root: null });
     const getterScope = ObservableScope.Gated(function () {
         const value = getter();
         const clonedValue = ObservableNode.Clone(value);
-        ObservableNode.Apply(observableNode, { root: clonedValue });
+        return clonedValue;
+    });
+    const observableNode = ObservableNode.Create({ root: ObservableScope.Peek(getterScope) });
+    ObservableScope.Watch(getterScope, function (scope) {
+        PeekCallback(function () {
+            const value = ObservableScope.Peek(scope);
+            ObservableNode.Apply(observableNode, { root: value });
+        });
+    });
+    const nodeScope = ObservableScope.Create(function () {
         return observableNode.root;
     });
-    return getterScope;
+    ObservableScope.OnDestroyed(nodeScope, function () {
+        ObservableScope.Destroy(getterScope);
+    });
+    return nodeScope;
 }
 /**
  * Computed decorator factory for creating synchronous computed properties with caching and object reuse.
@@ -214,13 +228,16 @@ function CreateNodeScope(getter) {
  * @remarks
  * The @Computed decorator uses a Gated getter scope driving a persistent observable node:
  * 1. Getter scope (Gated): Re-evaluates the getter when dependencies change, batched via
- *    the microtask queue. If the result deep-equals the previous value, no update is emitted.
+ *    the microtask queue, and returns a clone of the result. A watcher on this scope
+ *    applies each new clone to the node.
  * 2. ObservableNode.Apply: Diffs the fresh value against the node's current root and applies
- *    only the changed paths in-place, preserving the node's object identity.
- * 3. Downstream notification: Per-property scopes are fired for each changed path, so scopes
- *    reading sub-properties update directly. If the diff collapses to a full root replacement
- *    (type change or removed keys), the root value gets a new identity and the Gated scope
- *    emits, notifying top-level subscribers.
+ *    only the changed paths in-place, preserving the node's object identity. If the result
+ *    deep-equals the previous value, nothing is changed and nothing is emitted.
+ * 3. Downstream notification: Per-property emitters fire for each changed path, so scopes
+ *    reading sub-properties update directly. The property itself is backed by a separate
+ *    scope that reads the node's root; it emits, notifying top-level subscribers, only when
+ *    the diff collapses to a full root replacement (type change or removed keys) and the
+ *    root value gets a new identity.
  *
  * **Initialization**: @Computed uses lazy initialization - the scopes are created on first access:
  * ```typescript
@@ -237,7 +254,7 @@ function CreateNodeScope(getter) {
  * dependencies change. The key difference is what happens during re-evaluation:
  *
  * **Key benefit - Object Reuse**: The returned object maintains its identity across updates.
- * Only the changed properties are modified in-place using ObservableNode.ApplyDiff. This enables:
+ * Only the changed properties are modified in-place using ObservableNode.Apply. This enables:
  * - DOM reference preservation (no unnecessary re-renders)
  * - Existing proxy reuse (no proxy recreation overhead)
  * - Identity checks (===) remain stable across updates
@@ -266,7 +283,7 @@ function CreateNodeScope(getter) {
  * @see {@link Scope} for simple getter-based reactive properties (caches but new reference)
  * @see {@link ComputedAsync} for async computed properties
  * @see {@link ObservableNode.Apply} for how diffs are applied in-place to maintain object identity
- * @see {@link ObservableScope} for the Gated scope mechanism (batched, ===-gated updates)
+ * @see {@link ObservableScope} for the Gated scope mechanism (batched updates)
  * @see {@link StoreSync} for the store-backed variant used by @ComputedAsync
  */
 export function Computed() {
@@ -733,7 +750,7 @@ function ValueDecorator(target, propertyKey) {
  *
  * @see {@link Computed} for cached computed properties with object reuse
  * @see {@link ComputedAsync} for sync getters with StoreAsync backend
- * @see {@link ObservableNode.ApplyDiff} for how @Computed maintains object identity
+ * @see {@link ObservableNode.Apply} for how @Computed maintains object identity
  * @see {@link ObservableScope} for the scope-based reactivity system
  * @see {@link scope} for inline computed scopes within @Scope
  */

package/Utils/emitter.d.ts

@@ -1,5 +1,5 @@
 export type EmitterCallback<T extends readonly any[] = any[]> = (...args: T) => void;
-export type Emitter = [number, ...EmitterCallback[]];
+export type Emitter = [[number, number], ...EmitterCallback[]];
 export declare namespace Emitter {
     function Create(): Emitter;
     function On(emitter: Emitter, callback: EmitterCallback): void;

package/Utils/emitter.js

@@ -1,8 +1,7 @@
-import { RemoveNulls } from "./array";
 import { _requestIdleCallback } from "./scheduling";
 const pendingCompactEmitters = new Set();
 function Compact(emitter) {
-    if (emitter.length === 1 || emitter[0] === 0)
+    if (emitter.length === 1 || emitter[0][0] === 0)
         return;
     pendingCompactEmitters.add(emitter);
     ScheduleCompact();
@@ -22,57 +21,63 @@ function PerformCompact() {
         CompactEmitter(compactEmitters[x]);
 }
 function CompactEmitter(emitter) {
-    if (emitter[0] === 0)
+    if (emitter[0][0] === 0)
         return;
-    emitter.splice(1, emitter[0]);
-    emitter[0] = 0;
+    emitter.splice(1, emitter[0][0]);
+    emitter[0][0] = 0;
 }
 export var Emitter;
 (function (Emitter) {
     function Create() {
-        return [0];
+        return [[0, -1]];
     }
     Emitter.Create = Create;
     function On(emitter, callback) {
         emitter.push(callback);
     }
     Emitter.On = On;
-    const emitterStack = [];
-    const modifiedDuringEmit = new Set();
+    // Re-entry during emit is not supported and considered a bug in client code
     function Emit(emitter, ...args) {
-        emitterStack.push(emitter);
-        for (let x = emitter[0] + 1; x < emitter.length; x++)
-            emitter[x]?.(...args);
-        emitterStack.pop();
-        if (modifiedDuringEmit.delete(emitter)) {
-            RemoveNulls(emitter);
-            emitter[0] = 0;
+        if (emitter[0][1] !== -1)
+            throw new Error("Emitter.Emit: re-entry during emit is not supported");
+        try {
+            for (let x = emitter[0][1] = emitter[0][0] + 1; x < emitter.length; emitter[0][1] = ++x) {
+                emitter[x](...args);
+            }
         }
+        finally {
+            emitter[0][1] = -1;
+        }
+        if (emitter[0][0] !== 0)
+            Compact(emitter);
     }
     Emitter.Emit = Emit;
+    function RemoveFromEnd(emitter, index) {
+        emitter[index] = emitter[emitter.length - 1];
+        emitter.pop();
+    }
+    function RemoveFromBeginning(emitter, index) {
+        const tombstoneSize = emitter[0][0];
+        emitter[index] = emitter[tombstoneSize + 1];
+        emitter[tombstoneSize + 1] = null;
+        emitter[0][0]++;
+    }
     function Remove(emitter, callback) {
         if (emitter.length === 1)
             return;
-        const startIndex = emitter[0] + 1;
+        const startIndex = emitter[0][0] + 1;
         const index = emitter.indexOf(callback, startIndex);
         if (index < 1)
             return;
-        const emitterStackIndex = emitterStack.indexOf(emitter);
-        if (emitterStackIndex < 0) {
-            emitter[0]++;
-            emitter[index] = emitter[startIndex];
-            emitter[startIndex] = null;
-            Compact(emitter);
-        }
-        else {
-            emitter[index] = null;
-            modifiedDuringEmit.add(emitter);
-        }
+        if (index <= emitter[0][1])
+            RemoveFromBeginning(emitter, index);
+        else
+            RemoveFromEnd(emitter, index);
     }
     Emitter.Remove = Remove;
     function Clear(emitter) {
         emitter.length > 1 && emitter.splice(1);
-        emitter[0] = 0;
+        emitter[0][0] = 0;
     }
     Emitter.Clear = Clear;
 })(Emitter || (Emitter = {}));

package/index.d.ts

@@ -1,3 +1,3 @@
 export { Component } from './Node/component';
-export { InlineScope as scope, GateScope as gate, PeekScope as peek, MappedScope as mapped } from './Store/Tree/observableScope';
+export { InlineScope as scope, GateScope as gate, PeekCallback as peek, MappedScope as mapped } from './Store/Tree/observableScope';
 export { vNode } from './Node/vNode.types';

package/index.js

@@ -1,2 +1,2 @@
 export { Component } from './Node/component';
-export { InlineScope as scope, GateScope as gate, PeekScope as peek, MappedScope as mapped } from './Store/Tree/observableScope';
+export { InlineScope as scope, GateScope as gate, PeekCallback as peek, MappedScope as mapped } from './Store/Tree/observableScope';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "j-templates",
-  "version": "8.0.19",
+  "version": "8.0.21",
   "description": "j-templates",
   "license": "MIT",
   "repository": "https://github.com/TypesInCode/jTemplates",