@mintjamsinc/ichigojs 0.1.9 → 0.1.10

package/README.md

@@ -16,9 +16,10 @@ A simple and intuitive reactive framework. Lightweight, fast, and user-friendly
 - 📦 **Lightweight** - Minimal bundle size
 - 🚀 **High Performance** - Efficient batched updates via microtask queue
 - 💪 **TypeScript** - Written in TypeScript with full type support
-- 🎨 **Directives** - `v-if`, `v-for`, `v-show`, `v-bind`, `v-on`, `v-model`, `v-resize`, `v-intersection`
+- 🎨 **Directives** - `v-if`, `v-for`, `v-show`, `v-bind`, `v-on`, `v-model`, `v-resize`, `v-intersection`, `v-performance`
 - 📐 **Resize Observer** - Monitor element size changes with `v-resize` directive
 - 👁️ **Intersection Observer** - Detect element visibility with `v-intersection` directive
+- ⚡ **Performance Observer** - Monitor performance metrics with `v-performance` directive
 
 ## Installation
 
@@ -272,6 +273,56 @@ You can also use `:options` for generic options:
 - Perfect for lazy loading, infinite scroll, and animation triggers
 - Access to element, VNode, and userData via `$ctx`
 
+#### v-performance
+
+Monitor performance metrics using PerformanceObserver:
+
+```html
+<div v-performance="onPerformance">
+  Performance monitoring
+</div>
+```
+
+```javascript
+methods: {
+  onPerformance(entries, observer, options, $ctx) {
+    entries.getEntries().forEach(entry => {
+      console.log(`${entry.name}: ${entry.duration}ms`);
+    });
+
+    // Access dropped entries count if available
+    if (options?.droppedEntriesCount) {
+      console.log(`Dropped: ${options.droppedEntriesCount}`);
+    }
+  }
+}
+```
+
+**With custom options:**
+
+```html
+<div v-performance="onPerformance"
+     :options.performance="{entryTypes: ['measure', 'mark']}">
+  Observe only measures and marks
+</div>
+```
+
+You can also use `:options` for generic options:
+
+```html
+<div v-performance="onPerformance"
+     :options="{type: 'navigation', buffered: true}">
+  Performance monitoring
+</div>
+```
+
+**Features:**
+- Native PerformanceObserver API for monitoring performance metrics
+- Custom entry types and options via `:options.performance` or `:options`
+- Automatic cleanup in destroy phase
+- Monitor marks, measures, navigation, resource timing, and more
+- Access to element, VNode, and userData via `$ctx`
+
 #### Lifecycle Hooks
 
 Lifecycle hooks allow you to run code at specific stages of an element's lifecycle. Each hook receives a **lifecycle context** (`$ctx`) with access to the element, VNode, and userData storage.

package/dist/ichigo.esm.js

@@ -68,10 +68,12 @@ var StandardDirectiveName;
     StandardDirectiveName["V_BIND"] = "v-bind";
     /** Two-way data binding directives. */
     StandardDirectiveName["V_MODEL"] = "v-model";
-    /** Slot content insertion directives. */
+    /** Resize observer directives. */
     StandardDirectiveName["V_RESIZE"] = "v-resize";
     /** Intersection observer directives. */
     StandardDirectiveName["V_INTERSECTION"] = "v-intersection";
+    /** Performance observer directives. */
+    StandardDirectiveName["V_PERFORMANCE"] = "v-performance";
 })(StandardDirectiveName || (StandardDirectiveName = {}));
 
 // This file was generated. Do not modify manually!
@@ -9921,6 +9923,220 @@ class VOnDirective {
     }
 }
 
+// Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+/**
+ * Directive for observing performance metrics using PerformanceObserver.
+ * The `v-performance` directive allows you to monitor various performance entries.
+ *
+ * Example usage:
+ *     <div v-performance="handlePerformance">Performance monitoring</div>
+ *     <div v-performance="handlePerformance" :options.performance="{entryTypes: ['measure']}">Performance monitoring</div>
+ *
+ * By default (without options), it observes 'mark' and 'measure' entry types.
+ *
+ * The handler receives PerformanceObserverEntryList, PerformanceObserver, options (with droppedEntriesCount), and $ctx as arguments:
+ *     handlePerformance(entries, observer, options, $ctx) {
+ *       entries.getEntries().forEach(entry => {
+ *         console.log(`${entry.name}: ${entry.duration}ms`);
+ *       });
+ *       if (options?.droppedEntriesCount) {
+ *         console.log(`Dropped entries: ${options.droppedEntriesCount}`);
+ *       }
+ *     }
+ *
+ * Options can be provided via :options or :options.performance attribute:
+ *     :options="{entryTypes: ['measure', 'mark']}"
+ *     :options.performance="{type: 'navigation', buffered: true}"
+ *
+ * This directive is useful for performance monitoring, profiling, and identifying
+ * performance bottlenecks in your application.
+ */
+class VPerformanceDirective {
+    /**
+     * The virtual node to which this directive is applied.
+     */
+    #vNode;
+    /**
+     * A list of variable and function names used in the directive's expression.
+     */
+    #dependentIdentifiers;
+    /**
+     * The performance handler wrapper function.
+     */
+    #handlerWrapper;
+    /**
+     * The PerformanceObserver instance.
+     */
+    #performanceObserver;
+    /**
+     * @param context The context for parsing the directive.
+     */
+    constructor(context) {
+        this.#vNode = context.vNode;
+        // Parse the expression to extract identifiers and create the handler wrapper
+        const expression = context.attribute.value;
+        if (expression) {
+            this.#dependentIdentifiers = ExpressionUtils.extractIdentifiers(expression, context.vNode.vApplication.functionDependencies);
+            this.#handlerWrapper = this.#createPerformanceHandlerWrapper(expression);
+        }
+        // Remove the directive attribute from the element
+        this.#vNode.node.removeAttribute(context.attribute.name);
+    }
+    /**
+     * @inheritdoc
+     */
+    get name() {
+        return StandardDirectiveName.V_PERFORMANCE;
+    }
+    /**
+     * @inheritdoc
+     */
+    get vNode() {
+        return this.#vNode;
+    }
+    /**
+     * @inheritdoc
+     */
+    get needsAnchor() {
+        return false;
+    }
+    /**
+     * @inheritdoc
+     */
+    get bindingsPreparer() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get domUpdater() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get templatize() {
+        return false;
+    }
+    /**
+     * @inheritdoc
+     */
+    get dependentIdentifiers() {
+        return this.#dependentIdentifiers ?? [];
+    }
+    /**
+     * @inheritdoc
+     */
+    get onMount() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onMounted() {
+        if (!this.#handlerWrapper) {
+            return undefined;
+        }
+        const handler = this.#handlerWrapper;
+        return () => {
+            // Get options from :options.performance or :options directive
+            let optionsDirective = this.#vNode.directiveManager?.optionsDirective('performance');
+            // Evaluate the options expression
+            let options;
+            if (optionsDirective && optionsDirective.expression) {
+                // Evaluate the options expression
+                const identifiers = optionsDirective.dependentIdentifiers;
+                const values = identifiers.map(id => this.#vNode.bindings?.get(id));
+                const args = identifiers.join(", ");
+                const funcBody = `return (${optionsDirective.expression});`;
+                const func = new Function(args, funcBody);
+                options = func(...values);
+            }
+            // Create PerformanceObserver and start observing
+            // Note: The callback receives a third argument 'options' with droppedEntriesCount in modern browsers
+            // TypeScript's type definition only includes 2 arguments, so we use type assertion
+            this.#performanceObserver = new PerformanceObserver(((...args) => {
+                const [entries, observer, callbackOptions] = args;
+                handler(entries, observer, callbackOptions);
+            }));
+            // If no options provided, use default: observe marks and measures
+            if (!options) {
+                options = { entryTypes: ['mark', 'measure'] };
+            }
+            // Start observing with options
+            this.#performanceObserver.observe(options);
+        };
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUpdate() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUpdated() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUnmount() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUnmounted() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    destroy() {
+        // Disconnect the PerformanceObserver when the directive is destroyed
+        if (this.#performanceObserver) {
+            this.#performanceObserver.disconnect();
+            this.#performanceObserver = undefined;
+        }
+    }
+    /**
+     * Creates a wrapper function for performance handlers.
+     * @param expression The expression string to evaluate.
+     * @returns A function that handles the performance event.
+     */
+    #createPerformanceHandlerWrapper(expression) {
+        const identifiers = this.#dependentIdentifiers ?? [];
+        const vNode = this.#vNode;
+        // Return a function that handles the performance event with proper scope
+        return (entries, observer, options) => {
+            const bindings = vNode.bindings;
+            const $ctx = {
+                element: vNode.node,
+                vnode: vNode,
+                userData: vNode.userData
+            };
+            // If the expression is just a method name, call it with bindings as 'this'
+            const trimmedExpr = expression.trim();
+            if (identifiers.includes(trimmedExpr) && typeof bindings?.get(trimmedExpr) === 'function') {
+                const methodName = trimmedExpr;
+                const originalMethod = bindings?.get(methodName);
+                // Call the method with bindings as 'this' context
+                // Pass entries, observer, options, and $ctx as arguments
+                return originalMethod(entries, observer, options, $ctx);
+            }
+            // For inline expressions, evaluate normally
+            // Note: inline expressions receive entries, observer, options, and $ctx as parameters
+            const values = identifiers.map(id => vNode.bindings?.get(id));
+            const args = [...identifiers, 'entries', 'observer', 'options', '$ctx'].join(", ");
+            const funcBody = `return (${expression});`;
+            const func = new Function(args, funcBody);
+            return func.call(bindings?.raw, ...values, entries, observer, options, $ctx);
+        };
+    }
+}
+
 // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
 /**
  * Directive for observing element resize events using ResizeObserver.
@@ -10351,7 +10567,9 @@ class VStandardDirectiveParser {
             // v-resize
             context.attribute.name === StandardDirectiveName.V_RESIZE ||
             // v-intersection
-            context.attribute.name === StandardDirectiveName.V_INTERSECTION) {
+            context.attribute.name === StandardDirectiveName.V_INTERSECTION ||
+            // v-performance
+            context.attribute.name === StandardDirectiveName.V_PERFORMANCE) {
             return true;
         }
         return false;
@@ -10398,6 +10616,10 @@ class VStandardDirectiveParser {
         if (context.attribute.name === StandardDirectiveName.V_INTERSECTION) {
             return new VIntersectionDirective(context);
         }
+        // v-performance
+        if (context.attribute.name === StandardDirectiveName.V_PERFORMANCE) {
+            return new VPerformanceDirective(context);
+        }
         throw new Error(`The attribute "${context.attribute.name}" cannot be parsed by ${this.name}.`);
     }
 }