@mintjamsinc/ichigojs 0.1.21 → 0.1.23

package/README.md

@@ -90,6 +90,51 @@ VDOM.createApp({
 }).mount('#app');
 ```
 
+### Marking Objects as Non-Reactive
+
+Use `$markRaw()` to prevent objects from being wrapped in a reactive proxy. This is useful when storing third-party library instances or large data structures that don't need reactivity.
+
+```javascript
+VDOM.createApp({
+  data() {
+    return {
+      // Regular reactive data
+      count: 0,
+
+      // Mark as non-reactive
+      chart: null,
+      bigData: null
+    };
+  },
+  methods: {
+    initChart($ctx) {
+      // Create Chart.js instance and mark as non-reactive
+      const chartInstance = new Chart(canvas, { /* ... */ });
+      this.chart = this.$markRaw(chartInstance);
+
+      // Large dataset that doesn't need reactivity
+      const data = fetchLargeDataset();
+      this.bigData = this.$markRaw(data);
+    }
+  }
+}).mount('#app');
+```
+
+**When to use `$markRaw()`:**
+
+- Third-party library instances (Chart.js, Three.js, etc.)
+- Large arrays or objects that don't need change detection
+- Objects with complex internal state that shouldn't be proxied
+- DOM elements or other built-in objects with internal slots
+
+**Note:** Objects marked with `$markRaw()` won't trigger updates when modified. Use reactive properties to trigger updates when needed:
+
+```javascript
+// Update reactive trigger after modifying non-reactive data
+this.bigData.push(newItem);  // Won't trigger update
+this.count++;                // Triggers update
+```
+
 ### Computed Properties
 
 Computed properties automatically track their dependencies and re-evaluate when dependencies change.

package/dist/ichigo.esm.js

@@ -7417,6 +7417,16 @@ class ReactiveProxy {
      * This prevents creating multiple proxies for the same object accessed from different paths.
      */
     static proxyCache = new WeakMap();
+    /**
+     * A WeakMap to track which objects are proxies, mapping proxy -> original target.
+     * This prevents double-wrapping of already proxied objects.
+     */
+    static proxyToTarget = new WeakMap();
+    /**
+     * A WeakSet to track objects marked as "raw" (non-reactive).
+     * These objects will not be wrapped with Proxy.
+     */
+    static rawObjects = new WeakSet();
     /**
      * Creates a reactive proxy for the given object.
      * The proxy will call the onChange callback whenever a property is modified.
@@ -7431,9 +7441,19 @@ class ReactiveProxy {
         if (typeof target !== 'object' || target === null) {
             return target;
         }
+        // Don't wrap objects marked as raw (non-reactive)
+        if (this.rawObjects.has(target)) {
+            return target;
+        }
         // Don't wrap built-in objects that have internal slots
         // These objects require their methods to be called with the correct 'this' context
-        if (target instanceof Date || target instanceof RegExp || target instanceof Error) {
+        // Use Object.prototype.toString for more reliable type checking
+        const typeTag = Object.prototype.toString.call(target);
+        if (typeTag === '[object Date]' || typeTag === '[object RegExp]' || typeTag === '[object Error]') {
+            return target;
+        }
+        // Check if the target is already a proxy - if so, return it as-is to prevent double-wrapping
+        if (this.proxyToTarget.has(target)) {
             return target;
         }
         // Check if we already have a proxy for this target with this path
@@ -7454,8 +7474,14 @@ class ReactiveProxy {
                 const value = Reflect.get(obj, key);
                 // If the value is an object or array, make it reactive too
                 if (typeof value === 'object' && value !== null) {
+                    // Don't wrap objects marked as raw (non-reactive)
+                    if (ReactiveProxy.rawObjects.has(value)) {
+                        return value;
+                    }
                     // Don't wrap built-in objects that have internal slots
-                    if (value instanceof Date || value instanceof RegExp || value instanceof Error) {
+                    // Use Object.prototype.toString for more reliable type checking
+                    const valueTypeTag = Object.prototype.toString.call(value);
+                    if (valueTypeTag === '[object Date]' || valueTypeTag === '[object RegExp]' || valueTypeTag === '[object Error]') {
                         return value;
                     }
                     // Build the nested path
@@ -7468,7 +7494,7 @@ class ReactiveProxy {
                     const arrayMutationMethods = ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse'];
                     if (arrayMutationMethods.includes(key)) {
                         return function (...args) {
-                            const result = value.apply(this, args);
+                            const result = value.apply(obj, args);
                             onChange(path || undefined);
                             return result;
                         };
@@ -7497,6 +7523,8 @@ class ReactiveProxy {
         });
         // Cache the proxy for this path
         pathMap.set(path, proxy);
+        // Track that this proxy wraps the target to prevent double-wrapping
+        this.proxyToTarget.set(proxy, target);
         return proxy;
     }
     /**
@@ -7520,6 +7548,32 @@ class ReactiveProxy {
         // In a full implementation, we'd need to store a reverse mapping
         return obj;
     }
+    /**
+     * Marks an object as "raw" (non-reactive).
+     * Objects marked as raw will not be wrapped with Proxy when accessed from reactive objects.
+     * This is useful for objects that should not be reactive, such as:
+     * - Objects with private fields (class instances with # fields)
+     * - Third-party library instances
+     * - Objects used only for method calls
+     *
+     * @param obj The object to mark as raw.
+     * @returns The same object (for chaining).
+     */
+    static markRaw(obj) {
+        if (typeof obj === 'object' && obj !== null) {
+            this.rawObjects.add(obj);
+        }
+        return obj;
+    }
+    /**
+     * Checks if an object is marked as raw (non-reactive).
+     *
+     * @param obj The object to check.
+     * @returns True if the object is marked as raw, false otherwise.
+     */
+    static isRaw(obj) {
+        return typeof obj === 'object' && obj !== null && this.rawObjects.has(obj);
+    }
 }
 
 // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
@@ -7553,6 +7607,10 @@ class VBindings {
      * Cache for array lengths to detect length changes when the same object reference is used.
      */
     #lengthCache = new Map();
+    /**
+     * Flag to suppress onChange callbacks temporarily.
+     */
+    #suppressOnChange = false;
     /**
      * Creates a new instance of VBindings.
      * @param parent The parent bindings, if any.
@@ -7591,7 +7649,9 @@ class VBindings {
                             this.#logger?.debug(`Binding changed: ${path}`);
                             this.#changes.add(path);
                         }
-                        this.#onChange?.(changedPath);
+                        if (!this.#suppressOnChange) {
+                            this.#onChange?.(changedPath);
+                        }
                     }, key);
                 }
                 const oldValue = Reflect.get(target, key);
@@ -7616,7 +7676,9 @@ class VBindings {
                         this.#logger.debug(`Binding set on ${target === obj ? 'local' : 'parent'}: ${key}: ${oldValuePreview} -> ${newValuePreview}`);
                     }
                     this.#changes.add(key);
-                    this.#onChange?.(key);
+                    if (!this.#suppressOnChange) {
+                        this.#onChange?.(key);
+                    }
                 }
                 return result;
             },
@@ -7703,6 +7765,21 @@ class VBindings {
     remove(key) {
         delete this.#local[key];
     }
+    /**
+     * Sets a binding value without triggering onChange callback.
+     * This is useful for internal updates that shouldn't trigger reactivity.
+     * @param key The binding name.
+     * @param value The binding value.
+     */
+    setSilent(key, value) {
+        this.#suppressOnChange = true;
+        try {
+            this.#local[key] = value;
+        }
+        finally {
+            this.#suppressOnChange = false;
+        }
+    }
 }
 
 // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
@@ -9224,7 +9301,10 @@ class VForDirective {
                     vApplication: this.#vNode.vApplication,
                     parentVNode: this.#vNode.parentVNode,
                     bindings,
-                    dependentIdentifiers: [`${this.#sourceName}[${context.index}]`]
+                    dependentIdentifiers: [
+                        `${this.#sourceName}[${context.index}]`,
+                        ...this.#vNode.vApplication.resolveDependentIdentifiers(this.#sourceName, context.item)
+                    ],
                 });
                 newRenderedItems.set(key, vNode);
                 vNode.forceUpdate();
@@ -11072,6 +11152,10 @@ class VApplication {
      * The application options.
      */
     #options;
+    /**
+     * The parent application, if any.
+     */
+    #parentApplication;
     /**
      * The global directive parser registry.
      */
@@ -11110,12 +11194,12 @@ class VApplication {
     #updateScheduled = false;
     /**
      * Creates an instance of the virtual application.
-     * @param options The application options.
-     * @param directiveParserRegistry The global directive parser registry.
-     * @param componentRegistry The global component registry.
+     * @param args The initialization arguments for the application.
      */
-    constructor(options, directiveParserRegistry, componentRegistry) {
+    constructor(args) {
+        const { options, parentApplication: parentApplication, directiveParserRegistry, componentRegistry } = args;
         this.#options = options;
+        this.#parentApplication = parentApplication;
         this.#directiveParserRegistry = directiveParserRegistry;
         this.#componentRegistry = componentRegistry;
         // Initialize log manager and logger
@@ -11128,6 +11212,12 @@ class VApplication {
         // Initialize bindings from data, computed, and methods
         this.#initializeBindings();
     }
+    /**
+     * Gets the parent application, if any.
+     */
+    get parentApplication() {
+        return this.#parentApplication;
+    }
     /**
      * Gets the global directive parser registry.
      */
@@ -11207,7 +11297,12 @@ class VApplication {
      * @returns The created child application instance.
      */
     createChildApp(options) {
-        return new VApplication(options, this.#directiveParserRegistry, this.#componentRegistry);
+        return new VApplication({
+            options,
+            parentApplication: this,
+            directiveParserRegistry: this.#directiveParserRegistry,
+            componentRegistry: this.#componentRegistry
+        });
     }
     /**
      * Cleans the element by removing unnecessary whitespace text nodes.
@@ -11239,6 +11334,26 @@ class VApplication {
             }
         }
     }
+    /**
+     * Computes dependent identifiers for a given computed property and value.
+     * This is used to track dependencies in directives like v-for.
+     * @param computedName The name of the computed property.
+     * @param value The value to check for dependencies.
+     * @returns An array of dependent identifiers.
+     */
+    resolveDependentIdentifiers(computedName, value) {
+        const identifiers = [];
+        for (const dep of this.#computedDependencies[computedName] || []) {
+            const depValue = this.#bindings?.get(dep);
+            if (Array.isArray(depValue)) {
+                const idx = depValue.indexOf(value);
+                if (idx !== -1) {
+                    identifiers.push(`${dep}[${idx}]`);
+                }
+            }
+        }
+        return identifiers;
+    }
     /**
      * Initializes bindings from data, computed properties, and methods.
      * @returns The initialized bindings object.
@@ -11253,6 +11368,7 @@ class VApplication {
         });
         // Inject utility methods into bindings
         this.#bindings.set('$nextTick', (callback) => this.#nextTick(callback));
+        this.#bindings.set('$markRaw', (obj) => ReactiveProxy.markRaw(obj));
         // Add methods
         if (this.#options.methods) {
             for (const [key, method] of Object.entries(this.#options.methods)) {
@@ -11267,7 +11383,13 @@ class VApplication {
         }
         // Add data properties
         if (this.#options.data) {
-            const data = this.#options.data();
+            // Create a $ctx context object with utility functions for data()
+            // This provides the same $markRaw access as in lifecycle hooks (@mount, etc.)
+            const $ctx = {
+                $markRaw: (obj) => ReactiveProxy.markRaw(obj)
+            };
+            // Call data() with $ctx as 'this'
+            const data = this.#options.data.call($ctx);
             if (data && typeof data === 'object') {
                 for (const [key, value] of Object.entries(data)) {
                     this.#bindings.set(key, value);
@@ -11350,9 +11472,15 @@ class VApplication {
             try {
                 const oldValue = this.#bindings?.get(key);
                 const newValue = computedFn.call(this.#bindings?.raw);
-                // Track if the computed value actually changed
-                if (oldValue !== newValue) {
-                    this.#bindings?.set(key, newValue);
+                // 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
+                    this.#bindings?.setSilent(key, newValue);
                     allChanges.add(key);
                 }
             }
@@ -11441,9 +11569,13 @@ class VDOM {
      * @returns The created virtual application instance.
      */
     static createApp(options) {
-        return new VApplication(options, this.#directiveParserRegistry, this.#componentRegistry);
+        return new VApplication({
+            options,
+            directiveParserRegistry: this.#directiveParserRegistry,
+            componentRegistry: this.#componentRegistry
+        });
     }
 }
 
-export { VComponent, VComponentRegistry, VDOM };
+export { ReactiveProxy, VComponent, VComponentRegistry, VDOM };
 //# sourceMappingURL=ichigo.esm.js.map