@geekmidas/cache 10.0.0-alpha.99 → 10.0.0

package/src/__tests__/cache.spec.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from 'vitest';
+import type { Cache } from '../';
+import { getExpirationInSeconds } from '../';
+import { InMemoryCache } from '../memory';
+import { UpstashCache } from '../upstash';
+
+describe('Cache Interface', () => {
+	describe('interface compliance', () => {
+		it('InMemoryCache should implement Cache interface', () => {
+			const cache: Cache = new InMemoryCache();
+
+			expect(typeof cache.get).toBe('function');
+			expect(typeof cache.set).toBe('function');
+			expect(typeof cache.delete).toBe('function');
+		});
+
+		it('UpstashCache should implement Cache interface', () => {
+			const cache: Cache = new UpstashCache(
+				'http://localhost:8079',
+				'example_token',
+			);
+
+			expect(typeof cache.get).toBe('function');
+			expect(typeof cache.set).toBe('function');
+			expect(typeof cache.delete).toBe('function');
+		});
+	});
+
+	describe('method signatures', () => {
+		it('should have correct get method signature', () => {
+			const cache: Cache = new InMemoryCache();
+
+			// These should compile without errors
+			const getResult: Promise<unknown> = cache.get('test');
+			expect(getResult).toBeInstanceOf(Promise);
+		});
+
+		it('should have correct set method signature', () => {
+			const cache: Cache = new InMemoryCache();
+
+			// These should compile without errors
+			const setResult: Promise<void> = cache.set('test', 'value');
+			expect(setResult).toBeInstanceOf(Promise);
+		});
+
+		it('should have correct delete method signature', () => {
+			const cache: Cache = new InMemoryCache();
+
+			// These should compile without errors
+			const deleteResult: Promise<void> = cache.delete('test');
+			expect(deleteResult).toBeInstanceOf(Promise);
+		});
+	});
+
+	describe('function-level generic type support', () => {
+		it('should support string types with function-level generics', async () => {
+			const cache: Cache = new InMemoryCache();
+
+			await cache.set<string>('key', 'value');
+			const result = await cache.get<string>('key');
+
+			expect(typeof result === 'string' || result === undefined).toBe(true);
+		});
+
+		it('should support number types with function-level generics', async () => {
+			const cache: Cache = new InMemoryCache();
+
+			await cache.set<number>('key', 42);
+			const result = await cache.get<number>('key');
+
+			expect(typeof result === 'number' || result === undefined).toBe(true);
+		});
+
+		it('should support object types with function-level generics', async () => {
+			interface User {
+				id: number;
+				name: string;
+			}
+
+			const cache: Cache = new InMemoryCache();
+			const user: User = { id: 1, name: 'John' };
+
+			await cache.set<User>('user', user);
+			const result = await cache.get<User>('user');
+
+			expect(
+				result === undefined ||
+					(typeof result === 'object' && 'id' in result && 'name' in result),
+			).toBe(true);
+		});
+
+		it('should support mixed types in same cache instance', async () => {
+			const cache: Cache = new InMemoryCache();
+
+			await cache.set<string>('string', 'text');
+			await cache.set<number>('number', 42);
+			await cache.set<boolean>('boolean', true);
+
+			const stringResult = await cache.get<string>('string');
+			const numberResult = await cache.get<number>('number');
+			const booleanResult = await cache.get<boolean>('boolean');
+
+			expect(stringResult).toBe('text');
+			expect(numberResult).toBe(42);
+			expect(booleanResult).toBe(true);
+		});
+	});
+});
+
+describe('getExpirationInSeconds', () => {
+	it('should return 0 for null', () => {
+		expect(getExpirationInSeconds(null)).toBe(0);
+	});
+
+	it('should return 0 for undefined', () => {
+		expect(getExpirationInSeconds(undefined)).toBe(0);
+	});
+
+	it('should return positive seconds for future date', () => {
+		const futureDate = new Date(Date.now() + 60000); // 1 minute in the future
+		const seconds = getExpirationInSeconds(futureDate);
+		expect(seconds).toBeGreaterThan(0);
+		expect(seconds).toBeLessThanOrEqual(60);
+	});
+
+	it('should return 0 for past date', () => {
+		const pastDate = new Date(Date.now() - 60000); // 1 minute in the past
+		expect(getExpirationInSeconds(pastDate)).toBe(0);
+	});
+
+	it('should handle ISO string dates', () => {
+		const futureDate = new Date(Date.now() + 120000).toISOString(); // 2 minutes in the future
+		const seconds = getExpirationInSeconds(futureDate);
+		expect(seconds).toBeGreaterThan(0);
+		expect(seconds).toBeLessThanOrEqual(120);
+	});
+
+	it('should handle timestamp numbers', () => {
+		const futureTimestamp = Date.now() + 30000; // 30 seconds in the future
+		const seconds = getExpirationInSeconds(futureTimestamp);
+		expect(seconds).toBeGreaterThan(0);
+		expect(seconds).toBeLessThanOrEqual(30);
+	});
+});

package/src/__tests__/file.spec.ts

@@ -0,0 +1,192 @@
+import { existsSync } from 'node:fs';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { FileCache } from '../file';
+
+describe('FileCache', () => {
+	let dir: string;
+	let cachePath: string;
+
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), 'file-cache-test-'));
+		cachePath = join(dir, 'cache.json');
+	});
+
+	afterEach(async () => {
+		vi.useRealTimers();
+		await rm(dir, { recursive: true, force: true });
+	});
+
+	describe('get', () => {
+		it('should return undefined for non-existent key', async () => {
+			const cache = new FileCache({ path: cachePath });
+			const result = await cache.get('non-existent');
+			expect(result).toBeUndefined();
+		});
+
+		it('should return undefined when file does not exist', async () => {
+			const cache = new FileCache({
+				path: join(dir, 'subdir', 'cache.json'),
+			});
+			const result = await cache.get('any-key');
+			expect(result).toBeUndefined();
+		});
+
+		it('should return stored value', async () => {
+			const cache = new FileCache({ path: cachePath });
+			await cache.set('key', 'hello');
+			const result = await cache.get('key');
+			expect(result).toBe('hello');
+		});
+
+		it('should handle different data types', async () => {
+			const cache = new FileCache({ path: cachePath });
+
+			await cache.set('string', 'value');
+			await cache.set('number', 42);
+			await cache.set('boolean', true);
+			await cache.set('object', { id: 1, name: 'test' });
+			await cache.set('array', [1, 2, 3]);
+			await cache.set('null', null);
+
+			expect(await cache.get('string')).toBe('value');
+			expect(await cache.get('number')).toBe(42);
+			expect(await cache.get('boolean')).toBe(true);
+			expect(await cache.get('object')).toEqual({ id: 1, name: 'test' });
+			expect(await cache.get('array')).toEqual([1, 2, 3]);
+			expect(await cache.get('null')).toBeNull();
+		});
+
+		it('should return undefined for expired entries', async () => {
+			const cache = new FileCache({ path: cachePath });
+
+			vi.useFakeTimers();
+			await cache.set('expiring', 'value', 1);
+
+			// Advance past expiration
+			vi.advanceTimersByTime(2000);
+
+			const result = await cache.get('expiring');
+			expect(result).toBeUndefined();
+
+			vi.useRealTimers();
+		});
+	});
+
+	describe('set', () => {
+		it('should create file and parent directory', async () => {
+			const nested = join(dir, 'nested', 'dir', 'cache.json');
+			const cache = new FileCache({ path: nested });
+
+			await cache.set('key', 'value');
+
+			expect(existsSync(nested)).toBe(true);
+		});
+
+		it('should overwrite existing value', async () => {
+			const cache = new FileCache({ path: cachePath });
+
+			await cache.set('key', 'first');
+			await cache.set('key', 'second');
+
+			expect(await cache.get('key')).toBe('second');
+		});
+
+		it('should persist data in valid JSON format', async () => {
+			const cache = new FileCache({ path: cachePath });
+
+			await cache.set('test', { hello: 'world' });
+
+			const raw = await readFile(cachePath, 'utf-8');
+			const parsed = JSON.parse(raw);
+
+			expect(parsed.test).toBeDefined();
+			expect(parsed.test.value).toEqual({ hello: 'world' });
+			expect(parsed.test.expiresAt).toBeDefined();
+		});
+
+		it('should use custom default TTL', async () => {
+			const cache = new FileCache({ path: cachePath, ttl: 3600 });
+
+			await cache.set('key', 'value');
+
+			const remaining = await cache.ttl('key');
+			expect(remaining).toBeGreaterThan(3500);
+			expect(remaining).toBeLessThanOrEqual(3600);
+		});
+	});
+
+	describe('delete', () => {
+		it('should remove existing key', async () => {
+			const cache = new FileCache({ path: cachePath });
+
+			await cache.set('key', 'value');
+			await cache.delete('key');
+
+			expect(await cache.get('key')).toBeUndefined();
+		});
+
+		it('should not throw for non-existent key', async () => {
+			const cache = new FileCache({ path: cachePath });
+			await expect(cache.delete('non-existent')).resolves.not.toThrow();
+		});
+
+		it('should only delete specified key', async () => {
+			const cache = new FileCache({ path: cachePath });
+
+			await cache.set('key1', 'value1');
+			await cache.set('key2', 'value2');
+			await cache.delete('key1');
+
+			expect(await cache.get('key1')).toBeUndefined();
+			expect(await cache.get('key2')).toBe('value2');
+		});
+	});
+
+	describe('ttl', () => {
+		it('should return 0 for non-existent key', async () => {
+			const cache = new FileCache({ path: cachePath });
+			expect(await cache.ttl('non-existent')).toBe(0);
+		});
+
+		it('should return remaining seconds for existing key', async () => {
+			const cache = new FileCache({ path: cachePath });
+			await cache.set('key', 'value', 300);
+
+			const remaining = await cache.ttl('key');
+			expect(remaining).toBeGreaterThan(298);
+			expect(remaining).toBeLessThanOrEqual(300);
+		});
+	});
+
+	describe('concurrency', () => {
+		it('should handle concurrent writes without corruption', async () => {
+			const cache = new FileCache({ path: cachePath });
+
+			// Write 10 keys concurrently
+			await Promise.all(
+				Array.from({ length: 10 }, (_, i) =>
+					cache.set(`key-${i}`, `value-${i}`),
+				),
+			);
+
+			// Verify all keys were written
+			for (let i = 0; i < 10; i++) {
+				const value = await cache.get(`key-${i}`);
+				expect(value).toBe(`value-${i}`);
+			}
+		});
+	});
+
+	describe('persistence', () => {
+		it('should persist across cache instances', async () => {
+			const cache1 = new FileCache({ path: cachePath });
+			await cache1.set('persistent', 'data');
+
+			const cache2 = new FileCache({ path: cachePath });
+			expect(await cache2.get('persistent')).toBe('data');
+		});
+	});
+});

package/src/__tests__/integration.spec.ts

@@ -0,0 +1,282 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import type { Cache } from '../';
+import { InMemoryCache } from '../memory';
+
+describe('Cache Integration Tests', () => {
+	let _memoryCache: Cache;
+
+	beforeEach(() => {
+		_memoryCache = new InMemoryCache();
+	});
+
+	describe('cross-cache behavior consistency', () => {
+		const testCases = [
+			{ name: 'InMemoryCache', cache: () => new InMemoryCache() },
+		];
+
+		testCases.forEach(({ name, cache }) => {
+			describe(name, () => {
+				let cacheInstance: Cache;
+
+				beforeEach(() => {
+					cacheInstance = cache();
+				});
+
+				it('should handle basic CRUD operations', async () => {
+					// Create
+					await cacheInstance.set('user:1', { id: 1, name: 'John' });
+
+					// Read
+					const user = await cacheInstance.get('user:1');
+					expect(user).toEqual({ id: 1, name: 'John' });
+
+					// Update
+					await cacheInstance.set('user:1', { id: 1, name: 'Jane' });
+					const updatedUser = await cacheInstance.get('user:1');
+					expect(updatedUser).toEqual({ id: 1, name: 'Jane' });
+
+					// Delete
+					await cacheInstance.delete('user:1');
+					const deletedUser = await cacheInstance.get('user:1');
+					expect(deletedUser).toBeUndefined();
+				});
+
+				it('should handle concurrent operations', async () => {
+					const operations = [
+						cacheInstance.set('key1', 'value1'),
+						cacheInstance.set('key2', 'value2'),
+						cacheInstance.set('key3', 'value3'),
+					];
+
+					await Promise.all(operations);
+
+					const results = await Promise.all([
+						cacheInstance.get('key1'),
+						cacheInstance.get('key2'),
+						cacheInstance.get('key3'),
+					]);
+
+					expect(results).toEqual(['value1', 'value2', 'value3']);
+				});
+
+				it('should handle data type preservation', async () => {
+					const testData = {
+						string: 'hello',
+						number: 42,
+						boolean: true,
+						object: { nested: true },
+						array: [1, 2, 3],
+						null: null,
+					};
+
+					// Store all data types
+					await Promise.all(
+						Object.entries(testData).map(([key, value]) =>
+							cacheInstance.set(key, value),
+						),
+					);
+
+					// Retrieve and verify
+					const results = await Promise.all(
+						Object.keys(testData).map((key) => cacheInstance.get(key)),
+					);
+
+					expect(results[0]).toBe('hello');
+					expect(results[1]).toBe(42);
+					expect(results[2]).toBe(true);
+					expect(results[3]).toEqual({ nested: true });
+					expect(results[4]).toEqual([1, 2, 3]);
+					expect(results[5]).toBeNull();
+				});
+
+				it('should handle key isolation', async () => {
+					await cacheInstance.set('user:1', 'User One');
+					await cacheInstance.set('user:2', 'User Two');
+					await cacheInstance.set('session:1', 'Session One');
+
+					await cacheInstance.delete('user:1');
+
+					expect(await cacheInstance.get('user:1')).toBeUndefined();
+					expect(await cacheInstance.get('user:2')).toBe('User Two');
+					expect(await cacheInstance.get('session:1')).toBe('Session One');
+				});
+			});
+		});
+	});
+
+	describe('cache migration scenarios', () => {
+		it('should support migrating data between cache implementations', async () => {
+			const sourceCache = new InMemoryCache();
+			const targetCache = new InMemoryCache();
+
+			// Populate source cache
+			const testData = {
+				'user:1': { id: 1, name: 'John' },
+				'user:2': { id: 2, name: 'Jane' },
+				'config:app': { theme: 'dark', notifications: true },
+			};
+
+			for (const [key, value] of Object.entries(testData)) {
+				await sourceCache.set(key, value);
+			}
+
+			// Simulate migration by reading from source and writing to target
+			const migrationKeys = Object.keys(testData);
+			for (const key of migrationKeys) {
+				const value = await sourceCache.get(key);
+				if (value !== undefined) {
+					await targetCache.set(key, value);
+				}
+			}
+
+			// Verify migration
+			for (const [key, expectedValue] of Object.entries(testData)) {
+				const migratedValue = await targetCache.get(key);
+				expect(migratedValue).toEqual(expectedValue);
+			}
+		});
+	});
+
+	describe('cache abstraction patterns', () => {
+		it('should support cache factory pattern', async () => {
+			const createCache = (type: 'memory'): Cache => {
+				switch (type) {
+					case 'memory':
+						return new InMemoryCache();
+					default:
+						throw new Error(`Unknown cache type: ${type}`);
+				}
+			};
+
+			const userCache = createCache('memory');
+			const sessionCache = createCache('memory');
+
+			await userCache.set<{ id: number; name: string }>('user:1', {
+				id: 1,
+				name: 'John',
+			});
+			await sessionCache.set<string>('session:abc', 'active');
+
+			expect(
+				await userCache.get<{ id: number; name: string }>('user:1'),
+			).toEqual({ id: 1, name: 'John' });
+			expect(await sessionCache.get<string>('session:abc')).toBe('active');
+		});
+
+		it('should support cache wrapper pattern', async () => {
+			class LoggingCache implements Cache {
+				private logs: string[] = [];
+
+				constructor(private underlying: Cache) {}
+
+				async get<T>(key: string): Promise<T | undefined> {
+					this.logs.push(`GET ${key}`);
+					return this.underlying.get<T>(key);
+				}
+
+				async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+					this.logs.push(`SET ${key}`);
+					return this.underlying.set<T>(key, value, ttl);
+				}
+
+				async delete(key: string): Promise<void> {
+					this.logs.push(`DELETE ${key}`);
+					return this.underlying.delete(key);
+				}
+
+				async ttl(key: string): Promise<number> {
+					return this.underlying.ttl(key);
+				}
+
+				getLogs(): string[] {
+					return [...this.logs];
+				}
+			}
+
+			const baseCache = new InMemoryCache();
+			const loggingCache = new LoggingCache(baseCache);
+
+			await loggingCache.set('test', 'value');
+			await loggingCache.get('test');
+			await loggingCache.delete('test');
+
+			const logs = loggingCache.getLogs();
+			expect(logs).toEqual(['SET test', 'GET test', 'DELETE test']);
+		});
+	});
+
+	describe('performance and stress tests', () => {
+		it('should handle large number of operations', async () => {
+			const cache = new InMemoryCache();
+			const operationCount = 1000;
+
+			// Bulk insert
+			const insertPromises = Array.from({ length: operationCount }, (_, i) =>
+				cache.set(`key:${i}`, i),
+			);
+			await Promise.all(insertPromises);
+
+			// Bulk read
+			const readPromises = Array.from({ length: operationCount }, (_, i) =>
+				cache.get(`key:${i}`),
+			);
+			const results = await Promise.all(readPromises);
+
+			// Verify all values
+			for (let i = 0; i < operationCount; i++) {
+				expect(results[i]).toBe(i);
+			}
+
+			// Bulk delete
+			const deletePromises = Array.from({ length: operationCount }, (_, i) =>
+				cache.delete(`key:${i}`),
+			);
+			await Promise.all(deletePromises);
+
+			// Verify deletion
+			const postDeleteRead = await cache.get('key:0');
+			expect(postDeleteRead).toBeUndefined();
+		});
+
+		it('should handle large objects efficiently', async () => {
+			const cache = new InMemoryCache();
+
+			const largeObject = {
+				id: 1,
+				data: Array.from({ length: 1000 }, (_, i) => ({
+					index: i,
+					value: `value-${i}`,
+					metadata: {
+						timestamp: Date.now(),
+						random: Math.random(),
+					},
+				})),
+			};
+
+			const startTime = Date.now();
+			await cache.set('large-object', largeObject);
+			const result = await cache.get('large-object');
+			const endTime = Date.now();
+
+			expect(result).toEqual(largeObject);
+			expect(endTime - startTime).toBeLessThan(100); // Should complete within 100ms
+		});
+	});
+
+	describe('error scenarios', () => {
+		it('should handle operations after errors gracefully', async () => {
+			const cache = new InMemoryCache();
+
+			// Successful operations
+			await cache.set('valid-key', 'valid-value');
+			expect(await cache.get('valid-key')).toBe('valid-value');
+
+			// Operations should continue working normally
+			await cache.set('another-key', 'another-value');
+			expect(await cache.get('another-key')).toBe('another-value');
+
+			await cache.delete('valid-key');
+			expect(await cache.get('valid-key')).toBeUndefined();
+		});
+	});
+});