@estjs/template 0.0.15-beta.12 → 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.
+ *
+ * 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
+ * @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
@@ -578,4 +607,19 @@ interface ResourceOptions<T> {
  */
 declare function createResource<T>(fetcher: () => Promise<T>, options?: ResourceOptions<T>): [Resource<T>, ResourceActions<T>];
 
-export { Component, type ComponentFn, type ComponentProps, Fragment, type FragmentProps, type InjectionKey, Portal, type PortalProps, type Scope, Suspense, type SuspenseProps, addEvent, addEventListener, bindElement, createApp, createComponent, createResource, createScope, delegateEvents, disposeScope, endHydration, getActiveScope, getFirstDOMNode, getHydrationKey, getRenderedElement, hydrate, inject, insert, insertNode, isComponent, isFragment, isHydrating, isPortal, isSameNode, isSuspense, mapNodes, mapSSRNodes, normalizeClass, normalizeNode, omitProps, onCleanup, onDestroy, onMount, onUpdate, patchAttr, patchClass, patchStyle, provide, removeNode, replaceNode, resetHydrationKey, runWithScope, setActiveScope, setStyle, shallowCompare, startHydration, template };
+interface ForProps<T> {
+    each: T[] | Signal<T[]> | (() => T[]);
+    children: (item: T, index: number) => AnyNode;
+    keyFn?: (item: T) => unknown;
+    fallback?: () => AnyNode;
+}
+/**
+ * Optimized For Component
+ * - Uses createDetachedScope to avoid parent.children Set overhead (SolidJS style)
+ * - Uses DocumentFragment batching for mass creation
+ * - Inlines scope switching for performance
+ */
+declare function For<T>(props: ForProps<T>): Node;
+declare namespace For { }
+
+export { Component, type ComponentFn, type ComponentProps, For, type ForProps, Fragment, type FragmentProps, type InjectionKey, Portal, type PortalProps, type Scope, Suspense, type SuspenseProps, addEvent, addEventListener, bindElement, createApp, createComponent, createResource, createScope, delegateEvents, disposeScope, endHydration, getActiveScope, getFirstDOMNode, getHydrationKey, getRenderedElement, hydrate, inject, insert, insertNode, isComponent, isFragment, isHydrating, isPortal, isSameNode, isSuspense, mapNodes, mapSSRNodes, normalizeClass, normalizeNode, omitProps, onCleanup, onDestroy, onMount, onUpdate, patchAttr, patchClass, patchStyle, provide, removeNode, replaceNode, resetHydrationKey, runWithScope, setActiveScope, setStyle, shallowCompare, startHydration, template };

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.
+ *
+ * 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
+ * @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
@@ -578,4 +607,19 @@ interface ResourceOptions<T> {
  */
 declare function createResource<T>(fetcher: () => Promise<T>, options?: ResourceOptions<T>): [Resource<T>, ResourceActions<T>];
 
-export { Component, type ComponentFn, type ComponentProps, Fragment, type FragmentProps, type InjectionKey, Portal, type PortalProps, type Scope, Suspense, type SuspenseProps, addEvent, addEventListener, bindElement, createApp, createComponent, createResource, createScope, delegateEvents, disposeScope, endHydration, getActiveScope, getFirstDOMNode, getHydrationKey, getRenderedElement, hydrate, inject, insert, insertNode, isComponent, isFragment, isHydrating, isPortal, isSameNode, isSuspense, mapNodes, mapSSRNodes, normalizeClass, normalizeNode, omitProps, onCleanup, onDestroy, onMount, onUpdate, patchAttr, patchClass, patchStyle, provide, removeNode, replaceNode, resetHydrationKey, runWithScope, setActiveScope, setStyle, shallowCompare, startHydration, template };
+interface ForProps<T> {
+    each: T[] | Signal<T[]> | (() => T[]);
+    children: (item: T, index: number) => AnyNode;
+    keyFn?: (item: T) => unknown;
+    fallback?: () => AnyNode;
+}
+/**
+ * Optimized For Component
+ * - Uses createDetachedScope to avoid parent.children Set overhead (SolidJS style)
+ * - Uses DocumentFragment batching for mass creation
+ * - Inlines scope switching for performance
+ */
+declare function For<T>(props: ForProps<T>): Node;
+declare namespace For { }
+
+export { Component, type ComponentFn, type ComponentProps, For, type ForProps, Fragment, type FragmentProps, type InjectionKey, Portal, type PortalProps, type Scope, Suspense, type SuspenseProps, addEvent, addEventListener, bindElement, createApp, createComponent, createResource, createScope, delegateEvents, disposeScope, endHydration, getActiveScope, getFirstDOMNode, getHydrationKey, getRenderedElement, hydrate, inject, insert, insertNode, isComponent, isFragment, isHydrating, isPortal, isSameNode, isSuspense, mapNodes, mapSSRNodes, normalizeClass, normalizeNode, omitProps, onCleanup, onDestroy, onMount, onUpdate, patchAttr, patchClass, patchStyle, provide, removeNode, replaceNode, resetHydrationKey, runWithScope, setActiveScope, setStyle, shallowCompare, startHydration, template };