Job, Chain & Worker Queries

Read-only methods for inspecting jobs, chains and workers.

The client provides read-only methods for inspecting chains, jobs and workers. The examples below query an order workflow: a reserve-stock chain blocks a process-order chain, which continues to ship-order.

Lookups

Look up a single chain or job by ID, or a batch of them in one round trip. Batch lookups return a positional array with undefined for each missing ID:

src/queries.ts

const chain = await client.getChain({ id: orderChain.id, typeName: "process-order" });
const job = await client.getJob({ id: orderChain.id });

const chains = await client.getChains({ ids: [orderChain.id, stockChain.id, "missing-id"] });
const jobs = await client.getJobs({ ids: [orderChain.id, stockChain.id] });

getChain, getChains, getJob, getJobs, getJobBlockers, and listBlockedJobs accept an optional typeName for type narrowing (listChainJobs, getChainTailJob and getChainTailJobs take chainTypeName) — the return type narrows to the specified type, so a completed process-order chain exposes its typed output. If the entity exists but has a different type, ChainTypeMismatchError or JobTypeMismatchError is thrown.

All query methods accept an optional transaction context in which every field is optional, so a read needs only the transaction handle, not the txHooks some providers carry in their context:

src/queries.ts

const chainInTransaction = await stateAdapter.withTransaction(async (txCtx) =>
  client.getChain({ ...txCtx, id: orderChain.id }),
);

Types and Counts

Discover which chain and job types exist in the data, and get per-status counts for specific types:

src/queries.ts

const chainTypeNames = await client.getChainTypeNames();
const jobTypeNames = await client.getJobTypeNames();

const [orderChainCounts] = await client.countChainsByTypeName({ typeNames: ["process-order"] });
const [shipJobCounts] = await client.countJobsByTypeName({ typeNames: ["ship-order"] });

Paginated Lists

listChains and listJobs require typeName and filter by it. Pass the previous page's nextCursor to read the next page:

src/queries.ts

const firstPage = await client.listChains({
  typeName: "process-order",
  status: "completed",
  limit: 1,
});
const secondPage = await client.listChains({
  typeName: "process-order",
  status: "completed",
  cursor: firstPage.nextCursor ?? undefined,
  limit: 1,
});

const shipJobs = await client.listJobs({
  typeName: "ship-order",
  status: "completed",
  orderBy: "createdAt",
});

listChains and listJobs route queries to status-specific indexes based on the status and orderBy combination. Each status has a natural default sort order — for example, completed chains default to completedAt descending, pending and blocked jobs to scheduledAt descending. Pass orderBy: "createdAt" to override.

Chain Jobs

listChainJobs lists the jobs within a chain in chain order. A chain's tail job is its latest job in chain order, and the head job while the chain has not continued; getChainTailJobs returns one entry per requested chain ID, undefined for a missing chain:

src/queries.ts

const chainJobs = await client.listChainJobs({
  chainId: orderChain.id,
  chainTypeName: "process-order",
});

const tailJob = await client.getChainTailJob({ chainId: orderChain.id });
const tailJobs = await client.getChainTailJobs({ chainIds: [orderChain.id, stockChain.id] });

getChainTailJob and getChainTailJobs are experimental: they may change in a minor release.

Blockers

Inspect blocker relationships from both directions: getJobBlockers returns the chains a job waits on, and listBlockedJobs lists the jobs a chain blocks:

src/queries.ts

const blockers = await client.getJobBlockers({ jobId: orderChain.id, typeName: "process-order" });
const blockedJobs = await client.listBlockedJobs({ chainId: stockChain.id });

Workers

Look up workers by ID (undefined for a worker with no row), count live and expired workers overall and per job type, and list the jobs running under a worker:

src/queries.ts

const workerPage = await client.listWorkers({ limit: 20 });
const workerId = workerPage.items[0].id;

const worker = await client.getWorker({ id: workerId });
const { live, expired } = await client.countWorkers();
const [shipWorkers] = await client.countWorkersByTypeName({ typeNames: ["ship-order"] });
const [runningJobCount] = await client.countRunningJobsByWorkerId({ workerIds: [workerId] });
const runningJobs = await client.listWorkerJobs({ workerId });

listWorkers orders workers by startedAt and optionally keeps only those processing a typeName; listWorkerJobs orders jobs by attemptAt. Both sort by that column, then id, ascending unless orderDirection says otherwise, and take no orderBy.

See examples/guides/src/queries.ts for the runnable code. See also the Client API reference and Dashboard.

esc

Search guides, integrations and every exported symbol.

↑ ↓ to navigate↵ to open