j-templates 7.0.84 → 7.0.86

package/Node/vNode.js

@@ -174,7 +174,7 @@ function CreateChildrenScope(vnode, children, data = DefaultData) {
     if ((0, functions_1.IsAsync)(data)) {
         const asyncData = data;
         data = function () {
-            return (0, observableScope_1.CalcScope)(async function () {
+            return (0, observableScope_1.InlineScope)(async function () {
                 return asyncData();
             });
         };

package/Store/Tree/observableScope.d.ts

@@ -35,8 +35,8 @@ interface IDynamicObservableScope<T> {
     emitters: (Emitter | null)[];
     /** Emitter for notifying when the scope is destroyed */
     onDestroyed: Emitter | null;
-    /** Map of nested calc scopes created during this scope's execution */
-    calcScopes: {
+    /** Map of nested scopes created during this scope's execution */
+    scopes: {
         [id: string]: IObservableScope<unknown> | null;
     } | null;
 }
@@ -46,21 +46,62 @@ interface IDynamicObservableScope<T> {
  */
 export type IObservableScope<T> = IStaticObservableScope<T> | IDynamicObservableScope<T>;
 /**
- * Creates a computed scope that acts as a gatekeeper for parent scope emissions.
- * If this scope's value doesn't change (=== comparison) it won't emit.
+ * 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.
+ * Emits on every recomputation — no === gating.
  *
- * Useful for optimizing expensive operations driven by key values (e.g., sort keys).
- * Scopes are memoized by ID and reused across multiple reads within a single parent scope evaluation.
- * Defaults to "default" ID - provide custom IDs when using multiple calc scopes.
+ * Supports async callbacks — Promise<T> is resolved and the resolved value is emitted.
  *
  * Only works within a watch context (during another scope's execution).
+ * Throws if called outside a watch context.
+ * Creates non-greedy scopes that emit immediately without === gating.
+ * @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 scope calls.
+ * @returns The computed value, reusing existing scope if available.
+ * @throws Error if called outside a watch context.
+ */
+export declare function InlineScope<T>(callback: () => T | Promise<T>, idOverride?: string): T;
+/**
+ * Creates a gatekeeper scope that only emits when the value actually changes (===).
+ * Prevents unnecessary downstream re-evaluations when the derived value stays the same.
+ *
+ * Useful for optimizing expensive operations driven by frequently-changing parent state.
+ * Scopes are memoized by ID and reused across reads within the same parent evaluation.
+ *
+ * Supports async callbacks — Promise<T> is resolved and the resolved value is gated.
+ *
+ * Only works within a watch context (during another scope's execution).
+ * Throws if called outside a watch context.
  * Always creates greedy scopes that batch updates via microtask queue.
- * @template T The type of value returned by the callback.
+ * @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 gate calls.
+ * @returns The computed value, reusing existing scope if available.
+ * @throws Error if called outside a watch context.
+ */
+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.
+ * 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.
+ *
+ * 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 calc scopes.
+ * @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.
  */
-export declare function CalcScope<T>(callback: () => T, idOverride?: string): T;
+export declare function PeekScope<T>(callback: () => T | Promise<T>, idOverride?: string): T;
 export declare namespace ObservableScope {
     /**
      * Creates a new observable scope from a value function.

package/Store/Tree/observableScope.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ObservableScope = void 0;
-exports.CalcScope = CalcScope;
+exports.InlineScope = InlineScope;
+exports.GateScope = GateScope;
+exports.PeekScope = PeekScope;
 const emitter_1 = require("../../Utils/emitter");
 const functions_1 = require("../../Utils/functions");
 /**
@@ -26,7 +28,7 @@ function CreateDynamicScope(getFunction, greedy, value) {
         emitter: emitter_1.Emitter.Create(),
         emitters: null,
         onDestroyed: null,
-        calcScopes: null,
+        scopes: null,
     };
     scope.setCallback = OnSet.bind(scope);
     return scope;
@@ -189,7 +191,7 @@ let watchState = null;
  * Executes a callback while tracking all scope and emitter dependencies.
  * Creates a watch context that records what was accessed during execution.
  * @param callback The function to execute while tracking dependencies.
- * @param currentCalc Optional map of existing calc scopes to reuse.
+ * @param currentCalc Optional map of existing inline scopes to reuse.
  * @returns The watch state containing tracked dependencies and result.
  */
 function WatchFunction(callback, currentCalc, initialEmitters) {
@@ -220,17 +222,21 @@ function WatchFunction(callback, currentCalc, initialEmitters) {
  */
 function ExecuteScope(scope) {
     scope.dirty = false;
-    const state = WatchFunction(scope.getFunction, scope.calcScopes, scope.emitters);
+    const state = WatchFunction(scope.getFunction, scope.scopes, scope.emitters);
     UpdateEmitters(scope, state);
     const calcScopes = state.currentCalc;
-    scope.calcScopes = state.nextCalc;
+    scope.scopes = state.nextCalc;
     for (const key in calcScopes)
         DestroyScope(calcScopes[key]);
-    if (scope.async)
-        state.value.then(function (result) {
+    if (scope.async) {
+        const promise = state.value;
+        promise.then(function (result) {
+            if (state.value !== promise)
+                return;
             scope.value = result;
             emitter_1.Emitter.Emit(scope.emitter, scope);
         });
+    }
     else
         scope.value = state.value;
 }
@@ -247,48 +253,112 @@ function ExecuteFunction(callback, greedy, allowStatic) {
     const state = WatchFunction(callback, null, null);
     if (!allowStatic || async || state.emitters !== null) {
         const scope = CreateDynamicScope(callback, greedy, async ? null : state.value);
-        scope.calcScopes = state.nextCalc;
+        scope.scopes = state.nextCalc;
         UpdateEmitters(scope, state);
-        if (async)
-            state.value.then(function (result) {
+        if (async) {
+            const promise = state.value;
+            promise.then(function (result) {
+                if (state.value !== promise)
+                    return;
                 scope.value = result;
                 emitter_1.Emitter.Emit(scope.emitter, scope);
             });
+        }
         return scope;
     }
     const value = state.value;
     return CreateStaticScope(value);
 }
+function ScopeHelper(callback, id, greedy) {
+    const nextScopes = (watchState.nextCalc ??= {});
+    if (nextScopes[id])
+        return nextScopes[id];
+    const currentScopes = watchState.currentCalc;
+    nextScopes[id] =
+        currentScopes?.[id] ?? ExecuteFunction(callback, greedy, true);
+    if (currentScopes?.[id])
+        delete currentScopes[id];
+    return nextScopes[id];
+}
 /**
- * Creates a computed scope that acts as a gatekeeper for parent scope emissions.
- * If this scope's value doesn't change (=== comparison) it won't emit.
+ * 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.
+ * Emits on every recomputation — no === gating.
+ *
+ * Supports async callbacks — Promise<T> is resolved and the resolved value is emitted.
+ *
+ * Only works within a watch context (during another scope's execution).
+ * Throws if called outside a watch context.
+ * Creates non-greedy scopes that emit immediately without === gating.
+ * @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 scope calls.
+ * @returns The computed value, reusing existing scope if available.
+ * @throws Error if called outside a watch context.
+ */
+function InlineScope(callback, idOverride) {
+    if (watchState === null) {
+        throw new Error("scope() must be called within a watch context");
+    }
+    const id = idOverride ?? "scope_default";
+    const scope = ScopeHelper(callback, id, false);
+    RegisterScope(scope);
+    return GetScopeValue(scope);
+}
+/**
+ * Creates a gatekeeper scope that only emits when the value actually changes (===).
+ * Prevents unnecessary downstream re-evaluations when the derived value stays the same.
+ *
+ * Useful for optimizing expensive operations driven by frequently-changing parent state.
+ * Scopes are memoized by ID and reused across reads within the same parent evaluation.
  *
- * Useful for optimizing expensive operations driven by key values (e.g., sort keys).
- * Scopes are memoized by ID and reused across multiple reads within a single parent scope evaluation.
- * Defaults to "default" ID - provide custom IDs when using multiple calc scopes.
+ * Supports async callbacks — Promise<T> is resolved and the resolved value is gated.
  *
  * Only works within a watch context (during another scope's execution).
+ * Throws if called outside a watch context.
  * Always creates greedy scopes that batch updates via microtask queue.
- * @template T The type of value returned by the callback.
+ * @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 calc scopes.
+ * @param idOverride Optional custom ID for memoization when using multiple gate calls.
  * @returns The computed value, reusing existing scope if available.
+ * @throws Error if called outside a watch context.
  */
-function CalcScope(callback, idOverride) {
-    if (watchState === null)
-        return callback();
-    const nextScopes = (watchState.nextCalc ??= {});
-    const id = idOverride ?? "default";
-    if (nextScopes[id]) {
-        RegisterScope(nextScopes[id]);
-        return GetScopeValue(nextScopes[id]);
+function GateScope(callback, idOverride) {
+    if (watchState === null) {
+        throw new Error("gate() must be called within a watch context");
     }
-    const currentScopes = watchState.currentCalc;
-    nextScopes[id] = currentScopes?.[id] ?? ExecuteFunction(callback, true, true);
-    if (currentScopes?.[id])
-        delete currentScopes[id];
-    RegisterScope(nextScopes[id]);
-    return GetScopeValue(nextScopes[id]);
+    const id = idOverride ?? "gate_default";
+    const scope = ScopeHelper(callback, id, true);
+    RegisterScope(scope);
+    return GetScopeValue(scope);
+}
+/**
+ * Creates a computed scope that isn't registered as a dependency with the parent.
+ * 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.
+ *
+ * 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.
+ */
+function PeekScope(callback, idOverride) {
+    if (watchState === null) {
+        throw new Error("peek() must be called within a watch context");
+    }
+    const id = idOverride ?? "peek_default";
+    const scope = ScopeHelper(callback, id, false);
+    return GetScopeValue(scope);
 }
 /**
  * Updates a scope's dependency emitters using efficient diffing.
@@ -350,12 +420,12 @@ function DestroyScope(scope) {
     if (!scope || scope.type === "static")
         return;
     emitter_1.Emitter.Clear(scope.emitter);
-    for (const key in scope.calcScopes)
-        DestroyScope(scope.calcScopes[key]);
+    for (const key in scope.scopes)
+        DestroyScope(scope.scopes[key]);
     for (let x = 0; x < scope.emitters.length; x++)
         emitter_1.Emitter.Remove(scope.emitters[x], scope.setCallback);
     scope.value = undefined;
-    scope.calcScopes = null;
+    scope.scopes = null;
     scope.emitters = null;
     scope.emitter = null;
     scope.getFunction = null;

package/Utils/decorators.d.ts

@@ -21,7 +21,7 @@
  * | getters only (expensive)  | @Computed | Cached + object reuse via Store |
  * | getters only (simple)     | @Scope  | Cached, but new reference on update |
  * | getters only (sync, StoreAsync) | @ComputedAsync | Sync getter, StoreAsync caching + object reuse |
-* | async functions (direct scope) | ObservableScope.Create(async) | Direct async, new reference, initial null |
+ * | async functions (direct scope) | ObservableScope.Create(async) | Direct async, new reference, initial null |
  * | subscribe to changes      | @Watch  | Calls method when scope value changes |
  * | dependency injection      | @Inject | Gets value from component injector |
  * | cleanup on destroy        | @Destroy| Calls .Destroy() on component teardown |
@@ -233,7 +233,7 @@ export declare function Computed<T extends WeakKey, K extends keyof T, D extends
  * Both use synchronous getters and provide object identity preservation.
  *
  * **Comparison**:
- * | Aspect | @Scope | @Computed | @ComputedAsync | calc(async) + @Scope |
+ * | Aspect | @Scope | @Computed | @ComputedAsync | scope(async) + @Scope |
  * |--------|--------|-----------|----------------|----------------------|
  * | Caches value | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes (memoized) |
  * | Getter type | Sync | Sync | Sync | Async supported |
@@ -461,15 +461,15 @@ export declare function Value(): any;
  * - Object identity matters (array/object references used in templates)
  * - You need DOM reference preservation to avoid re-renders
  *
- * **Async pattern with @Scope**: Use `calc(async () => ...)` for async operations:
+ * **Async pattern with @Scope**: Use `scope(async () => ...)` for async operations:
  * ```typescript
  * @Scope()
  * get CurrentUser() {
- *   return calc(async () => fetchUser(`/api/user/${this.userId}`));
+ *   return scope(async () => fetchUser(`/api/user/${this.userId}`));
  * }
  * ```
- * - `calc` memoizes async operations with ID-based caching
- * - Returns Promise initially, resolves when complete
+ * - `scope` creates an inline computed scope that resolves the async operation
+ * - Returns the resolved value (not a Promise)
  * - Automatically batches updates via microtask queue
  * - New reference on each update (no object reuse)
  *
@@ -486,7 +486,7 @@ export declare function Value(): any;
  * @see {@link ComputedAsync} for sync getters with StoreAsync backend
  * @see {@link ObservableNode.ApplyDiff} for how @Computed maintains object identity
  * @see {@link ObservableScope} for the scope-based reactivity system
- * @see {@link calc} for memoized async operations within @Scope
+ * @see {@link scope} for inline computed scopes within @Scope
  */
 export declare function Scope(): typeof ScopeDecorator;
 /**

package/Utils/decorators.js

@@ -22,7 +22,7 @@
  * | getters only (expensive)  | @Computed | Cached + object reuse via Store |
  * | getters only (simple)     | @Scope  | Cached, but new reference on update |
  * | getters only (sync, StoreAsync) | @ComputedAsync | Sync getter, StoreAsync caching + object reuse |
-* | async functions (direct scope) | ObservableScope.Create(async) | Direct async, new reference, initial null |
+ * | async functions (direct scope) | ObservableScope.Create(async) | Direct async, new reference, initial null |
  * | subscribe to changes      | @Watch  | Calls method when scope value changes |
  * | dependency injection      | @Inject | Gets value from component injector |
  * | cleanup on destroy        | @Destroy| Calls .Destroy() on component teardown |
@@ -136,10 +136,14 @@ function GetDestroyArrayForPrototype(prototype, create = true) {
 function CreateComputedScope(getter, store, defaultValue) {
     const getterScope = observableScope_1.ObservableScope.Create(getter, true);
     observableScope_1.ObservableScope.Watch(getterScope, (scope) => {
-        const data = observableScope_1.ObservableScope.Value(scope);
+        const data = observableScope_1.ObservableScope.Peek(scope);
         store.Write(data, "root");
     });
-    const propertyScope = observableScope_1.ObservableScope.Create(() => store.Get("root", defaultValue));
+    const data = observableScope_1.ObservableScope.Peek(getterScope);
+    store.Write(data, "root");
+    const propertyScope = observableScope_1.ObservableScope.Create(() => {
+        return store.Get("root", defaultValue);
+    });
     observableScope_1.ObservableScope.OnDestroyed(propertyScope, function () {
         observableScope_1.ObservableScope.Destroy(getterScope);
         if (store instanceof Store_1.StoreAsync)
@@ -356,7 +360,7 @@ function ComputedDecorator(target, prop, descriptor) {
  * Both use synchronous getters and provide object identity preservation.
  *
  * **Comparison**:
- * | Aspect | @Scope | @Computed | @ComputedAsync | calc(async) + @Scope |
+ * | Aspect | @Scope | @Computed | @ComputedAsync | scope(async) + @Scope |
  * |--------|--------|-----------|----------------|----------------------|
  * | Caches value | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes (memoized) |
  * | Getter type | Sync | Sync | Sync | Async supported |
@@ -684,15 +688,15 @@ function ValueDecorator(target, propertyKey) {
  * - Object identity matters (array/object references used in templates)
  * - You need DOM reference preservation to avoid re-renders
  *
- * **Async pattern with @Scope**: Use `calc(async () => ...)` for async operations:
+ * **Async pattern with @Scope**: Use `scope(async () => ...)` for async operations:
  * ```typescript
  * @Scope()
  * get CurrentUser() {
- *   return calc(async () => fetchUser(`/api/user/${this.userId}`));
+ *   return scope(async () => fetchUser(`/api/user/${this.userId}`));
  * }
  * ```
- * - `calc` memoizes async operations with ID-based caching
- * - Returns Promise initially, resolves when complete
+ * - `scope` creates an inline computed scope that resolves the async operation
+ * - Returns the resolved value (not a Promise)
  * - Automatically batches updates via microtask queue
  * - New reference on each update (no object reuse)
  *
@@ -709,7 +713,7 @@ function ValueDecorator(target, propertyKey) {
  * @see {@link ComputedAsync} for sync getters with StoreAsync backend
  * @see {@link ObservableNode.ApplyDiff} for how @Computed maintains object identity
  * @see {@link ObservableScope} for the scope-based reactivity system
- * @see {@link calc} for memoized async operations within @Scope
+ * @see {@link scope} for inline computed scopes within @Scope
  */
 function Scope() {
     return ScopeDecorator;

package/index.d.ts

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

package/index.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.calc = exports.Component = void 0;
+exports.peek = exports.gate = exports.scope = exports.Component = void 0;
 var component_1 = require("./Node/component");
 Object.defineProperty(exports, "Component", { enumerable: true, get: function () { return component_1.Component; } });
 var observableScope_1 = require("./Store/Tree/observableScope");
-Object.defineProperty(exports, "calc", { enumerable: true, get: function () { return observableScope_1.CalcScope; } });
+Object.defineProperty(exports, "scope", { enumerable: true, get: function () { return observableScope_1.InlineScope; } });
+Object.defineProperty(exports, "gate", { enumerable: true, get: function () { return observableScope_1.GateScope; } });
+Object.defineProperty(exports, "peek", { enumerable: true, get: function () { return observableScope_1.PeekScope; } });

package/package.json

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