@ecopages/core 0.2.0-alpha.1 → 0.2.0-alpha.11

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

@@ -1,126 +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.ts

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

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

@@ -1,130 +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.ts';
-
-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 class MemoryCacheStore implements CacheStore {
-	private cache = new Map<string, CacheEntry>();
-	private tagIndex = new Map<string, Set<string>>();
-	private readonly maxEntries: number;
-
-	constructor(options: MemoryCacheStoreOptions = {}) {
-		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: string): Promise<CacheEntry | null> {
-		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: string, entry: CacheEntry): Promise<void> {
-		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);
-		}
-	}
-
-	/**
-	 * Delete an entry and clean up its tag index references.
-	 * Removes empty tag sets to prevent memory leaks from accumulated tags.
-	 */
-	async delete(key: string): Promise<boolean> {
-		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: string[]): Promise<number> {
-		let count = 0;
-		const keysToDelete = new Set<string>();
-
-		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: string[]): Promise<number> {
-		let count = 0;
-		for (const path of paths) {
-			if (await this.delete(path)) count++;
-		}
-		return count;
-	}
-
-	async clear(): Promise<void> {
-		this.cache.clear();
-		this.tagIndex.clear();
-	}
-
-	async stats(): Promise<CacheStats> {
-		return {
-			entries: this.cache.size,
-		};
-	}
-}

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

@@ -1,202 +0,0 @@
-/**
- * Page cache service with ISR (Incremental Static Regeneration) support.
- * Handles stale-while-revalidate semantics and background regeneration.
- * @module
- */
-
-import { appLogger } from '../../global/app-logger.ts';
-import type { CacheEntry, CacheResult, CacheStore, CacheStrategy, RenderResult } from './cache.types.ts';
-import { MemoryCacheStore } from './memory-cache-store.ts';
-
-export interface PageCacheServiceOptions {
-	store?: CacheStore;
-	enabled?: boolean;
-}
-
-/**
- * Core page caching service with ISR support.
- */
-export class PageCacheService {
-	private store: CacheStore;
-	private enabled: boolean;
-	private regenerationPromises = new Map<string, Promise<string>>();
-
-	constructor(options: PageCacheServiceOptions = {}) {
-		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: string): string {
-		return url;
-	}
-
-	/**
-	 * Check if an entry is stale (past its revalidation time).
-	 */
-	private isStale(entry: CacheEntry): boolean {
-		if (entry.revalidateAfter === null) return false;
-		return Date.now() > entry.revalidateAfter;
-	}
-
-	/**
-	 * Create a cache entry from rendered HTML.
-	 */
-	private createEntry(html: string, strategy: CacheStrategy): CacheEntry {
-		const now = Date.now();
-
-		let revalidateAfter: number | null = null;
-		let tags: string[] = [];
-
-		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: string,
-		defaultStrategy: CacheStrategy,
-		renderFn: () => Promise<RenderResult>,
-	): Promise<CacheResult> {
-		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.
-	 */
-	private regenerateInBackground(
-		key: string,
-		fallbackStrategy: CacheStrategy,
-		renderFn: () => Promise<{ html: string; strategy: CacheStrategy }>,
-	): void {
-		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: string[]): Promise<number> {
-		return this.store.invalidateByTags(tags);
-	}
-
-	/**
-	 * Invalidate cache entries by paths.
-	 */
-	async invalidateByPaths(paths: string[]): Promise<number> {
-		return this.store.invalidateByPaths(paths);
-	}
-
-	/**
-	 * Clear all cached entries.
-	 */
-	async clear(): Promise<void> {
-		return this.store.clear();
-	}
-
-	/**
-	 * Get cache statistics.
-	 */
-	async stats() {
-		return this.store.stats?.() ?? { entries: 0 };
-	}
-
-	/**
-	 * Get the underlying cache store.
-	 */
-	getStore(): CacheStore {
-		return this.store;
-	}
-}
-
-/**
- * Generate Cache-Control header value from cache strategy.
- */
-export function getCacheControlHeader(strategy: CacheStrategy | 'disabled'): string {
-	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';
-}

package/src/services/html-transformer.service.d.ts

@@ -1,50 +0,0 @@
-import type { ProcessedAsset } from './asset-processing-service/assets.types';
-export type HtmlRewriterMode = 'auto' | 'native' | 'worker-tools' | 'fallback';
-export interface HtmlTransformerServiceOptions {
-    htmlRewriterMode?: HtmlRewriterMode;
-}
-export declare class HtmlTransformerService {
-    private processedDependencies;
-    private htmlRewriterConstructorPromise?;
-    private htmlRewriterMode;
-    constructor(options?: HtmlTransformerServiceOptions);
-    /**
-     * Overrides the HTML rewriter runtime selection.
-     *
-     * This is intended for internal/runtime tests that need deterministic
-     * selection between native, worker-tools, and string fallback behavior.
-     *
-     * @param mode Requested runtime selection strategy.
-     */
-    setHtmlRewriterMode(mode: HtmlRewriterMode): void;
-    /**
-     * Creates an HTML rewriter instance from the best available runtime.
-     *
-     * Resolution order is:
-     * 1. native `globalThis.HTMLRewriter`
-     * 2. `@worker-tools/html-rewriter/base64`
-     * 3. `null`, which triggers the string-based fallback path
-     *
-     * @returns HTML rewriter instance when available; otherwise `null`.
-     */
-    private createHtmlRewriter;
-    /**
-     * Resolves the constructor used for HTML rewriting.
-     *
-     * The worker-tools fallback is loaded lazily so native runtimes avoid the WASM
-     * dependency cost unless it is actually needed.
-     *
-     * @returns Rewriter constructor when available; otherwise `null`.
-     */
-    private resolveHtmlRewriterConstructor;
-    private formatAttributes;
-    private generateScriptTag;
-    private generateStylesheetTag;
-    private appendDependencies;
-    private buildDependencyTags;
-    private injectBeforeClosingTag;
-    setProcessedDependencies(processedDependencies: ProcessedAsset[]): void;
-    getProcessedDependencies(): ProcessedAsset[];
-    transform(res: Response): Promise<Response>;
-    private groupDependenciesByPosition;
-}

package/src/services/html-transformer.service.js

@@ -1,163 +0,0 @@
-import { appLogger } from "../global/app-logger.js";
-class HtmlTransformerService {
-  processedDependencies = [];
-  htmlRewriterConstructorPromise;
-  htmlRewriterMode = "auto";
-  constructor(options = {}) {
-    this.setHtmlRewriterMode(options.htmlRewriterMode ?? "auto");
-  }
-  /**
-   * Overrides the HTML rewriter runtime selection.
-   *
-   * This is intended for internal/runtime tests that need deterministic
-   * selection between native, worker-tools, and string fallback behavior.
-   *
-   * @param mode Requested runtime selection strategy.
-   */
-  setHtmlRewriterMode(mode) {
-    this.htmlRewriterMode = mode;
-    this.htmlRewriterConstructorPromise = void 0;
-  }
-  /**
-   * Creates an HTML rewriter instance from the best available runtime.
-   *
-   * Resolution order is:
-   * 1. native `globalThis.HTMLRewriter`
-   * 2. `@worker-tools/html-rewriter/base64`
-   * 3. `null`, which triggers the string-based fallback path
-   *
-   * @returns HTML rewriter instance when available; otherwise `null`.
-   */
-  async createHtmlRewriter() {
-    const RuntimeHtmlRewriter = await this.resolveHtmlRewriterConstructor();
-    return RuntimeHtmlRewriter ? new RuntimeHtmlRewriter() : null;
-  }
-  /**
-   * Resolves the constructor used for HTML rewriting.
-   *
-   * The worker-tools fallback is loaded lazily so native runtimes avoid the WASM
-   * dependency cost unless it is actually needed.
-   *
-   * @returns Rewriter constructor when available; otherwise `null`.
-   */
-  async resolveHtmlRewriterConstructor() {
-    if (!this.htmlRewriterConstructorPromise) {
-      const mode = this.htmlRewriterMode;
-      const RuntimeHtmlRewriter = globalThis.HTMLRewriter;
-      if (mode === "fallback") {
-        this.htmlRewriterConstructorPromise = Promise.resolve(null);
-      } else if (mode === "native") {
-        if (RuntimeHtmlRewriter) {
-          this.htmlRewriterConstructorPromise = Promise.resolve(RuntimeHtmlRewriter);
-        } else {
-          appLogger.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 = import("@worker-tools/html-rewriter/base64").then((module) => module.HTMLRewriter).catch((error) => {
-          const message = error instanceof Error ? error.message : String(error);
-          appLogger.warn(
-            `[HtmlTransformerService] Failed to load @worker-tools/html-rewriter/base64, falling back to string injection: ${message}`
-          );
-          return null;
-        });
-      }
-    }
-    return this.htmlRewriterConstructorPromise;
-  }
-  formatAttributes(attrs) {
-    if (!attrs) return "";
-    return ` ${Object.entries(attrs).map(([key, value]) => `${key}="${value}"`).join(" ")}`;
-  }
-  generateScriptTag(dep) {
-    return dep.inline ? `<script${this.formatAttributes(dep.attributes)}>${dep.content}<\/script>` : `<script src="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}><\/script>`;
-  }
-  generateStylesheetTag(dep) {
-    return dep.inline ? `<style${this.formatAttributes(dep.attributes)}>${dep.content}</style>` : `<link rel="stylesheet" href="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}>`;
-  }
-  appendDependencies(element, dependencies) {
-    for (const dep of dependencies) {
-      const tag = dep.kind === "script" ? this.generateScriptTag(dep) : this.generateStylesheetTag(dep);
-      element.append(tag, { html: true });
-    }
-  }
-  buildDependencyTags(dependencies) {
-    return dependencies.map(
-      (dep) => dep.kind === "script" ? this.generateScriptTag(dep) : this.generateStylesheetTag(dep)
-    ).join("");
-  }
-  injectBeforeClosingTag(html, tag, content) {
-    if (!content) {
-      return html;
-    }
-    const closingTag = `</${tag}>`;
-    const lowerHtml = html.toLowerCase();
-    const closingTagIndex = lowerHtml.lastIndexOf(closingTag);
-    if (closingTagIndex !== -1) {
-      return `${html.slice(0, closingTagIndex)}${content}${html.slice(closingTagIndex)}`;
-    }
-    if (tag === "head") {
-      return `${content}${html}`;
-    }
-    return `${html}${content}`;
-  }
-  setProcessedDependencies(processedDependencies) {
-    this.processedDependencies = processedDependencies;
-  }
-  getProcessedDependencies() {
-    return this.processedDependencies;
-  }
-  async transform(res) {
-    const { head, body } = this.groupDependenciesByPosition();
-    const htmlRewriter = await this.createHtmlRewriter();
-    const html = await res.text();
-    const headers = new Headers(res.headers);
-    if (htmlRewriter) {
-      htmlRewriter.on("head", {
-        element: (element) => this.appendDependencies(element, head)
-      }).on("body", {
-        element: (element) => this.appendDependencies(element, body)
-      });
-      return htmlRewriter.transform(
-        new Response(html, {
-          headers,
-          status: res.status,
-          statusText: res.statusText
-        })
-      );
-    }
-    const withHeadDependencies = this.injectBeforeClosingTag(html, "head", this.buildDependencyTags(head));
-    const transformedHtml = this.injectBeforeClosingTag(
-      withHeadDependencies,
-      "body",
-      this.buildDependencyTags(body)
-    );
-    return new Response(transformedHtml, {
-      headers,
-      status: res.status,
-      statusText: res.statusText
-    });
-  }
-  groupDependenciesByPosition() {
-    return this.processedDependencies.reduce(
-      (acc, dep) => {
-        if (dep.kind === "script") {
-          if (dep.excludeFromHtml) return acc;
-          const position = dep.position || "body";
-          acc[position].push(dep);
-        } else if (dep.kind === "stylesheet") {
-          acc.head.push(dep);
-        }
-        return acc;
-      },
-      { head: [], body: [] }
-    );
-  }
-}
-export {
-  HtmlTransformerService
-};