The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 399 lines 12.8 KB
Raw
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 :::