Client
Client<
TJobTypeDefinitions,TStateAdapter,TJobId> =object
Defined in: packages/core/src/client.ts:202
The public API for managing chains. Created via createClient.
Methods are split into three categories:
- Mutating —
createChain,createChains,completeChain,deleteChain,deleteChains,rescheduleJob,rescheduleJobs. RequiretransactionHooksand a transaction context; they throwErrorif called without the transaction context fromwithTransaction. - Read-only —
getChain,getChains,getJob,getJobs,listChainTypeNames,listJobTypeNames,countByChainTypeNames,countByJobTypeNames,listChains,listJobs,listChainJobs,getJobBlockers,listBlockedJobs. Accept an optional transaction context. - Waiting —
awaitChain. Takes no transaction context: it polls outside any transaction and listens for notify adapter events.
Type Parameters
Section titled “Type Parameters”TJobTypeDefinitions
Section titled “TJobTypeDefinitions”TJobTypeDefinitions extends BaseJobTypeDefinitions
TStateAdapter
Section titled “TStateAdapter”TStateAdapter extends StateAdapter<any, any>
TJobId
Section titled “TJobId”TJobId = GetStateAdapterJobId<TStateAdapter>
Properties
Section titled “Properties”[helpersSymbol]
Section titled “[helpersSymbol]”
readonly[helpersSymbol]:Helpers
Defined in: packages/core/src/client.ts:207
awaitChain
Section titled “awaitChain”awaitChain: <
TChainTypeName>(chain,options) =>Promise<ResolvedChain<TJobId,TJobTypeDefinitions,TChainTypeName> &object>
Defined in: packages/core/src/client.ts:221
Wait for a chain to complete. Combines polling with notify adapter events.
Type Parameters
Section titled “Type Parameters”TChainTypeName
Section titled “TChainTypeName”TChainTypeName extends JobTypeEntryNames<TJobTypeDefinitions> = JobTypeEntryNames<TJobTypeDefinitions>
Parameters
Section titled “Parameters”TJobId
typeName?
Section titled “typeName?”TChainTypeName
options
Section titled “options”pollIntervalMs?
Section titled “pollIntervalMs?”number
signal?
Section titled “signal?”AbortSignal
timeoutMs
Section titled “timeoutMs”number
Returns
Section titled “Returns”Promise<ResolvedChain<TJobId, TJobTypeDefinitions, TChainTypeName> & object>
Throws
Section titled “Throws”WaitChainTimeoutError on timeout or abort.
Throws
Section titled “Throws”ChainNotFoundError if the chain disappears or never existed.
Throws
Section titled “Throws”ChainTypeMismatchError if typeName is provided and does not match.
completeChain
Section titled “completeChain”completeChain: <
TChainTypeName,THandler,TResult>(options) =>Promise<TResult>
Defined in: packages/core/src/client.ts:370
Complete a chain from outside a worker. Validates typeName, then passes
the current job and a completeJob function to the handler. The handler
may decline (return without calling completeJob); when it does complete,
the callback passes exactly one outcome — { output } or
{ continueWith: {...} } — to finish, which writes it before it returns.
completeJob resolves to the continuation when the outcome continued the
chain, so several jobs can be walked in a row:
job = await completeJob(job, async ({ finish }) => finish({ continueWith: { typeName: "step-a", input: { valueA: 42 } } }));Type Parameters
Section titled “Type Parameters”TChainTypeName
Section titled “TChainTypeName”TChainTypeName extends JobTypeEntryNames<TJobTypeDefinitions>
THandler
Section titled “THandler”THandler extends (…args) => Promise<any> = ChainHandler<TStateAdapter, TJobTypeDefinitions, TChainTypeName>
TResult
Section titled “TResult”TResult = CompleteChainResultFromHandler<TJobId, TJobTypeDefinitions, TChainTypeName, THandler>
Parameters
Section titled “Parameters”options
Section titled “options”object & GetStateAdapterTxContext<TStateAdapter>
Returns
Section titled “Returns”Promise<TResult>
Throws
Section titled “Throws”ChainNotFoundError if the chain does not exist.
Throws
Section titled “Throws”ChainTypeMismatchError if the chain’s type does not match typeName.
Throws
Section titled “Throws”JobAlreadyCompletedError from the inner completeJob if the job is already completed.
Throws
Section titled “Throws”BlockerLimitExceededError from the inner finish if a continueWith outcome declares more blockers than the per-job limit.
countByChainTypeNames
Section titled “countByChainTypeNames”countByChainTypeNames: (
options) =>Promise<object[]>
Defined in: packages/core/src/client.ts:474
Returns capped per-status counts for the given chain type names, in input order.
Parameters
Section titled “Parameters”options
Section titled “options”object & Partial<GetStateAdapterTxContext<TStateAdapter>>
Returns
Section titled “Returns”Promise<object[]>
countByJobTypeNames
Section titled “countByJobTypeNames”countByJobTypeNames: (
options) =>Promise<object[]>
Defined in: packages/core/src/client.ts:488
Returns capped per-status counts for the given job type names, in input order.
Parameters
Section titled “Parameters”options
Section titled “options”object & Partial<GetStateAdapterTxContext<TStateAdapter>>
Returns
Section titled “Returns”Promise<object[]>
createChain
Section titled “createChain”createChain: <
TChainTypeName>(options) =>Promise<ResolvedChain<TJobId,TJobTypeDefinitions,TChainTypeName> &object>
Defined in: packages/core/src/client.ts:253
Create a new chain. Returns the created chain with a deduplicated flag.
Pass id to assign a caller-supplied ID for the root job; if the chain is
deduplicated, the returned chain carries the existing row’s ID, not the
caller’s.
Type Parameters
Section titled “Type Parameters”TChainTypeName
Section titled “TChainTypeName”TChainTypeName extends JobTypeEntryNames<TJobTypeDefinitions>
Parameters
Section titled “Parameters”options
Section titled “options”CreateChainEntry<TJobId, TJobTypeDefinitions, TChainTypeName> & object & GetStateAdapterTxContext<TStateAdapter>
Returns
Section titled “Returns”Promise<ResolvedChain<TJobId, TJobTypeDefinitions, TChainTypeName> & object>
Throws
Section titled “Throws”InvalidJobIdError if id fails the state adapter’s validateId check.
Throws
Section titled “Throws”BlockerLimitExceededError if the root job declares more blockers than the per-job limit.
Throws
Section titled “Throws”ChainNotFoundError if a blocker chain does not exist.
Throws
Section titled “Throws”JobTypeValidationError if the job type rejects the entry, input, or blockers.
Throws
Section titled “Throws”TypeError if deduplication.scope is missing or not "running" / "any".
Throws
Section titled “Throws”The state adapter’s own error (e.g. a unique-constraint violation) if a caller-supplied id is already taken.
createChains
Section titled “createChains”createChains: <
TChains>(options) =>Promise<CreateChainsResult<TJobId,TJobTypeDefinitions,TChains>>
Defined in: packages/core/src/client.ts:275
Create multiple chains in a single batch operation. Returns created chains
with deduplicated flags, in the same order as input. Each item may carry
an optional id; dedup wins over a caller-supplied id when applicable.
Type Parameters
Section titled “Type Parameters”TChains
Section titled “TChains”TChains extends readonly AnyCreateChainEntry<TJobId, TJobTypeDefinitions>[]
Parameters
Section titled “Parameters”options
Section titled “options”object & GetStateAdapterTxContext<TStateAdapter>
Returns
Section titled “Returns”Promise<CreateChainsResult<TJobId, TJobTypeDefinitions, TChains>>
Throws
Section titled “Throws”InvalidJobIdError if any id fails the state adapter’s validateId check.
Throws
Section titled “Throws”BlockerLimitExceededError if any root job declares more blockers than the per-job limit.
Throws
Section titled “Throws”ChainNotFoundError if any blocker chain does not exist.
Throws
Section titled “Throws”JobTypeValidationError if a job type rejects an item’s entry, input, or blockers.
Throws
Section titled “Throws”TypeError if deduplication.scope is missing or not "running" / "any".
Throws
Section titled “Throws”The state adapter’s own error (e.g. a unique-constraint violation) if a caller-supplied id is already taken.
deleteChain
Section titled “deleteChain”deleteChain: <
TEntryName>(options) =>Promise<ResolvedChain<TJobId,TJobTypeDefinitions,TEntryName> |undefined>
Defined in: packages/core/src/client.ts:288
Delete a single chain by ID. Returns the deleted chain, or undefined if no
chain with that ID exists.
Type Parameters
Section titled “Type Parameters”TEntryName
Section titled “TEntryName”TEntryName extends JobTypeEntryNames<TJobTypeDefinitions> = JobTypeEntryNames<TJobTypeDefinitions>
Parameters
Section titled “Parameters”options
Section titled “options”object & GetStateAdapterTxContext<TStateAdapter>
Returns
Section titled “Returns”Promise<ResolvedChain<TJobId, TJobTypeDefinitions, TEntryName> | undefined>
Throws
Section titled “Throws”BlockerReferenceError if external jobs depend on it.
deleteChains
Section titled “deleteChains”deleteChains: <
TEntryName>(options) =>Promise<ResolvedChain<TJobId,TJobTypeDefinitions,TEntryName>[]>
Defined in: packages/core/src/client.ts:303
Delete chains by ID. Missing IDs are silently skipped.
Type Parameters
Section titled “Type Parameters”TEntryName
Section titled “TEntryName”TEntryName extends JobTypeEntryNames<TJobTypeDefinitions> = JobTypeEntryNames<TJobTypeDefinitions>
Parameters
Section titled “Parameters”options
Section titled “options”object & GetStateAdapterTxContext<TStateAdapter>
Returns
Section titled “Returns”Promise<ResolvedChain<TJobId, TJobTypeDefinitions, TEntryName>[]>
Throws
Section titled “Throws”BlockerReferenceError if external jobs depend on them.
getChain
Section titled “getChain”getChain: <
TChainTypeName>(options) =>Promise<ResolvedChain<TJobId,TJobTypeDefinitions,TChainTypeName> |undefined>
Defined in: packages/core/src/client.ts:393
Get a single chain by ID. Pass typeName for type narrowing.
Type Parameters
Section titled “Type Parameters”TChainTypeName
Section titled “TChainTypeName”TChainTypeName extends JobTypeEntryNames<TJobTypeDefinitions> = JobTypeEntryNames<TJobTypeDefinitions>
Parameters
Section titled “Parameters”options
Section titled “options”object & Partial<GetStateAdapterTxContext<TStateAdapter>>
Returns
Section titled “Returns”Promise<ResolvedChain<TJobId, TJobTypeDefinitions, TChainTypeName> | undefined>
Throws
Section titled “Throws”ChainTypeMismatchError if typeName is provided and does not match.
getChains
Section titled “getChains”getChains: <
TChainTypeName>(options) =>Promise<(ResolvedChain<TJobId,TJobTypeDefinitions,TChainTypeName> |undefined)[]>
Defined in: packages/core/src/client.ts:411
Get multiple chains by ID. Returns a positional array aligned with the
input ids — undefined for any ID that does not exist. Pass typeName
to narrow the return type; all found chains must match or
ChainTypeMismatchError is thrown.
Type Parameters
Section titled “Type Parameters”TChainTypeName
Section titled “TChainTypeName”TChainTypeName extends JobTypeEntryNames<TJobTypeDefinitions> = JobTypeEntryNames<TJobTypeDefinitions>
Parameters
Section titled “Parameters”options
Section titled “options”object & Partial<GetStateAdapterTxContext<TStateAdapter>>
Returns
Section titled “Returns”Promise<(ResolvedChain<TJobId, TJobTypeDefinitions, TChainTypeName> | undefined)[]>
Throws
Section titled “Throws”ChainTypeMismatchError if typeName is provided and any found chain does not match.
getJob
Section titled “getJob”getJob: <
TJobTypeName>(options) =>Promise<ResolvedJob<TJobId,TJobTypeDefinitions,TJobTypeName> |undefined>
Defined in: packages/core/src/client.ts:426
Get a single job by ID. Pass typeName for type narrowing.
Type Parameters
Section titled “Type Parameters”TJobTypeName
Section titled “TJobTypeName”TJobTypeName extends JobTypeNames<TJobTypeDefinitions> = JobTypeNames<TJobTypeDefinitions>
Parameters
Section titled “Parameters”options
Section titled “options”object & Partial<GetStateAdapterTxContext<TStateAdapter>>
Returns
Section titled “Returns”Promise<ResolvedJob<TJobId, TJobTypeDefinitions, TJobTypeName> | undefined>
Throws
Section titled “Throws”JobTypeMismatchError if typeName is provided and does not match.
getJobBlockers
Section titled “getJobBlockers”getJobBlockers: <
TJobTypeName,TBlockers>(options) =>Promise<TBlockers>
Defined in: packages/core/src/client.ts:575
Get the blocker chains for a specific job. Not paginated — blockers are
bounded by design. Pass typeName for type narrowing.
Type Parameters
Section titled “Type Parameters”TJobTypeName
Section titled “TJobTypeName”TJobTypeName extends JobTypeNames<TJobTypeDefinitions> = JobTypeNames<TJobTypeDefinitions>
TBlockers
Section titled “TBlockers”TBlockers extends readonly unknown[] = BlockerChains<TJobId, TJobTypeDefinitions, TJobTypeName>
Parameters
Section titled “Parameters”options
Section titled “options”object & Partial<GetStateAdapterTxContext<TStateAdapter>>
Returns
Section titled “Returns”Promise<TBlockers>
Throws
Section titled “Throws”JobTypeMismatchError if typeName is provided and does not match.
getJobs
Section titled “getJobs”getJobs: <
TJobTypeName>(options) =>Promise<(ResolvedJob<TJobId,TJobTypeDefinitions,TJobTypeName> |undefined)[]>
Defined in: packages/core/src/client.ts:443
Get multiple jobs by ID. Returns a positional array aligned with the
input ids — undefined for any ID that does not exist. Pass typeName
to narrow the return type; all found jobs must match or
JobTypeMismatchError is thrown.
Type Parameters
Section titled “Type Parameters”TJobTypeName
Section titled “TJobTypeName”TJobTypeName extends JobTypeNames<TJobTypeDefinitions> = JobTypeNames<TJobTypeDefinitions>
Parameters
Section titled “Parameters”options
Section titled “options”object & Partial<GetStateAdapterTxContext<TStateAdapter>>
Returns
Section titled “Returns”Promise<(ResolvedJob<TJobId, TJobTypeDefinitions, TJobTypeName> | undefined)[]>
Throws
Section titled “Throws”JobTypeMismatchError if typeName is provided and any found job does not match.
listBlockedJobs
Section titled “listBlockedJobs”listBlockedJobs: <
TChainTypeName,TBlockedJob>(options) =>Promise<Page<TBlockedJob>>
Defined in: packages/core/src/client.ts:592
List jobs from other chains that are blocked by a given chain. Useful for
understanding downstream impact before deletion. Pass typeName for type
narrowing.
Type Parameters
Section titled “Type Parameters”TChainTypeName
Section titled “TChainTypeName”TChainTypeName extends JobTypeEntryNames<TJobTypeDefinitions> = JobTypeEntryNames<TJobTypeDefinitions>
TBlockedJob
Section titled “TBlockedJob”TBlockedJob = ResolvedJob<TJobId, TJobTypeDefinitions, JobTypeBlockedNames<TJobTypeDefinitions, TChainTypeName> & JobTypeNames<TJobTypeDefinitions>>
Parameters
Section titled “Parameters”options
Section titled “options”object & Partial<GetStateAdapterTxContext<TStateAdapter>>
Returns
Section titled “Returns”Promise<Page<TBlockedJob>>
Throws
Section titled “Throws”ChainTypeMismatchError if typeName is provided and does not match.
listChainJobs
Section titled “listChainJobs”listChainJobs: <
TChainTypeName>(options) =>Promise<Page<ResolvedChainJobs<TJobId,TJobTypeDefinitions,TChainTypeName>>>
Defined in: packages/core/src/client.ts:556
List jobs within a specific chain, in chain order. Defaults to ascending
order. Pass chainTypeName for type narrowing.
Type Parameters
Section titled “Type Parameters”TChainTypeName
Section titled “TChainTypeName”TChainTypeName extends JobTypeEntryNames<TJobTypeDefinitions> = JobTypeEntryNames<TJobTypeDefinitions>
Parameters
Section titled “Parameters”options
Section titled “options”object & Partial<GetStateAdapterTxContext<TStateAdapter>>
Returns
Section titled “Returns”Promise<Page<ResolvedChainJobs<TJobId, TJobTypeDefinitions, TChainTypeName>>>
Throws
Section titled “Throws”ChainTypeMismatchError if chainTypeName is provided and does not match.
listChains
Section titled “listChains”listChains: <
TChainTypeName>(options) =>Promise<Page<ResolvedChain<TJobId,TJobTypeDefinitions,TChainTypeName>>>
Defined in: packages/core/src/client.ts:505
List chains with filtering and cursor-based pagination. Defaults to orderDirection: "desc",
limit: 50, and orderBy: "completedAt" when status is "completed", "createdAt" otherwise.
Type Parameters
Section titled “Type Parameters”TChainTypeName
Section titled “TChainTypeName”TChainTypeName extends JobTypeEntryNames<TJobTypeDefinitions> = JobTypeEntryNames<TJobTypeDefinitions>
Parameters
Section titled “Parameters”options
Section titled “options”object & { orderBy?: "createdAt"; status?: undefined; } | { orderBy?: "createdAt"; status: "running"; } | { orderBy?: "createdAt" | "completedAt"; status: "completed"; } & Partial<GetStateAdapterTxContext<TStateAdapter>>
Returns
Section titled “Returns”Promise<Page<ResolvedChain<TJobId, TJobTypeDefinitions, TChainTypeName>>>
listChainTypeNames
Section titled “listChainTypeNames”listChainTypeNames: <
TChainTypeName>(options?) =>Promise<TChainTypeName[]>
Defined in: packages/core/src/client.ts:455
Returns distinct chain type names present in the data, sorted alphabetically.
Type Parameters
Section titled “Type Parameters”TChainTypeName
Section titled “TChainTypeName”TChainTypeName extends JobTypeEntryNames<TJobTypeDefinitions> = JobTypeEntryNames<TJobTypeDefinitions>
Parameters
Section titled “Parameters”options?
Section titled “options?”Partial<GetStateAdapterTxContext<TStateAdapter>>
Returns
Section titled “Returns”Promise<TChainTypeName[]>
listJobs
Section titled “listJobs”listJobs: <
TJobTypeName>(options) =>Promise<Page<ResolvedJob<TJobId,TJobTypeDefinitions,TJobTypeName>>>
Defined in: packages/core/src/client.ts:530
List jobs with filtering and cursor-based pagination. Defaults to orderDirection: "desc",
limit: 50, and an orderBy that follows status: scheduledAt for blocked/pending,
attemptAt for running, completedAt for completed, createdAt when unfiltered.
Type Parameters
Section titled “Type Parameters”TJobTypeName
Section titled “TJobTypeName”TJobTypeName extends JobTypeNames<TJobTypeDefinitions> = JobTypeNames<TJobTypeDefinitions>
Parameters
Section titled “Parameters”options
Section titled “options”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"; } & Partial<GetStateAdapterTxContext<TStateAdapter>>
Returns
Section titled “Returns”Promise<Page<ResolvedJob<TJobId, TJobTypeDefinitions, TJobTypeName>>>
listJobTypeNames
Section titled “listJobTypeNames”listJobTypeNames: <
TJobTypeName>(options?) =>Promise<TJobTypeName[]>
Defined in: packages/core/src/client.ts:465
Returns distinct job type names present in the data, sorted alphabetically.
Type Parameters
Section titled “Type Parameters”TJobTypeName
Section titled “TJobTypeName”TJobTypeName extends JobTypeNames<TJobTypeDefinitions> = JobTypeNames<TJobTypeDefinitions>
Parameters
Section titled “Parameters”options?
Section titled “options?”Partial<GetStateAdapterTxContext<TStateAdapter>>
Returns
Section titled “Returns”Promise<TJobTypeName[]>
rescheduleJob
Section titled “rescheduleJob”rescheduleJob: <
TJobTypeName>(options) =>Promise<ResolvedJob<TJobId,TJobTypeDefinitions,TJobTypeName>>
Defined in: packages/core/src/client.ts:321
Reschedule a pending job by setting its scheduledAt from the optional
schedule ({ at } | { afterMs }); omitting schedule reschedules to
now. Past times clamp to now.
Type Parameters
Section titled “Type Parameters”TJobTypeName
Section titled “TJobTypeName”TJobTypeName extends JobTypeNames<TJobTypeDefinitions> = JobTypeNames<TJobTypeDefinitions>
Parameters
Section titled “Parameters”options
Section titled “options”object & GetStateAdapterTxContext<TStateAdapter>
Returns
Section titled “Returns”Promise<ResolvedJob<TJobId, TJobTypeDefinitions, TJobTypeName>>
Throws
Section titled “Throws”JobNotFoundError if the job does not exist.
Throws
Section titled “Throws”JobNotReschedulableError if the job is not pending.
rescheduleJobs
Section titled “rescheduleJobs”rescheduleJobs: <
TJobTypeName>(options) =>Promise<ResolvedJob<TJobId,TJobTypeDefinitions,TJobTypeName>[]>
Defined in: packages/core/src/client.ts:340
Reschedule multiple pending jobs, setting each scheduledAt from the
optional schedule (omitted = now, past times clamped to now). Validation
is atomic — no job is rescheduled on failure. Returns jobs in input order.
Empty ids returns [].
Type Parameters
Section titled “Type Parameters”TJobTypeName
Section titled “TJobTypeName”TJobTypeName extends JobTypeNames<TJobTypeDefinitions> = JobTypeNames<TJobTypeDefinitions>
Parameters
Section titled “Parameters”options
Section titled “options”object & GetStateAdapterTxContext<TStateAdapter>
Returns
Section titled “Returns”Promise<ResolvedJob<TJobId, TJobTypeDefinitions, TJobTypeName>[]>
Throws
Section titled “Throws”JobsNotFoundError (batch variant listing every offending id) if any input is missing.
Throws
Section titled “Throws”JobsNotReschedulableError (batch variant listing every offending id) if any input is not pending.