npm - @ecopages/core - Versions diffs - 0.2.0-alpha.53 → 0.2.0-alpha.54 - Mend

@ecopages/core 0.2.0-alpha.53 → 0.2.0-alpha.54

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 (590) 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 ADDED Viewed

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

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');
+	});
+});