The best way to control Claude Code, Codex and more from any computer or phone
| 1 | --- |
| 2 | title: "Part 1: Model an account" |
| 3 | description: Declare events, commands and rejections, decide them in an aggregate, and check it with stories. |
| 4 | sidebar: |
| 5 | order: 1 |
| 6 | --- |
| 7 | |
| 8 | Build a bank in eight parts, starting with an account that opens, takes deposits and refuses overdrafts. This part runs on your machine: no cloud account needed yet. |
| 9 | |
| 10 | If commands, aggregates and events are new to you, read [What is Domain-Driven Design?](/domain/what-is-ddd) first. |
| 11 | |
| 12 | ## Install |
| 13 | |
| 14 | ```sh |
| 15 | bun add alchemy @alchemy.run/domain effect |
| 16 | bun add -d vitest @effect/vitest |
| 17 | ``` |
| 18 | |
| 19 | ## Give your coding agent the skill |
| 20 | |
| 21 | ```sh |
| 22 | bun add -d skills-npm |
| 23 | bunx skills-npm setup |
| 24 | ``` |
| 25 | |
| 26 | alchemy ships an `alchemy-domain` skill, and `skills-npm` links it into your coding agent's skills folder on every install, matching the alchemy version you have. Your agent then knows the building blocks and conventions this tutorial uses. For other ways to install it, see [Build it with your coding agent](/domain#build-it-with-your-coding-agent). |
| 27 | |
| 28 | ## Name account ids |
| 29 | |
| 30 | ```typescript |
| 31 | // src/Account.id.ts |
| 32 | import * as Schema from "effect/Schema"; |
| 33 | |
| 34 | export const AccountId = Schema.String.pipe(Schema.brand("AccountId")); |
| 35 | ``` |
| 36 | |
| 37 | A branded id keeps an account id from being mixed up with any other string. The commands and the account all use it, so it gets a file of its own. |
| 38 | |
| 39 | ## Record that an account opened |
| 40 | |
| 41 | ```typescript |
| 42 | // src/OpenAccount.command.ts |
| 43 | import * as Domain from "@alchemy.run/domain"; |
| 44 | import * as Schema from "effect/Schema"; |
| 45 | |
| 46 | export class AccountOpened extends Domain.Event("AccountOpened", { owner: Schema.String }) {} |
| 47 | ``` |
| 48 | |
| 49 | An event is a fact, named in the past tense. Everything the account knows will come from its events. |
| 50 | |
| 51 | Each command gets a file named after it, with a `.command.ts` suffix, holding the command, the events it records and the rejections only it returns. This event is what `OpenAccount` records, so it starts `src/OpenAccount.command.ts`. |
| 52 | |
| 53 | ## Refuse to open an account twice |
| 54 | |
| 55 | ```diff lang="typescript" |
| 56 | // src/OpenAccount.command.ts |
| 57 | |
| 58 | export class AccountOpened extends Domain.Event("AccountOpened", { owner: Schema.String }) {} |
| 59 | + |
| 60 | +export class AlreadyOpen extends Domain.Rejection("AlreadyOpen") {} |
| 61 | ``` |
| 62 | |
| 63 | A rejection is a typed reason to say no. Callers receive it exactly as declared. |
| 64 | |
| 65 | ## Ask to open an account |
| 66 | |
| 67 | ```diff lang="typescript" |
| 68 | // src/OpenAccount.command.ts |
| 69 | import * as Domain from "@alchemy.run/domain"; |
| 70 | import * as Schema from "effect/Schema"; |
| 71 | +import { AccountId } from "./Account.id.ts"; |
| 72 | |
| 73 | export class AccountOpened extends Domain.Event("AccountOpened", { owner: Schema.String }) {} |
| 74 | |
| 75 | export class AlreadyOpen extends Domain.Rejection("AlreadyOpen") {} |
| 76 | + |
| 77 | +export class OpenAccount extends Domain.Command("OpenAccount", { |
| 78 | + target: AccountId, |
| 79 | + input: { owner: Schema.String }, |
| 80 | + events: [AccountOpened], |
| 81 | + rejects: [AlreadyOpen], |
| 82 | +}) {} |
| 83 | ``` |
| 84 | |
| 85 | A command asks one account for a change. It lists every event it may record and every rejection it may return. |
| 86 | |
| 87 | ## Declare the account |
| 88 | |
| 89 | ```typescript |
| 90 | // src/Account.aggregate.ts |
| 91 | import * as Domain from "@alchemy.run/domain"; |
| 92 | import * as Schema from "effect/Schema"; |
| 93 | import { AccountId } from "./Account.id.ts"; |
| 94 | import { AccountOpened, AlreadyOpen, OpenAccount } from "./OpenAccount.command.ts"; |
| 95 | |
| 96 | const State = Schema.Union([ |
| 97 | Schema.TaggedStruct("Unopened", {}), |
| 98 | Schema.TaggedStruct("Open", { owner: Schema.String, balance: Schema.Int }), |
| 99 | ]); |
| 100 | type State = typeof State.Type; |
| 101 | |
| 102 | export class Account extends Domain.Aggregate("Account", { |
| 103 | id: AccountId, |
| 104 | state: State, |
| 105 | initial: { _tag: "Unopened" }, |
| 106 | commands: [OpenAccount], |
| 107 | decide: { |
| 108 | OpenAccount: (s, cmd) => |
| 109 | s._tag !== "Unopened" ? new AlreadyOpen() : [new AccountOpened({ owner: cmd.owner })], |
| 110 | }, |
| 111 | evolve: { |
| 112 | AccountOpened: (_, e) => ({ _tag: "Open" as const, owner: e.owner, balance: 0 }), |
| 113 | }, |
| 114 | }) {} |
| 115 | ``` |
| 116 | |
| 117 | The account is an aggregate. `decide` takes a command and the current state, and returns events or a rejection. `evolve` folds each event into the next state. |
| 118 | |
| 119 | ## Group it in a model |
| 120 | |
| 121 | ```typescript |
| 122 | // src/Bank.model.ts |
| 123 | import * as Domain from "@alchemy.run/domain"; |
| 124 | import { Account } from "./Account.aggregate.ts"; |
| 125 | |
| 126 | export class Bank extends Domain.Model("Bank", { |
| 127 | aggregates: [Account], |
| 128 | }) {} |
| 129 | ``` |
| 130 | |
| 131 | A model is everything you host together. You'll add views and policies to it in the next parts. |
| 132 | |
| 133 | ## Test opening an account |
| 134 | |
| 135 | ```typescript |
| 136 | // test/Account.test.ts |
| 137 | import { it } from "@effect/vitest"; |
| 138 | import { Story } from "@alchemy.run/domain/Story"; |
| 139 | import { Account } from "../src/Account.aggregate.ts"; |
| 140 | import { Bank } from "../src/Bank.model.ts"; |
| 141 | import { AccountOpened, AlreadyOpen, OpenAccount } from "../src/OpenAccount.command.ts"; |
| 142 | |
| 143 | const story = Story.make(Bank); |
| 144 | const account = Account.ref("a-1"); |
| 145 | |
| 146 | it.effect("opens an account", () => |
| 147 | story( |
| 148 | Story.when(account, new OpenAccount({ owner: "sam" })), |
| 149 | Story.then(account, new AccountOpened({ owner: "sam" })), |
| 150 | ), |
| 151 | ); |
| 152 | |
| 153 | it.effect("refuses to open an account twice", () => |
| 154 | story( |
| 155 | Story.given(account, new AccountOpened({ owner: "sam" })), |
| 156 | Story.when(account, new OpenAccount({ owner: "sam" })), |
| 157 | Story.rejected(new AlreadyOpen()), |
| 158 | ), |
| 159 | ); |
| 160 | ``` |
| 161 | |
| 162 | A story runs your model in memory. `given` sets up history, `when` sends a command, and `then` and `rejected` check the outcome. |
| 163 | |
| 164 | ```sh |
| 165 | bun vitest run |
| 166 | ``` |
| 167 | |
| 168 | Both stories pass. |
| 169 | |
| 170 | ## Record deposits |
| 171 | |
| 172 | ```typescript |
| 173 | // src/DepositMoney.command.ts |
| 174 | import * as Domain from "@alchemy.run/domain"; |
| 175 | import * as Schema from "effect/Schema"; |
| 176 | |
| 177 | export class MoneyDeposited extends Domain.Event("MoneyDeposited", { |
| 178 | amount: Schema.Int, |
| 179 | balanceAfter: Schema.Int, |
| 180 | }) {} |
| 181 | ``` |
| 182 | |
| 183 | The event carries the balance after the deposit, so anyone reading it knows the new balance without adding anything up. |
| 184 | |
| 185 | ## Refuse an account that isn't open |
| 186 | |
| 187 | ```typescript |
| 188 | // src/NotOpen.rejection.ts |
| 189 | import * as Domain from "@alchemy.run/domain"; |
| 190 | |
| 191 | export class NotOpen extends Domain.Rejection("NotOpen") {} |
| 192 | ``` |
| 193 | |
| 194 | Deposits need an open account, and so will withdrawals. A rejection two commands share gets a file of its own, instead of living in either command's file. |
| 195 | |
| 196 | ## Ask to deposit |
| 197 | |
| 198 | ```diff lang="typescript" |
| 199 | // src/DepositMoney.command.ts |
| 200 | import * as Domain from "@alchemy.run/domain"; |
| 201 | import * as Schema from "effect/Schema"; |
| 202 | +import { AccountId } from "./Account.id.ts"; |
| 203 | +import { NotOpen } from "./NotOpen.rejection.ts"; |
| 204 | |
| 205 | export class MoneyDeposited extends Domain.Event("MoneyDeposited", { |
| 206 | amount: Schema.Int, |
| 207 | balanceAfter: Schema.Int, |
| 208 | }) {} |
| 209 | + |
| 210 | +export class DepositMoney extends Domain.Command("DepositMoney", { |
| 211 | + target: AccountId, |
| 212 | + input: { amount: Schema.Int }, |
| 213 | + events: [MoneyDeposited], |
| 214 | + rejects: [NotOpen], |
| 215 | + reply: { balance: Schema.Int }, |
| 216 | +}) {} |
| 217 | ``` |
| 218 | |
| 219 | `reply` declares what the caller gets back once the deposit is recorded: the new balance. |
| 220 | |
| 221 | ## Decide deposits |
| 222 | |
| 223 | ```diff lang="typescript" |
| 224 | // src/Account.aggregate.ts |
| 225 | import * as Schema from "effect/Schema"; |
| 226 | import { AccountId } from "./Account.id.ts"; |
| 227 | +import { DepositMoney, MoneyDeposited } from "./DepositMoney.command.ts"; |
| 228 | +import { NotOpen } from "./NotOpen.rejection.ts"; |
| 229 | import { AccountOpened, AlreadyOpen, OpenAccount } from "./OpenAccount.command.ts"; |
| 230 | // ... |
| 231 | type State = typeof State.Type; |
| 232 | |
| 233 | export class Account extends Domain.Aggregate("Account", { |
| 234 | id: AccountId, |
| 235 | state: State, |
| 236 | initial: { _tag: "Unopened" }, |
| 237 | - commands: [OpenAccount], |
| 238 | + commands: [OpenAccount, DepositMoney], |
| 239 | decide: { |
| 240 | OpenAccount: (s, cmd) => |
| 241 | s._tag !== "Unopened" ? new AlreadyOpen() : [new AccountOpened({ owner: cmd.owner })], |
| 242 | + DepositMoney: (s, cmd) => |
| 243 | + s._tag !== "Open" |
| 244 | + ? new NotOpen() |
| 245 | + : [new MoneyDeposited({ amount: cmd.amount, balanceAfter: s.balance + cmd.amount })], |
| 246 | }, |
| 247 | evolve: { |
| 248 | AccountOpened: (_, e) => ({ _tag: "Open" as const, owner: e.owner, balance: 0 }), |
| 249 | + MoneyDeposited: (s, e) => (s._tag === "Open" ? { ...s, balance: e.balanceAfter } : s), |
| 250 | + }, |
| 251 | + reply: { |
| 252 | + DepositMoney: (s) => ({ balance: s._tag === "Open" ? s.balance : 0 }), |
| 253 | }, |
| 254 | }) {} |
| 255 | ``` |
| 256 | |
| 257 | `evolve` never refuses an event, because it already happened. `decide` already returned `NotOpen` for an account that isn't open, so `evolve` and `reply` just cover every state. `reply` answers from the state after the deposit. |
| 258 | |
| 259 | ## Test deposits |
| 260 | |
| 261 | ```diff lang="typescript" |
| 262 | // test/Account.test.ts |
| 263 | import { Account } from "../src/Account.aggregate.ts"; |
| 264 | import { Bank } from "../src/Bank.model.ts"; |
| 265 | +import { DepositMoney, MoneyDeposited } from "../src/DepositMoney.command.ts"; |
| 266 | +import { NotOpen } from "../src/NotOpen.rejection.ts"; |
| 267 | import { AccountOpened, AlreadyOpen, OpenAccount } from "../src/OpenAccount.command.ts"; |
| 268 | // ... |
| 269 | Story.rejected(new AlreadyOpen()), |
| 270 | ), |
| 271 | ); |
| 272 | + |
| 273 | +it.effect("deposits into an open account and replies with the balance", () => |
| 274 | + story( |
| 275 | + Story.given(account, new AccountOpened({ owner: "sam" })), |
| 276 | + Story.when(account, new DepositMoney({ amount: 100 })), |
| 277 | + Story.then(account, new MoneyDeposited({ amount: 100, balanceAfter: 100 })), |
| 278 | + Story.replied({ balance: 100 }), |
| 279 | + ), |
| 280 | +); |
| 281 | + |
| 282 | +it.effect("refuses a deposit into an account that isn't open", () => |
| 283 | + story(Story.when(account, new DepositMoney({ amount: 100 })), Story.rejected(new NotOpen())), |
| 284 | +); |
| 285 | ``` |
| 286 | |
| 287 | `replied` checks the last command's reply. |
| 288 | |
| 289 | ## Withdraw money |
| 290 | |
| 291 | ```typescript |
| 292 | // src/WithdrawMoney.command.ts |
| 293 | import * as Domain from "@alchemy.run/domain"; |
| 294 | import * as Schema from "effect/Schema"; |
| 295 | import { AccountId } from "./Account.id.ts"; |
| 296 | import { NotOpen } from "./NotOpen.rejection.ts"; |
| 297 | |
| 298 | export class MoneyWithdrawn extends Domain.Event("MoneyWithdrawn", { |
| 299 | amount: Schema.Int, |
| 300 | balanceAfter: Schema.Int, |
| 301 | }) {} |
| 302 | |
| 303 | export class InsufficientFunds extends Domain.Rejection("InsufficientFunds", { |
| 304 | balance: Schema.Int, |
| 305 | requested: Schema.Int, |
| 306 | }) {} |
| 307 | |
| 308 | export class WithdrawMoney extends Domain.Command("WithdrawMoney", { |
| 309 | target: AccountId, |
| 310 | input: { amount: Schema.Int }, |
| 311 | events: [MoneyWithdrawn], |
| 312 | rejects: [NotOpen, InsufficientFunds], |
| 313 | reply: { balance: Schema.Int }, |
| 314 | }) {} |
| 315 | ``` |
| 316 | |
| 317 | A withdrawal follows the same shape as a deposit, with one more way to say no: `InsufficientFunds` carries the balance and the amount asked for. |
| 318 | |
| 319 | ## Decide withdrawals |
| 320 | |
| 321 | ```diff lang="typescript" |
| 322 | // src/Account.aggregate.ts |
| 323 | import { NotOpen } from "./NotOpen.rejection.ts"; |
| 324 | import { AccountOpened, AlreadyOpen, OpenAccount } from "./OpenAccount.command.ts"; |
| 325 | +import { InsufficientFunds, MoneyWithdrawn, WithdrawMoney } from "./WithdrawMoney.command.ts"; |
| 326 | |
| 327 | const State = Schema.Union([ |
| 328 | // ... |
| 329 | ]); |
| 330 | // ... |
| 331 | export class Account extends Domain.Aggregate("Account", { |
| 332 | id: AccountId, |
| 333 | state: State, |
| 334 | initial: { _tag: "Unopened" }, |
| 335 | - commands: [OpenAccount, DepositMoney], |
| 336 | + commands: [OpenAccount, DepositMoney, WithdrawMoney], |
| 337 | decide: { |
| 338 | OpenAccount: (s, cmd) => |
| 339 | s._tag !== "Unopened" ? new AlreadyOpen() : [new AccountOpened({ owner: cmd.owner })], |
| 340 | DepositMoney: (s, cmd) => |
| 341 | s._tag !== "Open" |
| 342 | ? new NotOpen() |
| 343 | : [new MoneyDeposited({ amount: cmd.amount, balanceAfter: s.balance + cmd.amount })], |
| 344 | + WithdrawMoney: (s, cmd) => |
| 345 | + s._tag !== "Open" |
| 346 | + ? new NotOpen() |
| 347 | + : cmd.amount > s.balance |
| 348 | + ? new InsufficientFunds({ balance: s.balance, requested: cmd.amount }) |
| 349 | + : [new MoneyWithdrawn({ amount: cmd.amount, balanceAfter: s.balance - cmd.amount })], |
| 350 | }, |
| 351 | evolve: { |
| 352 | AccountOpened: (_, e) => ({ _tag: "Open" as const, owner: e.owner, balance: 0 }), |
| 353 | MoneyDeposited: (s, e) => (s._tag === "Open" ? { ...s, balance: e.balanceAfter } : s), |
| 354 | + MoneyWithdrawn: (s, e) => (s._tag === "Open" ? { ...s, balance: e.balanceAfter } : s), |
| 355 | }, |
| 356 | reply: { |
| 357 | DepositMoney: (s) => ({ balance: s._tag === "Open" ? s.balance : 0 }), |
| 358 | + WithdrawMoney: (s) => ({ balance: s._tag === "Open" ? s.balance : 0 }), |
| 359 | }, |
| 360 | }) {} |
| 361 | ``` |
| 362 | |
| 363 | The account checks the balance it holds right now. Withdrawals to one account run one at a time, so two of them can never both spend the same money. |
| 364 | |
| 365 | ## Test an overdraft |
| 366 | |
| 367 | ```diff lang="typescript" |
| 368 | // test/Account.test.ts |
| 369 | import { NotOpen } from "../src/NotOpen.rejection.ts"; |
| 370 | import { AccountOpened, AlreadyOpen, OpenAccount } from "../src/OpenAccount.command.ts"; |
| 371 | +import { InsufficientFunds, WithdrawMoney } from "../src/WithdrawMoney.command.ts"; |
| 372 | |
| 373 | const story = Story.make(Bank); |
| 374 | // ... |
| 375 | story(Story.when(account, new DepositMoney({ amount: 100 })), Story.rejected(new NotOpen())), |
| 376 | ); |
| 377 | + |
| 378 | +it.effect("refuses to withdraw more than the balance", () => |
| 379 | + story( |
| 380 | + Story.given( |
| 381 | + account, |
| 382 | + new AccountOpened({ owner: "sam" }), |
| 383 | + new MoneyDeposited({ amount: 100, balanceAfter: 100 }), |
| 384 | + ), |
| 385 | + Story.when(account, new WithdrawMoney({ amount: 150 })), |
| 386 | + Story.rejected(new InsufficientFunds({ balance: 100, requested: 150 })), |
| 387 | + ), |
| 388 | +); |
| 389 | ``` |
| 390 | |
| 391 | ```sh |
| 392 | bun vitest run |
| 393 | ``` |
| 394 | |
| 395 | All five stories pass. You have an account that opens once, takes deposits, and never goes below zero. |
| 396 | |
| 397 | :::note |
| 398 | Next, show the balance and a statement with [views](/domain/tutorial/part-2). The full design of aggregates is in [Aggregate](/domain/aggregate). |
| 399 | ::: |