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

main
mdx 118 lines 5.6 KB
Raw
1 ---
2 title: Optimistic updates
3 description: Show pending intent, confirm it by commandId from a View feed, and retry an unknown outcome safely.
4 ---
5
6 Show a deposit when the customer clicks. Confirm it when the bank's event arrives. A successful command reply means the write committed. The line waits for the feed before it becomes confirmed.
7
8 This guide uses `Bank = DomainFoldkit.make(CustomerApi)` from [Integrate with Foldkit](/domain/foldkit). The bank example keeps its own queue and line Model. The adapter has no generic pending-state helper.
9
10 ## Track each intent
11
12 ```typescript
13 import * as DomainFoldkit from "@alchemy.run/domain/Foldkit";
14 import { StatementLine } from "@bank/domain/Account/Statement.view";
15 import * as Schema from "effect/Schema";
16
17 const Line = Schema.Struct({
18 commandId: Schema.String,
19 kind: StatementLine.fields.kind,
20 amount: Schema.Number,
21 balance: Schema.Option(Schema.Number),
22 ack: Schema.Literals(["Pending", "Queued", "Confirmed", "Rejected", "Denied"]),
23 reason: Schema.Option(Schema.String),
24 });
25 type Line = typeof Line.Type;
26 ```
27
28 Allocate the id with `DomainFoldkit.next(model.commandIds)`. Store the returned command id state in the Model. Add a pending line with the allocated id. Send `Bank.DepositMoney({ target, input, commandId })` through `Command.mapMessage`.
29
30 The command and its pending line share one id. Each event caused by the command carries that id in `entry.envelope.commandId`.
31
32 ## Handle the command result
33
34 Match the generated result with `Bank.Message.match`. Handle each failure through its named variant.
35
36 | Result | Line state | What happens next |
37 | --- | --- | --- |
38 | `SucceededDepositMoney` | `Pending` | Wait for the feed. |
39 | `Rejected` | `Rejected` | Show the Rejection's fields. |
40 | `Denied` | `Denied` | Request authentication or MFA before a retry. |
41 | `Unknown` | `Queued` | Retry with the original id. |
42
43 Do not mark a confirmed line pending when a late reply arrives. The feed can arrive before the reply.
44
45 ## Confirm by command id
46
47 ```typescript
48 import * as Option from "effect/Option";
49 import { modifyFields } from "foldkit/struct";
50
51 const confirm = (model: Model, commandId: string, event: StatementLine) => {
52 const nextLine = Line.make({
53 commandId,
54 kind: event.kind,
55 amount: event.amount,
56 balance: Option.some(event.balance),
57 ack: "Confirmed",
58 reason: Option.none(),
59 });
60 const otherLines = model.lines.filter((line) => line.commandId !== commandId);
61 return modifyFields(model, { lines: () => [nextLine, ...otherLines] });
62 };
63 ```
64
65 `Model` is the app's Model with a `lines: Schema.Array(Line)` field. This example replaces a pending line with the feed's line. It also accepts history and writes from another device. A repeated confirmation replaces the same line.
66
67 Keep your own display order. The bank example puts unconfirmed lines above confirmed lines.
68
69 ## Resume the feed
70
71 ```typescript
72 import { Subscription } from "foldkit";
73 import { defineMessageUnion } from "foldkit/message";
74
75 const Message = defineMessageUnion({
76 ReceivedStatementLine: { commandId: Schema.String, line: StatementLine, cursor: Schema.Number },
77 CaughtUpStatement: { cursor: Schema.Number },
78 FailedReadStatement: { reason: Schema.String },
79 });
80
81 const subscriptions = Subscription.make<Model, typeof Message.Type, typeof CustomerApi.Client.Identifier>()(() => ({
82 statement: Bank.Statement.events({
83 key: (model: Model) => model.accountId,
84 cursor: (model) => model.statementCursor,
85 isEnabled: (model) => model.online,
86 onEntry: (entry): typeof Message.Type => Message.ReceivedStatementLine({
87 commandId: entry.envelope.commandId,
88 line: entry.event,
89 cursor: entry.envelope.seq,
90 }),
91 onCaughtUp: (cursor): typeof Message.Type => Message.CaughtUpStatement({ cursor }),
92 onFailure: (error): typeof Message.Type => Message.FailedReadStatement({ reason: error._tag }),
93 onDefect: (): typeof Message.Type => Message.FailedReadStatement({ reason: "Read defect" }),
94 }),
95 }));
96 ```
97
98
99 A restart reads the latest Model cursor and passes it as `after`. Cursor changes leave the stream alive. The adapter drops entries at or below the applied cursor. A filtered feed can skip sequence numbers, so the adapter does not count gaps.
100
101
102 The adapter does not reduce entries into state. Use `watch` for the current View state. Use this event feed to confirm intents or build the app's display list.
103
104 ## Keep the offline queue
105
106 Save unresolved intents in order. An offline click adds a queued line. When online, send the oldest queued intent first.
107
108 A transport retry acts on `Unknown`, with the same `commandId`. If the reply was lost after commit, the aggregate returns its stored receipt. It does not apply the intent twice.
109
110 If a retry remains unknown, stop the batch. Leave later intents queued, so a withdrawal cannot pass an earlier deposit. A `Denied` line shows its reason and a retry control. It does not block other intents. After authentication, retry that line with its original id. A `Rejected` result ends that intent.
111
112 Persist queued and pending intents after each Model change. A `Denied` line is not saved, so a reload drops it. On reload, replay the statement feed to confirm writes the server applied before the previous page closed.
113
114 ## Bound this pattern
115
116 This example confirms one bank line by `commandId`. It does not prove that every effect of an arbitrary command has reached every View. A command can emit no events or several events. A View can drop or transform them.
117
118 For general completion, use the success receipt with `snapshot({ atLeast: receipt })`. Design re-prediction and reconciliation for the application's own rules. Do not infer completion from a count of output events.