The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 04:45 UTC
| 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. |