@yarlisai/idempotency

Idempotenz-Primitiven für Webhooks, Poller und alle Operationen, die genau einmal ausgeführt werden müssen — atomisches Key-Claiming, Ergebnisspeicherung und -Replay, Retry-Freigabe, TTL-Ablauf und Bereinigung abgelaufener Keys.

Installation

npm install @yarlisai/idempotency

Warum

@yarlisai/idempotency folgt dem Port/Adapter-Vertrag: Konsumenten sind vom IdempotencyProvider-Port abhängig und instanziieren zur Laufzeit einen Adapter. Mit v1 werden zwei Adapter ausgeliefert:

• postgres — drizzle-basiert, mit optionalem Redis-kompatiblem Cache als schnellem Pfad. Der Aufrufer injiziert seine eigene db, die idempotency_key-Tabellenreferenz sowie die Operatoren and/eq/lt, sodass das Paket nie eine zweite Kopie von drizzle-orm oder ioredis bündelt.
• memory — prozessinterner Map mit TTL, für Tests und Single-Instance-Deployments.

Verwendung

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

Die README des Pakets enthält einen vollständigen Schnellstart. mybotbox-platform selbst ist der Referenz-Konsument — apps/sat/lib/idempotency/ zeigt, wie jede Aufrufstelle den Port verwendet, anstatt direkt auf die Datenbank zuzugreifen.

Siehe auch

• Quelle
• npm
• ADR 0007 — Port/Adapter-Vertrag