npm - @ecopages/core - Versions diffs - 0.2.0-alpha.4 → 0.2.0-alpha.6 - Mend

@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.6

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 (418) hide show

package/src/services/cache/memory-cache-store.test.ts ADDED Viewed

@@ -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 CHANGED Viewed

@@ -4,7 +4,7 @@
  * @module
  */
-import type { CacheEntry, CacheStats, CacheStore } from './cache.types.ts';
+import type { CacheEntry, CacheStats, CacheStore } from './cache.types.js';
 export interface MemoryCacheStoreOptions {
 	/** Maximum number of entries before LRU eviction. @default 1000 */

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 CHANGED Viewed

@@ -4,9 +4,9 @@
  * @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';
+import { appLogger } from '../../global/app-logger.js';
+import type { CacheEntry, CacheResult, CacheStore, CacheStrategy, RenderResult } from './cache.types.js';
+import { MemoryCacheStore } from './memory-cache-store.js';
 export interface PageCacheServiceOptions {
 	store?: CacheStore;

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/{page-request-cache-coordinator.service.ts → cache/page-request-cache-coordinator.service.ts} RENAMED Viewed

@@ -1,5 +1,5 @@
-import { getCacheControlHeader, type PageCacheService } from './cache/page-cache-service.ts';
-import type { CacheStrategy, RenderResult } from './cache/cache.types.ts';
+import { getCacheControlHeader, type PageCacheService } from './page-cache-service.js';
+import type { CacheStrategy, RenderResult } from './cache.types.js';
 type CacheStatus = 'hit' | 'miss' | 'stale' | 'expired' | 'disabled';
@@ -11,10 +11,13 @@ type CacheStatus = 'hit' | 'miss' | 'stale' | 'expired' | 'disabled';
  * body normalization for cache storage, and final cache header generation.
  */
 export class PageRequestCacheCoordinator {
-	constructor(
-		private cacheService: PageCacheService | null,
-		private defaultCacheStrategy: CacheStrategy,
-	) {}
+	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.