@yarlisai/idempotency

Webhookやポーラー、そして正確に一度だけ実行しなければならないあらゆる操作のためのべき等操作プリミティブ — アトミックなキーのクレーム、結果の保存とリプレイ、リトライのリリース、TTL有効期限、および期限切れキーのクリーンアップ。

インストール

npm install @yarlisai/idempotency

背景

@yarlisai/idempotency は ポート/アダプターの規約 に従っています。コンシューマーは IdempotencyProvider ポートに依存し、実行時にアダプターをインスタンス化します。v1 では2つのアダプターが同梱されています：

• postgres — drizzle ベースで、オプションの Redis 互換キャッシュによる高速パスに対応。呼び出し元が独自の db、idempotency_key テーブル参照、および and/eq/lt 演算子を注入するため、このパッケージが drizzle-orm や ioredis の二重バンドルを行うことはありません。
• memory — TTL 付きのインプロセス Map。テストやシングルインスタンスのデプロイに適しています。

使い方

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

このパッケージの README には完全なクイックスタートが含まれています。mybotbox-platform 自体がリファレンス実装のコンシューマーであり、apps/sat/lib/idempotency/ では、すべての呼び出し箇所がデータベースに直接アクセスする代わりにポートを使用している様子を確認できます。

関連情報

• ソース
• npm
• ADR 0007 — ポート/アダプターの規約