The best way to control Claude Code, Codex and more from any computer or phone
| 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. |