@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.41

package/src/adapters/abstract/application-adapter.d.ts

@@ -8,7 +8,9 @@
  */
 import type { SourceModuleLoader } from '../../services/module-loading/module-loading-types.js';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { ApiHandler, ApiHandlerContext, ErrorHandler, Middleware, RouteOptions, StaticRoute, ViewLoader } from '../../types/public-types.js';
+import type { ApiHandler, ApiHandlerContext, ErrorHandler, Middleware, RouteOptions, StaticRoute, ViewLoader, EcopagesRouteInfo } from '../../types/public-types.js';
+import type { EcopagesWebSocketHandler } from '../../types/public-types.js';
+import { type EcopagesRuntimeLabel } from '../../dev/runtime-server-started-message.js';
 import { type ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
 /**
  * Runtime bootstrap options layered on top of the app config.
@@ -25,6 +27,13 @@ export interface ApplicationRuntimeOptions {
      * adapter auto-detects a host module loader from the global scope.
      */
     embedded?: boolean;
+    /**
+     * Selects which layer injects browser dev-client bootstrap (HMR runtime, reload).
+     *
+     * `host` disables core injection and reload signaling so embedded hosts like
+     * Vite own the full dev-client surface.
+     */
+    devClientOwner?: 'core' | 'host';
     /**
      * Explicit source module loader for request-time imports.
      *
@@ -33,6 +42,27 @@ export interface ApplicationRuntimeOptions {
      */
     hostModuleLoader?: SourceModuleLoader;
 }
+export interface AppStartInfo {
+    origin: string;
+    /**
+     * Static-generation routes available when the runtime becomes ready.
+     *
+     * @remarks
+     * Empty when the server adapter has no route registry yet, or when route
+     * resolution fails (failures never block startup). Route resolution completes
+     * before the `onAppStart` callback runs.
+     */
+    routes: EcopagesRouteInfo[];
+}
+export type OnAppStartCallback = (info: AppStartInfo) => void;
+/** @deprecated Use {@link AppStartInfo}. */
+export type ApplicationListeningInfo = AppStartInfo;
+/** @deprecated Use {@link OnAppStartCallback}. */
+export type StartCallback = OnAppStartCallback;
+/** @deprecated Use {@link OnAppStartCallback}. */
+export type ListenCallback = OnAppStartCallback;
+/** @deprecated Use {@link OnAppStartCallback}. */
+export type ApplicationListeningCallback = OnAppStartCallback;
 /**
  * Configuration options for application adapters
  */
@@ -49,8 +79,12 @@ export interface ApplicationAdapterOptions {
 /**
  * Common interface for application adapters
  */
-export interface ApplicationAdapter<T = any> {
-    start(): Promise<T | void>;
+export interface ApplicationAdapter<T = any> extends AsyncDisposable {
+    /** Boot the server. Pass a callback to run when the runtime is ready (optional). */
+    start(onAppStart?: OnAppStartCallback): Promise<T | void>;
+    /** Invoked by embedded hosts once the app can take traffic. */
+    handleListening(origin: string): void | Promise<void>;
+    stop(force?: boolean): Promise<void>;
 }
 /**
  * Handler function type for route handlers
@@ -72,7 +106,14 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
     protected apiHandlers: ApiHandler[];
     protected staticRoutes: StaticRoute[];
     protected errorHandler?: ErrorHandler;
-    constructor(options: TOptions);
+    /**
+     * App-level WebSocket handlers keyed by URL path pattern (e.g. '/ws/chat/:id').
+     * Both Bun and Node adapters read this map to register upgrade routes.
+     */
+    protected websocketHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
+    private onAppStartCallback?;
+    protected readonly runtimeLabel: EcopagesRuntimeLabel;
+    constructor(options: TOptions, runtimeLabel: EcopagesRuntimeLabel);
     private clearDistFolder;
     /**
      * Register a GET route handler.
@@ -160,6 +201,46 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
      * Get all registered static routes
      */
     getStaticRoutes(): StaticRoute[];
+    /**
+     * Register a WebSocket handler for the given path pattern.
+     *
+     * The runtime adapter handles the HTTP→WebSocket upgrade for this path
+     * and routes lifecycle events to `handler`.
+     *
+     * Supports dynamic segments via `:param` syntax. The handler receives
+     * typed `params` and `search` fields, and a typed `context` produced by
+     * the optional `context()` factory.
+     *
+     * One pattern registration matches infinite path variations. For example,
+     * `app.websocket('/ws/chat/:roomId', handler)` matches `/ws/chat/abc`,
+     * `/ws/chat/xyz`, etc. Each connection receives its own `params.roomId`.
+     *
+     * Works across both Bun and Node runtimes — no runtime-specific imports needed.
+     *
+     * @example
+     * ```typescript
+     * app.websocket<ChatContext, { roomId: string }>('/ws/chat/:roomId', {
+     *   async context({ params, search }) {
+     *     return { username: search.username ?? 'anonymous', roomId: params.roomId };
+     *   },
+     *   onConnect(socket) {
+     *     socket.send(`Welcome to room ${socket.context.roomId}`);
+     *   },
+     *   onMessage(socket, message) {
+     *     if (message.kind === 'text') {
+     *       socket.send(message.text);
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    websocket<TContext = unknown, TParams extends Record<string, string> = Record<string, string>>(path: string, handler: EcopagesWebSocketHandler<TContext, TParams>): this;
+    /**
+     * Get the registered WebSocket handlers map.
+     *
+     * @returns The map of WebSocket route patterns to handlers
+     */
+    getWebsocketHandlers(): Map<string, EcopagesWebSocketHandler<any, any>>;
     /**
      * Register a global error handler for all routes.
      * Useful for logging, monitoring integration, and custom error formatting.
@@ -182,9 +263,37 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
      */
     protected abstract initializeServerAdapter(): Promise<any>;
     /**
-     * Start the application server
+     * Boot the server. When `onAppStart` is passed, it runs once the runtime can take traffic.
+     * Embedded apps only register the callback — the host (for example Vite) boots the port.
+     */
+    start(onAppStart?: OnAppStartCallback): Promise<TServer | void>;
+    /** Runtime-specific server boot (dev, preview, build). */
+    protected abstract bootServer(): Promise<TServer | void>;
+    protected logServerStarted(origin: string): void;
+    /**
+     * Invoked by embedded hosts (for example Vite) once the app can take traffic.
+     */
+    handleListening(origin: string): Promise<void>;
+    protected notifyListening(origin: string): Promise<void>;
+    /**
+     * Resolves routes exposed on {@link AppStartInfo}.
+     *
+     * @remarks
+     * Default is empty. Runtime adapters override this to read from the
+     * initialized server route registry.
+     */
+    protected resolveAppRoutes(): Promise<EcopagesRouteInfo[]>;
+    private invokeAppStartCallback;
+    /**
+     * Stops the application server and releases runtime resources.
+     *
+     * @remarks
+     * Subclasses override this to shut down bound servers, watchers, and other
+     * dev-time resources. The default implementation is a no-op so embedded
+     * adapters that never call `start()` can still be used with `await using`.
      */
-    abstract start(): Promise<TServer | void>;
+    stop(_force?: boolean): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * Handles a standard Web request without requiring a bound network server.
      * This is the primary interoperability surface for embedding Ecopages inside

package/src/adapters/abstract/application-adapter.js

@@ -1,121 +1,262 @@
-import { appLogger } from "../../global/app-logger.js";
-import {
-  getAppModuleLoader,
-  setAppHostModuleLoader
-} from "../../services/module-loading/app-server-module-transpiler.service.js";
-import { getHostModuleLoader } from "../../services/module-loading/host-module-loader-registry.js";
-import { invariant } from "../../utils/invariant.js";
-import { fileSystem } from "@ecopages/file-system";
-import { parseCliArgs } from "../../utils/parse-cli-args.js";
-class AbstractApplicationAdapter {
-  appConfig;
-  serverOptions;
-  cliArgs;
-  runtimeOptions;
-  apiHandlers = [];
-  staticRoutes = [];
-  errorHandler;
-  constructor(options) {
-    this.appConfig = options.appConfig;
-    this.serverOptions = options.serverOptions || {};
-    this.runtimeOptions = options.runtime ?? {};
-    this.cliArgs = parseCliArgs({ embeddedRuntime: this.runtimeOptions.embedded });
-    const hostModuleLoader = this.runtimeOptions.hostModuleLoader ?? (this.runtimeOptions.embedded ? getHostModuleLoader() : void 0);
-    if (hostModuleLoader) {
-      setAppHostModuleLoader(this.appConfig, hostModuleLoader);
-    }
-    getAppModuleLoader(this.appConfig);
-    if (options.clearOutput) {
-      this.clearDistFolder().catch((error) => {
-        appLogger.error("Error clearing dist folder", error);
-      });
-    }
-  }
-  async clearDistFolder() {
-    const distPath = this.appConfig.absolutePaths.distDir;
-    const distExists = fileSystem.exists(distPath);
-    if (!distExists) return;
-    try {
-      await fileSystem.removeAsync(distPath);
-      appLogger.debug(`Cleared dist folder: ${distPath}`);
-    } catch (error) {
-      appLogger.error(`Error clearing dist folder: ${distPath}`, error);
-    }
-  }
-  /**
-   * Internal method to add route handlers to the API handlers array
-   */
-  addRouteHandler(path, method, handler, middleware, schema) {
-    invariant(
-      typeof path === "string",
-      `Invalid route path for ${method}: expected a string path starting with "/" but received ${Object.prototype.toString.call(path)}. If you're passing a prebuilt ApiHandler, use app.add(handler).`
-    );
-    invariant(
-      path.startsWith("/"),
-      `Invalid route path for ${method}: "${path}". Route paths must start with '/'.`
-    );
-    this.apiHandlers.push({
-      path,
-      method,
-      handler,
-      middleware,
-      schema
-    });
-    return this;
-  }
-  /**
-   * Get all registered API handlers
-   */
-  getApiHandlers() {
-    return this.apiHandlers;
-  }
-  /**
-   * Register a view for static generation at build time.
-   * The view must have staticPaths defined for dynamic routes.
-   *
-   * Uses a loader function to enable HMR in development.
-   *
-   * @param path - URL path pattern (e.g., '/posts/:slug')
-   * @param loader - A function that dynamically imports the eco.page view module
-   * @example
-   * ```typescript
-   * app.static('/login', () => import('./src/views/login.kita'))
-   * app.static('/posts/:slug', () => import('./src/views/post-view.kita'))
-   * ```
-   */
-  static(path, loader) {
-    this.staticRoutes.push({ path, loader });
-    return this;
-  }
-  /**
-   * Get all registered static routes
-   */
-  getStaticRoutes() {
-    return this.staticRoutes;
-  }
-  /**
-   * Register a global error handler for all routes.
-   * Useful for logging, monitoring integration, and custom error formatting.
-   *
-   * @example
-   * ```typescript
-   * app.onError(async (error, ctx) => {
-   *   logger.error(error);
-   *   return ctx.response.status(500).json({ error: 'Something went wrong' });
-   * });
-   * ```
-   */
-  onError(handler) {
-    this.errorHandler = handler;
-    return this;
-  }
-  /**
-   * Get the registered error handler
-   */
-  getErrorHandler() {
-    return this.errorHandler;
-  }
+/**
+ * This file defines the abstract class for application adapters in EcoPages.
+ * It provides a common interface for different runtimes (e.g., Node.js, Deno) to implement.
+ * The class includes methods for handling HTTP requests and managing application state.
+ * It also includes a method for parsing command-line arguments.
+ *
+ * @module ApplicationAdapter
+ */
+import { appLogger } from '../../global/app-logger.js';
+import { getAppModuleLoader, setAppHostModuleLoader, } from '../../services/module-loading/app-server-module-transpiler.service.js';
+import { getHostModuleLoader } from '../../services/module-loading/host-module-loader-registry.js';
+import { invariant } from '../../utils/invariant.js';
+import { fileSystem } from '@ecopages/file-system';
+import { formatRuntimeServerStartedMessage, } from '../../dev/runtime-server-started-message.js';
+import { parseCliArgs } from '../../utils/parse-cli-args.js';
+import { startupTrace } from '../../diagnostics/startup-trace.js';
+/**
+ * Abstract base class for application adapters across different runtimes
+ */
+export class AbstractApplicationAdapter {
+    appConfig;
+    serverOptions;
+    cliArgs;
+    runtimeOptions;
+    apiHandlers = [];
+    staticRoutes = [];
+    errorHandler;
+    /**
+     * App-level WebSocket handlers keyed by URL path pattern (e.g. '/ws/chat/:id').
+     * Both Bun and Node adapters read this map to register upgrade routes.
+     */
+    websocketHandlers = new Map();
+    onAppStartCallback;
+    runtimeLabel;
+    constructor(options, runtimeLabel) {
+        this.runtimeLabel = runtimeLabel;
+        this.appConfig = options.appConfig;
+        this.serverOptions = options.serverOptions || {};
+        this.runtimeOptions = options.runtime ?? {};
+        if (options.runtime) {
+            this.appConfig.runtime = {
+                ...(this.appConfig.runtime ?? {}),
+                ...options.runtime,
+            };
+        }
+        this.cliArgs = parseCliArgs({ embeddedRuntime: this.runtimeOptions.embedded });
+        const hostModuleLoader = this.runtimeOptions.hostModuleLoader ?? (this.runtimeOptions.embedded ? getHostModuleLoader() : undefined);
+        if (hostModuleLoader) {
+            setAppHostModuleLoader(this.appConfig, hostModuleLoader);
+        }
+        getAppModuleLoader(this.appConfig);
+        startupTrace.markConfigReady();
+        if (options.clearOutput) {
+            this.clearDistFolder().catch((error) => {
+                appLogger.error('Error clearing dist folder', error);
+            });
+        }
+    }
+    async clearDistFolder() {
+        const distPath = this.appConfig.absolutePaths.distDir;
+        const distExists = fileSystem.exists(distPath);
+        if (!distExists)
+            return;
+        try {
+            await fileSystem.removeAsync(distPath);
+            appLogger.debug(`Cleared dist folder: ${distPath}`);
+        }
+        catch (error) {
+            appLogger.error(`Error clearing dist folder: ${distPath}`, error);
+        }
+    }
+    /**
+     * Internal method to add route handlers to the API handlers array
+     */
+    addRouteHandler(path, method, handler, middleware, schema) {
+        invariant(typeof path === 'string', `Invalid route path for ${method}: expected a string path starting with "/" but received ${Object.prototype.toString.call(path)}. If you're passing a prebuilt ApiHandler, use app.add(handler).`);
+        invariant(path.startsWith('/'), `Invalid route path for ${method}: "${path}". Route paths must start with '/'.`);
+        this.apiHandlers.push({
+            path,
+            method,
+            handler: handler,
+            middleware: middleware,
+            schema,
+        });
+        return this;
+    }
+    /**
+     * Get all registered API handlers
+     */
+    getApiHandlers() {
+        return this.apiHandlers;
+    }
+    /**
+     * Register a view for static generation at build time.
+     * The view must have staticPaths defined for dynamic routes.
+     *
+     * Uses a loader function to enable HMR in development.
+     *
+     * @param path - URL path pattern (e.g., '/posts/:slug')
+     * @param loader - A function that dynamically imports the eco.page view module
+     * @example
+     * ```typescript
+     * app.static('/login', () => import('./src/views/login.kita'))
+     * app.static('/posts/:slug', () => import('./src/views/post-view.kita'))
+     * ```
+     */
+    static(path, loader) {
+        this.staticRoutes.push({ path, loader });
+        return this;
+    }
+    /**
+     * Get all registered static routes
+     */
+    getStaticRoutes() {
+        return this.staticRoutes;
+    }
+    /**
+     * Register a WebSocket handler for the given path pattern.
+     *
+     * The runtime adapter handles the HTTP→WebSocket upgrade for this path
+     * and routes lifecycle events to `handler`.
+     *
+     * Supports dynamic segments via `:param` syntax. The handler receives
+     * typed `params` and `search` fields, and a typed `context` produced by
+     * the optional `context()` factory.
+     *
+     * One pattern registration matches infinite path variations. For example,
+     * `app.websocket('/ws/chat/:roomId', handler)` matches `/ws/chat/abc`,
+     * `/ws/chat/xyz`, etc. Each connection receives its own `params.roomId`.
+     *
+     * Works across both Bun and Node runtimes — no runtime-specific imports needed.
+     *
+     * @example
+     * ```typescript
+     * app.websocket<ChatContext, { roomId: string }>('/ws/chat/:roomId', {
+     *   async context({ params, search }) {
+     *     return { username: search.username ?? 'anonymous', roomId: params.roomId };
+     *   },
+     *   onConnect(socket) {
+     *     socket.send(`Welcome to room ${socket.context.roomId}`);
+     *   },
+     *   onMessage(socket, message) {
+     *     if (message.kind === 'text') {
+     *       socket.send(message.text);
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    websocket(path, handler) {
+        invariant(typeof path === 'string' && path.startsWith('/'), `app.websocket(): path must be a string starting with "/", got "${path}".`);
+        /**
+         * Validate the pattern at registration time. Reject empty segments
+         * and duplicate param names early.
+         */
+        const segments = path.split('/').filter(Boolean);
+        const paramNames = new Set();
+        for (const segment of segments) {
+            if (segment.startsWith(':')) {
+                const paramName = segment.slice(1);
+                invariant(paramName.length > 0, `app.websocket(): invalid pattern "${path}" — empty param name in segment ":${paramName}".`);
+                invariant(!paramNames.has(paramName), `app.websocket(): invalid pattern "${path}" — duplicate param name ":${paramName}".`);
+                paramNames.add(paramName);
+            }
+        }
+        this.websocketHandlers.set(path, handler);
+        return this;
+    }
+    /**
+     * Get the registered WebSocket handlers map.
+     *
+     * @returns The map of WebSocket route patterns to handlers
+     */
+    getWebsocketHandlers() {
+        return this.websocketHandlers;
+    }
+    /**
+     * Register a global error handler for all routes.
+     * Useful for logging, monitoring integration, and custom error formatting.
+     *
+     * @example
+     * ```typescript
+     * app.onError(async (error, ctx) => {
+     *   logger.error(error);
+     *   return ctx.response.status(500).json({ error: 'Something went wrong' });
+     * });
+     * ```
+     */
+    onError(handler) {
+        this.errorHandler = handler;
+        return this;
+    }
+    /**
+     * Get the registered error handler
+     */
+    getErrorHandler() {
+        return this.errorHandler;
+    }
+    /**
+     * Boot the server. When `onAppStart` is passed, it runs once the runtime can take traffic.
+     * Embedded apps only register the callback — the host (for example Vite) boots the port.
+     */
+    async start(onAppStart) {
+        if (onAppStart) {
+            this.onAppStartCallback = onAppStart;
+        }
+        if (this.runtimeOptions.embedded) {
+            return;
+        }
+        return this.bootServer();
+    }
+    logServerStarted(origin) {
+        appLogger.info(formatRuntimeServerStartedMessage(this.runtimeLabel, origin));
+    }
+    /**
+     * Invoked by embedded hosts (for example Vite) once the app can take traffic.
+     */
+    async handleListening(origin) {
+        await this.notifyListening(origin);
+    }
+    async notifyListening(origin) {
+        const normalizedOrigin = origin.replace(/\/$/, '');
+        startupTrace.markServerListening();
+        if (!this.onAppStartCallback) {
+            this.logServerStarted(normalizedOrigin);
+            return;
+        }
+        await this.invokeAppStartCallback(normalizedOrigin);
+    }
+    /**
+     * Resolves routes exposed on {@link AppStartInfo}.
+     *
+     * @remarks
+     * Default is empty. Runtime adapters override this to read from the
+     * initialized server route registry.
+     */
+    async resolveAppRoutes() {
+        return [];
+    }
+    async invokeAppStartCallback(origin) {
+        let routes = [];
+        try {
+            routes = await this.resolveAppRoutes();
+        }
+        catch (error) {
+            appLogger.debug('Failed to resolve app start routes; continuing with empty routes', error instanceof Error ? error.message : String(error));
+        }
+        this.onAppStartCallback?.({ origin, routes });
+    }
+    /**
+     * Stops the application server and releases runtime resources.
+     *
+     * @remarks
+     * Subclasses override this to shut down bound servers, watchers, and other
+     * dev-time resources. The default implementation is a no-op so embedded
+     * adapters that never call `start()` can still be used with `await using`.
+     */
+    async stop(_force = true) { }
+    async [Symbol.asyncDispose]() {
+        await this.stop(true);
+    }
 }
-export {
-  AbstractApplicationAdapter
-};

package/src/adapters/abstract/router-adapter.js

@@ -1,5 +1,13 @@
-class AbstractRouterAdapter {
+/**
+ * This file contains the abstract router adapter class and its methods.
+ * It is designed to be extended by specific router adapters for different runtimes.
+ * The class provides methods for converting paths, creating route handlers,
+ * and adapting routes to the expected format of the runtime.
+ *
+ * @module RouterAdapter
+ */
+/**
+ * Abstract base class for router adapters across different runtimes
+ */
+export class AbstractRouterAdapter {
 }
-export {
-  AbstractRouterAdapter
-};

package/src/adapters/abstract/segment-path-matcher.d.ts

@@ -0,0 +1,6 @@
+export declare function normalizeSegmentPath(pathname: string): string;
+export declare function matchApiPathPattern(pattern: string, pathname: string): Record<string, string | string[]> | null;
+export declare function scoreApiPathPattern(pattern: string): number;
+export declare function matchExplicitStaticPathPattern(pattern: string, pathname: string): Record<string, string> | null;
+export declare function matchColonSegmentPath(pattern: string, pathname: string): Record<string, string> | null;
+export declare function scoreColonSegmentPath(pattern: string): number;