foldkit-sync 0.3.0 → 0.4.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 +246 -137
- package/dist/index.d.mts +307 -183
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +308 -245
- package/dist/index.mjs.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,60 +1,97 @@
|
|
|
1
1
|
# `foldkit-sync`
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
Keeps part of a Foldkit application's Model working offline and converging with
|
|
4
|
+
a server. An edit applies to the local Model immediately, is written to a
|
|
5
|
+
persistent outbox, and is sent to the server when the network allows. The
|
|
6
|
+
server decides the order; every replica replays that order and ends up with the
|
|
7
|
+
same state.
|
|
8
|
+
|
|
9
|
+
The trick is that it is still your application. You declare which Model fields
|
|
10
|
+
replicate and which Messages are durable; the shared codec, the initial
|
|
11
|
+
snapshot, the replay reducer, and the server journal's contract are all derived
|
|
12
|
+
from the `update` you already wrote. There is no second reducer to keep in sync
|
|
13
|
+
with the first.
|
|
14
|
+
|
|
15
|
+
**Use it when** clients must keep working offline, several devices or tabs edit
|
|
16
|
+
the same document, and you have (or can run) a server that orders operations —
|
|
17
|
+
[`foldkit-durable`](https://github.com/doeixd/foldkit-plus/tree/main/packages/durable)
|
|
18
|
+
is one. **Not for** peer-to-peer collaboration: this is server-ordered and
|
|
19
|
+
single-writer-per-document, not a CRDT mesh. Concurrent edits to the same field
|
|
20
|
+
resolve by server arrival order unless you opt that field into the
|
|
21
|
+
[last-writer-wins register](#last-writer-wins-fields-experimental) below, and
|
|
22
|
+
there is no operational transform for collaborative text.
|
|
23
|
+
|
|
24
|
+
It is the **client half** of [replicated Foldkit state](https://github.com/doeixd/foldkit-plus/blob/main/docs/replication.md);
|
|
25
|
+
the [guide](https://github.com/doeixd/foldkit-plus/blob/main/docs/replication.md)
|
|
26
|
+
covers the mental model and when not to use it.
|
|
27
|
+
|
|
28
|
+
## Install
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pnpm add foldkit-sync
|
|
32
|
+
```
|
|
6
33
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
`foldkit-durable` (or any server that orders operations) as the authority. The
|
|
10
|
-
[guide](https://github.com/doeixd/foldkit-plus/blob/main/docs/replication.md) covers the mental model and when not to use
|
|
11
|
-
it.
|
|
34
|
+
`foldkit` and `effect` are peer dependencies; `foldkit-surface` comes with it.
|
|
35
|
+
`foldkit-durable` is the server half.
|
|
12
36
|
|
|
13
37
|
## Quick start
|
|
14
38
|
|
|
15
39
|
`Sync.forApplication` is the Foldkit-facing layer. From one
|
|
16
|
-
`Surface.application` and a writable projection it derives the shared schema,
|
|
17
|
-
durable Message subset, the initial snapshot, and replay, and exposes a
|
|
18
|
-
Surface over the same projection.
|
|
19
|
-
reducer.
|
|
40
|
+
`Surface.application` and a writable projection it derives the shared schema,
|
|
41
|
+
the durable Message subset, the initial snapshot, and replay, and exposes a
|
|
42
|
+
read-only Surface over the same projection.
|
|
20
43
|
|
|
21
44
|
```ts
|
|
22
45
|
import { Schema } from 'effect'
|
|
23
46
|
import { defineMessageUnion } from 'foldkit/message'
|
|
24
|
-
import
|
|
25
|
-
import {
|
|
47
|
+
import type * as Update from 'foldkit/update'
|
|
48
|
+
import { MessageSet, Projection, Surface } from 'foldkit-surface'
|
|
49
|
+
import { DocumentId, Sync } from 'foldkit-sync'
|
|
26
50
|
|
|
27
51
|
const Model = Schema.Struct({
|
|
28
52
|
todos: Schema.Array(Schema.Struct({ id: Schema.String, title: Schema.String })),
|
|
29
53
|
selectedTodoId: Schema.NullOr(Schema.String),
|
|
54
|
+
lastError: Schema.NullOr(Schema.String),
|
|
30
55
|
})
|
|
56
|
+
type Model = typeof Model.Type
|
|
57
|
+
|
|
31
58
|
const Message = defineMessageUnion({
|
|
32
59
|
CreatedTodo: { id: Schema.String, title: Schema.String },
|
|
33
60
|
RenamedTodo: { id: Schema.String, title: Schema.String },
|
|
34
61
|
SelectedTodo: { id: Schema.String },
|
|
35
62
|
})
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
const
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
63
|
+
type Message = typeof Message.Type
|
|
64
|
+
|
|
65
|
+
const initial: Model = { todos: [], selectedTodoId: null, lastError: null }
|
|
66
|
+
|
|
67
|
+
type Return = Update.Return<Model, Message>
|
|
68
|
+
// The application's ordinary transition. Sync does not add a second one.
|
|
69
|
+
const update = (model: Model, message: Message): Return =>
|
|
70
|
+
Message.match<Return>(message, {
|
|
71
|
+
CreatedTodo: ({ id, title }) => ({
|
|
72
|
+
model: { ...model, todos: [...model.todos, { id, title }] },
|
|
73
|
+
}),
|
|
74
|
+
RenamedTodo: ({ id, title }) => ({
|
|
75
|
+
model: {
|
|
76
|
+
...model,
|
|
77
|
+
todos: model.todos.map(todo => (todo.id === id ? { ...todo, title } : todo)),
|
|
78
|
+
},
|
|
79
|
+
}),
|
|
80
|
+
SelectedTodo: ({ id }) => ({ model: { ...model, selectedTodoId: id } }),
|
|
81
|
+
})
|
|
82
|
+
|
|
83
|
+
const App = Surface.application({ Model, Message, initial, update })
|
|
84
|
+
|
|
85
|
+
const TodoSync = Sync.forApplication(App).make({
|
|
86
|
+
documentId: DocumentId.make('todos'),
|
|
87
|
+
shared: Projection.pick(App.fields.todos), // the codec, read, and write
|
|
88
|
+
durable: MessageSet.make(App, [Message.CreatedTodo, Message.RenamedTodo]),
|
|
52
89
|
})
|
|
53
90
|
```
|
|
54
91
|
|
|
55
|
-
Only `todos` is replicated; `selectedTodoId`
|
|
56
|
-
installs the shared slice into the application's initial Model,
|
|
57
|
-
durable Message through `update`, and reads the shared slice back.
|
|
92
|
+
Only `todos` is replicated; `selectedTodoId` and `lastError` stay local. The
|
|
93
|
+
derived `replay` installs the shared slice into the application's initial Model,
|
|
94
|
+
applies the durable Message through `update`, and reads the shared slice back.
|
|
58
95
|
|
|
59
96
|
A durable Message must therefore be a deterministic, state-only transition of
|
|
60
97
|
the shared projection. Replay refuses one whose `update` returns a Command (a
|
|
@@ -69,14 +106,22 @@ On the server, the same contract produces the journal's codecs and reducer, so
|
|
|
69
106
|
neither is written twice:
|
|
70
107
|
|
|
71
108
|
```ts
|
|
72
|
-
import {
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
109
|
+
import { Effect } from 'effect'
|
|
110
|
+
import { actorId, documentId, makeJournal, opId } from 'foldkit-durable'
|
|
111
|
+
|
|
112
|
+
type Principal = { readonly actorId: string }
|
|
113
|
+
|
|
114
|
+
const server = Effect.gen(function* () {
|
|
115
|
+
const journal = yield* makeJournal({
|
|
116
|
+
// Operation and snapshot codecs, `empty`, `reduce`, and `authorize` if declared.
|
|
117
|
+
...TodoSync.journalContract(),
|
|
118
|
+
file: 'todos.sqlite',
|
|
119
|
+
// The two packages brand their ids separately, so re-brand at the seam.
|
|
120
|
+
opId: operation => opId(operation.opId),
|
|
121
|
+
actorId: (principal: Principal) => actorId(principal.actorId),
|
|
122
|
+
})
|
|
123
|
+
return yield* journal.load(documentId('todos'))
|
|
124
|
+
}).pipe(Effect.scoped)
|
|
80
125
|
```
|
|
81
126
|
|
|
82
127
|
### Mounting
|
|
@@ -87,47 +132,75 @@ persisted afterwards in a Command; the shared slice is re-installed from the
|
|
|
87
132
|
replica when an exchange or a rejection changes it, or when a persist fails.
|
|
88
133
|
|
|
89
134
|
```ts
|
|
90
|
-
|
|
91
|
-
|
|
135
|
+
import { Effect, Scope } from 'effect'
|
|
136
|
+
import { ReplicaId, Sync } from 'foldkit-sync'
|
|
137
|
+
|
|
138
|
+
const container = document.getElementById('app')! // Foldkit needs the element to have an id
|
|
139
|
+
|
|
140
|
+
const scope = Effect.runSync(Scope.make())
|
|
141
|
+
const storage = Effect.runSync(
|
|
142
|
+
Effect.provideService(Sync.indexedDb('todos/tab-1'), Scope.Scope, scope),
|
|
143
|
+
)
|
|
144
|
+
const replica = Effect.runSync(TodoSync.openReplica(ReplicaId.make('tab-1'), storage))
|
|
145
|
+
|
|
146
|
+
const mounted = Sync.mount(App, TodoSync, {
|
|
92
147
|
replica,
|
|
93
|
-
container
|
|
94
|
-
view: (model, h) => ({
|
|
148
|
+
container,
|
|
149
|
+
view: (model, h) => ({
|
|
150
|
+
title: 'Todos',
|
|
151
|
+
body: h.ul(
|
|
152
|
+
[],
|
|
153
|
+
model.todos.map(todo => h.li([], [todo.title])),
|
|
154
|
+
),
|
|
155
|
+
}),
|
|
95
156
|
onPersistenceFailure: (model, error) => ({ ...model, lastError: error.message }),
|
|
96
157
|
})
|
|
97
|
-
|
|
158
|
+
|
|
159
|
+
// The exchange loop: once, then after every submit, retrying a failed exchange.
|
|
160
|
+
Effect.runFork(
|
|
161
|
+
Effect.provide(replica.start, Sync.transport.socket({ url: 'wss://example.com/sync' })),
|
|
162
|
+
)
|
|
163
|
+
|
|
164
|
+
mounted.dispatch(Message.CreatedTodo({ id: crypto.randomUUID(), title: 'Milk' }))
|
|
98
165
|
mounted.model() // the Model after the last transition
|
|
99
166
|
await mounted.dispose() // waits for in-flight persists; the replica stays open
|
|
100
167
|
```
|
|
101
168
|
|
|
102
|
-
`url` routes the URL through the application:
|
|
103
|
-
into the Model before the first render,
|
|
104
|
-
for every navigation, and `onUrlRequest`
|
|
105
|
-
the
|
|
106
|
-
A `foldkit-mirror` URL mirror
|
|
107
|
-
|
|
169
|
+
The optional `url` option routes the URL through the application:
|
|
170
|
+
`init(model, url)` reduces it into the Model before the first render,
|
|
171
|
+
`onUrlChange(url)` names the Message for every navigation, and `onUrlRequest`
|
|
172
|
+
the Message for a link click (omitted, the mount follows the link itself: an
|
|
173
|
+
internal one pushed, an external one loaded). A `foldkit-mirror` URL mirror
|
|
174
|
+
plugs in there as
|
|
175
|
+
`url: { init: (model, url) => Filters.reduce(model, url), onUrlChange: url => Message.UrlChanged({ url }) }`;
|
|
108
176
|
`subscriptions` and `resources` carry its write entry and the store layer.
|
|
109
177
|
|
|
110
178
|
`mounted.model`, `mounted.dispatch`, `mounted.subscribe`, and `mounted.observe`
|
|
111
179
|
are the host an agent binds to; `observe` reports every application Message the
|
|
112
180
|
runtime applies, which a capability with a `completion` contract needs. See
|
|
113
|
-
[docs/sync-runtime-binding.md](
|
|
181
|
+
[docs/sync-runtime-binding.md](https://github.com/doeixd/foldkit-plus/blob/main/docs/sync-runtime-binding.md) for what the
|
|
114
182
|
mount guarantees and why no Foldkit change is required.
|
|
115
183
|
|
|
116
184
|
### Fragments
|
|
117
185
|
|
|
118
|
-
A large application declares one fragment per feature and composes them
|
|
186
|
+
A large application declares one fragment per feature and composes them. `App`
|
|
187
|
+
below is a wider application than the quick start's: it also has a `members`
|
|
188
|
+
field and an `Invited` Message.
|
|
119
189
|
|
|
120
190
|
```ts
|
|
121
|
-
const
|
|
122
|
-
const Todos =
|
|
191
|
+
const AppSync = Sync.forApplication(App)
|
|
192
|
+
const Todos = AppSync.fragment({
|
|
123
193
|
shared: Projection.pick(App.fields.todos),
|
|
124
194
|
durable: MessageSet.make(App, [Message.CreatedTodo, Message.RenamedTodo]),
|
|
125
195
|
})
|
|
126
|
-
const Members =
|
|
196
|
+
const Members = AppSync.fragment({
|
|
127
197
|
shared: Projection.pick(App.fields.members),
|
|
128
198
|
durable: MessageSet.make(App, [Message.Invited]),
|
|
129
199
|
})
|
|
130
|
-
const Board =
|
|
200
|
+
const Board = AppSync.make({
|
|
201
|
+
documentId: DocumentId.make('board'),
|
|
202
|
+
...AppSync.compose(Todos, Members),
|
|
203
|
+
})
|
|
131
204
|
```
|
|
132
205
|
|
|
133
206
|
`compose` merges the shared projections and the durable subsets and infers the
|
|
@@ -138,52 +211,59 @@ over the same field are a different mistake, which `Module.validate` reports.
|
|
|
138
211
|
### Authorization
|
|
139
212
|
|
|
140
213
|
Policy attaches to the contract per durable variant and compiles into the
|
|
141
|
-
journal contract, so the server applies it with no glue
|
|
214
|
+
journal contract, so the server applies it with no glue. This is the same
|
|
215
|
+
`Board` as above, with a principal fixed and one rule added:
|
|
142
216
|
|
|
143
217
|
```ts
|
|
144
|
-
const
|
|
145
|
-
const Board =
|
|
146
|
-
documentId:
|
|
147
|
-
...
|
|
218
|
+
const Authorized = Sync.forApplication(App).withPrincipal<{ readonly role: 'admin' | 'guest' }>()
|
|
219
|
+
const Board = Authorized.make({
|
|
220
|
+
documentId: DocumentId.make('board'),
|
|
221
|
+
...Authorized.compose(Todos, Members),
|
|
148
222
|
authorize: {
|
|
149
223
|
// `message` is exactly `RenamedTodo`; `shared` is the authoritative snapshot.
|
|
150
224
|
RenamedTodo: ({ principal, message, shared }) =>
|
|
151
225
|
principal.role === 'admin' && shared.todos.some(todo => todo.id === message.id),
|
|
152
226
|
},
|
|
153
227
|
})
|
|
154
|
-
|
|
155
|
-
const journal = yield* makeJournal({ ...Board.journalContract(), file, opId, actorId })
|
|
156
228
|
```
|
|
157
229
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
230
|
+
`Board.journalContract()` then carries the compiled rules in the shape
|
|
231
|
+
`makeJournal` takes. A durable variant without a rule is allowed; a key that is
|
|
232
|
+
not a durable tag is a compile error. The rule runs inside the append
|
|
233
|
+
transaction against the snapshot, so keep it synchronous and local. The client
|
|
234
|
+
does not run it: a replica has no principal, and a refused operation comes back
|
|
235
|
+
as a rejection.
|
|
162
236
|
|
|
163
237
|
### Lower level
|
|
164
238
|
|
|
165
|
-
`Sync.forApplication(App).make` compiles down to `
|
|
166
|
-
primitive. Use `
|
|
239
|
+
`Sync.forApplication(App).make` compiles down to `Sync.define`, the protocol
|
|
240
|
+
primitive. Use `Sync.define` directly when there is no Foldkit application to
|
|
167
241
|
derive the contract from — a non-Foldkit client, or a hand-written projection.
|
|
168
242
|
|
|
169
243
|
```ts
|
|
170
|
-
import { Effect } from 'effect'
|
|
171
|
-
import {
|
|
172
|
-
|
|
173
|
-
const
|
|
174
|
-
|
|
175
|
-
const
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
)
|
|
184
|
-
|
|
244
|
+
import { Effect, Schema } from 'effect'
|
|
245
|
+
import { DocumentId, ReplicaId, Sync, type TransportClient } from 'foldkit-sync'
|
|
246
|
+
|
|
247
|
+
const Shared = Schema.Struct({ todos: Schema.Array(Schema.String) })
|
|
248
|
+
const Renamed = Schema.Struct({ _tag: Schema.Literal('Renamed'), title: Schema.String })
|
|
249
|
+
declare const transport: TransportClient // the application's own server client
|
|
250
|
+
|
|
251
|
+
const Protocol = Sync.define({
|
|
252
|
+
documentId: DocumentId.make('todos'),
|
|
253
|
+
message: Renamed,
|
|
254
|
+
shared: Shared,
|
|
255
|
+
empty: { todos: [] },
|
|
256
|
+
durable: () => true,
|
|
257
|
+
replay: (shared, message) => ({ todos: [...shared.todos, message.title] }),
|
|
258
|
+
})
|
|
185
259
|
|
|
186
|
-
const
|
|
260
|
+
const program = Effect.gen(function* () {
|
|
261
|
+
const storage = yield* Sync.indexedDb('todos-tab-1')
|
|
262
|
+
const replica = yield* Protocol.openReplica(ReplicaId.make('tab-1'), storage)
|
|
263
|
+
yield* replica.submit({ _tag: 'Renamed', title: 'Milk' })
|
|
264
|
+
yield* Effect.provide(replica.synchronize, Sync.transport.fromPromise(transport))
|
|
265
|
+
return yield* replica.shared
|
|
266
|
+
}).pipe(Effect.scoped)
|
|
187
267
|
```
|
|
188
268
|
|
|
189
269
|
## What it owns
|
|
@@ -194,10 +274,9 @@ const shared = Effect.runSync(replica.shared)
|
|
|
194
274
|
declared twice. `Projection.pick`/`Projection.compose` build the writable projection;
|
|
195
275
|
`TodoSync.journalContract()` builds the durable codecs and reducer.
|
|
196
276
|
- The operation envelope: `replicaId:localSequence` identity, `baseCursor`, and
|
|
197
|
-
protocol/schema versions. The
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
`CommittedOperation`.
|
|
277
|
+
protocol/schema versions. The contract's `codec` (`normalizeOperation`,
|
|
278
|
+
`operationFrom`, `committedFrom`, `decodeExchange`) is there for a custom
|
|
279
|
+
transport or server; a server-committed operation is a `CommittedOperation`.
|
|
201
280
|
- A persisted outbox and optimistic projection: a durable Message is visible
|
|
202
281
|
immediately and rebased onto the authoritative order.
|
|
203
282
|
- Reconciliation: committed operations are replayed in order, acknowledged or
|
|
@@ -216,23 +295,23 @@ const shared = Effect.runSync(replica.shared)
|
|
|
216
295
|
- Branded positions: `Sequence` (a committed document position) and
|
|
217
296
|
`LocalSequence` (a replica's own 1-based counter) cannot be confused, so a
|
|
218
297
|
client counter is never passed where a committed position is expected.
|
|
219
|
-
- Presence (`
|
|
220
|
-
outside the durable log. A peer that stops refreshing is dropped, not
|
|
298
|
+
- Presence (`Sync.presence.make`): an ephemeral, TTL'd peer registry,
|
|
299
|
+
deliberately outside the durable log. A peer that stops refreshing is dropped, not
|
|
221
300
|
replayed. It is an Effect driven by the `Clock` (so a `TestClock` makes the
|
|
222
301
|
TTL deterministic), peers live in a `Ref`, and the channel is a `PubSub`.
|
|
223
302
|
Every value is decoded through the required `decodeValue` before it is stored,
|
|
224
303
|
so a hostile peer cannot inject a value your `Update` type does not describe.
|
|
225
|
-
Presence can travel over a socket — `
|
|
226
|
-
`
|
|
227
|
-
in-process via `
|
|
228
|
-
emits the current peers and re-emits
|
|
229
|
-
`subscribe` callback.
|
|
304
|
+
Presence can travel over a socket — `Sync.presence.socketChannel` on the
|
|
305
|
+
client and `Sync.presence.serve` fanning through a `Sync.presence.hub` on the
|
|
306
|
+
server — or in-process via `Sync.presence.loopbackChannel`.
|
|
307
|
+
`presence.changes` is a `Stream` that emits the current peers and re-emits
|
|
308
|
+
them on every change, alongside the `subscribe` callback.
|
|
230
309
|
- The transport seam (`Transport`): an Effect service with a loopback layer, a
|
|
231
310
|
bridge to and from the promise client the replica speaks, and a WebSocket
|
|
232
311
|
client layer. The socket reconnects on an exponential, jittered backoff and
|
|
233
312
|
re-sends queued and in-flight frames with their original ids, so a lost reply
|
|
234
313
|
is answered rather than dropped; retries (`maxRetries`) and the queue
|
|
235
|
-
(`maxQueue`) are bounded, and `
|
|
314
|
+
(`maxQueue`) are bounded, and `Sync.transport.serve` is the server side of a
|
|
236
315
|
connection. A refusal is an exchange result; only a wire failure is a
|
|
237
316
|
`TransportError`.
|
|
238
317
|
|
|
@@ -246,17 +325,17 @@ const shared = Effect.runSync(replica.shared)
|
|
|
246
325
|
server is left to the application; the sync example shows a `ws` one for the
|
|
247
326
|
transport (presence over `ws` is not wired there yet).
|
|
248
327
|
|
|
249
|
-
## Last-writer-wins fields (
|
|
328
|
+
## Last-writer-wins fields (experimental)
|
|
250
329
|
|
|
251
|
-
Use `
|
|
252
|
-
instead of the order offline clients reconnect. It returns a schema and a pure
|
|
330
|
+
Use `Sync.lww.register` when a field's winner should depend on a write's
|
|
331
|
+
logical time instead of the order offline clients reconnect. It returns a schema and a pure
|
|
253
332
|
`merge` function to call inside the application's existing `update`:
|
|
254
333
|
|
|
255
334
|
```ts
|
|
256
335
|
import { Schema } from 'effect'
|
|
257
|
-
import {
|
|
336
|
+
import { ReplicaId, Sync } from 'foldkit-sync'
|
|
258
337
|
|
|
259
|
-
const Title =
|
|
338
|
+
const Title = Sync.lww.register(Schema.String)
|
|
260
339
|
const Shared = Schema.Struct({ title: Title.schema })
|
|
261
340
|
const Renamed = Schema.Struct({ _tag: Schema.Literal('Renamed'), title: Title.schema })
|
|
262
341
|
|
|
@@ -267,7 +346,7 @@ const update = (model: typeof Shared.Type, message: typeof Renamed.Type) => ({
|
|
|
267
346
|
|
|
268
347
|
const message: typeof Renamed.Type = {
|
|
269
348
|
_tag: 'Renamed',
|
|
270
|
-
title: { stamp: { counter: 1, replicaId: 'tab-a' }, value: 'Milk' },
|
|
349
|
+
title: { stamp: { counter: 1, replicaId: ReplicaId.make('tab-a') }, value: 'Milk' },
|
|
271
350
|
}
|
|
272
351
|
```
|
|
273
352
|
|
|
@@ -276,44 +355,44 @@ order, independent of locale. This is logical ordering, not wall-clock time.
|
|
|
276
355
|
The rule follows the total-order register model described in
|
|
277
356
|
[Replicated Data Types: Specification, Verification, Optimality](https://www.microsoft.com/en-us/research/publication/replicated-data-types-specification-verification-optimality/).
|
|
278
357
|
|
|
279
|
-
Allocate stamps **before dispatch**, never in `update` or replay.
|
|
280
|
-
persists a counter independently of the outbox, so a
|
|
281
|
-
write cannot cause timestamp reuse after reload:
|
|
358
|
+
Allocate stamps **before dispatch**, never in `update` or replay.
|
|
359
|
+
`Sync.lww.openClock` persists a counter independently of the outbox, so a
|
|
360
|
+
rejected or unsubmitted write cannot cause timestamp reuse after reload:
|
|
282
361
|
|
|
283
362
|
```ts
|
|
284
363
|
import { Effect } from 'effect'
|
|
285
|
-
import {
|
|
364
|
+
import { DocumentId, ReplicaId, Sync, type Replica } from 'foldkit-sync'
|
|
286
365
|
|
|
287
|
-
|
|
366
|
+
type Shared = typeof Shared.Type
|
|
367
|
+
type Renamed = typeof Renamed.Type
|
|
368
|
+
|
|
369
|
+
const rename = (replica: Replica<Renamed, Shared>, title: string) =>
|
|
288
370
|
Effect.gen(function* () {
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
)
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
replica.submit({ _tag: 'Renamed', title: { stamp, value:
|
|
299
|
-
|
|
300
|
-
}
|
|
301
|
-
await Effect.runPromise(clock.close)
|
|
302
|
-
}
|
|
371
|
+
// A separate database from the replica's outbox; one clock per document/writer.
|
|
372
|
+
const storage = yield* Sync.indexedDb('todos-tab-a-clock')
|
|
373
|
+
const clock = yield* Sync.lww.openClock({
|
|
374
|
+
documentId: DocumentId.make('todos'),
|
|
375
|
+
replicaId: ReplicaId.make('tab-a'),
|
|
376
|
+
storage,
|
|
377
|
+
})
|
|
378
|
+
const shared = yield* replica.shared
|
|
379
|
+
const stamp = yield* clock.next(shared.title.stamp.counter)
|
|
380
|
+
yield* replica.submit({ _tag: 'Renamed', title: { stamp, value: title } })
|
|
381
|
+
yield* clock.close
|
|
382
|
+
}).pipe(Effect.scoped)
|
|
303
383
|
```
|
|
304
384
|
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
only the saved local counter. The clock does not inspect application state.
|
|
385
|
+
`next(observedCounter)` returns only after persisting a counter greater than
|
|
386
|
+
both its saved value and the supplied observation. Pass the latest observed
|
|
387
|
+
counter for the field being edited; when causality spans several registers, pass
|
|
388
|
+
their maximum. Calling `next()` without an observation advances only the saved
|
|
389
|
+
local counter. The clock does not inspect application state.
|
|
311
390
|
|
|
312
391
|
Allocations on one handle are serialized. Separate handles use storage's
|
|
313
392
|
compare-and-swap check; a stale handle fails and must be closed and reopened.
|
|
314
393
|
Storage failures reject allocation without returning a stamp. Counter gaps after
|
|
315
394
|
a crash or failed submission are harmless. Counters are nonnegative safe
|
|
316
|
-
integers; exhaustion fails before writing. `close
|
|
395
|
+
integers; exhaustion fails before writing. `close` waits for accepted
|
|
317
396
|
allocations and refuses new ones. Opening takes ownership of storage and closes
|
|
318
397
|
it on initialization failure too.
|
|
319
398
|
|
|
@@ -330,9 +409,9 @@ boundaries. Transforming value codecs retain both their encoded and decoded
|
|
|
330
409
|
types.
|
|
331
410
|
|
|
332
411
|
Keep the **whole register**, including the winning stamp, in shared snapshots.
|
|
333
|
-
For deletion, `
|
|
334
|
-
dropping its stamp would allow an old offline write to resurrect the
|
|
335
|
-
A newer write may intentionally replace that tombstone.
|
|
412
|
+
For deletion, `Sync.lww.register(Schema.NullOr(Entity))` can retain a `null`
|
|
413
|
+
tombstone: dropping its stamp would allow an old offline write to resurrect the
|
|
414
|
+
value. A newer write may intentionally replace that tombstone.
|
|
336
415
|
|
|
337
416
|
The journal still orders and authorizes every operation, including losing writes.
|
|
338
417
|
Replica ids and counters in Messages are client-authored data, not authenticated
|
|
@@ -340,6 +419,36 @@ identity. Applications must enforce writer ownership and clock policy at admissi
|
|
|
340
419
|
where needed. A losing write can still trigger a Command if the application's
|
|
341
420
|
update produces one; this helper only resolves state.
|
|
342
421
|
|
|
343
|
-
These
|
|
344
|
-
|
|
345
|
-
|
|
422
|
+
These helpers do not claim arbitrary Messages commute. Specialized sets,
|
|
423
|
+
counters, and collaborative text remain future work.
|
|
424
|
+
|
|
425
|
+
## Older spellings
|
|
426
|
+
|
|
427
|
+
`Sync` groups this package's exports; it does not wrap them. Every name is still
|
|
428
|
+
exported on its own with the same signature, so code written against the older
|
|
429
|
+
spellings keeps working:
|
|
430
|
+
|
|
431
|
+
- `forApplication`, `mount`, `indexedDb` — same names on the namespace.
|
|
432
|
+
- `defineSync` is `Sync.define`; `syncMetrics` is `Sync.metrics`.
|
|
433
|
+
- `layerSocket`, `layerLoopback`, `layerFromPromise`, `toPromise`, `serveSocket`
|
|
434
|
+
and `nativeSocket` are `Sync.transport.socket`, `.loopback`, `.fromPromise`,
|
|
435
|
+
`.toPromise`, `.serve` and `.nativeSocket`.
|
|
436
|
+
- `createPresence`, `createPresenceHub`, `servePresence`,
|
|
437
|
+
`socketPresenceChannel` and `loopbackPresenceChannel` are
|
|
438
|
+
`Sync.presence.make`, `.hub`, `.serve`, `.socketChannel` and
|
|
439
|
+
`.loopbackChannel`.
|
|
440
|
+
- `lwwRegister` and `openLwwClock` are `Sync.lww.register` and
|
|
441
|
+
`Sync.lww.openClock`.
|
|
442
|
+
- `documentId('todos')` and `DocumentId.make('todos')` return the same value,
|
|
443
|
+
and likewise for `replicaId`, `opId`, `sequence` and `localSequence`.
|
|
444
|
+
|
|
445
|
+
## See also
|
|
446
|
+
|
|
447
|
+
- [Replicated state](https://github.com/doeixd/foldkit-plus/blob/main/docs/replication.md) — the mental model, and
|
|
448
|
+
when not to use it.
|
|
449
|
+
- [Runtime binding](https://github.com/doeixd/foldkit-plus/blob/main/docs/sync-runtime-binding.md) — what
|
|
450
|
+
`Sync.mount` guarantees, and why no Foldkit change is required.
|
|
451
|
+
- [`foldkit-durable`](https://github.com/doeixd/foldkit-plus/tree/main/packages/durable) — the server half; [`foldkit-mirror`](https://github.com/doeixd/foldkit-plus/tree/main/packages/mirror) plugs into the mount's
|
|
452
|
+
`url` option.
|
|
453
|
+
- [`examples/todo-app`](https://github.com/doeixd/foldkit-plus/tree/main/examples/todo-app) — two fragments, owner-only rules, and a browser mount;
|
|
454
|
+
[`examples/sync`](https://github.com/doeixd/foldkit-plus/tree/main/examples/sync) is the in-process trace.
|