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 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 `Surface.application`
40
- and a writable projection it derives the shared schema, the durable Message
41
- subset, the initial snapshot, and replay, and exposes a read-only Surface over
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 { documentId, forApplication } from 'foldkit-sync'
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: documentId('todos'),
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 durable
130
- Message is applied at once through the application's `update` and persisted
131
- afterwards in a Command; the shared slice is re-installed from the replica when
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 { indexedDb, layerSocket, mount, replicaId } from 'foldkit-sync'
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(Effect.provideService(indexedDb('todos/tab-1'), Scope.Scope, scope))
142
- const replica = Effect.runSync(TodoSync.openReplica(replicaId('tab-1'), storage))
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(Effect.provide(replica.start, layerSocket({ url: 'wss://example.com/sync' })))
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 Sync = forApplication(App)
188
- const Todos = Sync.fragment({
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 = Sync.fragment({
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 = Sync.make({ documentId: documentId('board'), ...Sync.compose(Todos, Members) })
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: documentId('board'),
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 `defineSync`, the protocol
233
- primitive. Use `defineSync` directly when there is no Foldkit application to
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 = defineSync({
252
- documentId: documentId('todos'),
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(replicaId('tab-1'), storage)
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, layerFromPromise(transport))
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 (`createPresence`): an ephemeral, TTL'd peer registry, deliberately
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 — `socketPresenceChannel` on the client and
305
- `servePresence` fanning through a `createPresenceHub` on the server — or
306
- in-process via `loopbackPresenceChannel`. `presence.changes` is a `Stream` that
307
- emits the current peers and re-emits them on every change, alongside the
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 `serveSocket` is the server side of a
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 `lwwRegister` when a field's winner should depend on a write's logical time
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 { lwwRegister, replicaId } from 'foldkit-sync'
336
+ import { ReplicaId, Sync } from 'foldkit-sync'
337
337
 
338
- const Title = lwwRegister(Schema.String)
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: replicaId('tab-a') }, value: 'Milk' },
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. `openLwwClock`
359
- persists a counter independently of the outbox, so a rejected or unsubmitted
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 { documentId, indexedDb, openLwwClock, replicaId, type Replica } from 'foldkit-sync'
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* openLwwClock({
374
- documentId: documentId('todos'),
375
- replicaId: replicaId('tab-a'),
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, `lwwRegister(Schema.NullOr(Entity))` can retain a `null` tombstone:
413
- dropping its stamp would allow an old offline write to resurrect the value.
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;