IdempotencyStore
Defined in: packages/pipeline-idempotency/src/interfaces/idempotency-store.interface.ts:25
Backend-agnostic store for idempotency records — the single seam every
storage backend implements. Because IdempotencyBehavior depends only
on this interface, swapping the backend (memory, Redis, Postgres, your own)
is a one-line change of the store passed to IdempotencyBehavior; handlers never
change.
Concurrent duplicate exclusion hinges on setIfAbsent being atomic
— it must claim the key only if no live record exists (e.g. Redis SET NX PX,
or a Postgres conditional upsert that replaces only expired conflicts).
Atomic claiming prevents two live duplicates from both acquiring the same
key; it does not by itself imply exactly-once execution across failures/retries.
Ownership-sensitive transitions use claimId. A stale execution whose claim
expired must never complete or delete a newer execution’s record. Built-in
stores implement this with an atomic compare-and-set / compare-and-delete.
Methods
Section titled “Methods”completeIfOwned()
Section titled “completeIfOwned()”completeIfOwned(
key,claimId,record,ttlMs):MaybePromise<boolean>
Defined in: packages/pipeline-idempotency/src/interfaces/idempotency-store.interface.ts:51
Atomically replaces the live in_progress record with record only when
the existing record is still owned by claimId.
Parameters
Section titled “Parameters”string
claimId
Section titled “claimId”string
record
Section titled “record”number
Returns
Section titled “Returns”MaybePromise<boolean>
true when this claim completed its own record; false when the
claim expired, was replaced, or was otherwise no longer owned by the caller.
delete()
Section titled “delete()”delete(
key):MaybePromise<void>
Defined in: packages/pipeline-idempotency/src/interfaces/idempotency-store.interface.ts:79
Unconditional delete for administrative or custom use. Pipeline failure release uses deleteIfOwned, not this method.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”MaybePromise<void>
deleteIfOwned()
Section titled “deleteIfOwned()”deleteIfOwned(
key,claimId):MaybePromise<boolean>
Defined in: packages/pipeline-idempotency/src/interfaces/idempotency-store.interface.ts:63
Atomically removes the live record only when it is still owned by
claimId. Used by releaseOnError so a stale failure cannot delete a
newer execution’s claim.
Parameters
Section titled “Parameters”string
claimId
Section titled “claimId”string
Returns
Section titled “Returns”MaybePromise<boolean>
get(
key):MaybePromise<IdempotencyRecord|undefined>
Defined in: packages/pipeline-idempotency/src/interfaces/idempotency-store.interface.ts:30
Returns the live (non-expired) record for key, or undefined if there is
none.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”MaybePromise<IdempotencyRecord | undefined>
set(
key,record,ttlMs):MaybePromise<void>
Defined in: packages/pipeline-idempotency/src/interfaces/idempotency-store.interface.ts:69
Unconditional overwrite for administrative or custom use. Pipeline execution completion uses completeIfOwned, not this method.
Parameters
Section titled “Parameters”string
record
Section titled “record”number
Returns
Section titled “Returns”MaybePromise<void>
setIfAbsent()
Section titled “setIfAbsent()”setIfAbsent(
key,record,ttlMs):MaybePromise<boolean>
Defined in: packages/pipeline-idempotency/src/interfaces/idempotency-store.interface.ts:38
Atomically stores record only if no live record exists for key.
Parameters
Section titled “Parameters”string
record
Section titled “record”number
Returns
Section titled “Returns”MaybePromise<boolean>
true if the key was claimed by this call, false if a live
record already existed.