@hypen-space/core 0.2.0

package/src/app.ts

@@ -0,0 +1,330 @@
+/**
+ * Hypen App Builder API
+ * Implements the stateful module system from RFC-0001
+ */
+
+import type { Action } from "./engine.js";
+
+// Interface for engine compatibility (works with both engine.js and engine.browser.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 { createObservableState, type StateChange, getStateSnapshot } from "./state.js";
+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; // Direct access to router instance (from nearest parent)
+};
+
+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; // Internal: router instance for built-in Router component
+};
+
+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>;
+
+export interface HypenModuleDefinition<T = unknown> {
+  name?: string;
+  actions: string[];
+  stateKeys: string[];
+  persist?: boolean;
+  version?: number;
+  initialState: T;
+  handlers: {
+    onCreated?: LifecycleHandler<T>;
+    onAction: Map<string, ActionHandler<T>>;
+    onDestroyed?: LifecycleHandler<T>;
+  };
+}
+
+/**
+ * Alias for HypenModuleDefinition for backward compatibility
+ */
+export type HypenModule<T = unknown> = HypenModuleDefinition<T>;
+
+/**
+ * Builder for creating Hypen app modules
+ */
+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 destroyedHandler?: LifecycleHandler<T>;
+
+  constructor(
+    initialState: T,
+    options?: { persist?: boolean; version?: number; name?: string }
+  ) {
+    this.initialState = initialState;
+    this.options = options || {};
+  }
+
+  /**
+   * Register a handler for module creation
+   */
+  onCreated(fn: LifecycleHandler<T>): this {
+    this.createdHandler = fn;
+    return this;
+  }
+
+  /**
+   * Register a handler for a specific action
+   */
+  onAction(name: string, fn: ActionHandler<T>): this {
+    this.actionHandlers.set(name, fn);
+    return this;
+  }
+
+  /**
+   * Register a handler for module destruction
+   */
+  onDestroyed(fn: LifecycleHandler<T>): this {
+    this.destroyedHandler = fn;
+    return this;
+  }
+
+  /**
+   * Build the module definition
+   */
+  build(): HypenModuleDefinition<T> {
+    // Safe way to get keys from initialState
+    const stateKeys = this.initialState !== null && typeof this.initialState === 'object'
+      ? Object.keys(this.initialState)
+      : [];
+
+    return {
+      name: this.options.name,
+      actions: Array.from(this.actionHandlers.keys()),
+      stateKeys,
+      persist: this.options.persist,
+      version: this.options.version,
+      initialState: this.initialState,
+      handlers: {
+        onCreated: this.createdHandler,
+        onAction: this.actionHandlers,
+        onDestroyed: this.destroyedHandler,
+      },
+    };
+  }
+}
+
+/**
+ * Hypen App API
+ */
+export class HypenApp {
+  /**
+   * Define the initial state for a module
+   */
+  defineState<T>(
+    initial: T,
+    options?: { persist?: boolean; version?: number; name?: string }
+  ): HypenAppBuilder<T> {
+    return new HypenAppBuilder(initial, options);
+  }
+}
+
+/**
+ * The main app instance for creating modules
+ */
+export const app = new HypenApp();
+
+/**
+ * Module Instance - manages a running module with typed state
+ */
+export class HypenModuleInstance<T extends object = any> {
+  private engine: IEngine;
+  private definition: HypenModuleDefinition<T>;
+  private state: T;
+  private isDestroyed = false;
+  private routerContext?: RouterContext;
+  private globalContext?: HypenGlobalContext;
+  private stateChangeCallbacks: Array<() => void> = [];
+
+  constructor(
+    engine: IEngine,
+    definition: HypenModuleDefinition<T>,
+    routerContext?: RouterContext,
+    globalContext?: HypenGlobalContext
+  ) {
+    this.engine = engine;
+    this.definition = definition;
+    this.routerContext = routerContext;
+    this.globalContext = globalContext;
+
+    // Create observable state that sends only changed paths and values to engine
+    this.state = createObservableState<T>(definition.initialState as T & object, {
+      onChange: (change: StateChange) => {
+        // Send only the changed paths and their new values (not the whole state)
+        this.engine.notifyStateChange(change.paths, change.newValues);
+        // Notify all registered callbacks
+        this.stateChangeCallbacks.forEach(cb => cb());
+      },
+    });
+
+    // Register with engine (initial state registration)
+    this.engine.setModule(
+      definition.name || "AnonymousModule",
+      definition.actions,
+      definition.stateKeys,
+      getStateSnapshot(this.state)
+    );
+
+    // 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}`);
+      this.engine.onAction(actionName, async (action: Action) => {
+        console.log(`[ModuleInstance] Action handler fired: ${actionName}`, action);
+
+        const actionCtx: ActionContext = {
+          name: action.name,
+          payload: action.payload,
+          sender: action.sender,
+        };
+
+        const next: ActionNext = {
+          router: this.routerContext?.root || (null as any),
+        };
+
+        const context: GlobalContext | undefined = this.globalContext
+          ? 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);
+        }
+      });
+    }
+
+    // Call onCreated
+    this.callCreatedHandler();
+  }
+
+  /**
+   * Create the global context API for this module
+   */
+  private createGlobalContextAPI(): GlobalContext {
+    if (!this.globalContext) {
+      throw new Error("Global context not available");
+    }
+
+    const ctx = this.globalContext;
+    const api: GlobalContext = {
+      getModule: (id: string) => ctx.getModule(id),
+      hasModule: (id: string) => ctx.hasModule(id),
+      getModuleIds: () => ctx.getModuleIds(),
+      getGlobalState: () => ctx.getGlobalState(),
+      emit: (event: string, payload?: any) => ctx.emit(event, payload),
+      on: (event: string, handler: (payload?: any) => void) =>
+        ctx.on(event, handler),
+    };
+
+    // Expose router and hypen engine for built-in components (if available)
+    if ((ctx as any).__router) {
+      api.__router = (ctx as any).__router;
+    }
+    if ((ctx as any).__hypenEngine) {
+      (api as any).__hypenEngine = (ctx as any).__hypenEngine;
+    }
+
+    return api;
+  }
+
+  /**
+   * Call the onCreated handler
+   */
+  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);
+    }
+  }
+
+  /**
+   * Register a callback to be notified when state changes
+   */
+  onStateChange(callback: () => void): void {
+    this.stateChangeCallbacks.push(callback);
+  }
+
+  /**
+   * Destroy the module instance
+   */
+  async destroy(): Promise<void> {
+    if (this.isDestroyed) return;
+
+    if (this.definition.handlers.onDestroyed) {
+      await this.definition.handlers.onDestroyed(this.state);
+    }
+
+    this.isDestroyed = true;
+  }
+
+  /**
+   * Get the current state (returns a snapshot)
+   */
+  getState(): T {
+    return getStateSnapshot(this.state);
+  }
+
+  /**
+   * Get the live observable state
+   */
+  getLiveState(): T {
+    return this.state;
+  }
+
+  /**
+   * Update state directly (merges with existing state)
+   */
+  updateState(patch: Partial<T>): void {
+    Object.assign(this.state, patch);
+  }
+}

package/src/context.ts

@@ -0,0 +1,201 @@
+/**
+ * Global Context - Cross-module communication and state access
+ */
+
+import type { HypenModuleInstance } from "./app.js";
+import { getStateSnapshot } from "./state.js";
+import { TypedEventEmitter, type HypenFrameworkEvents } from "./events.js";
+
+export type ModuleReference<T = unknown> = {
+  state: T; // Live proxy state
+  setState: (patch: Partial<T>) => void;
+  getState: () => T; // Snapshot
+};
+
+/**
+ * @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 class HypenGlobalContext<TEvents extends Record<string, unknown> = HypenFrameworkEvents> {
+  private modules = new Map<string, HypenModuleInstance>();
+  private typedEvents: TypedEventEmitter<TEvents>;
+
+  /**
+   * @deprecated Legacy event bus for backward compatibility
+   */
+  private legacyEventBus = new Map<string, Set<EventHandler>>();
+
+  constructor() {
+    this.typedEvents = new TypedEventEmitter<TEvents>();
+  }
+
+  /**
+   * Get the typed event emitter for type-safe event handling
+   */
+  get events(): TypedEventEmitter<TEvents> {
+    return this.typedEvents;
+  }
+
+  /**
+   * Register a module instance with an ID
+   */
+  registerModule(id: string, instance: HypenModuleInstance) {
+    if (this.modules.has(id)) {
+      console.warn(`Module "${id}" is already registered. Overwriting.`);
+    }
+    this.modules.set(id, instance);
+    console.log(`Registered module: ${id}`);
+  }
+
+  /**
+   * Unregister a module
+   */
+  unregisterModule(id: string) {
+    this.modules.delete(id);
+    console.log(`Unregistered module: ${id}`);
+  }
+
+  /**
+   * Get a module by ID with type safety
+   */
+  getModule<T = unknown>(id: string): ModuleReference<T> {
+    const module = this.modules.get(id);
+    if (!module) {
+      throw new Error(
+        `Module "${id}" not found. Available modules: ${Array.from(this.modules.keys()).join(", ")}`
+      );
+    }
+
+    return {
+      state: module.getLiveState() as T,
+      setState: (patch: Partial<T>) => module.updateState(patch),
+      getState: () => module.getState() as T,
+    };
+  }
+
+  /**
+   * Check if a module exists
+   */
+  hasModule(id: string): boolean {
+    return this.modules.has(id);
+  }
+
+  /**
+   * Get all registered module IDs
+   */
+  getModuleIds(): string[] {
+    return Array.from(this.modules.keys());
+  }
+
+  /**
+   * Get the entire app state tree (snapshot)
+   */
+  getGlobalState(): Record<string, unknown> {
+    const state: Record<string, unknown> = {};
+    this.modules.forEach((module, id) => {
+      state[id] = module.getState();
+    });
+    return state;
+  }
+
+  /**
+   * 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 {
+    const handlers = this.legacyEventBus.get(event);
+    if (!handlers || handlers.size === 0) {
+      console.log(`Event "${event}" emitted but no listeners`);
+    } else {
+      console.log(`Emitting event: ${event}`, payload);
+      handlers.forEach((handler) => {
+        try {
+          handler(payload);
+        } catch (error) {
+          console.error(`Error in event handler for "${event}":`, error);
+        }
+      });
+    }
+
+    // Also emit to typed event system if the event is registered there
+    if (this.typedEvents.listenerCount(event as keyof TEvents) > 0) {
+      this.typedEvents.emit(event as keyof TEvents, payload as TEvents[keyof TEvents]);
+    }
+  }
+
+  /**
+   * Subscribe to an event (legacy API for backward compatibility)
+   * @deprecated Use `context.events.on()` for type-safe events
+   */
+  on(event: string, handler: EventHandler): () => void {
+    if (!this.legacyEventBus.has(event)) {
+      this.legacyEventBus.set(event, new Set());
+    }
+
+    const handlers = this.legacyEventBus.get(event)!;
+    handlers.add(handler);
+
+    console.log(`Listening to event: ${event}`);
+
+    // Return unsubscribe function
+    return () => {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this.legacyEventBus.delete(event);
+      }
+    };
+  }
+
+  /**
+   * Unsubscribe from an event (legacy API)
+   * @deprecated Use the unsubscribe function returned by `context.events.on()`
+   */
+  off(event: string, handler: EventHandler): void {
+    const handlers = this.legacyEventBus.get(event);
+    if (handlers) {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this.legacyEventBus.delete(event);
+      }
+    }
+  }
+
+  /**
+   * Clear all event listeners for an event (legacy API)
+   * @deprecated Use `context.events.removeAllListeners()`
+   */
+  clearEvent(event: string): void {
+    this.legacyEventBus.delete(event);
+  }
+
+  /**
+   * Clear all event listeners (legacy API)
+   * @deprecated Use `context.events.clearAll()`
+   */
+  clearAllEvents(): void {
+    this.legacyEventBus.clear();
+  }
+
+  /**
+   * Get debug info about the context
+   */
+  debug(): {
+    modules: string[];
+    events: string[];
+    typedEvents: Array<keyof TEvents>;
+    state: Record<string, unknown>;
+  } {
+    return {
+      modules: this.getModuleIds(),
+      events: Array.from(this.legacyEventBus.keys()),
+      typedEvents: this.typedEvents.eventNames(),
+      state: this.getGlobalState(),
+    };
+  }
+}