The best way to control Claude Code, Codex and more from any computer or phone
| 1 | --- |
| 2 | title: Saga |
| 3 | description: A process that spans several aggregates and takes time, run step by step as an Effect workflow, with steps that undo earlier ones when a later one fails. |
| 4 | --- |
| 5 | |
| 6 | import DAG from "../../../components/DAG.astro"; |
| 7 | |
| 8 | A saga runs a process that spans several aggregates. An aggregate changes one instance at a time, and no transaction spans two, so a process that touches several runs as a series of steps, each committed on its own. When a step fails after earlier ones succeeded, the saga undoes them with compensations. |
| 9 | |
| 10 | A saga is an [Effect workflow](https://effect.website/docs/workflow). Each step's result is stored, so a run that's interrupted resumes after its last finished step, and a run can wait hours or days for a signal or a timer. A policy usually decides when to start one. |
| 11 | |
| 12 | In the example bank, a transfer is a saga: it debits one account, credits another, and refunds the debit if the credit fails. |
| 13 | |
| 14 | <DAG |
| 15 | nodes={[ |
| 16 | { id: "request", label: "RequestTransfer", type: "command", kind: "command", col: 0, row: 0 }, |
| 17 | { id: "transfer", label: "Transfer", type: "records the request", kind: "aggregate", col: 1, row: 0 }, |
| 18 | { id: "policy", label: "TransferExecution", type: "starts the saga", kind: "policy", col: 2, row: 0 }, |
| 19 | { id: "saga", label: "ExecuteTransfer", type: "runs the steps", kind: "saga", col: 3, row: 0 }, |
| 20 | { id: "debit", label: "DebitTransfer", type: "1 · source account", kind: "command", col: 3, row: 1 }, |
| 21 | { id: "credit", label: "CreditTransfer", type: "2 · destination", kind: "command", col: 3, row: 2 }, |
| 22 | ]} |
| 23 | edges={[ |
| 24 | { from: "request", to: "transfer" }, |
| 25 | { from: "transfer", to: "policy" }, |
| 26 | { from: "policy", to: "saga" }, |
| 27 | { from: "saga", to: "debit" }, |
| 28 | { from: "saga", to: "credit" }, |
| 29 | ]} |
| 30 | caption="A policy decides when the transfer runs; the saga carries it out, one step at a time." |
| 31 | /> |
| 32 | |
| 33 | This chapter starts with why a process across aggregates can't be one transaction, and what to do instead. Then it builds the transfer saga step by step. |
| 34 | |
| 35 | ## No transaction spans two aggregates |
| 36 | |
| 37 | Moving money between two accounts touches two aggregates, and each is its own consistency boundary. There's no step in which both change together. So a transfer can't be "debit and credit, or neither", the way a database transaction would make it. |
| 38 | |
| 39 | Instead, it's a sequence of steps, each committed on its own: debit the source, then credit the destination. In between, the money is in flight. It has left one account and not yet reached the other, and anyone reading both balances at that moment sees it. That's not a bug to hide; it's how money moves in real banks too, and the `Transfer` aggregate records that the transfer is pending so screens can show it. |
| 40 | |
| 41 | ## Undo with a new fact, not an erasure |
| 42 | |
| 43 | When a later step fails, the earlier ones have already happened. Their events are facts and can't be erased. So the saga undoes them the way a business would, by recording another fact that reverses the effect: a debited transfer whose credit is refused is refunded, and the account's history shows the debit and the refund, one after the other. |
| 44 | |
| 45 | <DAG |
| 46 | nodes={[ |
| 47 | { id: "debited", label: "TransferDebited", type: "a-1 · −50", kind: "event", col: 0, row: 0 }, |
| 48 | { id: "refused", label: "CreditTransfer", type: "a-2 is closed", kind: "rejection", col: 1, row: 0 }, |
| 49 | { id: "refunded", label: "TransferRefunded", type: "a-1 · +50", kind: "event", col: 2, row: 0 }, |
| 50 | ]} |
| 51 | edges={[ |
| 52 | { from: "debited", to: "refused" }, |
| 53 | { from: "refused", to: "refunded" }, |
| 54 | ]} |
| 55 | caption="A compensation doesn't rewrite history. It adds the step that puts things right." |
| 56 | /> |
| 57 | |
| 58 | These undo steps are called **compensations**. Each step that can be undone declares its compensation next to it, and a saga that fails runs them in reverse order. A compensation must not be refused, or the process would be stuck halfway, so the command it sends records a fact in every state. See [Never refuse a compensation](/domain/aggregate#never-refuse-a-compensation). |
| 59 | |
| 60 | ## Saga or policy? |
| 61 | |
| 62 | A [policy](/domain/policy) is one reaction: an event arrives, the policy acts, and it's done. A saga is a process with memory. It knows which step it's on, waits between steps, and knows what to undo if something fails. |
| 63 | |
| 64 | Reach for a saga when a process has more than one step, waits for something, a decision or a timer, or has to undo earlier steps on failure. A policy usually starts the saga, on the event that records the request. |
| 65 | |
| 66 | ## Declare a saga |
| 67 | |
| 68 | A saga has a key, the input it starts with, and every way it can be refused. The key identifies one run: starting the saga again with the same transfer id returns the same run. |
| 69 | |
| 70 | ```typescript title="packages/domain/src/Transfer/ExecuteTransfer.saga.ts" |
| 71 | export class ExecuteTransfer extends Domain.Saga("ExecuteTransfer", { |
| 72 | key: TransferId, |
| 73 | input: { |
| 74 | from: AccountId, |
| 75 | to: AccountId, |
| 76 | amount: Cents, |
| 77 | requestedBy: Actor, |
| 78 | needsApproval: Schema.Boolean, |
| 79 | }, |
| 80 | rejects: [NotOpen, NotOwner, Frozen, InsufficientFunds, DestinationClosed], |
| 81 | }) {} |
| 82 | ``` |
| 83 | |
| 84 | ## Run its steps |
| 85 | |
| 86 | Its Layer resolves the clients its steps use, then returns what each run does. Each step is an `Activity`: a named Effect whose result is stored. When the run replays, a finished step returns its stored result instead of running again. |
| 87 | |
| 88 | ```typescript title="packages/domain/src/Transfer/ExecuteTransfer.saga.ts" |
| 89 | yield* Activity.make({ |
| 90 | name: "credit", |
| 91 | error: DestinationClosed, |
| 92 | execute: accounts |
| 93 | .send(to, new CreditTransfer({ transferId: key, amount })) |
| 94 | .pipe(Effect.catchTag("NotOpen", () => Effect.fail(new DestinationClosed()))), |
| 95 | }); |
| 96 | ``` |
| 97 | |
| 98 | A step declares the errors it can fail with, so a refusal survives being stored. Here the destination account's `NotOpen` becomes the saga's own `DestinationClosed`. |
| 99 | |
| 100 | A step that runs again is safe. A step can run twice: when it's retried, or when its run is cut short after the step's command committed but before its result was stored. The commands a step sends get ids derived from the run and the step, so the second run sends the same command ids, and the aggregate applies each command once. Keep each step to one command, so each stored result matches one fact. |
| 101 | |
| 102 | ## Undo a step when a later one fails |
| 103 | |
| 104 | A step can carry a compensation: what to do if the run fails after the step succeeded. The debit's compensation refunds it. |
| 105 | |
| 106 | ```typescript title="packages/domain/src/Transfer/ExecuteTransfer.saga.ts" |
| 107 | yield* Activity.make({ |
| 108 | name: "debit", |
| 109 | error: Schema.Union([NotOpen, NotOwner, Frozen, InsufficientFunds]), |
| 110 | execute: accounts.send(from, new DebitTransfer({ transferId: key, amount, requestedBy })), |
| 111 | }).pipe( |
| 112 | ExecuteTransfer.withCompensation(() => |
| 113 | Activity.make({ |
| 114 | name: "refund", |
| 115 | execute: accounts.send(from, new RefundTransfer({ transferId: key, amount })), |
| 116 | }), |
| 117 | ), |
| 118 | ); |
| 119 | ``` |
| 120 | |
| 121 | When the credit is refused, the run fails, and every compensation registered so far runs, last step first. |
| 122 | |
| 123 | <DAG |
| 124 | nodes={[ |
| 125 | { id: "debit", label: "DebitTransfer", type: "succeeded", kind: "command", col: 0, row: 0 }, |
| 126 | { id: "credit", label: "CreditTransfer", type: "refused", kind: "command", col: 1, row: 0 }, |
| 127 | { id: "closed", label: "DestinationClosed", type: "the saga fails", kind: "rejection", col: 2, row: 0 }, |
| 128 | { id: "refund", label: "RefundTransfer", type: "undoes the debit", kind: "command", col: 2, row: 1 }, |
| 129 | ]} |
| 130 | edges={[ |
| 131 | { from: "debit", to: "credit" }, |
| 132 | { from: "credit", to: "closed" }, |
| 133 | { from: "closed", to: "refund" }, |
| 134 | ]} |
| 135 | /> |
| 136 | |
| 137 | ## Take the step you can't undo first |
| 138 | |
| 139 | Debit before you credit. If the credit then fails, the money is refunded, so it can be in flight but never created out of nothing. In the same way, registration claims the username before the customer counts as registered: see [Unique values](/domain/unique-values). |
| 140 | |
| 141 | ## Record the outcome |
| 142 | |
| 143 | The Transfer aggregate shows where every transfer stands, so the saga reports back to it. The last step completes the transfer: |
| 144 | |
| 145 | ```typescript title="packages/domain/src/Transfer/ExecuteTransfer.saga.ts" |
| 146 | yield* Activity.make({ |
| 147 | name: "complete", |
| 148 | execute: transfers.send(key, new CompleteTransfer()), |
| 149 | }); |
| 150 | ``` |
| 151 | |
| 152 | A failure is recorded by a finalizer. It's registered first, so it runs after every compensation: |
| 153 | |
| 154 | ```typescript title="packages/domain/src/Transfer/ExecuteTransfer.saga.ts" |
| 155 | yield* Workflow.addFinalizer((exit) => |
| 156 | Exit.isSuccess(exit) |
| 157 | ? Effect.void |
| 158 | : Activity.make({ |
| 159 | name: "record-failure", |
| 160 | execute: transfers.send(key, new FailTransfer({ reason: reasonOf(exit.cause) })), |
| 161 | }).pipe(Effect.orDie), |
| 162 | ); |
| 163 | ``` |
| 164 | |
| 165 | ## Start it from a policy |
| 166 | |
| 167 | Start a saga from a policy, on the event that records the request. The command that asked for the transfer commits `TransferRequested` and replies straight away; the policy starts the saga after that, and the saga runs on its own. Nobody waits for it. |
| 168 | |
| 169 | <DAG |
| 170 | nodes={[ |
| 171 | { id: "request", label: "RequestTransfer", type: "replies at once", kind: "command", col: 0, row: 0 }, |
| 172 | { id: "transfer", label: "Transfer", type: "records the request", kind: "aggregate", col: 1, row: 0 }, |
| 173 | { id: "requested", label: "TransferRequested", type: "the fact", kind: "event", col: 2, row: 0 }, |
| 174 | { id: "policy", label: "TransferExecution", type: "starts it, later", kind: "policy", col: 2, row: 1 }, |
| 175 | { id: "saga", label: "ExecuteTransfer", type: "runs on its own", kind: "saga", col: 1, row: 1 }, |
| 176 | ]} |
| 177 | edges={[ |
| 178 | { from: "request", to: "transfer" }, |
| 179 | { from: "transfer", to: "requested" }, |
| 180 | { from: "requested", to: "policy", dashed: true }, |
| 181 | { from: "policy", to: "saga" }, |
| 182 | ]} |
| 183 | caption="The request is a fact before the process starts, so it's never lost, and the caller never waits for the process." |
| 184 | /> |
| 185 | |
| 186 | `yield* ExecuteTransfer` gives the saga's client. `start` begins a run, or returns the one already started with that key, as a handle to the run. Policies run at least once, so key the saga by the aggregate it's about: a policy that runs twice still starts one transfer. |
| 187 | |
| 188 | ```typescript title="packages/domain/src/Transfer/TransferExecution.policy.ts" |
| 189 | case "TransferRequested": |
| 190 | yield* executions.start(source, { |
| 191 | from: event.from, |
| 192 | to: event.to, |
| 193 | amount: event.amount, |
| 194 | requestedBy: event.requestedBy, |
| 195 | needsApproval: event.needsApproval, |
| 196 | }); |
| 197 | return; |
| 198 | ``` |
| 199 | |
| 200 | List the saga on the model, next to its aggregates and policies, and its Layer with the other handlers. |
| 201 | |
| 202 | ```typescript title="packages/domain/src/Bank.model.ts" |
| 203 | sagas: [ExecuteTransfer], |
| 204 | ``` |
| 205 | |
| 206 | ## Don't wait for it in a policy |
| 207 | |
| 208 | `start` returns as soon as the run is recorded. Its run handle also has `result`, which waits for the run to finish, but a run can take days, and a policy that waits holds up every later event on its key. Use `result` in tests and scripts. Anything that needs to react to how a saga ends should react to the events it reports instead, like `TransferCompleted` or `TransferFailed`. |
| 209 | |
| 210 | ## Wait for a decision |
| 211 | |
| 212 | A run can wait as long as it needs to. A large transfer waits until the Transfer decides it: an agent approves it, or its approval window closes first. The saga waits on a `DurableDeferred`, and suspends until someone completes it. |
| 213 | |
| 214 | ```typescript title="packages/domain/src/Transfer/ExecuteTransfer.saga.ts" |
| 215 | if (needsApproval) { |
| 216 | // The Transfer decides between approval and expiry; nothing to do if it expired. |
| 217 | if ((yield* DurableDeferred.await(Decision)) === "expired") return; |
| 218 | } |
| 219 | ``` |
| 220 | |
| 221 | The policy passes on the decision with the run's `signal`. `get` returns the run with a key: |
| 222 | |
| 223 | ```typescript title="packages/domain/src/Transfer/TransferExecution.policy.ts" |
| 224 | case "TransferApproved": |
| 225 | return yield* executions.get(source).signal(Decision, "approved"); |
| 226 | ``` |
| 227 | |
| 228 | The Transfer decides the race between approval and expiry, so there's one source of truth for it. See [Deadlines](/domain/deadlines). |
| 229 | |
| 230 | ## Follow it |
| 231 | |
| 232 | `TransferStatus` is a view of the transfer and both accounts. A client watches it to see the saga finish: the saga reports every step to the Transfer, so the view has everything a client should see. |
| 233 | |
| 234 | ```typescript title="packages/server/test/followTransfer.ts" |
| 235 | export const followTransfer = Effect.fn(function* (bank: CustomerClient, transferId: string) { |
| 236 | yield* bank.TransferStatus.watch(TransferId.make(transferId)).pipe( |
| 237 | Stream.map(({ state }) => state), |
| 238 | Stream.takeUntil((status) => status?.completedAt !== null || status?.failedReason !== null), |
| 239 | Stream.runForEach((status) => |
| 240 | Effect.log(status === null ? "pending" : TransferStatus.computed.status(status)), |
| 241 | ), |
| 242 | ); |
| 243 | }); |
| 244 | ``` |
| 245 | |
| 246 | The saga's own client reads a run too, which suits operators and tests more than apps. `get` returns the run with a key: |
| 247 | |
| 248 | ```typescript |
| 249 | const run = executions.get(transferId); |
| 250 | const status = yield* run.status; |
| 251 | ``` |
| 252 | |
| 253 | `status` is `NotStarted`, `Running`, `Completed` with its result, `Rejected` with its rejection, `Interrupted`, or `Died` with a defect. Runs read the same as [Effect workflow runs](/cloudflare/compute/effect-workflows), on every engine. |
| 254 | |
| 255 | ## Test it |
| 256 | |
| 257 | A story runs the whole saga in memory: the request, every step, the compensations, and its status at the end. |
| 258 | |
| 259 | Test what a saga does, not how it's built: the commands its steps send show up as events on the aggregates, and `Story.saga` checks how the run ended, with the same status its run handle reads. |
| 260 | |
| 261 | ```typescript title="packages/domain/test/transfers.test.ts" |
| 262 | Story.saga(ExecuteTransfer, transfer, { _tag: "Rejected", rejection: new DestinationClosed() }), |
| 263 | ``` |
| 264 | |
| 265 | To test a saga on its own, complete what it waits for with `Story.signal`, and move its durable clocks with `Story.clock`: |
| 266 | |
| 267 | ```typescript |
| 268 | Story.saga(ExecuteTransfer, transfer, { _tag: "Running" }), |
| 269 | Story.signal(ExecuteTransfer, transfer, Decision, "approved"), |
| 270 | ``` |
| 271 | |
| 272 | A step that calls an external system waits until the story answers the call, as a policy does. A run that dies fails the story, unless a step expects it with `Story.saga(ExecuteTransfer, transfer, { _tag: "Died" })`. |
| 273 | |
| 274 | A saga runs wherever its model runs: in memory in a story, and on [Cloudflare Durable Objects](/domain/cloudflare) in production, with each run's steps stored durably. |
| 275 | |
| 276 | Next, [External System](/domain/external-system): how the model talks to the world outside it. |