pulse-js-framework 1.4.8 → 1.4.9

package/types/hmr.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Pulse Framework - HMR (Hot Module Replacement) Type Definitions
+ * @module pulse-js-framework/runtime/hmr
+ */
+
+import { Pulse, PulseOptions } from './pulse';
+
+/**
+ * HMR Context interface for state preservation and effect cleanup
+ */
+export interface HMRContext {
+  /**
+   * Persistent data storage across HMR updates.
+   * Values stored here survive module reloads.
+   */
+  data: Record<string, unknown>;
+
+  /**
+   * Create a pulse with state preservation across HMR updates.
+   * If a value exists from a previous module load, it's restored.
+   *
+   * @param key - Unique key for this pulse within the module
+   * @param initialValue - Initial value (used on first load only)
+   * @param options - Pulse options (equals function, etc.)
+   * @returns A pulse instance with preserved state
+   *
+   * @example
+   * const count = hmr.preservePulse('count', 0);
+   * const todos = hmr.preservePulse('todos', [], { equals: deepEquals });
+   */
+  preservePulse<T>(key: string, initialValue: T, options?: PulseOptions<T>): Pulse<T>;
+
+  /**
+   * Execute code with module tracking enabled.
+   * Effects created within this callback will be registered
+   * for automatic cleanup during HMR.
+   *
+   * @param callback - Code to execute with tracking
+   * @returns The return value of the callback
+   *
+   * @example
+   * hmr.setup(() => {
+   *   effect(() => {
+   *     document.title = `Count: ${count.get()}`;
+   *   });
+   * });
+   */
+  setup<T>(callback: () => T): T;
+
+  /**
+   * Register a callback to run when the module accepts an HMR update.
+   * Call without arguments to auto-accept updates.
+   *
+   * @param callback - Optional callback for custom handling
+   *
+   * @example
+   * hmr.accept(); // Auto-accept
+   * hmr.accept(() => console.log('Module updated!'));
+   */
+  accept(callback?: () => void): void;
+
+  /**
+   * Register a callback to run before the module is replaced.
+   * Use this for custom cleanup logic.
+   *
+   * @param callback - Cleanup callback
+   *
+   * @example
+   * hmr.dispose(() => {
+   *   socket.close();
+   *   clearInterval(timer);
+   * });
+   */
+  dispose(callback: () => void): void;
+}
+
+/**
+ * Create an HMR context for a module.
+ * Provides utilities for state preservation and effect cleanup during HMR.
+ *
+ * In production or non-HMR environments, returns a no-op context
+ * that works normally but without HMR-specific behavior.
+ *
+ * @param moduleId - The module identifier (typically import.meta.url)
+ * @returns HMR context with preservation utilities
+ *
+ * @example
+ * import { createHMRContext } from 'pulse-js-framework/runtime/hmr';
+ *
+ * const hmr = createHMRContext(import.meta.url);
+ *
+ * // Preserve state across HMR
+ * const todos = hmr.preservePulse('todos', []);
+ * const filter = hmr.preservePulse('filter', 'all');
+ *
+ * // Setup effects with automatic cleanup
+ * hmr.setup(() => {
+ *   effect(() => {
+ *     document.title = `${todos.get().length} todos`;
+ *   });
+ * });
+ *
+ * // Accept HMR updates
+ * hmr.accept();
+ */
+export function createHMRContext(moduleId: string): HMRContext;
+
+declare const hmr: {
+  createHMRContext: typeof createHMRContext;
+};
+
+export default hmr;

package/types/index.d.ts

@@ -90,8 +90,15 @@ export {
   LinkOptions,
   MatchedRoute,
   Router,
+  MiddlewareContext,
+  MiddlewareFn,
+  LazyOptions,
+  LazyRouteHandler,
+  RouteContext,
   createRouter,
-  simpleRouter
+  simpleRouter,
+  lazy,
+  preload
 } from './router';
 
 // Store
@@ -137,3 +144,20 @@ export {
   logger,
   loggers
 } from './logger';
+
+// HMR (Hot Module Replacement)
+export {
+  HMRContext,
+  createHMRContext
+} from './hmr';
+
+// Source Maps (Compiler)
+export {
+  Position,
+  Mapping,
+  SourceMapV3,
+  OriginalPosition,
+  SourceMapGenerator,
+  SourceMapConsumer,
+  encodeVLQ
+} from './sourcemap';

package/types/router.d.ts

@@ -69,12 +69,57 @@ export interface Routes {
   [path: string]: RouteHandler | RouteDefinition;
 }
 
+// =============================================================================
+// Middleware Types
+// =============================================================================
+
+/** Middleware context passed to each middleware function */
+export interface MiddlewareContext {
+  /** Target route */
+  to: NavigationTarget;
+  /** Source route */
+  from: NavigationTarget;
+  /** Shared metadata between middlewares */
+  meta: Record<string, unknown>;
+  /** Redirect to another path */
+  redirect(path: string): void;
+  /** Abort navigation */
+  abort(): void;
+}
+
+/** Middleware function */
+export type MiddlewareFn = (
+  ctx: MiddlewareContext,
+  next: () => Promise<void>
+) => void | Promise<void>;
+
+// =============================================================================
+// Lazy Loading Types
+// =============================================================================
+
+/** Lazy loading options */
+export interface LazyOptions {
+  /** Loading component shown while loading */
+  loading?: () => Node;
+  /** Error component shown on failure */
+  error?: (err: Error) => Node;
+  /** Timeout in milliseconds (default: 10000) */
+  timeout?: number;
+  /** Delay before showing loading component (default: 200) */
+  delay?: number;
+}
+
+/** Lazy route handler */
+export type LazyRouteHandler = (ctx: RouteContext) => Node;
+
 /** Router options */
 export interface RouterOptions {
   routes?: Routes;
   mode?: 'history' | 'hash';
   base?: string;
   scrollBehavior?: ScrollBehaviorFn;
+  /** Middleware functions */
+  middleware?: MiddlewareFn[];
 }
 
 /** Navigation options */
@@ -84,6 +129,15 @@ export interface NavigateOptions {
   state?: unknown;
 }
 
+/** Route context passed to route handlers */
+export interface RouteContext {
+  params: RouteParams;
+  query: QueryParams;
+  path: string;
+  navigate: Router['navigate'];
+  router: Router;
+}
+
 /** Link options */
 export interface LinkOptions {
   exact?: boolean;
@@ -141,6 +195,12 @@ export interface Router {
   /** Go to specific history entry */
   go(delta: number): void;
 
+  /**
+   * Add middleware dynamically
+   * @returns Unregister function
+   */
+  use(middleware: MiddlewareFn): () => void;
+
   /**
    * Add global before-navigation guard
    * @returns Unregister function
@@ -195,3 +255,32 @@ export declare function createRouter(options?: RouterOptions): Router;
  * Quick router setup (creates, starts, and mounts)
  */
 export declare function simpleRouter(routes: Routes, target?: string): Router;
+
+/**
+ * Create a lazy-loaded route handler
+ * Wraps a dynamic import with loading states and error handling
+ *
+ * @example
+ * const routes = {
+ *   '/dashboard': lazy(() => import('./Dashboard.js')),
+ *   '/settings': lazy(() => import('./Settings.js'), {
+ *     loading: () => el('div.spinner', 'Loading...'),
+ *     error: (err) => el('div.error', `Failed: ${err.message}`),
+ *     timeout: 5000
+ *   })
+ * };
+ */
+export declare function lazy(
+  importFn: () => Promise<{ default: RouteHandler | (() => Node) }>,
+  options?: LazyOptions
+): LazyRouteHandler;
+
+/**
+ * Preload a lazy component without rendering
+ * Useful for prefetching on hover or when likely to navigate
+ *
+ * @example
+ * const DashboardLazy = lazy(() => import('./Dashboard.js'));
+ * link.addEventListener('mouseenter', () => preload(DashboardLazy));
+ */
+export declare function preload(lazyHandler: LazyRouteHandler): Promise<void>;

package/types/sourcemap.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Pulse Framework - Source Map Type Definitions
+ * @module pulse-js-framework/compiler/sourcemap
+ */
+
+/** Source map position */
+export interface Position {
+  line: number;
+  column: number;
+}
+
+/** Source map mapping */
+export interface Mapping {
+  generated: Position;
+  original?: Position;
+  source?: string;
+  name?: string;
+}
+
+/** V3 Source Map format */
+export interface SourceMapV3 {
+  version: 3;
+  file: string;
+  sourceRoot: string;
+  sources: string[];
+  sourcesContent: (string | null)[];
+  names: string[];
+  mappings: string;
+}
+
+/** Original position result from consumer */
+export interface OriginalPosition {
+  source: string;
+  line: number;
+  column: number;
+  name: string | null;
+}
+
+/**
+ * Source Map Generator
+ * Generates V3 source maps for compiled .pulse files
+ */
+export declare class SourceMapGenerator {
+  /**
+   * Create a new source map generator
+   * @param options - Generator options
+   */
+  constructor(options?: {
+    file?: string;
+    sourceRoot?: string;
+  });
+
+  /**
+   * Add a source file
+   * @param source - Source file path
+   * @param content - Source file content (optional, for inline sources)
+   * @returns Source index
+   */
+  addSource(source: string, content?: string | null): number;
+
+  /**
+   * Add a name (identifier) to the names array
+   * @param name - Identifier name
+   * @returns Name index
+   */
+  addName(name: string): number;
+
+  /**
+   * Add a mapping between generated and original positions
+   * @param mapping - Mapping information
+   */
+  addMapping(mapping: Mapping): void;
+
+  /**
+   * Generate the source map object
+   * @returns V3 source map object
+   */
+  toJSON(): SourceMapV3;
+
+  /**
+   * Generate source map as JSON string
+   */
+  toString(): string;
+
+  /**
+   * Generate inline source map comment
+   * @returns Comment with base64 encoded source map
+   */
+  toComment(): string;
+
+  /**
+   * Generate external source map URL comment
+   * @param url - URL to source map file
+   */
+  static toURLComment(url: string): string;
+}
+
+/**
+ * Source Map Consumer
+ * Parse and query source maps for error stack trace translation
+ */
+export declare class SourceMapConsumer {
+  /**
+   * Create a new source map consumer
+   * @param sourceMap - Source map object or JSON string
+   */
+  constructor(sourceMap: SourceMapV3 | string);
+
+  /**
+   * Decode VLQ string to numbers
+   * @param str - VLQ encoded string
+   */
+  static decodeVLQ(str: string): number[];
+
+  /**
+   * Get original position for a generated position
+   * @param position - Generated position
+   * @returns Original position or null if not found
+   */
+  originalPositionFor(position: Position): OriginalPosition | null;
+}
+
+/**
+ * Encode a number as VLQ base64
+ */
+export declare function encodeVLQ(value: number): string;