@hypen-space/core 0.2.12 → 0.3.0

package/src/app.ts

@@ -4,6 +4,8 @@
  */
 
 import type { Action } from "./engine.js";
+import type { Session } from "./remote/types.js";
+import { type Result, Ok, Err, fromPromise, ActionError, HypenError } from "./result.js";
 
 // Interface for engine compatibility (works with both engine.js and engine.browser.js)
 export interface IEngine {
@@ -15,6 +17,9 @@ export interface IEngine {
 import { createObservableState, type StateChange, getStateSnapshot } from "./state.js";
 import type { HypenRouter } from "./router.js";
 import type { HypenGlobalContext, ModuleReference } from "./context.js";
+import { createLogger } from "./logger.js";
+
+const log = createLogger("ModuleInstance");
 
 export type RouterContext = {
   root: HypenRouter;
@@ -62,6 +67,77 @@ export interface ActionHandlerContext<T> {
  */
 export type ActionHandler<T> = (ctx: ActionHandlerContext<T>) => void | Promise<void>;
 
+/**
+ * Context passed to onDisconnect handler
+ */
+export interface DisconnectContext<T> {
+  /** Current state snapshot (ready to serialize and save) */
+  state: T;
+  /** Session information */
+  session: Session;
+}
+
+/**
+ * Context passed to onReconnect handler
+ */
+export interface ReconnectContext<T> {
+  /** Session information */
+  session: Session;
+  /** Call this with saved state to restore it */
+  restore: (savedState: T) => void;
+}
+
+/**
+ * Context passed to onExpire handler
+ */
+export interface ExpireContext {
+  /** Session information */
+  session: Session;
+}
+
+/**
+ * Handler called when client disconnects (session still alive for TTL)
+ */
+export type DisconnectHandler<T> = (ctx: DisconnectContext<T>) => void | Promise<void>;
+
+/**
+ * Handler called when client reconnects with existing session
+ */
+export type ReconnectHandler<T> = (ctx: ReconnectContext<T>) => void | Promise<void>;
+
+/**
+ * Handler called when session TTL expires (client never reconnected)
+ */
+export type ExpireHandler = (ctx: ExpireContext) => void | Promise<void>;
+
+/**
+ * Context passed to onError handler
+ */
+export interface ErrorContext<T> {
+  /** The error that occurred */
+  error: HypenError;
+  /** Current state (for inspection, not mutation during error handling) */
+  state: T;
+  /** The action name if error occurred in an action handler */
+  actionName?: string;
+  /** The lifecycle phase if error occurred in a lifecycle handler */
+  lifecycle?: "created" | "destroyed" | "disconnect" | "reconnect" | "expire";
+}
+
+/**
+ * Error handler return type - controls error propagation
+ */
+export type ErrorHandlerResult =
+  | void                    // Continue with default behavior (log + emit)
+  | { handled: true }       // Error was handled, skip default behavior
+  | { retry: true }         // Retry the operation (only for actions)
+  | { rethrow: true };      // Re-throw the error
+
+/**
+ * Handler called when an error occurs in the module
+ */
+export type ErrorHandler<T> = (ctx: ErrorContext<T>) => ErrorHandlerResult | Promise<ErrorHandlerResult>;
+
 export interface HypenModuleDefinition<T = unknown> {
   name?: string;
   actions: string[];
@@ -69,10 +145,23 @@ export interface HypenModuleDefinition<T = unknown> {
   persist?: boolean;
   version?: number;
   initialState: T;
+  /**
+   * Inline UI template for single-file components.
+   * Set via the `.ui(hypen`...`)` method.
+   */
+  template?: string;
   handlers: {
     onCreated?: LifecycleHandler<T>;
     onAction: Map<string, ActionHandler<T>>;
     onDestroyed?: LifecycleHandler<T>;
+    /** Called when client disconnects (session persists for TTL) */
+    onDisconnect?: DisconnectHandler<T>;
+    /** Called when client reconnects with existing session */
+    onReconnect?: ReconnectHandler<T>;
+    /** Called when session TTL expires */
+    onExpire?: ExpireHandler;
+    /** Called when any error occurs in the module */
+    onError?: ErrorHandler<T>;
   };
 }
 
@@ -90,6 +179,11 @@ export class HypenAppBuilder<T> {
   private createdHandler?: LifecycleHandler<T>;
   private actionHandlers: Map<string, ActionHandler<T>> = new Map();
   private destroyedHandler?: LifecycleHandler<T>;
+  private disconnectHandler?: DisconnectHandler<T>;
+  private reconnectHandler?: ReconnectHandler<T>;
+  private expireHandler?: ExpireHandler;
+  private errorHandler?: ErrorHandler<T>;
+  private template?: string;
 
   constructor(
     initialState: T,
@@ -123,6 +217,99 @@ export class HypenAppBuilder<T> {
     return this;
   }
 
+  /**
+   * Register a handler for client disconnection
+   * Called when client disconnects; session persists for TTL
+   * Use this to save state for later restoration
+   */
+  onDisconnect(fn: DisconnectHandler<T>): this {
+    this.disconnectHandler = fn;
+    return this;
+  }
+
+  /**
+   * Register a handler for session reconnection
+   * Called when client reconnects with an existing session ID
+   * Use restore() to hydrate state from saved data
+   */
+  onReconnect(fn: ReconnectHandler<T>): this {
+    this.reconnectHandler = fn;
+    return this;
+  }
+
+  /**
+   * Register a handler for session expiration
+   * Called when TTL expires and client never reconnected
+   * Use this to clean up stored state
+   */
+  onExpire(fn: ExpireHandler): this {
+    this.expireHandler = fn;
+    return this;
+  }
+
+  /**
+   * Register an error handler for the module
+   * Called when any error occurs in action handlers or lifecycle hooks
+   *
+   * @example
+   * ```typescript
+   * app
+   *   .defineState({ count: 0 })
+   *   .onAction("increment", ({ state }) => {
+   *     if (state.count > 100) throw new Error("Count too high");
+   *     state.count += 1;
+   *   })
+   *   .onError(({ error, actionName, state }) => {
+   *     console.error(`Error in ${actionName}:`, error.message);
+   *     // Optionally recover
+   *     if (error.message.includes("too high")) {
+   *       return { handled: true }; // Don't propagate
+   *     }
+   *     // Or retry
+   *     // return { retry: true };
+   *   })
+   *   .build();
+   * ```
+   *
+   * @param fn - Error handler function
+   * @returns Builder for chaining
+   */
+  onError(fn: ErrorHandler<T>): this {
+    this.errorHandler = fn;
+    return this;
+  }
+
+  /**
+   * Define the component's UI template inline (single-file component).
+   *
+   * Use with the `hypen` tagged template literal and binding proxies:
+   *
+   * @example
+   * ```typescript
+   * import { app, hypen, state } from "@hypen-space/core";
+   *
+   * export default app
+   *   .defineState({ count: 0 })
+   *   .onAction("increment", ({ state }) => {
+   *     state.count += 1;
+   *   })
+   *   .ui(hypen`
+   *     Column {
+   *       Text("Count: ${state.count}")
+   *       Button { Text("+") }
+   *         .onClick("@actions.increment")
+   *     }
+   *   `);
+   * ```
+   *
+   * @param template - The Hypen DSL template string
+   * @returns The built module definition (calls build() internally)
+   */
+  ui(template: string): HypenModuleDefinition<T> {
+    this.template = template;
+    return this.build();
+  }
+
   /**
    * Build the module definition
    */
@@ -139,10 +326,15 @@ export class HypenAppBuilder<T> {
       persist: this.options.persist,
       version: this.options.version,
       initialState: this.initialState,
+      template: this.template,
       handlers: {
         onCreated: this.createdHandler,
         onAction: this.actionHandlers,
         onDestroyed: this.destroyedHandler,
+        onDisconnect: this.disconnectHandler,
+        onReconnect: this.reconnectHandler,
+        onExpire: this.expireHandler,
+        onError: this.errorHandler,
       },
     };
   }
@@ -211,9 +403,9 @@ export class HypenModuleInstance<T extends object = any> {
 
     // Register action handlers with flexible parameter support
     for (const [actionName, handler] of definition.handlers.onAction) {
-      console.log(`[ModuleInstance] Registering action handler: ${actionName} for module ${definition.name}`);
+      log.debug(`Registering action handler: ${actionName} for module ${definition.name}`);
       this.engine.onAction(actionName, async (action: Action) => {
-        console.log(`[ModuleInstance] Action handler fired: ${actionName}`, action);
+        log.debug(`Action handler fired: ${actionName}`, action);
 
         const actionCtx: ActionContext = {
           name: action.name,
@@ -229,17 +421,21 @@ export class HypenModuleInstance<T extends object = any> {
           ? this.createGlobalContextAPI()
           : undefined;
 
-        try {
-          await handler({
-            action: actionCtx,
-            state: this.state,
-            next,
-            context: context!,
-          });
-          console.log(`[ModuleInstance] Action handler completed: ${actionName}`);
-        } catch (error) {
-          console.error(`[ModuleInstance] Action handler error for ${actionName}:`, error);
-          throw error; // Re-throw to allow callers to handle the error
+        // Use Result type for error handling
+        const result = await this.executeAction(actionName, handler, {
+          action: actionCtx,
+          state: this.state,
+          next,
+          context: context!,
+        });
+
+        if (!result.ok) {
+          const shouldRethrow = await this.handleError(result.error, { actionName });
+          if (shouldRethrow) {
+            throw result.error;
+          }
+        } else {
+          log.debug(`Action handler completed: ${actionName}`);
         }
       });
     }
@@ -278,6 +474,89 @@ export class HypenModuleInstance<T extends object = any> {
     return api;
   }
 
+  /**
+   * Execute an action handler with Result-based error handling
+   * Handles both synchronous throws and async rejections
+   */
+  private async executeAction(
+    actionName: string,
+    handler: ActionHandler<T>,
+    ctx: ActionHandlerContext<T>
+  ): Promise<Result<void, ActionError>> {
+    try {
+      // Wrap in try-catch to handle synchronous throws
+      const result = handler(ctx);
+      // Await in case handler returns a promise
+      await result;
+      return Ok(undefined);
+    } catch (e) {
+      return Err(new ActionError(actionName, e));
+    }
+  }
+
+  /**
+   * Handle an error with module-level error handler support
+   * Falls back to default behavior (emit + log) if no handler or handler doesn't suppress
+   * @returns true if the error should be rethrown
+   */
+  private async handleError(
+    error: HypenError,
+    context: { actionName?: string; lifecycle?: ErrorContext<T>["lifecycle"] }
+  ): Promise<boolean> {
+    const errorCtx: ErrorContext<T> = {
+      error,
+      state: this.state,
+      actionName: context.actionName,
+      lifecycle: context.lifecycle,
+    };
+
+    // Call module-level error handler if defined
+    if (this.definition.handlers.onError) {
+      try {
+        const result = await this.definition.handlers.onError(errorCtx);
+
+        // Check if error was handled
+        if (result && typeof result === "object") {
+          if ("handled" in result && result.handled) {
+            // Error was handled, skip default behavior
+            return false;
+          }
+          if ("rethrow" in result && result.rethrow) {
+            // Signal caller to rethrow
+            return true;
+          }
+          // Note: 'retry' would need to be handled at the action execution level
+          // For now, we just continue with default behavior
+        }
+      } catch (handlerError) {
+        // Error in error handler - log and continue with default behavior
+        log.error("Error in onError handler:", handlerError);
+      }
+    }
+
+    // Default behavior: emit to global context and log
+    if (this.globalContext) {
+      const eventContext = context.actionName
+        ? `action:${context.actionName}`
+        : context.lifecycle
+          ? `lifecycle:${context.lifecycle}`
+          : "unknown";
+
+      this.globalContext.emit("error", {
+        message: error.message,
+        error,
+        context: eventContext,
+      });
+    }
+
+    log.error(
+      `${context.actionName ? `Action "${context.actionName}"` : `Lifecycle "${context.lifecycle}"`} error:`,
+      error
+    );
+
+    return false;
+  }
+
   /**
    * Call the onCreated handler
    */

package/src/discovery.ts

@@ -4,9 +4,10 @@
  * Automatically discovers Hypen components from the filesystem.
  *
  * Supports multiple conventions:
- *   1. Folder-based: ComponentName/component.ts + ComponentName/component.hypen
- *   2. Sibling files: ComponentName.ts + ComponentName.hypen
- *   3. Index-based: ComponentName/index.ts + ComponentName/index.hypen
+ *   1. Single-file: ComponentName.ts with .ui(hypen`...`) inline template
+ *   2. Folder-based: ComponentName/component.ts + ComponentName/component.hypen
+ *   3. Sibling files: ComponentName.ts + ComponentName.hypen
+ *   4. Index-based: ComponentName/index.ts + ComponentName/index.hypen
  */
 
 import { existsSync, readdirSync, readFileSync, watch } from "fs";
@@ -15,18 +16,29 @@ import type { HypenModuleDefinition } from "./app.js";
 
 export interface DiscoveredComponent {
   name: string;
-  hypenPath: string;
+  /** Path to .hypen file (null for single-file components with inline templates) */
+  hypenPath: string | null;
+  /** Path to .ts module file */
   modulePath: string | null;
+  /** The UI template (from .hypen file or inline) */
   template: string;
+  /** Whether this component has a module (state/actions) */
   hasModule: boolean;
+  /** Whether this is a single-file component with inline template */
+  isSingleFile: boolean;
 }
 
 export interface DiscoveryOptions {
   /**
    * Which naming patterns to look for
-   * Default: ["folder", "sibling", "index"]
+   * Default: ["single-file", "folder", "sibling", "index"]
+   *
+   * - single-file: ComponentName.ts with .ui(hypen`...`) inline template
+   * - folder: ComponentName/component.ts + ComponentName/component.hypen
+   * - sibling: ComponentName.ts + ComponentName.hypen
+   * - index: ComponentName/index.ts + ComponentName/index.hypen
    */
-  patterns?: ("folder" | "sibling" | "index")[];
+  patterns?: ("single-file" | "folder" | "sibling" | "index")[];
 
   /**
    * Recursively scan subdirectories
@@ -81,7 +93,7 @@ export async function discoverComponents(
   options: DiscoveryOptions = {}
 ): Promise<DiscoveredComponent[]> {
   const {
-    patterns = ["folder", "sibling", "index"],
+    patterns = ["single-file", "folder", "sibling", "index"],
     recursive = false,
     debug = false,
   } = options;
@@ -97,8 +109,8 @@ export async function discoverComponents(
   log("Scanning directory:", resolvedDir);
   log("Patterns:", patterns);
 
-  // Helper to add a component if not already seen
-  const addComponent = (
+  // Helper to add a two-file component (.hypen + .ts)
+  const addTwoFileComponent = (
     name: string,
     hypenPath: string,
     modulePath: string | null
@@ -118,9 +130,34 @@ export async function discoverComponents(
       modulePath,
       template,
       hasModule: modulePath !== null,
+      isSingleFile: false,
     });
 
-    log(`Found: ${name} (${modulePath ? "with module" : "stateless"})`);
+    log(`Found: ${name} (two-file, ${modulePath ? "with module" : "stateless"})`);
+  };
+
+  // Helper to add a single-file component (.ts with inline template)
+  const addSingleFileComponent = (
+    name: string,
+    modulePath: string,
+    template: string
+  ) => {
+    if (seen.has(name)) {
+      log(`Skipping duplicate: ${name}`);
+      return;
+    }
+
+    seen.add(name);
+    components.push({
+      name,
+      hypenPath: null,
+      modulePath,
+      template,
+      hasModule: true,
+      isSingleFile: true,
+    });
+
+    log(`Found: ${name} (single-file with inline template)`);
   };
 
   // Scan directory for folder-based components
@@ -140,7 +177,7 @@ export async function discoverComponents(
         const hypenPath = join(folderPath, "component.hypen");
         if (existsSync(hypenPath)) {
           const modulePath = join(folderPath, "component.ts");
-          addComponent(
+          addTwoFileComponent(
             componentName,
             hypenPath,
             existsSync(modulePath) ? modulePath : null
@@ -154,7 +191,7 @@ export async function discoverComponents(
         const hypenPath = join(folderPath, "index.hypen");
         if (existsSync(hypenPath)) {
           const modulePath = join(folderPath, "index.ts");
-          addComponent(
+          addTwoFileComponent(
             componentName,
             hypenPath,
             existsSync(modulePath) ? modulePath : null
@@ -170,7 +207,7 @@ export async function discoverComponents(
     }
   };
 
-  // Scan for sibling file components
+  // Scan for sibling file components (.ts + .hypen pairs)
   const scanForSiblingComponents = (dir: string) => {
     if (!existsSync(dir)) return;
 
@@ -193,7 +230,7 @@ export async function discoverComponents(
       if (baseName === "component" || baseName === "index") continue;
 
       const modulePath = join(dir, `${baseName}.ts`);
-      addComponent(
+      addTwoFileComponent(
         baseName,
         hypenPath,
         existsSync(modulePath) ? modulePath : null
@@ -201,6 +238,56 @@ export async function discoverComponents(
     }
   };
 
+  // Scan for single-file components (.ts files with inline templates)
+  const scanForSingleFileComponents = async (dir: string) => {
+    if (!existsSync(dir)) return;
+
+    const entries = readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (recursive) {
+          await scanForSingleFileComponents(join(dir, entry.name));
+        }
+        continue;
+      }
+
+      // Only look at .ts files
+      if (!entry.name.endsWith(".ts")) continue;
+
+      // Skip files that are clearly not components
+      if (entry.name.startsWith('.') || entry.name.includes('.test.') || entry.name.includes('.spec.')) continue;
+
+      // Skip component.ts and index.ts (handled by folder patterns)
+      const baseName = basename(entry.name, ".ts");
+      if (baseName === "component" || baseName === "index") continue;
+
+      // Skip if there's a matching .hypen file (handled by sibling pattern)
+      const hypenPath = join(dir, `${baseName}.hypen`);
+      if (existsSync(hypenPath)) continue;
+
+      // Check if this looks like a single-file component by looking for .ui( pattern
+      const modulePath = join(dir, entry.name);
+      const content = readFileSync(modulePath, "utf-8");
+
+      // Quick heuristic: look for .ui( or .ui(hypen pattern
+      if (content.includes(".ui(") || content.includes(".ui(hypen")) {
+        // Try to import and check for template
+        try {
+          const moduleExport = await import(modulePath);
+          const module = moduleExport.default as HypenModuleDefinition<any>;
+
+          if (module && typeof module === "object" && module.template) {
+            addSingleFileComponent(baseName, modulePath, module.template);
+          }
+        } catch (e) {
+          // Failed to import, skip this file
+          log(`Failed to import potential single-file component: ${entry.name}`, e);
+        }
+      }
+    }
+  };
+
   // Run scans based on patterns
   if (patterns.includes("folder") || patterns.includes("index")) {
     scanForFolderComponents(resolvedDir);
@@ -210,6 +297,10 @@ export async function discoverComponents(
     scanForSiblingComponents(resolvedDir);
   }
 
+  if (patterns.includes("single-file")) {
+    await scanForSingleFileComponents(resolvedDir);
+  }
+
   log(`Discovered ${components.length} components`);
 
   return components;
@@ -244,11 +335,17 @@ export async function loadDiscoveredComponents(
 
   for (const component of components) {
     let module: HypenModuleDefinition<any>;
+    let template = component.template;
 
     if (component.modulePath) {
       // Import the TypeScript module
       const moduleExport = await import(component.modulePath);
       module = moduleExport.default as HypenModuleDefinition<any>;
+
+      // For single-file components, template is already in the module
+      if (component.isSingleFile && module.template) {
+        template = module.template;
+      }
     } else {
       // Create a stateless module
       module = app.defineState({}).build();
@@ -257,7 +354,7 @@ export async function loadDiscoveredComponents(
     loaded.set(component.name, {
       name: component.name,
       module,
-      template: component.template,
+      template,
     });
   }
 
@@ -396,14 +493,22 @@ export async function generateComponentsCode(
   code += `\nimport { app } from "@hypen-space/core";\n\n`;
 
   for (const component of components) {
-    const templateJson = JSON.stringify(component.template);
-
-    if (component.hasModule) {
+    if (component.isSingleFile) {
+      // Single-file component: template is in the module itself
+      code += `export const ${component.name} = {
+  module: ${component.name}Module,
+  template: ${component.name}Module.template,
+};\n\n`;
+    } else if (component.hasModule) {
+      // Two-file component with module
+      const templateJson = JSON.stringify(component.template);
       code += `export const ${component.name} = {
   module: ${component.name}Module,
   template: ${templateJson},
 };\n\n`;
     } else {
+      // Stateless two-file component
+      const templateJson = JSON.stringify(component.template);
       code += `const ${component.name}Module = app.defineState({}).build();
 export const ${component.name} = {
   module: ${component.name}Module,