Chain Patterns

Linear, branched, loop, and go-to patterns.

Chains support various execution patterns via continueWith:

  • Linear — continueWith returns the next type
  • Branched — continueWith returns one of a union of types
  • Loop — continueWith returns the same type until a terminal output
  • Go-to — continueWith jumps to a different type, skipping intermediates

A subscription lifecycle uses all four. Each job type lists the types it may continue with, and a type that declares output can end the chain:

src/chain-patterns.ts

const jobTypes = defineJobTypes<{
  /*
   * activate-trial --> trial-decision --+--> expire-trial
   *                                     |
   *                                     +--> charge-billing <--+
   *                                               |            |
   *                                               +---(loop)---+
   *                                               |
   *                                               +--> cancel-subscription
   */
  "activate-trial": {
    entry: true;
    input: { subscriptionId: string };
    continueWith: { typeName: "trial-decision" };
  };
  "trial-decision": {
    input: { subscriptionId: string };
    continueWith: { typeName: "charge-billing" | "expire-trial" };
  };
  "expire-trial": {
    input: { subscriptionId: string };
    output: { expired: true };
  };
  "charge-billing": {
    input: { subscriptionId: string; cycle: number };
    output: { cyclesCharged: number };
    continueWith: { typeName: "charge-billing" | "cancel-subscription" };
  };
  "cancel-subscription": {
    input: { subscriptionId: string; cyclesCharged: number };
    output: { cancelledAfterCycles: number };
  };
}>();

Linear

activate-trial
continueWith
trial-decision

Jobs execute one after another: activate-trial marks the subscription as on trial and continues with trial-decision in the same transaction:

src/chain-patterns.ts

"activate-trial": {
  attemptHandler: async ({ job, complete }) =>
    stateAdapter.withTransaction(async (txCtx) => {
      subscriptions.get(job.input.subscriptionId)!.status = "trial";
      return complete({
        ...txCtx,
        continueWith: {
          typeName: "trial-decision",
          input: { subscriptionId: job.input.subscriptionId },
        },
      });
    }),
},

Branched

trial-decision
charge-billing
expire-trial

trial-decision declares a union in continueWith and picks one branch at runtime: a subscription with a card on file goes to billing, the rest expire:

src/chain-patterns.ts

"trial-decision": {
  attemptHandler: async ({ job, complete }) =>
    stateAdapter.withTransaction(async (txCtx) => {
      const subscription = subscriptions.get(job.input.subscriptionId)!;
      return complete({
        ...txCtx,
        continueWith: subscription.cardOnFile
          ? {
              typeName: "charge-billing",
              input: { subscriptionId: job.input.subscriptionId, cycle: 1 },
            }
          : {
              typeName: "expire-trial",
              input: { subscriptionId: job.input.subscriptionId },
            },
      });
    }),
},

Loops

charge-billing
continueWith itself
output
chaincompleted

charge-billing lists itself in continueWith, so each cycle continues with the next one until the last cycle completes with its terminal output. The first if is the jump covered in Go-to:

src/chain-patterns.ts

"charge-billing": {
  attemptHandler: async ({ job, complete }) =>
    stateAdapter.withTransaction(async (txCtx) => {
      const subscription = subscriptions.get(job.input.subscriptionId)!;
      if (subscription.cancelRequested) {
        return complete({
          ...txCtx,
          continueWith: {
            typeName: "cancel-subscription",
            input: {
              subscriptionId: job.input.subscriptionId,
              cyclesCharged: subscription.cyclesCharged,
            },
          },
        });
      }
      subscription.status = "active";
      subscription.cyclesCharged = job.input.cycle;
      if (job.input.cycle < billingCycles) {
        return complete({
          ...txCtx,
          continueWith: {
            typeName: "charge-billing",
            input: { subscriptionId: job.input.subscriptionId, cycle: job.input.cycle + 1 },
          },
        });
      }
      subscription.status = "ended";
      return complete({ ...txCtx, output: { cyclesCharged: job.input.cycle } });
    }),
},

Go-to

charge-billing
loop
jump
cancel-subscription

Because charge-billing also lists cancel-subscription, any cycle can jump out of the loop. When the subscriber asked to cancel, the job continues with cancel-subscription and skips the remaining cycles:

src/chain-patterns.ts

if (subscription.cancelRequested) {
  return complete({
    ...txCtx,
    continueWith: {
      typeName: "cancel-subscription",
      input: {
        subscriptionId: job.input.subscriptionId,
        cyclesCharged: subscription.cyclesCharged,
      },
    },
  });
}

Continuation References

All examples above use nominal references — { typeName: "..." }. Queuert also supports structural references ({ input: {...} }) that match any job type with a compatible input shape, enabling loose coupling. See Job Type References for details and examples.

See examples/guides/src/chain-patterns.ts for the runnable code. See also Job Blockers for parallel dependencies and Chain Model for how chains and their jobs are modelled.

esc

Search guides, integrations and every exported symbol.

↑ ↓ to navigate↵ to open