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

main
mdx 218 lines 7.31 KB
Raw
1 ---
2 title: "Part 3: React with a policy"
3 description: Register customers, and open a main account for each one with a policy.
4 sidebar:
5 order: 3
6 ---
7
8 Every new customer should get a main account. Model customers, then add a policy that opens the account whenever a customer registers.
9
10 ## Name customer ids
11
12 ```typescript
13 // src/Customer.id.ts
14 import * as Schema from "effect/Schema";
15
16 export const CustomerId = Schema.String.pipe(Schema.brand("CustomerId"));
17 ```
18
19 Like the account, a customer has its own kind of id.
20
21 ## Register a customer
22
23 ```typescript
24 // src/RegisterCustomer.command.ts
25 import * as Domain from "@alchemy.run/domain";
26 import * as Schema from "effect/Schema";
27 import { CustomerId } from "./Customer.id.ts";
28
29 export class CustomerRegistered extends Domain.Event("CustomerRegistered", {
30 name: Schema.String,
31 }) {}
32
33 export class AlreadyRegistered extends Domain.Rejection("AlreadyRegistered") {}
34
35 export class RegisterCustomer extends Domain.Command("RegisterCustomer", {
36 target: CustomerId,
37 input: { name: Schema.String },
38 events: [CustomerRegistered],
39 rejects: [AlreadyRegistered],
40 }) {}
41 ```
42
43 `RegisterCustomer` lives in its own file, with the event it records and the rejection it returns.
44
45 ## Model a customer
46
47 ```typescript
48 // src/Customer.aggregate.ts
49 import * as Domain from "@alchemy.run/domain";
50 import * as Schema from "effect/Schema";
51 import { CustomerId } from "./Customer.id.ts";
52 import { AlreadyRegistered, CustomerRegistered, RegisterCustomer } from "./RegisterCustomer.command.ts";
53
54 export class Customer extends Domain.Aggregate("Customer", {
55 id: CustomerId,
56 state: Schema.Struct({ name: Schema.NullOr(Schema.String) }),
57 initial: { name: null },
58 commands: [RegisterCustomer],
59 decide: {
60 RegisterCustomer: (s, cmd) =>
61 s.name !== null ? new AlreadyRegistered() : [new CustomerRegistered({ name: cmd.name })],
62 },
63 evolve: {
64 CustomerRegistered: (_, e) => ({ name: e.name }),
65 },
66 }) {}
67 ```
68
69 A customer is an aggregate with the same shape as the account: an id, the commands it handles, and `decide` and `evolve`.
70
71 ## Declare the policy
72
73 ```typescript
74 // src/MainAccountProvisioning.policy.ts
75 import * as Domain from "@alchemy.run/domain";
76 import { Customer } from "./Customer.aggregate.ts";
77 import { CustomerRegistered } from "./RegisterCustomer.command.ts";
78
79 export class MainAccountProvisioning extends Domain.Policy("MainAccountProvisioning", {
80 from: Customer,
81 on: [CustomerRegistered],
82 }) {}
83 ```
84
85 A policy is "whenever this happens, do that". This one listens to customers, for `CustomerRegistered`.
86
87 ## Implement it
88
89 ```diff lang="typescript"
90 // src/MainAccountProvisioning.policy.ts
91 import * as Domain from "@alchemy.run/domain";
92 +import * as Effect from "effect/Effect";
93 +import { Account } from "./Account.aggregate.ts";
94 +import { AccountId } from "./Account.id.ts";
95 import { Customer } from "./Customer.aggregate.ts";
96 +import { OpenAccount } from "./OpenAccount.command.ts";
97 import { CustomerRegistered } from "./RegisterCustomer.command.ts";
98 // ...
99 on: [CustomerRegistered],
100 }) {}
101 +
102 +export const MainAccountProvisioningLive = MainAccountProvisioning.toLayer(
103 + Effect.gen(function* () {
104 + const accounts = yield* Account;
105 + return Effect.fn(function* ({ source }) {
106 + yield* accounts
107 + .send(AccountId.make(`${source.id}-main`), new OpenAccount({ owner: source.id }))
108 + .pipe(Effect.catchTag("AlreadyOpen", () => Effect.void));
109 + });
110 + }),
111 +);
112 ```
113
114 `toLayer` resolves the account client once, and returns the handler that runs for each registration. `source` is the customer who registered, and becomes the account's owner.
115
116 A policy can see the same event twice. Its commands get ids derived from that event, so a second run opens nothing new, and catching `AlreadyOpen` lets it finish quietly.
117
118 ## Host the policy
119
120 ```diff lang="typescript"
121 // src/Bank.model.ts
122 import { Account } from "./Account.aggregate.ts";
123 import { AccountSummary } from "./AccountSummary.view.ts";
124 +import { Customer } from "./Customer.aggregate.ts";
125 +import {
126 + MainAccountProvisioning,
127 + MainAccountProvisioningLive,
128 +} from "./MainAccountProvisioning.policy.ts";
129 import { Statement } from "./Statement.view.ts";
130
131 export class Bank extends Domain.Model("Bank", {
132 - aggregates: [Account],
133 + aggregates: [Account, Customer],
134 views: [AccountSummary, Statement],
135 + policies: [MainAccountProvisioning],
136 }) {}
137 +
138 +export const BankHandlers = MainAccountProvisioningLive;
139 ```
140
141 The model lists the policy, and `BankHandlers` is its implementation. You provide it wherever you host the model.
142
143 ## Give every story the policies
144
145 ```diff lang="typescript"
146 // test/Account.test.ts
147 import { Story } from "@alchemy.run/domain/Story";
148 import { Account } from "../src/Account.aggregate.ts";
149 -import { Bank } from "../src/Bank.model.ts";
150 +import { Bank, BankHandlers } from "../src/Bank.model.ts";
151 import { DepositMoney, MoneyDeposited } from "../src/DepositMoney.command.ts";
152 import { NotOpen } from "../src/NotOpen.rejection.ts";
153 // ...
154 import { InsufficientFunds, WithdrawMoney } from "../src/WithdrawMoney.command.ts";
155
156 -const story = Story.make(Bank);
157 +const story = Story.make(Bank, { layer: BankHandlers });
158 const account = Account.ref("a-1");
159
160 ```
161
162 ```diff lang="typescript"
163 // test/views.test.ts
164 import { Account } from "../src/Account.aggregate.ts";
165 import { AccountSummary } from "../src/AccountSummary.view.ts";
166 -import { Bank } from "../src/Bank.model.ts";
167 +import { Bank, BankHandlers } from "../src/Bank.model.ts";
168 import { DepositMoney, MoneyDeposited } from "../src/DepositMoney.command.ts";
169 import { AccountOpened } from "../src/OpenAccount.command.ts";
170 // ...
171 import { MoneyWithdrawn, WithdrawMoney } from "../src/WithdrawMoney.command.ts";
172
173 -const story = Story.make(Bank);
174 +const story = Story.make(Bank, { layer: BankHandlers });
175 const account = Account.ref("a-1");
176
177 ```
178
179 A story runs the whole model, policies included, so every story now takes `BankHandlers`. Leave it out and the type checker tells you.
180
181 ## Test registration
182
183 ```typescript
184 // test/registration.test.ts
185 import { it } from "@effect/vitest";
186 import { Story } from "@alchemy.run/domain/Story";
187 import { Account } from "../src/Account.aggregate.ts";
188 import { AccountSummary } from "../src/AccountSummary.view.ts";
189 import { Bank, BankHandlers } from "../src/Bank.model.ts";
190 import { Customer } from "../src/Customer.aggregate.ts";
191 import { AccountOpened } from "../src/OpenAccount.command.ts";
192 import { CustomerRegistered, RegisterCustomer } from "../src/RegisterCustomer.command.ts";
193
194 const story = Story.make(Bank, { layer: BankHandlers });
195 const sam = Customer.ref("c-1");
196 const samsAccount = Account.ref("c-1-main");
197
198 it.effect("registering opens a main account", () =>
199 story(
200 Story.when(sam, new RegisterCustomer({ name: "sam" })),
201 Story.then(sam, new CustomerRegistered({ name: "sam" })),
202 Story.then(samsAccount, new AccountOpened({ owner: "c-1" })),
203 Story.view(AccountSummary, samsAccount, { owner: "c-1", balance: 0 }),
204 ),
205 );
206 ```
207
208 The policy runs for real. The registration's events, the account the policy opened, and the summary that followed are all checked in one story.
209
210 ```sh
211 bun vitest run
212 ```
213
214 Two aggregates and two views are now connected by a policy, and each step can be checked in a story.
215
216 :::note
217 Next, let customers reach the bank through an [Api](/domain/tutorial/part-4). Policies can also call external systems: see [Policy](/domain/policy#call-an-external-system).
218 :::