@syncular/client 0.65.0 → 0.65.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.
@@ -76,9 +76,9 @@ export declare function documentLifecycleSignal(options?: DocumentLifecycleSigna
76
76
  * Supported host policy for Syncular's explicit realtime transport. It owns
77
77
  * exactly one connect attempt, runs an explicit catch-up round before claiming
78
78
  * connected, retries transient loss with bounded exponential jitter, and
79
- * suspends across offline, background, or protected-preflight state. A host
80
- * `online` report also drives `syncUntilIdle` when realtime is unsupported
81
- * or disabled.
79
+ * suspends across offline, background, or protected-preflight state. Each
80
+ * failed attempt, each host `online` report, and each foreground return
81
+ * while no attempt starts at once drives one HTTP round (§1.8).
82
82
  */
83
83
  export declare class RealtimeSupervisor {
84
84
  #private;
@@ -104,9 +104,9 @@ export function documentLifecycleSignal(options = {}) {
104
104
  * Supported host policy for Syncular's explicit realtime transport. It owns
105
105
  * exactly one connect attempt, runs an explicit catch-up round before claiming
106
106
  * connected, retries transient loss with bounded exponential jitter, and
107
- * suspends across offline, background, or protected-preflight state. A host
108
- * `online` report also drives `syncUntilIdle` when realtime is unsupported
109
- * or disabled.
107
+ * suspends across offline, background, or protected-preflight state. Each
108
+ * failed attempt, each host `online` report, and each foreground return
109
+ * while no attempt starts at once drives one HTTP round (§1.8).
110
110
  */
111
111
  export class RealtimeSupervisor {
112
112
  #client;
@@ -160,18 +160,21 @@ export class RealtimeSupervisor {
160
160
  return;
161
161
  this.#started = true;
162
162
  this.#unsubscribeDiagnostics = this.#client.onDiagnostics((snapshot) => this.#observeDiagnostics(snapshot));
163
- this.#unsubscribeConnectivity = this.#connectivity?.subscribe(() => {
164
- // §1.8: the host's connectivity signal re-arms the drive a failed
165
- // round left behind. The drive does not wait for the socket, so a
166
- // socket that cannot connect does not hold back an HTTP round.
167
- if (this.#connectivity?.current() === 'online' && !this.#hostBlock()) {
168
- void Promise.resolve()
169
- .then(() => this.#client.syncUntilIdle())
170
- .catch(() => undefined);
171
- }
163
+ this.#unsubscribeConnectivity = this.#connectivity?.subscribe((state) => {
164
+ if (state === 'online')
165
+ this.#drive();
172
166
  this.#reconcileHostState();
173
167
  });
174
- this.#unsubscribeLifecycle = this.#lifecycle?.subscribe(() => this.#reconcileHostState());
168
+ this.#unsubscribeLifecycle = this.#lifecycle?.subscribe((state) => {
169
+ this.#reconcileHostState();
170
+ // An immediate attempt brings its own round; a pending retry or an
171
+ // absent socket does not.
172
+ const phase = this.#snapshot.phase;
173
+ if (state === 'active' &&
174
+ (phase === 'retrying' || phase === 'unsupported')) {
175
+ this.#drive();
176
+ }
177
+ });
175
178
  this.#unsubscribeProtection = this.#protection?.subscribe(() => this.#reconcileHostState());
176
179
  this.#reconcileHostState();
177
180
  const generation = this.#generation;
@@ -181,21 +184,12 @@ export class RealtimeSupervisor {
181
184
  if (this.#stopped)
182
185
  return;
183
186
  this.#stopped = true;
184
- this.#generation += 1;
185
- const disconnect = this.#connected || this.#transportConnected || this.#connecting;
186
- this.#connected = false;
187
- this.#transportConnected = false;
188
- this.#connecting = false;
189
- this.#attempt = 0;
190
- this.#clearRetry();
187
+ this.#suspend('stopped');
191
188
  this.#unsubscribeDiagnostics?.();
192
189
  this.#unsubscribeConnectivity?.();
193
190
  this.#unsubscribeLifecycle?.();
194
191
  this.#unsubscribeProtection?.();
195
- this.#publish({ phase: 'stopped', attempt: 0 });
196
192
  this.#listeners.clear();
197
- if (disconnect)
198
- this.#disconnect();
199
193
  }
200
194
  async #initialize(generation) {
201
195
  let snapshot;
@@ -230,6 +224,18 @@ export class RealtimeSupervisor {
230
224
  }
231
225
  return undefined;
232
226
  }
227
+ /**
228
+ * §1.8: one HTTP round that re-arms the drive a refused fetch left behind.
229
+ * It does not wait for the socket, so a socket that cannot connect does not
230
+ * hold back the round.
231
+ */
232
+ #drive() {
233
+ if (this.#hostBlock())
234
+ return;
235
+ void Promise.resolve()
236
+ .then(() => this.#client.syncUntilIdle())
237
+ .catch(() => undefined);
238
+ }
233
239
  #canConnect() {
234
240
  return (this.#initialized &&
235
241
  !this.#stopped &&
@@ -256,14 +262,26 @@ export class RealtimeSupervisor {
256
262
  this.#cancelRetry?.();
257
263
  this.#cancelRetry = undefined;
258
264
  }
259
- #schedule(delayMs) {
260
- if (!this.#canConnect() ||
261
- this.#connected ||
262
- this.#connecting ||
263
- this.#cancelRetry) {
265
+ /** A retry counts one attempt and backs off with bounded jitter. */
266
+ #schedule(retry) {
267
+ if (!this.#canConnect())
268
+ return this.#reconcileHostState();
269
+ // Count an attempt only when this call actually schedules one. Repeated
270
+ // 'disconnected' diagnostics beside a pending retry keep the backoff and
271
+ // the worker-mode reconnect nudge intact.
272
+ if (this.#connected || this.#connecting || this.#cancelRetry)
264
273
  return;
274
+ let delayMs = 0;
275
+ if (retry) {
276
+ const exponential = Math.min(this.#maximumDelayMs, this.#initialDelayMs * 2 ** this.#attempt);
277
+ const random = this.#random();
278
+ const boundedRandom = Number.isFinite(random)
279
+ ? Math.max(0, Math.min(1, random))
280
+ : 0;
281
+ delayMs = Math.min(this.#maximumDelayMs, exponential + Math.floor(exponential * 0.25 * boundedRandom));
282
+ this.#attempt = Math.min(32, this.#attempt + 1);
265
283
  }
266
- this.#publish(delayMs > 0
284
+ this.#publish(retry
267
285
  ? { phase: 'retrying', attempt: this.#attempt, retryDelayMs: delayMs }
268
286
  : { phase: 'connecting', attempt: this.#attempt });
269
287
  this.#cancelRetry = this.#scheduleTimer(() => {
@@ -271,32 +289,6 @@ export class RealtimeSupervisor {
271
289
  void this.#connect();
272
290
  }, delayMs);
273
291
  }
274
- #retryDelay() {
275
- const exponential = Math.min(this.#maximumDelayMs, this.#initialDelayMs * 2 ** this.#attempt);
276
- const random = this.#random();
277
- const boundedRandom = Number.isFinite(random)
278
- ? Math.max(0, Math.min(1, random))
279
- : 0;
280
- const jitter = Math.floor(exponential * 0.25 * boundedRandom);
281
- return Math.min(this.#maximumDelayMs, exponential + jitter);
282
- }
283
- #scheduleRetry() {
284
- if (!this.#canConnect()) {
285
- this.#reconcileHostState();
286
- return;
287
- }
288
- // Count an attempt only when this call actually schedules one. Repeated
289
- // 'disconnected' diagnostics beside a pending retry keep the backoff and
290
- // the worker-mode reconnect nudge intact.
291
- if (this.#connected ||
292
- this.#connecting ||
293
- this.#cancelRetry !== undefined) {
294
- return;
295
- }
296
- const delay = this.#retryDelay();
297
- this.#attempt = Math.min(32, this.#attempt + 1);
298
- this.#schedule(delay);
299
- }
300
292
  /**
301
293
  * A superseded attempt observed a generation bump mid-flight. Whenever a
302
294
  * newer generation is mid-connect or holds the transport, that generation
@@ -350,8 +342,10 @@ export class RealtimeSupervisor {
350
342
  if (generation === this.#generation)
351
343
  this.#connecting = false;
352
344
  }
353
- if (failed && generation === this.#generation)
354
- this.#scheduleRetry();
345
+ if (failed && generation === this.#generation) {
346
+ this.#schedule(true);
347
+ this.#drive();
348
+ }
355
349
  }
356
350
  async #catchUpConnectedTransport(generation) {
357
351
  await this.#client.syncUntilIdle();
@@ -395,7 +389,7 @@ export class RealtimeSupervisor {
395
389
  this.#connecting = false;
396
390
  }
397
391
  if (failed && generation === this.#generation)
398
- this.#scheduleRetry();
392
+ this.#schedule(true);
399
393
  }
400
394
  #observeDiagnostics(snapshot, initial = false) {
401
395
  if (this.#stopped)
@@ -403,16 +397,8 @@ export class RealtimeSupervisor {
403
397
  this.#diagnosticSecurity = snapshot.securityLifecycle;
404
398
  if (snapshot.host.realtime === 'unsupported' ||
405
399
  snapshot.host.realtime === 'disabled') {
406
- const disconnect = this.#connected || this.#transportConnected || this.#connecting;
407
400
  this.#realtimeSupported = false;
408
- this.#generation += 1;
409
- this.#connected = false;
410
- this.#transportConnected = false;
411
- this.#attempt = 0;
412
- this.#clearRetry();
413
- this.#publish({ phase: 'unsupported', attempt: 0 });
414
- if (disconnect)
415
- this.#disconnect();
401
+ this.#suspend('unsupported');
416
402
  return;
417
403
  }
418
404
  if (!this.#realtimeSupported) {
@@ -460,7 +446,7 @@ export class RealtimeSupervisor {
460
446
  if (this.#connecting)
461
447
  return;
462
448
  if (this.#initialized && !initial)
463
- this.#scheduleRetry();
449
+ this.#schedule(true);
464
450
  return;
465
451
  }
466
452
  this.#reconcileHostState();
@@ -485,14 +471,14 @@ export class RealtimeSupervisor {
485
471
  this.#publish({ phase: 'connected', attempt: 0 });
486
472
  return;
487
473
  }
488
- this.#schedule(0);
474
+ this.#schedule(false);
489
475
  }
476
+ /** Cancel every attempt and release the socket, then publish `phase`. */
490
477
  #suspend(phase) {
491
478
  const disconnect = this.#connected || this.#transportConnected || this.#connecting;
492
- const hadScheduledWork = this.#cancelRetry !== undefined;
493
- const phaseChanged = this.#snapshot.phase !== phase;
494
- if (!disconnect && !hadScheduledWork && !phaseChanged)
479
+ if (!disconnect && !this.#cancelRetry && this.#snapshot.phase === phase) {
495
480
  return;
481
+ }
496
482
  this.#generation += 1;
497
483
  this.#connected = false;
498
484
  this.#transportConnected = false;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.65.0",
3
+ "version": "0.65.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",
@@ -121,11 +121,11 @@
121
121
  },
122
122
  "dependencies": {
123
123
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
124
- "@syncular/core": "0.65.0"
124
+ "@syncular/core": "0.65.1"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.65.0",
128
+ "@syncular/server": "0.65.1",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
@@ -214,9 +214,9 @@ export function documentLifecycleSignal(
214
214
  * Supported host policy for Syncular's explicit realtime transport. It owns
215
215
  * exactly one connect attempt, runs an explicit catch-up round before claiming
216
216
  * connected, retries transient loss with bounded exponential jitter, and
217
- * suspends across offline, background, or protected-preflight state. A host
218
- * `online` report also drives `syncUntilIdle` when realtime is unsupported
219
- * or disabled.
217
+ * suspends across offline, background, or protected-preflight state. Each
218
+ * failed attempt, each host `online` report, and each foreground return
219
+ * while no attempt starts at once drives one HTTP round (§1.8).
220
220
  */
221
221
  export class RealtimeSupervisor {
222
222
  readonly #client: RealtimeSupervisorClient;
@@ -285,20 +285,22 @@ export class RealtimeSupervisor {
285
285
  this.#unsubscribeDiagnostics = this.#client.onDiagnostics((snapshot) =>
286
286
  this.#observeDiagnostics(snapshot),
287
287
  );
288
- this.#unsubscribeConnectivity = this.#connectivity?.subscribe(() => {
289
- // §1.8: the host's connectivity signal re-arms the drive a failed
290
- // round left behind. The drive does not wait for the socket, so a
291
- // socket that cannot connect does not hold back an HTTP round.
292
- if (this.#connectivity?.current() === 'online' && !this.#hostBlock()) {
293
- void Promise.resolve()
294
- .then(() => this.#client.syncUntilIdle())
295
- .catch(() => undefined);
296
- }
288
+ this.#unsubscribeConnectivity = this.#connectivity?.subscribe((state) => {
289
+ if (state === 'online') this.#drive();
297
290
  this.#reconcileHostState();
298
291
  });
299
- this.#unsubscribeLifecycle = this.#lifecycle?.subscribe(() =>
300
- this.#reconcileHostState(),
301
- );
292
+ this.#unsubscribeLifecycle = this.#lifecycle?.subscribe((state) => {
293
+ this.#reconcileHostState();
294
+ // An immediate attempt brings its own round; a pending retry or an
295
+ // absent socket does not.
296
+ const phase = this.#snapshot.phase;
297
+ if (
298
+ state === 'active' &&
299
+ (phase === 'retrying' || phase === 'unsupported')
300
+ ) {
301
+ this.#drive();
302
+ }
303
+ });
302
304
  this.#unsubscribeProtection = this.#protection?.subscribe(() =>
303
305
  this.#reconcileHostState(),
304
306
  );
@@ -310,21 +312,12 @@ export class RealtimeSupervisor {
310
312
  stop(): void {
311
313
  if (this.#stopped) return;
312
314
  this.#stopped = true;
313
- this.#generation += 1;
314
- const disconnect =
315
- this.#connected || this.#transportConnected || this.#connecting;
316
- this.#connected = false;
317
- this.#transportConnected = false;
318
- this.#connecting = false;
319
- this.#attempt = 0;
320
- this.#clearRetry();
315
+ this.#suspend('stopped');
321
316
  this.#unsubscribeDiagnostics?.();
322
317
  this.#unsubscribeConnectivity?.();
323
318
  this.#unsubscribeLifecycle?.();
324
319
  this.#unsubscribeProtection?.();
325
- this.#publish({ phase: 'stopped', attempt: 0 });
326
320
  this.#listeners.clear();
327
- if (disconnect) this.#disconnect();
328
321
  }
329
322
 
330
323
  async #initialize(generation: number): Promise<void> {
@@ -361,6 +354,18 @@ export class RealtimeSupervisor {
361
354
  return undefined;
362
355
  }
363
356
 
357
+ /**
358
+ * §1.8: one HTTP round that re-arms the drive a refused fetch left behind.
359
+ * It does not wait for the socket, so a socket that cannot connect does not
360
+ * hold back the round.
361
+ */
362
+ #drive(): void {
363
+ if (this.#hostBlock()) return;
364
+ void Promise.resolve()
365
+ .then(() => this.#client.syncUntilIdle())
366
+ .catch(() => undefined);
367
+ }
368
+
364
369
  #canConnect(): boolean {
365
370
  return (
366
371
  this.#initialized &&
@@ -393,17 +398,31 @@ export class RealtimeSupervisor {
393
398
  this.#cancelRetry = undefined;
394
399
  }
395
400
 
396
- #schedule(delayMs: number): void {
397
- if (
398
- !this.#canConnect() ||
399
- this.#connected ||
400
- this.#connecting ||
401
- this.#cancelRetry
402
- ) {
403
- return;
401
+ /** A retry counts one attempt and backs off with bounded jitter. */
402
+ #schedule(retry: boolean): void {
403
+ if (!this.#canConnect()) return this.#reconcileHostState();
404
+ // Count an attempt only when this call actually schedules one. Repeated
405
+ // 'disconnected' diagnostics beside a pending retry keep the backoff and
406
+ // the worker-mode reconnect nudge intact.
407
+ if (this.#connected || this.#connecting || this.#cancelRetry) return;
408
+ let delayMs = 0;
409
+ if (retry) {
410
+ const exponential = Math.min(
411
+ this.#maximumDelayMs,
412
+ this.#initialDelayMs * 2 ** this.#attempt,
413
+ );
414
+ const random = this.#random();
415
+ const boundedRandom = Number.isFinite(random)
416
+ ? Math.max(0, Math.min(1, random))
417
+ : 0;
418
+ delayMs = Math.min(
419
+ this.#maximumDelayMs,
420
+ exponential + Math.floor(exponential * 0.25 * boundedRandom),
421
+ );
422
+ this.#attempt = Math.min(32, this.#attempt + 1);
404
423
  }
405
424
  this.#publish(
406
- delayMs > 0
425
+ retry
407
426
  ? { phase: 'retrying', attempt: this.#attempt, retryDelayMs: delayMs }
408
427
  : { phase: 'connecting', attempt: this.#attempt },
409
428
  );
@@ -413,39 +432,6 @@ export class RealtimeSupervisor {
413
432
  }, delayMs);
414
433
  }
415
434
 
416
- #retryDelay(): number {
417
- const exponential = Math.min(
418
- this.#maximumDelayMs,
419
- this.#initialDelayMs * 2 ** this.#attempt,
420
- );
421
- const random = this.#random();
422
- const boundedRandom = Number.isFinite(random)
423
- ? Math.max(0, Math.min(1, random))
424
- : 0;
425
- const jitter = Math.floor(exponential * 0.25 * boundedRandom);
426
- return Math.min(this.#maximumDelayMs, exponential + jitter);
427
- }
428
-
429
- #scheduleRetry(): void {
430
- if (!this.#canConnect()) {
431
- this.#reconcileHostState();
432
- return;
433
- }
434
- // Count an attempt only when this call actually schedules one. Repeated
435
- // 'disconnected' diagnostics beside a pending retry keep the backoff and
436
- // the worker-mode reconnect nudge intact.
437
- if (
438
- this.#connected ||
439
- this.#connecting ||
440
- this.#cancelRetry !== undefined
441
- ) {
442
- return;
443
- }
444
- const delay = this.#retryDelay();
445
- this.#attempt = Math.min(32, this.#attempt + 1);
446
- this.#schedule(delay);
447
- }
448
-
449
435
  /**
450
436
  * A superseded attempt observed a generation bump mid-flight. Whenever a
451
437
  * newer generation is mid-connect or holds the transport, that generation
@@ -496,7 +482,10 @@ export class RealtimeSupervisor {
496
482
  // A superseded attempt leaves the successor's in-flight state alone.
497
483
  if (generation === this.#generation) this.#connecting = false;
498
484
  }
499
- if (failed && generation === this.#generation) this.#scheduleRetry();
485
+ if (failed && generation === this.#generation) {
486
+ this.#schedule(true);
487
+ this.#drive();
488
+ }
500
489
  }
501
490
 
502
491
  async #catchUpConnectedTransport(generation: number): Promise<void> {
@@ -538,7 +527,7 @@ export class RealtimeSupervisor {
538
527
  // A superseded adoption leaves the successor's in-flight state alone.
539
528
  if (generation === this.#generation) this.#connecting = false;
540
529
  }
541
- if (failed && generation === this.#generation) this.#scheduleRetry();
530
+ if (failed && generation === this.#generation) this.#schedule(true);
542
531
  }
543
532
 
544
533
  #observeDiagnostics(
@@ -551,16 +540,8 @@ export class RealtimeSupervisor {
551
540
  snapshot.host.realtime === 'unsupported' ||
552
541
  snapshot.host.realtime === 'disabled'
553
542
  ) {
554
- const disconnect =
555
- this.#connected || this.#transportConnected || this.#connecting;
556
543
  this.#realtimeSupported = false;
557
- this.#generation += 1;
558
- this.#connected = false;
559
- this.#transportConnected = false;
560
- this.#attempt = 0;
561
- this.#clearRetry();
562
- this.#publish({ phase: 'unsupported', attempt: 0 });
563
- if (disconnect) this.#disconnect();
544
+ this.#suspend('unsupported');
564
545
  return;
565
546
  }
566
547
  if (!this.#realtimeSupported) {
@@ -606,7 +587,7 @@ export class RealtimeSupervisor {
606
587
  this.#transportConnected = false;
607
588
  this.#connected = false;
608
589
  if (this.#connecting) return;
609
- if (this.#initialized && !initial) this.#scheduleRetry();
590
+ if (this.#initialized && !initial) this.#schedule(true);
610
591
  return;
611
592
  }
612
593
  this.#reconcileHostState();
@@ -631,15 +612,16 @@ export class RealtimeSupervisor {
631
612
  this.#publish({ phase: 'connected', attempt: 0 });
632
613
  return;
633
614
  }
634
- this.#schedule(0);
615
+ this.#schedule(false);
635
616
  }
636
617
 
637
- #suspend(phase: RealtimeSuspendedPhase): void {
618
+ /** Cancel every attempt and release the socket, then publish `phase`. */
619
+ #suspend(phase: RealtimeSupervisorPhase): void {
638
620
  const disconnect =
639
621
  this.#connected || this.#transportConnected || this.#connecting;
640
- const hadScheduledWork = this.#cancelRetry !== undefined;
641
- const phaseChanged = this.#snapshot.phase !== phase;
642
- if (!disconnect && !hadScheduledWork && !phaseChanged) return;
622
+ if (!disconnect && !this.#cancelRetry && this.#snapshot.phase === phase) {
623
+ return;
624
+ }
643
625
  this.#generation += 1;
644
626
  this.#connected = false;
645
627
  this.#transportConnected = false;