foldkit-sync 0.3.1 → 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 +83 -63
- 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 +1 -1
package/README.md
CHANGED
|
@@ -36,17 +36,17 @@ pnpm add foldkit-sync
|
|
|
36
36
|
|
|
37
37
|
## Quick start
|
|
38
38
|
|
|
39
|
-
`forApplication` is the Foldkit-facing layer. From one
|
|
40
|
-
and a writable projection it derives the shared schema,
|
|
41
|
-
subset, the initial snapshot, and replay, and exposes a
|
|
42
|
-
the same projection.
|
|
39
|
+
`Sync.forApplication` is the Foldkit-facing layer. From one
|
|
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.
|
|
43
43
|
|
|
44
44
|
```ts
|
|
45
45
|
import { Schema } from 'effect'
|
|
46
46
|
import { defineMessageUnion } from 'foldkit/message'
|
|
47
47
|
import type * as Update from 'foldkit/update'
|
|
48
48
|
import { MessageSet, Projection, Surface } from 'foldkit-surface'
|
|
49
|
-
import {
|
|
49
|
+
import { DocumentId, Sync } from 'foldkit-sync'
|
|
50
50
|
|
|
51
51
|
const Model = Schema.Struct({
|
|
52
52
|
todos: Schema.Array(Schema.Struct({ id: Schema.String, title: Schema.String })),
|
|
@@ -82,8 +82,8 @@ const update = (model: Model, message: Message): Return =>
|
|
|
82
82
|
|
|
83
83
|
const App = Surface.application({ Model, Message, initial, update })
|
|
84
84
|
|
|
85
|
-
const TodoSync = forApplication(App).make({
|
|
86
|
-
documentId:
|
|
85
|
+
const TodoSync = Sync.forApplication(App).make({
|
|
86
|
+
documentId: DocumentId.make('todos'),
|
|
87
87
|
shared: Projection.pick(App.fields.todos), // the codec, read, and write
|
|
88
88
|
durable: MessageSet.make(App, [Message.CreatedTodo, Message.RenamedTodo]),
|
|
89
89
|
})
|
|
@@ -126,22 +126,24 @@ const server = Effect.gen(function* () {
|
|
|
126
126
|
|
|
127
127
|
### Mounting
|
|
128
128
|
|
|
129
|
-
`mount` runs the application over an open replica with one reducer. A
|
|
130
|
-
Message is applied at once through the application's `update` and
|
|
131
|
-
afterwards in a Command; the shared slice is re-installed from the
|
|
132
|
-
an exchange or a rejection changes it, or when a persist fails.
|
|
129
|
+
`Sync.mount` runs the application over an open replica with one reducer. A
|
|
130
|
+
durable Message is applied at once through the application's `update` and
|
|
131
|
+
persisted afterwards in a Command; the shared slice is re-installed from the
|
|
132
|
+
replica when an exchange or a rejection changes it, or when a persist fails.
|
|
133
133
|
|
|
134
134
|
```ts
|
|
135
135
|
import { Effect, Scope } from 'effect'
|
|
136
|
-
import {
|
|
136
|
+
import { ReplicaId, Sync } from 'foldkit-sync'
|
|
137
137
|
|
|
138
138
|
const container = document.getElementById('app')! // Foldkit needs the element to have an id
|
|
139
139
|
|
|
140
140
|
const scope = Effect.runSync(Scope.make())
|
|
141
|
-
const storage = Effect.runSync(
|
|
142
|
-
|
|
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))
|
|
143
145
|
|
|
144
|
-
const mounted = mount(App, TodoSync, {
|
|
146
|
+
const mounted = Sync.mount(App, TodoSync, {
|
|
145
147
|
replica,
|
|
146
148
|
container,
|
|
147
149
|
view: (model, h) => ({
|
|
@@ -155,7 +157,9 @@ const mounted = mount(App, TodoSync, {
|
|
|
155
157
|
})
|
|
156
158
|
|
|
157
159
|
// The exchange loop: once, then after every submit, retrying a failed exchange.
|
|
158
|
-
Effect.runFork(
|
|
160
|
+
Effect.runFork(
|
|
161
|
+
Effect.provide(replica.start, Sync.transport.socket({ url: 'wss://example.com/sync' })),
|
|
162
|
+
)
|
|
159
163
|
|
|
160
164
|
mounted.dispatch(Message.CreatedTodo({ id: crypto.randomUUID(), title: 'Milk' }))
|
|
161
165
|
mounted.model() // the Model after the last transition
|
|
@@ -184,16 +188,19 @@ below is a wider application than the quick start's: it also has a `members`
|
|
|
184
188
|
field and an `Invited` Message.
|
|
185
189
|
|
|
186
190
|
```ts
|
|
187
|
-
const
|
|
188
|
-
const Todos =
|
|
191
|
+
const AppSync = Sync.forApplication(App)
|
|
192
|
+
const Todos = AppSync.fragment({
|
|
189
193
|
shared: Projection.pick(App.fields.todos),
|
|
190
194
|
durable: MessageSet.make(App, [Message.CreatedTodo, Message.RenamedTodo]),
|
|
191
195
|
})
|
|
192
|
-
const Members =
|
|
196
|
+
const Members = AppSync.fragment({
|
|
193
197
|
shared: Projection.pick(App.fields.members),
|
|
194
198
|
durable: MessageSet.make(App, [Message.Invited]),
|
|
195
199
|
})
|
|
196
|
-
const Board =
|
|
200
|
+
const Board = AppSync.make({
|
|
201
|
+
documentId: DocumentId.make('board'),
|
|
202
|
+
...AppSync.compose(Todos, Members),
|
|
203
|
+
})
|
|
197
204
|
```
|
|
198
205
|
|
|
199
206
|
`compose` merges the shared projections and the durable subsets and infers the
|
|
@@ -208,9 +215,9 @@ journal contract, so the server applies it with no glue. This is the same
|
|
|
208
215
|
`Board` as above, with a principal fixed and one rule added:
|
|
209
216
|
|
|
210
217
|
```ts
|
|
211
|
-
const Authorized = forApplication(App).withPrincipal<{ readonly role: 'admin' | 'guest' }>()
|
|
218
|
+
const Authorized = Sync.forApplication(App).withPrincipal<{ readonly role: 'admin' | 'guest' }>()
|
|
212
219
|
const Board = Authorized.make({
|
|
213
|
-
documentId:
|
|
220
|
+
documentId: DocumentId.make('board'),
|
|
214
221
|
...Authorized.compose(Todos, Members),
|
|
215
222
|
authorize: {
|
|
216
223
|
// `message` is exactly `RenamedTodo`; `shared` is the authoritative snapshot.
|
|
@@ -229,27 +236,20 @@ as a rejection.
|
|
|
229
236
|
|
|
230
237
|
### Lower level
|
|
231
238
|
|
|
232
|
-
`forApplication(App).make` compiles down to `
|
|
233
|
-
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
|
|
234
241
|
derive the contract from — a non-Foldkit client, or a hand-written projection.
|
|
235
242
|
|
|
236
243
|
```ts
|
|
237
244
|
import { Effect, Schema } from 'effect'
|
|
238
|
-
import {
|
|
239
|
-
defineSync,
|
|
240
|
-
documentId,
|
|
241
|
-
indexedDb,
|
|
242
|
-
layerFromPromise,
|
|
243
|
-
replicaId,
|
|
244
|
-
type TransportClient,
|
|
245
|
-
} from 'foldkit-sync'
|
|
245
|
+
import { DocumentId, ReplicaId, Sync, type TransportClient } from 'foldkit-sync'
|
|
246
246
|
|
|
247
247
|
const Shared = Schema.Struct({ todos: Schema.Array(Schema.String) })
|
|
248
248
|
const Renamed = Schema.Struct({ _tag: Schema.Literal('Renamed'), title: Schema.String })
|
|
249
249
|
declare const transport: TransportClient // the application's own server client
|
|
250
250
|
|
|
251
|
-
const Protocol =
|
|
252
|
-
documentId:
|
|
251
|
+
const Protocol = Sync.define({
|
|
252
|
+
documentId: DocumentId.make('todos'),
|
|
253
253
|
message: Renamed,
|
|
254
254
|
shared: Shared,
|
|
255
255
|
empty: { todos: [] },
|
|
@@ -258,17 +258,17 @@ const Protocol = defineSync({
|
|
|
258
258
|
})
|
|
259
259
|
|
|
260
260
|
const program = Effect.gen(function* () {
|
|
261
|
-
const storage = yield* indexedDb('todos-tab-1')
|
|
262
|
-
const replica = yield* Protocol.openReplica(
|
|
261
|
+
const storage = yield* Sync.indexedDb('todos-tab-1')
|
|
262
|
+
const replica = yield* Protocol.openReplica(ReplicaId.make('tab-1'), storage)
|
|
263
263
|
yield* replica.submit({ _tag: 'Renamed', title: 'Milk' })
|
|
264
|
-
yield* Effect.provide(replica.synchronize,
|
|
264
|
+
yield* Effect.provide(replica.synchronize, Sync.transport.fromPromise(transport))
|
|
265
265
|
return yield* replica.shared
|
|
266
266
|
}).pipe(Effect.scoped)
|
|
267
267
|
```
|
|
268
268
|
|
|
269
269
|
## What it owns
|
|
270
270
|
|
|
271
|
-
- The Foldkit-facing contract (`forApplication(App).make`, optionally with
|
|
271
|
+
- The Foldkit-facing contract (`Sync.forApplication(App).make`, optionally with
|
|
272
272
|
a custom `replay`): derives the shared projection, the durable Message subset, the
|
|
273
273
|
initial snapshot, and the journal contract from the application, so none is
|
|
274
274
|
declared twice. `Projection.pick`/`Projection.compose` build the writable projection;
|
|
@@ -295,23 +295,23 @@ const program = Effect.gen(function* () {
|
|
|
295
295
|
- Branded positions: `Sequence` (a committed document position) and
|
|
296
296
|
`LocalSequence` (a replica's own 1-based counter) cannot be confused, so a
|
|
297
297
|
client counter is never passed where a committed position is expected.
|
|
298
|
-
- Presence (`
|
|
299
|
-
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
|
|
300
300
|
replayed. It is an Effect driven by the `Clock` (so a `TestClock` makes the
|
|
301
301
|
TTL deterministic), peers live in a `Ref`, and the channel is a `PubSub`.
|
|
302
302
|
Every value is decoded through the required `decodeValue` before it is stored,
|
|
303
303
|
so a hostile peer cannot inject a value your `Update` type does not describe.
|
|
304
|
-
Presence can travel over a socket — `
|
|
305
|
-
`
|
|
306
|
-
in-process via `
|
|
307
|
-
emits the current peers and re-emits
|
|
308
|
-
`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.
|
|
309
309
|
- The transport seam (`Transport`): an Effect service with a loopback layer, a
|
|
310
310
|
bridge to and from the promise client the replica speaks, and a WebSocket
|
|
311
311
|
client layer. The socket reconnects on an exponential, jittered backoff and
|
|
312
312
|
re-sends queued and in-flight frames with their original ids, so a lost reply
|
|
313
313
|
is answered rather than dropped; retries (`maxRetries`) and the queue
|
|
314
|
-
(`maxQueue`) are bounded, and `
|
|
314
|
+
(`maxQueue`) are bounded, and `Sync.transport.serve` is the server side of a
|
|
315
315
|
connection. A refusal is an exchange result; only a wire failure is a
|
|
316
316
|
`TransportError`.
|
|
317
317
|
|
|
@@ -327,15 +327,15 @@ const program = Effect.gen(function* () {
|
|
|
327
327
|
|
|
328
328
|
## Last-writer-wins fields (experimental)
|
|
329
329
|
|
|
330
|
-
Use `
|
|
331
|
-
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
|
|
332
332
|
`merge` function to call inside the application's existing `update`:
|
|
333
333
|
|
|
334
334
|
```ts
|
|
335
335
|
import { Schema } from 'effect'
|
|
336
|
-
import {
|
|
336
|
+
import { ReplicaId, Sync } from 'foldkit-sync'
|
|
337
337
|
|
|
338
|
-
const Title =
|
|
338
|
+
const Title = Sync.lww.register(Schema.String)
|
|
339
339
|
const Shared = Schema.Struct({ title: Title.schema })
|
|
340
340
|
const Renamed = Schema.Struct({ _tag: Schema.Literal('Renamed'), title: Title.schema })
|
|
341
341
|
|
|
@@ -346,7 +346,7 @@ const update = (model: typeof Shared.Type, message: typeof Renamed.Type) => ({
|
|
|
346
346
|
|
|
347
347
|
const message: typeof Renamed.Type = {
|
|
348
348
|
_tag: 'Renamed',
|
|
349
|
-
title: { stamp: { counter: 1, replicaId:
|
|
349
|
+
title: { stamp: { counter: 1, replicaId: ReplicaId.make('tab-a') }, value: 'Milk' },
|
|
350
350
|
}
|
|
351
351
|
```
|
|
352
352
|
|
|
@@ -355,13 +355,13 @@ order, independent of locale. This is logical ordering, not wall-clock time.
|
|
|
355
355
|
The rule follows the total-order register model described in
|
|
356
356
|
[Replicated Data Types: Specification, Verification, Optimality](https://www.microsoft.com/en-us/research/publication/replicated-data-types-specification-verification-optimality/).
|
|
357
357
|
|
|
358
|
-
Allocate stamps **before dispatch**, never in `update` or replay.
|
|
359
|
-
persists a counter independently of the outbox, so a
|
|
360
|
-
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:
|
|
361
361
|
|
|
362
362
|
```ts
|
|
363
363
|
import { Effect } from 'effect'
|
|
364
|
-
import {
|
|
364
|
+
import { DocumentId, ReplicaId, Sync, type Replica } from 'foldkit-sync'
|
|
365
365
|
|
|
366
366
|
type Shared = typeof Shared.Type
|
|
367
367
|
type Renamed = typeof Renamed.Type
|
|
@@ -369,10 +369,10 @@ type Renamed = typeof Renamed.Type
|
|
|
369
369
|
const rename = (replica: Replica<Renamed, Shared>, title: string) =>
|
|
370
370
|
Effect.gen(function* () {
|
|
371
371
|
// A separate database from the replica's outbox; one clock per document/writer.
|
|
372
|
-
const storage = yield* indexedDb('todos-tab-a-clock')
|
|
373
|
-
const clock = yield*
|
|
374
|
-
documentId:
|
|
375
|
-
replicaId:
|
|
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
376
|
storage,
|
|
377
377
|
})
|
|
378
378
|
const shared = yield* replica.shared
|
|
@@ -409,9 +409,9 @@ boundaries. Transforming value codecs retain both their encoded and decoded
|
|
|
409
409
|
types.
|
|
410
410
|
|
|
411
411
|
Keep the **whole register**, including the winning stamp, in shared snapshots.
|
|
412
|
-
For deletion, `
|
|
413
|
-
dropping its stamp would allow an old offline write to resurrect the
|
|
414
|
-
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.
|
|
415
415
|
|
|
416
416
|
The journal still orders and authorizes every operation, including losing writes.
|
|
417
417
|
Replica ids and counters in Messages are client-authored data, not authenticated
|
|
@@ -422,12 +422,32 @@ update produces one; this helper only resolves state.
|
|
|
422
422
|
These helpers do not claim arbitrary Messages commute. Specialized sets,
|
|
423
423
|
counters, and collaborative text remain future work.
|
|
424
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
|
+
|
|
425
445
|
## See also
|
|
426
446
|
|
|
427
447
|
- [Replicated state](https://github.com/doeixd/foldkit-plus/blob/main/docs/replication.md) — the mental model, and
|
|
428
448
|
when not to use it.
|
|
429
449
|
- [Runtime binding](https://github.com/doeixd/foldkit-plus/blob/main/docs/sync-runtime-binding.md) — what
|
|
430
|
-
`mount` guarantees, and why no Foldkit change is required.
|
|
450
|
+
`Sync.mount` guarantees, and why no Foldkit change is required.
|
|
431
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
|
|
432
452
|
`url` option.
|
|
433
453
|
- [`examples/todo-app`](https://github.com/doeixd/foldkit-plus/tree/main/examples/todo-app) — two fragments, owner-only rules, and a browser mount;
|