j-templates 7.0.85 → 7.0.87

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

@@ -46,38 +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 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.
  */
-export declare function CalcScope<T>(callback: () => T, idOverride?: string): T;
+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 CalcScope, PeekScope does not register itself as a dependency, meaning
+ * 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).
- * @template T The type of value returned by the callback.
+ * 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 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 PeekScope<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,8 @@
 "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");
@@ -190,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) {
@@ -280,24 +281,53 @@ function ScopeHelper(callback, id, greedy) {
     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.
  *
- * 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.
+ */
+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.
+ *
+ * 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 id = idOverride ?? "calc_default";
+function GateScope(callback, idOverride) {
+    if (watchState === null) {
+        throw new Error("gate() must be called within a watch context");
+    }
+    const id = idOverride ?? "gate_default";
     const scope = ScopeHelper(callback, id, true);
     RegisterScope(scope);
     return GetScopeValue(scope);
@@ -307,20 +337,25 @@ function CalcScope(callback, idOverride) {
  * Use this function to read reactive data without subscribing to changes
  * to that data.
  *
- * Unlike CalcScope, PeekScope does not register itself as a dependency, meaning
+ * 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).
- * @template T The type of value returned by the callback.
+ * 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 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.
  */
 function PeekScope(callback, idOverride) {
-    if (watchState === null)
-        return callback();
+    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);
@@ -387,8 +422,9 @@ function DestroyScope(scope) {
     emitter_1.Emitter.Clear(scope.emitter);
     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);
+    if (scope.emitters !== null)
+        for (let x = 0; x < scope.emitters.length; x++)
+            emitter_1.Emitter.Remove(scope.emitters[x], scope.setCallback);
     scope.value = undefined;
     scope.scopes = null;
     scope.emitters = 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, PeekScope as peek } from './Store/Tree/observableScope';
+export { InlineScope as scope, GateScope as gate, PeekScope as peek } from './Store/Tree/observableScope';

package/index.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.peek = 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.85",
+  "version": "7.0.87",
   "description": "j-templates",
   "license": "MIT",
   "repository": "https://github.com/TypesInCode/jTemplates",