j-templates 7.0.104 → 8.0.0

package/Node/vNode.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.vNode = void 0;
 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");
@@ -152,8 +153,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);
 }
@@ -204,32 +207,18 @@ function ToArray(result) {
         return result;
     return [result];
 }
-function IsFragmentOrNull(vnode) {
-    return vnode === null || vnode.type === vNode_types_1.FRAGMENT_NODE;
-}
-function GetNode(vnode) {
-    return vnode.node;
-}
-function FlattenFragmentsRecursive(children, startIndex, result) {
-    for (let x = startIndex; x < children.length; x++) {
-        const vnode = children[x];
-        switch (vnode.type) {
-            case vNode_types_1.FRAGMENT_NODE:
-                FlattenFragmentsRecursive(vnode.children, 0, result);
-            default:
-                if (vnode.node !== null)
-                    result.push(vnode.node);
-        }
+function MapNode(vnode) {
+    switch (vnode.type) {
+        case vNode_types_1.FRAGMENT_NODE:
+            return vnode.children.flatMap(MapNode);
+        default:
+            return vnode.node;
     }
-    return result;
 }
 function CleanupChildrenArray(children) {
-    const index = children.findIndex(IsFragmentOrNull);
-    if (index < 0)
-        return children;
-    const result = children.slice(0, index).map(GetNode);
-    FlattenFragmentsRecursive(children, index, result);
-    return result;
+    const nodes = children.flatMap(MapNode);
+    (0, array_1.RemoveNulls)(nodes);
+    return nodes;
 }
 function UpdateChildren(vnode, init = false, skipInit = false) {
     if (!vnode.children)

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/_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,40 +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++) { }
-    }
-    array.splice(nullIndex);
-}
 function ArrayDiff(source, target) {
     if (source === target)
         return false;

package/package.json

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