@syncular/client 0.55.1 → 0.56.1

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.
@@ -181,6 +181,7 @@ export declare class FollowerLink<E = SyncWorkerEvent> {
181
181
  callTimeoutMs?: number;
182
182
  queueLimit?: number;
183
183
  schedule?: FollowerSchedule;
184
+ replayOnHandover?: readonly string[];
184
185
  });
185
186
  get epoch(): number;
186
187
  get maxEpochSeen(): number;
@@ -204,8 +205,9 @@ export declare class FollowerLink<E = SyncWorkerEvent> {
204
205
  /**
205
206
  * The leader we were bound to went away (its lock released). Un-bind so new
206
207
  * calls queue again; re-request an announce so the next leader finds us.
207
- * Calls in flight to the departed leader reject; the winner's announce
208
- * flushes the queued ones.
208
+ * Calls in flight to the departed leader reject, except `replayOnHandover`
209
+ * methods, which queue again; the winner's announce flushes the queued
210
+ * ones.
209
211
  */
210
212
  unbind(): void;
211
213
  /**
@@ -304,6 +306,13 @@ export interface TabCoordinatorConfig<E> {
304
306
  readonly channelFactory?: (name: string) => CrossTabChannel<E>;
305
307
  /** Liveness and handover-queue deadline; defaults to 10 s. */
306
308
  readonly callTimeoutMs?: number;
309
+ /**
310
+ * Methods whose follower call, in flight when the leader changes, runs again
311
+ * on the next leader instead of rejecting with `client.leader_handover`.
312
+ * List only methods whose result does not depend on whether the departed
313
+ * core ran them.
314
+ */
315
+ readonly replayOnHandover?: readonly string[];
307
316
  /**
308
317
  * How long a follower must have been `leader-unreachable` before
309
318
  * `takeOver()` is allowed; defaults to twice `callTimeoutMs`.
package/dist/multi-tab.js CHANGED
@@ -291,6 +291,7 @@ export class FollowerLink {
291
291
  #leaderClientId = '';
292
292
  #nextReqId = 1;
293
293
  #inFlight = new Map();
294
+ #replayOnHandover;
294
295
  #queue = [];
295
296
  #closed = false;
296
297
  #state = {
@@ -312,6 +313,7 @@ export class FollowerLink {
312
313
  options.callTimeoutMs ?? DEFAULT_FOLLOWER_CALL_TIMEOUT_MS;
313
314
  this.#probeAfterMs = Math.max(1, Math.floor(this.#callTimeoutMs / 3));
314
315
  this.#queueLimit = options.queueLimit ?? DEFAULT_FOLLOWER_QUEUE_LIMIT;
316
+ this.#replayOnHandover = new Set(options.replayOnHandover);
315
317
  this.#schedule =
316
318
  options.schedule ??
317
319
  ((callback, delayMs) => {
@@ -420,10 +422,7 @@ export class FollowerLink {
420
422
  const reqId = this.#nextReqId++;
421
423
  // No deadline: a live leader may queue the call behind a long sync round.
422
424
  // The liveness probe, a leader change, or close settles it otherwise.
423
- this.#inFlight.set(reqId, {
424
- resolve: queued.resolve,
425
- reject: queued.reject,
426
- });
425
+ this.#inFlight.set(reqId, queued);
427
426
  this.#channel.postMessage({
428
427
  t: 'req',
429
428
  epoch: this.#epoch,
@@ -448,6 +447,23 @@ export class FollowerLink {
448
447
  for (const inflight of pending)
449
448
  inflight.reject(error);
450
449
  }
450
+ /**
451
+ * The leader changed before it answered. Calls to `replayOnHandover`
452
+ * methods return for replay on the next leader. Every other call rejects
453
+ * with `error`: the follower cannot tell whether the old core applied it.
454
+ */
455
+ #handOverInFlight(error) {
456
+ const pending = [...this.#inFlight.values()];
457
+ this.#inFlight.clear();
458
+ const replay = [];
459
+ for (const inflight of pending) {
460
+ if (this.#replayOnHandover.has(inflight.method))
461
+ replay.push(inflight);
462
+ else
463
+ inflight.reject(error);
464
+ }
465
+ return replay;
466
+ }
451
467
  #dropQueued(queued) {
452
468
  const index = this.#queue.indexOf(queued);
453
469
  if (index >= 0)
@@ -471,9 +487,9 @@ export class FollowerLink {
471
487
  const changed = message.epoch !== this.#epoch ||
472
488
  message.clientId !== this.#leaderClientId;
473
489
  // Calls sent to the previous leader get no answer from this one.
474
- if (changed && this.#epoch >= 0) {
475
- this.#rejectInFlight(new ClientSyncError(LEADER_HANDOVER_CODE, 'the leader changed before it answered the call', true));
476
- }
490
+ const replay = changed && this.#epoch >= 0
491
+ ? this.#handOverInFlight(new ClientSyncError(LEADER_HANDOVER_CODE, 'the leader changed before it answered the call', true))
492
+ : [];
477
493
  this.#epoch = message.epoch;
478
494
  this.#leaderClientId = message.clientId;
479
495
  if (changed)
@@ -486,6 +502,9 @@ export class FollowerLink {
486
502
  this.#armLivenessProbe();
487
503
  this.#resolveBindWaiters();
488
504
  this.#flushQueue();
505
+ for (const call of replay) {
506
+ this.call(call.method, call.args).then(call.resolve, call.reject);
507
+ }
489
508
  return;
490
509
  }
491
510
  if (message.t === 'res') {
@@ -528,17 +547,21 @@ export class FollowerLink {
528
547
  /**
529
548
  * The leader we were bound to went away (its lock released). Un-bind so new
530
549
  * calls queue again; re-request an announce so the next leader finds us.
531
- * Calls in flight to the departed leader reject; the winner's announce
532
- * flushes the queued ones.
550
+ * Calls in flight to the departed leader reject, except `replayOnHandover`
551
+ * methods, which queue again; the winner's announce flushes the queued
552
+ * ones.
533
553
  */
534
554
  unbind() {
535
555
  if (this.#closed)
536
556
  return;
537
- this.#rejectInFlight(new ClientSyncError(LEADER_HANDOVER_CODE, 'the leader released the database before it answered the call', true));
557
+ const replay = this.#handOverInFlight(new ClientSyncError(LEADER_HANDOVER_CODE, 'the leader released the database before it answered the call', true));
538
558
  this.#epoch = -1;
539
559
  this.#leaderClientId = '';
540
560
  this.#setState({ state: 'waiting', reason: 'handover' });
541
561
  this.#armUnboundDeadline();
562
+ for (const call of replay) {
563
+ this.call(call.method, call.args).then(call.resolve, call.reject);
564
+ }
542
565
  this.#probe();
543
566
  }
544
567
  /**
@@ -968,6 +991,9 @@ export async function createTabCoordinator(config) {
968
991
  onStateChange: setState,
969
992
  callTimeoutMs,
970
993
  schedule: clock.schedule,
994
+ ...(config.replayOnHandover !== undefined
995
+ ? { replayOnHandover: config.replayOnHandover }
996
+ : {}),
971
997
  });
972
998
  follower = link;
973
999
  // Granted only when the lock is released: the leader's tab closed, or this
@@ -701,6 +701,9 @@ export async function createSyncClientHandle(config) {
701
701
  name: lockName,
702
702
  version: resolvedConfig.schema.version,
703
703
  lock,
704
+ // A promoted leader starts a fresh core, so the realtime state a follower
705
+ // set on the departed core is gone either way.
706
+ replayOnHandover: ['connectRealtime', 'disconnectRealtime'],
704
707
  ...(resolvedConfig.channelFactory !== undefined
705
708
  ? { channelFactory: resolvedConfig.channelFactory }
706
709
  : {}),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.55.1",
3
+ "version": "0.56.1",
4
4
  "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -105,11 +105,11 @@
105
105
  },
106
106
  "dependencies": {
107
107
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
108
- "@syncular/core": "0.55.1"
108
+ "@syncular/core": "0.56.1"
109
109
  },
110
110
  "devDependencies": {
111
111
  "@electric-sql/pglite": "^0.5.4",
112
- "@syncular/server": "0.55.1",
112
+ "@syncular/server": "0.56.1",
113
113
  "playwright": "1.63.0",
114
114
  "vite": "8.3.4"
115
115
  }
package/src/multi-tab.ts CHANGED
@@ -439,11 +439,6 @@ interface QueuedCall {
439
439
  cancelTimer: (() => void) | undefined;
440
440
  }
441
441
 
442
- interface InFlight {
443
- readonly resolve: (value: unknown) => void;
444
- readonly reject: (error: unknown) => void;
445
- }
446
-
447
442
  /**
448
443
  * Runs on a follower tab. Sends `req`s to the leader and settles them on the
449
444
  * matching `res`; queues calls (bounded, timed) while no leader is bound (the
@@ -474,7 +469,8 @@ export class FollowerLink<E = SyncWorkerEvent> {
474
469
  #maxEpochSeen = -1;
475
470
  #leaderClientId = '';
476
471
  #nextReqId = 1;
477
- readonly #inFlight = new Map<number, InFlight>();
472
+ readonly #inFlight = new Map<number, QueuedCall>();
473
+ readonly #replayOnHandover: ReadonlySet<string>;
478
474
  #queue: QueuedCall[] = [];
479
475
  #closed = false;
480
476
  #state: LeadershipState = {
@@ -496,6 +492,7 @@ export class FollowerLink<E = SyncWorkerEvent> {
496
492
  callTimeoutMs?: number;
497
493
  queueLimit?: number;
498
494
  schedule?: FollowerSchedule;
495
+ replayOnHandover?: readonly string[];
499
496
  }) {
500
497
  this.#channel = options.channel;
501
498
  this.#fromId = options.fromId;
@@ -507,6 +504,7 @@ export class FollowerLink<E = SyncWorkerEvent> {
507
504
  options.callTimeoutMs ?? DEFAULT_FOLLOWER_CALL_TIMEOUT_MS;
508
505
  this.#probeAfterMs = Math.max(1, Math.floor(this.#callTimeoutMs / 3));
509
506
  this.#queueLimit = options.queueLimit ?? DEFAULT_FOLLOWER_QUEUE_LIMIT;
507
+ this.#replayOnHandover = new Set(options.replayOnHandover);
510
508
  this.#schedule =
511
509
  options.schedule ??
512
510
  ((callback, delayMs) => {
@@ -643,10 +641,7 @@ export class FollowerLink<E = SyncWorkerEvent> {
643
641
  const reqId = this.#nextReqId++;
644
642
  // No deadline: a live leader may queue the call behind a long sync round.
645
643
  // The liveness probe, a leader change, or close settles it otherwise.
646
- this.#inFlight.set(reqId, {
647
- resolve: queued.resolve,
648
- reject: queued.reject,
649
- });
644
+ this.#inFlight.set(reqId, queued);
650
645
  this.#channel.postMessage({
651
646
  t: 'req',
652
647
  epoch: this.#epoch,
@@ -681,6 +676,22 @@ export class FollowerLink<E = SyncWorkerEvent> {
681
676
  for (const inflight of pending) inflight.reject(error);
682
677
  }
683
678
 
679
+ /**
680
+ * The leader changed before it answered. Calls to `replayOnHandover`
681
+ * methods return for replay on the next leader. Every other call rejects
682
+ * with `error`: the follower cannot tell whether the old core applied it.
683
+ */
684
+ #handOverInFlight(error: ClientSyncError): QueuedCall[] {
685
+ const pending = [...this.#inFlight.values()];
686
+ this.#inFlight.clear();
687
+ const replay: QueuedCall[] = [];
688
+ for (const inflight of pending) {
689
+ if (this.#replayOnHandover.has(inflight.method)) replay.push(inflight);
690
+ else inflight.reject(error);
691
+ }
692
+ return replay;
693
+ }
694
+
684
695
  #dropQueued(queued: QueuedCall): void {
685
696
  const index = this.#queue.indexOf(queued);
686
697
  if (index >= 0) this.#queue.splice(index, 1);
@@ -703,15 +714,16 @@ export class FollowerLink<E = SyncWorkerEvent> {
703
714
  message.epoch !== this.#epoch ||
704
715
  message.clientId !== this.#leaderClientId;
705
716
  // Calls sent to the previous leader get no answer from this one.
706
- if (changed && this.#epoch >= 0) {
707
- this.#rejectInFlight(
708
- new ClientSyncError(
709
- LEADER_HANDOVER_CODE,
710
- 'the leader changed before it answered the call',
711
- true,
712
- ),
713
- );
714
- }
717
+ const replay =
718
+ changed && this.#epoch >= 0
719
+ ? this.#handOverInFlight(
720
+ new ClientSyncError(
721
+ LEADER_HANDOVER_CODE,
722
+ 'the leader changed before it answered the call',
723
+ true,
724
+ ),
725
+ )
726
+ : [];
715
727
  this.#epoch = message.epoch;
716
728
  this.#leaderClientId = message.clientId;
717
729
  if (changed) this.#onLeaderChange(message.clientId);
@@ -723,6 +735,9 @@ export class FollowerLink<E = SyncWorkerEvent> {
723
735
  this.#armLivenessProbe();
724
736
  this.#resolveBindWaiters();
725
737
  this.#flushQueue();
738
+ for (const call of replay) {
739
+ this.call(call.method, call.args).then(call.resolve, call.reject);
740
+ }
726
741
  return;
727
742
  }
728
743
  if (message.t === 'res') {
@@ -769,12 +784,13 @@ export class FollowerLink<E = SyncWorkerEvent> {
769
784
  /**
770
785
  * The leader we were bound to went away (its lock released). Un-bind so new
771
786
  * calls queue again; re-request an announce so the next leader finds us.
772
- * Calls in flight to the departed leader reject; the winner's announce
773
- * flushes the queued ones.
787
+ * Calls in flight to the departed leader reject, except `replayOnHandover`
788
+ * methods, which queue again; the winner's announce flushes the queued
789
+ * ones.
774
790
  */
775
791
  unbind(): void {
776
792
  if (this.#closed) return;
777
- this.#rejectInFlight(
793
+ const replay = this.#handOverInFlight(
778
794
  new ClientSyncError(
779
795
  LEADER_HANDOVER_CODE,
780
796
  'the leader released the database before it answered the call',
@@ -785,6 +801,9 @@ export class FollowerLink<E = SyncWorkerEvent> {
785
801
  this.#leaderClientId = '';
786
802
  this.#setState({ state: 'waiting', reason: 'handover' });
787
803
  this.#armUnboundDeadline();
804
+ for (const call of replay) {
805
+ this.call(call.method, call.args).then(call.resolve, call.reject);
806
+ }
788
807
  this.#probe();
789
808
  }
790
809
 
@@ -1054,6 +1073,13 @@ export interface TabCoordinatorConfig<E> {
1054
1073
  readonly channelFactory?: (name: string) => CrossTabChannel<E>;
1055
1074
  /** Liveness and handover-queue deadline; defaults to 10 s. */
1056
1075
  readonly callTimeoutMs?: number;
1076
+ /**
1077
+ * Methods whose follower call, in flight when the leader changes, runs again
1078
+ * on the next leader instead of rejecting with `client.leader_handover`.
1079
+ * List only methods whose result does not depend on whether the departed
1080
+ * core ran them.
1081
+ */
1082
+ readonly replayOnHandover?: readonly string[];
1057
1083
  /**
1058
1084
  * How long a follower must have been `leader-unreachable` before
1059
1085
  * `takeOver()` is allowed; defaults to twice `callTimeoutMs`.
@@ -1407,6 +1433,9 @@ export async function createTabCoordinator<E>(
1407
1433
  onStateChange: setState,
1408
1434
  callTimeoutMs,
1409
1435
  schedule: clock.schedule,
1436
+ ...(config.replayOnHandover !== undefined
1437
+ ? { replayOnHandover: config.replayOnHandover }
1438
+ : {}),
1410
1439
  });
1411
1440
  follower = link;
1412
1441
  // Granted only when the lock is released: the leader's tab closed, or this
@@ -1125,6 +1125,9 @@ export async function createSyncClientHandle(
1125
1125
  name: lockName,
1126
1126
  version: resolvedConfig.schema.version,
1127
1127
  lock,
1128
+ // A promoted leader starts a fresh core, so the realtime state a follower
1129
+ // set on the departed core is gone either way.
1130
+ replayOnHandover: ['connectRealtime', 'disconnectRealtime'],
1128
1131
  ...(resolvedConfig.channelFactory !== undefined
1129
1132
  ? { channelFactory: resolvedConfig.channelFactory }
1130
1133
  : {}),