@hypen-space/core 0.4.3 → 0.4.11

package/README.md

@@ -136,7 +136,7 @@ const userModule = app
     state.user = await fetchUser(userId);
     state.loading = false;
     // State changes are auto-synced via Proxy
-    // next.router is available for programmatic navigation
+    // context.router is available for programmatic navigation
   })
 
   .onAction("logout", ({ state }) => {

package/dist/app.d.ts

@@ -12,19 +12,11 @@ export interface IEngine {
 }
 import type { HypenRouter } from "./router.js";
 import type { HypenGlobalContext, ModuleReference } from "./context.js";
-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;
-};
 export type GlobalContext = {
     getModule: <T = unknown>(id: string) => ModuleReference<T>;
     hasModule: (id: string) => boolean;
@@ -32,22 +24,21 @@ export type GlobalContext = {
     getGlobalState: () => Record<string, unknown>;
     emit: (event: string, payload?: unknown) => void;
     on: (event: string, handler: (payload?: unknown) => void) => () => void;
-    __router?: unknown;
+    router: HypenRouter | null;
 };
 export type LifecycleHandler<T> = (state: T, context?: GlobalContext) => void | Promise<void>;
 /**
  * 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
  */
@@ -126,7 +117,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>;
@@ -156,19 +147,34 @@ export declare class HypenAppBuilder<T> {
     private expireHandler?;
     private errorHandler?;
     private template?;
+    private _registry?;
     constructor(initialState: T, options?: {
         persist?: boolean;
         version?: number;
         name?: string;
-    });
+    }, registry?: Map<string, HypenModuleDefinition>);
     /**
      * Register a handler for module creation
      */
     onCreated(fn: LifecycleHandler<T>): this;
     /**
-     * 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;
+    onAction<P = unknown>(name: string, fn: ActionHandler<T, P>): this;
     /**
      * Register a handler for module destruction
      */
@@ -252,9 +258,15 @@ export declare class HypenAppBuilder<T> {
     build(): HypenModuleDefinition<T>;
 }
 /**
- * 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 declare class HypenApp {
+    /** @internal */
+    readonly _registry: Map<string, HypenModuleDefinition<unknown>>;
     /**
      * Define the initial state for a module
      */
@@ -263,6 +275,51 @@ export declare class HypenApp {
         version?: number;
         name?: string;
     }): HypenAppBuilder<T>;
+    /**
+     * 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): {
+        defineState: <T>(initial: T, options?: {
+            persist?: boolean;
+            version?: number;
+        }) => HypenAppBuilder<T>;
+    };
+    /**
+     * Get a registered module definition by component name.
+     */
+    get(name: string): HypenModuleDefinition | undefined;
+    /**
+     * Check if a module definition is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * Read-only view of all registered component definitions.
+     */
+    get components(): ReadonlyMap<string, HypenModuleDefinition>;
+    /**
+     * Get all registered component names.
+     */
+    getNames(): string[];
+    /**
+     * Number of registered definitions.
+     */
+    get size(): number;
+    /**
+     * Unregister a module definition.
+     */
+    unregister(name: string): void;
+    /**
+     * Clear all registered definitions.
+     */
+    clear(): void;
 }
 /**
  * The main app instance for creating modules
@@ -276,10 +333,10 @@ export declare class HypenModuleInstance<T extends object = any> {
     private definition;
     private state;
     private isDestroyed;
-    private routerContext?;
+    private router;
     private globalContext?;
     private stateChangeCallbacks;
-    constructor(engine: IEngine, definition: HypenModuleDefinition<T>, routerContext?: RouterContext, globalContext?: HypenGlobalContext);
+    constructor(engine: IEngine, definition: HypenModuleDefinition<T>, router?: HypenRouter | null, globalContext?: HypenGlobalContext);
     /**
      * Create the global context API for this module
      */

package/dist/app.js

@@ -275,144 +275,6 @@ var init_state = __esm(() => {
   RAW_TARGET = Symbol.for("hypen.rawTarget");
 });
 
-// src/result.ts
-function Ok(value) {
-  return { ok: true, value };
-}
-function Err(error) {
-  return { ok: false, error };
-}
-function isOk(result) {
-  return result.ok;
-}
-function isErr(result) {
-  return !result.ok;
-}
-async function fromPromise(promise, mapError) {
-  try {
-    const value = await promise;
-    return Ok(value);
-  } catch (e) {
-    if (mapError) {
-      return Err(mapError(e));
-    }
-    return Err(e);
-  }
-}
-function fromTry(fn, mapError) {
-  try {
-    return Ok(fn());
-  } catch (e) {
-    if (mapError) {
-      return Err(mapError(e));
-    }
-    return Err(e);
-  }
-}
-function map(result, fn) {
-  if (result.ok) {
-    return Ok(fn(result.value));
-  }
-  return result;
-}
-function mapErr(result, fn) {
-  if (!result.ok) {
-    return Err(fn(result.error));
-  }
-  return result;
-}
-function flatMap(result, fn) {
-  if (result.ok) {
-    return fn(result.value);
-  }
-  return result;
-}
-function unwrap(result) {
-  if (result.ok) {
-    return result.value;
-  }
-  throw result.error;
-}
-function unwrapOr(result, defaultValue) {
-  if (result.ok) {
-    return result.value;
-  }
-  return defaultValue;
-}
-function unwrapOrElse(result, fn) {
-  if (result.ok) {
-    return result.value;
-  }
-  return fn(result.error);
-}
-function match(result, handlers) {
-  if (result.ok) {
-    return handlers.ok(result.value);
-  }
-  return handlers.err(result.error);
-}
-function all(results) {
-  const values = [];
-  for (const result of results) {
-    if (!result.ok) {
-      return result;
-    }
-    values.push(result.value);
-  }
-  return Ok(values);
-}
-var HypenError, ActionError, ConnectionError, StateError;
-var init_result = __esm(() => {
-  HypenError = class HypenError extends Error {
-    code;
-    context;
-    cause;
-    constructor(code, message, options) {
-      super(message);
-      this.name = "HypenError";
-      this.code = code;
-      this.context = options?.context;
-      this.cause = options?.cause;
-      Object.setPrototypeOf(this, new.target.prototype);
-    }
-  };
-  ActionError = class ActionError extends HypenError {
-    actionName;
-    constructor(actionName, cause) {
-      super("ACTION_ERROR", `Action handler "${actionName}" failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
-        context: { actionName },
-        cause: cause instanceof Error ? cause : undefined
-      });
-      this.name = "ActionError";
-      this.actionName = actionName;
-    }
-  };
-  ConnectionError = class ConnectionError extends HypenError {
-    url;
-    attempt;
-    constructor(url, cause, attempt) {
-      super("CONNECTION_ERROR", `Connection to "${url}" failed${attempt ? ` (attempt ${attempt})` : ""}: ${cause instanceof Error ? cause.message : String(cause)}`, {
-        context: { url, attempt },
-        cause: cause instanceof Error ? cause : undefined
-      });
-      this.name = "ConnectionError";
-      this.url = url;
-      this.attempt = attempt;
-    }
-  };
-  StateError = class StateError extends HypenError {
-    path;
-    constructor(message, path, cause) {
-      super("STATE_ERROR", message, {
-        context: { path },
-        cause: cause instanceof Error ? cause : undefined
-      });
-      this.name = "StateError";
-      this.path = path;
-    }
-  };
-});
-
 // src/logger.ts
 function isProduction() {
   if (typeof process !== "undefined" && process.env) {
@@ -612,6 +474,176 @@ var init_logger = __esm(() => {
   };
 });
 
+// src/result.ts
+function Ok(value) {
+  return { ok: true, value };
+}
+function Err(error) {
+  return { ok: false, error };
+}
+function isOk(result) {
+  return result.ok;
+}
+function isErr(result) {
+  return !result.ok;
+}
+async function fromPromise(promise, mapError) {
+  try {
+    const value = await promise;
+    return Ok(value);
+  } catch (e) {
+    if (mapError) {
+      return Err(mapError(e));
+    }
+    return Err(e);
+  }
+}
+function fromTry(fn, mapError) {
+  try {
+    return Ok(fn());
+  } catch (e) {
+    if (mapError) {
+      return Err(mapError(e));
+    }
+    return Err(e);
+  }
+}
+function map(result, fn) {
+  if (result.ok) {
+    return Ok(fn(result.value));
+  }
+  return result;
+}
+function mapErr(result, fn) {
+  if (!result.ok) {
+    return Err(fn(result.error));
+  }
+  return result;
+}
+function flatMap(result, fn) {
+  if (result.ok) {
+    return fn(result.value);
+  }
+  return result;
+}
+function unwrap(result) {
+  if (result.ok) {
+    return result.value;
+  }
+  throw result.error;
+}
+function unwrapOr(result, defaultValue) {
+  if (result.ok) {
+    return result.value;
+  }
+  return defaultValue;
+}
+function unwrapOrElse(result, fn) {
+  if (result.ok) {
+    return result.value;
+  }
+  return fn(result.error);
+}
+function match(result, handlers) {
+  if (result.ok) {
+    return handlers.ok(result.value);
+  }
+  return handlers.err(result.error);
+}
+function all(results) {
+  const values = [];
+  for (const result of results) {
+    if (!result.ok) {
+      return result;
+    }
+    values.push(result.value);
+  }
+  return Ok(values);
+}
+function classifyEngineError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  if (message.startsWith("Parse error:")) {
+    return new ParseError(message);
+  }
+  if (message.startsWith("Invalid state:") || message.startsWith("Invalid state patch:")) {
+    return new StateError(message);
+  }
+  if (message.startsWith("Parent node not found:")) {
+    return new RenderError(message);
+  }
+  return new RenderError(message);
+}
+var HypenError, ActionError, ConnectionError, StateError, ParseError, RenderError;
+var init_result = __esm(() => {
+  HypenError = class HypenError extends Error {
+    code;
+    context;
+    cause;
+    constructor(code, message, options) {
+      super(message);
+      this.name = "HypenError";
+      this.code = code;
+      this.context = options?.context;
+      this.cause = options?.cause;
+      Object.setPrototypeOf(this, new.target.prototype);
+    }
+  };
+  ActionError = class ActionError extends HypenError {
+    actionName;
+    constructor(actionName, cause) {
+      super("ACTION_ERROR", `Action handler "${actionName}" failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+        context: { actionName },
+        cause: cause instanceof Error ? cause : undefined
+      });
+      this.name = "ActionError";
+      this.actionName = actionName;
+    }
+  };
+  ConnectionError = class ConnectionError extends HypenError {
+    url;
+    attempt;
+    constructor(url, cause, attempt) {
+      super("CONNECTION_ERROR", `Connection to "${url}" failed${attempt ? ` (attempt ${attempt})` : ""}: ${cause instanceof Error ? cause.message : String(cause)}`, {
+        context: { url, attempt },
+        cause: cause instanceof Error ? cause : undefined
+      });
+      this.name = "ConnectionError";
+      this.url = url;
+      this.attempt = attempt;
+    }
+  };
+  StateError = class StateError extends HypenError {
+    path;
+    constructor(message, path, cause) {
+      super("STATE_ERROR", message, {
+        context: { path },
+        cause: cause instanceof Error ? cause : undefined
+      });
+      this.name = "StateError";
+      this.path = path;
+    }
+  };
+  ParseError = class ParseError extends HypenError {
+    source;
+    constructor(message, source, cause) {
+      super("PARSE_ERROR", message, {
+        context: { source },
+        cause: cause instanceof Error ? cause : undefined
+      });
+      this.name = "ParseError";
+      this.source = source;
+    }
+  };
+  RenderError = class RenderError extends HypenError {
+    constructor(message, cause) {
+      super("RENDER_ERROR", message, {
+        cause: cause instanceof Error ? cause : undefined
+      });
+      this.name = "RenderError";
+    }
+  };
+});
+
 // src/app.ts
 var exports_app = {};
 __export(exports_app, {
@@ -632,9 +664,11 @@ class HypenAppBuilder {
   expireHandler;
   errorHandler;
   template;
-  constructor(initialState, options) {
+  _registry;
+  constructor(initialState, options, registry) {
     this.initialState = initialState;
     this.options = options || {};
+    this._registry = registry;
   }
   onCreated(fn) {
     this.createdHandler = fn;
@@ -670,7 +704,7 @@ class HypenAppBuilder {
   }
   build() {
     const stateKeys = this.initialState !== null && typeof this.initialState === "object" ? Object.keys(this.initialState) : [];
-    return {
+    const definition = {
       name: this.options.name,
       actions: Array.from(this.actionHandlers.keys()),
       stateKeys,
@@ -688,12 +722,46 @@ class HypenAppBuilder {
         onError: this.errorHandler
       }
     };
+    if (this.options.name && this._registry) {
+      this._registry.set(this.options.name, definition);
+    }
+    return definition;
   }
 }
 
 class HypenApp {
+  _registry = new Map;
   defineState(initial, options) {
-    return new HypenAppBuilder(initial, options);
+    return new HypenAppBuilder(initial, options, this._registry);
+  }
+  module(name) {
+    const registry = this._registry;
+    return {
+      defineState: (initial, options) => {
+        return new HypenAppBuilder(initial, { ...options, name }, registry);
+      }
+    };
+  }
+  get(name) {
+    return this._registry.get(name);
+  }
+  has(name) {
+    return this._registry.has(name);
+  }
+  get components() {
+    return this._registry;
+  }
+  getNames() {
+    return Array.from(this._registry.keys());
+  }
+  get size() {
+    return this._registry.size;
+  }
+  unregister(name) {
+    this._registry.delete(name);
+  }
+  clear() {
+    this._registry.clear();
   }
 }
 
@@ -702,13 +770,13 @@ class HypenModuleInstance {
   definition;
   state;
   isDestroyed = false;
-  routerContext;
+  router;
   globalContext;
   stateChangeCallbacks = [];
-  constructor(engine, definition, routerContext, globalContext) {
+  constructor(engine, definition, router, globalContext) {
     this.engine = engine;
     this.definition = definition;
-    this.routerContext = routerContext;
+    this.router = router ?? null;
     this.globalContext = globalContext;
     const statePrefix = (definition.name || "").toLowerCase();
     this.state = createObservableState(definition.initialState, {
@@ -730,14 +798,10 @@ class HypenModuleInstance {
           payload: action.payload,
           sender: action.sender
         };
-        const next = {
-          router: this.routerContext?.root || null
-        };
         const context = this.globalContext ? this.createGlobalContextAPI() : undefined;
         const result = await this.executeAction(actionName, handler, {
           action: actionCtx,
           state: this.state,
-          next,
           context
         });
         if (!result.ok) {
@@ -750,6 +814,21 @@ class HypenModuleInstance {
         }
       });
     }
+    this.engine.onAction("__hypen_bind", (action) => {
+      const payload = action.payload;
+      if (!payload?.path)
+        return;
+      const segments = payload.path.split(".");
+      let target = 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;
+    });
     this.callCreatedHandler();
   }
   createGlobalContextAPI() {
@@ -763,11 +842,9 @@ class HypenModuleInstance {
       getModuleIds: () => ctx.getModuleIds(),
       getGlobalState: () => ctx.getGlobalState(),
       emit: (event, payload) => ctx.emit(event, payload),
-      on: (event, handler) => ctx.on(event, handler)
+      on: (event, handler) => ctx.on(event, handler),
+      router: this.router
     };
-    if (ctx.__router) {
-      api.__router = ctx.__router;
-    }
     if (ctx.__hypenEngine) {
       api.__hypenEngine = ctx.__hypenEngine;
     }
@@ -818,7 +895,15 @@ class HypenModuleInstance {
   async callCreatedHandler() {
     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;
+        }
+      }
     }
   }
   onStateChange(callback) {
@@ -828,7 +913,15 @@ class HypenModuleInstance {
     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;
   }
@@ -859,4 +952,4 @@ export {
   HypenApp
 };
 
-//# debugId=047B2B99C6893ED464756E2164756E21
+//# debugId=901B51DDE158736764756E2164756E21