@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.40

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

@@ -1,98 +1,110 @@
-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);
+/**
+ * In-memory cache store with LRU eviction.
+ * Suitable for single-instance deployments and development.
+ * @module
+ */
+/**
+ * Simple in-memory cache store with LRU eviction.
+ * Uses Map insertion order for LRU tracking.
+ */
+export class MemoryCacheStore {
+    cache = new Map();
+    tagIndex = new Map();
+    maxEntries;
+    constructor(options = {}) {
+        this.maxEntries = options.maxEntries ?? 1000;
+    }
+    /**
+     * 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, new Set());
+            }
+            this.tagIndex.get(tag).add(key);
         }
-      }
-      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);
     }
-  }
-  /**
-   * 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);
-      }
+    async invalidateByTags(tags) {
+        let count = 0;
+        const keysToDelete = 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;
     }
-    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);
+    async invalidateByPaths(paths) {
+        let count = 0;
+        for (const path of paths) {
+            if (await this.delete(path))
+                count++;
         }
-      }
+        return count;
     }
-    for (const key of keysToDelete) {
-      if (await this.delete(key)) count++;
+    async clear() {
+        this.cache.clear();
+        this.tagIndex.clear();
     }
-    return count;
-  }
-  async invalidateByPaths(paths) {
-    let count = 0;
-    for (const path of paths) {
-      if (await this.delete(path)) count++;
+    async stats() {
+        return {
+            entries: this.cache.size,
+        };
     }
-    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

@@ -3,10 +3,13 @@
  * Handles stale-while-revalidate semantics and background regeneration.
  * @module
  */
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import type { CacheResult, CacheStore, CacheStrategy, RenderResult } from './cache.types.js';
+import { HtmlPageCacheDependencyIndex } from './html-page-cache-dependency-index.js';
 export interface PageCacheServiceOptions {
     store?: CacheStore;
     enabled?: boolean;
+    dependencyIndex?: HtmlPageCacheDependencyIndex;
 }
 /**
  * Core page caching service with ISR support.
@@ -14,7 +17,9 @@ export interface PageCacheServiceOptions {
 export declare class PageCacheService {
     private store;
     private enabled;
+    private readonly dependencyIndex;
     private regenerationPromises;
+    private missPromises;
     constructor(options?: PageCacheServiceOptions);
     /**
      * Generate a cache key from URL and optional params.
@@ -35,7 +40,11 @@ export declare class PageCacheService {
      * @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>;
+    getOrCreate(key: string, defaultStrategy: CacheStrategy, renderFn: () => Promise<RenderResult>, options?: {
+        sourceDependencyPaths?: readonly string[];
+    }): Promise<CacheResult>;
+    private resolveOrCreate;
+    private registerDependencyPaths;
     /**
      * Regenerate content in the background without blocking the response.
      * Uses promise deduplication to prevent multiple concurrent regenerations.
@@ -49,6 +58,11 @@ export declare class PageCacheService {
      * Invalidate cache entries by paths.
      */
     invalidateByPaths(paths: string[]): Promise<number>;
+    /**
+     * Invalidates cached HTML entries that registered the given source paths.
+     */
+    invalidateBySourceDependencyPaths(sourcePaths: readonly string[]): Promise<number>;
+    getDependencyIndex(): HtmlPageCacheDependencyIndex;
     /**
      * Clear all cached entries.
      */
@@ -68,3 +82,19 @@ export declare class PageCacheService {
  * Generate Cache-Control header value from cache strategy.
  */
 export declare function getCacheControlHeader(strategy: CacheStrategy | 'disabled'): string;
+/**
+ * Registers the page cache service for one app config instance.
+ */
+export declare function registerAppPageCacheService(appConfig: EcoPagesAppConfig, service: PageCacheService | null): void;
+/**
+ * Returns the registered page cache service for one app config, if any.
+ */
+export declare function getAppPageCacheService(appConfig: EcoPagesAppConfig): PageCacheService | null;
+/**
+ * Clears rendered HTML cache entries for one app during development invalidation.
+ */
+export declare function clearAppPageCache(appConfig: EcoPagesAppConfig): Promise<void>;
+/**
+ * Invalidates rendered HTML cache entries that depend on the given source paths.
+ */
+export declare function invalidateAppPageCacheBySourcePaths(appConfig: EcoPagesAppConfig, sourcePaths: readonly string[]): Promise<number>;

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

@@ -1,152 +1,239 @@
-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;
-  }
+/**
+ * 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';
+import { HtmlPageCacheDependencyIndex } from './html-page-cache-dependency-index.js';
+/**
+ * Core page caching service with ISR support.
+ */
+export class PageCacheService {
+    store;
+    enabled;
+    dependencyIndex;
+    regenerationPromises = new Map();
+    missPromises = new Map();
+    constructor(options = {}) {
+        this.store = options.store ?? new MemoryCacheStore();
+        this.enabled = options.enabled ?? true;
+        this.dependencyIndex = options.dependencyIndex ?? new HtmlPageCacheDependencyIndex();
+    }
+    /**
+     * 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 * 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, defaultStrategy, renderFn, options) {
+        if (!this.enabled) {
+            const { html, strategy } = await renderFn();
+            return { html, status: 'miss', strategy };
+        }
+        const pendingMiss = this.missPromises.get(key);
+        if (pendingMiss) {
+            return pendingMiss;
+        }
+        const missPromise = this.resolveOrCreate(key, defaultStrategy, renderFn, options).finally(() => {
+            this.missPromises.delete(key);
+        });
+        this.missPromises.set(key, missPromise);
+        return missPromise;
+    }
+    async resolveOrCreate(key, defaultStrategy, renderFn, options) {
+        const entry = await this.store.get(key);
+        if (!entry) {
+            const { html, strategy, sourceDependencyPaths } = 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);
+            this.registerDependencyPaths(key, options?.sourceDependencyPaths, sourceDependencyPaths);
+            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 };
+    }
+    registerDependencyPaths(key, initialPaths, renderedPaths) {
+        const mergedPaths = new Set();
+        for (const sourcePath of initialPaths ?? []) {
+            mergedPaths.add(sourcePath);
+        }
+        for (const sourcePath of renderedPaths ?? []) {
+            mergedPaths.add(sourcePath);
+        }
+        if (mergedPaths.size > 0) {
+            this.dependencyIndex.register(key, [...mergedPaths]);
+        }
+    }
+    /**
+     * 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, sourceDependencyPaths } = await renderFn();
+                const effectiveStrategy = strategy ?? fallbackStrategy;
+                const newEntry = this.createEntry(html, effectiveStrategy);
+                await this.store.set(key, newEntry);
+                this.registerDependencyPaths(key, undefined, sourceDependencyPaths);
+                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);
+    }
+    /**
+     * Invalidates cached HTML entries that registered the given source paths.
+     */
+    async invalidateBySourceDependencyPaths(sourcePaths) {
+        const cacheKeys = this.dependencyIndex.resolveCacheKeysForSourcePaths(sourcePaths);
+        let count = 0;
+        for (const cacheKey of cacheKeys) {
+            if (await this.store.delete(cacheKey)) {
+                count += 1;
+            }
+            this.dependencyIndex.unregister(cacheKey);
+        }
+        return count;
+    }
+    getDependencyIndex() {
+        return this.dependencyIndex;
+    }
+    /**
+     * Clear all cached entries.
+     */
+    async clear() {
+        this.dependencyIndex.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;
+    }
+}
+/**
+ * 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';
+}
+const pageCacheByAppConfig = new WeakMap();
+/**
+ * Registers the page cache service for one app config instance.
+ */
+export function registerAppPageCacheService(appConfig, service) {
+    if (service) {
+        pageCacheByAppConfig.set(appConfig, service);
+        return;
+    }
+    pageCacheByAppConfig.delete(appConfig);
+}
+/**
+ * Returns the registered page cache service for one app config, if any.
+ */
+export function getAppPageCacheService(appConfig) {
+    return pageCacheByAppConfig.get(appConfig) ?? null;
+}
+/**
+ * Clears rendered HTML cache entries for one app during development invalidation.
+ */
+export async function clearAppPageCache(appConfig) {
+    await getAppPageCacheService(appConfig)?.clear();
 }
-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";
+/**
+ * Invalidates rendered HTML cache entries that depend on the given source paths.
+ */
+export async function invalidateAppPageCacheBySourcePaths(appConfig, sourcePaths) {
+    return (await getAppPageCacheService(appConfig)?.invalidateBySourceDependencyPaths(sourcePaths)) ?? 0;
 }
-export {
-  PageCacheService,
-  getCacheControlHeader
-};