```json { "code": "type CacheEntry = { result: T; expiresAt: number };\n\ntype InFlightEntry = Promise;\n\ninterface IdempotencyGuardOptions {\n key: string;\n ttlMs: number;\n handler: () => Promise;\n}\n\nconst cache = new Map>();\nconst inFlight = new Map>();\n\nexport function createIdempotencyGuard(options: IdempotencyGuardOptions): Promise {\n const { key, ttlMs, handler } = options;\n\n // Check in-flight requests first\n if (inFlight.has(key)) {\n return inFlight.get(key) as Promise;\n }\n\n // Check cache\n const cached = cache.get(key);\n if (cached && Date.now() < cached.expiresAt) {\n return Promise.resolve(cached.result as T);\n }\n\n // Remove expired cache entry\n if (cached) {\n cache.delete(key);\n }\n\n // Start processing\n const promise = handler().then((result) => {\n // Cache successful result\n cache.set(key, { result, expiresAt: Date.now() + ttlMs });\n return result;\n }).finally(() => {\n // Clean up in-flight entry\n inFlight.delete(key);\n });\n\n inFlight.set(key, promise);\n\n return promise;\n}\n\n// Helper function to clear cache (useful for testing)\nexport function clearIdempotencyGuardCache(): void {\n cache.clear();\n inFlight.clear();\n}", "explanation": "The createIdempotencyGuard function implements an idempotency pattern to prevent duplicate processing of the same key. It maintains two maps: one for cached results and one for in-flight requests. When called with a key:\n\n1. First checks if there's an in-flight request for the same key and returns that promise if found\n2. Checks the cache for a valid (non-expired) result and returns it if available\n3. If neither exists, it starts the handler, caches the result on success, and cleans up the in-flight entry when done\n4. On handler failure, the result is not cached and the in-flight entry is removed, allowing future retries\n\nThe function uses JavaScript's Map for O(1) lookups and stores cache entries with expiration timestamps. The in-flight map ensures that concurrent calls with the same key share the same promise, preventing duplicate handler executions.", "complexity": { "time": "O(1) for all operations - Map lookups, insertions, and deletions are constant time. Handler execution time is excluded as it depends on the specific handler implementation.", "space": "O(n) where n is the number of unique keys being processed or cached. Each key stores either a cache entry (result + expiration) or an in-flight promise reference." }, "tests": [ "test('returns same promise for concurrent calls with same key', async () => { createIdempotencyGuard({ key: 'test', ttlMs: 1000, handler: () => Promise.resolve('result') }); const p1 = createIdempotencyGuard({ key: 'test', ttlMs: 1000, handler: () => Promise.resolve('result') }); const p2 = createIdempotencyGuard({ key: 'test', ttlMs: 1000, handler: () => Promise.resolve('result') }); expect(p1).toBe(p2); });", "test('caches result and returns cached value within ttl', async () => { let callCount = 0; const result = await createIdempotencyGuard({ key: 'cache-test', ttlMs: 1000, handler: () => { callCount++; return Promise.resolve('cached'); } }); expect(result).toBe('cached'); expect(callCount).toBe(1); const cachedResult = await createIdempotencyGuard({ key: 'cache-test', ttlMs: 1000, handler: () => { callCount++; return Promise.resolve('cached'); } }); expect(cachedResult).toBe('cached'); expect(callCount).toBe(1); });", "test('retries after ttl expiration', async () => { let callCount = 0; const result1 = await createIdempotencyGuard({ key: 'expiry-test', ttlMs: 10, handler: () => { callCount++; return Promise.resolve('first'); } }); expect(result1).toBe('first'); expect(callCount).toBe(1); await new Promise(resolve => setTimeout(resolve, 20)); const result2 = await createIdempotencyGuard({ key: 'expiry-test', ttlMs: 10, handler: () => { callCount++; return Promise.resolve('second'); } }); expect(result2).toBe('second'); expect(callCount).toBe(2); });", "test('does not cache on handler failure and allows retry', async () => { let callCount = 0; const failingHandler = () => { callCount++; return Promise.reject(new Error('handler failed')); }; await expect(createIdempotencyGuard({ key: 'error-test', ttlMs: 1000, handler: failingHandler })).rejects.toThrow('handler failed'); await expect(createIdempotencyGuard({ key: 'error-test', ttlMs: 1000, handler: failingHandler })).rejects.toThrow('handler failed'); expect(callCount).toBe(2); });", "test('handles concurrent calls and caches result once', async () => { let callCount = 0; const slowHandler = () => { callCount++; return new Promise(resolve => setTimeout(() => resolve('slow-result'), 50)); }; const promises = Array(5).fill(null).map(() => createIdempotencyGuard({ key: 'concurrent-test', ttlMs: 1000, handler: slowHandler })); const results = await Promise.all(promises); results.forEach(result => expect(result).toBe('slow-result')); expect(callCount).toBe(1); });" ] } ```