@ecopages/core 0.2.0-alpha.53 → 0.2.0-alpha.54

package/src/adapters/shared/fs-server-response-matcher.js

@@ -1,186 +0,0 @@
-import path from "node:path";
-import { appLogger } from "../../global/app-logger.js";
-import { PageRequestCacheCoordinator } from "../../services/cache/page-request-cache-coordinator.service.js";
-import { ServerUtils } from "../../utils/server-utils.module.js";
-import { FileRouteMiddlewarePipeline } from "./file-route-middleware-pipeline.js";
-import { LocalsAccessError } from "../../errors/locals-access-error.js";
-import { isDevelopmentRuntime } from "../../utils/runtime.js";
-class FileSystemResponseMatcher {
-  appConfig;
-  assetPrefix;
-  router;
-  routeRendererFactory;
-  fileSystemResponseFactory;
-  pageRequestCacheCoordinator;
-  fileRouteMiddlewarePipeline;
-  constructor({
-    appConfig,
-    assetPrefix,
-    router,
-    routeRendererFactory,
-    fileSystemResponseFactory,
-    cacheService = null,
-    defaultCacheStrategy = "static"
-  }) {
-    this.appConfig = appConfig;
-    this.assetPrefix = assetPrefix;
-    this.router = router;
-    this.routeRendererFactory = routeRendererFactory;
-    this.fileSystemResponseFactory = fileSystemResponseFactory;
-    this.pageRequestCacheCoordinator = new PageRequestCacheCoordinator(cacheService, defaultCacheStrategy);
-    this.fileRouteMiddlewarePipeline = new FileRouteMiddlewarePipeline(cacheService);
-  }
-  /**
-   * Resolves unmatched paths either as static asset requests or as the custom
-   * not-found page.
-   * @param requestUrl Incoming pathname.
-   * @returns Static file response or rendered 404 response.
-   */
-  async handleNoMatch(requestUrl) {
-    const isStaticFileRequest = ServerUtils.hasKnownExtension(requestUrl);
-    if (!isStaticFileRequest) {
-      return this.renderCustomNotFoundResponse();
-    }
-    const relativeUrl = requestUrl.startsWith("/") ? requestUrl.slice(1) : requestUrl;
-    const filePath = path.join(this.assetPrefix, relativeUrl);
-    const contentType = ServerUtils.getContentType(filePath);
-    const response = await this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
-    return response ?? this.renderCustomNotFoundResponse();
-  }
-  /**
-   * Handles a matched file-system page route.
-   *
-   * The method inspects page metadata needed for request-time execution,
-   * prepares the renderer invocation, validates middleware/cache constraints,
-   * and delegates caching plus middleware execution to dedicated collaborators.
-   *
-   * @param match Router match result.
-   * @param request Optional incoming request. A synthetic GET request is created when omitted.
-   * @returns Final response for the matched route.
-   */
-  async handleMatch(match, request) {
-    try {
-      const executionPlan = await this.createExecutionPlan(match, request);
-      this.fileRouteMiddlewarePipeline.assertValidConfiguration({
-        middleware: executionPlan.pageMiddleware,
-        pageCacheStrategy: executionPlan.pageCacheStrategy,
-        filePath: executionPlan.pageFilePath
-      });
-      const routeRenderer = this.routeRendererFactory.getPageRenderer(executionPlan.pageFilePath);
-      const middlewareContext = this.fileRouteMiddlewarePipeline.createContext({
-        request: executionPlan.request,
-        params: match.params,
-        locals: executionPlan.localsStore
-      });
-      const renderFn = async () => {
-        const result = await routeRenderer.execute({
-          file: executionPlan.pageFilePath,
-          params: match.params,
-          query: match.query,
-          locals: executionPlan.localsForRender
-        });
-        const html = await this.pageRequestCacheCoordinator.bodyToString(result.body);
-        const strategy = result.cacheStrategy ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
-        return { html, strategy };
-      };
-      const renderResponse = async () => {
-        return this.pageRequestCacheCoordinator.render({
-          cacheKey: executionPlan.cacheKey,
-          pageCacheStrategy: executionPlan.pageCacheStrategy,
-          renderFn
-        });
-      };
-      return await this.fileRouteMiddlewarePipeline.run({
-        middleware: executionPlan.pageMiddleware,
-        context: middlewareContext,
-        renderResponse
-      });
-    } catch (error) {
-      if (error instanceof Response) {
-        return error;
-      }
-      if (error instanceof LocalsAccessError) {
-        return new Response(error.message, {
-          status: 500,
-          headers: { "Content-Type": "text/plain; charset=utf-8" }
-        });
-      }
-      if (error instanceof Error) {
-        if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
-          appLogger.error(`[FileSystemResponseMatcher] ${error.message} at ${match.requestedPathname}`);
-        }
-      }
-      return this.renderCustomNotFoundResponse();
-    }
-  }
-  /**
-   * Renders the app-owned custom 404 page, falling back to the default text 404
-   * when the page template cannot be resolved.
-   */
-  async renderCustomNotFoundResponse() {
-    const error404TemplatePath = this.appConfig.absolutePaths.error404TemplatePath;
-    try {
-      const routeRenderer = this.routeRendererFactory.getPageRenderer(error404TemplatePath);
-      const result = await routeRenderer.execute({
-        file: error404TemplatePath
-      });
-      return this.fileSystemResponseFactory.createHtmlNotFoundResponse(result.body);
-    } catch {
-      appLogger.debug(
-        "Custom 404 template not found, falling back to default 404 response",
-        error404TemplatePath
-      );
-      return this.fileSystemResponseFactory.createDefaultNotFoundResponse();
-    }
-  }
-  async createExecutionPlan(match, request) {
-    const cacheKey = this.pageRequestCacheCoordinator.buildCacheKey({
-      pathname: match.requestedPathname,
-      query: match.query
-    });
-    const resolvedRequest = request ?? new Request(new URL(cacheKey, this.router.origin).toString(), {
-      method: "GET"
-    });
-    const localsStore = {};
-    const pageFilePath = match.templateRoute.filePath;
-    const pageModule = await this.importPageModule(pageFilePath);
-    const Page = pageModule?.default;
-    const pageMiddleware = Page?.middleware ?? [];
-    const pageCacheStrategy = Page?.cache ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
-    return {
-      cacheKey,
-      request: resolvedRequest,
-      pageFilePath,
-      pageMiddleware,
-      pageCacheStrategy,
-      localsStore,
-      localsForRender: pageCacheStrategy === "dynamic" ? localsStore : void 0
-    };
-  }
-  /**
-   * Loads the matched page module for request-time inspection.
-   *
-   * The matcher needs access to page-level metadata such as `cache` and
-   * `middleware` before full rendering starts, so it asks the owning route
-   * renderer to load the page module. That preserves integration-specific page
-   * import setup for request-time inspection as well as for full rendering.
-   *
-   * @param filePath Absolute page module path.
-   * @returns Imported page module.
-   */
-  async importPageModule(filePath) {
-    const routeRenderer = this.routeRendererFactory.getPageRenderer(filePath);
-    return routeRenderer.loadPageModule(filePath, {
-      cacheScope: "request-metadata"
-    });
-  }
-  /**
-   * Get the underlying cache service for external invalidation.
-   */
-  getCacheService() {
-    return this.pageRequestCacheCoordinator.getCacheService();
-  }
-}
-export {
-  FileSystemResponseMatcher
-};

package/src/adapters/shared/hmr-entrypoint-registrar.d.ts

@@ -1,55 +0,0 @@
-/**
- * Shared runtime state used while registering HMR-owned entrypoints.
- */
-export interface HmrEntrypointRegistrarOptions {
-    /** Absolute source directory used to derive the emitted HMR path. */
-    srcDir: string;
-    /** Absolute distribution directory where HMR outputs are written. */
-    distDir: string;
-    /** In-flight registrations keyed by normalized absolute entrypoint path. */
-    entrypointRegistrations: Map<string, Promise<string>>;
-    /** Stable entrypoint-to-output mapping retained once an entrypoint is registered. */
-    watchedFiles: Map<string, string>;
-    /** Runtime-specific cleanup invoked when an entrypoint registration fails. */
-    clearFailedRegistration?: (entrypointPath: string) => void;
-    /** Development-only guardrail for integrations that never finish producing output. */
-    registrationTimeoutMs: number;
-}
-/**
- * Runtime-specific hooks required to materialize a single HMR entrypoint.
- */
-export interface HmrEntrypointRegistrationOptions {
-    /**
-     * Emits the browser-consumable HMR artifact for an entrypoint.
-     */
-    emit(entrypointPath: string, outputPath: string): Promise<void>;
-    /**
-     * Creates the runtime-specific error raised when the emit hook completes without producing output.
-     */
-    getMissingOutputError(entrypointPath: string, outputPath: string): Error;
-}
-/**
- * Coordinates the shared HMR entrypoint registration lifecycle for both Node and Bun managers.
- *
- * The registrar owns the cross-runtime policy: normalize entrypoint identities, dedupe concurrent
- * registrations, derive the emitted `_hmr` output path, clear stale output before rebuilding, and
- * apply the development timeout that prevents unresolved registrations from hanging navigation.
- * Runtime-specific managers remain responsible for the actual emit step and any cleanup outside
- * this shared registration flow.
- */
-export declare class HmrEntrypointRegistrar {
-    private readonly options;
-    constructor(options: HmrEntrypointRegistrarOptions);
-    /**
-     * Registers a single source entrypoint and returns the browser URL for its emitted HMR module.
-     *
-     * Concurrent requests for the same normalized entrypoint share the same in-flight promise so the
-     * integration only builds once per registration cycle.
-     */
-    registerEntrypoint(entrypointPath: string, registrationOptions: HmrEntrypointRegistrationOptions): Promise<string>;
-    private registerEntrypointInternal;
-    private awaitEntrypointRegistration;
-    private getEntrypointOutput;
-    private removeStaleEntrypointOutput;
-    private encodeDynamicSegments;
-}

package/src/adapters/shared/hmr-entrypoint-registrar.js

@@ -1,87 +0,0 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-import { appLogger } from "../../global/app-logger.js";
-import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
-class HmrEntrypointRegistrar {
-  options;
-  constructor(options) {
-    this.options = options;
-  }
-  /**
-   * Registers a single source entrypoint and returns the browser URL for its emitted HMR module.
-   *
-   * Concurrent requests for the same normalized entrypoint share the same in-flight promise so the
-   * integration only builds once per registration cycle.
-   */
-  async registerEntrypoint(entrypointPath, registrationOptions) {
-    const normalizedEntrypoint = path.resolve(entrypointPath);
-    const existingRegistration = this.options.entrypointRegistrations.get(normalizedEntrypoint);
-    if (existingRegistration) {
-      return await this.awaitEntrypointRegistration(existingRegistration, normalizedEntrypoint);
-    }
-    const registration = this.registerEntrypointInternal(normalizedEntrypoint, registrationOptions);
-    this.options.entrypointRegistrations.set(normalizedEntrypoint, registration);
-    try {
-      return await this.awaitEntrypointRegistration(registration, normalizedEntrypoint);
-    } catch (error) {
-      this.options.clearFailedRegistration?.(normalizedEntrypoint);
-      throw error;
-    } finally {
-      this.options.entrypointRegistrations.delete(normalizedEntrypoint);
-    }
-  }
-  async registerEntrypointInternal(entrypointPath, registrationOptions) {
-    if (this.options.watchedFiles.has(entrypointPath)) {
-      return this.options.watchedFiles.get(entrypointPath);
-    }
-    const { outputPath, outputUrl } = this.getEntrypointOutput(entrypointPath);
-    this.options.watchedFiles.set(entrypointPath, outputUrl);
-    this.removeStaleEntrypointOutput(outputPath);
-    await registrationOptions.emit(entrypointPath, outputPath);
-    if (!fileSystem.exists(outputPath)) {
-      throw registrationOptions.getMissingOutputError(entrypointPath, outputPath);
-    }
-    return outputUrl;
-  }
-  async awaitEntrypointRegistration(registration, entrypointPath) {
-    if (process.env.NODE_ENV !== "development") {
-      return await registration;
-    }
-    return await Promise.race([
-      registration,
-      new Promise((_, reject) => {
-        setTimeout(() => {
-          reject(new Error(`[HMR] Timed out registering entrypoint: ${entrypointPath}`));
-        }, this.options.registrationTimeoutMs);
-      })
-    ]);
-  }
-  getEntrypointOutput(entrypointPath) {
-    const relativePath = path.relative(this.options.srcDir, entrypointPath);
-    const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
-    const encodedPathJs = this.encodeDynamicSegments(relativePathJs);
-    const urlPath = encodedPathJs.split(path.sep).join("/");
-    return {
-      outputUrl: `/${path.join(RESOLVED_ASSETS_DIR, "_hmr", urlPath)}`,
-      outputPath: path.join(this.options.distDir, urlPath)
-    };
-  }
-  removeStaleEntrypointOutput(outputPath) {
-    if (!fileSystem.exists(outputPath)) {
-      return;
-    }
-    try {
-      fileSystem.remove(outputPath);
-    } catch (error) {
-      appLogger.warn(
-        `[HMR] Failed to remove stale entrypoint output ${outputPath}: ${error instanceof Error ? error.message : String(error)}`
-      );
-    }
-  }
-  encodeDynamicSegments(filepath) {
-    return filepath.replace(/\[([^\]]+)\]/g, "_$1_");
-  }
-}
-export {
-  HmrEntrypointRegistrar
-};

package/src/adapters/shared/hmr-html-response.d.ts

@@ -1,22 +0,0 @@
-import type { IHmrManager } from '../../types/public-types.js';
-/**
- * Returns whether a response is HTML and therefore eligible for development HMR
- * runtime injection.
- */
-export declare function isHtmlResponse(response: Response): boolean;
-/**
- * Returns whether HTML responses should receive the HMR runtime bootstrap.
- *
- * This is shared because filesystem page responses and adapter-level HTML
- * responses flow through different layers, but both need identical injection
- * behavior in watch mode.
- */
-export declare function shouldInjectHmrHtmlResponse(watch: boolean, hmrManager?: Pick<IHmrManager, 'isEnabled'>): boolean;
-/**
- * Injects the development HMR runtime script into an HTML response if it is not
- * already present.
- *
- * The check is intentionally idempotent because an HTML response can pass
- * through more than one development-layer wrapper before reaching the client.
- */
-export declare function injectHmrRuntimeIntoHtmlResponse(response: Response): Promise<Response>;

package/src/adapters/shared/hmr-html-response.js

@@ -1,33 +0,0 @@
-const HMR_RUNTIME_IMPORT = "import '/_hmr_runtime.js'";
-const HMR_RUNTIME_SCRIPT = `<script type="module">${HMR_RUNTIME_IMPORT};<\/script>`;
-function isHtmlResponse(response) {
-  const contentType = response.headers.get("Content-Type");
-  return contentType !== null && contentType.startsWith("text/html");
-}
-function shouldInjectHmrHtmlResponse(watch, hmrManager) {
-  return watch && hmrManager?.isEnabled() === true;
-}
-async function injectHmrRuntimeIntoHtmlResponse(response) {
-  const html = await response.text();
-  const headers = new Headers(response.headers);
-  headers.set("Cache-Control", "no-store, must-revalidate");
-  headers.delete("Content-Length");
-  if (html.includes(HMR_RUNTIME_IMPORT)) {
-    return new Response(html, {
-      status: response.status,
-      statusText: response.statusText,
-      headers
-    });
-  }
-  const updatedHtml = html.replace(/<\/html>/i, `${HMR_RUNTIME_SCRIPT}</html>`);
-  return new Response(updatedHtml, {
-    status: response.status,
-    statusText: response.statusText,
-    headers
-  });
-}
-export {
-  injectHmrRuntimeIntoHtmlResponse,
-  isHtmlResponse,
-  shouldInjectHmrHtmlResponse
-};

package/src/adapters/shared/render-context.d.ts

@@ -1,16 +0,0 @@
-import type { RenderContext } from '../../types/public-types.js';
-import type { AnyIntegrationPlugin } from '../../plugins/integration-plugin.js';
-export interface CreateRenderContextOptions {
-    integrations: AnyIntegrationPlugin[];
-    rendererModules?: unknown;
-    importServerModule?: (filePath: string) => Promise<unknown>;
-}
-/**
- * Creates a render context for route handlers.
- * Provides render(), renderPartial(), json(), and html() methods that can be used
- * within route handlers to generate responses.
- *
- * @param options - Configuration options including available integrations
- * @returns A RenderContext object with methods for rendering views and creating responses
- */
-export declare function createRenderContext(options: CreateRenderContextOptions): RenderContext;

package/src/adapters/shared/render-context.js

@@ -1,93 +0,0 @@
-import { fileURLToPath } from "node:url";
-import { invariant } from "../../utils/invariant.js";
-function resolveServerModulePath(filePath) {
-  return filePath instanceof URL ? fileURLToPath(filePath) : filePath;
-}
-function mergePropsWithLocals(props, locals) {
-  if (!locals || typeof props !== "object" || props === null) {
-    return props;
-  }
-  return { ...props, locals };
-}
-function createRenderContext(options) {
-  const { integrations } = options;
-  const getRendererForView = (view) => {
-    const integrationName = view.config?.integration ?? view.config?.__eco?.integration;
-    invariant(
-      !!integrationName,
-      "Cannot determine integration for view. Set view.config.integration explicitly or ensure the view is defined with eco.page() in a file with a recognized extension."
-    );
-    const integration = integrations.find((i) => i.name === integrationName);
-    invariant(!!integration, `No integration found for: ${integrationName}`);
-    return integration.initializeRenderer({
-      rendererModules: options.rendererModules
-    });
-  };
-  const renderContext = {
-    importServerModule: async (filePath) => {
-      invariant(!!options.importServerModule, "Server module importing is not available in this render context.");
-      return await options.importServerModule(resolveServerModulePath(filePath));
-    },
-    async renderServerModule(filePath, props, renderOptions) {
-      const module = await renderContext.importServerModule(filePath);
-      const view = module.default;
-      const locals = this?.locals;
-      const mergedProps = mergePropsWithLocals(props ?? {}, locals);
-      const renderer = getRendererForView(view);
-      const ctx = {
-        partial: false,
-        status: renderOptions?.status,
-        headers: renderOptions?.headers
-      };
-      return await renderer.renderToResponse(view, mergedProps, ctx);
-    },
-    async render(view, props, renderOptions) {
-      const locals = this?.locals;
-      const mergedProps = mergePropsWithLocals(props ?? {}, locals);
-      const renderer = getRendererForView(view);
-      const ctx = {
-        partial: false,
-        status: renderOptions?.status,
-        headers: renderOptions?.headers
-      };
-      return renderer.renderToResponse(view, mergedProps, ctx);
-    },
-    async renderPartial(view, props, renderOptions) {
-      const locals = this?.locals;
-      const mergedProps = mergePropsWithLocals(props, locals);
-      const renderer = getRendererForView(view);
-      const ctx = {
-        partial: true,
-        status: renderOptions?.status,
-        headers: renderOptions?.headers
-      };
-      return renderer.renderToResponse(view, mergedProps, ctx);
-    },
-    json(data, responseOptions) {
-      const headers = new Headers({ "Content-Type": "application/json; charset=utf-8" });
-      if (responseOptions?.headers) {
-        const incomingHeaders = new Headers(responseOptions.headers);
-        incomingHeaders.forEach((value, key) => headers.set(key, value));
-      }
-      return new Response(JSON.stringify(data), {
-        status: responseOptions?.status ?? 200,
-        headers
-      });
-    },
-    html(content, responseOptions) {
-      const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" });
-      if (responseOptions?.headers) {
-        const incomingHeaders = new Headers(responseOptions.headers);
-        incomingHeaders.forEach((value, key) => headers.set(key, value));
-      }
-      return new Response(content, {
-        status: responseOptions?.status ?? 200,
-        headers
-      });
-    }
-  };
-  return renderContext;
-}
-export {
-  createRenderContext
-};

package/src/adapters/shared/runtime-app-bootstrap.d.ts

@@ -1,26 +0,0 @@
-import type { ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-export type RuntimeBinding = {
-    preferredPort: number;
-    preferredHostname: string;
-    runtimeOrigin: string;
-    serveOptions: Record<string, unknown>;
-    watch: boolean;
-};
-export type StaticRuntimeMode = {
-    requiresFetchRuntime: boolean;
-    canBuildWithoutRuntimeServer: boolean;
-};
-export declare function resolveServeRuntimeOrigin(serveOptions: {
-    hostname?: string;
-    port?: number | string;
-}): string;
-export declare function resolveRuntimeBinding(options: {
-    cliArgs: ReturnParseCliArgs;
-    serverOptions?: Record<string, unknown>;
-    env?: NodeJS.ProcessEnv;
-}): RuntimeBinding;
-export declare function resolveStaticRuntimeMode(options: {
-    appConfig: EcoPagesAppConfig;
-    cliArgs: ReturnParseCliArgs;
-}): StaticRuntimeMode;

package/src/adapters/shared/runtime-app-bootstrap.js

@@ -1,46 +0,0 @@
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
-function normalizeOriginHostname(hostname) {
-  if (hostname.includes(":") && !hostname.startsWith("[") && !hostname.endsWith("]")) {
-    return `[${hostname}]`;
-  }
-  return hostname;
-}
-function resolveServeRuntimeOrigin(serveOptions) {
-  const hostname = normalizeOriginHostname(String(serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME));
-  const port = Number(serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
-  return `http://${hostname}:${port}`;
-}
-function resolveRuntimeBinding(options) {
-  const env = options.env ?? process.env;
-  const preferredPort = options.cliArgs.port ?? (env.ECOPAGES_PORT ? Number(env.ECOPAGES_PORT) : void 0) ?? DEFAULT_ECOPAGES_PORT;
-  const preferredHostname = options.cliArgs.hostname ?? env.ECOPAGES_HOSTNAME ?? DEFAULT_ECOPAGES_HOSTNAME;
-  return {
-    preferredPort,
-    preferredHostname,
-    runtimeOrigin: resolveServeRuntimeOrigin({
-      hostname: preferredHostname,
-      port: preferredPort
-    }),
-    serveOptions: {
-      port: preferredPort,
-      hostname: preferredHostname,
-      ...options.serverOptions ?? {}
-    },
-    watch: options.cliArgs.dev
-  };
-}
-function resolveStaticRuntimeMode(options) {
-  const requiresFetchRuntime = options.appConfig.integrations.some(
-    (integration) => integration.staticBuildStep === "fetch"
-  );
-  const canBuildWithoutRuntimeServer = (options.cliArgs.build || options.cliArgs.preview) && !requiresFetchRuntime;
-  return {
-    requiresFetchRuntime,
-    canBuildWithoutRuntimeServer
-  };
-}
-export {
-  resolveRuntimeBinding,
-  resolveServeRuntimeOrigin,
-  resolveStaticRuntimeMode
-};

package/src/adapters/shared/runtime-host.d.ts

@@ -1,12 +0,0 @@
-export interface RuntimeHost<TServer, TServeOptions> {
-    start(options: RuntimeHostStartOptions<TServeOptions>): Promise<TServer>;
-    stop(server: TServer, options?: {
-        force?: boolean;
-    }): Promise<void>;
-    getOrigin(server: TServer, fallbackServeOptions: TServeOptions): string;
-}
-export interface RuntimeHostStartOptions<TServeOptions> {
-    serveOptions: TServeOptions;
-    handleRequest(request: Request): Promise<Response>;
-    onError(error: Error): Promise<void> | void;
-}