eleva 1.0.0-alpha → 1.0.0-rc.2

package/src/modules/TemplateEngine.js

@@ -1,46 +1,64 @@
 "use strict";
 
 /**
- * 🔒 TemplateEngine: Secure interpolation & dynamic attribute parsing.
+ * @class 🔒 TemplateEngine
+ * @classdesc A secure template engine that handles interpolation and dynamic attribute parsing.
+ * Provides a safe way to evaluate expressions in templates while preventing XSS attacks.
+ * All methods are static and can be called directly on the class.
  *
- * This class provides methods to parse template strings by replacing
- * interpolation expressions with dynamic data values and to evaluate expressions
- * within a given data context.
+ * @example
+ * const template = "Hello, {{name}}!";
+ * const data = { name: "World" };
+ * const result = TemplateEngine.parse(template, data); // Returns: "Hello, World!"
  */
 export class TemplateEngine {
   /**
-   * Parses a template string and replaces interpolation expressions with corresponding values.
+   * @private {RegExp} Regular expression for matching template expressions in the format {{ expression }}
+   * @type {RegExp}
+   */
+  static expressionPattern = /\{\{\s*(.*?)\s*\}\}/g;
+
+  /**
+   * Parses a template string, replacing expressions with their evaluated values.
+   * Expressions are evaluated in the provided data context.
    *
-   * @param {string} template - The template string containing expressions in the format {{ expression }}.
-   * @param {object} data - The data object to use for evaluating expressions.
-   * @returns {string} The resulting string with evaluated values.
+   * @public
+   * @static
+   * @param {string} template - The template string to parse.
+   * @param {Record<string, unknown>} data - The data context for evaluating expressions.
+   * @returns {string} The parsed template with expressions replaced by their values.
+   * @example
+   * const result = TemplateEngine.parse("{{user.name}} is {{user.age}} years old", {
+   *   user: { name: "John", age: 30 }
+   * }); // Returns: "John is 30 years old"
    */
   static parse(template, data) {
-    return template.replace(/\{\{\s*(.*?)\s*\}\}/g, (_, expr) => {
-      const value = this.evaluate(expr, data);
-      return value === undefined ? "" : value;
-    });
+    if (typeof template !== "string") return template;
+    return template.replace(this.expressionPattern, (_, expression) =>
+      this.evaluate(expression, data)
+    );
   }
 
   /**
-   * Evaluates an expression using the provided data context.
+   * Evaluates an expression in the context of the provided data object.
+   * Note: This does not provide a true sandbox and evaluated expressions may access global scope.
+   * The use of the `with` statement is necessary for expression evaluation but has security implications.
+   * Expressions should be carefully validated before evaluation.
    *
-   * @param {string} expr - The JavaScript expression to evaluate.
-   * @param {object} data - The data context for evaluating the expression.
-   * @returns {*} The result of the evaluated expression, or an empty string if undefined or on error.
+   * @public
+   * @static
+   * @param {string} expression - The expression to evaluate.
+   * @param {Record<string, unknown>} data - The data context for evaluation.
+   * @returns {unknown} The result of the evaluation, or an empty string if evaluation fails.
+   * @example
+   * const result = TemplateEngine.evaluate("user.name", { user: { name: "John" } }); // Returns: "John"
+   * const age = TemplateEngine.evaluate("user.age", { user: { age: 30 } }); // Returns: 30
    */
-  static evaluate(expr, data) {
+  static evaluate(expression, data) {
+    if (typeof expression !== "string") return expression;
     try {
-      const keys = Object.keys(data);
-      const values = keys.map((k) => data[k]);
-      const result = new Function(...keys, `return ${expr}`)(...values);
-      return result === undefined ? "" : result;
-    } catch (error) {
-      console.error(`Template evaluation error:`, {
-        expression: expr,
-        data,
-        error: error.message,
-      });
+      return new Function("data", `with(data) { return ${expression}; }`)(data);
+    } catch {
       return "";
     }
   }

package/types/core/Eleva.d.ts

@@ -1,86 +1,355 @@
 /**
- * 🧩 Eleva Core: Signal-based component runtime framework with lifecycle, scoped styles, and plugins.
+ * @typedef {Object} ComponentDefinition
+ * @property {function(ComponentContext): (Record<string, unknown>|Promise<Record<string, unknown>>)} [setup]
+ *           Optional setup function that initializes the component's state and returns reactive data
+ * @property {(function(ComponentContext): string|Promise<string>)} template
+ *           Required function that defines the component's HTML structure
+ * @property {(function(ComponentContext): string)|string} [style]
+ *           Optional function or string that provides component-scoped CSS styles
+ * @property {Record<string, ComponentDefinition>} [children]
+ *           Optional object defining nested child components
+ */
+/**
+ * @typedef {Object} ComponentContext
+ * @property {Record<string, unknown>} props
+ *           Component properties passed during mounting
+ * @property {Emitter} emitter
+ *           Event emitter instance for component event handling
+ * @property {function<T>(value: T): Signal<T>} signal
+ *           Factory function to create reactive Signal instances
+ * @property {function(LifecycleHookContext): Promise<void>} [onBeforeMount]
+ *           Hook called before component mounting
+ * @property {function(LifecycleHookContext): Promise<void>} [onMount]
+ *           Hook called after component mounting
+ * @property {function(LifecycleHookContext): Promise<void>} [onBeforeUpdate]
+ *           Hook called before component update
+ * @property {function(LifecycleHookContext): Promise<void>} [onUpdate]
+ *           Hook called after component update
+ * @property {function(UnmountHookContext): Promise<void>} [onUnmount]
+ *           Hook called during component unmounting
+ */
+/**
+ * @typedef {Object} LifecycleHookContext
+ * @property {HTMLElement} container
+ *           The DOM element where the component is mounted
+ * @property {ComponentContext} context
+ *           The component's reactive state and context data
+ */
+/**
+ * @typedef {Object} UnmountHookContext
+ * @property {HTMLElement} container
+ *           The DOM element where the component is mounted
+ * @property {ComponentContext} context
+ *           The component's reactive state and context data
+ * @property {{
+ *   watchers: Array<() => void>,    // Signal watcher cleanup functions
+ *   listeners: Array<() => void>,   // Event listener cleanup functions
+ *   children: Array<MountResult>    // Child component instances
+ * }} cleanup
+ *           Object containing cleanup functions and instances
+ */
+/**
+ * @typedef {Object} MountResult
+ * @property {HTMLElement} container
+ *           The DOM element where the component is mounted
+ * @property {ComponentContext} data
+ *           The component's reactive state and context data
+ * @property {function(): Promise<void>} unmount
+ *           Function to clean up and unmount the component
+ */
+/**
+ * @typedef {Object} ElevaPlugin
+ * @property {function(Eleva, Record<string, unknown>): void} install
+ *           Function that installs the plugin into the Eleva instance
+ * @property {string} name
+ *           Unique identifier name for the plugin
+ */
+/**
+ * @class 🧩 Eleva
+ * @classdesc A modern, signal-based component runtime framework that provides lifecycle hooks,
+ * scoped styles, and plugin support. Eleva manages component registration, plugin integration,
+ * event handling, and DOM rendering with a focus on performance and developer experience.
+ *
+ * @example
+ * // Basic component creation and mounting
+ * const app = new Eleva("myApp");
+ * app.component("myComponent", {
+ *   setup: (ctx) => ({ count: ctx.signal(0) }),
+ *   template: (ctx) => `<div>Hello ${ctx.props.name}</div>`
+ * });
+ * app.mount(document.getElementById("app"), "myComponent", { name: "World" });
  *
- * The Eleva class is the core of the framework. It manages component registration,
- * plugin integration, lifecycle hooks, event handling, and DOM rendering.
+ * @example
+ * // Using lifecycle hooks
+ * app.component("lifecycleDemo", {
+ *   setup: () => {
+ *     return {
+ *       onMount: ({ container, context }) => {
+ *         console.log('Component mounted!');
+ *       }
+ *     };
+ *   },
+ *   template: `<div>Lifecycle Demo</div>`
+ * });
  */
 export class Eleva {
     /**
-     * Creates a new Eleva instance.
+     * Creates a new Eleva instance with the specified name and configuration.
+     *
+     * @public
+     * @param {string} name - The unique identifier name for this Eleva instance.
+     * @param {Record<string, unknown>} [config={}] - Optional configuration object for the instance.
+     *        May include framework-wide settings and default behaviors.
+     * @throws {Error} If the name is not provided or is not a string.
+     * @returns {Eleva} A new Eleva instance.
+     *
+     * @example
+     * const app = new Eleva("myApp");
+     * app.component("myComponent", {
+     *   setup: (ctx) => ({ count: ctx.signal(0) }),
+     *   template: (ctx) => `<div>Hello ${ctx.props.name}!</div>`
+     * });
+     * app.mount(document.getElementById("app"), "myComponent", { name: "World" });
      *
-     * @param {string} name - The name of the Eleva instance.
-     * @param {object} [config={}] - Optional configuration for the instance.
      */
-    constructor(name: string, config?: object);
-    name: string;
-    config: object;
-    _components: {};
-    _plugins: any[];
-    _lifecycleHooks: string[];
-    _isMounted: boolean;
-    emitter: Emitter;
-    renderer: Renderer;
+    constructor(name: string, config?: Record<string, unknown>);
+    /** @public {string} The unique identifier name for this Eleva instance */
+    public name: string;
+    /** @public {Object<string, unknown>} Optional configuration object for the Eleva instance */
+    public config: Record<string, unknown>;
+    /** @public {Emitter} Instance of the event emitter for handling component events */
+    public emitter: Emitter;
+    /** @public {typeof Signal} Static reference to the Signal class for creating reactive state */
+    public signal: typeof Signal;
+    /** @public {Renderer} Instance of the renderer for handling DOM updates and patching */
+    public renderer: Renderer;
+    /** @private {Map<string, ComponentDefinition>} Registry of all component definitions by name */
+    private _components;
+    /** @private {Map<string, ElevaPlugin>} Collection of installed plugin instances by name */
+    private _plugins;
+    /** @private {boolean} Flag indicating if the root component is currently mounted */
+    private _isMounted;
+    /** @private {number} Counter for generating unique component IDs */
+    private _componentCounter;
     /**
      * Integrates a plugin with the Eleva framework.
+     * The plugin's install function will be called with the Eleva instance and provided options.
+     * After installation, the plugin will be available for use by components.
      *
-     * @param {object} [plugin] - The plugin object which should have an install function.
-     * @param {object} [options={}] - Optional options to pass to the plugin.
-     * @returns {Eleva} The Eleva instance (for chaining).
+     * @public
+     * @param {ElevaPlugin} plugin - The plugin object which must have an `install` function.
+     * @param {Object<string, unknown>} [options={}] - Optional configuration options for the plugin.
+     * @returns {Eleva} The Eleva instance (for method chaining).
+     * @example
+     * app.use(myPlugin, { option1: "value1" });
      */
-    use(plugin?: object, options?: object): Eleva;
+    public use(plugin: ElevaPlugin, options?: {
+        [x: string]: unknown;
+    }): Eleva;
     /**
-     * Registers a component with the Eleva instance.
+     * Registers a new component with the Eleva instance.
+     * The component will be available for mounting using its registered name.
      *
-     * @param {string} name - The name of the component.
-     * @param {object} definition - The component definition including setup, template, style, and children.
-     * @returns {Eleva} The Eleva instance (for chaining).
+     * @public
+     * @param {string} name - The unique name of the component to register.
+     * @param {ComponentDefinition} definition - The component definition including setup, template, style, and children.
+     * @returns {Eleva} The Eleva instance (for method chaining).
+     * @throws {Error} If the component name is already registered.
+     * @example
+     * app.component("myButton", {
+     *   template: (ctx) => `<button>${ctx.props.text}</button>`,
+     *   style: `button { color: blue; }`
+     * });
      */
-    component(name: string, definition: object): Eleva;
+    public component(name: string, definition: ComponentDefinition): Eleva;
     /**
      * Mounts a registered component to a DOM element.
+     * This will initialize the component, set up its reactive state, and render it to the DOM.
      *
-     * @param {string|HTMLElement} selectorOrElement - A CSS selector string or DOM element where the component will be mounted.
-     * @param {string} compName - The name of the component to mount.
-     * @param {object} [props={}] - Optional properties to pass to the component.
-     * @returns {object|Promise<object>} An object representing the mounted component instance, or a Promise that resolves to it for asynchronous setups.
-     * @throws Will throw an error if the container or component is not found.
+     * @public
+     * @param {HTMLElement} container - The DOM element where the component will be mounted.
+     * @param {string|ComponentDefinition} compName - The name of the registered component or a direct component definition.
+     * @param {Object<string, unknown>} [props={}] - Optional properties to pass to the component.
+     * @returns {Promise<MountResult>}
+     *          A Promise that resolves to an object containing:
+     *          - container: The mounted component's container element
+     *          - data: The component's reactive state and context
+     *          - unmount: Function to clean up and unmount the component
+     * @throws {Error} If the container is not found, or component is not registered.
+     * @example
+     * const instance = await app.mount(document.getElementById("app"), "myComponent", { text: "Click me" });
+     * // Later...
+     * instance.unmount();
      */
-    mount(selectorOrElement: string | HTMLElement, compName: string, props?: object): object | Promise<object>;
-    /**
-     * Prepares default no-operation lifecycle hook functions.
-     *
-     * @returns {object} An object with keys for lifecycle hooks mapped to empty functions.
-     * @private
-     */
-    private _prepareLifecycleHooks;
+    public mount(container: HTMLElement, compName: string | ComponentDefinition, props?: {
+        [x: string]: unknown;
+    }): Promise<MountResult>;
     /**
      * Processes DOM elements for event binding based on attributes starting with "@".
+     * This method handles the event delegation system and ensures proper cleanup of event listeners.
      *
-     * @param {HTMLElement} container - The container element in which to search for events.
-     * @param {object} context - The current context containing event handler definitions.
      * @private
+     * @param {HTMLElement} container - The container element in which to search for event attributes.
+     * @param {ComponentContext} context - The current component context containing event handler definitions.
+     * @param {Array<() => void>} listeners - Array to collect cleanup functions for each event listener.
+     * @returns {void}
      */
     private _processEvents;
     /**
      * Injects scoped styles into the component's container.
+     * The styles are automatically prefixed to prevent style leakage to other components.
      *
-     * @param {HTMLElement} container - The container element.
-     * @param {string} compName - The component name used to identify the style element.
-     * @param {Function} styleFn - A function that returns CSS styles as a string.
-     * @param {object} context - The current context for style interpolation.
      * @private
+     * @param {HTMLElement} container - The container element where styles should be injected.
+     * @param {string} compId - The component ID used to identify the style element.
+     * @param {(function(ComponentContext): string)|string} styleDef - The component's style definition (function or string).
+     * @param {ComponentContext} context - The current component context for style interpolation.
+     * @returns {void}
      */
     private _injectStyles;
     /**
-     * Mounts child components within the parent component's container.
+     * Extracts props from an element's attributes that start with the specified prefix.
+     * This method is used to collect component properties from DOM elements.
      *
-     * @param {HTMLElement} container - The parent container element.
-     * @param {object} children - An object mapping child component selectors to their definitions.
-     * @param {Array} childInstances - An array to store the mounted child component instances.
      * @private
+     * @param {HTMLElement} element - The DOM element to extract props from
+     * @param {string} prefix - The prefix to look for in attributes
+     * @returns {Record<string, string>} An object containing the extracted props
+     * @example
+     * // For an element with attributes:
+     * // <div :name="John" :age="25">
+     * // Returns: { name: "John", age: "25" }
      */
-    private _mountChildren;
+    private _extractProps;
+    /**
+     * Mounts all components within the parent component's container.
+     * This method handles mounting of explicitly defined children components.
+     *
+     * The mounting process follows these steps:
+     * 1. Cleans up any existing component instances
+     * 2. Mounts explicitly defined children components
+     *
+     * @private
+     * @param {HTMLElement} container - The container element to mount components in
+     * @param {Object<string, ComponentDefinition>} children - Map of selectors to component definitions for explicit children
+     * @param {Array<MountResult>} childInstances - Array to store all mounted component instances
+     * @returns {Promise<void>}
+     *
+     * @example
+     * // Explicit children mounting:
+     * const children = {
+     *   'UserProfile': UserProfileComponent,
+     *   '#settings-panel': "settings-panel"
+     * };
+     */
+    private _mountComponents;
 }
+export type ComponentDefinition = {
+    /**
+     * Optional setup function that initializes the component's state and returns reactive data
+     */
+    setup?: ((arg0: ComponentContext) => (Record<string, unknown> | Promise<Record<string, unknown>>)) | undefined;
+    /**
+     *           Required function that defines the component's HTML structure
+     */
+    template: ((arg0: ComponentContext) => string | Promise<string>);
+    /**
+     * Optional function or string that provides component-scoped CSS styles
+     */
+    style?: string | ((arg0: ComponentContext) => string) | undefined;
+    /**
+     * Optional object defining nested child components
+     */
+    children?: Record<string, ComponentDefinition> | undefined;
+};
+export type ComponentContext = {
+    /**
+     *           Component properties passed during mounting
+     */
+    props: Record<string, unknown>;
+    /**
+     *           Event emitter instance for component event handling
+     */
+    emitter: Emitter;
+    /**
+     * <T>(value: T): Signal<T>} signal
+     * Factory function to create reactive Signal instances
+     */
+    "": Function;
+    /**
+     * Hook called before component mounting
+     */
+    onBeforeMount?: ((arg0: LifecycleHookContext) => Promise<void>) | undefined;
+    /**
+     * Hook called after component mounting
+     */
+    onMount?: ((arg0: LifecycleHookContext) => Promise<void>) | undefined;
+    /**
+     * Hook called before component update
+     */
+    onBeforeUpdate?: ((arg0: LifecycleHookContext) => Promise<void>) | undefined;
+    /**
+     * Hook called after component update
+     */
+    onUpdate?: ((arg0: LifecycleHookContext) => Promise<void>) | undefined;
+    /**
+     * Hook called during component unmounting
+     */
+    onUnmount?: ((arg0: UnmountHookContext) => Promise<void>) | undefined;
+};
+export type LifecycleHookContext = {
+    /**
+     *           The DOM element where the component is mounted
+     */
+    container: HTMLElement;
+    /**
+     *           The component's reactive state and context data
+     */
+    context: ComponentContext;
+};
+export type UnmountHookContext = {
+    /**
+     *           The DOM element where the component is mounted
+     */
+    container: HTMLElement;
+    /**
+     *           The component's reactive state and context data
+     */
+    context: ComponentContext;
+    /**
+     *           Object containing cleanup functions and instances
+     */
+    cleanup: {
+        watchers: Array<() => void>;
+        listeners: Array<() => void>;
+        children: Array<MountResult>;
+    };
+};
+export type MountResult = {
+    /**
+     *           The DOM element where the component is mounted
+     */
+    container: HTMLElement;
+    /**
+     *           The component's reactive state and context data
+     */
+    data: ComponentContext;
+    /**
+     *           Function to clean up and unmount the component
+     */
+    unmount: () => Promise<void>;
+};
+export type ElevaPlugin = {
+    /**
+     *           Function that installs the plugin into the Eleva instance
+     */
+    install: (arg0: Eleva, arg1: Record<string, unknown>) => void;
+    /**
+     *           Unique identifier name for the plugin
+     */
+    name: string;
+};
 import { Emitter } from "../modules/Emitter.js";
+import { Signal } from "../modules/Signal.js";
 import { Renderer } from "../modules/Renderer.js";
 //# sourceMappingURL=Eleva.d.ts.map

package/types/core/Eleva.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Eleva.d.ts","sourceRoot":"","sources":["../../src/core/Eleva.js"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH;IACE;;;;;OAKG;IACH,kBAHW,MAAM,WACN,MAAM,EAiBhB;IAdC,aAAgB;IAChB,eAAoB;IACpB,gBAAqB;IACrB,gBAAkB;IAClB,0BAMC;IACD,oBAAuB;IACvB,iBAA4B;IAC5B,mBAA8B;IAGhC;;;;;;OAMG;IACH,aAJW,MAAM,YACN,MAAM,GACJ,KAAK,CAQjB;IAED;;;;;;OAMG;IACH,gBAJW,MAAM,cACN,MAAM,GACJ,KAAK,CAKjB;IAED;;;;;;;;OAQG;IACH,yBANW,MAAM,GAAC,WAAW,YAClB,MAAM,UACN,MAAM,GACJ,MAAM,GAAC,OAAO,CAAC,MAAM,CAAC,CA0FlC;IAED;;;;;OAKG;IACH,+BAKC;IAED;;;;;;OAMG;IACH,uBAaC;IAED;;;;;;;;OAQG;IACH,sBAYC;IAED;;;;;;;OAOG;IACH,uBAgBC;CACF;wBAjPuB,uBAAuB;yBACtB,wBAAwB"}
+{"version":3,"file":"Eleva.d.ts","sourceRoot":"","sources":["../../src/core/Eleva.js"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AAEH;;;;;;;;GAQG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IACE;;;;;;;;;;;;;;;;;;OAkBG;IACH,kBAfW,MAAM,WACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAkCjC;IAnBC,0EAA0E;IAC1E,oBAAgB;IAChB,6FAA6F;IAC7F,uCAAoB;IACpB,oFAAoF;IACpF,wBAA4B;IAC5B,+FAA+F;IAC/F,6BAAoB;IACpB,wFAAwF;IACxF,0BAA8B;IAE9B,gGAAgG;IAChG,oBAA4B;IAC5B,2FAA2F;IAC3F,iBAAyB;IACzB,oFAAoF;IACpF,mBAAuB;IACvB,oEAAoE;IACpE,0BAA0B;IAG5B;;;;;;;;;;;OAWG;IACH,mBANW,WAAW;;QAET,KAAK,CASjB;IAED;;;;;;;;;;;;;;OAcG;IACH,uBAVW,MAAM,cACN,mBAAmB,GACjB,KAAK,CAYjB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,wBAdW,WAAW,YACX,MAAM,GAAC,mBAAmB;;QAExB,OAAO,CAAC,WAAW,CAAC,CA+JhC;IAED;;;;;;;;;OASG;IACH,uBA0BC;IAED;;;;;;;;;;OAUG;IACH,sBAkBC;IAED;;;;;;;;;;;;OAYG;IACH,sBAeC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,yBAcC;CACF;;;;;oBApesB,gBAAgB,KAAG,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;;;;cAEtF,CAAC,CAAS,IAAgB,EAAhB,gBAAgB,KAAG,MAAM,GAAC,OAAO,CAAC,MAAM,CAAC,CAAC;;;;6BAE1C,gBAAgB,KAAG,MAAM;;;;;;;;;;WAQnC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;aAEvB,OAAO;;;;;;;;;4BAIE,oBAAoB,KAAG,OAAO,CAAC,IAAI,CAAC;;;;sBAEpC,oBAAoB,KAAG,OAAO,CAAC,IAAI,CAAC;;;;6BAEpC,oBAAoB,KAAG,OAAO,CAAC,IAAI,CAAC;;;;uBAEpC,oBAAoB,KAAG,OAAO,CAAC,IAAI,CAAC;;;;wBAEpC,kBAAkB,KAAG,OAAO,CAAC,IAAI,CAAC;;;;;;eAM3C,WAAW;;;;aAEX,gBAAgB;;;;;;eAMhB,WAAW;;;;aAEX,gBAAgB;;;;aAEhB;QACT,QAAQ,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;QAC5B,SAAS,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;QAC7B,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,CAAA;KAC7B;;;;;;eAMU,WAAW;;;;UAEX,gBAAgB;;;;aAEhB,MAAY,OAAO,CAAC,IAAI,CAAC;;;;;;aAMzB,CAAS,IAAK,EAAL,KAAK,EAAE,IAAuB,EAAvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAAI;;;;UAE9C,MAAM;;wBAvEI,uBAAuB;uBADxB,sBAAsB;yBAEpB,wBAAwB"}

package/types/modules/Emitter.d.ts

@@ -1,34 +1,66 @@
 /**
- * 🎙️ Emitter: Robust inter-component communication with event bubbling.
+ * @class 📡 Emitter
+ * @classdesc A robust event emitter that enables inter-component communication through a publish-subscribe pattern.
+ * Components can emit events and listen for events from other components, facilitating loose coupling
+ * and reactive updates across the application.
+ * Events are handled synchronously in the order they were registered, with proper cleanup
+ * of unsubscribed handlers.
+ * Event names should follow the format 'namespace:action' (e.g., 'user:login', 'cart:update').
  *
- * Implements a basic publish-subscribe pattern for event handling,
- * allowing components to communicate through custom events.
+ * @example
+ * const emitter = new Emitter();
+ * emitter.on('user:login', (user) => console.log(`User logged in: ${user.name}`));
+ * emitter.emit('user:login', { name: 'John' }); // Logs: "User logged in: John"
  */
 export class Emitter {
-    /** @type {Object.<string, Function[]>} */
-    events: {
-        [x: string]: Function[];
-    };
+    /** @private {Map<string, Set<(data: unknown) => void>>} Map of event names to their registered handler functions */
+    private _events;
     /**
-     * Registers an event handler for the specified event.
+     * Registers an event handler for the specified event name.
+     * The handler will be called with the event data when the event is emitted.
+     * Event names should follow the format 'namespace:action' for consistency.
      *
-     * @param {string} event - The name of the event.
-     * @param {Function} handler - The function to call when the event is emitted.
+     * @public
+     * @param {string} event - The name of the event to listen for (e.g., 'user:login').
+     * @param {(data: unknown) => void} handler - The callback function to invoke when the event occurs.
+     * @returns {() => void} A function to unsubscribe the event handler.
+     * @example
+     * const unsubscribe = emitter.on('user:login', (user) => console.log(user));
+     * // Later...
+     * unsubscribe(); // Stops listening for the event
      */
-    on(event: string, handler: Function): void;
+    public on(event: string, handler: (data: unknown) => void): () => void;
     /**
-     * Removes a previously registered event handler.
+     * Removes an event handler for the specified event name.
+     * If no handler is provided, all handlers for the event are removed.
+     * Automatically cleans up empty event sets to prevent memory leaks.
      *
-     * @param {string} event - The name of the event.
-     * @param {Function} handler - The handler function to remove.
+     * @public
+     * @param {string} event - The name of the event to remove handlers from.
+     * @param {(data: unknown) => void} [handler] - The specific handler function to remove.
+     * @returns {void}
+     * @example
+     * // Remove a specific handler
+     * emitter.off('user:login', loginHandler);
+     * // Remove all handlers for an event
+     * emitter.off('user:login');
      */
-    off(event: string, handler: Function): void;
+    public off(event: string, handler?: (data: unknown) => void): void;
     /**
-     * Emits an event, invoking all handlers registered for that event.
+     * Emits an event with the specified data to all registered handlers.
+     * Handlers are called synchronously in the order they were registered.
+     * If no handlers are registered for the event, the emission is silently ignored.
      *
-     * @param {string} event - The event name.
-     * @param {...*} args - Additional arguments to pass to the event handlers.
+     * @public
+     * @param {string} event - The name of the event to emit.
+     * @param {...unknown} args - Optional arguments to pass to the event handlers.
+     * @returns {void}
+     * @example
+     * // Emit an event with data
+     * emitter.emit('user:login', { name: 'John', role: 'admin' });
+     * // Emit an event with multiple arguments
+     * emitter.emit('cart:update', { items: [] }, { total: 0 });
      */
-    emit(event: string, ...args: any[]): void;
+    public emit(event: string, ...args: unknown[]): void;
 }
 //# sourceMappingURL=Emitter.d.ts.map

package/types/modules/Emitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Emitter.d.ts","sourceRoot":"","sources":["../../src/modules/Emitter.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;IAKI,0CAA0C;IAC1C;;MAAgB;IAGlB;;;;;OAKG;IACH,UAHW,MAAM,2BAKhB;IAED;;;;;OAKG;IACH,WAHW,MAAM,2BAOhB;IAED;;;;;OAKG;IACH,YAHW,MAAM,WACH,GAAC,EAAA,QAId;CACF"}
+{"version":3,"file":"Emitter.d.ts","sourceRoot":"","sources":["../../src/modules/Emitter.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH;IAOI,oHAAoH;IACpH,gBAAwB;IAG1B;;;;;;;;;;;;;OAaG;IACH,iBARW,MAAM,WACN,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GACrB,MAAM,IAAI,CAWtB;IAED;;;;;;;;;;;;;;OAcG;IACH,kBATW,MAAM,YACN,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GACrB,IAAI,CAiBhB;IAED;;;;;;;;;;;;;;OAcG;IACH,mBATW,MAAM,WACH,OAAO,EAAA,GACR,IAAI,CAUhB;CACF"}