@mintjamsinc/ichigojs 0.1.89 → 0.1.90

package/README.md

@@ -219,6 +219,27 @@ 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.
 
+**Dependencies:**
+
+A computed property depends on the properties its source names (`this.firstName`,
+including those read by the methods it calls) and on everything it actually read
+the last time it ran. Reads that only happen at run time, such as a property
+looked up by a key, are therefore followed too, and the record is replaced on
+every run, so a computed that switches between branches follows the branch it
+took:
+
+```javascript
+computed: {
+  selected() {
+    // `this[key]` names no property in the source; the reads are recorded when it runs
+    return ['upper', 'lower', 'digit'].filter(key => this[key]);
+  }
+}
+```
+
+The same holds for template bindings that call a method, such as
+`:disabled="isLast('upper')"` where `isLast` reads `this[key]`.
+
 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
 or assigned to directly. Reads go through `get`, while assignments are routed

package/dist/ichigo.cjs

@@ -6813,6 +6813,13 @@
          * through a reactive proxy. Nested calls record into the innermost set only;
          * the previous set is restored when fn returns or throws.
          *
+         * The set is kept closed under ancestors: whenever a path is recorded, every
+         * path above it ("items" and "items[2]" for "items[2].name") is in the set as
+         * well. A read reached through a proxy records them on its way down; a read
+         * that starts partway (a proxy a computed returned, a v-for item) has them
+         * added when it is recorded. changeAffectsRead relies on this to answer with
+         * one lookup.
+         *
          * @param paths The set that receives the paths read.
          * @param fn The function to run.
          * @returns The value fn returns.
@@ -6827,6 +6834,57 @@
                 this.tracker = previous;
             }
         }
+        /**
+         * Records a read made outside any proxy while track() runs: a binding read by
+         * name (`this.flag`, `this[key]`), which the bindings report here. Reads below
+         * a binding are recorded by the proxy itself.
+         *
+         * @param path The binding name read.
+         */
+        static recordRead(path) {
+            this.tracker?.add(path);
+        }
+        /**
+         * Records a read made through a proxy while track() runs: the member `key` of
+         * the object at `containerPath`. The container's own path and its ancestors are
+         * added first when they are missing, which happens when the proxy was not
+         * reached from a root binding during this run (see track()). A container that
+         * is already recorded has its ancestors recorded too, so the common case is one
+         * lookup.
+         *
+         * @param containerPath The source path of the object read from ("" for a root).
+         * @param key The property key read.
+         */
+        static recordProxyRead(containerPath, key) {
+            const tracker = this.tracker;
+            if (containerPath && !tracker.has(containerPath)) {
+                for (let i = 1; i < containerPath.length; i++) {
+                    const c = containerPath[i];
+                    if (c === '.' || c === '[') {
+                        tracker.add(containerPath.substring(0, i));
+                    }
+                }
+                tracker.add(containerPath);
+            }
+            tracker.add(this.joinPath(containerPath, key));
+        }
+        /**
+         * Checks whether a change touches something read during a tracked run (see
+         * track()): the path read was written, or an object or array holding it was
+         * replaced. A change below a path read does not count, since a read of the
+         * changed member itself would have been recorded too; this keeps a read of a
+         * whole collection ("items") from matching a write to one element.
+         *
+         * The set holds the ancestors of every path read, so a replaced container is
+         * found by the same lookup as the path itself.
+         *
+         * @param changePath The path that was changed (e.g., "items[2].name")
+         * @param readPaths The paths read during the tracked run
+         * @returns True if the change touches a path read
+         */
+        static changeAffectsRead(changePath, readPaths) {
+            return readPaths.has(changePath);
+        }
         /**
          * The `Object.prototype.toString` tags of the *only* value types we deeply
          * proxy. Everything else is returned untouched (raw).
@@ -6918,7 +6976,7 @@
                     // Function-valued members (push, Map#get, …) are accesses to behaviour,
                     // not data, so they are left out.
                     if (ReactiveProxy.tracker && typeof key !== 'symbol' && typeof value !== 'function') {
-                        ReactiveProxy.tracker.add(ReactiveProxy.joinPath(path, key));
+                        ReactiveProxy.recordProxyRead(path, key);
                     }
                     // If the value is an object or array, make it reactive too
                     if (typeof value === 'object' && value !== null) {
@@ -7337,6 +7395,18 @@
             });
             return Array.from(identifiers);
         }
+        /**
+         * Whether an expression refers to one of the application's methods, judged by the
+         * identifiers extractIdentifiers returned for it. A called method may read bindings
+         * the source analysis cannot name (e.g. `this[key]`), so such an expression records
+         * its reads when it runs.
+         * @param identifiers The identifiers extracted from the expression.
+         * @param functionDependencies The application's methods and their dependencies.
+         * @returns True if an identifier names a method.
+         */
+        static callsFunction(identifiers, functionDependencies) {
+            return identifiers.some(id => Object.prototype.hasOwnProperty.call(functionDependencies, id));
+        }
         /**
          * Returns the binding name an identifier chain starts with
          * (e.g. "items" for "items[0].name" or "user.name").
@@ -7735,26 +7805,27 @@
          */
         additionalContext;
         /**
-         * Whether any identifier has an index known only at run time ("items[*].name").
-         * Only then are the paths read during evaluation worth recording.
+         * Whether the paths read during evaluation are recorded: when an identifier has an
+         * index known only at run time ("items[*].name"), or when the expression calls a
+         * method, whose reads (`this[key]` among them) the source analysis may not see.
          */
-        hasDynamicIndex;
+        tracksReads;
         /**
-         * The source paths read through reactive proxies during the last evaluation,
-         * or undefined before the first evaluation and when nothing is recorded.
+         * The source paths read during the last evaluation, or undefined before the
+         * first evaluation and when nothing is recorded.
          */
         trackedPathSet;
         /**
          * Private constructor. Use ExpressionEvaluator.create() to create instances.
          */
-        constructor(expression, bindings, identifiers, originalIdentifiers, evaluatorFunc, additionalContext) {
+        constructor(expression, bindings, identifiers, originalIdentifiers, evaluatorFunc, callsMethod, additionalContext) {
             this.expression = expression;
             this.bindings = bindings;
             this.identifiers = identifiers;
             this.originalIdentifiers = originalIdentifiers;
             this.evaluatorFunc = evaluatorFunc;
             this.additionalContext = additionalContext;
-            this.hasDynamicIndex = originalIdentifiers.some(id => id.includes('[*]'));
+            this.tracksReads = callsMethod || originalIdentifiers.some(id => id.includes('[*]'));
         }
         /**
          * Creates an ExpressionEvaluator instance.
@@ -7796,7 +7867,7 @@
                 // Cache the compiled function
                 this.cache.set(cacheKey, evaluatorFunc);
             }
-            return new ExpressionEvaluator(expression, bindings, baseIdentifiers, extractedIdentifiers, evaluatorFunc, options?.additionalContext);
+            return new ExpressionEvaluator(expression, bindings, baseIdentifiers, extractedIdentifiers, evaluatorFunc, ExpressionUtils.callsFunction(extractedIdentifiers, functionDependencies), options?.additionalContext);
         }
         /**
          * Compiles an expression into a function.
@@ -7851,9 +7922,11 @@
                     values.push(...Object.values(this.additionalContext));
                 }
                 // Call the compiled function with the gathered values. When an index is
-                // known only at run time, record which concrete paths this evaluation
-                // read so that change matching can be narrowed to them (see trackedPaths).
-                if (!this.hasDynamicIndex) {
+                // known only at run time or a method is called, record which concrete
+                // paths this evaluation read (see trackedPaths). The values above are
+                // gathered outside the tracked call on purpose: a binding passed in by
+                // name is already among the identifiers.
+                if (!this.tracksReads) {
                     return this.evaluatorFunc(...values);
                 }
                 const paths = new Set();
@@ -7868,11 +7941,11 @@
             }
         }
         /**
-         * The source paths read through reactive proxies during the last evaluation,
-         * recorded only for an expression with a run-time index ("items[i].name").
+         * The source paths read during the last evaluation, recorded only for an
+         * expression with a run-time index ("items[i].name") or a method call.
          * Each evaluation replaces the previous set, so a path read for a former
          * index value is dropped as soon as the expression runs with the new one.
-         * Undefined before the first evaluation and for expressions without such an index.
+         * Undefined before the first evaluation and for other expressions.
          */
         get trackedPaths() {
             return this.trackedPathSet;
@@ -8664,7 +8737,14 @@
                         this.#resolveComputedIfDirty(key);
                     }
                     if (Reflect.has(obj, key)) {
-                        return Reflect.get(obj, key);
+                        const value = Reflect.get(obj, key);
+                        // Record the read for a computed property or expression being tracked
+                        // (see ReactiveProxy.track). Methods are behaviour, not data; a binding of a
+                        // parent scope is recorded by the parent's own trap.
+                        if (typeof key === 'string' && typeof value !== 'function') {
+                            ReactiveProxy.recordRead(key);
+                        }
+                        return value;
                     }
                     return this.#parent?.raw[key];
                 },
@@ -9009,6 +9089,13 @@
         markComputedDirty(key) {
             this.#dirtyComputeds.add(key);
         }
+        /**
+         * Indicates whether a computed property is marked dirty and not yet recomputed.
+         * @param key The computed property name.
+         */
+        isComputedDirty(key) {
+            return this.#dirtyComputeds.has(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
@@ -9128,10 +9215,14 @@
          * path fits the identifier (not evaluated yet, a raw object, a short-circuited read),
          * the identifier keeps matching every index.
          *
+         * The recorded paths also count as dependencies of their own: they include what a
+         * method called by the expression read, such as `this[key]`, which the identifiers
+         * found in the source cannot name.
+         *
          * @param changes The change paths of the current update cycle.
          * @param identifiers The identifiers the expression depends on.
          * @param trackedPaths The paths read during the expression's last evaluation, if recorded.
-         * @returns True if some change matches some identifier.
+         * @returns True if some change matches some identifier or recorded path.
          */
         isAffected(changes, identifiers, trackedPaths) {
             if (changes.length === 0) {
@@ -9145,6 +9236,9 @@
                     }
                 }
             }
+            if (trackedPaths && trackedPaths.size > 0) {
+                return changes.some(change => ReactiveProxy.changeAffectsRead(change, trackedPaths));
+            }
             return false;
         }
         /**
@@ -10211,8 +10305,8 @@
          */
         #evaluate;
         /**
-         * The source paths read through reactive proxies during the last evaluation,
-         * recorded only when some expression has a run-time index ("items[i].name").
+         * The source paths read during the last evaluation, recorded only when some
+         * expression has a run-time index ("items[i].name") or calls a method.
          */
         #trackedPaths;
         /**
@@ -10255,10 +10349,15 @@
                     func: new Function(args, funcBody)
                 };
             });
-            // Only an expression with an index known at run time needs its reads recorded
-            const hasDynamicIndex = this.#identifiers.some(id => id.includes('[*]'));
-            // Create a function to reconstruct the text with evaluated expressions
-            const evaluateText = (bindings) => {
+            // Only an expression with an index known at run time, or one that calls a method
+            // (whose reads, such as `this[key]`, the source analysis may not see), needs its
+            // reads recorded
+            const tracksReads = this.#identifiers.some(id => id.includes('[*]')) ||
+                ExpressionUtils.callsFunction(this.#identifiers, functionDependencies);
+            // Create a function to reconstruct the text with evaluated expressions. The values
+            // are gathered outside the tracked call: a binding passed in by name is already
+            // among the identifiers.
+            const evaluateText = (bindings, paths) => {
                 let result = text;
                 evaluators.forEach((evaluator, i) => {
                     // Build values for baseArgs (no dots) in the same order as function parameters
@@ -10272,15 +10371,16 @@
                     });
                     // Evaluate the expression and replace {{...}} in the text.
                     // A function replacement keeps `$`-patterns in the value literal.
-                    result = result.replace(matches[i][0], () => toDisplayString(evaluator.func(...values)));
+                    const value = paths ? ReactiveProxy.track(paths, () => evaluator.func(...values)) : evaluator.func(...values);
+                    result = result.replace(matches[i][0], () => toDisplayString(value));
                 });
                 return result;
             };
-            this.#evaluate = hasDynamicIndex
+            this.#evaluate = tracksReads
                 ? (bindings) => {
                     const paths = new Set();
                     this.#trackedPaths = undefined;
-                    const result = ReactiveProxy.track(paths, () => evaluateText(bindings));
+                    const result = evaluateText(bindings, paths);
                     this.#trackedPaths = paths;
                     return result;
                 }
@@ -10302,9 +10402,9 @@
             return this.#identifiers;
         }
         /**
-         * The source paths read through reactive proxies during the last evaluation.
-         * Recorded only when an expression has a run-time index ("items[i].name");
-         * undefined before the first evaluation and for texts without such an index.
+         * The source paths read during the last evaluation. Recorded only when an
+         * expression has a run-time index ("items[i].name") or calls a method;
+         * undefined before the first evaluation and for other texts.
          */
         get trackedPaths() {
             return this.#trackedPaths;
@@ -10725,6 +10825,29 @@
             this.#dependentIdentifiers = [...new Set(ids)];
             return this.#dependentIdentifiers;
         }
+        /**
+         * Whether a change of the current update cycle concerns this node, so that a node it
+         * depends on should update it: a change matches one of its identifiers, or touches a
+         * path one of its bindings read the last time it ran. The recorded reads cover what a
+         * called method read, such as `this[key]`, which the identifiers cannot name. Each
+         * binding decides again for itself when the node updates.
+         * @param changes The change paths of the current update cycle.
+         */
+        isAffectedBy(changes) {
+            if (changes.length === 0) {
+                return false;
+            }
+            if (this.dependentIdentifiers.some(id => changes.some(change => this.bindings.doesChangeMatchIdentifier(change, id)))) {
+                return true;
+            }
+            const recorded = [
+                this.#textEvaluator?.trackedPaths,
+                ...(this.#directiveManager?.bindingsPreparers ?? []).map(preparer => preparer.trackedPaths),
+                ...(this.#directiveManager?.domUpdaters ?? []).map(updater => updater.trackedPaths),
+            ];
+            return recorded.some(paths => paths !== undefined && paths.size > 0 &&
+                changes.some(change => ReactiveProxy.changeAffectsRead(change, paths)));
+        }
         get preparableIdentifiers() {
             // If already computed, return the cached preparable identifiers
             if (this.#preparableIdentifiers) {
@@ -10837,8 +10960,7 @@
                 }
                 // Recursively update dependent virtual nodes
                 this.#dependents?.forEach(dependentNode => {
-                    const changed = dependentNode.dependentIdentifiers.some(id => changes.some(change => dependentNode.bindings.doesChangeMatchIdentifier(change, id)));
-                    if (changed) {
+                    if (dependentNode.isAffectedBy(changes)) {
                         dependentNode.update();
                     }
                 });
@@ -10853,8 +10975,7 @@
                 // For document fragments (e.g. from <template v-if>), propagate updates
                 // to dependent virtual nodes so that child bindings stay reactive.
                 this.#dependents?.forEach(dependentNode => {
-                    const changed = dependentNode.dependentIdentifiers.some(id => changes.some(change => dependentNode.bindings.doesChangeMatchIdentifier(change, id)));
-                    if (changed) {
+                    if (dependentNode.isAffectedBy(changes)) {
                         dependentNode.update();
                     }
                 });
@@ -10867,6 +10988,55 @@
          * This is useful when an immediate update is needed, bypassing the usual change detection.
          */
         forceUpdate() {
+            // One pass per outermost call; a call made while a pass runs (a directive rendering
+            // a fresh clone, a component mounting) joins it. The node is stamped with the pass,
+            // so that the recursion over the children below skips a child a directive has
+            // already rendered in this pass (see #forceChildren).
+            const outermost = VNode.#forcePass === 0;
+            if (outermost) {
+                VNode.#forcePass = ++VNode.#forcePassCounter;
+            }
+            this.#forcedInPass = VNode.#forcePass;
+            try {
+                this.#forceUpdate();
+            }
+            finally {
+                if (outermost) {
+                    VNode.#forcePass = 0;
+                }
+            }
+        }
+        /**
+         * The pass counter behind {@link forceUpdate}: the last pass number handed out.
+         */
+        static #forcePassCounter = 0;
+        /**
+         * The pass that is running, or 0 between passes.
+         */
+        static #forcePass = 0;
+        /**
+         * The pass this node was last forced in, or 0 if never.
+         */
+        #forcedInPass = 0;
+        /**
+         * Forces the children that have not been forced in the running pass. A v-if / v-for /
+         * slot clone is a child of its host, and the host's directive renders it with its own
+         * forceUpdate() call as soon as it is created, so recursing into it here would render it a
+         * second time. A clone that already existed, and that the directive updated with
+         * update(), has not been forced in this pass and is still forced here.
+         */
+        #forceChildren() {
+            // A copy: an update can destroy a v-if / v-for clone, which removes it from this list.
+            this.#childVNodes?.slice().forEach(childVNode => {
+                if (childVNode.#forcedInPass !== VNode.#forcePass) {
+                    childVNode.forceUpdate();
+                }
+            });
+        }
+        /**
+         * The body of {@link forceUpdate}, run within a pass.
+         */
+        #forceUpdate() {
             if (this.#nodeType === Node.TEXT_NODE && this.#textEvaluator) {
                 // If this is a text node with a text evaluator, update its content if needed
                 this.#renderText();
@@ -10896,11 +11066,8 @@
                         this.#renderSafely(() => updater.applyToDOM());
                     }
                 }
-                // Recursively update child virtual nodes. A copy: an update can
-                // destroy a v-if / v-for clone, which removes it from this list.
-                this.#childVNodes?.slice().forEach(childVNode => {
-                    childVNode.forceUpdate();
-                });
+                // Recursively update child virtual nodes
+                this.#forceChildren();
                 // If no directive requires template preservation, call onUpdated for directives that do not templatize
                 if (!this.#templatized) {
                     this.#directiveManager?.directives?.forEach(d => {
@@ -10910,9 +11077,7 @@
             }
             else if (this.#nodeType === Node.DOCUMENT_FRAGMENT_NODE) {
                 // For document fragments, recursively force update child VNodes
-                this.#childVNodes?.slice().forEach(childVNode => {
-                    childVNode.forceUpdate();
-                });
+                this.#forceChildren();
             }
         }
         /**
@@ -15483,6 +15648,13 @@
          * A dictionary mapping computed property names to their dependencies.
          */
         #computedDependencies;
+        /**
+         * The paths each computed property read the last time it was evaluated (see
+         * ReactiveProxy.track). A change to one of them marks the computed dirty as well as
+         * a change to the dependencies found in its source, since a read the source does not
+         * spell out, such as `this[key]`, is seen only here.
+         */
+        #computedReads = new Map();
         /**
          * A map tracking source paths for computed property values.
          * Maps source path (e.g., "model.elements[0]") to computed property name (e.g., "selectedElement").
@@ -16052,20 +16224,33 @@
         }
         /**
          * 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).
+         * A computed depends on what its source names (statically analyzed, with computed→computed and
+         * computed→method dependencies flattened to their underlying reactive paths) and on what it read
+         * the last time it ran (#computedReads). A computed marked dirty is itself a change for the
+         * computeds that read it, so marking follows those reads too. A computed already dirty is
+         * skipped: the computeds that read it were marked when it was, and a computed cannot be
+         * recomputed without reading — and so resolving — the dirty ones it depends on. The actual
+         * recomputation is deferred until the value is read (see #recomputeOne).
          * @param identifier The changed identifier reported by the bindings change tracker.
          */
         #markDirtyComputeds(identifier) {
             if (!this.#options.computed || !this.#bindings) {
                 return;
             }
-            for (const key of Object.keys(this.#computedDependencies)) {
-                const deps = this.#computedDependencies[key] || [];
-                if (deps.some(dep => this.#dependencyAffectedBy(dep, identifier))) {
-                    this.#bindings.markComputedDirty(key);
+            const pending = [identifier];
+            while (pending.length > 0) {
+                const changed = pending.pop();
+                for (const key of Object.keys(this.#computedDependencies)) {
+                    if (this.#bindings.isComputedDirty(key)) {
+                        continue;
+                    }
+                    const deps = this.#computedDependencies[key] || [];
+                    const reads = this.#computedReads.get(key);
+                    if (deps.some(dep => this.#dependencyAffectedBy(dep, changed)) ||
+                        (reads !== undefined && ReactiveProxy.changeAffectsRead(changed, reads))) {
+                        this.#bindings.markComputedDirty(key);
+                        pending.push(key);
+                    }
                 }
             }
         }
@@ -16125,10 +16310,21 @@
                 return;
             }
             const computedFn = VApplication.#getComputedGetter(def);
+            const bindings = this.#bindings;
             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);
+                const oldValue = bindings.peekComputed(key);
+                // Record what the getter reads, replacing the previous record: the reads can differ
+                // from run to run (a branch, a dynamic key). Kept even when the getter throws, so a
+                // change to what it read before failing retries it.
+                const reads = new Set();
+                let newValue;
+                try {
+                    newValue = ReactiveProxy.track(reads, () => computedFn.call(bindings.raw));
+                }
+                finally {
+                    this.#computedReads.set(key, reads);
+                }
                 // Check if the value actually changed.
                 let hasChanged = oldValue !== newValue;
                 // For arrays, always treat as changed (VBindings detects length changes via its length