j-templates 7.0.105 → 8.0.1

package/Node/component.d.ts

@@ -17,7 +17,7 @@ export declare class Component<D = void, T = void, E = {}> {
     /**
      * Returns the component's virtual node injector.
      */
-    get Injector(): import("../Utils/injector").Injector;
+    get Injector(): import("../Utils").Injector;
     /**
      * Indicates whether the component has been destroyed.
      */

package/Node/vNode.js

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.vNode = void 0;
-const array_1 = require("../_not_used/array");
 const Store_1 = require("../Store");
 const observableScope_1 = require("../Store/Tree/observableScope");
+const array_1 = require("../Utils/array");
 const emitter_1 = require("../Utils/emitter");
 const functions_1 = require("../Utils/functions");
 const injector_1 = require("../Utils/injector");
@@ -17,9 +17,7 @@ var vNode;
             definition,
             type: definition.type,
             injector: definition.componentFactory
-                ? injector_1.Injector.Scope(injector_1.Injector.Current(), function () {
-                    return new injector_1.Injector();
-                })
+                ? new injector_1.Injector()
                 : (injector_1.Injector.Current() ?? new injector_1.Injector()),
             parentNode: null,
             node: definition.node ?? null,
@@ -134,7 +132,7 @@ function InitNode(vnode, parentNode) {
             nodeConfig_1.NodeConfig.attributeAssignment(node, attrs);
     }
     if (componentFactory) {
-        vnode.component = componentFactory(vnode);
+        vnode.component = injector_1.Injector.Scope(vnode.injector, componentFactory, vnode);
         vnode.component.Bound();
         Children(vnode, ComponentChildren.bind(vnode.component));
     }
@@ -153,8 +151,10 @@ function Children(vnode, children, data) {
     Store_1.ObservableScope.Watch(childrenScope, CreateScheduledCallback(function (scope) {
         if (vnode.destroyed)
             return;
+        const oldChildrenLength = vnode.children.length;
         vnode.children = Store_1.ObservableScope.Value(scope);
-        UpdateChildren(vnode);
+        if (oldChildrenLength !== 0 || vnode.children.length !== 0)
+            UpdateChildren(vnode);
     }));
     vnode.children = Store_1.ObservableScope.Value(childrenScope);
 }

package/SYNTAX_PRIMER.md

@@ -594,7 +594,7 @@ Template() {
 
 > ⚠️ **Falsy edge case:** the falsy-collapse rule applies broadly — **`0`, `""`, and `NaN` also collapse to `[]`**, not just `false`/`null`/`undefined`. Only *truthy* non-array values are wrapped as `[value]`.
 
-**Also accepts** `Promise<T>` and `Promise<T[]>` for async data. While a Promise is pending, the scope evaluates to `null` (falsy), so the element renders nothing until resolved — there is no built-in placeholder; implement one yourself if needed.
+**Also accepts** `Promise<T>` and `Promise<T[]>` for async data. While a Promise is pending, the scope evaluates to `null` (falsy), so the element renders nothing until resolved — there is no built-in placeholder; implement one yourself if needed. While a newer promise is pending, the last resolved value is kept.
 
 The `false`/`true` behavior makes `data:` a clean conditional rendering mechanism. **The child function is invoked with the truthy value as its data argument** — e.g. `data: () => this.isLoading` calls the child with `true` when loading. It renders its child once when true and nothing when false, with its own isolated reactive scope.
 
@@ -979,6 +979,8 @@ get userData(): User | null { return getUserSync(this.Data.userId); }
 
 **Pattern 3 (@ComputedAsync):** Getter must be synchronous. Returns default value initially, then computed value with same reference via ApplyDiff.
 
+Shared async-scope behavior — typing, pending/old-value semantics, batching, and `scope()` composition — is covered in [Async Scopes](#async-scopes).
+
 ### State Location
 
 | State Type | Location | API |
@@ -995,6 +997,46 @@ get userData(): User | null { return getUserSync(this.Data.userId); }
 
 ---
 
+## Async Scopes
+
+Any function that supplies a scope value can be `async` — a `@Scope()` getter, a `props` or `data` function, or a `scope()`/`gate()`/`peek()`/`mapped()` callback. Services use the same mechanism through `ObservableScope.Create(async)` (see [Async Patterns](#async-patterns)).
+
+**Typing unwraps the resolved value.** The helper signatures declare `() => T | Promise<T>`, so TypeScript infers the resolved value, not the promise:
+
+```typescript
+scope(async () => (await fetch(url)).text());  // typed string, not Promise<string>
+```
+
+The same unwrap applies to config functions — `FunctionOr<T>` for `props`/`attrs`/`on`, and the `Promise<Array<T>> | Promise<T>` union for `data:`. **The `async` keyword is required:** `IsAsync` detects it via `Symbol.toStringTag`. A plain function that merely *returns* a promise (`() => fetch(url)`) is treated as a synchronous scope whose value is the promise itself — it is never resolved (see Traps #17).
+
+**Pending behavior.** An async scope renders nothing until its first result arrives: the initial value is `null`, so async `data:` collapses to no children and an async `props:` function applies nothing (the assignment closures skip null inputs). After the first result, the scope **keeps the last result while a new one is pending** — the value is replaced only when the promise resolves, and a resolution that arrives after a newer re-run has started is discarded.
+
+```typescript
+// Valid: nothing is applied to the element until the promise resolves.
+div({ props: async () => ({ innerHTML: await getMarkup() }) });
+```
+
+**Batching.** Async scopes are greedy — a dependency change marks the scope dirty and queues the re-run on the microtask queue (batched), instead of re-evaluating and propagating synchronously. This is the `greedy: true` behavior noted in Async Patterns.
+
+**Composition with `scope()`.** `scope()` can compose an async value inside a synchronous scope. The inner scope registers as a dependency of the enclosing watch context, so the **outer scope re-runs when the inner one resolves**:
+
+```typescript
+Template() {
+  return div({
+    props: () => ({
+      innerText: scope(async () => (await fetch(`/api/summary?open=${this.openCount}`)).text()),
+      className: "summary-container",
+    }),
+  });
+}
+```
+
+`scope()` must be called inside a watch context — a `@Scope()` getter, a children function, or a `props:`/`data:` function (see Traps #11).
+
+**Dependency capture.** Only reactive reads before the first `await` are tracked — reads after it happen outside the watch context and don't re-run the scope (see Traps #2). Read every reactive value the async scope depends on before the first `await`.
+
+---
+
 ## Scope Selection Decision Tree
 
 Need derived data?

package/Store/Tree/observableNode.js

@@ -374,7 +374,7 @@ var ObservableNode;
             // Replacing rootNode
             const rootPatch = diffResult[0].value;
             const rootType = (0, json_2.JsonType)(root);
-            const rootPatchType = (0, json_2.JsonType)(root);
+            const rootPatchType = (0, json_2.JsonType)(rootPatch);
             if (rootType !== rootPatchType)
                 throw new Error("Unable to change type of Root ObservableNode: " + rootType);
             switch (rootType) {

package/Utils/array.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Removes all null values from an array starting from a specified index.
+ * This function modifies the array in-place by shifting non-null elements
+ * to fill the gaps left by removed null values, then truncating the array.
+ *
+ * @param array - The array from which to remove null values. Can contain mixed types including null.
+ * @param startIndex - The index to start removing null values from (default: 0).
+ *
+ * @example
+ * ```typescript
+ * const arr = [1, null, 2, null, 3, null, 4];
+ * RemoveNulls(arr); // Removes all null values, result: [1, 2, 3, 4]
+ *
+ * const arr2 = [null, null, 1, null, 2];
+ * RemoveNulls(arr2, 2); // Starts from index 2, result: [null, null, 1, 2]
+ * ```
+ */
+export declare function RemoveNulls(array: (unknown | null)[], startIndex?: number): void;

package/Utils/array.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemoveNulls = RemoveNulls;
+/**
+ * Removes all null values from an array starting from a specified index.
+ * This function modifies the array in-place by shifting non-null elements
+ * to fill the gaps left by removed null values, then truncating the array.
+ *
+ * @param array - The array from which to remove null values. Can contain mixed types including null.
+ * @param startIndex - The index to start removing null values from (default: 0).
+ *
+ * @example
+ * ```typescript
+ * const arr = [1, null, 2, null, 3, null, 4];
+ * RemoveNulls(arr); // Removes all null values, result: [1, 2, 3, 4]
+ *
+ * const arr2 = [null, null, 1, null, 2];
+ * RemoveNulls(arr2, 2); // Starts from index 2, result: [null, null, 1, 2]
+ * ```
+ */
+function RemoveNulls(array, startIndex = 0) {
+    let nullIndex = startIndex;
+    for (; nullIndex < array.length && array[nullIndex] !== null; nullIndex++) { }
+    let notNullIndex = nullIndex + 1;
+    for (; notNullIndex < array.length && array[notNullIndex] === null; notNullIndex++) { }
+    while (notNullIndex < array.length) {
+        array[nullIndex] = array[notNullIndex];
+        nullIndex++;
+        notNullIndex++;
+        for (; notNullIndex < array.length && array[notNullIndex] === null; notNullIndex++) { }
+    }
+    if (nullIndex < array.length)
+        array.splice(nullIndex);
+}

package/Utils/decorators.d.ts

@@ -88,7 +88,7 @@ import { Injector } from "./injector";
  * @Value()
  * lastName: string = "Doe";
  *
- * @Computed()  // Overhead: creates StoreSync, watch cycle, diff computation
+ * @Computed()  // Overhead: observable node, watch cycle, diff computation
  * get fullName(): string {
  *   return this.firstName + " " + this.lastName;  // Cheap string concat
  * }
@@ -99,15 +99,18 @@ import { Injector } from "./injector";
  * }
  * ```
  *
- * @param defaultValue The default value to be used if the computed property is not defined.
  * @returns A property decorator that can be applied to a getter method.
  * @throws Will throw an error if the property is not a getter or if it has a setter.
  * @remarks
- * The @Computed decorator uses a two-phase caching system with diff-based updates:
- * 1. Getter scope: Computes value and writes to StoreSync when dependencies change
- * 2. StoreSync: Computes diff between old and new values
- * 3. ObservableNode.ApplyDiff: Updates the EXISTING object with only changed properties
- * 4. Property scope: Reads the updated (but same reference) value from StoreSync
+ * 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.
+ * 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.
  *
  * **Initialization**: @Computed uses lazy initialization - the scopes are created on first access:
  * ```typescript
@@ -152,8 +155,9 @@ import { Injector } from "./injector";
  * - The diff computation overhead is justified when you need object reuse
  * @see {@link Scope} for simple getter-based reactive properties (caches but new reference)
  * @see {@link ComputedAsync} for async computed properties
- * @see {@link ObservableNode.ApplyDiff} for how diffs are applied to maintain object identity
- * @see {@link StoreSync} for sync store implementation
+ * @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 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;
 /**

package/Utils/decorators.js

@@ -133,7 +133,7 @@ function GetDestroyArrayForPrototype(prototype, create = true) {
     }
     return array;
 }
-function CreateComputedScope(getter, store, defaultValue) {
+function CreateStoreScope(getter, store, defaultValue) {
     const getterScope = observableScope_1.ObservableScope.Gated(function () {
         const value = getter();
         return observableNode_1.ObservableNode.Clone(value);
@@ -154,6 +154,31 @@ function CreateComputedScope(getter, store, defaultValue) {
     });
     return propertyScope;
 }
+/**
+ * Creates a Gated 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:
+ * - Content changes (same structure, changed properties) fire only the affected
+ *   per-property scopes - the top-level 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.
+ *
+ * @param getter Function computing the value. May read reactive dependencies.
+ * @returns The Gated scope whose value is the observable root node.
+ */
+function CreateNodeScope(getter) {
+    const observableNode = observableNode_1.ObservableNode.Create({ root: null });
+    const getterScope = observableScope_1.ObservableScope.Gated(function () {
+        const value = getter();
+        const clonedValue = observableNode_1.ObservableNode.Clone(value);
+        observableNode_1.ObservableNode.Apply(observableNode, { root: clonedValue });
+        return observableNode.root;
+    });
+    return getterScope;
+}
 /**
  * Computed decorator factory for creating synchronous computed properties with caching and object reuse.
  * A computed property is derived from other properties and automatically updates when its dependencies change.
@@ -184,7 +209,7 @@ function CreateComputedScope(getter, store, defaultValue) {
  * @Value()
  * lastName: string = "Doe";
  *
- * @Computed()  // Overhead: creates StoreSync, watch cycle, diff computation
+ * @Computed()  // Overhead: observable node, watch cycle, diff computation
  * get fullName(): string {
  *   return this.firstName + " " + this.lastName;  // Cheap string concat
  * }
@@ -195,15 +220,18 @@ function CreateComputedScope(getter, store, defaultValue) {
  * }
  * ```
  *
- * @param defaultValue The default value to be used if the computed property is not defined.
  * @returns A property decorator that can be applied to a getter method.
  * @throws Will throw an error if the property is not a getter or if it has a setter.
  * @remarks
- * The @Computed decorator uses a two-phase caching system with diff-based updates:
- * 1. Getter scope: Computes value and writes to StoreSync when dependencies change
- * 2. StoreSync: Computes diff between old and new values
- * 3. ObservableNode.ApplyDiff: Updates the EXISTING object with only changed properties
- * 4. Property scope: Reads the updated (but same reference) value from StoreSync
+ * 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.
+ * 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.
  *
  * **Initialization**: @Computed uses lazy initialization - the scopes are created on first access:
  * ```typescript
@@ -248,8 +276,9 @@ function CreateComputedScope(getter, store, defaultValue) {
  * - The diff computation overhead is justified when you need object reuse
  * @see {@link Scope} for simple getter-based reactive properties (caches but new reference)
  * @see {@link ComputedAsync} for async computed properties
- * @see {@link ObservableNode.ApplyDiff} for how diffs are applied to maintain object identity
- * @see {@link StoreSync} for sync store implementation
+ * @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 StoreSync} for the store-backed variant used by @ComputedAsync
  */
 function Computed() {
     return function (target, propertyKey, descriptor) {
@@ -262,7 +291,6 @@ function Computed() {
  * @param target The target object.
  * @param prop The property key.
  * @param descriptor The property descriptor.
- * @param defaultValue The default value to be used if the computed property is not defined.
  * @returns A property descriptor that replaces the original descriptor with a computed implementation.
  * @throws Will throw an error if the property is not a getter or if it has a setter.
  */
@@ -279,7 +307,7 @@ function ComputedDecorator(target, prop, descriptor) {
         get: function () {
             const scopeMap = GetScopeMapForInstance(this);
             if (scopeMap[propertyKey] === undefined) {
-                const propertyScope = CreateComputedScope(getter.bind(this), new Store_1.StoreSync());
+                const propertyScope = CreateNodeScope(getter.bind(this));
                 scopeMap[propertyKey] = [propertyScope, undefined];
             }
             return observableScope_1.ObservableScope.Value(scopeMap[propertyKey][0]);
@@ -405,7 +433,7 @@ function ComputedAsyncDecorator(target, prop, descriptor, defaultValue) {
         get: function () {
             const scopeMap = GetScopeMapForInstance(this);
             if (scopeMap[propertyKey] === undefined) {
-                const propertyScope = CreateComputedScope(getter.bind(this), new Store_1.StoreAsync(), defaultValue);
+                const propertyScope = CreateStoreScope(getter.bind(this), new Store_1.StoreAsync(), defaultValue);
                 scopeMap[propertyKey] = [propertyScope, undefined];
             }
             return observableScope_1.ObservableScope.Value(scopeMap[propertyKey][0]);

package/Utils/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./decorators";
 export * from "./animation";
+export { Injector } from "./injector";
 export { IDestroyable } from "./utils.types";

package/Utils/index.js

@@ -14,5 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Injector = void 0;
 __exportStar(require("./decorators"), exports);
 __exportStar(require("./animation"), exports);
+var injector_1 = require("./injector");
+Object.defineProperty(exports, "Injector", { enumerable: true, get: function () { return injector_1.Injector; } });

package/_not_used/array.d.ts

@@ -1,21 +1,3 @@
-/**
- * Removes all null values from an array starting from a specified index.
- * This function modifies the array in-place by shifting non-null elements
- * to fill the gaps left by removed null values, then truncating the array.
- *
- * @param array - The array from which to remove null values. Can contain mixed types including null.
- * @param startIndex - The index to start removing null values from (default: 0).
- *
- * @example
- * ```typescript
- * const arr = [1, null, 2, null, 3, null, 4];
- * RemoveNulls(arr); // Removes all null values, result: [1, 2, 3, 4]
- *
- * const arr2 = [null, null, 1, null, 2];
- * RemoveNulls(arr2, 2); // Starts from index 2, result: [null, null, 1, 2]
- * ```
- */
-export declare function RemoveNulls(array: (unknown | null)[], startIndex?: number): void;
 export declare function ArrayDiff(source: any[], target: any[]): boolean;
 /**
  * Reconciles two sorted arrays by applying add and remove operations to transition

package/_not_used/array.js

@@ -1,41 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RemoveNulls = RemoveNulls;
 exports.ArrayDiff = ArrayDiff;
 exports.ReconcileSortedEmitters = ReconcileSortedEmitters;
 exports.InsertionSortTuples = InsertionSortTuples;
 exports.ReconcileSortedArrays = ReconcileSortedArrays;
-/**
- * Removes all null values from an array starting from a specified index.
- * This function modifies the array in-place by shifting non-null elements
- * to fill the gaps left by removed null values, then truncating the array.
- *
- * @param array - The array from which to remove null values. Can contain mixed types including null.
- * @param startIndex - The index to start removing null values from (default: 0).
- *
- * @example
- * ```typescript
- * const arr = [1, null, 2, null, 3, null, 4];
- * RemoveNulls(arr); // Removes all null values, result: [1, 2, 3, 4]
- *
- * const arr2 = [null, null, 1, null, 2];
- * RemoveNulls(arr2, 2); // Starts from index 2, result: [null, null, 1, 2]
- * ```
- */
-function RemoveNulls(array, startIndex = 0) {
-    let nullIndex = startIndex;
-    for (; nullIndex < array.length && array[nullIndex] !== null; nullIndex++) { }
-    let notNullIndex = nullIndex + 1;
-    for (; notNullIndex < array.length && array[notNullIndex] === null; notNullIndex++) { }
-    while (notNullIndex < array.length) {
-        array[nullIndex] = array[notNullIndex];
-        nullIndex++;
-        notNullIndex++;
-        for (; notNullIndex < array.length && array[notNullIndex] === null; notNullIndex++) { }
-    }
-    if (nullIndex < array.length)
-        array.splice(nullIndex);
-}
 function ArrayDiff(source, target) {
     if (source === target)
         return false;

package/index.d.ts

@@ -1,2 +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 { vNode } from './Node/vNode.types';

package/package.json

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