Awaiting Chains
Wait for chains to complete with polling and notifications.
awaitChain waits for a chain to complete by combining polling with notify adapter events. Between polls, it listens for completion notifications to react immediately.
A chain's output is the output of its final job. Here fetch-price continues with apply-discount, so the chain resolves to the discounted price:
src/chain-awaiting.ts
const jobTypes = defineJobTypes<{
/*
* fetch-price --> apply-discount
*/
"fetch-price": {
entry: true;
input: { productId: string };
continueWith: { typeName: "apply-discount" };
};
"apply-discount": {
input: { productId: string; basePrice: number };
output: { productId: string; finalPrice: number };
};
}>();Create the chain, then await it once the transaction has committed. awaitChain takes the chain (or any { id }) and options: timeoutMs is required, and pollIntervalMs sets how often the database is polled between notifications (default 15 seconds). The completed chain carries the typed output of apply-discount:
src/chain-awaiting.ts
const priceChain = await stateAdapter.withTransaction(async (txCtx) =>
client.createChain({ ...txCtx, typeName: "fetch-price", input: { productId: "widget" } }),
);
const completedChain = await client.awaitChain(priceChain, {
timeoutMs: 30_000,
pollIntervalMs: 5_000,
});awaitChain runs outside any transaction, so several chains can be awaited concurrently:
src/chain-awaiting.ts
const priceChains = await stateAdapter.withTransaction(async (txCtx) =>
client.createChains({
...txCtx,
items: [
{ typeName: "fetch-price", input: { productId: "gadget" } },
{ typeName: "fetch-price", input: { productId: "gizmo" } },
],
}),
);
const completedChains = await Promise.all(
priceChains.map(async (chain) => client.awaitChain(chain, { timeoutMs: 30_000 })),
);signal accepts an AbortSignal, such as the signal of the incoming request that is waiting for the result. Both a timeout and an abort throw WaitChainTimeoutError, and the chain keeps running. Here laterChain is a fetch-price chain created with a one-minute deferred start, so the worker has not reached it yet and the request gives up on it:
src/chain-awaiting.ts
const request = new AbortController();
setTimeout(() => {
request.abort();
}, 100);
const laterPrice = await client
.awaitChain(laterChain, { timeoutMs: 30_000, signal: request.signal })
.then(
(chain) => chain.output.finalPrice,
(error: unknown) => {
if (error instanceof WaitChainTimeoutError) return undefined;
throw error;
},
);See examples/guides/src/chain-awaiting.ts for the runnable code. See also Notify Adapters for the completion notifications and Scheduling for deferred starts.