@yarlisai/idempotency

Primitivas de operaciones idempotentes para webhooks, pollers y cualquier operación que deba ejecutarse exactamente una vez — reclamación atómica de claves, almacenamiento y repetición de resultados, liberación en reintentos, expiración por TTL y limpieza de claves expiradas.

Instalación

npm install @yarlisai/idempotency

Por qué

@yarlisai/idempotency sigue el contrato puerto/adaptador: los consumidores dependen del puerto IdempotencyProvider e instancian un adaptador en tiempo de ejecución. En la v1 se incluyen dos adaptadores:

• postgres — respaldado por drizzle, con una ruta rápida de caché compatible con Redis opcional. El llamador inyecta su propio db, la referencia a la tabla idempotency_key, y los operadores and/eq/lt, por lo que el paquete nunca incluye una segunda copia de drizzle-orm ni de ioredis.
• memory — Map en proceso con TTL, para pruebas y despliegues de instancia única.

Uso

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

El README del paquete incluye una guía de inicio rápida completa. mybotbox-platform en sí mismo es el consumidor de referencia — apps/sat/lib/idempotency/ muestra cómo cada punto de llamada usa el puerto en lugar de acceder directamente a la base de datos.

Ver también

• Fuente
• npm
• ADR 0007 — Contrato puerto/adaptador