@ecopages/core 0.2.0-alpha.52 → 0.2.0-alpha.54

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

@@ -1,107 +0,0 @@
-/**
- * Cache types and interfaces for page caching and ISR
- * @module
- */
-/**
- * Result from rendering a page, including HTML and cache strategy.
- */
-export interface RenderResult {
-    html: string;
-    strategy: CacheStrategy;
-}
-/**
- * Render strategy configuration for pages.
- * - `'static'`: Render once, cache indefinitely
- * - `'dynamic'`: No caching, render on every request
- * - `{ revalidate, tags }`: Cache with time-based revalidation and optional tags
- */
-export type CacheStrategy = 'static' | 'dynamic' | {
-    /** Seconds until cache is considered stale */
-    revalidate: number;
-    /** Tags for on-demand invalidation */
-    tags?: string[];
-};
-/**
- * Cache entry stored in the cache store.
- */
-export interface CacheEntry {
-    /** The rendered HTML content */
-    html: string;
-    /** Timestamp when the entry was created */
-    createdAt: number;
-    /** Timestamp when the entry should be revalidated (null = never stale) */
-    revalidateAfter: number | null;
-    /** Tags associated with this entry for invalidation */
-    tags: string[];
-    /** The cache strategy used (for generating headers on HIT) */
-    strategy: CacheStrategy;
-}
-/**
- * Cache statistics for debugging and monitoring.
- */
-export interface CacheStats {
-    /** Number of entries in the cache */
-    entries: number;
-    /** Memory usage in bytes (if available) */
-    memoryUsage?: number;
-    /** Cache hit rate (if tracked) */
-    hitRate?: number;
-}
-/**
- * Abstract interface for cache storage backends.
- * Implementations must handle serialization/deserialization internally.
- */
-export interface CacheStore {
-    /** Retrieve an entry by key */
-    get(key: string): Promise<CacheEntry | null>;
-    /** Store an entry */
-    set(key: string, entry: CacheEntry): Promise<void>;
-    /** Delete a specific entry */
-    delete(key: string): Promise<boolean>;
-    /** Delete all entries matching any of the provided tags */
-    invalidateByTags(tags: string[]): Promise<number>;
-    /** Delete entries by exact path */
-    invalidateByPaths(paths: string[]): Promise<number>;
-    /** Clear all entries */
-    clear(): Promise<void>;
-    /** Get cache statistics (optional, for debugging) */
-    stats?(): Promise<CacheStats>;
-}
-/**
- * Configuration for the cache system.
- */
-export interface CacheConfig {
-    /**
-     * Cache store implementation.
-     * @default 'memory'
-     */
-    store?: 'memory' | CacheStore;
-    /**
-     * Default cache strategy for pages that don't specify one.
-     * @default 'static'
-     */
-    defaultStrategy?: CacheStrategy;
-    /**
-     * Whether caching is enabled.
-     * Automatically disabled in dev mode unless explicitly set.
-     * @default true (production), false (development)
-     */
-    enabled?: boolean;
-    /**
-     * Maximum number of entries in the memory cache before LRU eviction.
-     * Only applies when using the built-in memory store.
-     * @default 1000
-     */
-    maxEntries?: number;
-}
-/**
- * Result of a cache lookup operation.
- */
-export interface CacheResult {
-    /** The cached HTML content */
-    html: string;
-    /** Cache status for X-Cache header */
-    status: 'hit' | 'miss' | 'stale';
-    /** The cache strategy (for generating Cache-Control headers) */
-    strategy: CacheStrategy;
-}

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

@@ -1,7 +0,0 @@
-/**
- * Cache services exports
- * @module
- */
-export type { CacheConfig, CacheEntry, CacheResult, CacheStats, CacheStore, CacheStrategy, RenderResult, } from './cache.types.js';
-export { MemoryCacheStore, type MemoryCacheStoreOptions } from './memory-cache-store.js';
-export { getCacheControlHeader, PageCacheService, type PageCacheServiceOptions } from './page-cache-service.js';

package/src/services/cache/index.js

@@ -1,7 +0,0 @@
-import { MemoryCacheStore } from "./memory-cache-store.js";
-import { getCacheControlHeader, PageCacheService } from "./page-cache-service.js";
-export {
-  MemoryCacheStore,
-  PageCacheService,
-  getCacheControlHeader
-};

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

@@ -1,42 +0,0 @@
-/**
- * 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

@@ -1,98 +0,0 @@
-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

@@ -1,70 +0,0 @@
-/**
- * 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

@@ -1,152 +0,0 @@
-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

@@ -1,75 +0,0 @@
-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

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