@hypen-space/core 0.4.1 → 0.4.3

package/dist/app.d.ts

@@ -0,0 +1,322 @@
+/**
+ * Hypen App Builder API
+ * Implements the stateful module system from RFC-0001
+ */
+import type { Action } from "./types.js";
+import type { Session } from "./remote/types.js";
+import { HypenError } from "./result.js";
+export interface IEngine {
+    setModule(name: string, actions: string[], stateKeys: string[], initialState: unknown): void;
+    onAction(actionName: string, handler: (action: Action) => void | Promise<void>): void;
+    notifyStateChange(paths: string[], changedValues: Record<string, unknown>): void;
+}
+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 = {
+    name: string;
+    payload?: unknown;
+    sender?: string;
+};
+export type ActionNext = {
+    router: HypenRouter;
+};
+export type GlobalContext = {
+    getModule: <T = unknown>(id: string) => ModuleReference<T>;
+    hasModule: (id: string) => boolean;
+    getModuleIds: () => string[];
+    getGlobalState: () => Record<string, unknown>;
+    emit: (event: string, payload?: unknown) => void;
+    on: (event: string, handler: (payload?: unknown) => void) => () => void;
+    __router?: unknown;
+};
+export type LifecycleHandler<T> = (state: T, context?: GlobalContext) => void | Promise<void>;
+/**
+ * Action handler context - all parameters available explicitly
+ */
+export interface ActionHandlerContext<T> {
+    action: ActionContext;
+    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>;
+/**
+ * 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 | {
+    handled: true;
+} | {
+    retry: true;
+} | {
+    rethrow: true;
+};
+/**
+ * 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[];
+    stateKeys: string[];
+    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>;
+    };
+}
+/**
+ * Alias for HypenModuleDefinition for backward compatibility
+ */
+export type HypenModule<T = unknown> = HypenModuleDefinition<T>;
+/**
+ * Builder for creating Hypen app modules
+ */
+export declare class HypenAppBuilder<T> {
+    private initialState;
+    private options;
+    private createdHandler?;
+    private actionHandlers;
+    private destroyedHandler?;
+    private disconnectHandler?;
+    private reconnectHandler?;
+    private expireHandler?;
+    private errorHandler?;
+    private template?;
+    constructor(initialState: T, options?: {
+        persist?: boolean;
+        version?: number;
+        name?: string;
+    });
+    /**
+     * Register a handler for module creation
+     */
+    onCreated(fn: LifecycleHandler<T>): this;
+    /**
+     * Register a handler for a specific action
+     */
+    onAction(name: string, fn: ActionHandler<T>): this;
+    /**
+     * Register a handler for module destruction
+     */
+    onDestroyed(fn: LifecycleHandler<T>): 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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>;
+    /**
+     * Build the module definition
+     */
+    build(): HypenModuleDefinition<T>;
+}
+/**
+ * Hypen App API
+ */
+export declare class HypenApp {
+    /**
+     * Define the initial state for a module
+     */
+    defineState<T>(initial: T, options?: {
+        persist?: boolean;
+        version?: number;
+        name?: string;
+    }): HypenAppBuilder<T>;
+}
+/**
+ * The main app instance for creating modules
+ */
+export declare const app: HypenApp;
+/**
+ * Module Instance - manages a running module with typed state
+ */
+export declare class HypenModuleInstance<T extends object = any> {
+    private engine;
+    private definition;
+    private state;
+    private isDestroyed;
+    private routerContext?;
+    private globalContext?;
+    private stateChangeCallbacks;
+    constructor(engine: IEngine, definition: HypenModuleDefinition<T>, routerContext?: RouterContext, globalContext?: HypenGlobalContext);
+    /**
+     * Create the global context API for this module
+     */
+    private createGlobalContextAPI;
+    /**
+     * Execute an action handler with Result-based error handling
+     * Handles both synchronous throws and async rejections
+     */
+    private executeAction;
+    /**
+     * 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 handleError;
+    /**
+     * Call the onCreated handler
+     */
+    private callCreatedHandler;
+    /**
+     * Register a callback to be notified when state changes
+     */
+    onStateChange(callback: () => void): void;
+    /**
+     * Destroy the module instance
+     */
+    destroy(): Promise<void>;
+    /**
+     * Get the current state (returns a snapshot)
+     */
+    getState(): T;
+    /**
+     * Get the live observable state
+     */
+    getLiveState(): T;
+    /**
+     * Update state directly (merges with existing state)
+     */
+    updateState(patch: Partial<T>): void;
+}

package/dist/components/builtin.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Built-in Hypen Components
+ * Framework-provided components like Router and Route
+ */
+/**
+ * Router Component
+ * Automatically matches routes and renders the appropriate child Route
+ *
+ * Usage in Hypen DSL:
+ * Router {
+ *   Route(path: "/") { HomePage }
+ *   Route(path: "/products") { ProductList }
+ *   Route(path: "/users/:id") { UserProfile }
+ * }
+ */
+export declare const Router: import("../app.js").HypenModuleDefinition<{
+    currentPath: string;
+    matchedRoute: any;
+    routeParams: Record<string, string>;
+}>;
+/**
+ * Route Component
+ * Defines a route pattern and its content
+ * This is just a marker component - Router processes it
+ *
+ * Props:
+ * - path: string - Route pattern (e.g., "/", "/users/:id", "/dashboard/*")
+ *
+ * Usage:
+ * Route(path: "/products") {
+ *   ProductList
+ * }
+ */
+export declare const Route: import("../app.js").HypenModuleDefinition<{}>;
+/**
+ * Navigation Link Component
+ * Navigates to a route when clicked
+ *
+ * Props:
+ * - to: string - Target path
+ *
+ * Usage:
+ * Link(to: "/products") {
+ *   Text("View Products")
+ * }
+ */
+export declare const Link: import("../app.js").HypenModuleDefinition<{
+    to: string;
+    isActive: boolean;
+}>;

package/dist/context.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Global Context - Cross-module communication and state access
+ */
+import type { HypenModuleInstance } from "./app.js";
+import { TypedEventEmitter, type HypenFrameworkEvents } from "./events.js";
+export type ModuleReference<T = unknown> = {
+    state: T;
+    setState: (patch: Partial<T>) => void;
+    getState: () => T;
+};
+/**
+ * @deprecated Use TypedEventEmitter from events.ts for type-safe events
+ */
+export type EventHandler = (payload?: unknown) => void;
+/**
+ * Global Context - Provides access to all modules and cross-module communication
+ *
+ * @template TEvents - Custom event map (extends HypenFrameworkEvents)
+ */
+export declare class HypenGlobalContext<TEvents extends Record<string, unknown> = HypenFrameworkEvents> {
+    private modules;
+    private typedEvents;
+    /**
+     * @deprecated Legacy event bus for backward compatibility
+     */
+    private legacyEventBus;
+    constructor();
+    /**
+     * Get the typed event emitter for type-safe event handling
+     */
+    get events(): TypedEventEmitter<TEvents>;
+    /**
+     * Register a module instance with an ID
+     */
+    registerModule(id: string, instance: HypenModuleInstance): void;
+    /**
+     * Unregister a module
+     */
+    unregisterModule(id: string): void;
+    /**
+     * Get a module by ID with type safety
+     */
+    getModule<T = unknown>(id: string): ModuleReference<T>;
+    /**
+     * Check if a module exists
+     */
+    hasModule(id: string): boolean;
+    /**
+     * Get all registered module IDs
+     */
+    getModuleIds(): string[];
+    /**
+     * Get the entire app state tree (snapshot)
+     */
+    getGlobalState(): Record<string, unknown>;
+    /**
+     * Emit an event to the event bus (legacy API for backward compatibility)
+     * @deprecated Use `context.events.emit()` for type-safe events
+     */
+    emit(event: string, payload?: unknown): void;
+    /**
+     * Subscribe to an event (legacy API for backward compatibility)
+     * @deprecated Use `context.events.on()` for type-safe events
+     */
+    on(event: string, handler: EventHandler): () => void;
+    /**
+     * Unsubscribe from an event (legacy API)
+     * @deprecated Use the unsubscribe function returned by `context.events.on()`
+     */
+    off(event: string, handler: EventHandler): void;
+    /**
+     * Clear all event listeners for an event (legacy API)
+     * @deprecated Use `context.events.removeAllListeners()`
+     */
+    clearEvent(event: string): void;
+    /**
+     * Clear all event listeners (legacy API)
+     * @deprecated Use `context.events.clearAll()`
+     */
+    clearAllEvents(): void;
+    /**
+     * Get debug info about the context
+     */
+    debug(): {
+        modules: string[];
+        events: string[];
+        typedEvents: Array<keyof TEvents>;
+        state: Record<string, unknown>;
+    };
+}

package/dist/discovery.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Component Discovery
+ *
+ * Automatically discovers Hypen components from the filesystem.
+ *
+ * Supports multiple conventions:
+ *   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 type { HypenModuleDefinition } from "./app.js";
+export interface DiscoveredComponent {
+    name: 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: ["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?: ("single-file" | "folder" | "sibling" | "index")[];
+    /**
+     * Recursively scan subdirectories
+     * Default: false
+     */
+    recursive?: boolean;
+    /**
+     * Enable debug logging
+     * Default: false
+     */
+    debug?: boolean;
+}
+export interface WatchOptions extends DiscoveryOptions {
+    /**
+     * Callback when components change
+     */
+    onChange?: (components: DiscoveredComponent[]) => void;
+    /**
+     * Callback when a component is added
+     */
+    onAdd?: (component: DiscoveredComponent) => void;
+    /**
+     * Callback when a component is removed
+     */
+    onRemove?: (name: string) => void;
+    /**
+     * Callback when a component is updated
+     */
+    onUpdate?: (component: DiscoveredComponent) => void;
+}
+/**
+ * Discover all Hypen components in a directory
+ */
+export declare function discoverComponents(baseDir: string, options?: DiscoveryOptions): Promise<DiscoveredComponent[]>;
+/**
+ * Load discovered components into a map for use with Hypen
+ */
+export declare function loadDiscoveredComponents(components: DiscoveredComponent[]): Promise<Map<string, {
+    name: string;
+    module: HypenModuleDefinition<any>;
+    template: string;
+}>>;
+/**
+ * Watch a directory for component changes
+ */
+export declare function watchComponents(baseDir: string, options?: WatchOptions): {
+    stop: () => void;
+};
+/**
+ * Generate a components object from discovered components
+ * Useful for static imports / code generation
+ */
+export declare function generateComponentsCode(baseDir: string, options?: DiscoveryOptions & {
+    outputDir?: string;
+}): Promise<string>;

package/dist/discovery.js

@@ -854,7 +854,7 @@ var init_app = __esm(() => {
 // src/discovery.ts
 init_logger();
 import { existsSync, readdirSync, readFileSync, watch } from "fs";
-import { join, basename, resolve } from "path";
+import { join, basename, resolve, relative } from "path";
 async function discoverComponents(baseDir, options = {}) {
   const {
     patterns = ["single-file", "folder", "sibling", "index"],
@@ -1090,6 +1090,7 @@ function watchComponents(baseDir, options = {}) {
 async function generateComponentsCode(baseDir, options = {}) {
   const components = await discoverComponents(baseDir, options);
   const resolvedDir = resolve(baseDir);
+  const outputBase = options.outputDir ? resolve(options.outputDir) : resolvedDir;
   let code = `/**
  * Auto-generated component imports
  * Generated by @hypen-space/core discovery
@@ -1097,9 +1098,13 @@ async function generateComponentsCode(baseDir, options = {}) {
 
 `;
   for (const component of components) {
-    const relativePath = component.modulePath ? "./" + component.modulePath.replace(resolvedDir + "/", "").replace(/\.ts$/, ".js") : null;
-    if (relativePath) {
-      code += `import ${component.name}Module from "${relativePath}";
+    let importPath = null;
+    if (component.modulePath) {
+      const rel = relative(outputBase, component.modulePath).replace(/\.ts$/, ".js");
+      importPath = rel.startsWith(".") ? rel : "./" + rel;
+    }
+    if (importPath) {
+      code += `import ${component.name}Module from "${importPath}";
 `;
     }
   }
@@ -1143,4 +1148,4 @@ export {
   discoverComponents
 };
 
-//# debugId=DEF834620FC1CE5864756E2164756E21
+//# debugId=85977D1E65CCBA9B64756E2164756E21