foldkit-sync 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +180 -6
- package/dist/index.d.mts +451 -158
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +791 -376
- package/dist/index.mjs.map +1 -1
- package/package.json +8 -2
package/README.md
CHANGED
|
@@ -10,16 +10,172 @@ Reach for it when clients must keep working offline and converge later, with
|
|
|
10
10
|
[guide](https://github.com/doeixd/foldkit-plus/blob/main/docs/replication.md) covers the mental model and when not to use
|
|
11
11
|
it.
|
|
12
12
|
|
|
13
|
+
## Quick start
|
|
14
|
+
|
|
15
|
+
`Sync.forApplication` is the Foldkit-facing layer. From one
|
|
16
|
+
`Surface.application` and a writable projection it derives the shared schema, the
|
|
17
|
+
durable Message subset, the initial snapshot, and replay, and exposes a read-only
|
|
18
|
+
Surface over the same projection. The application's `update` stays the only
|
|
19
|
+
reducer.
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import { Schema } from 'effect'
|
|
23
|
+
import { defineMessageUnion } from 'foldkit/message'
|
|
24
|
+
import { Surface } from 'foldkit-surface'
|
|
25
|
+
import { documentId, forApplication } from 'foldkit-sync'
|
|
26
|
+
|
|
27
|
+
const Model = Schema.Struct({
|
|
28
|
+
todos: Schema.Array(Schema.Struct({ id: Schema.String, title: Schema.String })),
|
|
29
|
+
selectedTodoId: Schema.NullOr(Schema.String),
|
|
30
|
+
})
|
|
31
|
+
const Message = defineMessageUnion({
|
|
32
|
+
CreatedTodo: { id: Schema.String, title: Schema.String },
|
|
33
|
+
RenamedTodo: { id: Schema.String, title: Schema.String },
|
|
34
|
+
SelectedTodo: { id: Schema.String },
|
|
35
|
+
})
|
|
36
|
+
|
|
37
|
+
// `update` is the application's ordinary transition.
|
|
38
|
+
const App = Surface.application({
|
|
39
|
+
Model,
|
|
40
|
+
Message,
|
|
41
|
+
initial: { todos: [], selectedTodoId: null },
|
|
42
|
+
update,
|
|
43
|
+
})
|
|
44
|
+
|
|
45
|
+
const Todos = Projection.pick(App.fields.todos)
|
|
46
|
+
const TodoChanges = MessageSet.make(App, [Message.CreatedTodo, Message.RenamedTodo])
|
|
47
|
+
|
|
48
|
+
const TodoSync = forApplication(App).make({
|
|
49
|
+
documentId: documentId('todos'),
|
|
50
|
+
shared: Todos, // the shared codec, read, and write
|
|
51
|
+
durable: TodoChanges, // the durable subset
|
|
52
|
+
})
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Only `todos` is replicated; `selectedTodoId` stays local. The derived `replay`
|
|
56
|
+
installs the shared slice into the application's initial Model, applies the
|
|
57
|
+
durable Message through `update`, and reads the shared slice back.
|
|
58
|
+
|
|
59
|
+
A durable Message must therefore be a deterministic, state-only transition of
|
|
60
|
+
the shared projection. Replay refuses one whose `update` returns a Command (a
|
|
61
|
+
live effect cannot be replayed) or changes a field outside the projection (the
|
|
62
|
+
change would be silently lost), naming the Message and the fields. A Message that
|
|
63
|
+
needs an effect stays local and emits a durable fact once the effect settles:
|
|
64
|
+
`RequestedChargeCard` runs the Command; `CardCharged` is what replicates.
|
|
65
|
+
Pass `replay` to `make` when an application needs a custom reducer over the
|
|
66
|
+
shared slice; a custom replay is not guarded.
|
|
67
|
+
|
|
68
|
+
On the server, the same contract produces the journal's codecs and reducer, so
|
|
69
|
+
neither is written twice:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import { makeJournal } from 'foldkit-durable'
|
|
73
|
+
|
|
74
|
+
const journal = yield* makeJournal({
|
|
75
|
+
...TodoSync.journalContract(), // operation/snapshot codecs, empty, reduce
|
|
76
|
+
file: 'todos.sqlite',
|
|
77
|
+
opId: operation => operation.opId,
|
|
78
|
+
actorId: principal => principal.actorId,
|
|
79
|
+
})
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### Mounting
|
|
83
|
+
|
|
84
|
+
`Sync.mount` runs the application over an open replica with one reducer. A
|
|
85
|
+
durable Message is applied at once through the application's `update` and
|
|
86
|
+
persisted afterwards in a Command; the shared slice is re-installed from the
|
|
87
|
+
replica when an exchange or a rejection changes it, or when a persist fails.
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
const replica = yield* TodoSync.openReplica(replicaId('tab-1'), yield* indexedDb('todos'))
|
|
91
|
+
const mounted = mount(App, TodoSync, {
|
|
92
|
+
replica,
|
|
93
|
+
container: document.getElementById('app')!, // Foldkit needs the id
|
|
94
|
+
view: (model, h) => ({ title: 'Todos', body: h.ul([], model.todos.map(todo => h.li([], [todo.title]))) }),
|
|
95
|
+
onPersistenceFailure: (model, error) => ({ ...model, lastError: error.message }),
|
|
96
|
+
})
|
|
97
|
+
mounted.dispatch(Message.CreatedTodo({ id, title: 'Milk' }))
|
|
98
|
+
mounted.model() // the Model after the last transition
|
|
99
|
+
await mounted.dispose() // waits for in-flight persists; the replica stays open
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
`url` routes the URL through the application: `init(model, url)` reduces it
|
|
103
|
+
into the Model before the first render, `onUrlChange(url)` names the Message
|
|
104
|
+
for every navigation, and `onUrlRequest` the Message for a link click (omitted,
|
|
105
|
+
the mount follows the link: an internal one pushed, an external one loaded).
|
|
106
|
+
A `foldkit-mirror` URL mirror plugs in as `url: { init: (model, url) =>
|
|
107
|
+
Filters.reduce(model, url), onUrlChange: url => Message.UrlChanged({ url }) }`;
|
|
108
|
+
`subscriptions` and `resources` carry its write entry and the store layer.
|
|
109
|
+
|
|
110
|
+
`mounted.model`, `mounted.dispatch`, `mounted.subscribe`, and `mounted.observe`
|
|
111
|
+
are the host an agent binds to; `observe` reports every application Message the
|
|
112
|
+
runtime applies, which a capability with a `completion` contract needs. See
|
|
113
|
+
[docs/sync-runtime-binding.md](../../docs/sync-runtime-binding.md) for what the
|
|
114
|
+
mount guarantees and why no Foldkit change is required.
|
|
115
|
+
|
|
116
|
+
### Fragments
|
|
117
|
+
|
|
118
|
+
A large application declares one fragment per feature and composes them:
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
const Sync = forApplication(App)
|
|
122
|
+
const Todos = Sync.fragment({
|
|
123
|
+
shared: Projection.pick(App.fields.todos),
|
|
124
|
+
durable: MessageSet.make(App, [Message.CreatedTodo, Message.RenamedTodo]),
|
|
125
|
+
})
|
|
126
|
+
const Members = Sync.fragment({
|
|
127
|
+
shared: Projection.pick(App.fields.members),
|
|
128
|
+
durable: MessageSet.make(App, [Message.Invited]),
|
|
129
|
+
})
|
|
130
|
+
const Board = Sync.make({ documentId: documentId('board'), ...Sync.compose(Todos, Members) })
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`compose` merges the shared projections and the durable subsets and infers the
|
|
134
|
+
merged shape. A field declared twice with a different codec, a Message declared
|
|
135
|
+
durable twice, or a fragment from another application throws. Two contracts
|
|
136
|
+
over the same field are a different mistake, which `Module.validate` reports.
|
|
137
|
+
|
|
138
|
+
### Authorization
|
|
139
|
+
|
|
140
|
+
Policy attaches to the contract per durable variant and compiles into the
|
|
141
|
+
journal contract, so the server applies it with no glue:
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
const Sync = forApplication(App).withPrincipal<{ readonly role: 'admin' | 'guest' }>()
|
|
145
|
+
const Board = Sync.make({
|
|
146
|
+
documentId: documentId('board'),
|
|
147
|
+
...Sync.compose(Todos, Members),
|
|
148
|
+
authorize: {
|
|
149
|
+
// `message` is exactly `RenamedTodo`; `shared` is the authoritative snapshot.
|
|
150
|
+
RenamedTodo: ({ principal, message, shared }) =>
|
|
151
|
+
principal.role === 'admin' && shared.todos.some(todo => todo.id === message.id),
|
|
152
|
+
},
|
|
153
|
+
})
|
|
154
|
+
|
|
155
|
+
const journal = yield* makeJournal({ ...Board.journalContract(), file, opId, actorId })
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
A durable variant without a rule is allowed; a key that is not a durable tag is
|
|
159
|
+
a compile error. The rule runs inside the append transaction against the
|
|
160
|
+
snapshot, so keep it synchronous and local. The client does not run it: a
|
|
161
|
+
replica has no principal, and a refused operation comes back as a rejection.
|
|
162
|
+
|
|
163
|
+
### Lower level
|
|
164
|
+
|
|
165
|
+
`Sync.forApplication(App).make` compiles down to `defineSync`, the protocol
|
|
166
|
+
primitive. Use `defineSync` directly when there is no Foldkit application to
|
|
167
|
+
derive the contract from — a non-Foldkit client, or a hand-written projection.
|
|
168
|
+
|
|
13
169
|
```ts
|
|
14
170
|
import { Effect } from 'effect'
|
|
15
|
-
import { defineSync, indexedDb, layerFromPromise } from 'foldkit-sync'
|
|
171
|
+
import { defineSync, indexedDb, layerFromPromise, replicaId } from 'foldkit-sync'
|
|
16
172
|
|
|
17
173
|
const Sync = defineSync({ ... })
|
|
18
174
|
|
|
19
175
|
const replica = await Effect.runPromise(
|
|
20
176
|
Effect.gen(function* () {
|
|
21
177
|
const storage = yield* indexedDb('todos-tab-1')
|
|
22
|
-
return yield* Sync.openReplica('tab-1', storage)
|
|
178
|
+
return yield* Sync.openReplica(replicaId('tab-1'), storage)
|
|
23
179
|
}),
|
|
24
180
|
)
|
|
25
181
|
await Effect.runPromise(
|
|
@@ -32,18 +188,34 @@ const shared = Effect.runSync(replica.shared)
|
|
|
32
188
|
|
|
33
189
|
## What it owns
|
|
34
190
|
|
|
191
|
+
- The Foldkit-facing contract (`Sync.forApplication(App).make`, optionally with
|
|
192
|
+
a custom `replay`): derives the shared projection, the durable Message subset, the
|
|
193
|
+
initial snapshot, and the journal contract from the application, so none is
|
|
194
|
+
declared twice. `Projection.pick`/`Projection.compose` build the writable projection;
|
|
195
|
+
`TodoSync.journalContract()` builds the durable codecs and reducer.
|
|
35
196
|
- The operation envelope: `replicaId:localSequence` identity, `baseCursor`, and
|
|
36
|
-
protocol/schema versions.
|
|
197
|
+
protocol/schema versions. The wire codecs live under `Sync.codec`
|
|
198
|
+
(`normalizeOperation`, `operationFrom`, `committedFrom`, `decodeExchange`) for a
|
|
199
|
+
custom transport or server; a server-committed operation is a
|
|
200
|
+
`CommittedOperation`.
|
|
37
201
|
- A persisted outbox and optimistic projection: a durable Message is visible
|
|
38
202
|
immediately and rebased onto the authoritative order.
|
|
39
203
|
- Reconciliation: committed operations are replayed in order, acknowledged or
|
|
40
204
|
refused pending entries are dropped, and a checkpoint replaces the compacted
|
|
41
|
-
prefix.
|
|
205
|
+
prefix. `replica.start` is the exchange loop: fork it to exchange once and then
|
|
206
|
+
after every `submit`, with a transport failure recorded in `status.lastError`
|
|
207
|
+
and retried on the next wake, so the application does not hand-roll it.
|
|
42
208
|
- A redacted status (`replica.status`): the pending count, the cursor, the last
|
|
43
209
|
exchange failure, and the operations the server refused — enough for a UI to
|
|
44
|
-
explain and recover without exposing Messages or the Model.
|
|
210
|
+
explain and recover without exposing Messages or the Model. `statusChanges` is
|
|
211
|
+
the same status, emitted on subscribe and re-emitted after every submit and
|
|
212
|
+
exchange. `changes` carries the status and the optimistic shared value together
|
|
213
|
+
from one read, so a UI holds one subscription instead of two.
|
|
45
214
|
- Strict decoding: an operation is always validated with the application's
|
|
46
215
|
Message schema, and a Message the contract does not call durable is refused.
|
|
216
|
+
- Branded positions: `Sequence` (a committed document position) and
|
|
217
|
+
`LocalSequence` (a replica's own 1-based counter) cannot be confused, so a
|
|
218
|
+
client counter is never passed where a committed position is expected.
|
|
47
219
|
- Presence (`createPresence`): an ephemeral, TTL'd peer registry, deliberately
|
|
48
220
|
outside the durable log. A peer that stops refreshing is dropped, not
|
|
49
221
|
replayed. It is an Effect driven by the `Clock` (so a `TestClock` makes the
|
|
@@ -52,7 +224,9 @@ const shared = Effect.runSync(replica.shared)
|
|
|
52
224
|
so a hostile peer cannot inject a value your `Update` type does not describe.
|
|
53
225
|
Presence can travel over a socket — `socketPresenceChannel` on the client and
|
|
54
226
|
`servePresence` fanning through a `createPresenceHub` on the server — or
|
|
55
|
-
in-process via `loopbackPresenceChannel`.
|
|
227
|
+
in-process via `loopbackPresenceChannel`. `presence.changes` is a `Stream` that
|
|
228
|
+
emits the current peers and re-emits them on every change, alongside the
|
|
229
|
+
`subscribe` callback.
|
|
56
230
|
- The transport seam (`Transport`): an Effect service with a loopback layer, a
|
|
57
231
|
bridge to and from the promise client the replica speaks, and a WebSocket
|
|
58
232
|
client layer. The socket reconnects on an exponential, jittered backoff and
|