foldkit-sync 0.1.0 → 0.2.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/dist/index.mjs CHANGED
@@ -1,47 +1,15 @@
1
- import { Context, Effect, Layer, Metric, Ref, Schedule, Schema, SynchronizedRef } from "effect";
2
- //#region src/indexedDb.ts
3
- /** One database per document/replica; CAS prevents two tabs from sharing a writer identity. */
4
- const indexedDb = async (name, factory = globalThis.indexedDB) => {
5
- const database = await new Promise((resolve, reject) => {
6
- const request = factory.open(name, 1);
7
- request.onupgradeneeded = () => request.result.createObjectStore("replica");
8
- request.onsuccess = () => resolve(request.result);
9
- request.onerror = () => reject(request.error);
10
- });
11
- database.onversionchange = () => database.close();
12
- return {
13
- load: () => new Promise((resolve, reject) => {
14
- const transaction = database.transaction("replica", "readonly");
15
- const request = transaction.objectStore("replica").get("state");
16
- transaction.oncomplete = () => resolve(request.result);
17
- transaction.onabort = () => reject(transaction.error ?? /* @__PURE__ */ new Error("IndexedDB read aborted"));
18
- }),
19
- save: (state, expectedRevision) => new Promise((resolve, reject) => {
20
- const transaction = database.transaction("replica", "readwrite", { durability: "strict" });
21
- const store = transaction.objectStore("replica");
22
- const request = store.get("state");
23
- let conflict = false;
24
- request.onsuccess = () => {
25
- if ((request.result?.revision ?? null) !== expectedRevision) {
26
- conflict = true;
27
- transaction.abort();
28
- return;
29
- }
30
- store.put(state, "state");
31
- };
32
- transaction.oncomplete = () => resolve();
33
- transaction.onabort = () => reject(conflict ? /* @__PURE__ */ new Error("Replica was changed by another writer") : transaction.error ?? /* @__PURE__ */ new Error("IndexedDB write aborted"));
34
- }),
35
- close: () => database.close()
36
- };
37
- };
38
- //#endregion
1
+ import { Clock, Context, Duration, Effect, Exit, Fiber, Layer, Metric, PubSub, Ref, Schedule, Schema, Stream, SynchronizedRef } from "effect";
39
2
  //#region src/errors.ts
40
3
  /** The persisted storage could not be read or written. */
41
4
  var StorageError = class extends Schema.TaggedError()("StorageError", {
42
5
  message: Schema.String,
43
6
  cause: Schema.optional(Schema.Unknown)
44
7
  }) {};
8
+ /** The stored clock state targets a schema version this build does not support. */
9
+ var UnsupportedClockVersionError = class extends Schema.TaggedError()("UnsupportedClockVersionError", {
10
+ schemaVersion: Schema.NullOr(Schema.Number),
11
+ message: Schema.String
12
+ }) {};
45
13
  /** The storage holds a different replica's state. */
46
14
  var WrongReplicaStorageError = class extends Schema.TaggedError()("WrongReplicaStorageError", {
47
15
  documentId: Schema.String,
@@ -74,62 +42,171 @@ var ForeignRejectionError = class extends Schema.TaggedError()("ForeignRejection
74
42
  }) {};
75
43
  /** The replica was closed while work was still being submitted. */
76
44
  var ReplicaClosedError = class extends Schema.TaggedError()("ReplicaClosedError", { message: Schema.String }) {};
45
+ /** The stored replica state targets a protocol or schema version this build does not support. */
46
+ var UnsupportedReplicaVersionError = class extends Schema.TaggedError()("UnsupportedReplicaVersionError", {
47
+ protocolVersion: Schema.NullOr(Schema.Number),
48
+ schemaVersion: Schema.NullOr(Schema.Number),
49
+ message: Schema.String
50
+ }) {};
51
+ //#endregion
52
+ //#region src/indexedDb.ts
53
+ const storageError = (message, cause) => new StorageError({
54
+ message: `${message}: ${cause instanceof Error ? cause.message : String(cause)}`,
55
+ cause
56
+ });
57
+ const openDatabase = (name, factory) => Effect.tryPromise({
58
+ try: () => new Promise((resolve, reject) => {
59
+ const request = factory.open(name, 1);
60
+ request.onupgradeneeded = () => request.result.createObjectStore("replica");
61
+ request.onsuccess = () => resolve(request.result);
62
+ request.onerror = () => reject(request.error);
63
+ request.onblocked = () => reject(/* @__PURE__ */ new Error("IndexedDB upgrade is blocked by another connection"));
64
+ }),
65
+ catch: (cause) => storageError("Could not open the storage", cause)
66
+ });
67
+ /** One database per document/replica; CAS prevents two tabs from sharing a writer identity. */
68
+ const indexedDb = (name, factory = globalThis.indexedDB) => Effect.gen(function* () {
69
+ const databaseName = typeof name === "string" ? name : yield* name.pipe(Effect.mapError((cause) => storageError("Could not read the storage name", cause)));
70
+ const database = yield* Effect.acquireRelease(openDatabase(databaseName, factory), (database) => Effect.sync(() => database.close()));
71
+ database.onversionchange = () => database.close();
72
+ return {
73
+ load: () => Effect.tryPromise({
74
+ try: () => new Promise((resolve, reject) => {
75
+ const transaction = database.transaction("replica", "readonly");
76
+ const request = transaction.objectStore("replica").get("state");
77
+ transaction.oncomplete = () => resolve(request.result);
78
+ transaction.onabort = () => reject(transaction.error ?? /* @__PURE__ */ new Error("IndexedDB read aborted"));
79
+ }),
80
+ catch: (cause) => storageError("Could not read the replica", cause)
81
+ }),
82
+ save: (state, expectedRevision) => Effect.tryPromise({
83
+ try: () => new Promise((resolve, reject) => {
84
+ const transaction = database.transaction("replica", "readwrite", { durability: "strict" });
85
+ const store = transaction.objectStore("replica");
86
+ const request = store.get("state");
87
+ let conflict = false;
88
+ request.onsuccess = () => {
89
+ if ((request.result?.revision ?? null) !== expectedRevision) {
90
+ conflict = true;
91
+ transaction.abort();
92
+ return;
93
+ }
94
+ store.put(state, "state");
95
+ };
96
+ transaction.oncomplete = () => resolve();
97
+ transaction.onabort = () => reject(conflict ? /* @__PURE__ */ new Error("Replica was changed by another writer") : transaction.error ?? /* @__PURE__ */ new Error("IndexedDB write aborted"));
98
+ }),
99
+ catch: (cause) => storageError("Could not save the replica", cause)
100
+ }),
101
+ close: Effect.sync(() => database.close())
102
+ };
103
+ });
104
+ //#endregion
105
+ //#region src/ids.ts
106
+ /** Identifies the replicated document a replica or operation belongs to. */
107
+ const DocumentId = Schema.NonEmptyString.pipe(Schema.brand("@foldkit-sync/DocumentId"));
108
+ /** Identifies one replica (writer identity) within a document. */
109
+ const ReplicaId = Schema.NonEmptyString.pipe(Schema.brand("@foldkit-sync/ReplicaId"));
110
+ /** The stable identity of one operation within a document. */
111
+ const OpId = Schema.NonEmptyString.pipe(Schema.brand("@foldkit-sync/OpId"));
112
+ const documentId = (value) => Schema.decodeUnknownSync(DocumentId)(value);
113
+ const replicaId = (value) => Schema.decodeUnknownSync(ReplicaId)(value);
114
+ const opId = (value) => Schema.decodeUnknownSync(OpId)(value);
77
115
  //#endregion
78
116
  //#region src/lww.ts
79
117
  /** A logical write time; replica ids break concurrent ties using UTF-16 order. */
80
118
  const Stamp = Schema.Struct({
81
119
  counter: Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER)),
82
- replicaId: Schema.NonEmptyString
120
+ replicaId: ReplicaId
83
121
  });
122
+ /** The persisted clock format. A bump must handle the older value explicitly. */
123
+ const CLOCK_SCHEMA_VERSION = 1;
84
124
  const ClockState = Schema.Struct({
85
- schemaVersion: Schema.Literal(1),
86
- documentId: Schema.NonEmptyString,
87
- replicaId: Stamp.fields.replicaId,
125
+ schemaVersion: Schema.Literal(CLOCK_SCHEMA_VERSION),
126
+ documentId: DocumentId,
127
+ replicaId: ReplicaId,
88
128
  revision: Stamp.fields.counter
89
129
  });
90
130
  const decodeClock = Schema.decodeUnknownSync(ClockState, { onExcessProperty: "error" });
91
131
  const decodeCounter = Schema.decodeUnknownSync(Stamp.fields.counter);
92
- /** Opens a durable clock in its own storage, taking ownership even if opening fails. */
93
- const openLwwClock = async ({ documentId, replicaId, storage }) => {
94
- let state;
132
+ const clockError = (message, cause) => new StorageError({
133
+ message: `${message}: ${cause instanceof Error ? cause.message : String(cause)}`,
134
+ cause
135
+ });
136
+ const VersionProbe = Schema.Struct({ schemaVersion: Schema.optional(Schema.Number) });
137
+ /**
138
+ * Tells a version this build does not understand apart from malformed data, so
139
+ * the caller gets an actionable failure and the stored state is preserved.
140
+ */
141
+ const unsupportedVersion = (input) => {
142
+ let found;
95
143
  try {
96
- const initial = decodeClock({
97
- schemaVersion: 1,
98
- documentId,
99
- replicaId,
100
- revision: 0
101
- });
102
- const saved = await storage.load();
103
- state = saved === void 0 ? initial : decodeClock(saved);
104
- if (state.documentId !== documentId || state.replicaId !== replicaId) throw new Error("Wrong clock storage");
105
- if (saved === void 0) await storage.save(state, null);
106
- } catch (error) {
107
- storage.close();
108
- throw error;
144
+ found = Schema.decodeUnknownSync(VersionProbe)(input);
145
+ } catch {
146
+ return;
109
147
  }
110
- let tail = Promise.resolve();
111
- let closing;
112
- return {
113
- next: (observedCounter = 0) => {
114
- if (closing !== void 0) return Promise.reject(/* @__PURE__ */ new Error("Clock is closed"));
115
- const allocation = tail.then(async () => {
116
- const next = decodeClock({
117
- ...state,
118
- revision: Math.max(state.revision, decodeCounter(observedCounter)) + 1
119
- });
120
- await storage.save(next, state.revision);
121
- state = next;
122
- return {
123
- counter: next.revision,
124
- replicaId
125
- };
148
+ if (found.schemaVersion === CLOCK_SCHEMA_VERSION) return void 0;
149
+ return new UnsupportedClockVersionError({
150
+ schemaVersion: found.schemaVersion ?? null,
151
+ message: `Stored clock uses schema ${found.schemaVersion ?? "?"}; this build supports ${CLOCK_SCHEMA_VERSION}`
152
+ });
153
+ };
154
+ /**
155
+ * Opens a durable clock over the caller's storage.
156
+ *
157
+ * Allocations are serialized through a `SynchronizedRef` and each persists before
158
+ * its stamp is returned. A crash after the save may skip a timestamp but never
159
+ * reuse one. Storage is owned by the caller; a failed open closes it so a partial
160
+ * initialization does not leak the connection.
161
+ */
162
+ const openLwwClock = (options) => Effect.gen(function* () {
163
+ const { documentId, replicaId, storage } = options;
164
+ yield* Effect.annotateCurrentSpan({
165
+ documentId,
166
+ replicaId
167
+ });
168
+ const initial = decodeClock({
169
+ schemaVersion: CLOCK_SCHEMA_VERSION,
170
+ documentId,
171
+ replicaId,
172
+ revision: 0
173
+ });
174
+ const saved = yield* storage.load();
175
+ const state = yield* Effect.try({
176
+ try: () => saved === void 0 ? initial : decodeClock(saved),
177
+ catch: (cause) => unsupportedVersion(saved) ?? clockError("Stored clock state is invalid", cause)
178
+ });
179
+ if (state.documentId !== documentId || state.replicaId !== replicaId) return yield* new StorageError({ message: "Wrong clock storage" });
180
+ if (saved === void 0) yield* storage.save(state, null);
181
+ const stateRef = yield* SynchronizedRef.make(state);
182
+ const closed = yield* Ref.make(false);
183
+ const next = (observedCounter = 0) => Effect.gen(function* () {
184
+ if (yield* Ref.get(closed)) return yield* new StorageError({ message: "Clock is closed" });
185
+ return yield* SynchronizedRef.modifyEffect(stateRef, (current) => Effect.gen(function* () {
186
+ if (yield* Ref.get(closed)) return yield* new StorageError({ message: "Clock is closed" });
187
+ const allocated = yield* Effect.try({
188
+ try: () => decodeClock({
189
+ ...current,
190
+ revision: Math.max(current.revision, decodeCounter(observedCounter)) + 1
191
+ }),
192
+ catch: (cause) => clockError("Invalid clock allocation", cause)
126
193
  });
127
- tail = allocation.then(() => {}, () => {});
128
- return allocation;
129
- },
130
- close: () => closing ??= tail.then(() => storage.close())
194
+ yield* storage.save(allocated, current.revision);
195
+ return [{
196
+ counter: allocated.revision,
197
+ replicaId
198
+ }, allocated];
199
+ }));
200
+ }).pipe(Effect.withSpan("Lww.next"));
201
+ return {
202
+ next,
203
+ close: Effect.gen(function* () {
204
+ if (yield* Ref.modify(closed, (current) => [current, true])) return;
205
+ yield* SynchronizedRef.modifyEffect(stateRef, (current) => Effect.succeed([void 0, current]));
206
+ yield* storage.close;
207
+ }).pipe(Effect.withSpan("Lww.close"))
131
208
  };
132
- };
209
+ }).pipe(Effect.withSpan("Lww.openClock"), Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : options.storage.close.pipe(Effect.ignore)));
133
210
  /**
134
211
  * A schema and reducer helper for a last-writer-wins register.
135
212
  * Allocate a unique stamp per write before dispatch, and retain it in the Message.
@@ -158,11 +235,13 @@ const lwwRegister = (value) => {
158
235
  * Tracks ephemeral peers with a time-to-live.
159
236
  *
160
237
  * Nothing here touches the durable log: presence is state a peer refreshes, and
161
- * a peer that stops refreshing is dropped, not replayed.
238
+ * a peer that stops refreshing is dropped, not replayed. Time comes from the
239
+ * `Clock`, so a `TestClock` drives the TTL deterministically.
162
240
  */
163
- const createPresence = (options) => {
164
- const now = options.now ?? (() => Date.now());
165
- const peers = /* @__PURE__ */ new Map();
241
+ const createPresence = (options) => Effect.gen(function* () {
242
+ const ttl = Duration.toMillis(options.ttl);
243
+ const peers = yield* Ref.make(/* @__PURE__ */ new Map());
244
+ const closed = yield* Ref.make(false);
166
245
  const listeners = /* @__PURE__ */ new Set();
167
246
  /** A subscriber must never fail an update. */
168
247
  const notify = () => {
@@ -170,11 +249,26 @@ const createPresence = (options) => {
170
249
  listener();
171
250
  } catch {}
172
251
  };
173
- const expired = (peer, at) => at - peer.updatedAt > options.ttl;
174
- const receive = (update) => {
252
+ const expired = (peer, at) => at - peer.updatedAt > ttl;
253
+ const put = (id, value, at) => Ref.update(peers, (map) => {
254
+ const next = new Map(map);
255
+ next.set(id, {
256
+ id,
257
+ value,
258
+ updatedAt: at
259
+ });
260
+ return next;
261
+ });
262
+ const remove = (id) => Ref.modify(peers, (map) => {
263
+ if (!map.has(id)) return [false, map];
264
+ const next = new Map(map);
265
+ next.delete(id);
266
+ return [true, next];
267
+ });
268
+ const receive = (update) => Effect.gen(function* () {
175
269
  if (update.id === options.id) return;
176
270
  if (update.value === null) {
177
- if (peers.delete(update.id)) notify();
271
+ if (yield* remove(update.id)) notify();
178
272
  return;
179
273
  }
180
274
  let value;
@@ -183,73 +277,68 @@ const createPresence = (options) => {
183
277
  } catch {
184
278
  return;
185
279
  }
186
- peers.set(update.id, {
187
- id: update.id,
188
- value,
189
- updatedAt: now()
280
+ yield* put(update.id, value, yield* Clock.currentTimeMillis);
281
+ notify();
282
+ });
283
+ const channel = options.channel;
284
+ const consuming = channel === void 0 ? void 0 : yield* Stream.runForEach(Stream.fromPubSub(channel.updates), receive).pipe(Effect.forkScoped);
285
+ const set = (value) => Effect.gen(function* () {
286
+ if (yield* Ref.get(closed)) return;
287
+ yield* put(options.id, value, yield* Clock.currentTimeMillis);
288
+ if (channel !== void 0) yield* channel.publish({
289
+ id: options.id,
290
+ value
190
291
  });
191
292
  notify();
192
- };
193
- const unsubscribe = options.channel?.subscribe(receive);
293
+ }).pipe(Effect.withSpan("Presence.set"));
194
294
  return {
195
- set: (value) => {
196
- peers.set(options.id, {
197
- id: options.id,
198
- value,
199
- updatedAt: now()
200
- });
201
- options.channel?.publish({
202
- id: options.id,
203
- value
204
- });
205
- notify();
206
- },
207
- leave: () => {
208
- peers.delete(options.id);
209
- options.channel?.publish({
295
+ set,
296
+ leave: Effect.gen(function* () {
297
+ if (yield* Ref.get(closed)) return;
298
+ yield* remove(options.id);
299
+ if (channel !== void 0) yield* channel.publish({
210
300
  id: options.id,
211
301
  value: null
212
302
  });
213
303
  notify();
214
- },
215
- peers: () => {
216
- const at = now();
217
- return [...peers.values()].filter((peer) => !expired(peer, at)).map((peer) => ({ ...peer }));
218
- },
219
- prune: () => {
220
- const at = now();
221
- let changed = false;
222
- for (const [id, peer] of peers) if (expired(peer, at)) {
223
- peers.delete(id);
224
- changed = true;
225
- }
226
- if (changed) notify();
227
- },
304
+ }).pipe(Effect.withSpan("Presence.leave")),
305
+ peers: Effect.gen(function* () {
306
+ const at = yield* Clock.currentTimeMillis;
307
+ return [...(yield* Ref.get(peers)).values()].filter((peer) => !expired(peer, at)).map((peer) => ({ ...peer }));
308
+ }),
309
+ prune: Effect.gen(function* () {
310
+ if (yield* Ref.get(closed)) return;
311
+ const at = yield* Clock.currentTimeMillis;
312
+ if (yield* Ref.modify(peers, (map) => {
313
+ let removed = false;
314
+ const next = new Map(map);
315
+ for (const [id, peer] of map) if (expired(peer, at)) {
316
+ next.delete(id);
317
+ removed = true;
318
+ }
319
+ return [removed, next];
320
+ })) notify();
321
+ }).pipe(Effect.withSpan("Presence.prune")),
228
322
  subscribe: (listener) => {
229
323
  listeners.add(listener);
230
324
  return () => listeners.delete(listener);
231
325
  },
232
- close: () => {
233
- unsubscribe?.();
234
- listeners.clear();
235
- }
326
+ close: Effect.gen(function* () {
327
+ if (yield* Ref.get(closed)) return;
328
+ yield* Ref.set(closed, true);
329
+ if (consuming !== void 0) yield* Fiber.interrupt(consuming);
330
+ yield* Effect.sync(() => listeners.clear());
331
+ }).pipe(Effect.withSpan("Presence.close"))
236
332
  };
237
- };
333
+ }).pipe(Effect.withSpan("Presence.create"));
238
334
  /** An in-process channel, for tests and single-process demos. */
239
- const loopbackPresenceChannel = () => {
240
- const listeners = /* @__PURE__ */ new Set();
335
+ const loopbackPresenceChannel = () => Effect.gen(function* () {
336
+ const updates = yield* PubSub.unbounded();
241
337
  return {
242
- publish: (update) => {
243
- for (const listener of [...listeners]) try {
244
- listener(update);
245
- } catch {}
246
- },
247
- subscribe: (listener) => {
248
- listeners.add(listener);
249
- return () => listeners.delete(listener);
250
- }
338
+ updates,
339
+ publish: (update) => PubSub.publish(updates, update)
251
340
  };
252
- };
341
+ });
253
342
  const createPresenceHub = () => {
254
343
  const peers = /* @__PURE__ */ new Set();
255
344
  return {
@@ -282,13 +371,17 @@ const decodePresence = (data) => {
282
371
  value: payload ?? null
283
372
  };
284
373
  };
285
- /** A presence channel carried on a socket, alongside exchange frames. */
286
- const socketPresenceChannel = (socket) => ({
287
- publish: (update) => socket.send(JSON.stringify({ [frameType]: update })),
288
- subscribe: (listener) => socket.onMessage((data) => {
374
+ /** A presence channel fed by frames arriving on a socket, sent back over it. */
375
+ const socketPresenceChannel = (socket) => Effect.gen(function* () {
376
+ const updates = yield* PubSub.unbounded();
377
+ yield* Effect.acquireRelease(Effect.sync(() => socket.onMessage((data) => {
289
378
  const update = decodePresence(data);
290
- if (update !== void 0) listener(update);
291
- })
379
+ if (update !== void 0) PubSub.publishUnsafe(updates, update);
380
+ })), (off) => Effect.sync(off));
381
+ return {
382
+ updates,
383
+ publish: (update) => Effect.sync(() => socket.send(JSON.stringify({ [frameType]: update })))
384
+ };
292
385
  });
293
386
  /** Serves presence frames on an accepted socket, fanning them through the hub. */
294
387
  const servePresence = (socket, hub) => {
@@ -518,14 +611,17 @@ const layerSocket = (options) => Layer.effect(Transport, Effect.gen(function* ()
518
611
  //#endregion
519
612
  //#region src/sync.ts
520
613
  const Sequence = Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
614
+ /** Wire and persisted-format versions. A bump must handle the older value explicitly. */
615
+ const PROTOCOL_VERSION = 1;
616
+ const SCHEMA_VERSION = 1;
521
617
  /** A client-authored operation envelope. `message` is the application's encoded Message. */
522
618
  const OperationSchema = Schema.Struct({
523
- protocolVersion: Schema.Literal(1),
524
- schemaVersion: Schema.Literal(1),
525
- documentId: Schema.NonEmptyString,
526
- replicaId: Schema.NonEmptyString,
619
+ protocolVersion: Schema.Literal(PROTOCOL_VERSION),
620
+ schemaVersion: Schema.Literal(SCHEMA_VERSION),
621
+ documentId: DocumentId,
622
+ replicaId: ReplicaId,
527
623
  localSequence: Sequence,
528
- opId: Schema.NonEmptyString,
624
+ opId: OpId,
529
625
  baseCursor: Sequence,
530
626
  message: Schema.Unknown
531
627
  });
@@ -551,11 +647,6 @@ const syncMetrics = {
551
647
  1024
552
648
  ] })
553
649
  };
554
- /** Keeps the storage driver's message visible on the typed failure. */
555
- const storageError = (context, cause) => new StorageError({
556
- message: `${context}: ${cause instanceof Error ? cause.message : String(cause)}`,
557
- cause
558
- });
559
650
  /**
560
651
  * Binds the replicated-state protocol to one application contract.
561
652
  *
@@ -568,10 +659,10 @@ const defineSync = (definition) => {
568
659
  const decodeMessage = Schema.decodeUnknownSync(definition.message, { onExcessProperty: "error" });
569
660
  const encodeMessage = Schema.encodeSync(definition.message);
570
661
  const ReplicaStateSchema = Schema.Struct({
571
- protocolVersion: Schema.Literal(1),
572
- schemaVersion: Schema.Literal(1),
573
- documentId: Schema.NonEmptyString,
574
- replicaId: Schema.NonEmptyString,
662
+ protocolVersion: Schema.Literal(PROTOCOL_VERSION),
663
+ schemaVersion: Schema.Literal(SCHEMA_VERSION),
664
+ documentId: DocumentId,
665
+ replicaId: ReplicaId,
575
666
  revision: Sequence,
576
667
  nextLocalSequence: Sequence,
577
668
  cursor: Sequence,
@@ -585,11 +676,35 @@ const defineSync = (definition) => {
585
676
  });
586
677
  const ExchangeSchema = Schema.Struct({
587
678
  operations: Schema.Array(Schema.Unknown),
588
- rejected: Schema.Array(Schema.NonEmptyString),
589
- acknowledged: Schema.optional(Schema.Array(Schema.NonEmptyString)),
679
+ rejected: Schema.Array(OpId),
680
+ acknowledged: Schema.optional(Schema.Array(OpId)),
590
681
  checkpoint: Schema.optional(CheckpointSchema)
591
682
  });
592
683
  const decodeState = Schema.decodeUnknownSync(ReplicaStateSchema, { onExcessProperty: "error" });
684
+ const VersionProbe = Schema.Struct({
685
+ protocolVersion: Schema.optional(Schema.Number),
686
+ schemaVersion: Schema.optional(Schema.Number)
687
+ });
688
+ /**
689
+ * Tells a version this build does not understand apart from malformed data,
690
+ * so the caller gets an actionable failure and the stored state is preserved.
691
+ */
692
+ const unsupportedVersion = (input) => {
693
+ let found;
694
+ try {
695
+ found = Schema.decodeUnknownSync(VersionProbe)(input);
696
+ } catch {
697
+ return;
698
+ }
699
+ if (found.protocolVersion === PROTOCOL_VERSION && found.schemaVersion === SCHEMA_VERSION) return void 0;
700
+ const protocolVersion = found.protocolVersion ?? null;
701
+ const schemaVersion = found.schemaVersion ?? null;
702
+ return new UnsupportedReplicaVersionError({
703
+ protocolVersion,
704
+ schemaVersion,
705
+ message: `Stored replica uses protocol ${protocolVersion ?? "?"} / schema ${schemaVersion ?? "?"}; this build supports ${PROTOCOL_VERSION}/${SCHEMA_VERSION}`
706
+ });
707
+ };
593
708
  const decodeExchange = (input) => Schema.decodeUnknownSync(ExchangeSchema, { onExcessProperty: "error" })(input);
594
709
  const checkIdentity = (operation) => {
595
710
  if (operation.localSequence < 1 || operation.opId !== `${operation.replicaId}:${operation.localSequence}`) throw new Error("Invalid operation identity");
@@ -628,13 +743,10 @@ const defineSync = (definition) => {
628
743
  const committedFrom = (input, key) => decodeCommittedOperation(input, key).committed;
629
744
  const optimistic = (state) => state.pending.reduce((model, operation) => definition.replay(model, decodeMessage(operation.message)), state.committed);
630
745
  const openReplica = (replicaId, storage) => Effect.gen(function* () {
631
- const saved = yield* Effect.tryPromise({
632
- try: () => storage.load(),
633
- catch: (cause) => storageError("Could not read the replica", cause)
634
- });
746
+ const saved = yield* storage.load();
635
747
  const initial = {
636
- protocolVersion: 1,
637
- schemaVersion: 1,
748
+ protocolVersion: PROTOCOL_VERSION,
749
+ schemaVersion: SCHEMA_VERSION,
638
750
  documentId,
639
751
  replicaId,
640
752
  revision: 0,
@@ -646,7 +758,7 @@ const defineSync = (definition) => {
646
758
  };
647
759
  const state = saved === void 0 ? initial : yield* Effect.try({
648
760
  try: () => decodeState(saved),
649
- catch: (cause) => new InvalidReplicaHistoryError({
761
+ catch: (cause) => unsupportedVersion(saved) ?? new InvalidReplicaHistoryError({
650
762
  message: "Stored replica state is invalid",
651
763
  cause
652
764
  })
@@ -667,22 +779,30 @@ const defineSync = (definition) => {
667
779
  if (operation.replicaId !== replicaId || operation.localSequence >= state.nextLocalSequence || committedIds.has(operation.opId) || pendingIds.has(operation.opId)) return yield* new InvalidOutboxError({ message: "Invalid outbox" });
668
780
  pendingIds.add(operation.opId);
669
781
  }
670
- if (saved === void 0) yield* Effect.tryPromise({
671
- try: () => storage.save(state, null),
672
- catch: (cause) => storageError("Could not save the replica", cause)
673
- });
782
+ if (saved === void 0) yield* storage.save(state, null);
674
783
  const stateRef = yield* SynchronizedRef.make(state);
675
784
  const closed = yield* Ref.make(false);
676
- const persist = (next, current) => Effect.tryPromise({
677
- try: () => storage.save(next, current.revision),
678
- catch: (cause) => storageError("Could not save the replica", cause)
785
+ const lastError = yield* Ref.make(void 0);
786
+ const rejectedOps = yield* Ref.make([]);
787
+ const projection = yield* Ref.make(void 0);
788
+ const shared = Effect.gen(function* () {
789
+ const current = yield* SynchronizedRef.get(stateRef);
790
+ const cached = yield* Ref.get(projection);
791
+ if (cached !== void 0 && cached.state === current) return cached.shared;
792
+ const projected = optimistic(current);
793
+ yield* Ref.set(projection, {
794
+ state: current,
795
+ shared: projected
796
+ });
797
+ return projected;
679
798
  });
799
+ const persist = (next, current) => storage.save(next, current.revision);
680
800
  const submit = (message) => SynchronizedRef.modifyEffect(stateRef, (current) => Effect.gen(function* () {
681
801
  if (yield* Ref.get(closed)) return yield* new ReplicaClosedError({ message: "Replica is closed" });
682
802
  const operation = yield* Effect.try({
683
803
  try: () => operationFrom({
684
- protocolVersion: 1,
685
- schemaVersion: 1,
804
+ protocolVersion: PROTOCOL_VERSION,
805
+ schemaVersion: SCHEMA_VERSION,
686
806
  documentId,
687
807
  replicaId,
688
808
  localSequence: current.nextLocalSequence,
@@ -716,10 +836,13 @@ const defineSync = (definition) => {
716
836
  const sent = yield* SynchronizedRef.get(stateRef);
717
837
  yield* Metric.update(syncMetrics.exchanges, 1);
718
838
  yield* Metric.update(syncMetrics.exchangePending, sent.pending.length);
719
- const response = decodeExchange(yield* transport.exchange(sent.cursor, sent.pending).pipe(Effect.tapError((error) => Effect.logWarning("sync exchange failed", {
720
- documentId,
721
- replicaId,
722
- error: error.message
839
+ const response = decodeExchange(yield* transport.exchange(sent.cursor, sent.pending).pipe(Effect.tapError((error) => Effect.gen(function* () {
840
+ yield* Effect.logWarning("sync exchange failed", {
841
+ documentId,
842
+ replicaId,
843
+ error: error.message
844
+ });
845
+ yield* Ref.set(lastError, error.message);
723
846
  }))));
724
847
  yield* SynchronizedRef.modifyEffect(stateRef, (current) => Effect.gen(function* () {
725
848
  if (yield* Ref.get(closed)) return yield* new ReplicaClosedError({ message: "Replica is closed" });
@@ -786,16 +909,27 @@ const defineSync = (definition) => {
786
909
  yield* persist(next, current);
787
910
  return [void 0, next];
788
911
  }));
912
+ yield* Ref.set(lastError, void 0);
913
+ if (response.rejected.length > 0) yield* Ref.update(rejectedOps, (previous) => [...response.rejected, ...previous].slice(0, 32));
789
914
  }).pipe(Effect.withSpan("Sync.synchronize", { attributes: { documentId } }));
790
915
  return {
791
- shared: Effect.map(SynchronizedRef.get(stateRef), optimistic),
916
+ shared,
792
917
  pending: Effect.map(SynchronizedRef.get(stateRef), (state) => state.pending),
793
918
  cursor: Effect.map(SynchronizedRef.get(stateRef), (state) => state.cursor),
919
+ status: Effect.gen(function* () {
920
+ const state = yield* SynchronizedRef.get(stateRef);
921
+ return {
922
+ pending: state.pending.length,
923
+ cursor: state.cursor,
924
+ lastError: yield* Ref.get(lastError),
925
+ rejected: yield* Ref.get(rejectedOps)
926
+ };
927
+ }),
794
928
  submit,
795
929
  synchronize,
796
930
  close: Effect.gen(function* () {
797
931
  yield* Ref.set(closed, true);
798
- yield* Effect.sync(() => storage.close());
932
+ yield* storage.close;
799
933
  })
800
934
  };
801
935
  }).pipe(Effect.withSpan("Sync.openReplica", { attributes: {
@@ -812,6 +946,6 @@ const defineSync = (definition) => {
812
946
  };
813
947
  };
814
948
  //#endregion
815
- export { CheckpointRegressionError, CommittedOrderError, ForeignRejectionError, InvalidOutboxError, InvalidReplicaHistoryError, ReplicaClosedError, StorageError, Transport, TransportError, WrongReplicaStorageError, createPresence, createPresenceHub, defineSync, indexedDb, layerFromPromise, layerLoopback, layerSocket, loopbackPresenceChannel, lwwRegister, nativeSocket, openLwwClock, servePresence, serveSocket, socketPresenceChannel, syncMetrics, toPromise };
949
+ export { CheckpointRegressionError, CommittedOrderError, DocumentId, ForeignRejectionError, InvalidOutboxError, InvalidReplicaHistoryError, OpId, ReplicaClosedError, ReplicaId, StorageError, Transport, TransportError, UnsupportedClockVersionError, UnsupportedReplicaVersionError, WrongReplicaStorageError, createPresence, createPresenceHub, defineSync, documentId, indexedDb, layerFromPromise, layerLoopback, layerSocket, loopbackPresenceChannel, lwwRegister, nativeSocket, opId, openLwwClock, replicaId, servePresence, serveSocket, socketPresenceChannel, syncMetrics, toPromise };
816
950
 
817
951
  //# sourceMappingURL=index.mjs.map