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

main
mdx 172 lines 7.47 KB
Raw
1 ---
2 title: Stream
3 description: How a stream keeps a keyed, append-only log that a projection writes and clients read through an Api, with its latest entry as the current value.
4 ---
5
6 import DAG from "../../../components/DAG.astro";
7
8 A stream is a keyed, append-only log: one ordered list of entries per key, kept for good and readable from any point. A [projection](/domain/projection) writes it; clients read it through an [Api](/domain/api), with the same middleware and `validate` as a view.
9
10 Its latest entry is its current value. So one stream answers both "what is it now?" and "tell me every change", which is what a client syncing state needs: the current value first, then everything after it.
11
12 ## A read model you publish entry by entry
13
14 A view's state is shaped by its `evolve`, and its fold belongs to the model. A stream is for when you want to decide, in code, exactly what each client-visible entry contains and when one is written. The projection that writes it can read any source, combine a view's state with an event, skip changes no client cares about, and publish a compact entry shaped for the screen.
15
16 The bank's account card is an example. The card on a customer's home screen shows the owner, the balance and whether the account is frozen. It changes when any of those change, and not when anything else does. A stream of `CardChanged` entries is that card, with its whole history:
17
18 <DAG
19 nodes={[
20 { id: "c1", label: "CardChanged", type: "balance 100", kind: "event", col: 0, row: 0 },
21 { id: "c2", label: "CardChanged", type: "balance 70", kind: "event", col: 1, row: 0 },
22 { id: "c3", label: "CardChanged", type: "frozen", kind: "event", col: 2, row: 0 },
23 { id: "now", label: "peek", type: "the card now", kind: "query", col: 2, row: 1 },
24 ]}
25 edges={[
26 { from: "c1", to: "c2" },
27 { from: "c2", to: "c3" },
28 { from: "c3", to: "now", dashed: true },
29 ]}
30 caption="One log per account. Its last entry is the card a client shows."
31 />
32
33 Use a view when a fold describes the read model well. Use a stream when a projection should choose each entry, and clients should follow those entries live.
34
35 ## Declare a stream
36
37 A stream names its key and the events its entries may be. The example keeps a card per account, one entry each time the card changes.
38
39 ```typescript title="packages/domain/src/Account/AccountCard.stream.ts"
40 export class CardChanged extends Domain.Event("CardChanged", {
41 customerId: CustomerId,
42 owner: Schema.String,
43 balance: Cents,
44 frozen: Schema.Boolean,
45 }) {}
46 ```
47
48 ```typescript title="packages/domain/src/Account/AccountCard.stream.ts"
49 export class AccountCard extends Domain.Stream("AccountCard", {
50 key: Account,
51 entries: [CardChanged],
52 middleware: [Session],
53 rejects: [NotOwner],
54 ```
55
56 Add it to the model's `streams`.
57
58 A stream can also be keyed by a string Schema, like an org id, with one log per value. Its writer is then keyed by the same Schema, and reads take the value: `bank.OrgFeed.peek(orgId)`. See [Key a view by a value](/domain/view#key-a-view-by-a-value).
59
60 ## Write it from a projection
61
62 A stream has exactly one writer: a projection that lists it in `writes`, keyed by the same aggregate. `AccountCards` reads the account summary, whose events arrive with the summary's state after each one, and appends a card for every change.
63
64 ```typescript title="packages/domain/src/Account/AccountCards.projection.ts"
65 export const AccountCardsLive = AccountCards.toLayer(
66 Effect.gen(function* () {
67 const cards = yield* AccountCard;
68 return Effect.fn(function* (batch) {
69 for (const input of batch) {
70 const summary = input.state;
71 if (!summary?.customerId || !summary.owner) continue;
72 yield* cards.append(
73 input,
74 new CardChanged({
75 customerId: summary.customerId,
76 owner: summary.owner,
77 balance: summary.balance,
78 frozen: summary.frozen,
79 }),
80 );
81 }
82 });
83 }),
84 );
85 ```
86
87 `append` takes the input being handled. That's how the stream knows which key it belongs to, and how it keeps writes exactly once: each append is identified by the input's place in the projection's log, so a redelivered or replayed input appends nothing twice.
88
89 <DAG
90 nodes={[
91 { id: "account", label: "Account a-1", type: "MoneyWithdrawn", kind: "aggregate" },
92 { id: "summary", label: "AccountSummary", type: "view", kind: "view" },
93 { id: "cards", label: "AccountCards", type: "projection", kind: "projection" },
94 { id: "card", label: "AccountCard a-1", type: "stream", kind: "stream" },
95 ]}
96 edges={[
97 { from: "account", to: "summary", dashed: true },
98 { from: "summary", to: "cards", dashed: true },
99 { from: "cards", to: "card" },
100 ]}
101 caption="Each change to the summary reaches the projection, which appends one card to the account's stream."
102 />
103
104 ## One writer per key
105
106 Order per key only holds if each key has a single writer. The writer says so in its declaration:
107
108 ```typescript title="packages/domain/src/Account/AccountCards.projection.ts"
109 writes: [AccountCard],
110 ```
111
112 The model checks this when it's built: a stream listed in two projections' `writes`, or written by a projection keyed differently, is a definition error.
113
114 ## Read it
115
116 Exposed on an Api, a stream offers four reads for a key.
117
118 ```typescript title="packages/server/test/cardReads.ts"
119 export const cardReads = Effect.fn(function* (bank: CustomerClient, accountId: AccountId) {
120 // The card now: the latest entry, or null.
121 const now = yield* bank.AccountCard.peek(accountId);
122
123 // Every new card, starting with the current one.
124 yield* bank.AccountCard.watch(accountId).pipe(
125 Stream.take(2),
126 Stream.runForEach(({ state: card }) => Effect.log(`balance ${card?.event.balance}`)),
127 );
128
129 // History from a position, then live; and a page of it.
130 yield* bank.AccountCard.events(accountId, { after: 0 }).pipe(Stream.take(1), Stream.runDrain);
131 const page = yield* bank.AccountCard.list(accountId, { order: "desc", take: 10 });
132 return [now, page.entries.length] as const;
133 });
134 ```
135
136 Over `Domain.protocolWebSocket`, `watch` and `events` are WebSockets to the Durable Object that owns the key, which pushes each new entry as it's appended.
137
138 `peek` also takes `atLeast`, a `stream` and `version`, and waits until the stream's writer has handled that commit. It only covers sources the writer consumes directly. `AccountCards` reads accounts through the `AccountSummary` view, so an account command's receipt is not one its stream can wait for.
139
140 ## Decide who may read it
141
142 `validate` judges every read against the key's latest entry, and runs again on each new entry while a client watches.
143
144 ```typescript title="packages/domain/src/Account/AccountCard.stream.ts"
145 validate: Effect.fn(function* (_request, latest) {
146 yield* mustOwn(latest?.event.customerId ?? null);
147 }),
148 ```
149
150 ## Use it as a value
151
152 Because `peek` returns the latest entry, a stream whose entries are full snapshots, like the card, is a value with a history.
153
154 ```typescript title="packages/server/test/cardReads.ts"
155 const now = yield* bank.AccountCard.peek(accountId);
156 ```
157
158 There's no separate "current value" to keep in sync, and no race between two writers setting it: there's one writer, and its entries are ordered.
159
160 ## Test it
161
162 `Story.streamed` checks the entries a projection appended since the last check.
163
164 ```typescript title="packages/domain/test/Bank.story.test.ts"
165 streamed(
166 AccountCard,
167 a1,
168 new CardChanged({ customerId: c1.id, owner: "sam", balance: 7_500, frozen: false }),
169 ),
170 ```
171
172 Next, [Policy](/domain/policy): the consumer that acts on the world rather than recording it.