@geekmidas/cache 10.0.0-alpha.99 → 10.0.0

package/src/__tests__/memory.spec.ts

@@ -0,0 +1,134 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { InMemoryCache } from '../memory';
+
+describe('InMemoryCache', () => {
+	let cache: InMemoryCache;
+
+	beforeEach(() => {
+		cache = new InMemoryCache();
+	});
+
+	describe('get', () => {
+		it('should return undefined for non-existent key', async () => {
+			const result = await cache.get('non-existent');
+			expect(result).toBeUndefined();
+		});
+
+		it('should return value for existing key', async () => {
+			await cache.set('test-key', 'test-value');
+			const result = await cache.get('test-key');
+			expect(result).toBe('test-value');
+		});
+
+		it('should handle different data types', async () => {
+			const objectValue = { id: 1, name: 'test' };
+			const arrayValue = [1, 2, 3];
+			const numberValue = 42;
+			const booleanValue = true;
+
+			await cache.set('object', objectValue);
+			await cache.set('array', arrayValue);
+			await cache.set('number', numberValue);
+			await cache.set('boolean', booleanValue);
+
+			expect(await cache.get('object')).toEqual(objectValue);
+			expect(await cache.get('array')).toEqual(arrayValue);
+			expect(await cache.get('number')).toBe(numberValue);
+			expect(await cache.get('boolean')).toBe(booleanValue);
+		});
+	});
+
+	describe('set', () => {
+		it('should store string value', async () => {
+			await cache.set('string-key', 'string-value');
+			const result = await cache.get('string-key');
+			expect(result).toBe('string-value');
+		});
+
+		it('should store object value', async () => {
+			const value = { id: 1, data: 'test' };
+			await cache.set('object-key', value);
+			const result = await cache.get('object-key');
+			expect(result).toEqual(value);
+		});
+
+		it('should overwrite existing value', async () => {
+			await cache.set('key', 'initial-value');
+			await cache.set('key', 'updated-value');
+			const result = await cache.get('key');
+			expect(result).toBe('updated-value');
+		});
+
+		it('should handle null values', async () => {
+			await cache.set('null-key', null);
+			const result = await cache.get('null-key');
+			expect(result).toBeNull();
+		});
+	});
+
+	describe('delete', () => {
+		it('should remove existing key', async () => {
+			await cache.set('to-delete', 'value');
+			await cache.delete('to-delete');
+			const result = await cache.get('to-delete');
+			expect(result).toBeUndefined();
+		});
+
+		it('should not throw error for non-existent key', async () => {
+			await expect(cache.delete('non-existent')).resolves.not.toThrow();
+		});
+
+		it('should only delete specified key', async () => {
+			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('multiple operations', () => {
+		it('should handle multiple keys independently', async () => {
+			await cache.set('key1', 'value1');
+			await cache.set('key2', 'value2');
+			await cache.set('key3', 'value3');
+
+			expect(await cache.get('key1')).toBe('value1');
+			expect(await cache.get('key2')).toBe('value2');
+			expect(await cache.get('key3')).toBe('value3');
+		});
+
+		it('should maintain data integrity across operations', async () => {
+			const data = { count: 0 };
+			await cache.set('counter', data);
+
+			const retrieved = await cache.get('counter');
+			retrieved.count = 5;
+
+			const original = await cache.get('counter');
+			expect(original.count).toBe(5); // Reference equality in memory
+		});
+	});
+
+	describe('edge cases', () => {
+		it('should handle empty string as key', async () => {
+			await cache.set('', 'empty-key-value');
+			const result = await cache.get('');
+			expect(result).toBe('empty-key-value');
+		});
+
+		it('should handle special characters in keys', async () => {
+			const specialKey = 'key!@#$%^&*()_+{}|:"<>?[]\\;\',./?`~';
+			await cache.set(specialKey, 'special-value');
+			const result = await cache.get(specialKey);
+			expect(result).toBe('special-value');
+		});
+
+		it('should handle undefined values', async () => {
+			await cache.set('undefined-key', undefined);
+			const result = await cache.get('undefined-key');
+			expect(result).toBeUndefined();
+		});
+	});
+});

package/src/__tests__/upstash.spec.ts

@@ -0,0 +1,276 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { UpstashCache } from '../upstash';
+
+describe('UpstashCache', () => {
+	let cache: UpstashCache;
+	const testKeyPrefix = `test:${Date.now()}:`;
+	let testKeys: string[] = [];
+
+	beforeEach(() => {
+		cache = new UpstashCache('http://localhost:8079', 'example_token');
+		testKeys = [];
+	});
+
+	afterEach(async () => {
+		// Clean up test keys
+		for (const key of testKeys) {
+			try {
+				await cache.delete(key);
+			} catch (_error) {
+				// Ignore cleanup errors
+			}
+		}
+	});
+
+	const getTestKey = (suffix: string): string => {
+		const key = `${testKeyPrefix}${suffix}`;
+		testKeys.push(key);
+		return key;
+	};
+
+	describe('get', () => {
+		it('should return undefined for non-existent key', async () => {
+			const key = getTestKey('non-existent');
+			const result = await cache.get(key);
+
+			expect(result).toBeUndefined();
+		});
+
+		it('should parse and return JSON value', async () => {
+			const key = getTestKey('object');
+			const testValue = { id: 1, name: 'test' };
+
+			await cache.set(key, testValue);
+			const result = await cache.get(key);
+
+			expect(result).toEqual(testValue);
+		});
+
+		it('should handle string values', async () => {
+			const key = getTestKey('string');
+			const testValue = 'simple string';
+
+			await cache.set(key, testValue);
+			const result = await cache.get(key);
+
+			expect(result).toBe(testValue);
+		});
+
+		it('should handle number values', async () => {
+			const key = getTestKey('number');
+			const testValue = 42;
+
+			await cache.set(key, testValue);
+			const result = await cache.get(key);
+
+			expect(result).toBe(testValue);
+		});
+
+		it('should handle boolean values', async () => {
+			const key = getTestKey('boolean');
+			const testValue = true;
+
+			await cache.set(key, testValue);
+			const result = await cache.get(key);
+
+			expect(result).toBe(testValue);
+		});
+
+		it('should handle array values', async () => {
+			const key = getTestKey('array');
+			const testArray = [1, 2, 3, 'test'];
+
+			await cache.set(key, testArray);
+			const result = await cache.get(key);
+
+			expect(result).toEqual(testArray);
+		});
+
+		it('should handle null values as undefined', async () => {
+			const key = getTestKey('null');
+
+			await cache.set(key, null);
+			const result = await cache.get(key);
+
+			expect(result).toBeUndefined();
+		});
+	});
+
+	describe('set', () => {
+		it('should store and retrieve object value', async () => {
+			const key = getTestKey('set-object');
+			const testValue = { id: 1, name: 'test' };
+
+			await cache.set(key, testValue);
+			const result = await cache.get(key);
+
+			expect(result).toEqual(testValue);
+		});
+
+		it('should store and retrieve string values', async () => {
+			const key = getTestKey('set-string');
+			const testValue = 'test string';
+
+			await cache.set(key, testValue);
+			const result = await cache.get(key);
+
+			expect(result).toBe(testValue);
+		});
+
+		it('should store and retrieve number values', async () => {
+			const key = getTestKey('set-number');
+			const testValue = 42;
+
+			await cache.set(key, testValue);
+			const result = await cache.get(key);
+
+			expect(result).toBe(testValue);
+		});
+
+		it('should store and retrieve boolean values', async () => {
+			const key = getTestKey('set-boolean');
+			const testValue = true;
+
+			await cache.set(key, testValue);
+			const result = await cache.get(key);
+
+			expect(result).toBe(testValue);
+		});
+
+		it('should store and retrieve array values', async () => {
+			const key = getTestKey('set-array');
+			const testArray = [1, 2, 3];
+
+			await cache.set(key, testArray);
+			const result = await cache.get(key);
+
+			expect(result).toEqual(testArray);
+		});
+
+		it('should not store and retrieve null values', async () => {
+			const key = getTestKey('set-null');
+
+			await cache.set(key, null);
+			const result = await cache.get(key);
+
+			expect(result).toBeUndefined();
+		});
+
+		it('should overwrite existing values', async () => {
+			const key = getTestKey('overwrite');
+
+			await cache.set(key, 'initial');
+			await cache.set(key, 'updated');
+			const result = await cache.get(key);
+
+			expect(result).toBe('updated');
+		});
+	});
+
+	describe('delete', () => {
+		it('should delete existing key', async () => {
+			const key = getTestKey('delete-test');
+
+			await cache.set(key, 'value-to-delete');
+			await cache.delete(key);
+			const result = await cache.get(key);
+
+			expect(result).toBeUndefined();
+		});
+
+		it('should handle deletion of non-existent key', async () => {
+			const key = getTestKey('non-existent-delete');
+
+			await expect(cache.delete(key)).resolves.not.toThrow();
+		});
+
+		it('should only delete specified key', async () => {
+			const key1 = getTestKey('delete-key1');
+			const key2 = getTestKey('delete-key2');
+
+			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 key = getTestKey('ttl-non-existent');
+			const result = await cache.ttl(key);
+
+			expect(result).toBe(0);
+		});
+
+		it('should return positive TTL for existing key with expiry', async () => {
+			const key = getTestKey('ttl-with-expiry');
+
+			await cache.set(key, 'test-value', 3600);
+			const result = await cache.ttl(key);
+
+			expect(result).toBeGreaterThan(0);
+			expect(result).toBeLessThanOrEqual(3600);
+		});
+
+		it('should return TTL in seconds', async () => {
+			const key = getTestKey('ttl-seconds');
+
+			await cache.set(key, 'test-value', 60); // 60 seconds
+			const result = await cache.ttl(key);
+
+			expect(result).toBeGreaterThan(0);
+			expect(result).toBeLessThanOrEqual(60);
+		});
+	});
+
+	describe('integration scenarios', () => {
+		it('should handle round-trip operations', async () => {
+			const key = getTestKey('user-session');
+			const testData = {
+				user: { id: 1, name: 'John' },
+				preferences: ['dark-mode', 'notifications'],
+				count: 42,
+			};
+
+			await cache.set(key, testData);
+			const result = await cache.get(key);
+
+			expect(result).toEqual(testData);
+		});
+
+		it('should handle complex nested objects', async () => {
+			const key = getTestKey('complex');
+			const complexObject = {
+				level1: {
+					level2: {
+						level3: {
+							data: 'deep nested value',
+							array: [{ id: 1 }, { id: 2 }],
+						},
+					},
+				},
+			};
+
+			await cache.set(key, complexObject);
+			const result = await cache.get(key);
+
+			expect(result).toEqual(complexObject);
+		});
+
+		it('should handle concurrent operations', async () => {
+			const keys = ['concurrent1', 'concurrent2', 'concurrent3'].map((suffix) =>
+				getTestKey(suffix),
+			);
+			const values = ['value1', 'value2', 'value3'];
+
+			await Promise.all(keys.map((key, i) => cache.set(key, values[i])));
+			const results = await Promise.all(keys.map((key) => cache.get(key)));
+
+			expect(results).toEqual(values);
+		});
+	});
+});

package/src/expo.ts

@@ -0,0 +1,50 @@
+import { addSeconds } from 'date-fns';
+import * as SecureStore from 'expo-secure-store';
+import { type Cache, getExpirationInSeconds } from './index';
+
+export class ExpoSecureCache implements Cache {
+	static getExpiryKey(key: string): string {
+		return `${key}:expiresAt`;
+	}
+
+	async ttl(key: string): Promise<number> {
+		const result = await SecureStore.getItemAsync(
+			ExpoSecureCache.getExpiryKey(key),
+		);
+		if (!result) {
+			return 0;
+		}
+
+		const secondsLeft = getExpirationInSeconds(result);
+
+		return Math.max(secondsLeft, 0);
+	}
+
+	async get<T>(key: string): Promise<T | undefined> {
+		const result = await SecureStore.getItemAsync(key);
+		if (!result) {
+			return undefined;
+		}
+
+		const expiresAt = await this.ttl(key);
+		if (expiresAt === 0) {
+			return undefined;
+		}
+
+		return JSON.parse(result) as T;
+	}
+
+	async set<T>(key: string, value: T, ttl: number = 600): Promise<void> {
+		const expiresAt = addSeconds(new Date(), ttl).toISOString();
+		await SecureStore.setItemAsync(key, JSON.stringify(value));
+		await SecureStore.setItemAsync(
+			ExpoSecureCache.getExpiryKey(key),
+			expiresAt,
+		);
+	}
+
+	async delete(key: string): Promise<void> {
+		await SecureStore.deleteItemAsync(key);
+		await SecureStore.deleteItemAsync(ExpoSecureCache.getExpiryKey(key));
+	}
+}

package/src/file.ts

@@ -0,0 +1,126 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { addSeconds } from 'date-fns';
+import lockfile from 'proper-lockfile';
+import { type Cache, getExpirationInSeconds } from './';
+
+interface FileCacheEntry {
+	value: unknown;
+	expiresAt: string;
+}
+
+type FileCacheData = Record<string, FileCacheEntry>;
+
+export interface FileCacheOptions {
+	/** Path to the cache JSON file. Default: `process.cwd()/.gkm/cache.json` */
+	path?: string;
+	/** Default TTL in seconds. Default: 600 */
+	ttl?: number;
+}
+
+export class FileCache implements Cache {
+	private readonly path: string;
+	private readonly defaultTtl: number;
+	/** In-process mutex to serialize concurrent writes within the same process. */
+	private mutex: Promise<void> = Promise.resolve();
+
+	constructor(options: FileCacheOptions = {}) {
+		this.path = options.path ?? join(process.cwd(), '.gkm', 'cache.json');
+		this.defaultTtl = options.ttl ?? 600;
+	}
+
+	async get<T>(key: string): Promise<T | undefined> {
+		const data = await this.readData();
+		const entry = data[key];
+		if (!entry) return undefined;
+
+		const remaining = getExpirationInSeconds(entry.expiresAt);
+		if (remaining <= 0) {
+			await this.withLock(async (current) => {
+				delete current[key];
+				return current;
+			});
+			return undefined;
+		}
+
+		return entry.value as T;
+	}
+
+	async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+		const seconds = ttl ?? this.defaultTtl;
+		const expiresAt = addSeconds(new Date(), seconds).toISOString();
+
+		await this.withLock(async (data) => {
+			data[key] = { value, expiresAt };
+			return data;
+		});
+	}
+
+	async delete(key: string): Promise<void> {
+		await this.withLock(async (data) => {
+			delete data[key];
+			return data;
+		});
+	}
+
+	async ttl(key: string): Promise<number> {
+		const data = await this.readData();
+		const entry = data[key];
+		if (!entry) return 0;
+
+		return getExpirationInSeconds(entry.expiresAt);
+	}
+
+	private async readData(): Promise<FileCacheData> {
+		try {
+			const content = await readFile(this.path, 'utf-8');
+			return JSON.parse(content) as FileCacheData;
+		} catch {
+			return {};
+		}
+	}
+
+	private async ensureDir(): Promise<void> {
+		const dir = dirname(this.path);
+		if (!existsSync(dir)) {
+			await mkdir(dir, { recursive: true });
+		}
+	}
+
+	private async withLock(
+		fn: (data: FileCacheData) => Promise<FileCacheData>,
+	): Promise<void> {
+		// Queue behind any pending in-process operations
+		const prev = this.mutex;
+		let resolve: () => void;
+		this.mutex = new Promise<void>((r) => {
+			resolve = r;
+		});
+
+		try {
+			await prev;
+			await this.ensureDir();
+
+			// Ensure file exists before locking (proper-lockfile requires it)
+			if (!existsSync(this.path)) {
+				await writeFile(this.path, '{}');
+			}
+
+			const release = await lockfile.lock(this.path, {
+				retries: { retries: 3, minTimeout: 100, maxTimeout: 1000 },
+				stale: 10000,
+			});
+
+			try {
+				const data = await this.readData();
+				const updated = await fn(data);
+				await writeFile(this.path, JSON.stringify(updated, null, 2));
+			} finally {
+				await release();
+			}
+		} finally {
+			resolve!();
+		}
+	}
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+import { differenceInSeconds } from 'date-fns';
+
+export const getExpirationInSeconds = (
+	expiresAt: string | number | Date | undefined | null,
+): number => {
+	if (!expiresAt) {
+		return 0;
+	}
+
+	const expirationDate = new Date(expiresAt);
+	const now = new Date();
+
+	const secondsLeft = differenceInSeconds(expirationDate, now);
+
+	return Math.max(secondsLeft, 0);
+};
+
+export interface Cache {
+	/**
+	 * Retrieves a value from the cache.
+	 *
+	 * @param key The key to retrieve the value for.
+	 * @returns The cached value, or undefined if not found.
+	 */
+	get<T>(key: string): Promise<T | undefined>;
+	/**
+	 * Sets a value in the cache.
+	 *
+	 * @param key The key to set the value for.
+	 * @param value The value to cache.
+	 * @param ttl Optional time-to-live in seconds. If not provided, the value will not expire.
+	 */
+	set<T>(key: string, value: T, ttl?: number): Promise<void>;
+	/**
+	 * Deletes a value from the cache.
+	 *
+	 * @param key The key to delete from the cache.
+	 */
+	delete(key: string): Promise<void>;
+
+	/**
+	 * Retrieves the time-to-live (TTL) for a cached value.
+	 *
+	 * @param key The key to retrieve the TTL for.
+	 * @returns The TTL in seconds, or 0 if the key does not exist.
+	 */
+	ttl(key: string): Promise<number>;
+}

package/src/memory.ts

@@ -0,0 +1,38 @@
+import { addSeconds } from 'date-fns';
+import { type Cache, getExpirationInSeconds } from './';
+
+export class InMemoryCache implements Cache {
+	private store: Map<string, unknown> = new Map();
+	private expirations: Map<string, Date> = new Map();
+
+	async get<T>(key: string): Promise<T | undefined> {
+		const expiration = await this.ttl(key);
+		if (!expiration) {
+			await this.delete(key);
+			return undefined;
+		}
+
+		return this.store.get(key) as T | undefined;
+	}
+
+	async ttl(key: string): Promise<number> {
+		const expiration = this.expirations.get(key);
+		if (!expiration) {
+			return 0;
+		}
+
+		return getExpirationInSeconds(expiration);
+	}
+
+	async set<T>(key: string, value: T, ttl: number = 600): Promise<void> {
+		this.store.set(key, value);
+		const now = new Date();
+		const expiresAt = addSeconds(now, ttl);
+		this.expirations.set(key, expiresAt);
+	}
+
+	async delete(key: string): Promise<void> {
+		this.store.delete(key);
+		this.expirations.delete(key);
+	}
+}