@ecopages/core 0.2.0-alpha.1 → 0.2.0-alpha.10

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

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

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

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

@@ -1,129 +0,0 @@
-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.ts

@@ -1,128 +0,0 @@
-import { getCacheControlHeader, type PageCacheService } from './cache/page-cache-service.ts';
-import type { CacheStrategy, RenderResult } from './cache/cache.types.ts';
-
-type CacheStatus = 'hit' | 'miss' | 'stale' | 'expired' | 'disabled';
-
-/**
- * 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 class PageRequestCacheCoordinator {
-	constructor(
-		private cacheService: PageCacheService | null,
-		private 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 {
-		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: {
-		cacheKey: string;
-		pageCacheStrategy: CacheStrategy;
-		renderFn: () => Promise<RenderResult>;
-	}): Promise<Response> {
-		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(): PageCacheService | null {
-		return this.cacheService;
-	}
-
-	/**
-	 * Returns the default render strategy used when a page does not declare one.
-	 *
-	 * @returns Application-level fallback cache strategy.
-	 */
-	getDefaultCacheStrategy(): CacheStrategy {
-		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: unknown): Promise<string> {
-		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.
-	 */
-	private createCachedResponse(html: string, strategy: CacheStrategy, cacheStatus: CacheStatus): Response {
-		const headers: HeadersInit = {
-			'Content-Type': 'text/html',
-			'Cache-Control': getCacheControlHeader(cacheStatus === 'disabled' ? 'disabled' : strategy),
-			'X-Cache': cacheStatus.toUpperCase(),
-		};
-
-		return new Response(html, { headers });
-	}
-}