@ecopages/core 0.2.0-alpha.22 → 0.2.0-alpha.24

package/src/services/assets/browser-bundle.service.ts

@@ -0,0 +1,109 @@
+import type { BuildOptions, BuildResult, BuildTranspileProfile } from '../../build/build-adapter.ts';
+import type { EcoBuildPlugin } from '../../build/build-types.ts';
+import { getAppBrowserBuildPlugins, getAppBuildExecutor, getAppTranspileOptions } from '../../build/build-adapter.ts';
+import { mergeEcoBuildPlugins } from '../../build/build-manifest.ts';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+
+export type BrowserBundleOptions = {
+	entrypoints: string[];
+	outdir?: string;
+	outbase?: string;
+	naming?: string;
+	conditions?: string[];
+	define?: Record<string, string>;
+	minify?: boolean;
+	treeshaking?: boolean;
+	splitting?: boolean;
+	root?: string;
+	bundle?: boolean;
+	externalPackages?: boolean;
+	external?: string[];
+	plugins?: EcoBuildPlugin[];
+	[key: string]: unknown;
+	profile: BuildTranspileProfile;
+	excludeAppBuildPlugins?: string[];
+};
+
+type BrowserBundleGroupedOptions = {
+	outdir?: string;
+	outbase?: string;
+	naming?: string;
+	conditions?: string[];
+	define?: Record<string, string>;
+	minify?: boolean;
+	treeshaking?: boolean;
+	splitting?: boolean;
+	root?: string;
+	bundle?: boolean;
+	externalPackages?: boolean;
+	external?: string[];
+	plugins?: EcoBuildPlugin[];
+	[key: string]: unknown;
+	profile: BuildTranspileProfile;
+	excludeAppBuildPlugins?: string[];
+};
+
+export interface BrowserBundleExecutor {
+	bundle(options: BrowserBundleOptions): Promise<BuildResult>;
+}
+
+export type BrowserBundleGroupedEntry = {
+	entrypoint: string;
+	entryName: string;
+};
+
+/**
+ * App-owned boundary for browser-oriented bundle work.
+ *
+ * @remarks
+ * This service owns the shared browser transpile defaults and ensures browser
+ * builds always run through the app-owned executor rather than direct backend
+ * calls scattered across HMR and asset processing paths.
+ */
+export class BrowserBundleService implements BrowserBundleExecutor {
+	private readonly appConfig: EcoPagesAppConfig;
+
+	/**
+	 * Creates the browser bundle boundary for one finalized app instance.
+	 */
+	constructor(appConfig: EcoPagesAppConfig) {
+		this.appConfig = appConfig;
+	}
+
+	/**
+	 * Runs one browser-targeted build through the app-owned executor.
+	 *
+	 * @remarks
+	 * Browser defaults and app-owned browser build plugins are applied here so HMR
+	 * and runtime asset generation do not have to recreate that policy at each call
+	 * site.
+	 */
+	async bundle(options: BrowserBundleOptions): Promise<BuildResult> {
+		const { profile, excludeAppBuildPlugins, plugins, ...rawBuildOptions } = options;
+		const appBrowserPlugins = getAppBrowserBuildPlugins(this.appConfig);
+		const filteredAppBrowserPlugins =
+			excludeAppBuildPlugins && excludeAppBuildPlugins.length > 0
+				? appBrowserPlugins.filter((plugin) => !excludeAppBuildPlugins.includes(plugin.name))
+				: appBrowserPlugins;
+		const request: BuildOptions = {
+			...rawBuildOptions,
+			entrypoints: options.entrypoints,
+			...getAppTranspileOptions(this.appConfig, profile),
+			plugins: mergeEcoBuildPlugins(plugins, filteredAppBrowserPlugins),
+		};
+
+		return await getAppBuildExecutor(this.appConfig).build(request);
+	}
+
+	async bundleGroupedEntries(
+		entries: BrowserBundleGroupedEntry[],
+		options: BrowserBundleGroupedOptions,
+	): Promise<BuildResult> {
+		const request: BrowserBundleOptions = {
+			...options,
+			entrypoints: entries.map((entry) => entry.entrypoint),
+		};
+
+		return this.bundle(request);
+	}
+}

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.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.test.ts

@@ -0,0 +1,225 @@
+/**
+ * Unit tests for MemoryCacheStore
+ */
+
+import { describe, expect, test, beforeEach } from 'vitest';
+import { MemoryCacheStore } from './memory-cache-store.js';
+import type { CacheEntry } from './cache.types.js';
+
+function createEntry(overrides: Partial<CacheEntry> = {}): CacheEntry {
+	return {
+		html: '<html>test</html>',
+		createdAt: Date.now(),
+		revalidateAfter: null,
+		tags: [],
+		strategy: 'static',
+		...overrides,
+	};
+}
+
+describe('MemoryCacheStore', () => {
+	let store: MemoryCacheStore;
+
+	beforeEach(() => {
+		store = new MemoryCacheStore();
+	});
+
+	describe('get/set', () => {
+		test('should return null for cache miss', async () => {
+			const result = await store.get('/nonexistent');
+			expect(result).toBeNull();
+		});
+
+		test('should store and retrieve an entry', async () => {
+			const entry = createEntry({ html: '<html>hello</html>' });
+			await store.set('/page', entry);
+			const result = await store.get('/page');
+			expect(result?.html).toBe('<html>hello</html>');
+		});
+
+		test('should update existing entry', async () => {
+			await store.set('/page', createEntry({ html: '<html>v1</html>' }));
+			await store.set('/page', createEntry({ html: '<html>v2</html>' }));
+			const result = await store.get('/page');
+			expect(result?.html).toBe('<html>v2</html>');
+		});
+	});
+
+	describe('LRU eviction', () => {
+		test('should evict oldest entry when maxEntries reached', async () => {
+			const smallStore = new MemoryCacheStore({ maxEntries: 3 });
+
+			await smallStore.set('/page1', createEntry());
+			await smallStore.set('/page2', createEntry());
+			await smallStore.set('/page3', createEntry());
+
+			await smallStore.set('/page4', createEntry());
+
+			expect(await smallStore.get('/page1')).toBeNull();
+			expect(await smallStore.get('/page2')).not.toBeNull();
+			expect(await smallStore.get('/page3')).not.toBeNull();
+			expect(await smallStore.get('/page4')).not.toBeNull();
+		});
+
+		test('should refresh entry position on access', async () => {
+			const smallStore = new MemoryCacheStore({ maxEntries: 3 });
+
+			await smallStore.set('/page1', createEntry());
+			await smallStore.set('/page2', createEntry());
+			await smallStore.set('/page3', createEntry());
+
+			await smallStore.get('/page1');
+
+			await smallStore.set('/page4', createEntry());
+
+			expect(await smallStore.get('/page1')).not.toBeNull();
+			expect(await smallStore.get('/page2')).toBeNull();
+			expect(await smallStore.get('/page3')).not.toBeNull();
+			expect(await smallStore.get('/page4')).not.toBeNull();
+		});
+
+		test('should not evict when updating existing key', async () => {
+			const smallStore = new MemoryCacheStore({ maxEntries: 3 });
+
+			await smallStore.set('/page1', createEntry());
+			await smallStore.set('/page2', createEntry());
+			await smallStore.set('/page3', createEntry());
+
+			await smallStore.set('/page1', createEntry({ html: '<html>updated</html>' }));
+
+			const stats = await smallStore.stats();
+			expect(stats.entries).toBe(3);
+			expect((await smallStore.get('/page1'))?.html).toBe('<html>updated</html>');
+		});
+
+		test('should refresh entry position on update (move to most recent)', async () => {
+			const smallStore = new MemoryCacheStore({ maxEntries: 3 });
+
+			await smallStore.set('/page1', createEntry({ html: '<html>v1</html>' }));
+			await smallStore.set('/page2', createEntry());
+			await smallStore.set('/page3', createEntry());
+
+			await smallStore.set('/page1', createEntry({ html: '<html>v2</html>' }));
+
+			await smallStore.set('/page4', createEntry());
+
+			expect(await smallStore.get('/page1')).not.toBeNull();
+			expect(await smallStore.get('/page2')).toBeNull();
+			expect(await smallStore.get('/page3')).not.toBeNull();
+			expect(await smallStore.get('/page4')).not.toBeNull();
+		});
+	});
+
+	describe('delete', () => {
+		test('should delete an entry', async () => {
+			await store.set('/page', createEntry());
+			const deleted = await store.delete('/page');
+			expect(deleted).toBe(true);
+			expect(await store.get('/page')).toBeNull();
+		});
+
+		test('should return false for non-existent entry', async () => {
+			const deleted = await store.delete('/nonexistent');
+			expect(deleted).toBe(false);
+		});
+	});
+
+	describe('invalidateByTags', () => {
+		test('should invalidate all entries with matching tag', async () => {
+			await store.set('/blog/1', createEntry({ tags: ['blog'] }));
+			await store.set('/blog/2', createEntry({ tags: ['blog'] }));
+			await store.set('/about', createEntry({ tags: ['static'] }));
+
+			const count = await store.invalidateByTags(['blog']);
+			expect(count).toBe(2);
+			expect(await store.get('/blog/1')).toBeNull();
+			expect(await store.get('/blog/2')).toBeNull();
+			expect(await store.get('/about')).not.toBeNull();
+		});
+
+		test('should handle multiple tags', async () => {
+			await store.set('/blog/1', createEntry({ tags: ['blog', 'featured'] }));
+			await store.set('/product/1', createEntry({ tags: ['product'] }));
+
+			const count = await store.invalidateByTags(['blog', 'product']);
+			expect(count).toBe(2);
+		});
+
+		test('should return 0 for non-matching tags', async () => {
+			await store.set('/page', createEntry({ tags: ['blog'] }));
+			const count = await store.invalidateByTags(['nonexistent']);
+			expect(count).toBe(0);
+		});
+
+		test('should clean up all tag references when entry has multiple tags', async () => {
+			await store.set('/blog/featured', createEntry({ tags: ['blog', 'featured', 'homepage'] }));
+			await store.set('/blog/regular', createEntry({ tags: ['blog'] }));
+			await store.set('/featured-product', createEntry({ tags: ['featured', 'product'] }));
+
+			const count = await store.invalidateByTags(['blog']);
+			expect(count).toBe(2);
+
+			expect(await store.get('/blog/featured')).toBeNull();
+			expect(await store.get('/blog/regular')).toBeNull();
+			expect(await store.get('/featured-product')).not.toBeNull();
+
+			const countFeatured = await store.invalidateByTags(['featured']);
+			expect(countFeatured).toBe(1);
+			expect(await store.get('/featured-product')).toBeNull();
+		});
+
+		test('should not leave orphaned tag references after invalidation', async () => {
+			await store.set('/page1', createEntry({ tags: ['tagA', 'tagB'] }));
+
+			await store.invalidateByTags(['tagA']);
+
+			expect(await store.get('/page1')).toBeNull();
+
+			await store.set('/page2', createEntry({ tags: ['tagB'] }));
+			const count = await store.invalidateByTags(['tagB']);
+			expect(count).toBe(1);
+		});
+	});
+
+	describe('invalidateByPaths', () => {
+		test('should invalidate specific paths', async () => {
+			await store.set('/blog/1', createEntry());
+			await store.set('/blog/2', createEntry());
+
+			const count = await store.invalidateByPaths(['/blog/1']);
+			expect(count).toBe(1);
+			expect(await store.get('/blog/1')).toBeNull();
+			expect(await store.get('/blog/2')).not.toBeNull();
+		});
+
+		test('should handle multiple paths', async () => {
+			await store.set('/blog/1', createEntry());
+			await store.set('/blog/2', createEntry());
+			await store.set('/about', createEntry());
+
+			const count = await store.invalidateByPaths(['/blog/1', '/about']);
+			expect(count).toBe(2);
+		});
+	});
+
+	describe('clear', () => {
+		test('should remove all entries', async () => {
+			await store.set('/page1', createEntry());
+			await store.set('/page2', createEntry());
+			await store.clear();
+
+			const stats = await store.stats();
+			expect(stats.entries).toBe(0);
+		});
+	});
+
+	describe('stats', () => {
+		test('should return entry count', async () => {
+			await store.set('/page1', createEntry());
+			await store.set('/page2', createEntry());
+
+			const stats = await store.stats();
+			expect(stats.entries).toBe(2);
+		});
+	});
+});

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,
+		};
+	}
+}