@hypen-space/core 0.4.2 → 0.4.5

package/dist/retry.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Retry Utility for Network Operations
+ *
+ * Provides configurable retry logic with exponential/linear backoff
+ * for handling transient failures in network operations.
+ */
+import { type Result } from "./result.js";
+/**
+ * Options for retry behavior
+ */
+export interface RetryOptions {
+    /** Maximum number of attempts (default: 3) */
+    maxAttempts?: number;
+    /** Initial delay in milliseconds (default: 1000) */
+    delayMs?: number;
+    /** Backoff strategy (default: 'exponential') */
+    backoff?: "linear" | "exponential" | "none";
+    /** Maximum delay cap in milliseconds (default: 30000) */
+    maxDelayMs?: number;
+    /** Jitter factor 0-1 to randomize delays (default: 0.1) */
+    jitter?: number;
+    /** Callback on each retry attempt */
+    onRetry?: (attempt: number, error: Error, nextDelayMs: number) => void;
+    /** Optional predicate to determine if error is retryable */
+    shouldRetry?: (error: Error) => boolean;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Retry a function with configurable backoff
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const result = await retry(() => fetch('/api/data'));
+ *
+ * // With options
+ * const result = await retry(
+ *   () => fetch('/api/data'),
+ *   {
+ *     maxAttempts: 5,
+ *     delayMs: 2000,
+ *     backoff: 'exponential',
+ *     onRetry: (n, err) => console.log(`Attempt ${n} failed: ${err.message}`)
+ *   }
+ * );
+ * ```
+ */
+export declare function retry<T>(fn: () => T | Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Retry a function, returning a Result instead of throwing
+ *
+ * @example
+ * ```typescript
+ * const result = await retryResult(() => fetch('/api/data'));
+ * if (result.ok) {
+ *   console.log('Success:', result.value);
+ * } else {
+ *   console.error('All retries failed:', result.error);
+ * }
+ * ```
+ */
+export declare function retryResult<T>(fn: () => T | Promise<T>, options?: RetryOptions): Promise<Result<T, Error>>;
+/**
+ * Create a retryable version of a function
+ *
+ * @example
+ * ```typescript
+ * const fetchWithRetry = withRetry(
+ *   (url: string) => fetch(url),
+ *   { maxAttempts: 3 }
+ * );
+ *
+ * const response = await fetchWithRetry('/api/data');
+ * ```
+ */
+export declare function withRetry<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn | Promise<TReturn>, options?: RetryOptions): (...args: TArgs) => Promise<TReturn>;
+/**
+ * Predefined retry conditions
+ */
+export declare const RetryConditions: {
+    /**
+     * Retry on network errors (fetch failures, timeouts)
+     */
+    networkErrors: (error: Error) => boolean;
+    /**
+     * Retry on specific HTTP status codes (from fetch Response)
+     */
+    httpRetryable: (error: Error & {
+        status?: number;
+    }) => boolean;
+    /**
+     * Retry on transient WebSocket errors
+     */
+    websocketErrors: (error: Error) => boolean;
+    /**
+     * Combine multiple conditions (retry if any match)
+     */
+    any: (...conditions: Array<(error: Error) => boolean>) => (error: Error) => boolean;
+    /**
+     * Combine multiple conditions (retry if all match)
+     */
+    all: (...conditions: Array<(error: Error) => boolean>) => (error: Error) => boolean;
+};
+/**
+ * Preset configurations for common use cases
+ */
+export declare const RetryPresets: {
+    /**
+     * Aggressive retry for critical operations
+     */
+    aggressive: {
+        maxAttempts: number;
+        delayMs: number;
+        backoff: "exponential";
+        maxDelayMs: number;
+        jitter: number;
+    };
+    /**
+     * Conservative retry for non-critical operations
+     */
+    conservative: {
+        maxAttempts: number;
+        delayMs: number;
+        backoff: "linear";
+        maxDelayMs: number;
+        jitter: number;
+    };
+    /**
+     * Fast retry for local operations (short delays)
+     */
+    fast: {
+        maxAttempts: number;
+        delayMs: number;
+        backoff: "exponential";
+        maxDelayMs: number;
+        jitter: number;
+    };
+    /**
+     * WebSocket reconnection preset
+     */
+    websocket: {
+        maxAttempts: number;
+        delayMs: number;
+        backoff: "exponential";
+        maxDelayMs: number;
+        jitter: number;
+        shouldRetry: (error: Error) => boolean;
+    };
+};

package/dist/router.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Hypen Router - Declarative routing system
+ * Integrated with Hypen's reactive state management
+ */
+export type RouteMatch = {
+    params: Record<string, string>;
+    query: Record<string, string>;
+    path: string;
+};
+export type RouteState = {
+    currentPath: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    previousPath: string | null;
+};
+export type RouteChangeCallback = (route: RouteState) => void;
+/**
+ * Hypen Router - Manages application routing with pattern matching
+ */
+export declare class HypenRouter {
+    private state;
+    private subscribers;
+    private isInitialized;
+    private isUpdating;
+    constructor();
+    /**
+     * Initialize browser history sync
+     */
+    private initializeBrowserSync;
+    /**
+     * Get path from browser URL (supports both hash and pathname)
+     */
+    private getPathFromBrowser;
+    /**
+     * Parse query string from URL
+     */
+    private parseQuery;
+    /**
+     * Navigate to a new path
+     */
+    push(path: string): void;
+    /**
+     * Replace current path without adding to history
+     */
+    replace(path: string): void;
+    /**
+     * Go back in history
+     */
+    back(): void;
+    /**
+     * Go forward in history
+     */
+    forward(): void;
+    /**
+     * Update the current path
+     */
+    private updatePath;
+    /**
+     * Get current path
+     */
+    getCurrentPath(): string;
+    /**
+     * Get current route params
+     */
+    getParams(): Record<string, string>;
+    /**
+     * Get current query params
+     */
+    getQuery(): Record<string, string>;
+    /**
+     * Get full route state snapshot
+     */
+    getState(): RouteState;
+    /**
+     * Match a pattern against a path
+     */
+    matchPath(pattern: string, path: string): RouteMatch | null;
+    /**
+     * Subscribe to route changes
+     */
+    onNavigate(callback: RouteChangeCallback): () => void;
+    /**
+     * Notify all subscribers of route change
+     */
+    private notifySubscribers;
+    /**
+     * Check if a path matches the current route
+     */
+    isActive(pattern: string): boolean;
+    /**
+     * Get a URL with query params
+     */
+    buildUrl(path: string, query?: Record<string, string>): string;
+}

package/dist/state.d.ts

@@ -0,0 +1,42 @@
+/**
+ * State management with observer pattern and diffing
+ *
+ * Uses a proxy-based approach with self-detection to avoid
+ * creating nested proxies repeatedly.
+ */
+export type StatePath = string;
+/**
+ * Represents a change in state with full path information
+ */
+export interface StateChange {
+    paths: StatePath[];
+    newValues: Record<StatePath, any>;
+}
+/**
+ * Options for state observer
+ */
+export interface StateObserverOptions {
+    onChange: (change: StateChange) => void;
+    pathPrefix?: string;
+}
+/**
+ * Create an observable state object that tracks changes
+ */
+export declare function createObservableState<T extends object>(initialState: T, options?: StateObserverOptions): T;
+/**
+ * Helper to batch multiple state updates
+ */
+export declare function batchStateUpdates<T>(state: T, fn: () => void): void;
+/**
+ * Get a snapshot of the current state
+ */
+export declare function getStateSnapshot<T>(state: T): T;
+/**
+ * Check if a value is a Hypen state proxy
+ */
+export declare function isStateProxy(value: unknown): boolean;
+/**
+ * Get the raw (unwrapped) target from a proxy
+ * Returns the value as-is if not a proxy
+ */
+export declare function unwrapProxy<T>(value: T): T;

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Core types shared across the engine and runtime.
+ *
+ * These types are intentionally decoupled from the WASM engine so that
+ * packages can import them without pulling in any WASM code.
+ */
+export type Patch = {
+    type: "create" | "setProp" | "setText" | "insert" | "move" | "remove" | "attachEvent" | "detachEvent";
+    id?: string;
+    elementType?: string;
+    props?: Record<string, any>;
+    name?: string;
+    value?: any;
+    text?: string;
+    parentId?: string;
+    beforeId?: string;
+    eventName?: string;
+};
+export type Action = {
+    name: string;
+    payload?: any;
+    sender?: string;
+};
+export type RenderCallback = (patches: Patch[]) => void;
+export type ActionHandler = (action: Action) => void | Promise<void>;
+export type ResolvedComponent = {
+    source: string;
+    path: string;
+};
+export type ComponentResolver = (componentName: string, contextPath: string | null) => ResolvedComponent | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypen-space/core",
-  "version": "0.4.2",
+  "version": "0.4.5",
   "description": "Hypen core engine - Platform-agnostic reactive UI runtime",
   "type": "module",
   "main": "./dist/index.js",
@@ -152,6 +152,7 @@
   "scripts": {
     "build": "bun run build.ts",
     "build:types": "tsc --emitDeclarationOnly",
+    "prepublishOnly": "bun run build",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist"
   },

package/src/app.ts

@@ -21,22 +21,12 @@ import { createLogger } from "./logger.js";
 
 const log = createLogger("ModuleInstance");
 
-export type RouterContext = {
-  root: HypenRouter;
-  current?: HypenRouter;
-  parent?: HypenRouter;
-};
-
-export type ActionContext = {
+export type ActionContext<P = unknown> = {
   name: string;
-  payload?: unknown;
+  payload?: P;
   sender?: string;
 };
 
-export type ActionNext = {
-  router: HypenRouter; // Direct access to router instance (from nearest parent)
-};
-
 export type GlobalContext = {
   getModule: <T = unknown>(id: string) => ModuleReference<T>;
   hasModule: (id: string) => boolean;
@@ -44,7 +34,7 @@ export type GlobalContext = {
   getGlobalState: () => Record<string, unknown>;
   emit: (event: string, payload?: unknown) => void;
   on: (event: string, handler: (payload?: unknown) => void) => () => void;
-  __router?: unknown; // Internal: router instance for built-in Router component
+  router: HypenRouter | null;
 };
 
 export type LifecycleHandler<T> = (
@@ -55,17 +45,16 @@ export type LifecycleHandler<T> = (
 /**
  * Action handler context - all parameters available explicitly
  */
-export interface ActionHandlerContext<T> {
-  action: ActionContext;
+export interface ActionHandlerContext<T, P = unknown> {
+  action: ActionContext<P>;
   state: T;
-  next: ActionNext;
   context: GlobalContext;
 }
 
 /**
  * Action handler - receives all context in a single object
  */
-export type ActionHandler<T> = (ctx: ActionHandlerContext<T>) => void | Promise<void>;
+export type ActionHandler<T, P = unknown> = (ctx: ActionHandlerContext<T, P>) => void | Promise<void>;
 
 /**
  * Context passed to onDisconnect handler
@@ -152,7 +141,7 @@ export interface HypenModuleDefinition<T = unknown> {
   template?: string;
   handlers: {
     onCreated?: LifecycleHandler<T>;
-    onAction: Map<string, ActionHandler<T>>;
+    onAction: Map<string, ActionHandler<T, any>>;
     onDestroyed?: LifecycleHandler<T>;
     /** Called when client disconnects (session persists for TTL) */
     onDisconnect?: DisconnectHandler<T>;
@@ -177,20 +166,23 @@ export class HypenAppBuilder<T> {
   private initialState: T;
   private options: { persist?: boolean; version?: number; name?: string };
   private createdHandler?: LifecycleHandler<T>;
-  private actionHandlers: Map<string, ActionHandler<T>> = new Map();
+  private actionHandlers: Map<string, ActionHandler<T, any>> = new Map();
   private destroyedHandler?: LifecycleHandler<T>;
   private disconnectHandler?: DisconnectHandler<T>;
   private reconnectHandler?: ReconnectHandler<T>;
   private expireHandler?: ExpireHandler;
   private errorHandler?: ErrorHandler<T>;
   private template?: string;
+  private _registry?: Map<string, HypenModuleDefinition>;
 
   constructor(
     initialState: T,
-    options?: { persist?: boolean; version?: number; name?: string }
+    options?: { persist?: boolean; version?: number; name?: string },
+    registry?: Map<string, HypenModuleDefinition>
   ) {
     this.initialState = initialState;
     this.options = options || {};
+    this._registry = registry;
   }
 
   /**
@@ -202,10 +194,24 @@ export class HypenAppBuilder<T> {
   }
 
   /**
-   * Register a handler for a specific action
+   * Register a handler for a specific action.
+   * Optionally provide a payload type parameter for typed action payloads.
+   *
+   * @example
+   * ```typescript
+   * // Typed payload:
+   * .onAction<{ amount: number }>("add", ({ action, state }) => {
+   *   action.payload.amount; // fully typed
+   * })
+   *
+   * // Untyped (payload is unknown):
+   * .onAction("add", ({ action, state }) => {
+   *   action.payload; // unknown
+   * })
+   * ```
    */
-  onAction(name: string, fn: ActionHandler<T>): this {
-    this.actionHandlers.set(name, fn);
+  onAction<P = unknown>(name: string, fn: ActionHandler<T, P>): this {
+    this.actionHandlers.set(name, fn as ActionHandler<T, any>);
     return this;
   }
 
@@ -319,7 +325,7 @@ export class HypenAppBuilder<T> {
       ? Object.keys(this.initialState)
       : [];
 
-    return {
+    const definition: HypenModuleDefinition<T> = {
       name: this.options.name,
       actions: Array.from(this.actionHandlers.keys()),
       stateKeys,
@@ -337,13 +343,27 @@ export class HypenAppBuilder<T> {
         onError: this.errorHandler,
       },
     };
+
+    // Auto-register in the app registry when the module has a name
+    if (this.options.name && this._registry) {
+      this._registry.set(this.options.name, definition as HypenModuleDefinition);
+    }
+
+    return definition;
   }
 }
 
 /**
- * Hypen App API
+ * Hypen App API — singleton factory and component registry.
+ *
+ * Modules built with a `name` are automatically registered here.
+ * Consumers (ManagedRouter, RemoteServer, ComponentResolver) read from this
+ * registry instead of requiring a separate ModuleRegistry instance.
  */
 export class HypenApp {
+  /** @internal */
+  readonly _registry = new Map<string, HypenModuleDefinition>();
+
   /**
    * Define the initial state for a module
    */
@@ -351,7 +371,83 @@ export class HypenApp {
     initial: T,
     options?: { persist?: boolean; version?: number; name?: string }
   ): HypenAppBuilder<T> {
-    return new HypenAppBuilder(initial, options);
+    return new HypenAppBuilder(initial, options, this._registry);
+  }
+
+  /**
+   * Convenience: start a module builder with a name pre-set.
+   *
+   * @example
+   * ```typescript
+   * export default app
+   *   .module("Settings")
+   *   .defineState({ theme: "dark" })
+   *   .ui(hypen`...`);
+   * ```
+   */
+  module(name: string) {
+    const registry = this._registry;
+    return {
+      defineState: <T>(
+        initial: T,
+        options?: { persist?: boolean; version?: number }
+      ): HypenAppBuilder<T> => {
+        return new HypenAppBuilder(initial, { ...options, name }, registry);
+      },
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Registry API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get a registered module definition by component name.
+   */
+  get(name: string): HypenModuleDefinition | undefined {
+    return this._registry.get(name);
+  }
+
+  /**
+   * Check if a module definition is registered.
+   */
+  has(name: string): boolean {
+    return this._registry.has(name);
+  }
+
+  /**
+   * Read-only view of all registered component definitions.
+   */
+  get components(): ReadonlyMap<string, HypenModuleDefinition> {
+    return this._registry;
+  }
+
+  /**
+   * Get all registered component names.
+   */
+  getNames(): string[] {
+    return Array.from(this._registry.keys());
+  }
+
+  /**
+   * Number of registered definitions.
+   */
+  get size(): number {
+    return this._registry.size;
+  }
+
+  /**
+   * Unregister a module definition.
+   */
+  unregister(name: string): void {
+    this._registry.delete(name);
+  }
+
+  /**
+   * Clear all registered definitions.
+   */
+  clear(): void {
+    this._registry.clear();
   }
 }
 
@@ -368,19 +464,19 @@ export class HypenModuleInstance<T extends object = any> {
   private definition: HypenModuleDefinition<T>;
   private state: T;
   private isDestroyed = false;
-  private routerContext?: RouterContext;
+  private router: HypenRouter | null;
   private globalContext?: HypenGlobalContext;
   private stateChangeCallbacks: Array<() => void> = [];
 
   constructor(
     engine: IEngine,
     definition: HypenModuleDefinition<T>,
-    routerContext?: RouterContext,
+    router?: HypenRouter | null,
     globalContext?: HypenGlobalContext
   ) {
     this.engine = engine;
     this.definition = definition;
-    this.routerContext = routerContext;
+    this.router = router ?? null;
     this.globalContext = globalContext;
 
     // Named state prefix — all lowercase per convention
@@ -425,10 +521,6 @@ export class HypenModuleInstance<T extends object = any> {
           sender: action.sender,
         };
 
-        const next: ActionNext = {
-          router: this.routerContext?.root || (null as any),
-        };
-
         const context: GlobalContext | undefined = this.globalContext
           ? this.createGlobalContextAPI()
           : undefined;
@@ -437,7 +529,6 @@ export class HypenModuleInstance<T extends object = any> {
         const result = await this.executeAction(actionName, handler, {
           action: actionCtx,
           state: this.state,
-          next,
           context: context!,
         });
 
@@ -452,6 +543,22 @@ export class HypenModuleInstance<T extends object = any> {
       });
     }
 
+    // Auto-register __hypen_bind for .bind() two-way binding support
+    this.engine.onAction("__hypen_bind", (action: Action) => {
+      const payload = action.payload as { path?: string; value?: unknown } | null;
+      if (!payload?.path) return;
+
+      const segments = payload.path.split(".");
+      let target: any = this.state;
+      for (let i = 0; i < segments.length - 1; i++) {
+        const seg = segments[i]!;
+        target = target?.[seg];
+        if (target == null) return;
+      }
+      const lastSeg = segments[segments.length - 1]!;
+      target[lastSeg] = payload.value;
+    });
+
     // Call onCreated
     this.callCreatedHandler();
   }
@@ -473,12 +580,10 @@ export class HypenModuleInstance<T extends object = any> {
       emit: (event: string, payload?: any) => ctx.emit(event, payload),
       on: (event: string, handler: (payload?: any) => void) =>
         ctx.on(event, handler),
+      router: this.router,
     };
 
-    // Expose router and hypen engine for built-in components (if available)
-    if ((ctx as any).__router) {
-      api.__router = (ctx as any).__router;
-    }
+    // Expose hypen engine for built-in components (if available)
     if ((ctx as any).__hypenEngine) {
       (api as any).__hypenEngine = (ctx as any).__hypenEngine;
     }
@@ -492,7 +597,7 @@ export class HypenModuleInstance<T extends object = any> {
    */
   private async executeAction(
     actionName: string,
-    handler: ActionHandler<T>,
+    handler: ActionHandler<T, any>,
     ctx: ActionHandlerContext<T>
   ): Promise<Result<void, ActionError>> {
     try {
@@ -575,7 +680,15 @@ export class HypenModuleInstance<T extends object = any> {
   private async callCreatedHandler(): Promise<void> {
     if (this.definition.handlers.onCreated) {
       const context = this.globalContext ? this.createGlobalContextAPI() : undefined;
-      await this.definition.handlers.onCreated(this.state, context);
+      try {
+        await this.definition.handlers.onCreated(this.state, context);
+      } catch (e) {
+        const error = e instanceof HypenError ? e : new ActionError("onCreated", e);
+        const shouldRethrow = await this.handleError(error, { lifecycle: "created" });
+        if (shouldRethrow) {
+          throw error;
+        }
+      }
     }
   }
 
@@ -593,7 +706,15 @@ export class HypenModuleInstance<T extends object = any> {
     if (this.isDestroyed) return;
 
     if (this.definition.handlers.onDestroyed) {
-      await this.definition.handlers.onDestroyed(this.state);
+      try {
+        await this.definition.handlers.onDestroyed(this.state);
+      } catch (e) {
+        const error = e instanceof HypenError ? e : new ActionError("onDestroyed", e);
+        const shouldRethrow = await this.handleError(error, { lifecycle: "destroyed" });
+        if (shouldRethrow) {
+          throw error;
+        }
+      }
     }
 
     this.isDestroyed = true;