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

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

@@ -1,25 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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,41 +0,0 @@
-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: 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;
-    private readonly staticRoutes;
-    constructor({ appConfig, routeRendererFactory, staticRoutes }: ExplicitStaticRouteMatcherOptions);
-    /**
-     * Match a request URL against explicit static routes.
-     * Returns the matched route and extracted params, or null if no match.
-     */
-    match(url: string): ExplicitRouteMatch | null;
-    /**
-     * Match a route pattern against a pathname.
-     * Supports :param and [param] syntax.
-     * Returns extracted params or null if no match.
-     */
-    private matchRoute;
-    /**
-     * Handle a matched explicit static route.
-     * Resolves the loader and renders the view using the appropriate integration renderer.
-     */
-    handleMatch(match: ExplicitRouteMatch): Promise<Response>;
-}

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

@@ -1,101 +0,0 @@
-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}`
-};
-class ExplicitStaticRouteMatcher {
-  appConfig;
-  routeRendererFactory;
-  staticRoutes;
-  constructor({ appConfig, routeRendererFactory, staticRoutes }) {
-    this.appConfig = appConfig;
-    this.routeRendererFactory = routeRendererFactory;
-    this.staticRoutes = staticRoutes;
-  }
-  /**
-   * Match a request URL against explicit static routes.
-   * Returns the matched route and extracted params, or null if no match.
-   */
-  match(url) {
-    const pathname = new URL(url).pathname;
-    for (const route of this.staticRoutes) {
-      const params = this.matchRoute(route.path, pathname);
-      if (params !== null) {
-        return { route, params };
-      }
-    }
-    return null;
-  }
-  /**
-   * Match a route pattern against a pathname.
-   * Supports :param and [param] syntax.
-   * Returns extracted params or null if no match.
-   */
-  matchRoute(pattern, pathname) {
-    const patternSegments = pattern.split("/").filter(Boolean);
-    const pathSegments = pathname.split("/").filter(Boolean);
-    if (patternSegments.length !== pathSegments.length) {
-      const lastPattern = patternSegments[patternSegments.length - 1];
-      const isCatchAll = lastPattern?.startsWith("[...") || lastPattern?.startsWith(":...");
-      if (!isCatchAll) {
-        return null;
-      }
-    }
-    const params = {};
-    for (let i = 0; i < patternSegments.length; i++) {
-      const patternPart = patternSegments[i];
-      const pathPart = pathSegments[i];
-      if (patternPart.startsWith(":...") || patternPart.startsWith("[...")) {
-        const paramName = patternPart.replace(/^(:\.\.\.|\[\.\.\.)/, "").replace(/\]$/, "");
-        params[paramName] = pathSegments.slice(i).join("/");
-        return params;
-      }
-      if (patternPart.startsWith(":")) {
-        const paramName = patternPart.slice(1);
-        params[paramName] = pathPart;
-      } else if (patternPart.startsWith("[") && patternPart.endsWith("]")) {
-        const paramName = patternPart.slice(1, -1);
-        params[paramName] = pathPart;
-      } else if (patternPart !== pathPart) {
-        return null;
-      }
-    }
-    return params;
-  }
-  /**
-   * Handle a matched explicit static route.
-   * Resolves the loader and renders the view using the appropriate integration renderer.
-   */
-  async handleMatch(match) {
-    const { route, params } = match;
-    try {
-      const mod = await route.loader();
-      const view = mod.default;
-      const {
-        renderer,
-        props,
-        view: renderableView
-      } = await prepareExplicitStaticRender({
-        routePath: route.path,
-        view,
-        params,
-        appConfig: this.appConfig,
-        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}:`,
-        error instanceof Error ? error : String(error)
-      );
-      throw error;
-    }
-  }
-}
-export {
-  EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS,
-  ExplicitStaticRouteMatcher
-};

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

@@ -1,62 +0,0 @@
-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 middlewareRequiresDynamic: (filePath: string) => string;
-};
-/**
- * Executes middleware for file-based page routes.
- *
- * This pipeline owns the middleware-specific rules that are distinct from route
- * matching and rendering, including request-local storage, the middleware
- * execution context, and the invariant that page middleware only runs for
- * request-time dynamic rendering.
- */
-export declare class FileRouteMiddlewarePipeline {
-    private cacheService;
-    constructor(cacheService: PageCacheService | null);
-    /**
-     * Enforces the current middleware contract for file-routed pages.
-     *
-     * Middleware depends on request-scoped locals and therefore must not run when
-     * the page is treated as statically cacheable.
-     *
-     * @param input Middleware list, effective cache strategy, and page path.
-     * @throws LocalsAccessError When middleware is configured for a non-dynamic page.
-     */
-    assertValidConfiguration(input: {
-        middleware: FileRouteMiddleware[];
-        pageCacheStrategy: 'static' | 'dynamic' | {
-            revalidate: number;
-            tags?: string[];
-        };
-        filePath: string;
-    }): void;
-    /**
-     * Creates the request-scoped middleware context used by page middleware.
-     *
-     * 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.
-     */
-    createContext(input: {
-        request: Request;
-        params: Record<string, string>;
-        locals: RequestLocals;
-    }): FileRouteMiddlewareContext;
-    /**
-     * Runs the middleware chain and eventually delegates to the render callback.
-     *
-     * Middleware may short-circuit by returning a response directly. If the chain
-     * completes, the supplied `renderResponse` callback is executed exactly once.
-     *
-     * @param input Middleware context, chain, and terminal render callback.
-     * @returns Response from middleware or final render stage.
-     */
-    run(input: {
-        middleware: FileRouteMiddleware[];
-        context: FileRouteMiddlewareContext;
-        renderResponse: () => Promise<Response>;
-    }): Promise<Response>;
-}

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

@@ -1,90 +0,0 @@
-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 = {
-  middlewareRequiresDynamic: (filePath) => `[ecopages] Page middleware requires cache: 'dynamic'. Page: ${filePath}`
-};
-class FileRouteMiddlewarePipeline {
-  cacheService;
-  constructor(cacheService) {
-    this.cacheService = cacheService;
-  }
-  /**
-   * Enforces the current middleware contract for file-routed pages.
-   *
-   * Middleware depends on request-scoped locals and therefore must not run when
-   * the page is treated as statically cacheable.
-   *
-   * @param input Middleware list, effective cache strategy, and page path.
-   * @throws LocalsAccessError When middleware is configured for a non-dynamic page.
-   */
-  assertValidConfiguration(input) {
-    if (input.middleware.length > 0 && input.pageCacheStrategy !== "dynamic") {
-      throw new LocalsAccessError(
-        FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.middlewareRequiresDynamic(input.filePath)
-      );
-    }
-  }
-  /**
-   * Creates the request-scoped middleware context used by page middleware.
-   *
-   * 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.
-   */
-  createContext(input) {
-    const context = {
-      request: input.request,
-      params: input.params,
-      response: new ApiResponseBuilder(),
-      server: null,
-      services: {
-        cache: this.cacheService
-      },
-      locals: input.locals,
-      require: createRequire(() => context.locals),
-      json: (data, options) => {
-        const builder = new ApiResponseBuilder();
-        if (options?.status) builder.status(options.status);
-        if (options?.headers) builder.headers(options.headers);
-        return builder.json(data);
-      },
-      html: (content, options) => {
-        const builder = new ApiResponseBuilder();
-        if (options?.status) builder.status(options.status);
-        if (options?.headers) builder.headers(options.headers);
-        return builder.html(content);
-      }
-    };
-    return context;
-  }
-  /**
-   * Runs the middleware chain and eventually delegates to the render callback.
-   *
-   * Middleware may short-circuit by returning a response directly. If the chain
-   * completes, the supplied `renderResponse` callback is executed exactly once.
-   *
-   * @param input Middleware context, chain, and terminal render callback.
-   * @returns Response from middleware or final render stage.
-   */
-  async run(input) {
-    if (input.middleware.length === 0) {
-      return input.renderResponse();
-    }
-    let index = 0;
-    const executeNext = async () => {
-      if (index < input.middleware.length) {
-        const current = input.middleware[index++];
-        return current(input.context, executeNext);
-      }
-      return input.renderResponse();
-    };
-    return executeNext();
-  }
-}
-export {
-  FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS,
-  FileRouteMiddlewarePipeline
-};

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

@@ -1,23 +0,0 @@
-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 options;
-    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>;
-    /**
-     * 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,81 +0,0 @@
-import { STATUS_MESSAGE } from "../../config/constants.js";
-import { appLogger } from "../../global/app-logger.js";
-import { fileSystem } from "@ecopages/file-system";
-class FileSystemServerResponseFactory {
-  options;
-  constructor({ options }) {
-    this.options = options;
-  }
-  isHtml(contentType) {
-    return contentType === "text/html";
-  }
-  shouldEnableGzip(contentType) {
-    if (this.options.watchMode) return false;
-    const gzipEnabledExtensions = ["text/javascript", "text/css"];
-    return gzipEnabledExtensions.includes(contentType);
-  }
-  async createResponseWithBody(body, init = {
-    headers: {
-      "Content-Type": "text/html"
-    }
-  }) {
-    return new Response(body, init);
-  }
-  async createDefaultNotFoundResponse() {
-    return new Response(STATUS_MESSAGE[404], {
-      status: 404
-    });
-  }
-  /**
-   * Wraps already-rendered HTML in a 404 response envelope.
-   */
-  async createHtmlNotFoundResponse(body) {
-    return await this.createResponseWithBody(body, {
-      status: 404,
-      statusText: STATUS_MESSAGE[404],
-      headers: {
-        "Content-Type": "text/html"
-      }
-    });
-  }
-  /**
-   * Reads a static file response, returning `null` when the file is missing.
-   */
-  async createFileResponse(filePath, contentType) {
-    try {
-      let file;
-      const contentEncodingHeader = {};
-      if (this.shouldEnableGzip(contentType)) {
-        const gzipPath = `${filePath}.gz`;
-        if (fileSystem.exists(gzipPath)) {
-          file = fileSystem.readFileAsBuffer(gzipPath);
-          contentEncodingHeader["Content-Encoding"] = "gzip";
-          contentEncodingHeader["Vary"] = "Accept-Encoding";
-        } else {
-          appLogger.debug("Gzip file not found, serving uncompressed", gzipPath);
-          file = fileSystem.readFileAsBuffer(filePath);
-        }
-      } else {
-        file = fileSystem.readFileAsBuffer(filePath);
-      }
-      return await this.createResponseWithBody(file, {
-        headers: {
-          "Content-Type": contentType,
-          ...contentEncodingHeader
-        }
-      });
-    } catch (error) {
-      const err = error;
-      const code = err.code || err.cause?.code;
-      if (code === "ENOENT") {
-        appLogger.debug("File not found", filePath);
-      } else {
-        appLogger.error("Error reading file", filePath, err);
-      }
-      return null;
-    }
-  }
-}
-export {
-  FileSystemServerResponseFactory
-};

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

@@ -1,75 +0,0 @@
-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 interface FileSystemResponseMatcherOptions {
-    appConfig: EcoPagesAppConfig;
-    assetPrefix: string;
-    router: RouteRegistry;
-    routeRendererFactory: PageRendererResolver;
-    fileSystemResponseFactory: FileSystemServerResponseFactory;
-    /** Optional cache service. When null, caching is disabled. */
-    cacheService?: PageCacheService | null;
-    /** Default cache strategy when caching is enabled. @default 'static' */
-    defaultCacheStrategy?: CacheStrategy;
-}
-/**
- * Matches file-system routes to rendered HTML responses.
- *
- * 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 pageRequestCacheCoordinator;
-    private fileRouteMiddlewarePipeline;
-    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.
-     */
-    handleNoMatch(requestUrl: string): Promise<Response>;
-    /**
-     * 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.
-     */
-    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 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.
-     */
-    private importPageModule;
-    /**
-     * Get the underlying cache service for external invalidation.
-     */
-    getCacheService(): PageCacheService | null;
-}