@ecopages/core 0.2.0-alpha.1

package/src/services/asset-processing-service/processors/stylesheet/file-stylesheet.processor.js

@@ -0,0 +1,63 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { BaseProcessor } from "../base/base-processor";
+class FileStylesheetProcessor extends BaseProcessor {
+  static PROCESSABLE_STYLESHEET_EXTENSIONS = /* @__PURE__ */ new Set([".css", ".scss", ".sass", ".less"]);
+  getStyleContent = (srcUrl) => {
+    return fileSystem.readFileAsBuffer(srcUrl);
+  };
+  isProcessableStylesheet(filepath) {
+    return FileStylesheetProcessor.PROCESSABLE_STYLESHEET_EXTENSIONS.has(path.extname(filepath));
+  }
+  async applyStylesheetProcessors(content, filepath) {
+    if (!this.isProcessableStylesheet(filepath)) {
+      return content;
+    }
+    let transformedContent = content;
+    for (const processor of this.appConfig.processors.values()) {
+      const hasCapabilities = processor.getAssetCapabilities().length > 0;
+      const canProcessStylesheet = processor.canProcessAsset("stylesheet", filepath);
+      if (!canProcessStylesheet && (hasCapabilities || !processor.getName().includes("postcss"))) {
+        continue;
+      }
+      if (!processor.matchesFileFilter(filepath)) {
+        continue;
+      }
+      const result = await processor.process(transformedContent, filepath);
+      if (typeof result === "string") {
+        transformedContent = result;
+        continue;
+      }
+      if (result instanceof Buffer) {
+        transformedContent = result.toString();
+      }
+    }
+    return transformedContent;
+  }
+  async process(dep) {
+    const buffer = this.getStyleContent(dep.filepath);
+    const rawContent = buffer.toString();
+    const processedContent = await this.applyStylesheetProcessors(rawContent, dep.filepath);
+    const hash = this.generateHash(processedContent);
+    const cachekey = this.buildCacheKey(dep.filepath, hash, dep);
+    return this.getOrProcess(cachekey, () => {
+      const filepath = path.join(this.getAssetsDir(), path.relative(this.appConfig.srcDir, dep.filepath));
+      const outputBuffer = Buffer.from(processedContent);
+      if (!dep.inline) {
+        fileSystem.ensureDir(path.dirname(filepath));
+        fileSystem.write(filepath, outputBuffer);
+      }
+      return {
+        filepath,
+        content: dep.inline ? processedContent : void 0,
+        kind: "stylesheet",
+        position: dep.position,
+        attributes: dep.attributes,
+        inline: dep.inline
+      };
+    });
+  }
+}
+export {
+  FileStylesheetProcessor
+};

package/src/services/asset-processing-service/processors/stylesheet/file-stylesheet.processor.ts

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import type { FileStylesheetAsset, ProcessedAsset } from '../../assets.types';
+import { BaseProcessor } from '../base/base-processor';
+
+export class FileStylesheetProcessor extends BaseProcessor<FileStylesheetAsset> {
+	private static readonly PROCESSABLE_STYLESHEET_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less']);
+
+	getStyleContent = (srcUrl: string): Buffer => {
+		return fileSystem.readFileAsBuffer(srcUrl);
+	};
+
+	private isProcessableStylesheet(filepath: string): boolean {
+		return FileStylesheetProcessor.PROCESSABLE_STYLESHEET_EXTENSIONS.has(path.extname(filepath));
+	}
+
+	private async applyStylesheetProcessors(content: string, filepath: string): Promise<string> {
+		if (!this.isProcessableStylesheet(filepath)) {
+			return content;
+		}
+
+		let transformedContent = content;
+
+		for (const processor of this.appConfig.processors.values()) {
+			const hasCapabilities = processor.getAssetCapabilities().length > 0;
+			const canProcessStylesheet = processor.canProcessAsset('stylesheet', filepath);
+
+			if (!canProcessStylesheet && (hasCapabilities || !processor.getName().includes('postcss'))) {
+				continue;
+			}
+
+			if (!processor.matchesFileFilter(filepath)) {
+				continue;
+			}
+
+			const result = await processor.process(transformedContent, filepath);
+
+			if (typeof result === 'string') {
+				transformedContent = result;
+				continue;
+			}
+
+			if (result instanceof Buffer) {
+				transformedContent = result.toString();
+			}
+		}
+
+		return transformedContent;
+	}
+
+	async process(dep: FileStylesheetAsset): Promise<ProcessedAsset> {
+		const buffer = this.getStyleContent(dep.filepath);
+		const rawContent = buffer.toString();
+		const processedContent = await this.applyStylesheetProcessors(rawContent, dep.filepath);
+		const hash = this.generateHash(processedContent);
+		const cachekey = this.buildCacheKey(dep.filepath, hash, dep);
+
+		return this.getOrProcess(cachekey, () => {
+			const filepath = path.join(this.getAssetsDir(), path.relative(this.appConfig.srcDir, dep.filepath));
+			const outputBuffer = Buffer.from(processedContent);
+
+			if (!dep.inline) {
+				fileSystem.ensureDir(path.dirname(filepath));
+				fileSystem.write(filepath, outputBuffer);
+			}
+
+			return {
+				filepath: filepath,
+				content: dep.inline ? processedContent : undefined,
+				kind: 'stylesheet',
+				position: dep.position,
+				attributes: dep.attributes,
+				inline: dep.inline,
+			};
+		});
+	}
+}

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

@@ -0,0 +1,107 @@
+/**
+ * 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/cache.types.ts

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

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

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

package/src/services/cache/index.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.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/memory-cache-store.ts

@@ -0,0 +1,130 @@
+/**
+ * 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,
+		};
+	}
+}