@mintjamsinc/ichigojs 0.1.86 → 0.1.87

package/dist/types/ichigo/VBindings.d.ts

@@ -134,4 +134,20 @@ export declare class VBindings {
      * global aliases (computed properties etc.).
      */
     doesChangeMatchIdentifier(changePath: string, identifier: string): boolean;
+    /**
+     * Checks whether any of the changes affects an expression with the given identifiers.
+     *
+     * An identifier with a run-time index ("frames[*].url" for frames[i].url) normally
+     * matches a change at any index. When trackedPaths holds the paths the expression read
+     * during its last evaluation, the identifier is narrowed to the concrete paths among
+     * them ("frames[0].url"), so a write to another element is ignored. When no recorded
+     * path fits the identifier (not evaluated yet, a raw object, a short-circuited read),
+     * the identifier keeps matching every index.
+     *
+     * @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.
+     */
+    isAffected(changes: string[], identifiers: string[], trackedPaths?: ReadonlySet<string>): boolean;
 }

package/dist/types/ichigo/VBindingsPreparer.d.ts

@@ -7,6 +7,12 @@ export interface VBindingsPreparer {
      * Changes to these identifiers may trigger the need to prepare bindings again.
      */
     get dependentIdentifiers(): string[];
+    /**
+     * The source paths the preparer's expressions read during their last evaluation,
+     * when a dependent identifier has an index known only at run time ("items[*].name").
+     * A change is then matched against these concrete paths instead of every index.
+     */
+    readonly trackedPaths?: ReadonlySet<string>;
     /**
      * The list of identifiers that can be prepared by this preparer.
      * This is a subset of the identifiers property.

package/dist/types/ichigo/VDOMUpdater.d.ts

@@ -9,6 +9,12 @@ export interface VDOMUpdater {
      * Changes to these identifiers may trigger the updater to apply changes to the DOM.
      */
     get dependentIdentifiers(): string[];
+    /**
+     * The source paths the updater's expressions read during their last evaluation,
+     * when a dependent identifier has an index known only at run time ("items[*].name").
+     * A change is then matched against these concrete paths instead of every index.
+     */
+    readonly trackedPaths?: ReadonlySet<string>;
     /**
      * Applies the changes from the virtual DOM to the actual DOM.
      * This method is called when the identifiers change or when an update is needed.

package/dist/types/ichigo/VTextEvaluator.d.ts

@@ -21,6 +21,12 @@ export declare class VTextEvaluator {
      * Gets the list of identifiers extracted from the text expressions.
      */
     get identifiers(): string[];
+    /**
+     * 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.
+     */
+    get trackedPaths(): ReadonlySet<string> | undefined;
     /**
      * Evaluates the text with the provided bindings and returns the resulting string.
      * @param bindings The bindings to use for evaluating the expressions.

package/dist/types/ichigo/directives/VConditionalDirective.d.ts

@@ -43,6 +43,11 @@ export declare abstract class VConditionalDirective implements VDirective {
      * @inheritdoc
      */
     get dependentIdentifiers(): string[];
+    /**
+     * The paths the condition read during its last evaluation, when it has an index
+     * known only at run time (see ExpressionEvaluator.trackedPaths).
+     */
+    get trackedPaths(): ReadonlySet<string> | undefined;
     /**
      * The context for managing related conditional directives (v-if, v-else-if, v-else).
      */

package/dist/types/ichigo/directives/VConditionalDirectiveContext.d.ts

@@ -9,6 +9,11 @@ export declare class VConditionalDirectiveContext {
      * This is useful for determining dependencies for re-evaluation when data changes.
      */
     get allDependentIdentifiers(): string[];
+    /**
+     * The paths the conditions of the chain read during their last evaluation, united
+     * across directives, or undefined when no condition has a run-time index.
+     */
+    get trackedPaths(): ReadonlySet<string> | undefined;
     /**
      * Adds a directive (v-else-if or v-else) to the conditional context.
      * @param directive The directive to add.

package/dist/types/ichigo/util/ExpressionEvaluator.d.ts

@@ -53,6 +53,16 @@ export declare class ExpressionEvaluator {
      * Additional context variables (e.g., 'event', '$ctx').
      */
     private readonly additionalContext?;
+    /**
+     * Whether any identifier has an index known only at run time ("items[*].name").
+     * Only then are the paths read during evaluation worth recording.
+     */
+    private readonly hasDynamicIndex;
+    /**
+     * The source paths read through reactive proxies during the last evaluation,
+     * or undefined before the first evaluation and when nothing is recorded.
+     */
+    private trackedPathSet?;
     /**
      * Private constructor. Use ExpressionEvaluator.create() to create instances.
      */
@@ -82,6 +92,14 @@ export declare class ExpressionEvaluator {
      * @returns The result of the expression evaluation.
      */
     evaluate(): any;
+    /**
+     * The source paths read through reactive proxies during the last evaluation,
+     * recorded only for an expression with a run-time index ("items[i].name").
+     * 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.
+     */
+    get trackedPaths(): ReadonlySet<string> | undefined;
     /**
      * Evaluates the expression and returns the result as a boolean.
      *

package/dist/types/ichigo/util/ReactiveProxy.d.ts

@@ -55,6 +55,40 @@ export declare class ReactiveProxy {
      * identifier and whether descendants of the path also match.
      */
     private static pathPatterns;
+    /**
+     * The set collecting the paths read through any proxy while track() runs, or
+     * undefined when no expression is being tracked.
+     */
+    private static tracker?;
+    /**
+     * Whether a property key is spelled as an array index ("0", "12") rather than a
+     * property name. Both the proxy and the expression analyzer decide between
+     * "items[0]" and "items.name" with this test alone, so a numeric key on a plain
+     * object and a numeric key on an array get the same spelling.
+     *
+     * @param key The property key as a string.
+     * @returns True if the key is a canonical non-negative integer.
+     */
+    static isIndexKey(key: string): boolean;
+    /**
+     * Appends a property key to a source path the way change paths are reported:
+     * an index in brackets ("items[0]"), a name after a dot ("user.name").
+     *
+     * @param path The path of the containing object, or "" for a root binding.
+     * @param key The property key being appended.
+     * @returns The joined path.
+     */
+    static joinPath(path: string, key: string | symbol): string;
+    /**
+     * Runs fn while recording, into paths, the source path of every property read
+     * through a reactive proxy. Nested calls record into the innermost set only;
+     * the previous set is restored when fn returns or throws.
+     *
+     * @param paths The set that receives the paths read.
+     * @param fn The function to run.
+     * @returns The value fn returns.
+     */
+    static track<T>(paths: Set<string>, fn: () => T): T;
     /**
      * The `Object.prototype.toString` tags of the *only* value types we deeply
      * proxy. Everything else is returned untouched (raw).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintjamsinc/ichigojs",
-  "version": "0.1.86",
+  "version": "0.1.87",
   "description": "ichigo.js - Simple and intuitive reactive framework. Lightweight, fast, and user-friendly virtual DOM library",
   "main": "./dist/ichigo.cjs",
   "module": "./dist/ichigo.esm.js",