@syncular/client 0.64.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.
@@ -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;
@@ -31,7 +31,10 @@ export interface SyncWorkerOverrides {
31
31
  * deadlines and the client's §8.5 heartbeat watchdog.
32
32
  */
33
33
  readonly scheduleBackground?: (callback: () => void, delayMs: number) => () => void;
34
- readonly createTransport?: (config: WorkerInitConfig) => SyncTransport;
34
+ /** `http` reads the current host auth set, as the default transport does. */
35
+ readonly createTransport?: (config: WorkerInitConfig, http: {
36
+ readonly headers: () => Readonly<Record<string, string>>;
37
+ }) => SyncTransport;
35
38
  readonly createSegments?: (config: WorkerInitConfig) => SegmentDownloader | undefined;
36
39
  /**
37
40
  * Custom realtime connector, e.g. one that mints a fresh ticket per
@@ -220,7 +220,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
220
220
  }
221
221
  }
222
222
  const remote = overrides.createTransport !== undefined
223
- ? overrides.createTransport(config)
223
+ ? overrides.createTransport(config, http)
224
224
  : httpSyncTransport(config.endpoints.syncUrl, http);
225
225
  const remoteSegments = overrides.createSegments !== undefined
226
226
  ? overrides.createSegments(config)
@@ -485,8 +485,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
485
485
  }
486
486
  async function defaultOpenDatabase(config) {
487
487
  if (config.database.mode !== 'persistent') {
488
- throw new ClientSyncError(WORKER_FAILED_CODE, "database mode 'custom' requires an openDatabase override in the " +
489
- 'worker bootstrap (startSyncWorker({ openDatabase }))');
488
+ throw new ClientSyncError(WORKER_FAILED_CODE, "database mode 'custom' requires startSyncWorker({ openDatabase })");
490
489
  }
491
490
  return openPersistentWasmDatabase(config.database.name, {
492
491
  ...(config.database.directory !== undefined
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.64.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",
@@ -97,6 +97,14 @@
97
97
  "types": "./dist/native-bridge.d.ts",
98
98
  "default": "./dist/native-bridge.js"
99
99
  }
100
+ },
101
+ "./dev": {
102
+ "bun": "./src/dev-profiler.ts",
103
+ "browser": "./dist/dev-profiler.js",
104
+ "import": {
105
+ "types": "./dist/dev-profiler.d.ts",
106
+ "default": "./dist/dev-profiler.js"
107
+ }
100
108
  }
101
109
  },
102
110
  "files": [
@@ -113,11 +121,11 @@
113
121
  },
114
122
  "dependencies": {
115
123
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
116
- "@syncular/core": "0.64.0"
124
+ "@syncular/core": "0.65.1"
117
125
  },
118
126
  "devDependencies": {
119
127
  "@electric-sql/pglite": "^0.5.4",
120
- "@syncular/server": "0.64.0",
128
+ "@syncular/server": "0.65.1",
121
129
  "playwright": "1.63.0",
122
130
  "vite": "8.3.4"
123
131
  }