@ecopages/core 0.2.0-alpha.1

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

@@ -0,0 +1,90 @@
+import {
+  AbstractApplicationAdapter
+} from "../abstract/application-adapter.js";
+class SharedApplicationAdapter extends AbstractApplicationAdapter {
+  register(path, method, handler, options) {
+    return this.addRouteHandler(path, method, handler, options?.middleware, options?.schema);
+  }
+  get(path, handler, options) {
+    return this.register(path, "GET", handler, options);
+  }
+  post(path, handler, options) {
+    return this.register(path, "POST", handler, options);
+  }
+  put(path, handler, options) {
+    return this.register(path, "PUT", handler, options);
+  }
+  delete(path, handler, options) {
+    return this.register(path, "DELETE", handler, options);
+  }
+  patch(path, handler, options) {
+    return this.register(path, "PATCH", handler, options);
+  }
+  options(path, handler, options) {
+    return this.register(path, "OPTIONS", handler, options);
+  }
+  head(path, handler, options) {
+    return this.register(path, "HEAD", handler, options);
+  }
+  route(path, method, handler, options) {
+    return this.register(path, method, handler, options);
+  }
+  add(handler) {
+    return this.addRouteHandler(handler.path, handler.method, handler.handler, handler.middleware, handler.schema);
+  }
+  group(prefixOrGroup, callback, options) {
+    if (typeof prefixOrGroup === "object") {
+      return this.registerGroup(prefixOrGroup);
+    }
+    const normalizedPrefix = prefixOrGroup.endsWith("/") ? prefixOrGroup.slice(0, -1) : prefixOrGroup;
+    const groupMiddleware = options?.middleware ?? [];
+    const createHandler = (method) => {
+      return ((path, handler, routeOptions) => {
+        const combinedMiddleware = [
+          ...groupMiddleware,
+          ...routeOptions?.middleware ?? []
+        ];
+        const fullPath = path === "/" ? normalizedPrefix : `${normalizedPrefix}${path}`;
+        this.addRouteHandler(
+          fullPath,
+          method,
+          handler,
+          combinedMiddleware.length > 0 ? combinedMiddleware : void 0,
+          routeOptions?.schema
+        );
+        return builder;
+      });
+    };
+    const builder = {
+      get: createHandler("GET"),
+      post: createHandler("POST"),
+      put: createHandler("PUT"),
+      delete: createHandler("DELETE"),
+      patch: createHandler("PATCH"),
+      options: createHandler("OPTIONS"),
+      head: createHandler("HEAD")
+    };
+    callback?.(builder);
+    return this;
+  }
+  registerGroup(group) {
+    const normalizedPrefix = group.prefix.endsWith("/") ? group.prefix.slice(0, -1) : group.prefix;
+    const groupMiddleware = group.middleware ?? [];
+    for (const route of group.routes) {
+      const normalizedPath = route.path.startsWith("/") ? route.path : `/${route.path}`;
+      const fullPath = route.path === "/" ? normalizedPrefix : `${normalizedPrefix}${normalizedPath}`;
+      const combinedMiddleware = [...groupMiddleware, ...route.middleware ?? []];
+      this.addRouteHandler(
+        fullPath,
+        route.method,
+        route.handler,
+        combinedMiddleware.length > 0 ? combinedMiddleware : void 0,
+        route.schema
+      );
+    }
+    return this;
+  }
+}
+export {
+  SharedApplicationAdapter
+};

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

@@ -0,0 +1,199 @@
+import type {
+	ApiHandler,
+	ApiHandlerContext,
+	Middleware,
+	RouteGroupBuilder,
+	RouteOptions,
+	RouteSchema,
+} from '../../public-types.ts';
+import {
+	AbstractApplicationAdapter,
+	type ApplicationAdapterOptions,
+	type RouteGroupDefinition,
+	type RouteHandler,
+} from '../abstract/application-adapter.ts';
+
+export 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 {
+		return this.addRouteHandler(path, method, handler, options?.middleware, options?.schema);
+	}
+
+	get<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(
+		path: P,
+		handler: RouteHandler<TRequest, TServer, TContext>,
+		options?: RouteOptions<TRequest, TServer, TContext>,
+	): this {
+		return this.register(path, 'GET', handler, options);
+	}
+
+	post<
+		P extends string,
+		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
+	>(
+		path: P,
+		handler: RouteHandler<TRequest, TServer, TContext>,
+		options?: RouteOptions<TRequest, TServer, TContext>,
+	): this {
+		return this.register(path, 'POST', handler, options);
+	}
+
+	put<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(
+		path: P,
+		handler: RouteHandler<TRequest, TServer, TContext>,
+		options?: RouteOptions<TRequest, TServer, TContext>,
+	): this {
+		return this.register(path, 'PUT', handler, options);
+	}
+
+	delete<
+		P extends string,
+		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
+	>(
+		path: P,
+		handler: RouteHandler<TRequest, TServer, TContext>,
+		options?: RouteOptions<TRequest, TServer, TContext>,
+	): this {
+		return this.register(path, 'DELETE', handler, options);
+	}
+
+	patch<
+		P extends string,
+		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
+	>(
+		path: P,
+		handler: RouteHandler<TRequest, TServer, TContext>,
+		options?: RouteOptions<TRequest, TServer, TContext>,
+	): this {
+		return this.register(path, 'PATCH', handler, options);
+	}
+
+	options<
+		P extends string,
+		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
+	>(
+		path: P,
+		handler: RouteHandler<TRequest, TServer, TContext>,
+		options?: RouteOptions<TRequest, TServer, TContext>,
+	): this {
+		return this.register(path, 'OPTIONS', handler, options);
+	}
+
+	head<
+		P extends string,
+		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
+	>(
+		path: P,
+		handler: RouteHandler<TRequest, TServer, TContext>,
+		options?: RouteOptions<TRequest, TServer, TContext>,
+	): this {
+		return this.register(path, 'HEAD', handler, options);
+	}
+
+	route<P extends string>(
+		path: P,
+		method: ApiHandler['method'],
+		handler: RouteHandler<TRequest, TServer>,
+		options?: RouteOptions<TRequest, TServer>,
+	): this {
+		return this.register(path, method, handler, options);
+	}
+
+	add(handler: ApiHandler<string, TRequest, TServer>): this {
+		return this.addRouteHandler(handler.path, handler.method, handler.handler, handler.middleware, handler.schema);
+	}
+
+	group<TMiddleware extends readonly Middleware<TRequest, TServer, any>[] = []>(
+		prefixOrGroup: string | RouteGroupDefinition<TRequest, TServer>,
+		callback?: (
+			builder: TMiddleware extends readonly Middleware<TRequest, TServer, infer TContext>[]
+				? RouteGroupBuilder<TRequest, TServer, TContext>
+				: RouteGroupBuilder<TRequest, TServer>,
+		) => void,
+		options?: {
+			middleware?: TMiddleware;
+		},
+	): this {
+		if (typeof prefixOrGroup === 'object') {
+			return this.registerGroup(prefixOrGroup);
+		}
+
+		type TContext = TMiddleware extends readonly Middleware<TRequest, TServer, infer TCtx>[]
+			? TCtx
+			: ApiHandlerContext<TRequest, TServer>;
+
+		const normalizedPrefix = prefixOrGroup.endsWith('/') ? prefixOrGroup.slice(0, -1) : prefixOrGroup;
+		const groupMiddleware = (options?.middleware ?? []) as Middleware<TRequest, TServer, TContext>[];
+
+		const createHandler = (
+			method: ApiHandler['method'],
+		): RouteGroupBuilder<TRequest, TServer, TContext>[Lowercase<typeof method>] => {
+			return ((
+				path: string,
+				handler: (context: TContext) => Promise<Response> | Response,
+				routeOptions?: RouteOptions<TRequest, TServer, TContext> & { schema?: RouteSchema },
+			) => {
+				const combinedMiddleware: Middleware<TRequest, TServer, TContext>[] = [
+					...groupMiddleware,
+					...(routeOptions?.middleware ?? []),
+				];
+				const fullPath = path === '/' ? normalizedPrefix : `${normalizedPrefix}${path}`;
+				this.addRouteHandler(
+					fullPath,
+					method,
+					handler as RouteHandler<TRequest, TServer, ApiHandlerContext<TRequest, TServer>>,
+					combinedMiddleware.length > 0
+						? (combinedMiddleware as Middleware<TRequest, TServer, ApiHandlerContext<TRequest, TServer>>[])
+						: undefined,
+					routeOptions?.schema,
+				);
+				return builder;
+			}) as RouteGroupBuilder<TRequest, TServer, TContext>[Lowercase<typeof method>];
+		};
+
+		const builder: RouteGroupBuilder<TRequest, TServer, TContext> = {
+			get: createHandler('GET'),
+			post: createHandler('POST'),
+			put: createHandler('PUT'),
+			delete: createHandler('DELETE'),
+			patch: createHandler('PATCH'),
+			options: createHandler('OPTIONS'),
+			head: createHandler('HEAD'),
+		};
+
+		callback?.(builder as never);
+		return this;
+	}
+
+	private registerGroup(group: RouteGroupDefinition<TRequest, TServer>): this {
+		const normalizedPrefix = group.prefix.endsWith('/') ? group.prefix.slice(0, -1) : group.prefix;
+		const groupMiddleware = group.middleware ?? [];
+
+		for (const route of group.routes) {
+			const normalizedPath = route.path.startsWith('/') ? route.path : `/${route.path}`;
+			const fullPath = route.path === '/' ? normalizedPrefix : `${normalizedPrefix}${normalizedPath}`;
+			const combinedMiddleware = [...groupMiddleware, ...(route.middleware ?? [])];
+
+			this.addRouteHandler(
+				fullPath,
+				route.method,
+				route.handler,
+				combinedMiddleware.length > 0 ? combinedMiddleware : undefined,
+				route.schema,
+			);
+		}
+
+		return this;
+	}
+}

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

@@ -0,0 +1,38 @@
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { StaticRoute } from '../../public-types.js';
+import type { RouteRendererFactory } 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;
+    staticRoutes: StaticRoute[];
+}
+export interface ExplicitRouteMatch {
+    route: StaticRoute;
+    params: Record<string, string>;
+}
+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

@@ -0,0 +1,100 @@
+import { appLogger } from "../../global/app-logger.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 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 },
+        appConfig: this.appConfig,
+        runtimeOrigin: this.appConfig.baseUrl
+      })).props : {};
+      return renderer.renderToResponse(view, 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/explicit-static-route-matcher.ts

@@ -0,0 +1,134 @@
+import { appLogger } from '../../global/app-logger.ts';
+import type { EcoPagesAppConfig } from '../../internal-types.ts';
+import type { StaticRoute } from '../../public-types.ts';
+import type { RouteRendererFactory } from '../../route-renderer/route-renderer.ts';
+
+export const EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS = {
+	missingIntegration: (routePath: string) =>
+		`View at ${routePath} is missing __eco.integration. Ensure it's defined with eco.page() and exported as default.`,
+	noRendererForIntegration: (integrationName: string) => `No renderer found for integration: ${integrationName}`,
+} as const;
+
+export interface ExplicitStaticRouteMatcherOptions {
+	appConfig: EcoPagesAppConfig;
+	routeRendererFactory: RouteRendererFactory;
+	staticRoutes: StaticRoute[];
+}
+
+export interface ExplicitRouteMatch {
+	route: StaticRoute;
+	params: Record<string, string>;
+}
+
+export class ExplicitStaticRouteMatcher {
+	private readonly appConfig: EcoPagesAppConfig;
+	private readonly routeRendererFactory: RouteRendererFactory;
+	private readonly staticRoutes: StaticRoute[];
+
+	constructor({ appConfig, routeRendererFactory, staticRoutes }: ExplicitStaticRouteMatcherOptions) {
+		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: string): ExplicitRouteMatch | null {
+		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.
+	 */
+	private matchRoute(pattern: string, pathname: string): Record<string, string> | null {
+		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: Record<string, string> = {};
+
+		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: ExplicitRouteMatch): Promise<Response> {
+		const { route, params } = match;
+
+		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 },
+							appConfig: this.appConfig,
+							runtimeOrigin: this.appConfig.baseUrl,
+						})
+					).props
+				: {};
+
+			return renderer.renderToResponse(view, props, {});
+		} catch (error) {
+			appLogger.error(
+				`Error rendering explicit static route ${route.path}:`,
+				error instanceof Error ? error : String(error),
+			);
+			throw error;
+		}
+	}
+}

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

@@ -0,0 +1,65 @@
+import type { Middleware, ApiHandlerContext, RequestLocals } from '../../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;
+};
+/**
+ * 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: Middleware[];
+        pageCacheStrategy: 'static' | 'dynamic' | {
+            revalidate: number;
+            tags?: string[];
+        };
+        filePath: string;
+    }): void;
+    /**
+     * 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.
+     *
+     * @param input Request details and the mutable locals store.
+     * @returns Middleware execution context.
+     */
+    createContext(input: {
+        request: Request;
+        params: Record<string, string>;
+        locals: RequestLocals;
+    }): ApiHandlerContext;
+    /**
+     * 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: Middleware[];
+        context: ApiHandlerContext;
+        renderResponse: () => Promise<Response>;
+    }): Promise<Response>;
+}