@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.1

package/src/services/cache/index.d.ts

@@ -4,4 +4,6 @@
  */
 export type { CacheConfig, CacheEntry, CacheResult, CacheStats, CacheStore, CacheStrategy, RenderResult, } from './cache.types.js';
 export { MemoryCacheStore, type MemoryCacheStoreOptions } from './memory-cache-store.js';
+export { HtmlPageCacheDependencyIndex } from './html-page-cache-dependency-index.js';
 export { getCacheControlHeader, PageCacheService, type PageCacheServiceOptions } from './page-cache-service.js';
+export { clearAppPageCache, getAppPageCacheService, invalidateAppPageCacheBySourcePaths, registerAppPageCacheService, } from './page-cache-service.js';

package/src/services/cache/index.js

@@ -1,7 +1,8 @@
-import { MemoryCacheStore } from "./memory-cache-store.js";
-import { getCacheControlHeader, PageCacheService } from "./page-cache-service.js";
-export {
-  MemoryCacheStore,
-  PageCacheService,
-  getCacheControlHeader
-};
+/**
+ * Cache services exports
+ * @module
+ */
+export { MemoryCacheStore } from './memory-cache-store.js';
+export { HtmlPageCacheDependencyIndex } from './html-page-cache-dependency-index.js';
+export { getCacheControlHeader, PageCacheService } from './page-cache-service.js';
+export { clearAppPageCache, getAppPageCacheService, invalidateAppPageCacheBySourcePaths, registerAppPageCacheService, } from './page-cache-service.js';

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>;