@syncular/client 0.61.0 → 0.62.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.
@@ -278,26 +278,33 @@ export declare class FollowerLink<E = SyncWorkerEvent> {
278
278
  /** Whether a leader is currently bound (an announce has been heard). */
279
279
  get bound(): boolean;
280
280
  /**
281
- * Resolve once the link is bound to a leader (the first `announce` arrived),
282
- * or reject if `timeoutMs` elapses first. A caller awaits this before
283
- * treating the follower as ready: until an announce is processed the link's
281
+ * Resolve once the link is bound to a leader (the first `announce` arrived)
282
+ * or hands over to this tab's own core, and reject once it is blocked
283
+ * because no leader announced within the call timeout. A caller awaits this
284
+ * before treating the follower as ready: until an announce is processed the link's
284
285
  * epoch is -1, so any fanned-out `event` in that window is dropped (an
285
286
  * unbound follower cannot match the leader's epoch). Awaiting binding closes
286
287
  * that gap — a just-opened follower tab never misses an invalidation emitted
287
288
  * between its `hello` and the leader's `announce`. Resolves synchronously
288
289
  * when already bound.
289
290
  */
290
- waitUntilBound(timeoutMs?: number): Promise<void>;
291
+ waitUntilBound(): Promise<void>;
291
292
  /** Forward one logical API call to the leader (queued if unbound). */
292
293
  call(method: string, args: readonly unknown[]): Promise<unknown>;
293
294
  /**
294
- * The leader we were bound to went away (its lock released). Un-bind so new
295
- * calls queue again; re-request an announce so the next leader finds us.
296
- * Calls in flight to the departed leader reject, except `replayOnHandover`
297
- * methods, which queue again; the winner's announce flushes the queued
298
- * ones.
295
+ * The leader we were bound to released its lock to this tab, which now
296
+ * starts its own core. Un-bind so new calls queue for that core. Calls in
297
+ * flight to the departed leader reject, except `replayOnHandover` methods,
298
+ * which queue again. No follower deadline runs while the core starts:
299
+ * `handOver` settles the queued calls, or `awaitLeader` after a failed
300
+ * start.
299
301
  */
300
302
  unbind(): void;
303
+ /**
304
+ * This tab's own core failed to start: wait for another tab's leader under
305
+ * the follower deadlines again, and ask it to announce.
306
+ */
307
+ awaitLeader(): void;
301
308
  /**
302
309
  * This tab won the lock and runs its own core: calls queued for the next
303
310
  * leader run on `invoke` instead of failing, then the link closes.
package/dist/multi-tab.js CHANGED
@@ -311,8 +311,10 @@ export class FollowerLink {
311
311
  };
312
312
  #cancelProbe;
313
313
  #cancelBlocked;
314
- /** Resolvers waiting for the first `announce` to bind a leader. */
314
+ /** Waiting for the first `announce` to bind a leader. */
315
315
  #bindWaiters = [];
316
+ /** This tab won the lock and starts its own core: no follower deadline runs. */
317
+ #startingCore = false;
316
318
  constructor(options) {
317
319
  this.#channel = options.channel;
318
320
  this.#fromId = options.fromId;
@@ -354,46 +356,34 @@ export class FollowerLink {
354
356
  return this.#epoch >= 0;
355
357
  }
356
358
  /**
357
- * Resolve once the link is bound to a leader (the first `announce` arrived),
358
- * or reject if `timeoutMs` elapses first. A caller awaits this before
359
- * treating the follower as ready: until an announce is processed the link's
359
+ * Resolve once the link is bound to a leader (the first `announce` arrived)
360
+ * or hands over to this tab's own core, and reject once it is blocked
361
+ * because no leader announced within the call timeout. A caller awaits this
362
+ * before treating the follower as ready: until an announce is processed the link's
360
363
  * epoch is -1, so any fanned-out `event` in that window is dropped (an
361
364
  * unbound follower cannot match the leader's epoch). Awaiting binding closes
362
365
  * that gap — a just-opened follower tab never misses an invalidation emitted
363
366
  * between its `hello` and the leader's `announce`. Resolves synchronously
364
367
  * when already bound.
365
368
  */
366
- waitUntilBound(timeoutMs = this.#callTimeoutMs) {
369
+ waitUntilBound() {
367
370
  if (this.#epoch >= 0)
368
371
  return Promise.resolve();
369
372
  if (this.#closed) {
370
373
  return Promise.reject(new ClientSyncError(WORKER_FAILED_CODE, 'the follower link is closed'));
371
374
  }
375
+ if (this.#state.state === 'blocked') {
376
+ return Promise.reject(this.#blockedError());
377
+ }
372
378
  return new Promise((resolve, reject) => {
373
- const cancelTimer = this.#schedule(() => {
374
- this.#dropBindWaiter(settle);
375
- this.#setBlocked();
376
- reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'no leader announced within the follower bind timeout', true));
377
- }, timeoutMs);
378
- const settle = () => {
379
- cancelTimer();
380
- resolve();
381
- };
382
- this.#bindWaiters.push(settle);
379
+ this.#bindWaiters.push({ resolve, reject });
383
380
  });
384
381
  }
385
- #dropBindWaiter(waiter) {
386
- const index = this.#bindWaiters.indexOf(waiter);
387
- if (index >= 0)
388
- this.#bindWaiters.splice(index, 1);
389
- }
390
382
  #resolveBindWaiters() {
391
- if (this.#bindWaiters.length === 0)
392
- return;
393
383
  const waiters = this.#bindWaiters;
394
384
  this.#bindWaiters = [];
395
- for (const settle of waiters)
396
- settle();
385
+ for (const waiter of waiters)
386
+ waiter.resolve();
397
387
  }
398
388
  /** Forward one logical API call to the leader (queued if unbound). */
399
389
  call(method, args) {
@@ -412,23 +402,28 @@ export class FollowerLink {
412
402
  cancelTimer: undefined,
413
403
  };
414
404
  if (this.#epoch < 0) {
415
- // No leader bound yet — queue with a deadline so we never hang.
405
+ // No leader bound yet: queue with a deadline so we never hang. A core
406
+ // this tab starts settles the call itself (`handOver`).
416
407
  if (this.#queue.length >= this.#queueLimit) {
417
408
  this.#setBlocked();
418
409
  reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'follower call queue overflow while awaiting a leader', true));
419
410
  return;
420
411
  }
421
- queued.cancelTimer = this.#schedule(() => {
422
- this.#dropQueued(queued);
423
- this.#setBlocked();
424
- reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'no leader answered within the follower call timeout', true));
425
- }, this.#callTimeoutMs);
412
+ if (!this.#startingCore)
413
+ this.#armQueuedDeadline(queued);
426
414
  this.#queue.push(queued);
427
415
  return;
428
416
  }
429
417
  this.#send(queued);
430
418
  });
431
419
  }
420
+ #armQueuedDeadline(queued) {
421
+ queued.cancelTimer = this.#schedule(() => {
422
+ this.#dropQueued(queued);
423
+ this.#setBlocked();
424
+ queued.reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'no leader answered within the follower call timeout', true));
425
+ }, this.#callTimeoutMs);
426
+ }
432
427
  #send(queued) {
433
428
  const reqId = this.#nextReqId++;
434
429
  // No deadline: a live leader may queue the call behind a long sync round.
@@ -510,6 +505,7 @@ export class FollowerLink {
510
505
  : [];
511
506
  this.#epoch = message.epoch;
512
507
  this.#leaderClientId = message.clientId;
508
+ this.#startingCore = false;
513
509
  if (changed)
514
510
  this.#onLeaderChange(message.clientId);
515
511
  this.#setState({
@@ -564,11 +560,12 @@ export class FollowerLink {
564
560
  }
565
561
  }
566
562
  /**
567
- * The leader we were bound to went away (its lock released). Un-bind so new
568
- * calls queue again; re-request an announce so the next leader finds us.
569
- * Calls in flight to the departed leader reject, except `replayOnHandover`
570
- * methods, which queue again; the winner's announce flushes the queued
571
- * ones.
563
+ * The leader we were bound to released its lock to this tab, which now
564
+ * starts its own core. Un-bind so new calls queue for that core. Calls in
565
+ * flight to the departed leader reject, except `replayOnHandover` methods,
566
+ * which queue again. No follower deadline runs while the core starts:
567
+ * `handOver` settles the queued calls, or `awaitLeader` after a failed
568
+ * start.
572
569
  */
573
570
  unbind() {
574
571
  if (this.#closed)
@@ -576,13 +573,31 @@ export class FollowerLink {
576
573
  const replay = this.#handOverInFlight(new ClientSyncError(LEADER_HANDOVER_CODE, 'the leader released the database before it answered the call', true));
577
574
  this.#epoch = -1;
578
575
  this.#leaderClientId = '';
576
+ this.#startingCore = true;
577
+ this.#clearReachabilityTimers();
578
+ for (const queued of this.#queue) {
579
+ queued.cancelTimer?.();
580
+ queued.cancelTimer = undefined;
581
+ }
579
582
  this.#setState({ state: 'waiting', reason: 'handover' });
580
- this.#armUnboundDeadline();
581
583
  for (const call of replay) {
582
584
  this.call(call.method, call.args).then(call.resolve, call.reject);
583
585
  }
584
586
  this.#probe();
585
587
  }
588
+ /**
589
+ * This tab's own core failed to start: wait for another tab's leader under
590
+ * the follower deadlines again, and ask it to announce.
591
+ */
592
+ awaitLeader() {
593
+ if (this.#closed || !this.#startingCore)
594
+ return;
595
+ this.#startingCore = false;
596
+ for (const queued of this.#queue)
597
+ this.#armQueuedDeadline(queued);
598
+ this.#armUnboundDeadline();
599
+ this.#probe();
600
+ }
586
601
  /**
587
602
  * This tab won the lock and runs its own core: calls queued for the next
588
603
  * leader run on `invoke` instead of failing, then the link closes.
@@ -609,8 +624,8 @@ export class FollowerLink {
609
624
  queued.reject(closedError);
610
625
  }
611
626
  this.#queue = [];
612
- // Bind waiters carry their own timeout timers; resolving them here lets an
613
- // awaiting boot path settle promptly instead of hanging until that timeout.
627
+ // A boot path waiting for a leader settles: `handOver` closes the link
628
+ // once this tab's own core runs.
614
629
  this.#resolveBindWaiters();
615
630
  this.#channel.close();
616
631
  }
@@ -687,7 +702,12 @@ export class FollowerLink {
687
702
  code: FOLLOWER_TIMEOUT_CODE,
688
703
  retryable: true,
689
704
  });
690
- this.#rejectInFlight(this.#blockedError());
705
+ const error = this.#blockedError();
706
+ this.#rejectInFlight(error);
707
+ const waiters = this.#bindWaiters;
708
+ this.#bindWaiters = [];
709
+ for (const waiter of waiters)
710
+ waiter.reject(error);
691
711
  const reprobe = () => {
692
712
  this.#cancelProbe = this.#schedule(() => {
693
713
  reprobe();
@@ -848,6 +868,7 @@ export async function createTabCoordinator(config) {
848
868
  // Closed while the core was starting, or another tab took the lock: a
849
869
  // follower link, if any, binds to that tab's announcement.
850
870
  current = false;
871
+ follower?.awaitLeader();
851
872
  await leader.close();
852
873
  await lease.release();
853
874
  return;
@@ -1039,6 +1060,7 @@ export async function createTabCoordinator(config) {
1039
1060
  // time (a changed worker bundle, an unreadable database) would
1040
1061
  // otherwise take and drop the lock in a loop while this tab is alone.
1041
1062
  await promoted.release();
1063
+ link.awaitLeader();
1042
1064
  failedStarts += 1;
1043
1065
  const retrying = failedStarts < 3 && !closed;
1044
1066
  setState({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.61.0",
3
+ "version": "0.62.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",
@@ -113,11 +113,11 @@
113
113
  },
114
114
  "dependencies": {
115
115
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
116
- "@syncular/core": "0.61.0"
116
+ "@syncular/core": "0.62.1"
117
117
  },
118
118
  "devDependencies": {
119
119
  "@electric-sql/pglite": "^0.5.4",
120
- "@syncular/server": "0.61.0",
120
+ "@syncular/server": "0.62.1",
121
121
  "playwright": "1.63.0",
122
122
  "vite": "8.3.4"
123
123
  }
package/src/multi-tab.ts CHANGED
@@ -506,8 +506,13 @@ export class FollowerLink<E = SyncWorkerEvent> {
506
506
  };
507
507
  #cancelProbe: (() => void) | undefined;
508
508
  #cancelBlocked: (() => void) | undefined;
509
- /** Resolvers waiting for the first `announce` to bind a leader. */
510
- #bindWaiters: Array<() => void> = [];
509
+ /** Waiting for the first `announce` to bind a leader. */
510
+ #bindWaiters: Array<{
511
+ resolve(): void;
512
+ reject(error: ClientSyncError): void;
513
+ }> = [];
514
+ /** This tab won the lock and starts its own core: no follower deadline runs. */
515
+ #startingCore = false;
511
516
 
512
517
  constructor(options: {
513
518
  channel: CrossTabChannel<E>;
@@ -567,52 +572,35 @@ export class FollowerLink<E = SyncWorkerEvent> {
567
572
  }
568
573
 
569
574
  /**
570
- * Resolve once the link is bound to a leader (the first `announce` arrived),
571
- * or reject if `timeoutMs` elapses first. A caller awaits this before
572
- * treating the follower as ready: until an announce is processed the link's
575
+ * Resolve once the link is bound to a leader (the first `announce` arrived)
576
+ * or hands over to this tab's own core, and reject once it is blocked
577
+ * because no leader announced within the call timeout. A caller awaits this
578
+ * before treating the follower as ready: until an announce is processed the link's
573
579
  * epoch is -1, so any fanned-out `event` in that window is dropped (an
574
580
  * unbound follower cannot match the leader's epoch). Awaiting binding closes
575
581
  * that gap — a just-opened follower tab never misses an invalidation emitted
576
582
  * between its `hello` and the leader's `announce`. Resolves synchronously
577
583
  * when already bound.
578
584
  */
579
- waitUntilBound(timeoutMs = this.#callTimeoutMs): Promise<void> {
585
+ waitUntilBound(): Promise<void> {
580
586
  if (this.#epoch >= 0) return Promise.resolve();
581
587
  if (this.#closed) {
582
588
  return Promise.reject(
583
589
  new ClientSyncError(WORKER_FAILED_CODE, 'the follower link is closed'),
584
590
  );
585
591
  }
592
+ if (this.#state.state === 'blocked') {
593
+ return Promise.reject(this.#blockedError());
594
+ }
586
595
  return new Promise((resolve, reject) => {
587
- const cancelTimer = this.#schedule(() => {
588
- this.#dropBindWaiter(settle);
589
- this.#setBlocked();
590
- reject(
591
- new ClientSyncError(
592
- FOLLOWER_TIMEOUT_CODE,
593
- 'no leader announced within the follower bind timeout',
594
- true,
595
- ),
596
- );
597
- }, timeoutMs);
598
- const settle = (): void => {
599
- cancelTimer();
600
- resolve();
601
- };
602
- this.#bindWaiters.push(settle);
596
+ this.#bindWaiters.push({ resolve, reject });
603
597
  });
604
598
  }
605
599
 
606
- #dropBindWaiter(waiter: () => void): void {
607
- const index = this.#bindWaiters.indexOf(waiter);
608
- if (index >= 0) this.#bindWaiters.splice(index, 1);
609
- }
610
-
611
600
  #resolveBindWaiters(): void {
612
- if (this.#bindWaiters.length === 0) return;
613
601
  const waiters = this.#bindWaiters;
614
602
  this.#bindWaiters = [];
615
- for (const settle of waiters) settle();
603
+ for (const waiter of waiters) waiter.resolve();
616
604
  }
617
605
 
618
606
  /** Forward one logical API call to the leader (queued if unbound). */
@@ -634,7 +622,8 @@ export class FollowerLink<E = SyncWorkerEvent> {
634
622
  cancelTimer: undefined,
635
623
  };
636
624
  if (this.#epoch < 0) {
637
- // No leader bound yet — queue with a deadline so we never hang.
625
+ // No leader bound yet: queue with a deadline so we never hang. A core
626
+ // this tab starts settles the call itself (`handOver`).
638
627
  if (this.#queue.length >= this.#queueLimit) {
639
628
  this.#setBlocked();
640
629
  reject(
@@ -646,17 +635,7 @@ export class FollowerLink<E = SyncWorkerEvent> {
646
635
  );
647
636
  return;
648
637
  }
649
- queued.cancelTimer = this.#schedule(() => {
650
- this.#dropQueued(queued);
651
- this.#setBlocked();
652
- reject(
653
- new ClientSyncError(
654
- FOLLOWER_TIMEOUT_CODE,
655
- 'no leader answered within the follower call timeout',
656
- true,
657
- ),
658
- );
659
- }, this.#callTimeoutMs);
638
+ if (!this.#startingCore) this.#armQueuedDeadline(queued);
660
639
  this.#queue.push(queued);
661
640
  return;
662
641
  }
@@ -664,6 +643,20 @@ export class FollowerLink<E = SyncWorkerEvent> {
664
643
  });
665
644
  }
666
645
 
646
+ #armQueuedDeadline(queued: QueuedCall): void {
647
+ queued.cancelTimer = this.#schedule(() => {
648
+ this.#dropQueued(queued);
649
+ this.#setBlocked();
650
+ queued.reject(
651
+ new ClientSyncError(
652
+ FOLLOWER_TIMEOUT_CODE,
653
+ 'no leader answered within the follower call timeout',
654
+ true,
655
+ ),
656
+ );
657
+ }, this.#callTimeoutMs);
658
+ }
659
+
667
660
  #send(queued: QueuedCall): void {
668
661
  const reqId = this.#nextReqId++;
669
662
  // No deadline: a live leader may queue the call behind a long sync round.
@@ -760,6 +753,7 @@ export class FollowerLink<E = SyncWorkerEvent> {
760
753
  : [];
761
754
  this.#epoch = message.epoch;
762
755
  this.#leaderClientId = message.clientId;
756
+ this.#startingCore = false;
763
757
  if (changed) this.#onLeaderChange(message.clientId);
764
758
  this.#setState({
765
759
  state: 'follower',
@@ -817,11 +811,12 @@ export class FollowerLink<E = SyncWorkerEvent> {
817
811
  }
818
812
 
819
813
  /**
820
- * The leader we were bound to went away (its lock released). Un-bind so new
821
- * calls queue again; re-request an announce so the next leader finds us.
822
- * Calls in flight to the departed leader reject, except `replayOnHandover`
823
- * methods, which queue again; the winner's announce flushes the queued
824
- * ones.
814
+ * The leader we were bound to released its lock to this tab, which now
815
+ * starts its own core. Un-bind so new calls queue for that core. Calls in
816
+ * flight to the departed leader reject, except `replayOnHandover` methods,
817
+ * which queue again. No follower deadline runs while the core starts:
818
+ * `handOver` settles the queued calls, or `awaitLeader` after a failed
819
+ * start.
825
820
  */
826
821
  unbind(): void {
827
822
  if (this.#closed) return;
@@ -834,14 +829,31 @@ export class FollowerLink<E = SyncWorkerEvent> {
834
829
  );
835
830
  this.#epoch = -1;
836
831
  this.#leaderClientId = '';
832
+ this.#startingCore = true;
833
+ this.#clearReachabilityTimers();
834
+ for (const queued of this.#queue) {
835
+ queued.cancelTimer?.();
836
+ queued.cancelTimer = undefined;
837
+ }
837
838
  this.#setState({ state: 'waiting', reason: 'handover' });
838
- this.#armUnboundDeadline();
839
839
  for (const call of replay) {
840
840
  this.call(call.method, call.args).then(call.resolve, call.reject);
841
841
  }
842
842
  this.#probe();
843
843
  }
844
844
 
845
+ /**
846
+ * This tab's own core failed to start: wait for another tab's leader under
847
+ * the follower deadlines again, and ask it to announce.
848
+ */
849
+ awaitLeader(): void {
850
+ if (this.#closed || !this.#startingCore) return;
851
+ this.#startingCore = false;
852
+ for (const queued of this.#queue) this.#armQueuedDeadline(queued);
853
+ this.#armUnboundDeadline();
854
+ this.#probe();
855
+ }
856
+
845
857
  /**
846
858
  * This tab won the lock and runs its own core: calls queued for the next
847
859
  * leader run on `invoke` instead of failing, then the link closes.
@@ -873,8 +885,8 @@ export class FollowerLink<E = SyncWorkerEvent> {
873
885
  queued.reject(closedError);
874
886
  }
875
887
  this.#queue = [];
876
- // Bind waiters carry their own timeout timers; resolving them here lets an
877
- // awaiting boot path settle promptly instead of hanging until that timeout.
888
+ // A boot path waiting for a leader settles: `handOver` closes the link
889
+ // once this tab's own core runs.
878
890
  this.#resolveBindWaiters();
879
891
  this.#channel.close();
880
892
  }
@@ -956,7 +968,11 @@ export class FollowerLink<E = SyncWorkerEvent> {
956
968
  code: FOLLOWER_TIMEOUT_CODE,
957
969
  retryable: true,
958
970
  });
959
- this.#rejectInFlight(this.#blockedError());
971
+ const error = this.#blockedError();
972
+ this.#rejectInFlight(error);
973
+ const waiters = this.#bindWaiters;
974
+ this.#bindWaiters = [];
975
+ for (const waiter of waiters) waiter.reject(error);
960
976
  const reprobe = (): void => {
961
977
  this.#cancelProbe = this.#schedule(() => {
962
978
  reprobe();
@@ -1281,6 +1297,7 @@ export async function createTabCoordinator<E>(
1281
1297
  // Closed while the core was starting, or another tab took the lock: a
1282
1298
  // follower link, if any, binds to that tab's announcement.
1283
1299
  current = false;
1300
+ follower?.awaitLeader();
1284
1301
  await leader.close();
1285
1302
  await lease.release();
1286
1303
  return;
@@ -1496,6 +1513,7 @@ export async function createTabCoordinator<E>(
1496
1513
  // time (a changed worker bundle, an unreadable database) would
1497
1514
  // otherwise take and drop the lock in a loop while this tab is alone.
1498
1515
  await promoted.release();
1516
+ link.awaitLeader();
1499
1517
  failedStarts += 1;
1500
1518
  const retrying = failedStarts < 3 && !closed;
1501
1519
  setState({