@ecopages/core 0.2.0-alpha.22 → 0.2.0-alpha.24

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

@@ -1,121 +0,0 @@
-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;
-  }
-}
-export {
-  AbstractApplicationAdapter
-};

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

@@ -1,26 +0,0 @@
-/**
- * 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
- */
-import type { Routes } from '../../types/internal-types.js';
-/**
- * Abstract base class for router adapters across different runtimes
- */
-export declare abstract class AbstractRouterAdapter<TRouteFormat = any> {
-    /**
-     * Convert a route path to the format expected by the runtime
-     */
-    protected abstract convertPath(pathname: string): string;
-    /**
-     * Create a route handler compatible with the runtime
-     */
-    protected abstract createRouteHandler(route: any): any;
-    /**
-     * Adapt framework routes to the format expected by the runtime
-     */
-    abstract adaptRoutes(routes: Routes): TRouteFormat;
-}

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

@@ -1,5 +0,0 @@
-class AbstractRouterAdapter {
-}
-export {
-  AbstractRouterAdapter
-};

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

@@ -1,69 +0,0 @@
-/**
- * This file contains the abstract server adapter class and its related types.
- * It is designed to be extended by specific server adapters for different runtimes.
- * The class provides methods for initializing the server, creating server options,
- * building static files, and handling HTTP requests.
- *
- * @module ServerAdapter
- */
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { ApiHandler } from '../../types/public-types.js';
-/**
- * Configuration options for all server adapters
- */
-export interface ServerAdapterOptions {
-    appConfig: EcoPagesAppConfig;
-    apiHandlers?: ApiHandler<string, any>[];
-    options?: {
-        watch?: boolean;
-        [key: string]: any;
-    };
-    serveOptions?: Record<string, any>;
-    runtimeOrigin: string;
-}
-/**
- * Base adapter result containing common functionalities
- * across different runtime implementations
- */
-export interface ServerAdapterResult {
-    getServerOptions: (options?: {
-        enableHmr?: boolean;
-    }) => any;
-    buildStatic: (options?: {
-        preview?: boolean;
-    }) => Promise<void>;
-}
-/**
- * Abstract base class for server adapters across different runtimes
- */
-export declare abstract class AbstractServerAdapter<TOptions extends ServerAdapterOptions = ServerAdapterOptions, TResult extends ServerAdapterResult = ServerAdapterResult> {
-    protected appConfig: EcoPagesAppConfig;
-    protected options: TOptions['options'];
-    protected serveOptions: TOptions['serveOptions'];
-    protected runtimeOrigin: string;
-    constructor(options: TOptions);
-    /**
-     * Initialize the server adapter
-     */
-    abstract initialize(): Promise<void>;
-    /**
-     * Create server options specific to the runtime
-     */
-    abstract getServerOptions(options?: {
-        enableHmr?: boolean;
-    }): any;
-    /**
-     * Build static files for the application
-     */
-    abstract buildStatic(options?: {
-        preview?: boolean;
-    }): Promise<void>;
-    /**
-     * Factory method to create a server adapter with runtime-specific functionality
-     */
-    abstract createAdapter(): Promise<TResult>;
-    /**
-     * Handle HTTP requests
-     */
-    abstract handleRequest(request: Request): Promise<Response>;
-}

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

@@ -1,15 +0,0 @@
-class AbstractServerAdapter {
-  appConfig;
-  options;
-  serveOptions;
-  runtimeOrigin;
-  constructor(options) {
-    this.appConfig = options.appConfig;
-    this.options = options.options || {};
-    this.serveOptions = options.serveOptions || {};
-    this.runtimeOrigin = options.runtimeOrigin;
-  }
-}
-export {
-  AbstractServerAdapter
-};

package/src/adapters/bun/client-bridge.d.ts

@@ -1,34 +0,0 @@
-import type { ServerWebSocket } from 'bun';
-import type { ClientBridgeEvent, IClientBridge } from '../../types/public-types.js';
-type BunSocket = ServerWebSocket<unknown>;
-/**
- * Manages WebSocket subscribers and broadcasts development events.
- * Bridges the gap between the server and the development client.
- */
-export declare class ClientBridge implements IClientBridge {
-    private subscribers;
-    subscribe(ws: BunSocket): void;
-    unsubscribe(ws: BunSocket): void;
-    /**
-     * Broadcast a raw event to all connected clients.
-     */
-    broadcast(event: ClientBridgeEvent): void;
-    /**
-     * Trigger a full page reload on all connected clients.
-     */
-    reload(): void;
-    /**
-     * Broadcast a CSS update for hot stylesheet reload.
-     */
-    cssUpdate(path: string): void;
-    /**
-     * Broadcast a JS module update for hot module replacement.
-     */
-    update(path: string): void;
-    /**
-     * Broadcast an error message to connected clients.
-     */
-    error(message: string): void;
-    get subscriberCount(): number;
-}
-export {};

package/src/adapters/bun/client-bridge.js

@@ -1,48 +0,0 @@
-class ClientBridge {
-  subscribers = /* @__PURE__ */ new Set();
-  subscribe(ws) {
-    this.subscribers.add(ws);
-  }
-  unsubscribe(ws) {
-    this.subscribers.delete(ws);
-  }
-  /**
-   * Broadcast a raw event to all connected clients.
-   */
-  broadcast(event) {
-    const payload = JSON.stringify(event);
-    for (const ws of this.subscribers) {
-      ws.send(payload);
-    }
-  }
-  /**
-   * Trigger a full page reload on all connected clients.
-   */
-  reload() {
-    this.broadcast({ type: "reload" });
-  }
-  /**
-   * Broadcast a CSS update for hot stylesheet reload.
-   */
-  cssUpdate(path) {
-    this.broadcast({ type: "css-update", path, timestamp: Date.now() });
-  }
-  /**
-   * Broadcast a JS module update for hot module replacement.
-   */
-  update(path) {
-    this.broadcast({ type: "update", path, timestamp: Date.now() });
-  }
-  /**
-   * Broadcast an error message to connected clients.
-   */
-  error(message) {
-    this.broadcast({ type: "error", message });
-  }
-  get subscriberCount() {
-    return this.subscribers.size;
-  }
-}
-export {
-  ClientBridge
-};

package/src/adapters/bun/create-app.d.ts

@@ -1,52 +0,0 @@
-/**
- * This file contains the implementation of the Bun application adapter for EcoPages.
- * It extends the AbstractApplicationAdapter class and provides methods for handling
- * HTTP requests, initializing the server adapter, and starting the Bun application server.
- * The adapter is designed to work with the Bun runtime and provides a way to create
- * EcoPages applications using Bun's features.
- *
- * @module EcopagesApp
- */
-import type { Server } from 'bun';
-import type { ApiHandlerContext, RouteGroupBuilder } from '../../types/public-types.js';
-import { SharedApplicationAdapter } from '../shared/application-adapter.js';
-import type { EcopagesAppOptions } from '../create-app.js';
-import { type BunServerAdapterResult } from './server-adapter.js';
-/**
- * Bun-specific route group builder that properly infers route params from path patterns.
- * When you define a route like `/posts/:slug`, the handler context will have
- * `ctx.params.slug` typed as `string`.
- *
- * @typeParam WebSocketData - WebSocket data type for the server
- * @typeParam TContext - Extended context type from middleware (e.g., `{ user: User }`)
- */
-export type BunRouteGroupBuilder<WebSocketData = undefined, TContext extends ApiHandlerContext<Request, Server<WebSocketData>> = ApiHandlerContext<Request, Server<WebSocketData>>> = RouteGroupBuilder<Request, Server<WebSocketData>, TContext>;
-/**
- * Bun-specific application adapter implementation
- * This class extends the {@link AbstractApplicationAdapter}
- * and provides methods for handling HTTP requests and managing the server.
- */
-export declare class BunEcopagesApp<WebSocketData = undefined> extends SharedApplicationAdapter<EcopagesAppOptions, Server<WebSocketData>, Request> {
-    serverAdapter: BunServerAdapterResult | undefined;
-    private server;
-    fetch(request: Request): Promise<Response>;
-    /**
-     * Complete the initialization of the server adapter by processing dynamic routes
-     * @param server The Bun server instance
-     */
-    completeInitialization(server: Server<WebSocketData>): Promise<void>;
-    /**
-     * Initialize the Bun server adapter
-     */
-    protected initializeServerAdapter(): Promise<BunServerAdapterResult>;
-    /**
-     * Start the Bun application server
-     * @param options Optional settings
-     * @param options.autoCompleteInitialization Whether to automatically complete initialization with dynamic routes after server start (defaults to true)
-     */
-    start(): Promise<Server<WebSocketData> | void>;
-}
-/**
- * Factory function to create a Bun application
- */
-export declare function createApp<WebSocketData = undefined>(options: EcopagesAppOptions): Promise<BunEcopagesApp<WebSocketData>>;

package/src/adapters/bun/create-app.js

@@ -1,116 +0,0 @@
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
-import { appLogger } from "../../global/app-logger.js";
-import { getBunRuntime } from "../../utils/runtime.js";
-import { SharedApplicationAdapter } from "../shared/application-adapter.js";
-import { createBunServerAdapter } from "./server-adapter.js";
-class BunEcopagesApp extends SharedApplicationAdapter {
-  serverAdapter;
-  server = null;
-  async fetch(request) {
-    if (!this.serverAdapter) {
-      this.serverAdapter = await this.initializeServerAdapter();
-    }
-    await this.serverAdapter.completeInitialization(this.server);
-    return this.serverAdapter.handleRequest(request);
-  }
-  /**
-   * Complete the initialization of the server adapter by processing dynamic routes
-   * @param server The Bun server instance
-   */
-  async completeInitialization(server) {
-    if (!this.serverAdapter) {
-      throw new Error("Server adapter not initialized. Call start() first.");
-    }
-    await this.serverAdapter.completeInitialization(server);
-  }
-  /**
-   * Initialize the Bun server adapter
-   */
-  async initializeServerAdapter() {
-    const { dev } = this.cliArgs;
-    const { port: cliPort, hostname: cliHostname } = this.cliArgs;
-    const envPort = process.env.ECOPAGES_PORT ? process.env.ECOPAGES_PORT : void 0;
-    const envHostname = process.env.ECOPAGES_HOSTNAME;
-    const preferredPort = cliPort ?? envPort ?? DEFAULT_ECOPAGES_PORT;
-    const preferredHostname = cliHostname ?? envHostname ?? DEFAULT_ECOPAGES_HOSTNAME;
-    appLogger.debug("initializeServerAdapter", {
-      dev,
-      cliPort,
-      cliHostname,
-      envPort,
-      envHostname,
-      preferredPort,
-      preferredHostname,
-      composedUrl: `http://${preferredHostname}:${preferredPort}`
-    });
-    return await createBunServerAdapter({
-      runtimeOrigin: `http://${preferredHostname}:${preferredPort}`,
-      appConfig: this.appConfig,
-      apiHandlers: this.apiHandlers,
-      staticRoutes: this.staticRoutes,
-      errorHandler: this.errorHandler,
-      options: { watch: dev },
-      serveOptions: {
-        port: preferredPort,
-        hostname: preferredHostname,
-        ...this.serverOptions
-      }
-    });
-  }
-  /**
-   * Start the Bun application server
-   * @param options Optional settings
-   * @param options.autoCompleteInitialization Whether to automatically complete initialization with dynamic routes after server start (defaults to true)
-   */
-  async start() {
-    if (!this.serverAdapter) {
-      this.serverAdapter = await this.initializeServerAdapter();
-    }
-    const { dev, preview, build } = this.cliArgs;
-    const requiresFetchRuntime = this.appConfig.integrations.some(
-      (integration) => integration.staticBuildStep === "fetch"
-    );
-    const canBuildWithoutRuntimeServer = (build || preview) && !requiresFetchRuntime;
-    if (canBuildWithoutRuntimeServer) {
-      appLogger.debugTime("Building static pages");
-      await this.serverAdapter.buildStatic({ preview });
-      appLogger.debugTimeEnd("Building static pages");
-      if (build) {
-        process.exit(0);
-      }
-      return;
-    }
-    const enableHmr = dev || !preview && !build;
-    const serverOptions = this.serverAdapter.getServerOptions({ enableHmr });
-    const bun = getBunRuntime();
-    if (!bun) {
-      throw new Error("Bun runtime is required for the Bun adapter");
-    }
-    const bunServer = bun.serve(serverOptions);
-    this.server = bunServer;
-    await this.serverAdapter.completeInitialization(this.server).catch((error) => {
-      appLogger.error(`Failed to complete initialization: ${error}`);
-    });
-    if (!this.server) {
-      throw new Error("Server failed to start");
-    }
-    appLogger.info(`Server running at http://${this.server.hostname}:${this.server.port}`);
-    if (build || preview) {
-      appLogger.debugTime("Building static pages");
-      await this.serverAdapter.buildStatic({ preview });
-      this.server.stop(true);
-      appLogger.debugTimeEnd("Building static pages");
-      if (build) {
-        process.exit(0);
-      }
-    }
-    return this.server;
-  }
-}
-async function createApp(options) {
-  return new BunEcopagesApp(options);
-}
-export {
-  BunEcopagesApp,
-  createApp
-};

package/src/adapters/bun/hmr-manager.d.ts

@@ -1,143 +0,0 @@
-import type { WebSocketHandler } from 'bun';
-import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.js';
-import type { EcoBuildPlugin } from '../../build/build-types.js';
-import { type HmrStrategy } from '../../hmr/hmr-strategy.js';
-import type { ClientBridge } from './client-bridge.js';
-import type { ClientBridgeEvent } from '../../types/public-types.js';
-type BunSocketHandler = WebSocketHandler<unknown>;
-export interface HmrManagerParams {
-    appConfig: EcoPagesAppConfig;
-    bridge: ClientBridge;
-}
-type HandleFileChangeOptions = {
-    broadcast?: boolean;
-};
-/**
- * Bun development HMR manager.
- *
- * @remarks
- * Bun shares the same public contract as the Node manager: page entrypoints are
- * strict integration-owned registrations, while generic script assets use their
- * own explicit registration path.
- */
-export declare class HmrManager implements IHmrManager {
-    private static readonly entrypointRegistrationTimeoutMs;
-    readonly appConfig: EcoPagesAppConfig;
-    private readonly bridge;
-    /** Keep track of watchers */
-    private watchers;
-    /** entrypoint -> output path */
-    private watchedFiles;
-    private entrypointRegistrations;
-    private distDir;
-    private plugins;
-    private enabled;
-    private strategies;
-    private readonly entrypointRegistrar;
-    private readonly browserBundleService;
-    private readonly entrypointDependencyGraph;
-    private readonly runtimeSpecifierRegistry;
-    private readonly serverModuleTranspiler;
-    private wsHandler;
-    constructor({ appConfig, bridge }: HmrManagerParams);
-    /**
-     * Ensures the HMR output directory exists.
-     *
-     * This must not remove the directory because multiple app processes
-     * can share the same dist path during e2e runs.
-     */
-    private cleanDistDir;
-    /**
-     * Returns whether the generic JS strategy may rebuild an entrypoint.
-     *
-     * @remarks
-     * Integration-owned page entrypoints are excluded so a shared dependency
-     * invalidation cannot replace framework-owned browser output with a generic JS
-     * rebuild.
-     */
-    private shouldJsStrategyProcessEntrypoint;
-    /**
-     * Initializes core HMR strategies.
-     * Strategies are evaluated in priority order (highest first).
-     */
-    private initializeStrategies;
-    /**
-     * Registers a custom HMR strategy.
-     * Used by integrations to provide framework-specific HMR handling.
-     * @param strategy - The HMR strategy to register
-     */
-    registerStrategy(strategy: HmrStrategy): void;
-    setPlugins(plugins: EcoBuildPlugin[]): void;
-    setEnabled(enabled: boolean): void;
-    isEnabled(): boolean;
-    /**
-     * Registers runtime bare-specifier mappings exposed by integrations.
-     *
-     * @remarks
-     * These mappings are consumed by framework-owned HMR strategies that preserve
-     * shared runtime imports in browser bundles. The registry stays generic so
-     * these mappings can later support broader import-map-style runtime features
-     * without moving integration semantics into core.
-     */
-    registerSpecifierMap(map: Record<string, string>): void;
-    getWebSocketHandler(): BunSocketHandler;
-    /**
-     * Builds the client-side HMR runtime script.
-     */
-    buildRuntime(): Promise<void>;
-    getRuntimePath(): string;
-    broadcast(event: ClientBridgeEvent): void;
-    handleFileChange(filePath: string, options?: HandleFileChangeOptions): Promise<void>;
-    getOutputUrl(entrypointPath: string): string | undefined;
-    getWatchedFiles(): Map<string, string>;
-    getSpecifierMap(): Map<string, string>;
-    getDistDir(): string;
-    getPlugins(): EcoBuildPlugin[];
-    getDefaultContext(): DefaultHmrContext;
-    private clearFailedEntrypointRegistration;
-    /**
-     * Registers one integration-owned page entrypoint.
-     *
-     * @remarks
-     * Concurrent callers share one in-flight registration. The registration is
-     * cleared from the dedupe map when it settles so later callers cannot inherit a
-     * stale promise.
-     */
-    registerEntrypoint(entrypointPath: string): Promise<string>;
-    /**
-     * Registers one generic script entrypoint.
-     *
-     * @remarks
-     * This explicit path keeps the page-entrypoint contract strict while still
-     * allowing generic script assets to use the fallback build path.
-     */
-    registerScriptEntrypoint(entrypointPath: string): Promise<string>;
-    /**
-     * Performs strict integration-owned registration for one normalized path.
-     *
-     * @remarks
-     * The manager reserves the output URL, removes any stale emitted file, runs
-     * strategy processing without broadcasting, and then verifies that the owning
-     * integration emitted the expected file.
-     */
-    private emitStrictEntrypoint;
-    /**
-     * Performs registration for a generic script asset.
-     *
-     * @remarks
-     * This path performs a targeted browser bundle for the requested script
-     * entrypoint only. The resulting dependency graph is retained so later file
-     * changes can invalidate just the affected script entrypoints.
-     */
-    private emitScriptEntrypoint;
-    /**
-     * Stops active watchers and releases retained registration state.
-     *
-     * @remarks
-     * Emitted `_hmr` files remain on disk because parallel app processes may share
-     * the same dist directory. The in-memory indexes are cleared so stale
-     * entrypoints and specifier maps cannot leak through a reused manager object.
-     */
-    stop(): void;
-}
-export {};