@ecopages/core 0.2.0-alpha.5 → 0.2.0-alpha.51

package/src/adapters/node/static-preview-host.js

@@ -0,0 +1,68 @@
+import { NodeStaticContentServer } from "./static-content-server.js";
+class NodeStaticPreviewHost {
+  /**
+   * Creates the preview host with an injectable preview-server constructor.
+   */
+  constructor(previewServerFactory = NodeStaticContentServer) {
+    this.previewServerFactory = previewServerFactory;
+  }
+  previewServerFactory;
+  previewServer = null;
+  stopPromise = null;
+  /**
+   * Starts the Node preview host after fully draining any previous preview server
+   * shutdown that may still be in flight.
+   *
+   * @remarks
+   * The host only publishes a new preview server after `start()` succeeds. That
+   * keeps failed startup attempts from replacing the last known-good server with a
+   * half-initialized instance.
+   */
+  async start(options) {
+    await this.stop();
+    const previewServer = new this.previewServerFactory({
+      appConfig: options.appConfig,
+      options: {
+        hostname: options.hostname,
+        port: options.port
+      }
+    });
+    const server = await previewServer.start();
+    this.previewServer = previewServer;
+    const address = server.address();
+    if (address && typeof address === "object") {
+      return address.port;
+    }
+    return options.port;
+  }
+  /**
+   * Stops the active preview server and coalesces overlapping stop requests onto
+   * the same shutdown promise.
+   *
+   * @remarks
+   * The host keeps the server reference until shutdown succeeds. If shutdown
+   * fails, callers can still retry `stop()` or inspect the same live instance
+   * instead of losing the handle during a rejected async stop.
+   */
+  async stop(force = true) {
+    if (this.stopPromise) {
+      await this.stopPromise;
+      return;
+    }
+    if (!this.previewServer) {
+      return;
+    }
+    const activePreviewServer = this.previewServer;
+    this.stopPromise = activePreviewServer.stop(force).then(() => {
+      if (this.previewServer === activePreviewServer) {
+        this.previewServer = null;
+      }
+    }).finally(() => {
+      this.stopPromise = null;
+    });
+    await this.stopPromise;
+  }
+}
+export {
+  NodeStaticPreviewHost
+};

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

@@ -1,4 +1,4 @@
-import type { ApiHandler, ApiHandlerContext, Middleware, RouteGroupBuilder, RouteOptions } from '../../public-types.js';
+import type { ApiHandler, ApiHandlerContext, Middleware, RouteGroupBuilder, RouteOptions } from '../../types/public-types.js';
 import { AbstractApplicationAdapter, type ApplicationAdapterOptions, type RouteGroupDefinition, type RouteHandler } from '../abstract/application-adapter.js';
 export declare abstract class SharedApplicationAdapter<TOptions extends ApplicationAdapterOptions = ApplicationAdapterOptions, TServer = any, TRequest extends Request = Request> extends AbstractApplicationAdapter<TOptions, TServer, TRequest> {
     protected register<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, method: ApiHandler['method'], handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;

package/src/{define-api-handler.d.ts → adapters/shared/define-api-handler.d.ts}

@@ -1,4 +1,4 @@
-import type { ApiHandler, ApiHandlerContext, Middleware, RouteSchema, TypedGroupHandlerContext } from './public-types.js';
+import type { ApiHandler, ApiHandlerContext, Middleware, RouteSchema, TypedGroupHandlerContext } from '../../types/public-types.js';
 type UniversalContext = ApiHandlerContext<Request, unknown>;
 type SchemaHandlerContext<TSchema extends RouteSchema | undefined, TContext extends UniversalContext> = TSchema extends RouteSchema ? TypedGroupHandlerContext<TSchema, TContext> : TContext;
 export declare function defineApiHandler<TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, 'handler' | 'middleware' | 'schema'> & {

package/src/adapters/shared/explicit-static-render-preparation.d.ts

@@ -0,0 +1,25 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { EcoFunctionComponent, EcoPageComponent } from '../../types/public-types.js';
+import type { ExplicitViewRenderer, ExplicitViewRendererResolver } from '../../route-renderer/route-renderer.js';
+type ExplicitStaticRenderPreparationResult = {
+    renderer: ExplicitViewRenderer;
+    props: Record<string, unknown>;
+    view: EcoFunctionComponent<Record<string, unknown>, any>;
+};
+/**
+ * Resolves the renderer and static props needed to render one explicit static
+ * view at runtime or during static generation.
+ */
+export declare function prepareExplicitStaticRender(input: {
+    routePath: string;
+    view: EcoPageComponent<any>;
+    params: Record<string, string | string[]>;
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    routeRendererFactory: ExplicitViewRendererResolver;
+    errors: {
+        missingIntegration(routePath: string): string;
+        noRendererForIntegration(integrationName: string): string;
+    };
+}): Promise<ExplicitStaticRenderPreparationResult>;
+export {};

package/src/adapters/shared/explicit-static-render-preparation.js

@@ -0,0 +1,26 @@
+function getViewIntegrationName(view) {
+  return view.config?.integration ?? view.config?.__eco?.integration;
+}
+async function prepareExplicitStaticRender(input) {
+  const integrationName = getViewIntegrationName(input.view);
+  if (!integrationName) {
+    throw new Error(input.errors.missingIntegration(input.routePath));
+  }
+  const renderer = input.routeRendererFactory.getExplicitViewRenderer(integrationName);
+  if (!renderer) {
+    throw new Error(input.errors.noRendererForIntegration(integrationName));
+  }
+  const props = input.view.staticProps ? (await input.view.staticProps({
+    pathname: { params: input.params },
+    appConfig: input.appConfig,
+    runtimeOrigin: input.runtimeOrigin
+  })).props : {};
+  return {
+    renderer,
+    props,
+    view: input.view
+  };
+}
+export {
+  prepareExplicitStaticRender
+};

package/src/adapters/shared/explicit-static-route-matcher.d.ts

@@ -1,19 +1,22 @@
-import type { EcoPagesAppConfig } from '../../internal-types.js';
-import type { StaticRoute } from '../../public-types.js';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { StaticRoute } from '../../types/public-types.js';
+import type { ExplicitViewRendererResolver } from '../../route-renderer/route-renderer.js';
 export declare const EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS: {
     readonly missingIntegration: (routePath: string) => string;
     readonly noRendererForIntegration: (integrationName: string) => string;
 };
 export interface ExplicitStaticRouteMatcherOptions {
     appConfig: EcoPagesAppConfig;
-    routeRendererFactory: RouteRendererFactory;
+    routeRendererFactory: ExplicitViewRendererResolver;
     staticRoutes: StaticRoute[];
 }
 export interface ExplicitRouteMatch {
     route: StaticRoute;
     params: Record<string, string>;
 }
+/**
+ * Matches and renders explicit static routes declared through `app.static()`.
+ */
 export declare class ExplicitStaticRouteMatcher {
     private readonly appConfig;
     private readonly routeRendererFactory;

package/src/adapters/shared/explicit-static-route-matcher.js

@@ -1,4 +1,5 @@
 import { appLogger } from "../../global/app-logger.js";
+import { prepareExplicitStaticRender } from "./explicit-static-render-preparation.js";
 const EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS = {
   missingIntegration: (routePath) => `View at ${routePath} is missing __eco.integration. Ensure it's defined with eco.page() and exported as default.`,
   noRendererForIntegration: (integrationName) => `No renderer found for integration: ${integrationName}`
@@ -71,20 +72,20 @@ class ExplicitStaticRouteMatcher {
     try {
       const mod = await route.loader();
       const view = mod.default;
-      const integrationName = view.config?.__eco?.integration;
-      if (!integrationName) {
-        throw new Error(EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS.missingIntegration(route.path));
-      }
-      const renderer = this.routeRendererFactory.getRendererByIntegration(integrationName);
-      if (!renderer) {
-        throw new Error(EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS.noRendererForIntegration(integrationName));
-      }
-      const props = view.staticProps ? (await view.staticProps({
-        pathname: { params },
+      const {
+        renderer,
+        props,
+        view: renderableView
+      } = await prepareExplicitStaticRender({
+        routePath: route.path,
+        view,
+        params,
         appConfig: this.appConfig,
-        runtimeOrigin: this.appConfig.baseUrl
-      })).props : {};
-      return renderer.renderToResponse(view, props, {});
+        runtimeOrigin: this.appConfig.baseUrl,
+        routeRendererFactory: this.routeRendererFactory,
+        errors: EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS
+      });
+      return renderer.renderToResponse(renderableView, props, {});
     } catch (error) {
       appLogger.error(
         `Error rendering explicit static route ${route.path}:`,

package/src/adapters/shared/file-route-middleware-pipeline.d.ts

@@ -1,8 +1,6 @@
-import type { Middleware, ApiHandlerContext, RequestLocals } from '../../public-types.js';
+import type { FileRouteMiddleware, FileRouteMiddlewareContext, RequestLocals } from '../../types/public-types.js';
 import type { PageCacheService } from '../../services/cache/page-cache-service.js';
 export declare const FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS: {
-    readonly CTX_RENDER_UNAVAILABLE: "[ecopages] ctx.render is not available in file-route middleware";
-    readonly CTX_RENDER_PARTIAL_UNAVAILABLE: "[ecopages] ctx.renderPartial is not available in file-route middleware";
     readonly middlewareRequiresDynamic: (filePath: string) => string;
 };
 /**
@@ -26,7 +24,7 @@ export declare class FileRouteMiddlewarePipeline {
      * @throws LocalsAccessError When middleware is configured for a non-dynamic page.
      */
     assertValidConfiguration(input: {
-        middleware: Middleware[];
+        middleware: FileRouteMiddleware[];
         pageCacheStrategy: 'static' | 'dynamic' | {
             revalidate: number;
             tags?: string[];
@@ -36,9 +34,8 @@ export declare class FileRouteMiddlewarePipeline {
     /**
      * Creates the request-scoped middleware context used by page middleware.
      *
-     * The context intentionally disables `render()` and `renderPartial()` inside
-     * file-route middleware because rendering is owned by the page route pipeline,
-     * not by middleware stages.
+     * The context intentionally omits `render()` and `renderPartial()` because
+     * rendering is owned by the page route pipeline, not by middleware stages.
      *
      * @param input Request details and the mutable locals store.
      * @returns Middleware execution context.
@@ -47,7 +44,7 @@ export declare class FileRouteMiddlewarePipeline {
         request: Request;
         params: Record<string, string>;
         locals: RequestLocals;
-    }): ApiHandlerContext;
+    }): FileRouteMiddlewareContext;
     /**
      * Runs the middleware chain and eventually delegates to the render callback.
      *
@@ -58,8 +55,8 @@ export declare class FileRouteMiddlewarePipeline {
      * @returns Response from middleware or final render stage.
      */
     run(input: {
-        middleware: Middleware[];
-        context: ApiHandlerContext;
+        middleware: FileRouteMiddleware[];
+        context: FileRouteMiddlewareContext;
         renderResponse: () => Promise<Response>;
     }): Promise<Response>;
 }

package/src/adapters/shared/file-route-middleware-pipeline.js

@@ -2,11 +2,10 @@ import { createRequire } from "../../utils/locals-utils.js";
 import { ApiResponseBuilder } from "./api-response.js";
 import { LocalsAccessError } from "../../errors/locals-access-error.js";
 const FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS = {
-  CTX_RENDER_UNAVAILABLE: "[ecopages] ctx.render is not available in file-route middleware",
-  CTX_RENDER_PARTIAL_UNAVAILABLE: "[ecopages] ctx.renderPartial is not available in file-route middleware",
   middlewareRequiresDynamic: (filePath) => `[ecopages] Page middleware requires cache: 'dynamic'. Page: ${filePath}`
 };
 class FileRouteMiddlewarePipeline {
+  cacheService;
   constructor(cacheService) {
     this.cacheService = cacheService;
   }
@@ -29,9 +28,8 @@ class FileRouteMiddlewarePipeline {
   /**
    * Creates the request-scoped middleware context used by page middleware.
    *
-   * The context intentionally disables `render()` and `renderPartial()` inside
-   * file-route middleware because rendering is owned by the page route pipeline,
-   * not by middleware stages.
+   * The context intentionally omits `render()` and `renderPartial()` because
+   * rendering is owned by the page route pipeline, not by middleware stages.
    *
    * @param input Request details and the mutable locals store.
    * @returns Middleware execution context.
@@ -47,12 +45,6 @@ class FileRouteMiddlewarePipeline {
       },
       locals: input.locals,
       require: createRequire(() => context.locals),
-      render: async () => {
-        throw new Error(FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.CTX_RENDER_UNAVAILABLE);
-      },
-      renderPartial: async () => {
-        throw new Error(FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.CTX_RENDER_PARTIAL_UNAVAILABLE);
-      },
       json: (data, options) => {
         const builder = new ApiResponseBuilder();
         if (options?.status) builder.status(options.status);

package/src/adapters/shared/fs-server-response-factory.d.ts

@@ -1,19 +1,23 @@
-import type { EcoPagesAppConfig, FileSystemServerOptions } from '../../internal-types.js';
-import type { RouteRendererBody } from '../../public-types.js';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
+import type { FileSystemServerOptions } from '../../types/internal-types.js';
+import type { RouteRendererBody } from '../../types/public-types.js';
+/**
+ * Builds HTTP responses for static files and shared file-system fallbacks.
+ */
 export declare class FileSystemServerResponseFactory {
-    private appConfig;
-    private routeRendererFactory;
     private options;
-    constructor({ appConfig, routeRendererFactory, options, }: {
-        appConfig: EcoPagesAppConfig;
-        routeRendererFactory: RouteRendererFactory;
+    constructor({ options }: {
         options: FileSystemServerOptions;
     });
     isHtml(contentType: string): contentType is "text/html";
     shouldEnableGzip(contentType: string): boolean;
     createResponseWithBody(body: RouteRendererBody, init?: ResponseInit): Promise<Response>;
     createDefaultNotFoundResponse(): Promise<Response>;
-    createCustomNotFoundResponse(): Promise<Response>;
-    createFileResponse(filePath: string, contentType: string): Promise<Response>;
+    /**
+     * Wraps already-rendered HTML in a 404 response envelope.
+     */
+    createHtmlNotFoundResponse(body: RouteRendererBody): Promise<Response>;
+    /**
+     * Reads a static file response, returning `null` when the file is missing.
+     */
+    createFileResponse(filePath: string, contentType: string): Promise<Response | null>;
 }

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

@@ -1,17 +1,9 @@
-import { STATUS_MESSAGE } from "../../constants.js";
+import { STATUS_MESSAGE } from "../../config/constants.js";
 import { appLogger } from "../../global/app-logger.js";
 import { fileSystem } from "@ecopages/file-system";
 class FileSystemServerResponseFactory {
-  appConfig;
-  routeRendererFactory;
   options;
-  constructor({
-    appConfig,
-    routeRendererFactory,
-    options
-  }) {
-    this.appConfig = appConfig;
-    this.routeRendererFactory = routeRendererFactory;
+  constructor({ options }) {
     this.options = options;
   }
   isHtml(contentType) {
@@ -34,22 +26,11 @@ class FileSystemServerResponseFactory {
       status: 404
     });
   }
-  async createCustomNotFoundResponse() {
-    const error404TemplatePath = this.appConfig.absolutePaths.error404TemplatePath;
-    try {
-      fileSystem.verifyFileExists(error404TemplatePath);
-    } catch {
-      appLogger.debug(
-        "Custom 404 template not found, falling back to default 404 response",
-        error404TemplatePath
-      );
-      return this.createDefaultNotFoundResponse();
-    }
-    const routeRenderer = this.routeRendererFactory.createRenderer(error404TemplatePath);
-    const result = await routeRenderer.createRoute({
-      file: error404TemplatePath
-    });
-    return await this.createResponseWithBody(result.body, {
+  /**
+   * Wraps already-rendered HTML in a 404 response envelope.
+   */
+  async createHtmlNotFoundResponse(body) {
+    return await this.createResponseWithBody(body, {
       status: 404,
       statusText: STATUS_MESSAGE[404],
       headers: {
@@ -57,6 +38,9 @@ class FileSystemServerResponseFactory {
       }
     });
   }
+  /**
+   * Reads a static file response, returning `null` when the file is missing.
+   */
   async createFileResponse(filePath, contentType) {
     try {
       let file;
@@ -88,7 +72,7 @@ class FileSystemServerResponseFactory {
       } else {
         appLogger.error("Error reading file", filePath, err);
       }
-      return this.createCustomNotFoundResponse();
+      return null;
     }
   }
 }

package/src/adapters/shared/fs-server-response-matcher.d.ts

@@ -1,16 +1,14 @@
-import type { MatchResult } from '../../internal-types.js';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
-import type { FSRouter } from '../../router/fs-router.js';
+import type { EcoPagesAppConfig, MatchResult } from '../../types/internal-types.js';
+import type { PageRendererResolver } from '../../route-renderer/route-renderer.js';
+import type { RouteRegistry } from '../../router/server/route-registry.js';
 import type { PageCacheService } from '../../services/cache/page-cache-service.js';
 import type { CacheStrategy } from '../../services/cache/cache.types.js';
 import type { FileSystemServerResponseFactory } from './fs-server-response-factory.js';
-export declare const FILE_SYSTEM_RESPONSE_MATCHER_ERRORS: {
-    readonly transpilePageModuleFailed: (details: string) => string;
-    readonly noTranspiledOutputForPageModule: (filePath: string) => string;
-};
 export interface FileSystemResponseMatcherOptions {
-    router: FSRouter;
-    routeRendererFactory: RouteRendererFactory;
+    appConfig: EcoPagesAppConfig;
+    assetPrefix: string;
+    router: RouteRegistry;
+    routeRendererFactory: PageRendererResolver;
     fileSystemResponseFactory: FileSystemServerResponseFactory;
     /** Optional cache service. When null, caching is disabled. */
     cacheService?: PageCacheService | null;
@@ -20,23 +18,22 @@ export interface FileSystemResponseMatcherOptions {
 /**
  * Matches file-system routes to rendered HTML responses.
  *
- * This class sits at the request-time boundary between router matches and the
- * render pipeline. It coordinates page module inspection, request-local policy,
+ * This render pipeline coordinates page module inspection, request-local policy,
  * renderer invocation, middleware execution, cache integration, and fallback
  * error translation.
  */
 export declare class FileSystemResponseMatcher {
+    private appConfig;
+    private assetPrefix;
     private router;
     private routeRendererFactory;
     private fileSystemResponseFactory;
-    private pageModuleImportService;
     private pageRequestCacheCoordinator;
     private fileRouteMiddlewarePipeline;
-    constructor({ router, routeRendererFactory, fileSystemResponseFactory, cacheService, defaultCacheStrategy, }: FileSystemResponseMatcherOptions);
+    constructor({ appConfig, assetPrefix, router, routeRendererFactory, fileSystemResponseFactory, cacheService, defaultCacheStrategy, }: FileSystemResponseMatcherOptions);
     /**
      * 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.
      */
@@ -53,12 +50,19 @@ export declare class FileSystemResponseMatcher {
      * @returns Final response for the matched route.
      */
     handleMatch(match: MatchResult, request?: Request): Promise<Response>;
+    /**
+     * Renders the app-owned custom 404 page, falling back to the default text 404
+     * when the page template cannot be resolved.
+     */
+    private renderCustomNotFoundResponse;
+    private createExecutionPlan;
     /**
      * 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 uses the shared module
-     * import service directly rather than going through route rendering.
+     * `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.