npm - @ecopages/core - Versions diffs - 0.2.0-alpha.26 → 0.2.0-alpha.27 - Mend

@ecopages/core 0.2.0-alpha.26 → 0.2.0-alpha.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (550) hide show

package/src/services/cache/page-cache-service.test.ts ADDED Viewed

@@ -0,0 +1,175 @@
+/**
+ * Unit tests for PageCacheService
+ */
+import { describe, expect, test, beforeEach, vi } from 'vitest';
+import { PageCacheService, getCacheControlHeader } from './page-cache-service.js';
+import { MemoryCacheStore } from './memory-cache-store.js';
+describe('PageCacheService', () => {
+	let service: PageCacheService;
+	let store: MemoryCacheStore;
+	beforeEach(() => {
+		store = new MemoryCacheStore();
+		service = new PageCacheService({ store });
+	});
+	describe('generateCacheKey', () => {
+		test('should use full URL as key', () => {
+			expect(service.generateCacheKey('/blog/post-1')).toBe('/blog/post-1');
+			expect(service.generateCacheKey('/search?q=test')).toBe('/search?q=test');
+		});
+	});
+	describe('getOrCreate', () => {
+		test('should return miss and render on cache miss', async () => {
+			const renderFn = vi.fn().mockResolvedValue({ html: '<html>hello</html>', strategy: 'static' as const });
+			const result = await service.getOrCreate('/page', 'static', renderFn);
+			expect(result.status).toBe('miss');
+			expect(result.html).toBe('<html>hello</html>');
+			expect(result.strategy).toBe('static');
+			expect(renderFn).toHaveBeenCalledTimes(1);
+		});
+		test('should return hit on cache hit', async () => {
+			const renderFn = vi.fn().mockResolvedValue({ html: '<html>hello</html>', strategy: 'static' as const });
+			await service.getOrCreate('/page', 'static', renderFn);
+			renderFn.mockClear();
+			const result = await service.getOrCreate('/page', 'static', renderFn);
+			expect(result.status).toBe('hit');
+			expect(result.html).toBe('<html>hello</html>');
+			expect(result.strategy).toBe('static');
+			expect(renderFn).not.toHaveBeenCalled();
+		});
+		test('should bypass cache for dynamic strategy', async () => {
+			const renderFn = vi.fn().mockResolvedValue({ html: '<html>hello</html>', strategy: 'dynamic' as const });
+			const result1 = await service.getOrCreate('/page', 'dynamic', renderFn);
+			const result2 = await service.getOrCreate('/page', 'dynamic', renderFn);
+			expect(result1.status).toBe('miss');
+			expect(result2.status).toBe('miss');
+			expect(renderFn).toHaveBeenCalledTimes(2);
+		});
+		test('should return stale when entry is past revalidation time', async () => {
+			const revalidateStrategy = { revalidate: 60 };
+			const renderFn = vi.fn().mockResolvedValue({ html: '<html>v1</html>', strategy: revalidateStrategy });
+			const staleEntry = {
+				html: '<html>stale</html>',
+				createdAt: Date.now() - 120000,
+				revalidateAfter: Date.now() - 60000,
+				tags: [],
+				strategy: revalidateStrategy,
+			};
+			await store.set('/stale-page', staleEntry);
+			const result = await service.getOrCreate('/stale-page', { revalidate: 60 }, renderFn);
+			expect(result.status).toBe('stale');
+			expect(result.html).toBe('<html>stale</html>');
+		});
+		test('should deduplicate concurrent regeneration requests', async () => {
+			let callCount = 0;
+			const renderFn = vi.fn().mockImplementation(async () => {
+				callCount++;
+				await new Promise((resolve) => setTimeout(resolve, 10));
+				return { html: `<html>v${callCount}</html>`, strategy: { revalidate: 60 } };
+			});
+			const staleEntry = {
+				html: '<html>stale</html>',
+				createdAt: Date.now() - 120000,
+				revalidateAfter: Date.now() - 60000,
+				tags: [],
+				strategy: { revalidate: 60 },
+			};
+			await store.set('/dedup-page', staleEntry);
+			const results = await Promise.all([
+				service.getOrCreate('/dedup-page', { revalidate: 60 }, renderFn),
+				service.getOrCreate('/dedup-page', { revalidate: 60 }, renderFn),
+				service.getOrCreate('/dedup-page', { revalidate: 60 }, renderFn),
+			]);
+			for (const result of results) {
+				expect(result.status).toBe('stale');
+				expect(result.html).toBe('<html>stale</html>');
+			}
+			await new Promise((resolve) => setTimeout(resolve, 50));
+			expect(renderFn).toHaveBeenCalledTimes(1);
+		});
+	});
+	describe('invalidation', () => {
+		test('should invalidate by tags', async () => {
+			const strategy = { revalidate: 3600, tags: ['blog'] };
+			const renderFn = vi.fn().mockResolvedValue({ html: '<html>hello</html>', strategy });
+			await service.getOrCreate('/blog/1', strategy, renderFn);
+			await service.getOrCreate('/blog/2', strategy, renderFn);
+			const count = await service.invalidateByTags(['blog']);
+			expect(count).toBe(2);
+			renderFn.mockClear();
+			const result = await service.getOrCreate('/blog/1', 'static', renderFn);
+			expect(result.status).toBe('miss');
+		});
+		test('should invalidate by paths', async () => {
+			const renderFn = vi.fn().mockResolvedValue({ html: '<html>hello</html>', strategy: 'static' as const });
+			await service.getOrCreate('/blog/1', 'static', renderFn);
+			const count = await service.invalidateByPaths(['/blog/1']);
+			expect(count).toBe(1);
+			renderFn.mockClear();
+			const result = await service.getOrCreate('/blog/1', 'static', renderFn);
+			expect(result.status).toBe('miss');
+		});
+	});
+	describe('disabled cache', () => {
+		test('should bypass cache when disabled', async () => {
+			const disabledService = new PageCacheService({ store, enabled: false });
+			const renderFn = vi.fn().mockResolvedValue({ html: '<html>hello</html>', strategy: 'static' as const });
+			const result1 = await disabledService.getOrCreate('/page', 'static', renderFn);
+			const result2 = await disabledService.getOrCreate('/page', 'static', renderFn);
+			expect(result1.status).toBe('miss');
+			expect(result2.status).toBe('miss');
+			expect(renderFn).toHaveBeenCalledTimes(2);
+		});
+	});
+});
+describe('getCacheControlHeader', () => {
+	test('should return immutable for static strategy', () => {
+		expect(getCacheControlHeader('static')).toBe('public, max-age=31536000, immutable');
+	});
+	test('should return no-store for dynamic strategy', () => {
+		expect(getCacheControlHeader('dynamic')).toBe('no-store, must-revalidate');
+	});
+	test('should return max-age and stale-while-revalidate for object strategy', () => {
+		expect(getCacheControlHeader({ revalidate: 3600 })).toBe('public, max-age=3600, stale-while-revalidate=7200');
+	});
+	test('should return no-store when disabled', () => {
+		expect(getCacheControlHeader('disabled')).toBe('no-store, must-revalidate');
+	});
+});

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

@@ -0,0 +1,202 @@
+/**
+ * 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/cache/page-request-cache-coordinator.service.test.ts ADDED Viewed

@@ -0,0 +1,79 @@
+import { describe, expect, it, vi } from 'vitest';
+import { PageRequestCacheCoordinator } from './page-request-cache-coordinator.service.ts';
+import type { PageCacheService } from './page-cache-service.js';
+describe('PageRequestCacheCoordinator', () => {
+	it('should build cache keys with query parameters', () => {
+		const service = new PageRequestCacheCoordinator(null, 'static');
+		expect(service.buildCacheKey({ pathname: '/blog' })).toBe('/blog');
+		expect(service.buildCacheKey({ pathname: '/blog', query: { page: '2', tag: 'eco' } })).toBe(
+			'/blog?page=2&tag=eco',
+		);
+	});
+	it('should bypass the cache service for dynamic pages', async () => {
+		const cacheService = {
+			getOrCreate: vi.fn(),
+		} as unknown as PageCacheService;
+		const renderFn = vi.fn(async () => ({
+			html: '<html><body>dynamic</body></html>',
+			strategy: 'dynamic' as const,
+		}));
+		const service = new PageRequestCacheCoordinator(cacheService, 'static');
+		const response = await service.render({
+			cacheKey: '/dynamic',
+			pageCacheStrategy: 'dynamic',
+			renderFn,
+		});
+		expect(await response.text()).toBe('<html><body>dynamic</body></html>');
+		expect(response.headers.get('X-Cache')).toBe('DISABLED');
+		expect(cacheService.getOrCreate).not.toHaveBeenCalled();
+		expect(renderFn).toHaveBeenCalledTimes(1);
+	});
+	it('should delegate cached rendering to the cache service', async () => {
+		const cacheService = {
+			getOrCreate: vi.fn(async () => ({
+				html: '<html><body>cached</body></html>',
+				strategy: { revalidate: 60 },
+				status: 'hit',
+			})),
+		} as unknown as PageCacheService;
+		const service = new PageRequestCacheCoordinator(cacheService, 'static');
+		const response = await service.render({
+			cacheKey: '/cached',
+			pageCacheStrategy: { revalidate: 60 },
+			renderFn: async () => ({
+				html: '<html><body>fresh</body></html>',
+				strategy: { revalidate: 60 },
+			}),
+		});
+		expect(await response.text()).toBe('<html><body>cached</body></html>');
+		expect(response.headers.get('X-Cache')).toBe('HIT');
+		expect(response.headers.get('Cache-Control')).toContain('max-age=60');
+		expect(cacheService.getOrCreate).toHaveBeenCalledWith('/cached', { revalidate: 60 }, expect.any(Function));
+	});
+	it('should normalize supported body types to strings', async () => {
+		const service = new PageRequestCacheCoordinator(null, 'static');
+		expect(await service.bodyToString('plain')).toBe('plain');
+		expect(await service.bodyToString(Buffer.from('buffered'))).toBe('buffered');
+		expect(await service.bodyToString(new Uint8Array([104, 101, 108, 108, 111]))).toBe('hello');
+		expect(
+			await service.bodyToString(
+				new ReadableStream({
+					start: (controller) => {
+						controller.enqueue(new TextEncoder().encode('streamed'));
+						controller.close();
+					},
+				}),
+			),
+		).toBe('streamed');
+	});
+});

package/src/services/cache/page-request-cache-coordinator.service.ts ADDED Viewed

@@ -0,0 +1,131 @@
+import { getCacheControlHeader, type PageCacheService } from './page-cache-service.ts';
+import type { CacheStrategy, RenderResult } from './cache.types.ts';
+type CacheStatus = 'hit' | 'miss' | 'stale' | 'expired' | 'disabled';
+/**
+ * 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 class PageRequestCacheCoordinator {
+	private cacheService: PageCacheService | null;
+	private defaultCacheStrategy: CacheStrategy;
+	constructor(cacheService: PageCacheService | null, defaultCacheStrategy: CacheStrategy) {
+		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: { pathname: string; query?: Record<string, string> }): string {
+		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: {
+		cacheKey: string;
+		pageCacheStrategy: CacheStrategy;
+		renderFn: () => Promise<RenderResult>;
+	}): Promise<Response> {
+		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(): PageCacheService | null {
+		return this.cacheService;
+	}
+	/**
+	 * Returns the default render strategy used when a page does not declare one.
+	 *
+	 * @returns Application-level fallback cache strategy.
+	 */
+	getDefaultCacheStrategy(): CacheStrategy {
+		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: unknown): Promise<string> {
+		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.
+	 */
+	private createCachedResponse(html: string, strategy: CacheStrategy, cacheStatus: CacheStatus): Response {
+		const headers: HeadersInit = {
+			'Content-Type': 'text/html',
+			'Cache-Control': getCacheControlHeader(cacheStatus === 'disabled' ? 'disabled' : strategy),
+			'X-Cache': cacheStatus.toUpperCase(),
+		};
+		return new Response(html, { headers });
+	}
+}