@estjs/template 0.0.15-beta.13 → 0.0.15-beta.14

package/dist/template.d.cts

@@ -24,30 +24,16 @@ declare function provide<T>(key: InjectionKey<T> | string | number, value: T): v
  */
 declare function inject<T>(key: InjectionKey<T> | string | number, defaultValue?: T): T;
 
-/**
- * Scope represents an execution context in the component tree.
- * It manages provides, cleanup functions, and lifecycle hooks.
- */
 interface Scope {
-    /** Unique identifier for debugging */
     readonly id: number;
-    /** Parent scope in the hierarchy */
     parent: Scope | null;
-    /** Child scopes (lazy initialized) */
-    children: Set<Scope> | null;
-    /** Provided values (lazy initialized) */
+    children: Scope[] | null;
     provides: Map<InjectionKey<unknown> | string | number | symbol, unknown> | null;
-    /** Cleanup functions (lazy initialized) */
-    cleanup: Set<() => void> | null;
-    /** Mount lifecycle hooks (lazy initialized) */
-    onMount: Set<() => void | Promise<void>> | null;
-    /** Update lifecycle hooks (lazy initialized) */
-    onUpdate: Set<() => void | Promise<void>> | null;
-    /** Destroy lifecycle hooks (lazy initialized) */
-    onDestroy: Set<() => void | Promise<void>> | null;
-    /** Whether the scope has been mounted */
+    cleanup: (() => void)[] | null;
+    onMount: (() => void | Promise<void>)[] | null;
+    onUpdate: (() => void | Promise<void>)[] | null;
+    onDestroy: (() => void | Promise<void>)[] | null;
     isMounted: boolean;
-    /** Whether the scope has been destroyed */
     isDestroyed: boolean;
 }
 /**
@@ -60,13 +46,6 @@ declare function getActiveScope(): Scope | null;
  * @param scope - The scope to set as active
  */
 declare function setActiveScope(scope: Scope | null): void;
-/**
- * Create a new scope with optional parent.
- * If no parent is provided, uses the current active scope as parent.
- *
- * @param parent - Optional parent scope (defaults to active scope)
- * @returns A new scope instance
- */
 declare function createScope(parent?: Scope | null): Scope;
 /**
  * Run a function within a scope, ensuring proper cleanup.
@@ -78,17 +57,42 @@ declare function createScope(parent?: Scope | null): Scope;
  */
 declare function runWithScope<T>(scope: Scope, fn: () => T): T;
 /**
- * Dispose a scope and all its children.
- * Children are disposed first (depth-first), then the scope itself.
+ * Dispose a scope and recursively dispose all child scopes.
+ * Performs the following cleanup in order:
+ * 1. Recursively disposes all children (depth-first)
+ * 2. Executes destroy lifecycle hooks
+ * 3. Executes registered cleanup functions
+ * 4. Removes scope from parent's children list
+ * 5. Clears all internal collections and resets state
+ *
+ * Safe to call multiple times (idempotent).
  *
  * @param scope - The scope to dispose
+ *
+ * @example
+ * ```ts
+ * const scope = createScope(parent);
+ * // ... use scope ...
+ * disposeScope(scope); // Cleanup everything
+ * ```
  */
 declare function disposeScope(scope: Scope): void;
 /**
- * Register a cleanup function in the current scope.
- * The function will be called when the scope is disposed.
+ * Register a cleanup function to be executed when the scope is disposed.
+ * Useful for cleaning up timers, subscriptions, event listeners, etc.
  *
- * @param fn - The cleanup function
+ * Cleanup functions are executed in LIFO order (last registered, first executed).
+ * Cleanup errors don't prevent other cleanups from running.
+ *
+ * @param fn - The cleanup function to register
+ *
+ * @throws Error in dev mode if called outside a scope
+ *
+ * @example
+ * ```ts
+ * const timerId = setInterval(() => {}, 1000);
+ * onCleanup(() => clearInterval(timerId));
+ * ```
  */
 declare function onCleanup(fn: () => void): void;
 
@@ -170,28 +174,54 @@ declare function template(html: string): () => Node;
  */
 declare function createApp<P extends ComponentProps = {}>(component: ComponentFn<P> | Component<P>, target: string | Element): Component<P> | undefined;
 
+/**
+ * Lifecycle hook type: returns void or a Promise that resolves when complete.
+ * Hooks can perform cleanup by returning a cleanup function.
+ */
 type LifecycleHook = () => void | Promise<void>;
 /**
  * Register a mount lifecycle hook.
- * Called after the component is mounted to the DOM.
+ * Runs after component is mounted and virtual tree is committed.
+ * If the scope is already mounted, the hook executes immediately.
  *
- * @param hook - The hook function to execute on mount
+ * @throws Error in dev mode if called outside a scope
+ * @example
+ * ```tsx
+ * onMount(() => {
+ *   console.log('Component mounted');
+ *   return () => console.log('Cleanup');
+ * });
+ * ```
  */
 declare function onMount(hook: LifecycleHook): void;
 /**
- * Register a destroy lifecycle hook.
- * Called before the component is removed from the DOM.
+ * Register an update lifecycle hook.
+ * Runs whenever the component re-renders due to prop or state changes.
  *
- * @param hook - The hook function to execute on destroy
+ * @throws Error in dev mode if called outside a scope
+ * @example
+ * ```tsx
+ * onUpdate(() => {
+ *   console.log('Component updated');
+ * });
+ * ```
  */
-declare function onDestroy(hook: LifecycleHook): void;
+declare function onUpdate(hook: LifecycleHook): void;
 /**
- * Register an update lifecycle hook.
- * Called after the component updates.
+ * Register a destroy lifecycle hook.
+ * Runs before scope is disposed and resources are cleaned up.
+ * Perfect for resetting external state, unsubscribing from events, etc.
  *
- * @param hook - The hook function to execute on update
+ * @throws Error in dev mode if called outside a scope
+ * @example
+ * ```tsx
+ * onDestroy(() => {
+ *   unsubscribe();
+ *   clearTimeout(timerId);
+ * });
+ * ```
  */
-declare function onUpdate(hook: LifecycleHook): void;
+declare function onDestroy(hook: LifecycleHook): void;
 
 /**
  * Add event listener with automatic cleanup on scope destruction
@@ -217,7 +247,6 @@ declare function bindElement(node: Element, key: string, defaultValue: unknown,
  * @param parent Parent node
  * @param nodeFactory Node factory function or static node
  * @param before Reference node for insertion position
- * @param options Insertion options
  *
  * @example
  * ```typescript

package/dist/template.d.ts

@@ -24,30 +24,16 @@ declare function provide<T>(key: InjectionKey<T> | string | number, value: T): v
  */
 declare function inject<T>(key: InjectionKey<T> | string | number, defaultValue?: T): T;
 
-/**
- * Scope represents an execution context in the component tree.
- * It manages provides, cleanup functions, and lifecycle hooks.
- */
 interface Scope {
-    /** Unique identifier for debugging */
     readonly id: number;
-    /** Parent scope in the hierarchy */
     parent: Scope | null;
-    /** Child scopes (lazy initialized) */
-    children: Set<Scope> | null;
-    /** Provided values (lazy initialized) */
+    children: Scope[] | null;
     provides: Map<InjectionKey<unknown> | string | number | symbol, unknown> | null;
-    /** Cleanup functions (lazy initialized) */
-    cleanup: Set<() => void> | null;
-    /** Mount lifecycle hooks (lazy initialized) */
-    onMount: Set<() => void | Promise<void>> | null;
-    /** Update lifecycle hooks (lazy initialized) */
-    onUpdate: Set<() => void | Promise<void>> | null;
-    /** Destroy lifecycle hooks (lazy initialized) */
-    onDestroy: Set<() => void | Promise<void>> | null;
-    /** Whether the scope has been mounted */
+    cleanup: (() => void)[] | null;
+    onMount: (() => void | Promise<void>)[] | null;
+    onUpdate: (() => void | Promise<void>)[] | null;
+    onDestroy: (() => void | Promise<void>)[] | null;
     isMounted: boolean;
-    /** Whether the scope has been destroyed */
     isDestroyed: boolean;
 }
 /**
@@ -60,13 +46,6 @@ declare function getActiveScope(): Scope | null;
  * @param scope - The scope to set as active
  */
 declare function setActiveScope(scope: Scope | null): void;
-/**
- * Create a new scope with optional parent.
- * If no parent is provided, uses the current active scope as parent.
- *
- * @param parent - Optional parent scope (defaults to active scope)
- * @returns A new scope instance
- */
 declare function createScope(parent?: Scope | null): Scope;
 /**
  * Run a function within a scope, ensuring proper cleanup.
@@ -78,17 +57,42 @@ declare function createScope(parent?: Scope | null): Scope;
  */
 declare function runWithScope<T>(scope: Scope, fn: () => T): T;
 /**
- * Dispose a scope and all its children.
- * Children are disposed first (depth-first), then the scope itself.
+ * Dispose a scope and recursively dispose all child scopes.
+ * Performs the following cleanup in order:
+ * 1. Recursively disposes all children (depth-first)
+ * 2. Executes destroy lifecycle hooks
+ * 3. Executes registered cleanup functions
+ * 4. Removes scope from parent's children list
+ * 5. Clears all internal collections and resets state
+ *
+ * Safe to call multiple times (idempotent).
  *
  * @param scope - The scope to dispose
+ *
+ * @example
+ * ```ts
+ * const scope = createScope(parent);
+ * // ... use scope ...
+ * disposeScope(scope); // Cleanup everything
+ * ```
  */
 declare function disposeScope(scope: Scope): void;
 /**
- * Register a cleanup function in the current scope.
- * The function will be called when the scope is disposed.
+ * Register a cleanup function to be executed when the scope is disposed.
+ * Useful for cleaning up timers, subscriptions, event listeners, etc.
  *
- * @param fn - The cleanup function
+ * Cleanup functions are executed in LIFO order (last registered, first executed).
+ * Cleanup errors don't prevent other cleanups from running.
+ *
+ * @param fn - The cleanup function to register
+ *
+ * @throws Error in dev mode if called outside a scope
+ *
+ * @example
+ * ```ts
+ * const timerId = setInterval(() => {}, 1000);
+ * onCleanup(() => clearInterval(timerId));
+ * ```
  */
 declare function onCleanup(fn: () => void): void;
 
@@ -170,28 +174,54 @@ declare function template(html: string): () => Node;
  */
 declare function createApp<P extends ComponentProps = {}>(component: ComponentFn<P> | Component<P>, target: string | Element): Component<P> | undefined;
 
+/**
+ * Lifecycle hook type: returns void or a Promise that resolves when complete.
+ * Hooks can perform cleanup by returning a cleanup function.
+ */
 type LifecycleHook = () => void | Promise<void>;
 /**
  * Register a mount lifecycle hook.
- * Called after the component is mounted to the DOM.
+ * Runs after component is mounted and virtual tree is committed.
+ * If the scope is already mounted, the hook executes immediately.
  *
- * @param hook - The hook function to execute on mount
+ * @throws Error in dev mode if called outside a scope
+ * @example
+ * ```tsx
+ * onMount(() => {
+ *   console.log('Component mounted');
+ *   return () => console.log('Cleanup');
+ * });
+ * ```
  */
 declare function onMount(hook: LifecycleHook): void;
 /**
- * Register a destroy lifecycle hook.
- * Called before the component is removed from the DOM.
+ * Register an update lifecycle hook.
+ * Runs whenever the component re-renders due to prop or state changes.
  *
- * @param hook - The hook function to execute on destroy
+ * @throws Error in dev mode if called outside a scope
+ * @example
+ * ```tsx
+ * onUpdate(() => {
+ *   console.log('Component updated');
+ * });
+ * ```
  */
-declare function onDestroy(hook: LifecycleHook): void;
+declare function onUpdate(hook: LifecycleHook): void;
 /**
- * Register an update lifecycle hook.
- * Called after the component updates.
+ * Register a destroy lifecycle hook.
+ * Runs before scope is disposed and resources are cleaned up.
+ * Perfect for resetting external state, unsubscribing from events, etc.
  *
- * @param hook - The hook function to execute on update
+ * @throws Error in dev mode if called outside a scope
+ * @example
+ * ```tsx
+ * onDestroy(() => {
+ *   unsubscribe();
+ *   clearTimeout(timerId);
+ * });
+ * ```
  */
-declare function onUpdate(hook: LifecycleHook): void;
+declare function onDestroy(hook: LifecycleHook): void;
 
 /**
  * Add event listener with automatic cleanup on scope destruction
@@ -217,7 +247,6 @@ declare function bindElement(node: Element, key: string, defaultValue: unknown,
  * @param parent Parent node
  * @param nodeFactory Node factory function or static node
  * @param before Reference node for insertion position
- * @param options Insertion options
  *
  * @example
  * ```typescript

package/dist/template.dev.cjs.js

@@ -39,6 +39,108 @@ var __async = (__this, __arguments, generator) => {
     step((generator = generator.apply(__this, __arguments)).next());
   });
 };
+var LIFECYCLE = {
+  mount: "mount",
+  destroy: "destroy",
+  update: "update"
+};
+function registerScopedHook(scope, listKey, hook) {
+  let hookList = scope[listKey];
+  if (!hookList) {
+    hookList = scope[listKey] = [];
+  }
+  if (!hookList.includes(hook)) {
+    hookList.push(hook);
+  }
+}
+function executeHooks(hooks, scopeId2, phase) {
+  const len = hooks.length;
+  if (len === 0) return;
+  let pending;
+  for (let i = 0; i < len; i++) {
+    try {
+      const result = hooks[i]();
+      if (shared.isPromise(result)) {
+        const safePromise = result.catch((error_) => {
+          if (true) {
+            shared.error(`Scope(${scopeId2}): Async ${phase} hook rejected:`, error_);
+          }
+        });
+        (pending != null ? pending : pending = []).push(safePromise);
+      }
+    } catch (error_) {
+      {
+        shared.error(`Scope(${scopeId2}): Error in ${phase} hook:`, error_);
+      }
+    }
+  }
+  if (!pending) return;
+  return Promise.all(pending).then(() => void 0);
+}
+function onMount(hook) {
+  const scope = getActiveScope();
+  if (!scope) {
+    shared.error("onMount() must be called within a scope");
+    return;
+  }
+  if (scope.isMounted) {
+    try {
+      const result = hook();
+      if (shared.isPromise(result)) {
+        result.catch((error_) => {
+          if (true) shared.error(`Scope(${scope.id}): Async ${LIFECYCLE.mount} hook rejected:`, error_);
+        });
+      }
+    } catch (error_) {
+      shared.error(`Scope(${scope.id}): Error in ${LIFECYCLE.mount} hook:`, error_);
+    }
+    return;
+  }
+  registerScopedHook(scope, "onMount", hook);
+}
+function onUpdate(hook) {
+  const scope = getActiveScope();
+  if (!scope) {
+    shared.error("onUpdate() must be called within a scope");
+    return;
+  }
+  registerScopedHook(scope, "onUpdate", hook);
+}
+function onDestroy(hook) {
+  const scope = getActiveScope();
+  if (!scope) {
+    shared.error("onDestroy() must be called within a scope");
+    return;
+  }
+  registerScopedHook(scope, "onDestroy", hook);
+}
+function triggerMountHooks(scope) {
+  var _a2;
+  if (scope.isDestroyed || !((_a2 = scope.onMount) == null ? void 0 : _a2.length)) {
+    scope.isMounted = true;
+    return;
+  }
+  const mountHooks = scope.onMount;
+  const result = runWithScope(scope, () => executeHooks(mountHooks, scope.id, LIFECYCLE.mount));
+  mountHooks.length = 0;
+  scope.isMounted = true;
+  return result;
+}
+function triggerUpdateHooks(scope) {
+  var _a2;
+  if (scope.isDestroyed || !((_a2 = scope.onUpdate) == null ? void 0 : _a2.length)) return;
+  const updateHooks = scope.onUpdate;
+  const result = runWithScope(scope, () => executeHooks(updateHooks, scope.id, "update"));
+  updateHooks.length = 0;
+  return result;
+}
+function triggerDestroyHooks(scope) {
+  var _a2;
+  if (scope.isDestroyed || !((_a2 = scope.onDestroy) == null ? void 0 : _a2.length)) return;
+  return runWithScope(scope, () => executeHooks(scope.onDestroy, scope.id, "destroy"));
+}
+
+// src/scope.ts
 var activeScope = null;
 var scopeId = 0;
 function getActiveScope() {
@@ -52,25 +154,19 @@ function createScope(parent = activeScope) {
     id: ++scopeId,
     parent,
     children: null,
-    // Lazy initialized
     provides: null,
-    // Lazy initialized
     cleanup: null,
-    // Lazy initialized
     onMount: null,
-    // Lazy initialized
     onUpdate: null,
-    // Lazy initialized
     onDestroy: null,
-    // Lazy initialized
     isMounted: false,
     isDestroyed: false
   };
   if (parent) {
     if (!parent.children) {
-      parent.children = /* @__PURE__ */ new Set();
+      parent.children = [];
     }
-    parent.children.add(scope);
+    parent.children.push(scope);
   }
   return scope;
 }
@@ -84,31 +180,22 @@ function runWithScope(scope, fn) {
   }
 }
 function disposeScope(scope) {
-  var _a2, _b, _c, _d, _e;
+  var _a2, _b, _c;
   if (!scope || scope.isDestroyed) {
     return;
   }
+  const parentScope = scope.parent;
   if (scope.children) {
-    while (scope.children.size > 0) {
-      const child = scope.children.values().next().value;
-      if (child) {
-        disposeScope(child);
-      }
+    for (const child of scope.children) {
+      disposeScope(child);
     }
+    scope.children.length = 0;
   }
-  if (scope.onDestroy) {
-    for (const hook of scope.onDestroy) {
-      try {
-        hook();
-      } catch (error_) {
-        {
-          shared.error(`Scope(${scope.id}): Error in destroy hook:`, error_);
-        }
-      }
-    }
-    scope.onDestroy.clear();
+  if ((_a2 = scope.onDestroy) == null ? void 0 : _a2.length) {
+    triggerDestroyHooks(scope);
+    scope.onDestroy.length = 0;
   }
-  if (scope.cleanup) {
+  if ((_b = scope.cleanup) == null ? void 0 : _b.length) {
     for (const fn of scope.cleanup) {
       try {
         fn();
@@ -118,18 +205,22 @@ function disposeScope(scope) {
         }
       }
     }
-    scope.cleanup.clear();
+    scope.cleanup.length = 0;
   }
-  if ((_a2 = scope.parent) == null ? void 0 : _a2.children) {
-    scope.parent.children.delete(scope);
+  if (parentScope == null ? void 0 : parentScope.children) {
+    const idx = parentScope.children.indexOf(scope);
+    if (idx !== -1) {
+      parentScope.children.splice(idx, 1);
+    }
   }
-  (_b = scope.children) == null ? void 0 : _b.clear();
   (_c = scope.provides) == null ? void 0 : _c.clear();
-  (_d = scope.onMount) == null ? void 0 : _d.clear();
-  (_e = scope.onUpdate) == null ? void 0 : _e.clear();
-  setActiveScope(scope.parent);
+  if (scope.onMount) scope.onMount.length = 0;
+  if (scope.onUpdate) scope.onUpdate.length = 0;
   scope.parent = null;
   scope.isDestroyed = true;
+  if (activeScope === scope) {
+    activeScope = parentScope;
+  }
 }
 function onCleanup(fn) {
   const scope = activeScope;
@@ -140,9 +231,9 @@ function onCleanup(fn) {
     return;
   }
   if (!scope.cleanup) {
-    scope.cleanup = /* @__PURE__ */ new Set();
+    scope.cleanup = [];
   }
-  scope.cleanup.add(fn);
+  scope.cleanup.push(fn);
 }
 
 // src/constants.ts
@@ -749,99 +840,6 @@ function mapNodes(template2, indexes) {
   walk(template2);
   return tree;
 }
-function registerMountHook(hook) {
-  const scope = getActiveScope();
-  if (!scope) {
-    {
-      shared.error("onMount() must be called within a scope");
-    }
-    return;
-  }
-  if (scope.isMounted) {
-    try {
-      hook();
-    } catch (error_) {
-      {
-        shared.error(`Scope(${scope.id}): Error in mount hook:`, error_);
-      }
-    }
-    return;
-  }
-  if (!scope.onMount) {
-    scope.onMount = /* @__PURE__ */ new Set();
-  }
-  scope.onMount.add(hook);
-}
-function registerUpdateHook(hook) {
-  const scope = getActiveScope();
-  if (!scope) {
-    {
-      shared.error("onUpdate() must be called within a scope");
-    }
-    return;
-  }
-  if (!scope.onUpdate) {
-    scope.onUpdate = /* @__PURE__ */ new Set();
-  }
-  scope.onUpdate.add(hook);
-}
-function registerDestroyHook(hook) {
-  const scope = getActiveScope();
-  if (!scope) {
-    {
-      shared.error("onDestroy() must be called within a scope");
-    }
-    return;
-  }
-  if (!scope.onDestroy) {
-    scope.onDestroy = /* @__PURE__ */ new Set();
-  }
-  scope.onDestroy.add(hook);
-}
-function triggerMountHooks(scope) {
-  if (!scope || scope.isDestroyed || scope.isMounted) {
-    return;
-  }
-  scope.isMounted = true;
-  if (scope.onMount) {
-    runWithScope(scope, () => {
-      for (const hook of scope.onMount) {
-        try {
-          hook();
-        } catch (error_) {
-          if (true) {
-            shared.error(`Scope(${scope.id}): Error in mount hook:`, error_);
-          }
-        }
-      }
-    });
-  }
-}
-function triggerUpdateHooks(scope) {
-  if (!scope || scope.isDestroyed) {
-    return;
-  }
-  if (scope.onUpdate) {
-    for (const hook of scope.onUpdate) {
-      try {
-        hook();
-      } catch (error_) {
-        {
-          shared.error(`Scope(${scope.id}): Error in update hook:`, error_);
-        }
-      }
-    }
-  }
-}
-function onMount(hook) {
-  registerMountHook(hook);
-}
-function onDestroy(hook) {
-  registerDestroyHook(hook);
-}
-function onUpdate(hook) {
-  registerUpdateHook(hook);
-}
 
 // src/component.ts
 var _a;
@@ -1586,7 +1584,7 @@ function Portal(props) {
     onMount(() => {
       const targetElement = shared.isString(props.target) ? document.querySelector(props.target) : props.target;
       if (!targetElement) {
-        {
+        if (true) {
           shared.warn(`[Portal] Target element not found: ${props.target}`);
         }
         return;