@mintjamsinc/ichigojs 0.1.69 → 0.1.71

package/README.md

@@ -198,7 +198,25 @@ VDOM.createApp({
 }).mount('#app');
 ```
 
-**Writable Computed Properties:**
+**Lazy (pull-based) evaluation:**
+
+Computed properties are evaluated lazily and cached. When a dependency changes,
+the dependent computed is marked stale (rather than eagerly recomputed) and is
+recomputed on the next read. Because of this, reading a computed property
+**synchronously after mutating a dependency returns an up-to-date value** — you
+do not have to wait for the next tick:
+
+```javascript
+this.cartItems.push(item);
+console.log(this.subtotal); // already reflects the new item
+```
+
+DOM updates remain batched in a microtask, so multiple synchronous mutations
+still result in a single render. Each computed is recomputed at most once per
+update cycle (on first read, or during the pre-render flush, whichever comes
+first), and a computed whose recomputed value is unchanged does not trigger DOM
+updates or watchers that depend on it. Computed→computed chains resolve
+automatically and independently of declaration order.
 
 A computed property can also be defined as an object with both a `get` and a
 `set` function. This makes it writable, so it can be used as a `v-model` target
@@ -913,7 +931,7 @@ ichigo.js uses several optimization techniques:
 
 - **Microtask batching**: Multiple synchronous changes result in a single DOM update
 - **Efficient change tracking**: Only changed properties trigger re-evaluation
-- **Smart computed caching**: Computed properties only re-evaluate when dependencies change
+- **Lazy computed caching**: Computed properties are pull-based — they re-evaluate only when a dependency changes and the value is actually read, at most once per update cycle
 
 Benchmark (1000 item list update): **~6.8ms** ⚡
 
@@ -1003,6 +1021,10 @@ MIT License - Copyright (c) 2025 MintJams Inc.
 
 Inspired by [Vue.js](https://vuejs.org/) - A progressive JavaScript framework.
 
+## Trademarks
+
+All trademarks are the property of their respective owners.
+
 ---
 
 Built with ❤️ by [MintJams Inc.](https://github.com/mintjamsinc)

package/dist/ichigo.cjs

@@ -8399,6 +8399,31 @@
          * 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.
@@ -8410,8 +8435,13 @@
             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);
                     }
@@ -8669,6 +8699,79 @@
         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
@@ -13654,7 +13757,8 @@
             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 = {};
@@ -13663,7 +13767,23 @@
                     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
@@ -13854,7 +13974,11 @@
         #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
@@ -13904,8 +14028,17 @@
                     }
                 }
             }
-            // 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.
@@ -13956,8 +14089,9 @@
          * 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]
@@ -14002,110 +14136,116 @@
             }
         }
         /**
-         * 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}`);
             }
         }
         /**