@ecopages/core 0.2.0-alpha.27 → 0.2.0-alpha.28

package/src/services/cache/memory-cache-store.d.ts

@@ -0,0 +1,42 @@
+/**
+ * In-memory cache store with LRU eviction.
+ * Suitable for single-instance deployments and development.
+ * @module
+ */
+import type { CacheEntry, CacheStats, CacheStore } from './cache.types.js';
+export interface MemoryCacheStoreOptions {
+    /** Maximum number of entries before LRU eviction. @default 1000 */
+    maxEntries?: number;
+}
+/**
+ * Simple in-memory cache store with LRU eviction.
+ * Uses Map insertion order for LRU tracking.
+ */
+export declare class MemoryCacheStore implements CacheStore {
+    private cache;
+    private tagIndex;
+    private readonly maxEntries;
+    constructor(options?: MemoryCacheStoreOptions);
+    /**
+     * Retrieve an entry by key.
+     * Uses Map's insertion order for LRU tracking - accessed entries are
+     * deleted and re-inserted to move them to the "most recently used" position.
+     */
+    get(key: string): Promise<CacheEntry | null>;
+    /**
+     * Store an entry, evicting the oldest if at capacity.
+     * When maxEntries is reached and a new key is added, the first key in
+     * the Map (oldest/least-recently-used) is evicted to make room.
+     * Updating an existing key refreshes its LRU position.
+     */
+    set(key: string, entry: CacheEntry): Promise<void>;
+    /**
+     * Delete an entry and clean up its tag index references.
+     * Removes empty tag sets to prevent memory leaks from accumulated tags.
+     */
+    delete(key: string): Promise<boolean>;
+    invalidateByTags(tags: string[]): Promise<number>;
+    invalidateByPaths(paths: string[]): Promise<number>;
+    clear(): Promise<void>;
+    stats(): Promise<CacheStats>;
+}

package/src/services/cache/memory-cache-store.js

@@ -0,0 +1,98 @@
+class MemoryCacheStore {
+  cache = /* @__PURE__ */ new Map();
+  tagIndex = /* @__PURE__ */ new Map();
+  maxEntries;
+  constructor(options = {}) {
+    this.maxEntries = options.maxEntries ?? 1e3;
+  }
+  /**
+   * Retrieve an entry by key.
+   * Uses Map's insertion order for LRU tracking - accessed entries are
+   * deleted and re-inserted to move them to the "most recently used" position.
+   */
+  async get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    return entry;
+  }
+  /**
+   * Store an entry, evicting the oldest if at capacity.
+   * When maxEntries is reached and a new key is added, the first key in
+   * the Map (oldest/least-recently-used) is evicted to make room.
+   * Updating an existing key refreshes its LRU position.
+   */
+  async set(key, entry) {
+    const existingEntry = this.cache.get(key);
+    if (existingEntry) {
+      for (const tag of existingEntry.tags) {
+        this.tagIndex.get(tag)?.delete(key);
+        if (this.tagIndex.get(tag)?.size === 0) {
+          this.tagIndex.delete(tag);
+        }
+      }
+      this.cache.delete(key);
+    } else if (this.cache.size >= this.maxEntries) {
+      const oldestKey = this.cache.keys().next().value;
+      if (oldestKey) await this.delete(oldestKey);
+    }
+    this.cache.set(key, entry);
+    for (const tag of entry.tags) {
+      if (!this.tagIndex.has(tag)) {
+        this.tagIndex.set(tag, /* @__PURE__ */ new Set());
+      }
+      this.tagIndex.get(tag).add(key);
+    }
+  }
+  /**
+   * Delete an entry and clean up its tag index references.
+   * Removes empty tag sets to prevent memory leaks from accumulated tags.
+   */
+  async delete(key) {
+    const entry = this.cache.get(key);
+    if (!entry) return false;
+    for (const tag of entry.tags) {
+      this.tagIndex.get(tag)?.delete(key);
+      if (this.tagIndex.get(tag)?.size === 0) {
+        this.tagIndex.delete(tag);
+      }
+    }
+    return this.cache.delete(key);
+  }
+  async invalidateByTags(tags) {
+    let count = 0;
+    const keysToDelete = /* @__PURE__ */ new Set();
+    for (const tag of tags) {
+      const keys = this.tagIndex.get(tag);
+      if (keys) {
+        for (const key of keys) {
+          keysToDelete.add(key);
+        }
+      }
+    }
+    for (const key of keysToDelete) {
+      if (await this.delete(key)) count++;
+    }
+    return count;
+  }
+  async invalidateByPaths(paths) {
+    let count = 0;
+    for (const path of paths) {
+      if (await this.delete(path)) count++;
+    }
+    return count;
+  }
+  async clear() {
+    this.cache.clear();
+    this.tagIndex.clear();
+  }
+  async stats() {
+    return {
+      entries: this.cache.size
+    };
+  }
+}
+export {
+  MemoryCacheStore
+};

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-request-cache-coordinator.service.d.ts

@@ -0,0 +1,75 @@
+import { type PageCacheService } from './page-cache-service.js';
+import type { CacheStrategy, RenderResult } from './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/cache/page-request-cache-coordinator.service.js

@@ -0,0 +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}`;
+    }
+    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
+};

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

@@ -0,0 +1,37 @@
+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 declare class DefaultHtmlRewriterProvider implements HtmlRewriterProvider {
+    private htmlRewriterConstructorPromise?;
+    private htmlRewriterMode;
+    private logger;
+    private getNativeHtmlRewriter;
+    private loadWorkerToolsHtmlRewriter;
+    constructor(options?: DefaultHtmlRewriterProviderOptions);
+    setMode(mode: HtmlRewriterMode): void;
+    createHtmlRewriter(): Promise<HtmlRewriterRuntime | null>;
+    private resolveHtmlRewriterConstructor;
+}

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

@@ -0,0 +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);
+        }
+      } else if (mode === "auto" && RuntimeHtmlRewriter) {
+        this.htmlRewriterConstructorPromise = Promise.resolve(RuntimeHtmlRewriter);
+      } else {
+        this.htmlRewriterConstructorPromise = this.loadWorkerToolsHtmlRewriter();
+      }
+    }
+    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;
+    }
+  }
+}
+export {
+  DefaultHtmlRewriterProvider
+};