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.

awaitChain()
wait loop
poll the DBevery pollIntervalMs
listenwakes the loop early
chaincompletedreturns the output
timeout / abortthrows

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.

esc

Search guides, integrations and every exported symbol.

↑ ↓ to navigate↵ to open