@yarlisai/idempotency

Idempotent-operation primitives for webhooks, pollers, and any operation that must run exactly once — atomic key claiming, result storage and replay, retry release, TTL expiry, and expired-key cleanup.

Install

npm install @yarlisai/idempotency

Why

@yarlisai/idempotency follows the port/adapter contract: consumers depend on the IdempotencyProvider port and instantiate an adapter at runtime. Two adapters ship at v1:

• postgres — drizzle-backed, with an optional Redis-compatible cache fast path. The caller injects its own db, idempotency_key table reference, and and/eq/lt operators, so the package never bundles a second copy of drizzle-orm or ioredis.
• memory — in-process Map with TTL, for tests and single-instance deployments.

Usage

import { createIdempotencyClient } from '@yarlisai/idempotency'
import { and, eq, lt } from 'drizzle-orm'

const webhookIdempotency = createIdempotencyClient({
  adapter: 'postgres',
  db,
  table: idempotencyKey,
  operators: { and, eq, lt },
  namespace: 'webhook',
  ttlSeconds: 60 * 60 * 24 * 7,
})

const claim = await webhookIdempotency.atomicallyClaim('stripe', event.id)
if (!claim.claimed) return // duplicate delivery

The package's README ships a complete quickstart. mybotbox-platform itself is the reference consumer — apps/sat/lib/idempotency/ shows how every callsite uses the port instead of reaching the database directly.

See also

• Source
• npm
• ADR 0007 — Port/adapter contract