@ecopages/core 0.2.0-alpha.1

package/src/services/html-transformer.service.ts

@@ -0,0 +1,217 @@
+import { appLogger } from '../global/app-logger.ts';
+import type { AssetPosition, ProcessedAsset, ScriptAsset } from './asset-processing-service/assets.types';
+
+type HtmlRewriterElement = {
+	append(content: string, options?: { html?: boolean }): void;
+};
+
+type HtmlRewriterConstructor = new () => HtmlRewriterRuntime;
+
+export type HtmlRewriterMode = 'auto' | 'native' | 'worker-tools' | 'fallback';
+
+type HtmlRewriterRuntime = {
+	on(selector: 'head' | 'body', handler: { element: (element: HtmlRewriterElement) => void }): HtmlRewriterRuntime;
+	transform(response: Response): Response;
+};
+
+export interface HtmlTransformerServiceOptions {
+	htmlRewriterMode?: HtmlRewriterMode;
+}
+
+export class HtmlTransformerService {
+	private processedDependencies: ProcessedAsset[] = [];
+	private htmlRewriterConstructorPromise?: Promise<HtmlRewriterConstructor | null>;
+	private htmlRewriterMode: HtmlRewriterMode = 'auto';
+
+	constructor(options: HtmlTransformerServiceOptions = {}) {
+		this.setHtmlRewriterMode(options.htmlRewriterMode ?? 'auto');
+	}
+
+	/**
+	 * Overrides the HTML rewriter runtime selection.
+	 *
+	 * This is intended for internal/runtime tests that need deterministic
+	 * selection between native, worker-tools, and string fallback behavior.
+	 *
+	 * @param mode Requested runtime selection strategy.
+	 */
+	setHtmlRewriterMode(mode: HtmlRewriterMode) {
+		this.htmlRewriterMode = mode;
+		this.htmlRewriterConstructorPromise = undefined;
+	}
+
+	/**
+	 * Creates an HTML rewriter instance from the best available runtime.
+	 *
+	 * Resolution order is:
+	 * 1. native `globalThis.HTMLRewriter`
+	 * 2. `@worker-tools/html-rewriter/base64`
+	 * 3. `null`, which triggers the string-based fallback path
+	 *
+	 * @returns HTML rewriter instance when available; otherwise `null`.
+	 */
+	private async createHtmlRewriter(): Promise<HtmlRewriterRuntime | null> {
+		const RuntimeHtmlRewriter = await this.resolveHtmlRewriterConstructor();
+		return RuntimeHtmlRewriter ? new RuntimeHtmlRewriter() : null;
+	}
+
+	/**
+	 * Resolves the constructor used for HTML rewriting.
+	 *
+	 * The worker-tools fallback is loaded lazily so native runtimes avoid the WASM
+	 * dependency cost unless it is actually needed.
+	 *
+	 * @returns Rewriter constructor when available; otherwise `null`.
+	 */
+	private async resolveHtmlRewriterConstructor(): Promise<HtmlRewriterConstructor | null> {
+		if (!this.htmlRewriterConstructorPromise) {
+			const mode = this.htmlRewriterMode;
+			const RuntimeHtmlRewriter = (globalThis as { HTMLRewriter?: HtmlRewriterConstructor }).HTMLRewriter;
+
+			if (mode === 'fallback') {
+				this.htmlRewriterConstructorPromise = Promise.resolve(null);
+			} else if (mode === 'native') {
+				if (RuntimeHtmlRewriter) {
+					this.htmlRewriterConstructorPromise = Promise.resolve(RuntimeHtmlRewriter);
+				} else {
+					appLogger.warn(
+						'[HtmlTransformerService] Native HTMLRewriter was forced but is unavailable, falling back to string injection.',
+					);
+					this.htmlRewriterConstructorPromise = Promise.resolve(null);
+				}
+			} else if (mode === 'auto' && RuntimeHtmlRewriter) {
+				this.htmlRewriterConstructorPromise = Promise.resolve(RuntimeHtmlRewriter);
+			} else {
+				this.htmlRewriterConstructorPromise = import('@worker-tools/html-rewriter/base64')
+					.then((module) => module.HTMLRewriter as HtmlRewriterConstructor)
+					.catch((error: unknown) => {
+						const message = error instanceof Error ? error.message : String(error);
+						appLogger.warn(
+							`[HtmlTransformerService] Failed to load @worker-tools/html-rewriter/base64, falling back to string injection: ${message}`,
+						);
+						return null;
+					});
+			}
+		}
+
+		return this.htmlRewriterConstructorPromise;
+	}
+
+	private formatAttributes(attrs?: Record<string, string>): string {
+		if (!attrs) return '';
+		return ` ${Object.entries(attrs)
+			.map(([key, value]) => `${key}="${value}"`)
+			.join(' ')}`;
+	}
+
+	private generateScriptTag(dep: ProcessedAsset & { kind: 'script' }): string {
+		return dep.inline
+			? `<script${this.formatAttributes(dep.attributes)}>${dep.content}</script>`
+			: `<script src="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}></script>`;
+	}
+
+	private generateStylesheetTag(dep: ProcessedAsset): string {
+		return dep.inline
+			? `<style${this.formatAttributes(dep.attributes)}>${dep.content}</style>`
+			: `<link rel="stylesheet" href="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}>`;
+	}
+
+	private appendDependencies(element: HtmlRewriterElement, dependencies: ProcessedAsset[]) {
+		for (const dep of dependencies) {
+			const tag =
+				dep.kind === 'script' ? this.generateScriptTag(dep as ScriptAsset) : this.generateStylesheetTag(dep);
+			element.append(tag, { html: true });
+		}
+	}
+
+	private buildDependencyTags(dependencies: ProcessedAsset[]): string {
+		return dependencies
+			.map((dep) =>
+				dep.kind === 'script' ? this.generateScriptTag(dep as ScriptAsset) : this.generateStylesheetTag(dep),
+			)
+			.join('');
+	}
+
+	private injectBeforeClosingTag(html: string, tag: 'head' | 'body', content: string): string {
+		if (!content) {
+			return html;
+		}
+
+		const closingTag = `</${tag}>`;
+		const lowerHtml = html.toLowerCase();
+		const closingTagIndex = lowerHtml.lastIndexOf(closingTag);
+
+		if (closingTagIndex !== -1) {
+			return `${html.slice(0, closingTagIndex)}${content}${html.slice(closingTagIndex)}`;
+		}
+
+		if (tag === 'head') {
+			return `${content}${html}`;
+		}
+
+		return `${html}${content}`;
+	}
+
+	setProcessedDependencies(processedDependencies: ProcessedAsset[]) {
+		this.processedDependencies = processedDependencies;
+	}
+
+	getProcessedDependencies(): ProcessedAsset[] {
+		return this.processedDependencies;
+	}
+
+	async transform(res: Response): Promise<Response> {
+		const { head, body } = this.groupDependenciesByPosition();
+		const htmlRewriter = await this.createHtmlRewriter();
+
+		const html = await res.text();
+		const headers = new Headers(res.headers);
+
+		if (htmlRewriter) {
+			htmlRewriter
+				.on('head', {
+					element: (element) => this.appendDependencies(element, head),
+				})
+				.on('body', {
+					element: (element) => this.appendDependencies(element, body),
+				});
+
+			return htmlRewriter.transform(
+				new Response(html, {
+					headers,
+					status: res.status,
+					statusText: res.statusText,
+				}),
+			);
+		}
+
+		const withHeadDependencies = this.injectBeforeClosingTag(html, 'head', this.buildDependencyTags(head));
+		const transformedHtml = this.injectBeforeClosingTag(
+			withHeadDependencies,
+			'body',
+			this.buildDependencyTags(body),
+		);
+
+		return new Response(transformedHtml, {
+			headers,
+			status: res.status,
+			statusText: res.statusText,
+		});
+	}
+
+	private groupDependenciesByPosition() {
+		return this.processedDependencies.reduce(
+			(acc, dep) => {
+				if (dep.kind === 'script') {
+					if (dep.excludeFromHtml) return acc;
+					const position = dep.position || 'body';
+					acc[position].push(dep);
+				} else if (dep.kind === 'stylesheet') {
+					acc.head.push(dep);
+				}
+				return acc;
+			},
+			{ head: [], body: [] } as Record<AssetPosition, ProcessedAsset[]>,
+		);
+	}
+}

package/src/services/page-module-import.service.d.ts

@@ -0,0 +1,37 @@
+export interface PageModuleImportOptions {
+    filePath: string;
+    rootDir: string;
+    outdir: string;
+    externalPackages?: boolean;
+    transpileErrorMessage?: (details: string) => string;
+    noOutputMessage?: (filePath: string) => string;
+}
+/**
+ * Loads source page modules in a runtime-agnostic way.
+ *
+ * This service centralizes the Bun-vs-Node import strategy used by route
+ * scanning, page data loading, and request-time page inspection. In Bun it can
+ * import source files directly; in Node it transpiles the file into a dedicated
+ * output directory first and then imports the generated module.
+ *
+ * Keeping this logic in one place prevents subtle drift in cache-busting,
+ * transpilation settings, and error semantics across the different callers.
+ */
+export declare class PageModuleImportService {
+    private static readonly importCache;
+    static clearImportCache(): void;
+    /**
+     * Imports a page-like module from source.
+     *
+     * The caller controls the output directory and error wording so different
+     * subsystems can reuse the same loading mechanism while preserving their
+     * current diagnostics. Module identities stay stable for unchanged files and
+     * roll forward automatically when the source hash changes during watch mode.
+     *
+     * @typeParam T Expected module shape.
+     * @param options Runtime-specific import settings.
+     * @returns The loaded module.
+     */
+    importModule<T = unknown>(options: PageModuleImportOptions): Promise<T>;
+    private loadModule;
+}

package/src/services/page-module-import.service.js

@@ -0,0 +1,88 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { fileSystem } from "@ecopages/file-system";
+import { defaultBuildAdapter } from "../build/build-adapter.js";
+class PageModuleImportService {
+  static importCache = /* @__PURE__ */ new Map();
+  static clearImportCache() {
+    this.importCache.clear();
+  }
+  /**
+   * Imports a page-like module from source.
+   *
+   * The caller controls the output directory and error wording so different
+   * subsystems can reuse the same loading mechanism while preserving their
+   * current diagnostics. Module identities stay stable for unchanged files and
+   * roll forward automatically when the source hash changes during watch mode.
+   *
+   * @typeParam T Expected module shape.
+   * @param options Runtime-specific import settings.
+   * @returns The loaded module.
+   */
+  async importModule(options) {
+    const { filePath, rootDir, externalPackages } = options;
+    const fileHash = fileSystem.hash(filePath);
+    const runtime = typeof Bun !== "undefined" ? "bun" : "node";
+    const cacheKey = [runtime, filePath, rootDir, externalPackages ?? "default", fileHash].join("::");
+    const cachedModule = PageModuleImportService.importCache.get(cacheKey);
+    if (cachedModule) {
+      return await cachedModule;
+    }
+    const importPromise = this.loadModule({
+      ...options,
+      fileHash
+    });
+    PageModuleImportService.importCache.set(cacheKey, importPromise);
+    try {
+      return await importPromise;
+    } catch (error) {
+      PageModuleImportService.importCache.delete(cacheKey);
+      throw error;
+    }
+  }
+  async loadModule(options) {
+    const {
+      filePath,
+      rootDir,
+      outdir,
+      externalPackages,
+      transpileErrorMessage = (details) => `Error transpiling page module: ${details}`,
+      noOutputMessage = (targetFilePath) => `No transpiled output generated for page module: ${targetFilePath}`,
+      fileHash
+    } = options;
+    if (typeof Bun !== "undefined") {
+      const moduleUrl = pathToFileURL(filePath);
+      if (process.env.NODE_ENV === "development") {
+        moduleUrl.searchParams.set("update", fileHash);
+      }
+      return await import(moduleUrl.href);
+    }
+    const fileBaseName = path.basename(filePath, path.extname(filePath));
+    const outputFileName = `${fileBaseName}-${fileHash}.js`;
+    const buildResult = await defaultBuildAdapter.build({
+      entrypoints: [filePath],
+      root: rootDir,
+      outdir,
+      target: "node",
+      format: "esm",
+      sourcemap: "none",
+      splitting: false,
+      minify: false,
+      naming: outputFileName,
+      ...externalPackages !== void 0 ? { externalPackages } : {}
+    });
+    if (!buildResult.success) {
+      const details = buildResult.logs.map((log) => log.message).join(" | ");
+      throw new Error(transpileErrorMessage(details));
+    }
+    const preferredOutputPath = path.join(outdir, outputFileName);
+    const compiledOutput = buildResult.outputs.find((output) => output.path === preferredOutputPath)?.path ?? buildResult.outputs.find((output) => output.path.endsWith(".js"))?.path;
+    if (!compiledOutput) {
+      throw new Error(noOutputMessage(filePath));
+    }
+    return await import(pathToFileURL(compiledOutput).href);
+  }
+}
+export {
+  PageModuleImportService
+};

package/src/services/page-module-import.service.ts

@@ -0,0 +1,129 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { fileSystem } from '@ecopages/file-system';
+import { defaultBuildAdapter } from '../build/build-adapter.ts';
+
+export interface PageModuleImportOptions {
+	filePath: string;
+	rootDir: string;
+	outdir: string;
+	externalPackages?: boolean;
+	transpileErrorMessage?: (details: string) => string;
+	noOutputMessage?: (filePath: string) => string;
+}
+
+/**
+ * Loads source page modules in a runtime-agnostic way.
+ *
+ * This service centralizes the Bun-vs-Node import strategy used by route
+ * scanning, page data loading, and request-time page inspection. In Bun it can
+ * import source files directly; in Node it transpiles the file into a dedicated
+ * output directory first and then imports the generated module.
+ *
+ * Keeping this logic in one place prevents subtle drift in cache-busting,
+ * transpilation settings, and error semantics across the different callers.
+ */
+export class PageModuleImportService {
+	private static readonly importCache = new Map<string, Promise<unknown>>();
+
+	static clearImportCache(): void {
+		this.importCache.clear();
+	}
+
+	/**
+	 * Imports a page-like module from source.
+	 *
+	 * The caller controls the output directory and error wording so different
+	 * subsystems can reuse the same loading mechanism while preserving their
+	 * current diagnostics. Module identities stay stable for unchanged files and
+	 * roll forward automatically when the source hash changes during watch mode.
+	 *
+	 * @typeParam T Expected module shape.
+	 * @param options Runtime-specific import settings.
+	 * @returns The loaded module.
+	 */
+	async importModule<T = unknown>(options: PageModuleImportOptions): Promise<T> {
+		const { filePath, rootDir, externalPackages } = options;
+
+		const fileHash = fileSystem.hash(filePath);
+		const runtime = typeof Bun !== 'undefined' ? 'bun' : 'node';
+		const cacheKey = [runtime, filePath, rootDir, externalPackages ?? 'default', fileHash].join('::');
+		const cachedModule = PageModuleImportService.importCache.get(cacheKey);
+
+		if (cachedModule) {
+			return (await cachedModule) as T;
+		}
+
+		const importPromise = this.loadModule<T>({
+			...options,
+			fileHash,
+		});
+
+		PageModuleImportService.importCache.set(cacheKey, importPromise);
+
+		try {
+			return await importPromise;
+		} catch (error) {
+			PageModuleImportService.importCache.delete(cacheKey);
+			throw error;
+		}
+	}
+
+	private async loadModule<T = unknown>(
+		options: PageModuleImportOptions & {
+			fileHash: string;
+		},
+	): Promise<T> {
+		const {
+			filePath,
+			rootDir,
+			outdir,
+			externalPackages,
+			transpileErrorMessage = (details) => `Error transpiling page module: ${details}`,
+			noOutputMessage = (targetFilePath) => `No transpiled output generated for page module: ${targetFilePath}`,
+			fileHash,
+		} = options;
+
+		if (typeof Bun !== 'undefined') {
+			const moduleUrl = pathToFileURL(filePath);
+
+			if (process.env.NODE_ENV === 'development') {
+				moduleUrl.searchParams.set('update', fileHash);
+			}
+
+			return (await import(moduleUrl.href)) as T;
+		}
+
+		const fileBaseName = path.basename(filePath, path.extname(filePath));
+		const outputFileName = `${fileBaseName}-${fileHash}.js`;
+
+		const buildResult = await defaultBuildAdapter.build({
+			entrypoints: [filePath],
+			root: rootDir,
+			outdir,
+			target: 'node',
+			format: 'esm',
+			sourcemap: 'none',
+			splitting: false,
+			minify: false,
+			naming: outputFileName,
+			...(externalPackages !== undefined ? { externalPackages } : {}),
+		});
+
+		if (!buildResult.success) {
+			const details = buildResult.logs.map((log) => log.message).join(' | ');
+			throw new Error(transpileErrorMessage(details));
+		}
+
+		const preferredOutputPath = path.join(outdir, outputFileName);
+		const compiledOutput =
+			buildResult.outputs.find((output) => output.path === preferredOutputPath)?.path ??
+			buildResult.outputs.find((output) => output.path.endsWith('.js'))?.path;
+
+		if (!compiledOutput) {
+			throw new Error(noOutputMessage(filePath));
+		}
+
+		return (await import(pathToFileURL(compiledOutput).href)) as T;
+	}
+}

package/src/services/page-request-cache-coordinator.service.d.ts

@@ -0,0 +1,75 @@
+import { type PageCacheService } from './cache/page-cache-service.js';
+import type { CacheStrategy, RenderResult } from './cache/cache.types.js';
+/**
+ * Coordinates request-time page caching concerns around one render invocation.
+ *
+ * This service keeps `FileSystemResponseMatcher` from owning low-level cache
+ * policy mechanics such as cache key construction, `dynamic` bypass behavior,
+ * body normalization for cache storage, and final cache header generation.
+ */
+export declare class PageRequestCacheCoordinator {
+    private cacheService;
+    private defaultCacheStrategy;
+    constructor(cacheService: PageCacheService | null, defaultCacheStrategy: CacheStrategy);
+    /**
+     * Builds the cache key used for page lookups.
+     *
+     * Query parameters are part of the key so two requests that hit the same
+     * pathname but differ by search params do not share the same rendered entry.
+     *
+     * @param input Pathname plus optional query record.
+     * @returns Stable cache key for the request.
+     */
+    buildCacheKey(input: {
+        pathname: string;
+        query?: Record<string, string>;
+    }): string;
+    /**
+     * Resolves a render request through the configured cache policy.
+     *
+     * Pages using `dynamic` rendering, or applications without a cache service,
+     * bypass cache lookup entirely and still receive the same response header
+     * contract as cached pages.
+     *
+     * @param options Cache coordination inputs for one page request.
+     * @returns HTTP response with cache headers applied.
+     */
+    render(options: {
+        cacheKey: string;
+        pageCacheStrategy: CacheStrategy;
+        renderFn: () => Promise<RenderResult>;
+    }): Promise<Response>;
+    /**
+     * Exposes the underlying cache service for invalidation and adapter plumbing.
+     *
+     * @returns Configured cache service or `null` when caching is disabled.
+     */
+    getCacheService(): PageCacheService | null;
+    /**
+     * Returns the default render strategy used when a page does not declare one.
+     *
+     * @returns Application-level fallback cache strategy.
+     */
+    getDefaultCacheStrategy(): CacheStrategy;
+    /**
+     * Normalizes various route render body shapes into a cacheable string.
+     *
+     * Page rendering may produce strings, buffers, byte arrays, or streams. The
+     * matcher needs a single representation before passing HTML through the cache
+     * layer, so this method centralizes the conversion rules.
+     *
+     * @param body Render output body in any supported form.
+     * @returns HTML string representation.
+     */
+    bodyToString(body: unknown): Promise<string>;
+    /**
+     * Creates the final HTML response with the current cache semantics encoded in
+     * response headers.
+     *
+     * @param html Rendered page HTML.
+     * @param strategy Effective cache strategy for the response.
+     * @param cacheStatus Status used for `X-Cache` and `Cache-Control` generation.
+     * @returns HTTP response ready to send to the client.
+     */
+    private createCachedResponse;
+}

package/src/services/page-request-cache-coordinator.service.js

@@ -0,0 +1,107 @@
+import { getCacheControlHeader } from "./cache/page-cache-service.js";
+class PageRequestCacheCoordinator {
+  constructor(cacheService, defaultCacheStrategy) {
+    this.cacheService = cacheService;
+    this.defaultCacheStrategy = defaultCacheStrategy;
+  }
+  /**
+   * Builds the cache key used for page lookups.
+   *
+   * Query parameters are part of the key so two requests that hit the same
+   * pathname but differ by search params do not share the same rendered entry.
+   *
+   * @param input Pathname plus optional query record.
+   * @returns Stable cache key for the request.
+   */
+  buildCacheKey(input) {
+    let key = input.pathname;
+    if (input.query && Object.keys(input.query).length > 0) {
+      const queryString = new URLSearchParams(input.query).toString();
+      key += `?${queryString}`;
+    }
+    return key;
+  }
+  /**
+   * Resolves a render request through the configured cache policy.
+   *
+   * Pages using `dynamic` rendering, or applications without a cache service,
+   * bypass cache lookup entirely and still receive the same response header
+   * contract as cached pages.
+   *
+   * @param options Cache coordination inputs for one page request.
+   * @returns HTTP response with cache headers applied.
+   */
+  async render(options) {
+    if (!this.cacheService || options.pageCacheStrategy === "dynamic") {
+      const { html, strategy } = await options.renderFn();
+      return this.createCachedResponse(html, strategy, "disabled");
+    }
+    const result = await this.cacheService.getOrCreate(
+      options.cacheKey,
+      options.pageCacheStrategy,
+      options.renderFn
+    );
+    return this.createCachedResponse(result.html, result.strategy, result.status);
+  }
+  /**
+   * Exposes the underlying cache service for invalidation and adapter plumbing.
+   *
+   * @returns Configured cache service or `null` when caching is disabled.
+   */
+  getCacheService() {
+    return this.cacheService;
+  }
+  /**
+   * Returns the default render strategy used when a page does not declare one.
+   *
+   * @returns Application-level fallback cache strategy.
+   */
+  getDefaultCacheStrategy() {
+    return this.defaultCacheStrategy;
+  }
+  /**
+   * Normalizes various route render body shapes into a cacheable string.
+   *
+   * Page rendering may produce strings, buffers, byte arrays, or streams. The
+   * matcher needs a single representation before passing HTML through the cache
+   * layer, so this method centralizes the conversion rules.
+   *
+   * @param body Render output body in any supported form.
+   * @returns HTML string representation.
+   */
+  async bodyToString(body) {
+    if (typeof body === "string") {
+      return body;
+    }
+    if (Buffer.isBuffer(body)) {
+      return body.toString("utf-8");
+    }
+    if (body instanceof ReadableStream) {
+      return new Response(body).text();
+    }
+    if (body instanceof Uint8Array) {
+      return new TextDecoder().decode(body);
+    }
+    return String(body);
+  }
+  /**
+   * Creates the final HTML response with the current cache semantics encoded in
+   * response headers.
+   *
+   * @param html Rendered page HTML.
+   * @param strategy Effective cache strategy for the response.
+   * @param cacheStatus Status used for `X-Cache` and `Cache-Control` generation.
+   * @returns HTTP response ready to send to the client.
+   */
+  createCachedResponse(html, strategy, cacheStatus) {
+    const headers = {
+      "Content-Type": "text/html",
+      "Cache-Control": getCacheControlHeader(cacheStatus === "disabled" ? "disabled" : strategy),
+      "X-Cache": cacheStatus.toUpperCase()
+    };
+    return new Response(html, { headers });
+  }
+}
+export {
+  PageRequestCacheCoordinator
+};