j-templates 7.0.70 → 7.0.71

package/Store/Tree/observableNode.d.ts

@@ -1,12 +1,56 @@
 import { JsonDiffResult } from "../../Utils/json";
-export declare const IS_OBSERVABLE_NODE = "____isObservableNode";
-export declare const GET_OBSERVABLE_VALUE = "____getObservableValue";
-export declare const GET_TO_JSON = "toJSON";
+/**
+ * Symbol to identify observable nodes.
+ * Used to check if a value is an observable node proxy.
+ */
+export declare const IS_OBSERVABLE_NODE: unique symbol;
+/**
+ * Symbol to get the raw underlying value from an observable node.
+ * Returns the unwrapped, non-proxied value.
+ */
+export declare const GET_OBSERVABLE_VALUE: unique symbol;
+/**
+ * Symbol for the toJSON method on observable nodes.
+ * Used to serialize observable nodes to plain JSON.
+ */
+export declare const GET_TO_JSON: unique symbol;
 export declare namespace ObservableNode {
-    function BypassProxy(value: boolean): void;
+    /**
+     * Unwraps an observable node to get the raw underlying value.
+     * Recursively unwraps nested objects and arrays.
+     * @template T The type of value to unwrap.
+     * @param value The value to unwrap, which may be an observable node or plain value.
+     * @returns The unwrapped raw value without proxy wrappers.
+     */
     function Unwrap<T>(value: T): T;
+    /**
+     * Creates an observable node from a plain value.
+     * Wraps the value in a proxy that tracks changes and enables reactive updates.
+     * @template T The type of value to wrap.
+     * @param value The plain value (object, array, or primitive) to make observable.
+     * @returns A proxied version of the value that emits change events.
+     */
     function Create<T>(value: T): T;
+    /**
+     * Marks an observable node or its property as changed, triggering reactive updates.
+     * Used internally to notify dependencies that a value has been modified.
+     * @param value The observable node to touch.
+     * @param prop Optional property name or index to touch a specific nested property.
+     */
     function Touch(value: unknown, prop?: string | number): void;
+    /**
+     * Applies a JSON diff result to an observable node, efficiently updating only changed properties.
+     * Optimizes nested object updates by computing paths incrementally and touching modified properties.
+     * @param rootNode The observable node to apply the diff to.
+     * @param diffResult The diff result from JsonDiff containing path-value pairs of changes.
+     */
     function ApplyDiff(rootNode: any, diffResult: JsonDiffResult): void;
+    /**
+     * Creates a factory function for making values observable with optional aliasing.
+     * The alias function transforms values before creating the observable proxy,
+     * useful for read-only views or value transformations.
+     * @param alias Optional function to transform values before making them observable.
+     * @returns A function that creates observable nodes from plain values.
+     */
     function CreateFactory(alias?: (value: any) => any | undefined): <T>(value: T) => T;
 }

package/Store/Tree/observableNode.js

@@ -4,10 +4,21 @@ exports.ObservableNode = exports.GET_TO_JSON = exports.GET_OBSERVABLE_VALUE = ex
 const json_1 = require("../../Utils/json");
 const jsonType_1 = require("../../Utils/jsonType");
 const observableScope_1 = require("./observableScope");
-let bypassProxy = false;
-exports.IS_OBSERVABLE_NODE = "____isObservableNode";
-exports.GET_OBSERVABLE_VALUE = "____getObservableValue";
-exports.GET_TO_JSON = "toJSON";
+/**
+ * Symbol to identify observable nodes.
+ * Used to check if a value is an observable node proxy.
+ */
+exports.IS_OBSERVABLE_NODE = Symbol("isObservableNode");
+/**
+ * Symbol to get the raw underlying value from an observable node.
+ * Returns the unwrapped, non-proxied value.
+ */
+exports.GET_OBSERVABLE_VALUE = Symbol("getObservableValue");
+/**
+ * Symbol for the toJSON method on observable nodes.
+ * Used to serialize observable nodes to plain JSON.
+ */
+exports.GET_TO_JSON = Symbol("toJSON");
 const proxyCache = new WeakMap();
 const scopeCache = new WeakMap();
 const leafScopeCache = new WeakMap();
@@ -40,7 +51,7 @@ function ownKeysArray(value) {
 function UnwrapProxy(value, type = (0, jsonType_1.JsonType)(value)) {
     if (type === "value")
         return value;
-    if (value[exports.IS_OBSERVABLE_NODE] === true)
+    if (value[exports.IS_OBSERVABLE_NODE])
         return value[exports.GET_OBSERVABLE_VALUE];
     switch (type) {
         case "object": {
@@ -114,8 +125,6 @@ function CreateProxyFactory(alias) {
     function ArrayProxySetter(array, prop, value) {
         if (readOnly)
             throw `Object is readonly`;
-        if (prop === exports.IS_OBSERVABLE_NODE)
-            throw `Cannot assign read-only property: ${exports.IS_OBSERVABLE_NODE}`;
         value = UnwrapProxy(value);
         array[prop] = value;
         const scope = scopeCache.get(array);
@@ -147,8 +156,6 @@ function CreateProxyFactory(alias) {
                 const scope = scopeCache.get(array);
                 array = observableScope_1.ObservableScope.Value(scope);
                 const arrayValue = array[prop];
-                if (bypassProxy)
-                    return arrayValue;
                 if (typeof prop === "symbol")
                     return arrayValue;
                 if (typeof arrayValue === "function")
@@ -188,8 +195,6 @@ function CreateProxyFactory(alias) {
     function ObjectProxySetter(object, prop, value) {
         if (readOnly)
             throw `Object is readonly`;
-        if (prop === exports.IS_OBSERVABLE_NODE)
-            throw `Cannot assign read-only property: ${exports.IS_OBSERVABLE_NODE}`;
         const jsonType = (0, jsonType_1.JsonType)(value);
         if (jsonType === "value") {
             value !== object[prop] && SetPropertyValue(object, prop, value);
@@ -224,8 +229,6 @@ function CreateProxyFactory(alias) {
             case exports.GET_OBSERVABLE_VALUE:
                 return object;
             default: {
-                if (bypassProxy)
-                    return object[prop];
                 return GetAccessorValue(object, prop);
             }
         }
@@ -264,18 +267,34 @@ function CreateProxyFactory(alias) {
 const DefaultCreateProxy = CreateProxyFactory();
 var ObservableNode;
 (function (ObservableNode) {
-    function BypassProxy(value) {
-        bypassProxy = value;
-    }
-    ObservableNode.BypassProxy = BypassProxy;
+    /**
+     * Unwraps an observable node to get the raw underlying value.
+     * Recursively unwraps nested objects and arrays.
+     * @template T The type of value to unwrap.
+     * @param value The value to unwrap, which may be an observable node or plain value.
+     * @returns The unwrapped raw value without proxy wrappers.
+     */
     function Unwrap(value) {
         return UnwrapProxy(value);
     }
     ObservableNode.Unwrap = Unwrap;
+    /**
+     * Creates an observable node from a plain value.
+     * Wraps the value in a proxy that tracks changes and enables reactive updates.
+     * @template T The type of value to wrap.
+     * @param value The plain value (object, array, or primitive) to make observable.
+     * @returns A proxied version of the value that emits change events.
+     */
     function Create(value) {
         return DefaultCreateProxy(value);
     }
     ObservableNode.Create = Create;
+    /**
+     * Marks an observable node or its property as changed, triggering reactive updates.
+     * Used internally to notify dependencies that a value has been modified.
+     * @param value The observable node to touch.
+     * @param prop Optional property name or index to touch a specific nested property.
+     */
     function Touch(value, prop) {
         let scope;
         if (prop !== undefined) {
@@ -286,6 +305,12 @@ var ObservableNode;
         observableScope_1.ObservableScope.Update(scope);
     }
     ObservableNode.Touch = Touch;
+    /**
+     * Applies a JSON diff result to an observable node, efficiently updating only changed properties.
+     * Optimizes nested object updates by computing paths incrementally and touching modified properties.
+     * @param rootNode The observable node to apply the diff to.
+     * @param diffResult The diff result from JsonDiff containing path-value pairs of changes.
+     */
     function ApplyDiff(rootNode, diffResult) {
         const root = rootNode[exports.GET_OBSERVABLE_VALUE];
         const pathTuples = [["", root]];
@@ -312,6 +337,13 @@ var ObservableNode;
         }
     }
     ObservableNode.ApplyDiff = ApplyDiff;
+    /**
+     * Creates a factory function for making values observable with optional aliasing.
+     * The alias function transforms values before creating the observable proxy,
+     * useful for read-only views or value transformations.
+     * @param alias Optional function to transform values before making them observable.
+     * @returns A function that creates observable nodes from plain values.
+     */
     function CreateFactory(alias) {
         return CreateProxyFactory(alias);
     }

package/Store/Tree/observableScope.js

@@ -48,6 +48,10 @@ function CreateStaticScope(initialValue) {
     };
 }
 let scopeQueue = [];
+/**
+ * Processes all queued scopes, recomputing dirty scopes and emitting changes.
+ * Executed as a microtask to batch updates efficiently.
+ */
 function ProcessScopeQueue() {
     const queue = scopeQueue;
     scopeQueue = [];
@@ -61,6 +65,11 @@ function ProcessScopeQueue() {
         }
     }
 }
+/**
+ * Queues a scope for batched update processing.
+ * Schedules ProcessScopeQueue as a microtask if the queue was empty.
+ * @param scope The scope to queue for update.
+ */
 function OnSetQueued(scope) {
     if (scopeQueue.length === 0)
         queueMicrotask(ProcessScopeQueue);
@@ -84,6 +93,13 @@ function OnSet(scope) {
     emitter_1.Emitter.Emit(scope.emitter, scope);
     return false;
 }
+/**
+ * Registers an emitter using SAME_STRATEGY.
+ * If the emitter is already registered at the current index, increments the index.
+ * Otherwise, switches to PUSH_STRATEGY and appends the emitter.
+ * @param state The current watch state.
+ * @param emitter The emitter to register.
+ */
 function RegisterSame(state, emitter) {
     if (state.emitterIndex < state.emitters.length &&
         state.emitters[state.emitterIndex] === emitter) {
@@ -91,10 +107,30 @@ function RegisterSame(state, emitter) {
         return;
     }
     state.emitters = state.emitters.slice(0, state.emitterIndex);
-    state.emitters.push(emitter);
-    state.emitterIndex = -1;
-    state.strategy = PUSH_STRATEGY;
+    state.strategy = SORTED_STRATEGY;
+    RegisterSorted(state, emitter);
 }
+/**
+ * Registers an emitter while maintaining sorted order by emitter ID.
+ * If insertion would break sort order, falls back to PUSH_STRATEGY.
+ * @param state The current watch state.
+ * @param emitter The emitter to register.
+ */
+function RegisterSorted(state, emitter) {
+    if (state.emitters.length === 0 ||
+        state.emitters[state.emitters.length - 1][0] < emitter[0])
+        state.emitters.push(emitter);
+    else {
+        state.strategy = PUSH_STRATEGY;
+        RegisterPush(state, emitter);
+    }
+}
+/**
+ * Registers an emitter using PUSH_STRATEGY.
+ * Switches to DISTINCT_STRATEGY when the emitter count exceeds 50 to optimize memory.
+ * @param state The current watch state.
+ * @param emitter The emitter to register.
+ */
 function RegisterPush(state, emitter) {
     state.emitters.push(emitter);
     if (state.emitters.length > 50) {
@@ -112,12 +148,23 @@ function RegisterPush(state, emitter) {
         state.strategy = DISTINCT_STRATEGY;
     }
 }
+/**
+ * Registers an emitter using DISTINCT_STRATEGY.
+ * Only adds emitters that haven't been registered yet, using an ID set for O(1) lookup.
+ * @param state The current watch state.
+ * @param emitter The emitter to register.
+ */
 function RegisterDistinct(state, emitter) {
     if (!state.emitterIds.has(emitter[0])) {
         state.emitters.push(emitter);
         state.emitterIds.add(emitter[0]);
     }
 }
+/**
+ * Routes an emitter to the appropriate registration strategy based on current watch state.
+ * Does nothing if not within a watch context.
+ * @param emitter The emitter to register.
+ */
 function RegisterEmitter(emitter) {
     if (watchState === null)
         return;
@@ -125,6 +172,9 @@ function RegisterEmitter(emitter) {
         case SAME_STRATEGY:
             RegisterSame(watchState, emitter);
             break;
+        case SORTED_STRATEGY:
+            RegisterSorted(watchState, emitter);
+            break;
         case PUSH_STRATEGY:
             RegisterPush(watchState, emitter);
             break;
@@ -154,12 +204,22 @@ function GetScopeValue(scope) {
     ExecuteScope(scope);
     return scope.value;
 }
+/**
+ * Strategy constants for optimizing emitter registration during watch operations.
+ * Each strategy represents a different approach to tracking and deduplicating dependencies.
+ */
 const SAME_STRATEGY = 1;
 const PUSH_STRATEGY = 2;
-const DISTINCT_STRATEGY = 3;
-const SHRINK_STRATEGY = 4;
+const SORTED_STRATEGY = 3;
+const DISTINCT_STRATEGY = 4;
+const SHRINK_STRATEGY = 5;
 let watchState = null;
 const watchPool = list_1.List.Create();
+/**
+ * Creates a new watch state object, reusing from pool if available.
+ * Object pooling reduces GC pressure during frequent watch operations.
+ * @returns A new or recycled watch state object.
+ */
 function CreateWatchState() {
     return (list_1.List.Pop(watchPool) ?? {
         emitterIndex: 0,
@@ -171,6 +231,11 @@ function CreateWatchState() {
         strategy: PUSH_STRATEGY,
     });
 }
+/**
+ * Returns a watch state object to the pool for reuse.
+ * Resets all fields to their default values before pooling.
+ * @param state The watch state to return to the pool.
+ */
 function ReturnWatchState(state) {
     state.emitterIndex = 0;
     state.value = null;
@@ -178,7 +243,7 @@ function ReturnWatchState(state) {
     state.emitterIds = null;
     state.currentCalc = null;
     state.nextCalc = null;
-    state.strategy = PUSH_STRATEGY;
+    state.strategy = SORTED_STRATEGY;
     list_1.List.Push(watchPool, state);
 }
 /**
@@ -304,6 +369,7 @@ function UpdateEmitters(scope, right, strategy) {
             strategy === PUSH_STRATEGY
                 ? emitter_1.Emitter.Distinct(right)
                 : emitter_1.Emitter.Sort(right);
+        case SORTED_STRATEGY:
             if (scope.emitters === null || scope.emitters.length === 0) {
                 for (let x = 0; x < right.length; x++)
                     emitter_1.Emitter.On(right[x], scope.setCallback);

package/package.json

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