@mintjamsinc/ichigojs 0.1.69 → 0.1.71

package/dist/ichigo.esm.js

@@ -8393,6 +8393,31 @@ class VBindings {
      * is replaced, the binding is set to null/undefined, or the bindings are destroyed.
      */
     #externalSubscriptions = new Map();
+    /**
+     * Recompute callbacks for computed properties registered on these bindings.
+     * Maps a computed property name to a function that recomputes and caches its value.
+     * Only the bindings instance that owns the computed (typically the root) holds an entry;
+     * child bindings resolve computed reads by delegating to their parent through the proxy.
+     */
+    #computedRecomputers = new Map();
+    /**
+     * The set of computed properties whose cached value is stale and must be recomputed on next
+     * access (pull-based evaluation). Populated by markComputedDirty when a dependency changes,
+     * and cleared as each computed is resolved.
+     */
+    #dirtyComputeds = new Set();
+    /**
+     * Guard set used to detect re-entrant (circular) computed resolution. While a computed is
+     * being recomputed its name is held here; a nested read of the same computed returns the
+     * currently cached (stale) value instead of recursing infinitely.
+     */
+    #resolvingComputeds = new Set();
+    /**
+     * The plain backing object behind the #local proxy. Kept as a direct reference so the cached
+     * value of a computed property can be read without triggering pull-based re-evaluation
+     * (see peekComputed).
+     */
+    #store = {};
     /**
      * Creates a new instance of VBindings.
      * @param parent The parent bindings, if any.
@@ -8404,8 +8429,13 @@ class VBindings {
         if (this.#logger?.isDebugEnabled) {
             this.#logger.debug(`VBindings created. Parent: ${this.#parent ? 'yes' : 'no'}`);
         }
-        this.#local = new Proxy({}, {
+        this.#local = new Proxy(this.#store, {
             get: (obj, key) => {
+                // Pull-based evaluation: if this key is a dirty computed property, recompute it now
+                // so the read returns a fresh value (synchronously, even before the update microtask).
+                if (typeof key === 'string') {
+                    this.#resolveComputedIfDirty(key);
+                }
                 if (Reflect.has(obj, key)) {
                     return Reflect.get(obj, key);
                 }
@@ -8663,6 +8693,79 @@ class VBindings {
     registerWritableComputed(key, setter) {
         this.#writableComputeds.set(key, setter);
     }
+    /**
+     * Registers a computed property for pull-based (lazy) evaluation. The provided recompute
+     * callback is invoked the first time the property is read after it has been marked dirty
+     * (or during the pre-render flush), and is expected to update the cached value (typically
+     * via setSilent).
+     * @param key The computed property name.
+     * @param recompute The callback that recomputes and caches the property's value.
+     */
+    registerComputed(key, recompute) {
+        this.#computedRecomputers.set(key, recompute);
+    }
+    /**
+     * Marks a computed property as dirty so it will be recomputed on next access.
+     * @param key The computed property name.
+     */
+    markComputedDirty(key) {
+        this.#dirtyComputeds.add(key);
+    }
+    /**
+     * Reads the currently cached value of a computed property without triggering pull-based
+     * re-evaluation. Used by the recompute routine to obtain the previous value for change
+     * detection. Falls back to the parent bindings when the key is not stored locally.
+     * @param key The computed property name.
+     * @returns The cached value, or undefined if not cached.
+     */
+    peekComputed(key) {
+        if (Object.prototype.hasOwnProperty.call(this.#store, key)) {
+            return this.#store[key];
+        }
+        return this.#parent?.peekComputed(key);
+    }
+    /**
+     * Forces resolution of every computed property currently marked dirty. Called before the DOM
+     * diff and watcher notification so that the set of changed identifiers is complete.
+     */
+    flushDirtyComputeds() {
+        for (const key of [...this.#dirtyComputeds]) {
+            this.#resolveComputedIfDirty(key);
+        }
+    }
+    /**
+     * Resolves a computed property if its cached value is dirty (pull-based evaluation), by
+     * invoking its registered recompute callback. Computed→computed chains resolve naturally:
+     * reading another computed inside the getter re-enters this method for that key. Re-entrant
+     * resolution of the same key (a circular dependency) is detected and short-circuited, leaving
+     * the previously cached value in place.
+     * @param key The property name to resolve.
+     */
+    #resolveComputedIfDirty(key) {
+        const recompute = this.#computedRecomputers.get(key);
+        if (!recompute) {
+            // Not a computed owned by these bindings; a parent (if any) resolves it when the value
+            // is read through the proxy delegation in the get trap.
+            return;
+        }
+        if (!this.#dirtyComputeds.has(key)) {
+            return;
+        }
+        if (this.#resolvingComputeds.has(key)) {
+            this.#logger?.warn(`Circular dependency detected while resolving computed property '${key}'.`);
+            return;
+        }
+        this.#resolvingComputeds.add(key);
+        try {
+            // Clear the dirty flag before recomputing so reads of this same key during recomputation
+            // (other than a true cycle) do not attempt to resolve it again.
+            this.#dirtyComputeds.delete(key);
+            recompute();
+        }
+        finally {
+            this.#resolvingComputeds.delete(key);
+        }
+    }
     /**
      * Manually adds an identifier to the set of changed identifiers.
      * This is useful for computed properties that need to mark themselves as changed
@@ -13648,7 +13751,8 @@ class VApplication {
         this.#logManager = new VLogManager(options.logLevel);
         this.#logger = this.#logManager.getLogger('VApplication');
         // Analyze function dependencies
-        this.#functionDependencies = ExpressionUtils.analyzeFunctionDependencies(options.methods || {});
+        const methods = (options.methods || {});
+        this.#functionDependencies = ExpressionUtils.analyzeFunctionDependencies(methods);
         // Analyze computed dependencies based on getter functions only.
         // Writable computeds (defined as { get, set }) contribute their getter for dependency analysis.
         const computedGetters = {};
@@ -13657,7 +13761,23 @@ class VApplication {
                 computedGetters[key] = VApplication.#getComputedGetter(def);
             }
         }
-        this.#computedDependencies = ExpressionUtils.analyzeFunctionDependencies(computedGetters);
+        // Resolve computed dependencies against BOTH the computed getters AND the methods, so a
+        // computed that delegates to a method inherits that method's reactive dependencies. A
+        // computed whose only reactive reads happen inside a called method (e.g. a reactive i18n
+        // `t()` helper that reads `this.localization`) would otherwise never be invalidated, leaving
+        // its binding stale on a dependency change. Analyzing the combined set flattens every
+        // computed→method (and computed→computed, method→method) edge down to the underlying
+        // reactive paths — the same expansion that template-expression analysis already performs for
+        // method calls (see ExpressionUtils.extractIdentifiers). We then keep only the computed
+        // entries, since #computedDependencies must be keyed by computed name alone.
+        const combinedDependencies = ExpressionUtils.analyzeFunctionDependencies({
+            ...methods,
+            ...computedGetters,
+        });
+        this.#computedDependencies = {};
+        for (const key of Object.keys(computedGetters)) {
+            this.#computedDependencies[key] = combinedDependencies[key] || [];
+        }
         // Initialize watcher manager
         this.#watcher = new VWatcher(this.#logger);
         // Initialize bindings from data, computed, and methods
@@ -13848,7 +13968,11 @@ class VApplication {
     #initializeBindings() {
         // Create bindings with change tracking
         this.#bindings = new VBindings({
-            onChange: () => {
+            onChange: (identifier) => {
+                // Pull-based invalidation: mark dependent computed properties dirty synchronously
+                // so a subsequent synchronous read returns a fresh value, then schedule the
+                // batched DOM update for the next microtask.
+                this.#markDirtyComputeds(identifier);
                 this.#scheduleUpdate();
             },
             vApplication: this
@@ -13898,8 +14022,17 @@ class VApplication {
                 }
             }
         }
-        // Add computed properties (initialization mode)
-        this.#recomputeProperties(true);
+        // Register computed properties for pull-based (lazy) evaluation. Each computed is
+        // recomputed on first access after being marked dirty, rather than eagerly in the update
+        // microtask. We mark them all dirty and resolve once here so that initial values are
+        // cached and recorded as changes for the first render.
+        if (this.#options.computed) {
+            for (const key of Object.keys(this.#options.computed)) {
+                this.#bindings.registerComputed(key, () => this.#recomputeOne(key));
+                this.#bindings.markComputedDirty(key);
+            }
+        }
+        this.#flushDirtyComputeds();
     }
     /**
      * Initializes watchers from the watch option.
@@ -13950,8 +14083,9 @@ class VApplication {
      * Executes an immediate DOM update.
      */
     #update() {
-        // Re-evaluate computed properties that depend on changed values
-        this.#recomputeProperties();
+        // Resolve any computed properties still marked dirty (those not already pulled by a
+        // synchronous read) so that the set of changed identifiers is complete before the DOM diff.
+        this.#flushDirtyComputeds();
         // Apply computed source path mappings to changes
         // This converts paths like "model.elements[0].executionListeners"
         // to "selectedElement.executionListeners" when selectedElement points to model.elements[0]
@@ -13996,110 +14130,116 @@ class VApplication {
         }
     }
     /**
-     * Recursively recomputes computed properties based on changed identifiers.
-     * @param isInitialization - If true, computes all computed properties regardless of dependencies
+     * Marks computed properties as dirty (pull-based invalidation) when a dependency changes.
+     * Uses the statically analyzed dependency graph; because computed→computed and computed→method
+     * dependencies are flattened to their underlying reactive paths during analysis, a single change
+     * marks every transitively dependent computed dirty in one pass. The actual recomputation is
+     * deferred until the value is read (see #recomputeOne).
+     * @param identifier The changed identifier reported by the bindings change tracker.
      */
-    #recomputeProperties(isInitialization = false) {
-        if (!this.#options.computed) {
+    #markDirtyComputeds(identifier) {
+        if (!this.#options.computed || !this.#bindings) {
             return;
         }
-        const computed = new Set();
-        const processing = new Set();
-        // Gather all changed identifiers, including all parent paths
-        // e.g., for "model.elements[0].messageRef", also add:
-        // "model.elements[0]", "model.elements", "model"
-        const allChanges = new Set();
-        this.#bindings?.changes.forEach(id => {
-            allChanges.add(id);
-            // Add all parent paths by progressively stripping from the end
-            let path = id;
-            while (path.length > 0) {
-                // Find last separator (either '[' or '.')
-                const bracketIdx = path.lastIndexOf('[');
-                const dotIdx = path.lastIndexOf('.');
-                const lastSep = Math.max(bracketIdx, dotIdx);
-                if (lastSep === -1) {
-                    break;
-                }
-                path = path.substring(0, lastSep);
-                if (path.length > 0) {
-                    allChanges.add(path);
-                }
-            }
-        });
-        // Helper function to recursively compute a property
-        const compute = (key) => {
-            // Skip if already computed in this update cycle
-            if (computed.has(key)) {
-                return;
-            }
-            // Detect circular dependency
-            if (processing.has(key)) {
-                this.#logger.error(`Circular dependency detected for computed property '${key}'`);
-                return;
-            }
-            processing.add(key);
-            // Get the dependencies for this computed property
+        for (const key of Object.keys(this.#computedDependencies)) {
             const deps = this.#computedDependencies[key] || [];
-            // First, recursively compute any dependent computed properties.
-            // This must happen before the change check so that computed→computed
-            // dependency chains are resolved and allChanges is up-to-date.
-            for (const dep of deps) {
-                if (this.#options.computed[dep]) {
-                    compute(dep);
-                }
+            if (deps.some(dep => this.#dependencyAffectedBy(dep, identifier))) {
+                this.#bindings.markComputedDirty(key);
             }
-            // If none of the dependencies have changed, skip recomputation (unless it's initialization).
-            // Checked after recursive computation to detect transitive changes through computed properties.
-            if (!isInitialization && !deps.some(dep => allChanges.has(dep))) {
-                computed.add(key);
-                return;
-            }
-            // Now compute this property
-            const computedFn = VApplication.#getComputedGetter(this.#options.computed[key]);
-            try {
-                const oldValue = this.#bindings?.get(key);
-                const newValue = computedFn.call(this.#bindings?.raw);
-                // Check if the value actually changed
-                let hasChanged = oldValue !== newValue;
-                // For arrays, always update (VBindings will detect length changes via its length cache)
-                if (!hasChanged && Array.isArray(newValue)) {
-                    hasChanged = true;
-                }
-                if (hasChanged) {
-                    // Use setSilent to avoid triggering onChange during computed property updates
-                    // Then mark the computed property as changed so UI depending on it will update
-                    this.#bindings?.setSilent(key, newValue);
-                    this.#bindings?.markChanged(key);
-                    allChanges.add(key);
-                    // Track source path mapping for computed property values
-                    // This allows changes like "model.elements[0].x" to be mapped to "selectedElement.x"
-                    if (typeof newValue === 'object' && newValue !== null) {
-                        const sourcePath = ReactiveProxy.getPath(newValue);
-                        if (sourcePath) {
-                            // Remove old mapping for this computed property
-                            for (const [path, name] of this.#computedSourcePaths) {
-                                if (name === key) {
-                                    this.#computedSourcePaths.delete(path);
-                                    break;
-                                }
+        }
+    }
+    /**
+     * Determines whether a change to `changePath` affects a computed dependency `dep`, taking both
+     * path directions into account:
+     *  - an exact match;
+     *  - `changePath` is a descendant of `dep` (e.g. dep "cartItems", change "cartItems.0.quantity")
+     *    — a nested mutation of the dependency;
+     *  - `dep` is a descendant of `changePath` (e.g. dep "user.name", change "user") — the container
+     *    holding the dependency was replaced wholesale.
+     * Local and global path aliases (e.g. computed source paths) are also honored via the bindings'
+     * own alias-aware matcher.
+     * @param dep The dependency path declared by a computed property.
+     * @param changePath The identifier reported by the bindings change tracker.
+     */
+    #dependencyAffectedBy(dep, changePath) {
+        if (changePath === dep) {
+            return true;
+        }
+        if (changePath.startsWith(dep + '.') || changePath.startsWith(dep + '[')) {
+            return true;
+        }
+        if (dep.startsWith(changePath + '.') || dep.startsWith(changePath + '[')) {
+            return true;
+        }
+        // Fall back to alias-aware matching for aliased paths (computed source paths, props, etc.).
+        return this.#bindings.doesChangeMatchIdentifier(changePath, dep);
+    }
+    /**
+     * Forces resolution of all computed properties currently marked dirty so that the set of
+     * changed identifiers is complete before watcher notification and the DOM diff. Computeds that
+     * were already pulled by a synchronous read earlier in the cycle are no longer dirty and are
+     * skipped, so each computed is recomputed at most once per update cycle.
+     */
+    #flushDirtyComputeds() {
+        this.#bindings?.flushDirtyComputeds();
+    }
+    /**
+     * Recomputes a single computed property and updates its cached value. Registered with the
+     * bindings as the pull-based recompute callback, so it runs lazily the first time the property
+     * is read after being marked dirty (or during the pre-render flush). Computed→computed chains
+     * resolve naturally and order-independently: reading a dependent computed inside the getter
+     * triggers its own lazy resolution through the bindings proxy.
+     *
+     * When the value actually changes, the computed name is recorded as a change so that
+     * dependency-precise DOM updates and watcher notifications still fire, and the source-path
+     * mapping is refreshed so nested changes to the underlying object map back to the computed.
+     * @param key The computed property name.
+     */
+    #recomputeOne(key) {
+        if (!this.#options.computed || !this.#bindings) {
+            return;
+        }
+        const def = this.#options.computed[key];
+        if (!def) {
+            return;
+        }
+        const computedFn = VApplication.#getComputedGetter(def);
+        try {
+            // Read the previous value without triggering re-resolution, for change detection.
+            const oldValue = this.#bindings.peekComputed(key);
+            const newValue = computedFn.call(this.#bindings.raw);
+            // Check if the value actually changed.
+            let hasChanged = oldValue !== newValue;
+            // For arrays, always treat as changed (VBindings detects length changes via its length
+            // cache). This preserves the precise-update behavior of the previous eager implementation.
+            if (!hasChanged && Array.isArray(newValue)) {
+                hasChanged = true;
+            }
+            // Cache the value silently so the read returns it without re-triggering reactivity.
+            this.#bindings.setSilent(key, newValue);
+            if (hasChanged) {
+                // Mark the computed property as changed so UI and watchers depending on it update.
+                this.#bindings.markChanged(key);
+                // Track source path mapping for computed property values.
+                // This allows changes like "model.elements[0].x" to be mapped to "selectedElement.x".
+                if (typeof newValue === 'object' && newValue !== null) {
+                    const sourcePath = ReactiveProxy.getPath(newValue);
+                    if (sourcePath) {
+                        // Remove old mapping for this computed property
+                        for (const [path, name] of this.#computedSourcePaths) {
+                            if (name === key) {
+                                this.#computedSourcePaths.delete(path);
+                                break;
                             }
-                            // Add new mapping
-                            this.#computedSourcePaths.set(sourcePath, key);
                         }
+                        // Add new mapping
+                        this.#computedSourcePaths.set(sourcePath, key);
                     }
                 }
             }
-            catch (error) {
-                this.#logger.error(`Error evaluating computed property '${key}': ${error}`);
-            }
-            computed.add(key);
-            processing.delete(key);
-        };
-        // Compute all properties; the recursive logic inside compute() handles
-        // dependency ordering and skips properties whose dependencies did not change.
-        for (const key of Object.keys(this.#computedDependencies)) {
-            compute(key);
+        }
+        catch (error) {
+            this.#logger.error(`Error evaluating computed property '${key}': ${error}`);
         }
     }
     /**