@ecopages/core 0.2.0-alpha.9 → 0.2.1

package/src/services/cache/page-cache-service.ts

@@ -1,202 +0,0 @@
-/**
- * Page cache service with ISR (Incremental Static Regeneration) support.
- * Handles stale-while-revalidate semantics and background regeneration.
- * @module
- */
-
-import { appLogger } from '../../global/app-logger.js';
-import type { CacheEntry, CacheResult, CacheStore, CacheStrategy, RenderResult } from './cache.types.js';
-import { MemoryCacheStore } from './memory-cache-store.js';
-
-export interface PageCacheServiceOptions {
-	store?: CacheStore;
-	enabled?: boolean;
-}
-
-/**
- * Core page caching service with ISR support.
- */
-export class PageCacheService {
-	private store: CacheStore;
-	private enabled: boolean;
-	private regenerationPromises = new Map<string, Promise<string>>();
-
-	constructor(options: PageCacheServiceOptions = {}) {
-		this.store = options.store ?? new MemoryCacheStore();
-		this.enabled = options.enabled ?? true;
-	}
-
-	/**
-	 * Generate a cache key from URL and optional params.
-	 * Uses full URL (path + query) as the key.
-	 */
-	generateCacheKey(url: string): string {
-		return url;
-	}
-
-	/**
-	 * Check if an entry is stale (past its revalidation time).
-	 */
-	private isStale(entry: CacheEntry): boolean {
-		if (entry.revalidateAfter === null) return false;
-		return Date.now() > entry.revalidateAfter;
-	}
-
-	/**
-	 * Create a cache entry from rendered HTML.
-	 */
-	private createEntry(html: string, strategy: CacheStrategy): CacheEntry {
-		const now = Date.now();
-
-		let revalidateAfter: number | null = null;
-		let tags: string[] = [];
-
-		if (strategy === 'static') {
-			revalidateAfter = null;
-		} else if (strategy === 'dynamic') {
-			revalidateAfter = 0;
-		} else if (typeof strategy === 'object') {
-			revalidateAfter = now + strategy.revalidate * 1000;
-			tags = strategy.tags ?? [];
-		}
-
-		return {
-			html,
-			createdAt: now,
-			revalidateAfter,
-			tags,
-			strategy,
-		};
-	}
-
-	/**
-	 * Get cached content or create new content with stale-while-revalidate semantics.
-	 * @param key - Cache key (URL path + query)
-	 * @param defaultStrategy - Default strategy if page doesn't specify one
-	 * @param renderFn - Function that renders the page and returns HTML + strategy
-	 */
-	async getOrCreate(
-		key: string,
-		defaultStrategy: CacheStrategy,
-		renderFn: () => Promise<RenderResult>,
-	): Promise<CacheResult> {
-		if (!this.enabled) {
-			const { html, strategy } = await renderFn();
-			return { html, status: 'miss', strategy };
-		}
-
-		const entry = await this.store.get(key);
-
-		if (!entry) {
-			const { html, strategy } = await renderFn();
-			const effectiveStrategy = strategy ?? defaultStrategy;
-
-			if (effectiveStrategy === 'dynamic') {
-				return { html, status: 'miss', strategy: effectiveStrategy };
-			}
-
-			const newEntry = this.createEntry(html, effectiveStrategy);
-			await this.store.set(key, newEntry);
-			return { html, status: 'miss', strategy: effectiveStrategy };
-		}
-
-		if (!this.isStale(entry)) {
-			return { html: entry.html, status: 'hit', strategy: entry.strategy };
-		}
-
-		this.regenerateInBackground(key, entry.strategy, renderFn);
-		return { html: entry.html, status: 'stale', strategy: entry.strategy };
-	}
-
-	/**
-	 * Regenerate content in the background without blocking the response.
-	 * Uses promise deduplication to prevent multiple concurrent regenerations.
-	 */
-	private regenerateInBackground(
-		key: string,
-		fallbackStrategy: CacheStrategy,
-		renderFn: () => Promise<{ html: string; strategy: CacheStrategy }>,
-	): void {
-		if (this.regenerationPromises.has(key)) {
-			return;
-		}
-
-		const regeneratePromise = (async () => {
-			try {
-				const { html, strategy } = await renderFn();
-				const effectiveStrategy = strategy ?? fallbackStrategy;
-				const newEntry = this.createEntry(html, effectiveStrategy);
-				await this.store.set(key, newEntry);
-				return html;
-			} finally {
-				this.regenerationPromises.delete(key);
-			}
-		})();
-
-		this.regenerationPromises.set(key, regeneratePromise);
-
-		queueMicrotask(() => {
-			regeneratePromise.catch((error) => {
-				appLogger.error(`[PageCacheService] Failed to regenerate: ${key}`, error);
-			});
-		});
-	}
-
-	/**
-	 * Invalidate cache entries by tags.
-	 */
-	async invalidateByTags(tags: string[]): Promise<number> {
-		return this.store.invalidateByTags(tags);
-	}
-
-	/**
-	 * Invalidate cache entries by paths.
-	 */
-	async invalidateByPaths(paths: string[]): Promise<number> {
-		return this.store.invalidateByPaths(paths);
-	}
-
-	/**
-	 * Clear all cached entries.
-	 */
-	async clear(): Promise<void> {
-		return this.store.clear();
-	}
-
-	/**
-	 * Get cache statistics.
-	 */
-	async stats() {
-		return this.store.stats?.() ?? { entries: 0 };
-	}
-
-	/**
-	 * Get the underlying cache store.
-	 */
-	getStore(): CacheStore {
-		return this.store;
-	}
-}
-
-/**
- * Generate Cache-Control header value from cache strategy.
- */
-export function getCacheControlHeader(strategy: CacheStrategy | 'disabled'): string {
-	if (strategy === 'disabled') {
-		return 'no-store, must-revalidate';
-	}
-	if (strategy === 'static') {
-		return 'public, max-age=31536000, immutable';
-	}
-
-	if (strategy === 'dynamic') {
-		return 'no-store, must-revalidate';
-	}
-
-	if (typeof strategy === 'object') {
-		const swr = strategy.revalidate * 2;
-		return `public, max-age=${strategy.revalidate}, stale-while-revalidate=${swr}`;
-	}
-
-	return 'no-store';
-}

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

@@ -1,131 +0,0 @@
-import { getCacheControlHeader, type PageCacheService } from './page-cache-service.js';
-import type { CacheStrategy, RenderResult } from './cache.types.js';
-
-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 {
-	private cacheService: PageCacheService | null;
-	private defaultCacheStrategy: CacheStrategy;
-
-	constructor(cacheService: PageCacheService | null, defaultCacheStrategy: CacheStrategy) {
-		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: { 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 });
-	}
-}

package/src/services/html/html-rewriter-provider.service.ts

@@ -1,103 +0,0 @@
-import { appLogger } from '../../global/app-logger.js';
-
-export type HtmlRewriterElement = {
-	append(content: string, options?: { html?: boolean }): void;
-};
-
-export type HtmlRewriterRuntime = {
-	on(selector: 'head' | 'body', handler: { element: (element: HtmlRewriterElement) => void }): HtmlRewriterRuntime;
-	transform(response: Response): Response;
-};
-
-export type HtmlRewriterConstructor = new () => HtmlRewriterRuntime;
-
-export type HtmlRewriterMode = 'auto' | 'native' | 'worker-tools' | 'fallback';
-
-export interface HtmlRewriterProvider {
-	createHtmlRewriter(): Promise<HtmlRewriterRuntime | null>;
-	setMode(mode: HtmlRewriterMode): void;
-}
-
-export interface HtmlRewriterLogger {
-	warn(message: string): void;
-}
-
-export interface DefaultHtmlRewriterProviderOptions {
-	mode?: HtmlRewriterMode;
-	logger?: HtmlRewriterLogger;
-	getNativeHtmlRewriter?: () => HtmlRewriterConstructor | undefined;
-	loadWorkerToolsHtmlRewriter?: () => Promise<HtmlRewriterConstructor | null>;
-}
-
-export class DefaultHtmlRewriterProvider implements HtmlRewriterProvider {
-	private htmlRewriterConstructorPromise?: Promise<HtmlRewriterConstructor | null>;
-	private htmlRewriterMode: HtmlRewriterMode;
-	private logger: HtmlRewriterLogger;
-	private getNativeHtmlRewriter: () => HtmlRewriterConstructor | undefined;
-	private loadWorkerToolsHtmlRewriter: () => Promise<HtmlRewriterConstructor | null>;
-
-	constructor(options: DefaultHtmlRewriterProviderOptions = {}) {
-		this.htmlRewriterMode = options.mode ?? 'auto';
-		this.logger = options.logger ?? appLogger;
-		this.getNativeHtmlRewriter =
-			options.getNativeHtmlRewriter ??
-			(() => (globalThis as { HTMLRewriter?: HtmlRewriterConstructor }).HTMLRewriter);
-		this.loadWorkerToolsHtmlRewriter = options.loadWorkerToolsHtmlRewriter ?? loadWorkerToolsHtmlRewriter;
-	}
-
-	setMode(mode: HtmlRewriterMode) {
-		this.htmlRewriterMode = mode;
-		this.htmlRewriterConstructorPromise = undefined;
-	}
-
-	async createHtmlRewriter(): Promise<HtmlRewriterRuntime | null> {
-		const RuntimeHtmlRewriter = await this.resolveHtmlRewriterConstructor();
-		return RuntimeHtmlRewriter ? new RuntimeHtmlRewriter() : null;
-	}
-
-	private async resolveHtmlRewriterConstructor(): Promise<HtmlRewriterConstructor | null> {
-		if (!this.htmlRewriterConstructorPromise) {
-			const mode = this.htmlRewriterMode;
-			const RuntimeHtmlRewriter = this.getNativeHtmlRewriter();
-
-			if (mode === 'fallback') {
-				this.htmlRewriterConstructorPromise = Promise.resolve(null);
-			} else if (mode === 'native') {
-				if (RuntimeHtmlRewriter) {
-					this.htmlRewriterConstructorPromise = Promise.resolve(RuntimeHtmlRewriter);
-				} else {
-					this.logger.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 = this.loadWorkerToolsHtmlRewriter();
-			}
-		}
-
-		return this.htmlRewriterConstructorPromise;
-	}
-}
-
-async function loadWorkerToolsHtmlRewriter(): Promise<HtmlRewriterConstructor | null> {
-	try {
-		const module = await import('@worker-tools/html-rewriter/base64');
-		return module.HTMLRewriter as HtmlRewriterConstructor;
-	} catch (primaryError) {
-		try {
-			const runtimeLocalModule = await import(
-				new URL('../node_modules/@worker-tools/html-rewriter/base64.js', import.meta.url).href
-			);
-			return runtimeLocalModule.HTMLRewriter as HtmlRewriterConstructor;
-		} catch {
-			const message = primaryError instanceof Error ? primaryError.message : String(primaryError);
-			appLogger.warn(
-				`[HtmlTransformerService] Failed to load @worker-tools/html-rewriter/base64, falling back to string injection: ${message}`,
-			);
-			return null;
-		}
-	}
-}