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

package/src/adapters/node/static-content-server.js

@@ -0,0 +1,194 @@
+import { createServer } from "node:http";
+import { extname, join, normalize, sep } from "node:path";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT, STATUS_MESSAGE } from "../../config/constants.js";
+import { fileSystem } from "@ecopages/file-system";
+import { ServerUtils } from "../../utils/server-utils.module.js";
+class NodeStaticContentServer {
+  appConfig;
+  options;
+  server = null;
+  /**
+   * Creates the Node static-content server for one built app output directory.
+   */
+  constructor({ appConfig, options }) {
+    this.appConfig = appConfig;
+    this.options = {
+      hostname: options?.hostname ?? DEFAULT_ECOPAGES_HOSTNAME,
+      port: options?.port ?? DEFAULT_ECOPAGES_PORT
+    };
+  }
+  /**
+   * Returns whether the given content type should be served from a pre-gzipped
+   * companion file when available.
+   */
+  shouldServeGzip(contentType) {
+    return ["text/javascript", "text/css"].includes(contentType);
+  }
+  /**
+   * Normalizes a request pathname and rejects directory traversal attempts.
+   */
+  sanitizePath(pathname) {
+    const withoutLeadingSlash = pathname.replace(/^\/+/, "");
+    const normalizedPath = normalize(withoutLeadingSlash);
+    if (normalizedPath.startsWith("..") || normalizedPath.includes(`..${sep}`)) {
+      return null;
+    }
+    return normalizedPath;
+  }
+  /**
+   * Writes one HTTP response with the provided headers and optional body.
+   */
+  sendResponse(res, status, headers, body) {
+    res.statusCode = status;
+    for (const [key, value] of Object.entries(headers)) {
+      res.setHeader(key, value);
+    }
+    if (!body) {
+      res.end();
+      return;
+    }
+    res.end(body);
+  }
+  /**
+   * Serves the generated 404 page when present, or a plain-text fallback.
+   */
+  sendNotFoundPage(req, res) {
+    const error404TemplatePath = join(this.appConfig.absolutePaths.distDir, "404.html");
+    const isHead = (req.method ?? "GET").toUpperCase() === "HEAD";
+    if (!fileSystem.exists(error404TemplatePath)) {
+      this.sendResponse(
+        res,
+        404,
+        { "Content-Type": "text/plain" },
+        isHead ? void 0 : Buffer.from(STATUS_MESSAGE[404])
+      );
+      return;
+    }
+    const file = fileSystem.readFileAsBuffer(error404TemplatePath);
+    this.sendResponse(res, 404, { "Content-Type": "text/html" }, isHead ? void 0 : file);
+  }
+  /**
+   * Serves one concrete file path, honoring gzip and HEAD semantics.
+   */
+  serveFile(req, res, filePath, status = 200) {
+    const contentType = ServerUtils.getContentType(extname(filePath));
+    const acceptsGzip = req.headers["accept-encoding"]?.includes("gzip");
+    const isHead = (req.method ?? "GET").toUpperCase() === "HEAD";
+    if (acceptsGzip && this.shouldServeGzip(contentType)) {
+      const gzipPath = `${filePath}.gz`;
+      if (fileSystem.exists(gzipPath)) {
+        const file2 = fileSystem.readFileAsBuffer(gzipPath);
+        this.sendResponse(
+          res,
+          status,
+          {
+            "Content-Type": contentType,
+            "Content-Encoding": "gzip",
+            Vary: "Accept-Encoding"
+          },
+          isHead ? void 0 : file2
+        );
+        return;
+      }
+    }
+    if (!fileSystem.exists(filePath)) {
+      this.sendNotFoundPage(req, res);
+      return;
+    }
+    const file = fileSystem.readFileAsBuffer(filePath);
+    this.sendResponse(res, status, { "Content-Type": contentType }, isHead ? void 0 : file);
+  }
+  /**
+   * Handles one incoming Node HTTP request against the built static output tree.
+   */
+  handleRequest(req, res) {
+    const method = (req.method ?? "GET").toUpperCase();
+    const isHead = method === "HEAD";
+    if (method !== "GET" && method !== "HEAD") {
+      this.sendResponse(
+        res,
+        405,
+        { Allow: "GET, HEAD", "Content-Type": "text/plain" },
+        isHead ? void 0 : Buffer.from("Method Not Allowed")
+      );
+      return;
+    }
+    const url = new URL(req.url ?? "/", "http://localhost");
+    let decodedPathname = "/";
+    try {
+      decodedPathname = decodeURIComponent(url.pathname);
+    } catch {
+      this.sendResponse(
+        res,
+        400,
+        { "Content-Type": "text/plain" },
+        isHead ? void 0 : Buffer.from("Invalid path")
+      );
+      return;
+    }
+    const pathname = decodedPathname === "/" ? "/index.html" : decodedPathname;
+    const relativePath = this.sanitizePath(pathname);
+    if (!relativePath) {
+      this.sendResponse(
+        res,
+        400,
+        { "Content-Type": "text/plain" },
+        isHead ? void 0 : Buffer.from("Invalid path")
+      );
+      return;
+    }
+    const basePath = join(this.appConfig.absolutePaths.distDir, relativePath);
+    if (pathname.includes(".")) {
+      this.serveFile(req, res, basePath);
+      return;
+    }
+    const htmlCandidates = [`${basePath}.html`, join(basePath, "index.html")];
+    for (const candidate of htmlCandidates) {
+      if (fileSystem.exists(candidate)) {
+        this.serveFile(req, res, candidate);
+        return;
+      }
+    }
+    this.sendNotFoundPage(req, res);
+  }
+  /**
+   * Starts the static preview server.
+   */
+  async start() {
+    if (this.server) {
+      return this.server;
+    }
+    this.server = createServer(this.handleRequest.bind(this));
+    const hostname = this.options.hostname ?? DEFAULT_ECOPAGES_HOSTNAME;
+    const port = this.options.port ?? DEFAULT_ECOPAGES_PORT;
+    await new Promise((resolve) => {
+      this.server.listen(port, hostname, () => resolve());
+    });
+    return this.server;
+  }
+  /**
+   * Stops the static preview server and optionally closes active connections.
+   */
+  async stop(force = true) {
+    if (!this.server) {
+      return;
+    }
+    const activeServer = this.server;
+    this.server = null;
+    await new Promise((resolve, reject) => {
+      activeServer.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+      if (force) {
+        activeServer.closeAllConnections();
+      }
+    });
+  }
+}
+export {
+  NodeStaticContentServer
+};

package/src/adapters/node/static-preview-host.d.ts

@@ -0,0 +1,55 @@
+import type { AddressInfo } from 'node:net';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { StaticPreviewHost, StaticPreviewHostStartOptions } from '../shared/static-preview-host.js';
+type NodeStaticPreviewServer = {
+    start(): Promise<{
+        address(): AddressInfo | string | null;
+    }>;
+    stop(force?: boolean): Promise<void>;
+};
+type NodeStaticPreviewServerFactory = new (args: {
+    appConfig: EcoPagesAppConfig;
+    options?: {
+        hostname?: string;
+        port?: number;
+    };
+}) => NodeStaticPreviewServer;
+/**
+ * Node preview-host wrapper that manages the lifecycle of the static preview
+ * server used after a build.
+ *
+ * @remarks
+ * The host separates preview-server construction from lifecycle control so the
+ * Node server adapter can restart preview serving safely across repeated build
+ * and preview flows.
+ */
+export declare class NodeStaticPreviewHost implements StaticPreviewHost {
+    private readonly previewServerFactory;
+    private previewServer;
+    private stopPromise;
+    /**
+     * Creates the preview host with an injectable preview-server constructor.
+     */
+    constructor(previewServerFactory?: NodeStaticPreviewServerFactory);
+    /**
+     * 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.
+     */
+    start(options: StaticPreviewHostStartOptions): Promise<number | null>;
+    /**
+     * 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.
+     */
+    stop(force?: boolean): Promise<void>;
+}
+export {};

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/api-response.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A builder class for creating Response objects fluently.
+ */
+export declare class ApiResponseBuilder {
+    private _status;
+    private _headers;
+    /**
+     * Sets the HTTP status code for the response.
+     * @param code - The HTTP status code.
+     * @returns The builder instance for chaining.
+     */
+    status(code: Response['status']): this;
+    /**
+     * Adds or merges headers for the response.
+     * @param headersInit - Headers to add or merge.
+     * @returns The builder instance for chaining.
+     */
+    headers(headersInit: HeadersInit): this;
+    /**
+     * Creates a JSON response using the configured status and headers.
+     * @param data - The data to serialize.
+     * @returns A Response object.
+     */
+    json(data: any): Response;
+    /**
+     * Creates a plain text response using the configured status and headers.
+     * @param data - The text content.
+     * @returns A Response object.
+     */
+    text(data: string): Response;
+    /**
+     * Creates an HTML response using the configured status and headers.
+     * @param data - The HTML content.
+     * @returns A Response object.
+     */
+    html(data: string): Response;
+    /**
+     * Creates a redirect response.
+     * @param url - The URL to redirect to.
+     * @param explicitStatus - Optional explicit status code (overrides status() if provided). Defaults to 302 if not set via status().
+     * @returns A Response object.
+     */
+    redirect(url: string, explicitStatus?: Response['status']): Response;
+    /**
+     * Creates an error response using the configured status and headers.
+     * If data is an object, it's treated as JSON, otherwise as text.
+     * @param data - The error data (string or object).
+     * @param explicitStatus - Optional explicit status code (overrides status() if provided). Defaults to 500 if not set via status().
+     * @returns A Response object.
+     */
+    error(data: string | object, explicitStatus?: Response['status']): Response;
+}

package/src/adapters/shared/api-response.js

@@ -0,0 +1,96 @@
+class ApiResponseBuilder {
+  _status = 200;
+  _headers = new Headers();
+  /**
+   * Sets the HTTP status code for the response.
+   * @param code - The HTTP status code.
+   * @returns The builder instance for chaining.
+   */
+  status(code) {
+    this._status = code;
+    return this;
+  }
+  /**
+   * Adds or merges headers for the response.
+   * @param headersInit - Headers to add or merge.
+   * @returns The builder instance for chaining.
+   */
+  headers(headersInit) {
+    const inputHeaders = new Headers(headersInit);
+    inputHeaders.forEach((value, key) => {
+      this._headers.set(key, value);
+    });
+    return this;
+  }
+  /**
+   * Creates a JSON response using the configured status and headers.
+   * @param data - The data to serialize.
+   * @returns A Response object.
+   */
+  json(data) {
+    if (!this._headers.has("Content-Type")) {
+      this._headers.set("Content-Type", "application/json; charset=utf-8");
+    }
+    return new Response(JSON.stringify(data), { status: this._status, headers: this._headers });
+  }
+  /**
+   * Creates a plain text response using the configured status and headers.
+   * @param data - The text content.
+   * @returns A Response object.
+   */
+  text(data) {
+    if (!this._headers.has("Content-Type")) {
+      this._headers.set("Content-Type", "text/plain; charset=utf-8");
+    }
+    return new Response(data, { status: this._status, headers: this._headers });
+  }
+  /**
+   * Creates an HTML response using the configured status and headers.
+   * @param data - The HTML content.
+   * @returns A Response object.
+   */
+  html(data) {
+    if (!this._headers.has("Content-Type")) {
+      this._headers.set("Content-Type", "text/html; charset=utf-8");
+    }
+    return new Response(data, { status: this._status, headers: this._headers });
+  }
+  /**
+   * Creates a redirect response.
+   * @param url - The URL to redirect to.
+   * @param explicitStatus - Optional explicit status code (overrides status() if provided). Defaults to 302 if not set via status().
+   * @returns A Response object.
+   */
+  redirect(url, explicitStatus) {
+    const redirectStatus = explicitStatus ?? (this._status === 200 ? 302 : this._status);
+    this._headers.set("Location", url);
+    return new Response(null, { status: redirectStatus, headers: this._headers });
+  }
+  /**
+   * Creates an error response using the configured status and headers.
+   * If data is an object, it's treated as JSON, otherwise as text.
+   * @param data - The error data (string or object).
+   * @param explicitStatus - Optional explicit status code (overrides status() if provided). Defaults to 500 if not set via status().
+   * @returns A Response object.
+   */
+  error(data, explicitStatus) {
+    const errorStatus = explicitStatus ?? (this._status === 200 ? 500 : this._status);
+    this.status(errorStatus);
+    if (typeof data === "object" && data !== null) {
+      if (!this._headers.has("Content-Type")) {
+        this._headers.set("Content-Type", "application/json; charset=utf-8");
+      }
+      return new Response(JSON.stringify({ error: data }), {
+        status: this._status,
+        headers: this._headers
+      });
+    }
+    if (!this._headers.has("Content-Type")) {
+      this._headers.set("Content-Type", "text/plain; charset=utf-8");
+    }
+    return new Response(String(data), { status: this._status, headers: this._headers });
+  }
+}
+export {
+  ApiResponseBuilder
+};

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

@@ -0,0 +1,18 @@
+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;
+    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;
+    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;
+    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;
+    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;
+    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;
+    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;
+    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;
+    route<P extends string>(path: P, method: ApiHandler['method'], handler: RouteHandler<TRequest, TServer>, options?: RouteOptions<TRequest, TServer>): this;
+    add(handler: ApiHandler<string, TRequest, TServer>): this;
+    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;
+    private registerGroup;
+}

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/define-api-handler.d.ts

@@ -0,0 +1,25 @@
+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'> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[];
+    schema?: TSchema;
+}): ApiHandler<TPath, Request, unknown>;
+export interface GroupHandler<TPrefix extends string = string> {
+    prefix: TPrefix;
+    middleware?: readonly Middleware<Request, unknown, any>[];
+    routes: readonly ApiHandler<string, Request, unknown>[];
+}
+type GroupDefineHandler<TContext extends UniversalContext> = <const TPath extends string, TSchema extends RouteSchema | undefined = undefined>(handler: Omit<ApiHandler<TPath, Request, unknown>, 'handler' | 'middleware' | 'schema'> & {
+    path: TPath;
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[];
+    schema?: TSchema;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare function defineGroupHandler<TPrefix extends string, TMiddleware extends readonly Middleware<Request, unknown, any>[] = [], TContext extends UniversalContext = TMiddleware extends readonly Middleware<Request, unknown, infer TGroupContext>[] ? TGroupContext : UniversalContext>(config: {
+    prefix: TPrefix;
+    middleware?: TMiddleware;
+    routes: (define: GroupDefineHandler<TContext>) => readonly ApiHandler<string, Request, unknown>[];
+}): GroupHandler<TPrefix>;
+export {};

package/src/adapters/shared/define-api-handler.js

@@ -0,0 +1,15 @@
+function defineApiHandler(handler) {
+  return handler;
+}
+function defineGroupHandler(config) {
+  const define = ((handler) => handler);
+  return {
+    prefix: config.prefix,
+    middleware: config.middleware,
+    routes: config.routes(define)
+  };
+}
+export {
+  defineApiHandler,
+  defineGroupHandler
+};

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
+};