@ecopages/core 0.2.0-alpha.1

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

@@ -0,0 +1,70 @@
+/**
+ * Page cache service with ISR (Incremental Static Regeneration) support.
+ * Handles stale-while-revalidate semantics and background regeneration.
+ * @module
+ */
+import type { CacheResult, CacheStore, CacheStrategy, RenderResult } from './cache.types.js';
+export interface PageCacheServiceOptions {
+    store?: CacheStore;
+    enabled?: boolean;
+}
+/**
+ * Core page caching service with ISR support.
+ */
+export declare class PageCacheService {
+    private store;
+    private enabled;
+    private regenerationPromises;
+    constructor(options?: PageCacheServiceOptions);
+    /**
+     * Generate a cache key from URL and optional params.
+     * Uses full URL (path + query) as the key.
+     */
+    generateCacheKey(url: string): string;
+    /**
+     * Check if an entry is stale (past its revalidation time).
+     */
+    private isStale;
+    /**
+     * Create a cache entry from rendered HTML.
+     */
+    private createEntry;
+    /**
+     * 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
+     */
+    getOrCreate(key: string, defaultStrategy: CacheStrategy, renderFn: () => Promise<RenderResult>): Promise<CacheResult>;
+    /**
+     * Regenerate content in the background without blocking the response.
+     * Uses promise deduplication to prevent multiple concurrent regenerations.
+     */
+    private regenerateInBackground;
+    /**
+     * Invalidate cache entries by tags.
+     */
+    invalidateByTags(tags: string[]): Promise<number>;
+    /**
+     * Invalidate cache entries by paths.
+     */
+    invalidateByPaths(paths: string[]): Promise<number>;
+    /**
+     * Clear all cached entries.
+     */
+    clear(): Promise<void>;
+    /**
+     * Get cache statistics.
+     */
+    stats(): Promise<import("./cache.types.js").CacheStats | {
+        entries: number;
+    }>;
+    /**
+     * Get the underlying cache store.
+     */
+    getStore(): CacheStore;
+}
+/**
+ * Generate Cache-Control header value from cache strategy.
+ */
+export declare function getCacheControlHeader(strategy: CacheStrategy | 'disabled'): string;

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

@@ -0,0 +1,152 @@
+import { appLogger } from "../../global/app-logger.js";
+import { MemoryCacheStore } from "./memory-cache-store.js";
+class PageCacheService {
+  store;
+  enabled;
+  regenerationPromises = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    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) {
+    return url;
+  }
+  /**
+   * Check if an entry is stale (past its revalidation time).
+   */
+  isStale(entry) {
+    if (entry.revalidateAfter === null) return false;
+    return Date.now() > entry.revalidateAfter;
+  }
+  /**
+   * Create a cache entry from rendered HTML.
+   */
+  createEntry(html, strategy) {
+    const now = Date.now();
+    let revalidateAfter = null;
+    let tags = [];
+    if (strategy === "static") {
+      revalidateAfter = null;
+    } else if (strategy === "dynamic") {
+      revalidateAfter = 0;
+    } else if (typeof strategy === "object") {
+      revalidateAfter = now + strategy.revalidate * 1e3;
+      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, defaultStrategy, renderFn) {
+    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.
+   */
+  regenerateInBackground(key, fallbackStrategy, renderFn) {
+    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) {
+    return this.store.invalidateByTags(tags);
+  }
+  /**
+   * Invalidate cache entries by paths.
+   */
+  async invalidateByPaths(paths) {
+    return this.store.invalidateByPaths(paths);
+  }
+  /**
+   * Clear all cached entries.
+   */
+  async clear() {
+    return this.store.clear();
+  }
+  /**
+   * Get cache statistics.
+   */
+  async stats() {
+    return this.store.stats?.() ?? { entries: 0 };
+  }
+  /**
+   * Get the underlying cache store.
+   */
+  getStore() {
+    return this.store;
+  }
+}
+function getCacheControlHeader(strategy) {
+  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";
+}
+export {
+  PageCacheService,
+  getCacheControlHeader
+};

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

@@ -0,0 +1,202 @@
+/**
+ * Page cache service with ISR (Incremental Static Regeneration) support.
+ * Handles stale-while-revalidate semantics and background regeneration.
+ * @module
+ */
+
+import { appLogger } from '../../global/app-logger.ts';
+import type { CacheEntry, CacheResult, CacheStore, CacheStrategy, RenderResult } from './cache.types.ts';
+import { MemoryCacheStore } from './memory-cache-store.ts';
+
+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/html-transformer.service.d.ts

@@ -0,0 +1,50 @@
+import type { ProcessedAsset } from './asset-processing-service/assets.types';
+export type HtmlRewriterMode = 'auto' | 'native' | 'worker-tools' | 'fallback';
+export interface HtmlTransformerServiceOptions {
+    htmlRewriterMode?: HtmlRewriterMode;
+}
+export declare class HtmlTransformerService {
+    private processedDependencies;
+    private htmlRewriterConstructorPromise?;
+    private htmlRewriterMode;
+    constructor(options?: HtmlTransformerServiceOptions);
+    /**
+     * 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): void;
+    /**
+     * 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 createHtmlRewriter;
+    /**
+     * 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 resolveHtmlRewriterConstructor;
+    private formatAttributes;
+    private generateScriptTag;
+    private generateStylesheetTag;
+    private appendDependencies;
+    private buildDependencyTags;
+    private injectBeforeClosingTag;
+    setProcessedDependencies(processedDependencies: ProcessedAsset[]): void;
+    getProcessedDependencies(): ProcessedAsset[];
+    transform(res: Response): Promise<Response>;
+    private groupDependenciesByPosition;
+}

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

@@ -0,0 +1,163 @@
+import { appLogger } from "../global/app-logger.js";
+class HtmlTransformerService {
+  processedDependencies = [];
+  htmlRewriterConstructorPromise;
+  htmlRewriterMode = "auto";
+  constructor(options = {}) {
+    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) {
+    this.htmlRewriterMode = mode;
+    this.htmlRewriterConstructorPromise = void 0;
+  }
+  /**
+   * 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`.
+   */
+  async createHtmlRewriter() {
+    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`.
+   */
+  async resolveHtmlRewriterConstructor() {
+    if (!this.htmlRewriterConstructorPromise) {
+      const mode = this.htmlRewriterMode;
+      const RuntimeHtmlRewriter = globalThis.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).catch((error) => {
+          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;
+  }
+  formatAttributes(attrs) {
+    if (!attrs) return "";
+    return ` ${Object.entries(attrs).map(([key, value]) => `${key}="${value}"`).join(" ")}`;
+  }
+  generateScriptTag(dep) {
+    return dep.inline ? `<script${this.formatAttributes(dep.attributes)}>${dep.content}<\/script>` : `<script src="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}><\/script>`;
+  }
+  generateStylesheetTag(dep) {
+    return dep.inline ? `<style${this.formatAttributes(dep.attributes)}>${dep.content}</style>` : `<link rel="stylesheet" href="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}>`;
+  }
+  appendDependencies(element, dependencies) {
+    for (const dep of dependencies) {
+      const tag = dep.kind === "script" ? this.generateScriptTag(dep) : this.generateStylesheetTag(dep);
+      element.append(tag, { html: true });
+    }
+  }
+  buildDependencyTags(dependencies) {
+    return dependencies.map(
+      (dep) => dep.kind === "script" ? this.generateScriptTag(dep) : this.generateStylesheetTag(dep)
+    ).join("");
+  }
+  injectBeforeClosingTag(html, tag, content) {
+    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) {
+    this.processedDependencies = processedDependencies;
+  }
+  getProcessedDependencies() {
+    return this.processedDependencies;
+  }
+  async transform(res) {
+    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
+    });
+  }
+  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: [] }
+    );
+  }
+}
+export {
+  HtmlTransformerService
+};