StateAdapter
StateAdapter<
TTxContext,TJobId> =object
Defined in: packages/core/src/state-adapter/state-adapter.ts:85
Abstracts database operations for job persistence.
An adapter never throws Queuert’s domain errors: an absent or already completed row is
reported as undefined in the result position it belongs to, and the caller decides which
error the user sees. Adapters still throw for driver errors and connection loss.
Type Parameters
Section titled “Type Parameters”TTxContext
Section titled “TTxContext”TTxContext extends BaseTxContext
The transaction context type
TJobId
Section titled “TJobId”TJobId extends string
The job ID type
Properties
Section titled “Properties”addJobsBlockers
Section titled “addJobsBlockers”addJobsBlockers: (
params) =>Promise<StateJob&object[]>
Defined in: packages/core/src/state-adapter/state-adapter.ts:229
Adds blocker dependencies to jobs, in input order, with one blockers entry per
blockedByChainIds position — undefined at a position whose id does not name a chain
head. Rows for the resolvable positions may already be written, so the caller is expected
to abort the transaction, which is what rolls them back.
Parameters
Section titled “Parameters”params
Section titled “params”jobBlockers
Section titled “jobBlockers”object[]
TTxContext
Returns
Section titled “Returns”Promise<StateJob & object[]>
close: () =>
Promise<void>
Defined in: packages/core/src/state-adapter/state-adapter.ts:326
Releases internal resources. Idempotent.
Returns
Section titled “Returns”Promise<void>
completeJobs
Section titled “completeJobs”completeJobs: (
params) =>Promise<(StateJob&object|undefined)[]>
Defined in: packages/core/src/state-adapter/state-adapter.ts:155
Completes each job with its terminal output, ending its chain and setting the chain’s
completedAt. Results are in input order, undefined for an id with no matching job or
one already completed. hasBlockedJobs reports whether any job depends on the chain,
gating unblockJobs.
The caller must already hold each chain’s head row — take it with
getJobs({ lock: "exclusive" }) earlier in the same transaction, or a blocker committed
in the meantime is missed and its job stays blocked against a completed chain.
Parameters
Section titled “Parameters”params
Section titled “params”object & WriteTxContextParam<TTxContext>
Returns
Section titled “Returns”Promise<(StateJob & object | undefined)[]>
continueJobs
Section titled “continueJobs”continueJobs: (
params) =>Promise<(StateJob&object|undefined)[]>
Defined in: packages/core/src/state-adapter/state-adapter.ts:132
Completes each continueFromId and inserts its chain successor, linking the two. Each
result is the completed predecessor, with its successor under continuation. Results are
in input order, undefined for an id with no matching job or one already completed. A
colliding caller-supplied id or an already taken chain position still throws.
Parameters
Section titled “Parameters”params
Section titled “params”completedBy?
Section titled “completedBy?”string | null
object[]
TTxContext
Returns
Section titled “Returns”Promise<(StateJob & object | undefined)[]>
countByChainTypeNames
Section titled “countByChainTypeNames”countByChainTypeNames: (
params) =>Promise<object[]>
Defined in: packages/core/src/state-adapter/state-adapter.ts:263
Returns capped per-status counts for each requested chain type name, in input order.
Parameters
Section titled “Parameters”params
Section titled “params”ReadTxContextParam<TTxContext> & object
Returns
Section titled “Returns”Promise<object[]>
countByJobTypeNames
Section titled “countByJobTypeNames”countByJobTypeNames: (
params) =>Promise<object[]>
Defined in: packages/core/src/state-adapter/state-adapter.ts:268
Returns capped per-status counts for each requested job type name, in input order.
Parameters
Section titled “Parameters”params
Section titled “params”ReadTxContextParam<TTxContext> & object
Returns
Section titled “Returns”Promise<object[]>
createJobs
Section titled “createJobs”createJobs: (
params) =>Promise<StateChain&object[]>
Defined in: packages/core/src/state-adapter/state-adapter.ts:113
Creates chain heads. Deduplicated matches return deduplicated: true.
Parameters
Section titled “Parameters”params
Section titled “params”object[]
TTxContext
Returns
Section titled “Returns”Promise<StateChain & object[]>
deleteChains
Section titled “deleteChains”deleteChains: (
params) =>Promise<(StateChain|StateBlockedJob[] |undefined)[]>
Defined in: packages/core/src/state-adapter/state-adapter.ts:185
Deletes all jobs in the given chains atomically, returning each deleted chain in input
order, undefined for missing chains. If any chain is referenced as a blocker by a job
outside the set, nothing is deleted: that chain’s position holds the referencing
StateBlockedJob[] and every other position is undefined.
Parameters
Section titled “Parameters”params
Section titled “params”object & WriteTxContextParam<TTxContext>
Returns
Section titled “Returns”Promise<(StateChain | StateBlockedJob[] | undefined)[]>
extendJobAttempt
Section titled “extendJobAttempt”extendJobAttempt: (
params) =>Promise<StateJob|undefined>
Defined in: packages/core/src/state-adapter/state-adapter.ts:207
Extends a running job attempt’s deadline. Returns undefined when no job with this
id holds an attempt by this worker — it is gone, or the attempt is someone else’s.
Parameters
Section titled “Parameters”params
Section titled “params”object & WriteTxContextParam<TTxContext>
Returns
Section titled “Returns”Promise<StateJob | undefined>
getChains
Section titled “getChains”getChains: (
params) =>Promise<(StateChain|undefined)[]>
Defined in: packages/core/src/state-adapter/state-adapter.ts:99
Gets chains by their IDs, in input order, undefined for missing chains. Pass
lock: "exclusive" to acquire a write-intent lock on each chain’s head row.
Parameters
Section titled “Parameters”params
Section titled “params”object & LockTxContextParam<TTxContext>
Returns
Section titled “Returns”Promise<(StateChain | undefined)[]>
getJobBlockers
Section titled “getJobBlockers”getJobBlockers: (
params) =>Promise<StateChain[]>
Defined in: packages/core/src/state-adapter/state-adapter.ts:242
Gets the blocker chains for a job, one per blocker row in index order — a chain listed twice as a blocker appears twice.
Parameters
Section titled “Parameters”params
Section titled “params”object & ReadTxContextParam<TTxContext>
Returns
Section titled “Returns”Promise<StateChain[]>
getJobs
Section titled “getJobs”getJobs: (
params) =>Promise<(StateJob|undefined)[]>
Defined in: packages/core/src/state-adapter/state-adapter.ts:108
Gets jobs by their IDs, with their chains, in input order, undefined for missing
jobs. Pass lock: "exclusive" to acquire a write-intent lock on each job and its
chain’s head row, in a consistent id order.
Parameters
Section titled “Parameters”params
Section titled “params”object & LockTxContextParam<TTxContext>
Returns
Section titled “Returns”Promise<(StateJob | undefined)[]>
getStartAttemptDelayMs
Section titled “getStartAttemptDelayMs”getStartAttemptDelayMs: (
params) =>Promise<number|null>
Defined in: packages/core/src/state-adapter/state-adapter.ts:199
Ms until a pending job of these types can be attempted: 0 if due now, null if none.
Parameters
Section titled “Parameters”params
Section titled “params”object & ReadTxContextParam<TTxContext>
Returns
Section titled “Returns”Promise<number | null>
listBlockedJobs
Section titled “listBlockedJobs”listBlockedJobs: (
params) =>Promise<Page<StateJob>>
Defined in: packages/core/src/state-adapter/state-adapter.ts:317
Lists jobs that depend on the given chain as a blocker.
Parameters
Section titled “Parameters”params
Section titled “params”object & ReadTxContextParam<TTxContext>
Returns
Section titled “Returns”Promise<Page<StateJob>>
listChainJobs
Section titled “listChainJobs”listChainJobs: (
params) =>Promise<Page<StateJob>>
Defined in: packages/core/src/state-adapter/state-adapter.ts:308
Lists jobs within a specific chain, ordered by position in the chain.
Parameters
Section titled “Parameters”params
Section titled “params”object & ReadTxContextParam<TTxContext>
Returns
Section titled “Returns”Promise<Page<StateJob>>
listChains
Section titled “listChains”listChains: (
params) =>Promise<Page<StateChain>>
Defined in: packages/core/src/state-adapter/state-adapter.ts:275
Lists chains with pagination, status-dependent ordering, and filtering.
Parameters
Section titled “Parameters”params
Section titled “params”ReadTxContextParam<TTxContext> & object & { orderBy: "createdAt"; status?: undefined; } | { orderBy: "createdAt"; status: "running"; } | { orderBy: "createdAt" | "completedAt"; status: "completed"; }
Returns
Section titled “Returns”Promise<Page<StateChain>>
listChainTypeNames
Section titled “listChainTypeNames”listChainTypeNames: (
params) =>Promise<string[]>
Defined in: packages/core/src/state-adapter/state-adapter.ts:257
Returns distinct chain type names present in the data.
Parameters
Section titled “Parameters”params
Section titled “params”ReadTxContextParam<TTxContext>
Returns
Section titled “Returns”Promise<string[]>
listJobs
Section titled “listJobs”listJobs: (
params) =>Promise<Page<StateJob>>
Defined in: packages/core/src/state-adapter/state-adapter.ts:291
Lists jobs with pagination, status-dependent ordering, and filtering.
Parameters
Section titled “Parameters”params
Section titled “params”ReadTxContextParam<TTxContext> & object & { orderBy: "createdAt"; status?: undefined; } | { orderBy: "createdAt" | "scheduledAt"; status: "blocked"; } | { orderBy: "createdAt" | "scheduledAt"; status: "pending"; } | { orderBy: "createdAt" | "attemptAt" | "attemptUntil"; status: "running"; } | { orderBy: "createdAt" | "completedAt"; status: "completed"; }
Returns
Section titled “Returns”Promise<Page<StateJob>>
listJobTypeNames
Section titled “listJobTypeNames”listJobTypeNames: (
params) =>Promise<string[]>
Defined in: packages/core/src/state-adapter/state-adapter.ts:260
Returns distinct job type names present in the data.
Parameters
Section titled “Parameters”params
Section titled “params”ReadTxContextParam<TTxContext>
Returns
Section titled “Returns”Promise<string[]>
reclaimExpiredJobAttempt
Section titled “reclaimExpiredJobAttempt”reclaimExpiredJobAttempt: (
params) =>Promise<StateJob|undefined>
Defined in: packages/core/src/state-adapter/state-adapter.ts:216
Releases an expired job attempt back to the pending pool.
Parameters
Section titled “Parameters”params
Section titled “params”object & WriteTxContextParam<TTxContext>
Returns
Section titled “Returns”Promise<StateJob | undefined>
rescheduleJobs
Section titled “rescheduleJobs”rescheduleJobs: (
params) =>Promise<(StateJob|undefined)[]>
Defined in: packages/core/src/state-adapter/state-adapter.ts:169
Returns jobs to pending, clearing any running attempt. A blocked job keeps its
blocked status and only moves its scheduledAt. Skips completed and missing ids.
Parameters
Section titled “Parameters”params
Section titled “params”object & WriteTxContextParam<TTxContext>
Returns
Section titled “Returns”Promise<(StateJob | undefined)[]>
startJobAttempt
Section titled “startJobAttempt”startJobAttempt: (
params) =>Promise<StateJob&object|undefined>
Defined in: packages/core/src/state-adapter/state-adapter.ts:194
Atomically selects a pending job and starts an attempt, returning it with its
chain. Two parallel callers must never receive the same job — locked rows must
be skipped, not waited on. hasBlockers gates getJobBlockers.
Parameters
Section titled “Parameters”params
Section titled “params”object & WriteTxContextParam<TTxContext>
Returns
Section titled “Returns”Promise<StateJob & object | undefined>
transactionConcurrency
Section titled “transactionConcurrency”transactionConcurrency:
"concurrent"|"serialized"
Defined in: packages/core/src/state-adapter/state-adapter.ts:87
Whether two withTransaction callbacks can run concurrently.
unblockJobs
Section titled “unblockJobs”unblockJobs: (
params) =>Promise<StateDependentJob[]>
Defined in: packages/core/src/state-adapter/state-adapter.ts:252
Unblocks jobs when a blocker chain completes, transitioning each dependent whose blockers
are now all complete from blocked to pending. Returns one entry per blocker row on the
chain, whatever its job’s status, with the job’s own chain. Gated on completeJobs'
hasBlockedJobs.
Parameters
Section titled “Parameters”params
Section titled “params”object & WriteTxContextParam<TTxContext>
Returns
Section titled “Returns”Promise<StateDependentJob[]>
withSavepoint
Section titled “withSavepoint”withSavepoint: <
T>(txCtx,fn) =>Promise<T>
Defined in: packages/core/src/state-adapter/state-adapter.ts:93
Wraps a callback in a savepoint. Rolls back to the savepoint on error and re-throws.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”TTxContext
(txCtx) => Promise<T>
Returns
Section titled “Returns”Promise<T>
withTransaction
Section titled “withTransaction”withTransaction: <
T>(fn) =>Promise<T>
Defined in: packages/core/src/state-adapter/state-adapter.ts:90
Executes a callback within a transaction. Commits on success, rolls back on error.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”(txCtx) => Promise<T>
Returns
Section titled “Returns”Promise<T>