@hypen-space/core 0.2.12 → 0.3.1

package/src/index.ts

@@ -1,25 +1,43 @@
 /**
- * @hypen/core - Hypen Core Engine
+ * @hypen-space/core - Hypen Core Engine
  *
  * Platform-agnostic reactive UI runtime.
  * Use with @hypen/web for browser rendering, or build your own renderer.
  *
- * ## Quick Start
+ * ## Quick Start (Single-File Component)
  *
  * ```typescript
- * import { Engine, app } from "@hypen/core";
+ * import { app, hypen, state } from "@hypen-space/core";
  *
- * // Create a stateful module
- * const counter = app
+ * export default app
+ *   .defineState({ count: 0 })
+ *   .onAction("increment", ({ state }) => {
+ *     state.count += 1;
+ *   })
+ *   .ui(hypen`
+ *     Column {
+ *       Text("Count: ${state.count}")
+ *       Button { Text("+") }
+ *         .onClick("@actions.increment")
+ *     }
+ *   `);
+ * ```
+ *
+ * ## Two-File Component (Legacy)
+ *
+ * ```typescript
+ * // component.ts
+ * import { app } from "@hypen-space/core";
+ *
+ * export default app
  *   .defineState({ count: 0 })
  *   .onAction("increment", ({ state }) => {
  *     state.count++;
  *   })
  *   .build();
  *
- * // Initialize the engine
- * const engine = new Engine();
- * await engine.init();
+ * // component.hypen (separate file)
+ * // Column { Text("Count: ${state.count}") ... }
  * ```
  */
 
@@ -46,6 +64,14 @@ export type { EngineInitOptions } from "./engine.browser.js";
 // ============================================================================
 
 export { app, HypenApp, HypenAppBuilder, HypenModuleInstance } from "./app.js";
+
+// ============================================================================
+// TEMPLATE SYSTEM (Single-File Components)
+// ============================================================================
+
+export { hypen, state, item, index } from "./hypen.js";
+export type { StateProxy, ItemProxy } from "./hypen.js";
+
 export type {
   IEngine,
   RouterContext,
@@ -57,6 +83,17 @@ export type {
   ActionHandler,
   HypenModuleDefinition,
   HypenModule,
+  // Session lifecycle hooks
+  DisconnectContext,
+  ReconnectContext,
+  ExpireContext,
+  DisconnectHandler,
+  ReconnectHandler,
+  ExpireHandler,
+  // Error handling
+  ErrorContext,
+  ErrorHandler,
+  ErrorHandlerResult,
 } from "./app.js";
 
 // ============================================================================
@@ -67,6 +104,8 @@ export {
   createObservableState,
   batchStateUpdates,
   getStateSnapshot,
+  isStateProxy,
+  unwrapProxy,
 } from "./state.js";
 export type {
   StatePath,
@@ -110,20 +149,37 @@ export type { ModuleReference } from "./context.js";
 // REMOTE UI
 // ============================================================================
 
+// Client
 export { RemoteEngine } from "./remote/client.js";
+export type {
+  RemoteConnectionState,
+  RemoteEngineOptions,
+  SessionOptions,
+  SessionInfo,
+} from "./remote/client.js";
+
+// Server
+export { RemoteServer, serve } from "./remote/server.js";
+
+// Session Management
+export { SessionManager } from "./remote/session.js";
+export type { SessionExpireCallback } from "./remote/session.js";
+
+// Types
 export type {
   RemoteMessage,
   InitialTreeMessage,
   PatchMessage,
   DispatchActionMessage,
   StateUpdateMessage,
+  HelloMessage,
+  SessionAckMessage,
+  SessionExpiredMessage,
+  Session,
+  SessionConfig,
   RemoteClient,
   RemoteServerConfig,
 } from "./remote/types.js";
-export type {
-  RemoteConnectionState,
-  RemoteEngineOptions,
-} from "./remote/client.js";
 
 // ============================================================================
 // COMPONENT LOADER
@@ -173,3 +229,83 @@ export type { HypenPluginOptions } from "./plugin.js";
 // ============================================================================
 
 export { Router, Route, Link } from "./components/builtin.js";
+
+// ============================================================================
+// RESULT TYPE (Error Handling)
+// ============================================================================
+
+export {
+  Ok,
+  Err,
+  isOk,
+  isErr,
+  fromPromise,
+  fromTry,
+  map,
+  mapErr,
+  flatMap,
+  unwrap,
+  unwrapOr,
+  unwrapOrElse,
+  match,
+  all,
+  HypenError,
+  ActionError,
+  ConnectionError,
+  StateError,
+} from "./result.js";
+export type { Result } from "./result.js";
+
+// ============================================================================
+// DISPOSABLE PATTERN (Resource Management)
+// ============================================================================
+
+export {
+  DisposableStack,
+  DisposableMixin,
+  isDisposable,
+  disposableListener,
+  disposableTimeout,
+  disposableInterval,
+  disposableWebSocket,
+  disposableAbortController,
+  disposableSubscription,
+  getElementDisposables,
+  disposeElement,
+  hasElementDisposables,
+  compositeDisposable,
+  using,
+  usingSync,
+} from "./disposable.js";
+export type { Disposable } from "./disposable.js";
+
+// ============================================================================
+// Retry Utility
+// ============================================================================
+
+export {
+  retry,
+  retryResult,
+  withRetry,
+  RetryConditions,
+  RetryPresets,
+} from "./retry.js";
+export type { RetryOptions } from "./retry.js";
+
+// ============================================================================
+// Logger
+// ============================================================================
+
+export {
+  Logger,
+  createLogger,
+  logger,
+  log,
+  frameworkLoggers,
+  setLogLevel,
+  getLogLevel,
+  configureLogger,
+  enableLogging,
+  disableLogging,
+} from "./logger.js";
+export type { LogLevel, LoggerConfig, LogHandler } from "./logger.js";

package/src/logger.ts

@@ -0,0 +1,338 @@
+/**
+ * Configurable Debug Logger
+ *
+ * Provides environment-aware logging that can be disabled in production.
+ * Supports log levels, tagged output, and performance timing.
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type LogLevel = "debug" | "info" | "warn" | "error" | "none";
+
+export interface LoggerConfig {
+  /** Minimum log level (default: "debug" in dev, "error" in prod) */
+  level: LogLevel;
+  /** Enable colored output (default: true) */
+  colors: boolean;
+  /** Include timestamps (default: false) */
+  timestamps: boolean;
+  /** Custom log handler (default: console) */
+  handler?: LogHandler;
+}
+
+export interface LogHandler {
+  debug(tag: string, ...args: unknown[]): void;
+  info(tag: string, ...args: unknown[]): void;
+  warn(tag: string, ...args: unknown[]): void;
+  error(tag: string, ...args: unknown[]): void;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const LOG_LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  none: 4,
+};
+
+const LOG_LEVEL_COLORS: Record<Exclude<LogLevel, "none">, string> = {
+  debug: "\x1b[36m", // Cyan
+  info: "\x1b[32m",  // Green
+  warn: "\x1b[33m",  // Yellow
+  error: "\x1b[31m", // Red
+};
+
+const RESET_COLOR = "\x1b[0m";
+
+// ============================================================================
+// Global Configuration
+// ============================================================================
+
+/**
+ * Detect if running in production environment
+ */
+function isProduction(): boolean {
+  if (typeof process !== "undefined" && process.env) {
+    return process.env.NODE_ENV === "production";
+  }
+  return false;
+}
+
+/**
+ * Default configuration
+ */
+let config: LoggerConfig = {
+  level: isProduction() ? "error" : "debug",
+  colors: true,
+  timestamps: false,
+};
+
+// ============================================================================
+// Configuration API
+// ============================================================================
+
+/**
+ * Set the global log level
+ */
+export function setLogLevel(level: LogLevel): void {
+  config.level = level;
+}
+
+/**
+ * Get the current log level
+ */
+export function getLogLevel(): LogLevel {
+  return config.level;
+}
+
+/**
+ * Configure the logger
+ */
+export function configureLogger(options: Partial<LoggerConfig>): void {
+  config = { ...config, ...options };
+}
+
+/**
+ * Enable all logging (sets level to "debug")
+ */
+export function enableLogging(): void {
+  config.level = "debug";
+}
+
+/**
+ * Disable all logging (sets level to "none")
+ */
+export function disableLogging(): void {
+  config.level = "none";
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+function shouldLog(level: LogLevel): boolean {
+  return LOG_LEVEL_ORDER[level] >= LOG_LEVEL_ORDER[config.level];
+}
+
+function formatTag(tag: string, level: LogLevel): string {
+  const timestamp = config.timestamps ? `${new Date().toISOString()} ` : "";
+
+  if (config.colors && level !== "none") {
+    const color = LOG_LEVEL_COLORS[level as Exclude<LogLevel, "none">];
+    return `${timestamp}${color}[${tag}]${RESET_COLOR}`;
+  }
+
+  return `${timestamp}[${tag}]`;
+}
+
+// ============================================================================
+// Logger Class
+// ============================================================================
+
+/**
+ * Tagged logger instance
+ *
+ * @example
+ * ```typescript
+ * const log = createLogger("MyComponent");
+ * log.debug("initialized with", { props });
+ * log.error("failed to load", error);
+ * ```
+ */
+export class Logger {
+  private readonly tag: string;
+
+  constructor(tag: string) {
+    this.tag = tag;
+  }
+
+  debug(...args: unknown[]): void {
+    if (!shouldLog("debug")) return;
+
+    if (config.handler) {
+      config.handler.debug(this.tag, ...args);
+    } else {
+      console.log(formatTag(this.tag, "debug"), ...args);
+    }
+  }
+
+  info(...args: unknown[]): void {
+    if (!shouldLog("info")) return;
+
+    if (config.handler) {
+      config.handler.info(this.tag, ...args);
+    } else {
+      console.info(formatTag(this.tag, "info"), ...args);
+    }
+  }
+
+  warn(...args: unknown[]): void {
+    if (!shouldLog("warn")) return;
+
+    if (config.handler) {
+      config.handler.warn(this.tag, ...args);
+    } else {
+      console.warn(formatTag(this.tag, "warn"), ...args);
+    }
+  }
+
+  error(...args: unknown[]): void {
+    if (!shouldLog("error")) return;
+
+    if (config.handler) {
+      config.handler.error(this.tag, ...args);
+    } else {
+      console.error(formatTag(this.tag, "error"), ...args);
+    }
+  }
+
+  /**
+   * Time a function execution
+   */
+  time<T>(label: string, fn: () => T): T {
+    if (!shouldLog("debug")) {
+      return fn();
+    }
+
+    const start = performance.now();
+    try {
+      return fn();
+    } finally {
+      const duration = performance.now() - start;
+      this.debug(`${label}: ${duration.toFixed(2)}ms`);
+    }
+  }
+
+  /**
+   * Time an async function execution
+   */
+  async timeAsync<T>(label: string, fn: () => Promise<T>): Promise<T> {
+    if (!shouldLog("debug")) {
+      return fn();
+    }
+
+    const start = performance.now();
+    try {
+      return await fn();
+    } finally {
+      const duration = performance.now() - start;
+      this.debug(`${label}: ${duration.toFixed(2)}ms`);
+    }
+  }
+
+  /**
+   * Create a child logger with additional context
+   */
+  child(subTag: string): Logger {
+    return new Logger(`${this.tag}:${subTag}`);
+  }
+
+  /**
+   * Conditionally log based on a condition
+   */
+  debugIf(condition: boolean, ...args: unknown[]): void {
+    if (condition) this.debug(...args);
+  }
+
+  warnIf(condition: boolean, ...args: unknown[]): void {
+    if (condition) this.warn(...args);
+  }
+
+  errorIf(condition: boolean, ...args: unknown[]): void {
+    if (condition) this.error(...args);
+  }
+
+  /**
+   * Log once (useful for deprecation warnings)
+   */
+  private loggedOnce = new Set<string>();
+
+  warnOnce(key: string, ...args: unknown[]): void {
+    if (this.loggedOnce.has(key)) return;
+    this.loggedOnce.add(key);
+    this.warn(...args);
+  }
+
+  debugOnce(key: string, ...args: unknown[]): void {
+    if (this.loggedOnce.has(key)) return;
+    this.loggedOnce.add(key);
+    this.debug(...args);
+  }
+}
+
+// ============================================================================
+// Factory Functions
+// ============================================================================
+
+/**
+ * Create a tagged logger
+ *
+ * @example
+ * ```typescript
+ * const log = createLogger("Router");
+ * log.info("navigating to", path);
+ * ```
+ */
+export function createLogger(tag: string): Logger {
+  return new Logger(tag);
+}
+
+// ============================================================================
+// Default Logger Instance
+// ============================================================================
+
+/**
+ * Default logger for general use
+ */
+export const logger = createLogger("Hypen");
+
+// ============================================================================
+// Shorthand Functions (untagged)
+// ============================================================================
+
+/**
+ * Shorthand logging functions for quick use
+ * Prefer createLogger() for component-specific logging
+ */
+export const log = {
+  debug: (tag: string, ...args: unknown[]): void => {
+    if (!shouldLog("debug")) return;
+    console.log(formatTag(tag, "debug"), ...args);
+  },
+
+  info: (tag: string, ...args: unknown[]): void => {
+    if (!shouldLog("info")) return;
+    console.info(formatTag(tag, "info"), ...args);
+  },
+
+  warn: (tag: string, ...args: unknown[]): void => {
+    if (!shouldLog("warn")) return;
+    console.warn(formatTag(tag, "warn"), ...args);
+  },
+
+  error: (tag: string, ...args: unknown[]): void => {
+    if (!shouldLog("error")) return;
+    console.error(formatTag(tag, "error"), ...args);
+  },
+};
+
+// ============================================================================
+// Predefined Loggers for Framework Components
+// ============================================================================
+
+export const frameworkLoggers = {
+  engine: createLogger("Engine"),
+  router: createLogger("Router"),
+  state: createLogger("State"),
+  events: createLogger("Events"),
+  remote: createLogger("Remote"),
+  renderer: createLogger("Renderer"),
+  module: createLogger("Module"),
+  lifecycle: createLogger("Lifecycle"),
+};

package/src/plugin.ts

@@ -186,7 +186,7 @@ export default { module: _module, template: ${JSON.stringify(template)}, name: $
           // No TypeScript module - create stateless component
           log("No module found, creating stateless component");
           contents = `
-import { app } from "@hypen/core";
+import { app } from "@hypen-space/core";
 const _module = app.defineState({}).build();
 export const module = _module;
 export const template = ${JSON.stringify(template)};