@ecopages/core 0.2.0-beta.30 → 0.2.0-beta.32

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

@@ -1,152 +1,163 @@
-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 ?? [];
+/**
+ * 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 { MemoryCacheStore } from './memory-cache-store.js';
+/**
+ * Core page caching service with ISR support.
+ */
+export class PageCacheService {
+    store;
+    enabled;
+    regenerationPromises = new Map();
+    constructor(options = {}) {
+        this.store = options.store ?? new MemoryCacheStore();
+        this.enabled = options.enabled ?? true;
     }
-    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 };
+    /**
+     * Generate a cache key from URL and optional params.
+     * Uses full URL (path + query) as the key.
+     */
+    generateCacheKey(url) {
+        return url;
     }
-    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 };
+    /**
+     * Check if an entry is stale (past its revalidation time).
+     */
+    isStale(entry) {
+        if (entry.revalidateAfter === null)
+            return false;
+        return Date.now() > entry.revalidateAfter;
     }
-    if (!this.isStale(entry)) {
-      return { html: entry.html, status: "hit", strategy: entry.strategy };
+    /**
+     * 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 * 1000;
+            tags = strategy.tags ?? [];
+        }
+        return {
+            html,
+            createdAt: now,
+            revalidateAfter,
+            tags,
+            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;
+    /**
+     * 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;
     }
-    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";
+/**
+ * Generate Cache-Control header value from cache strategy.
+ */
+export 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-request-cache-coordinator.service.js

@@ -1,109 +1,109 @@
-import { getCacheControlHeader } from "./page-cache-service.js";
-class PageRequestCacheCoordinator {
-  cacheService;
-  defaultCacheStrategy;
-  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}`;
+import { getCacheControlHeader } from './page-cache-service.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 class PageRequestCacheCoordinator {
+    cacheService;
+    defaultCacheStrategy;
+    constructor(cacheService, defaultCacheStrategy) {
+        this.cacheService = cacheService;
+        this.defaultCacheStrategy = defaultCacheStrategy;
     }
-    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");
+    /**
+     * 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;
     }
-    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;
+    /**
+     * 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);
     }
-    if (Buffer.isBuffer(body)) {
-      return body.toString("utf-8");
+    /**
+     * Exposes the underlying cache service for invalidation and adapter plumbing.
+     *
+     * @returns Configured cache service or `null` when caching is disabled.
+     */
+    getCacheService() {
+        return this.cacheService;
     }
-    if (body instanceof ReadableStream) {
-      return new Response(body).text();
+    /**
+     * Returns the default render strategy used when a page does not declare one.
+     *
+     * @returns Application-level fallback cache strategy.
+     */
+    getDefaultCacheStrategy() {
+        return this.defaultCacheStrategy;
     }
-    if (body instanceof Uint8Array) {
-      return new TextDecoder().decode(body);
+    /**
+     * 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 });
     }
-    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
-};

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

@@ -1,68 +1,68 @@
-import { appLogger } from "../../global/app-logger.js";
-class DefaultHtmlRewriterProvider {
-  htmlRewriterConstructorPromise;
-  htmlRewriterMode;
-  logger;
-  getNativeHtmlRewriter;
-  loadWorkerToolsHtmlRewriter;
-  constructor(options = {}) {
-    this.htmlRewriterMode = options.mode ?? "auto";
-    this.logger = options.logger ?? appLogger;
-    this.getNativeHtmlRewriter = options.getNativeHtmlRewriter ?? (() => globalThis.HTMLRewriter);
-    this.loadWorkerToolsHtmlRewriter = options.loadWorkerToolsHtmlRewriter ?? loadWorkerToolsHtmlRewriter;
-  }
-  setMode(mode) {
-    this.htmlRewriterMode = mode;
-    this.htmlRewriterConstructorPromise = void 0;
-  }
-  async createHtmlRewriter() {
-    const RuntimeHtmlRewriter = await this.resolveHtmlRewriterConstructor();
-    return RuntimeHtmlRewriter ? new RuntimeHtmlRewriter() : null;
-  }
-  async resolveHtmlRewriterConstructor() {
-    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);
+import { appLogger } from '../../global/app-logger.js';
+export class DefaultHtmlRewriterProvider {
+    htmlRewriterConstructorPromise;
+    htmlRewriterMode;
+    logger;
+    getNativeHtmlRewriter;
+    loadWorkerToolsHtmlRewriter;
+    constructor(options = {}) {
+        this.htmlRewriterMode = options.mode ?? 'auto';
+        this.logger = options.logger ?? appLogger;
+        this.getNativeHtmlRewriter =
+            options.getNativeHtmlRewriter ??
+                (() => globalThis.HTMLRewriter);
+        this.loadWorkerToolsHtmlRewriter = options.loadWorkerToolsHtmlRewriter ?? loadWorkerToolsHtmlRewriter;
+    }
+    setMode(mode) {
+        this.htmlRewriterMode = mode;
+        this.htmlRewriterConstructorPromise = undefined;
+    }
+    async createHtmlRewriter() {
+        const RuntimeHtmlRewriter = await this.resolveHtmlRewriterConstructor();
+        return RuntimeHtmlRewriter ? new RuntimeHtmlRewriter() : null;
+    }
+    async resolveHtmlRewriterConstructor() {
+        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();
+            }
         }
-      } else if (mode === "auto" && RuntimeHtmlRewriter) {
-        this.htmlRewriterConstructorPromise = Promise.resolve(RuntimeHtmlRewriter);
-      } else {
-        this.htmlRewriterConstructorPromise = this.loadWorkerToolsHtmlRewriter();
-      }
+        return this.htmlRewriterConstructorPromise;
     }
-    return this.htmlRewriterConstructorPromise;
-  }
 }
 async function loadWorkerToolsHtmlRewriter() {
-  try {
-    const module = await import("@worker-tools/html-rewriter/base64");
-    return module.HTMLRewriter;
-  } catch (primaryError) {
     try {
-      const runtimeLocalModule = await import(
-        /* @vite-ignore */
-        new URL("../node_modules/@worker-tools/html-rewriter/base64.js", import.meta.url).href
-      );
-      return runtimeLocalModule.HTMLRewriter;
-    } 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;
+        const module = await import('@worker-tools/html-rewriter/base64');
+        return module.HTMLRewriter;
+    }
+    catch (primaryError) {
+        try {
+            const runtimeLocalModule = await import(
+            /* @vite-ignore */ new URL('../node_modules/@worker-tools/html-rewriter/base64.js', import.meta.url)
+                .href);
+            return runtimeLocalModule.HTMLRewriter;
+        }
+        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;
+        }
     }
-  }
 }
-export {
-  DefaultHtmlRewriterProvider
-};