crypto-aio / crypto-aio / OperationStore
Interface: OperationStore ​
Defined in: src/core/store/types.ts:343
Durable Operation storage. Required guarantees (verified by the contract suite), binding on every implementation (memory, Redis, Postgres, ...):
createis create-if-absent on(namespace, idempotencyKey): a secondcreatefor an existing key returns the stored record unchanged, regardless ofintentHash— this store never performs the idempotency-conflict check itself; the calling engine does.update/appendAttemptare version-checked (compare-and-set onexpectedVersion) and optionally fenced by a claim token. Both are restricted to the same runtime patch whitelist (OPERATION_PATCH_KEYS), andclearmay only nameCLEARABLE_FIELDS; any other key anywhere in the patch rejects the whole call withINVALID_TRANSITIONbefore any mutation. An explicitundefinedvalue for a writable field is a no-op (the stored value survives); onlyclearremoves a field.appendAttemptis atomic with its accompanying patch, never rewrites a previously storedAttemptRecord, and rejects a duplicate attempt id. Attempt ids are globally unique across every Operation and namespace: the core makes each one random, and observations are keyed by attempt id alone, so a store may also refuse (INVALID_TRANSITION) an id that another Operation holds.- Time:
createdAt,updatedAtand claim expiry are stamped with the store's clock, which the core compares with its own (claimDuegets the worker'snow). Give a durable store the container's clock, or a wall clock the processes share, as the memory stores take theirs. claimDueandlistare scoped by namespace: they never return a record of another namespace, even one with the same id.claimDuereturns only non-terminal operations withnextCheckAtset and<= now, ordered by(nextCheckAt, createdAt)with a stable tie-break for equal values, and returns[]forlimit <= 0. A claimed Operation is excluded until itsclaim.until <= now; then another worker may take it over. Claim tokens are strictly increasing per store; fenced writes are rejected after a takeover.listreturns matches in creation order.ClearableFieldis restricted on purpose:clearcan never remove store-owned or identity fields (attempts,claim,version,id, ...) orstate. An implementation reads the caller'sclearlist once, so the list it validates is the list it applies.- A key set to
undefined, in an observation or a patch, is never persisted as a value such asnull. In a patch, the stored field keeps its value. In an observation, which replaces the whole record, the field reads backundefined(nevernull). - Every record and observation returned is a copy: mutating it, or the caller's input after a write, never changes what is stored. Values keep their types (
bigint,Uint8Array), and orderings are kept whole. - A refusal (
VERSION_CONFLICT,FENCING,INVALID_TRANSITION) leaves the stored record unchanged, and no error names an idempotency key or an address.
Methods ​
appendAttempt() ​
appendAttempt(
namespace,id,attempt,patch,expectedVersion,fence?):Promise<OperationRecord>
Defined in: src/core/store/types.ts:388
Appends attempt after the earlier ones and applies patch, in one atomic write that bumps the version and makes attempt the activeAttemptId. Checked and fenced as update; a duplicate attempt id fails with INVALID_TRANSITION.
Parameters ​
namespace ​
string
id ​
string
attempt ​
patch ​
expectedVersion ​
number
fence? ​
Returns ​
Promise<OperationRecord>
claimDue() ​
claimDue(
namespace,workerId,now,leaseMs,limit):Promise<OperationRecord[]>
Defined in: src/core/store/types.ts:412
Claims non-terminal operations whose nextCheckAt is set and <= now (unscheduled ones are never due).
Parameters ​
namespace ​
string
workerId ​
string
now ​
number
leaseMs ​
number
limit ​
number
Returns ​
Promise<OperationRecord[]>
create() ​
create(
operation):Promise<CreateResult>
Defined in: src/core/store/types.ts:351
Stores operation unless its (namespace, idempotencyKey) is taken, in which case it returns the stored record (created: false). The new record has version 1. Refuses with INVALID_TRANSITION, storing nothing, an input carrying a store-owned field (version, createdAt, updatedAt, claim) or an id another Operation of the namespace holds.
Parameters ​
operation ​
Returns ​
Promise<CreateResult>
findByRef() ​
findByRef(
namespace,refOrTxHash):Promise<OperationRecord|null>
Defined in: src/core/store/types.ts:368
Finds by an Attempt ref id or by an observed canonical tx hash. The engine's AttemptRef guard, which refuses an Attempt whose ref another Operation of the namespace holds, relies on this read being read-your-writes consistent across every process that shares the store: it must see any appendAttempt that another store instance committed before it was called (no read replica, no eventually consistent index).
At most one Operation of a namespace holds a ref: that guard refuses an Attempt whose ref another Operation holds. Should several hold it anyway (records written outside the core), a store may return any one of them.
Parameters ​
namespace ​
string
refOrTxHash ​
string
Returns ​
Promise<OperationRecord | null>
get() ​
get(
namespace,id):Promise<OperationRecord|null>
Defined in: src/core/store/types.ts:353
The Operation with this id in the namespace, or null.
Parameters ​
namespace ​
string
id ​
string
Returns ​
Promise<OperationRecord | null>
getByKey() ​
getByKey(
namespace,idempotencyKey):Promise<OperationRecord|null>
Defined in: src/core/store/types.ts:355
The Operation holding this idempotency key in the namespace, or null.
Parameters ​
namespace ​
string
idempotencyKey ​
string
Returns ​
Promise<OperationRecord | null>
getObservation() ​
getObservation(
attemptId):Promise<AttemptObservation|null>
Defined in: src/core/store/types.ts:397
The latest observation of the Attempt, or null.
Parameters ​
attemptId ​
string
Returns ​
Promise<AttemptObservation | null>
list() ​
list(
filter):Promise<OperationRecord[]>
Defined in: src/core/store/types.ts:422
The Operations filter matches, in creation order, at most filter.limit of them.
Parameters ​
filter ​
Returns ​
Promise<OperationRecord[]>
purge()? ​
optionalpurge(filter):Promise<number>
Defined in: src/core/store/types.ts:430
Optional: deletes what filter matches, as list reads it (the oldest first, at most limit), with their Attempts' observations and their idempotency keys, and returns how many it deleted. The core never calls it. It deletes live Operations too, and a purged key creates a new Operation that pays again: purge only terminal Operations older than any time a caller could still repeat their key.
Parameters ​
filter ​
Returns ​
Promise<number>
putObservation() ​
putObservation(
observation,expectedVersion):Promise<AttemptObservation>
Defined in: src/core/store/types.ts:407
Stores observation as the whole new record, version-checked. An optional field left out of it or set to undefined (a cleared reason, blockHash or blockHeight) reads back undefined (never null) afterwards. A store must replace the record, never merge fields into the old one. The monitor relies on this to clear stale values. expectedVersion null creates the first observation (version 1) and fails with VERSION_CONFLICT if one exists; otherwise it must be the stored version. It never changes the Operation's version.
Parameters ​
observation ​
Omit<AttemptObservation, "version">
expectedVersion ​
number | null
Returns ​
Promise<AttemptObservation>
releaseClaim() ​
releaseClaim(
namespace,id,fence):Promise<void>
Defined in: src/core/store/types.ts:420
Removes the claim fence holds; a claim taken over since fails with FENCING.
Parameters ​
namespace ​
string
id ​
string
fence ​
Returns ​
Promise<void>
update() ​
update(
namespace,id,patch,expectedVersion,fence?):Promise<OperationRecord>
Defined in: src/core/store/types.ts:376
Compare-and-set on expectedVersion, optionally fenced. Every successful update bumps version, even when the patch changes no field (the engine fences stale writers with such a no-effect update). Fails with NOT_FOUND, VERSION_CONFLICT, FENCING, or INVALID_TRANSITION for a patch key outside the whitelist or a clear that is not an array of CLEARABLE_FIELDS.
Parameters ​
namespace ​
string
id ​
string
patch ​
expectedVersion ​
number
fence? ​
Returns ​
Promise<OperationRecord>