Job Blockers
Fan-out/fan-in job dependencies.
Jobs can depend on other chains to complete before they start. A job with incomplete blockers starts as blocked and transitions to pending when all blockers complete.
process-all declares its blockers as a tuple with a rest element, so it waits for one or more fetch-data chains:
src/job-blockers.ts
const jobTypes = defineJobTypes<{
/*
* fetch-data #1 --+
* fetch-data #2 --+--> process-all
* fetch-data #3 --+
*/
"fetch-data": {
entry: true;
input: { url: string };
output: { data: string };
};
"process-all": {
entry: true;
input: { reportId: string };
output: { results: string[] };
blockers: [{ typeName: "fetch-data" }, ...{ typeName: "fetch-data" }[]];
};
}>();Create the blocker chains and the blocked chain in one transaction, passing the created chains as blockers:
src/job-blockers.ts
const reportChain = await stateAdapter.withTransaction(async (txCtx) => {
const fetchChains = await client.createChains({
...txCtx,
items: [
{ typeName: "fetch-data", input: { url: "/users" } },
{ typeName: "fetch-data", input: { url: "/orders" } },
{ typeName: "fetch-data", input: { url: "/products" } },
],
});
return client.createChain({
...txCtx,
typeName: "process-all",
input: { reportId: "report-1" },
blockers: fetchChains,
});
});Once every blocker completes, the processor reads their typed outputs from job.blockers:
src/job-blockers.ts
"process-all": {
attemptHandler: async ({ job, complete }) => {
const results = job.blockers.map((blocker) => blocker.output.data);
return stateAdapter.withTransaction(async (txCtx) =>
complete({ ...txCtx, output: { results } }),
);
},
},Passing Blockers by ID
Often the blocker chain was created earlier and only its ID was saved. Think of an entity that works like a state machine: an order in the awaiting_payment state stores the ID of the capture-payment chain that moves it forward, and that chain clears it when it marks the order paid. Shipping reads the order in the same transaction and waits on the stored ID only while payment is still pending:
src/job-blockers.ts
const shipChain = await stateAdapter.withTransaction(async (txCtx) => {
const order = orders.get("order-1")!;
return client.createChain({
...txCtx,
typeName: "ship-order",
input: { orderId: "order-1" },
blockers:
order.status === "awaiting_payment" && order.paymentChainId !== null
? [{ id: order.paymentChainId }]
: [],
});
});Only keep the ID while the chain is still running: a completed chain can be removed by cleanup, and a missing blocker chain throws ChainNotFoundError.
Blocker References
The first example uses nominal references — { typeName: "fetch-data" }. Blockers also support fixed tuple slots, variadic rest slots, and structural references ({ input: {...} }) that match any entry job type with a compatible input shape. Blocker outputs are fully typed in the processor based on the reference. See Job Type References for details and examples.
Blocker Limit
A single job may declare at most 100 blocker chains by default. Declaring more throws BlockerLimitExceededError before any state is written. The limit belongs to the state adapter — pass maxBlockersPerJob to the state adapter factory to raise or lower it. Keep it bounded: the blocker model is built for fan-in of a bounded set of dependencies, not millions per job.
See examples/guides/src/job-blockers.ts for the runnable code. See also Tx Hooks and Chain Patterns.