npm install @reaatech/idempotency-middleware
# or
pnpm add @reaatech/idempotency-middleware

import { MemoryAdapter, IdempotencyMiddleware } from '@reaatech/idempotency-middleware';
 
const storage = new MemoryAdapter();
await storage.connect();
 
const middleware = new IdempotencyMiddleware(storage, { ttl: 86_400_000 });
 
// First call executes the handler
const result1 = await middleware.execute(
  'unique-key',
  { method: 'POST', path: '/charges', body: { amount: 100 } },
  async () => ({ id: 1, amount: 100 }),
);
 
// Duplicate call with same key returns the cached response
const result2 = await middleware.execute(
  'unique-key',
  { method: 'POST', path: '/charges', body: { amount: 100 } },
  async () => ({ id: 2, amount: 100 }), // Never called
);
 
console.log(result1 === result2); // true

import { IdempotencyMiddleware } from '@reaatech/idempotency-middleware';
 
const middleware = new IdempotencyMiddleware(storage, {
  ttl: 3_600_000,
  lockTimeout: 30_000,
});

import { IdempotencyError, IdempotencyErrorCode } from '@reaatech/idempotency-middleware';
 
throw new IdempotencyError(
  IdempotencyErrorCode.LOCK_TIMEOUT,
  'Could not acquire lock within the timeout period',
  { cause: originalError, context: { key: 'abc123' } },
);

import type { StorageAdapter, IdempotencyRecord } from '@reaatech/idempotency-middleware';
 
class MyAdapter implements StorageAdapter {
  async get(key: string): Promise<IdempotencyRecord | null> { /* ... */ }
  async set(key: string, record: IdempotencyRecord): Promise<void> { /* ... */ }
  async delete(key: string): Promise<void> { /* ... */ }
  async connect(): Promise<void> { /* ... */ }
  async disconnect(): Promise<void> { /* ... */ }
  async acquireLock(key: string, ttl: number): Promise<boolean> { /* ... */ }
  async releaseLock(key: string): Promise<void> { /* ... */ }
  async waitForLock(key: string, timeout: number, pollInterval: number): Promise<void> { /* ... */ }
}

import { MemoryAdapter } from '@reaatech/idempotency-middleware';
 
const adapter = new MemoryAdapter();
await adapter.connect();
// ... use the adapter ...
await adapter.disconnect(); // Clears all cache entries and lock timers

import { idempotentHandler } from '@reaatech/idempotency-middleware';
 
const handler = async (input: { amount: number }) => {
  return { id: 1, amount: input.amount };
};
 
const wrapped = idempotentHandler(storage, handler, { ttl: 3600000 });
 
// Call with input, idempotency key, and optional context
const result = await wrapped({ amount: 100 }, 'key-abc', { method: 'POST', path: '/charge' });

const middleware = new IdempotencyMiddleware(storage, {
  lockTimeout: 30000,    // Wait up to 30 seconds
  lockTtl: 60000,        // Lock auto-expires after 60 seconds
  lockPollInterval: 100, // Check every 100ms
});
 
// Execute concurrently — only one handler invocation
const [r1, r2] = await Promise.all([
  middleware.execute('same-key', {}, handler),
  middleware.execute('same-key', {}, handler),
]);
// r1 === r2, handler called once

const middleware = new IdempotencyMiddleware(storage, {
  getKey: (req) => {
    // Extract from a custom header
    return (req as Request).headers['x-idempotency-key'] as string;
  },
  varyHeaders: ['Accept-Language'],    // Include language in key
  includeBodyInKey: true,               // Different bodies = different keys (default)
  shouldCache: (response) => {
    // Don't cache responses marked as transient
    if (response && typeof response === 'object' && 'transient' in response) return false;
    return true;
  },
});

import { idempotentHandler, MemoryAdapter } from '@reaatech/idempotency-middleware';
 
const storage = new MemoryAdapter();
await storage.connect();
 
export const handler = idempotentHandler(
  storage,
  async (event: SQSEvent) => {
    // Process the message
    return { processed: event.Records.length };
  },
  { ttl: 3600000 },
);
 
// Usage — idempotencyKey from message deduplication ID
await handler(event, event.Records[0].messageId);