@syncular/client 0.67.2 → 0.67.3

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/README.md CHANGED
@@ -87,7 +87,8 @@ core per origin. Wake-ups are handled inside the worker (`autoSync`,
87
87
  SPEC §8.4); the supported page-level realtime supervisor owns reconnect and
88
88
  resume policy. The main thread gets `onSyncNeeded` / `onConflict` / `onSynced`
89
89
  events for rendering in the leader tab; `handle.onSynced(listener)` reports the
90
- end of each automatic drive in every tab, followers included.
90
+ end of each drive to idle, automatic or requested by any tab, in every tab,
91
+ followers included.
91
92
 
92
93
  For a reviewed recovery from a retained conflict or rejection, call
93
94
  `await client.proveCurrentBase(outcome)`. The result contains bases for every
@@ -47,6 +47,11 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
47
47
  let offline = false;
48
48
  let headers = {};
49
49
  let closed = false;
50
+ // Every worker event goes through here; a closed worker posts none.
51
+ const emit = (event) => {
52
+ if (!closed)
53
+ post({ t: 'event', event });
54
+ };
50
55
  let pushingDiagnostics = false;
51
56
  // -- one sync loop: RPC-driven and auto-driven rounds serialize ----------
52
57
  let syncChain = Promise.resolve();
@@ -55,6 +60,17 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
55
60
  syncChain = next.then(() => undefined, () => undefined);
56
61
  return next;
57
62
  }
63
+ /**
64
+ * One drive to idle, automatic or requested: its end reaches every tab.
65
+ * The event is posted inside the serialized step, so the drive settles
66
+ * before the next queued drive starts, as without it.
67
+ */
68
+ function drive(run) {
69
+ return serializedSync(() => run().then((summary) => (emit({ kind: 'synced', summary }), summary), (error) => {
70
+ emit({ kind: 'synced', error: toErrorShape(error) });
71
+ throw error;
72
+ }));
73
+ }
58
74
  // -- SPEC §7.5 host loop: event-driven intents, no interactive polling --
59
75
  let autoSync = true;
60
76
  let autoSyncScheduled = false;
@@ -73,14 +89,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
73
89
  connectivity: offline ? 'offline' : snapshot.host.connectivity,
74
90
  realtime: snapshot.host.realtime,
75
91
  });
76
- const postDiagnostics = (snapshot) => {
77
- if (!closed) {
78
- post({
79
- t: 'event',
80
- event: { kind: 'diagnostics', snapshot: workerDiagnostics(snapshot) },
81
- });
82
- }
83
- };
92
+ const postDiagnostics = (snapshot) => emit({ kind: 'diagnostics', snapshot: workerDiagnostics(snapshot) });
84
93
  function runAutoSync() {
85
94
  if (closed ||
86
95
  client === undefined ||
@@ -90,7 +99,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
90
99
  return;
91
100
  }
92
101
  const running = client;
93
- void serializedSync(() => {
102
+ void drive(() => {
94
103
  // The queued round owns the flag from here. Clearing it at entry would
95
104
  // let every wake-up that arrives while this round waits behind the
96
105
  // running one queue its own full drive (§8.4 coalescing).
@@ -99,18 +108,12 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
99
108
  })
100
109
  .then((summary) => {
101
110
  retryDelayMs = 250;
102
- if (!closed)
103
- post({ t: 'event', event: { kind: 'synced', summary } });
104
111
  if (summary.budgetExhausted)
105
112
  consumeSyncIntent({ kind: 'interactive' });
106
113
  })
107
114
  .catch((error) => {
108
115
  if (closed)
109
116
  return;
110
- post({
111
- t: 'event',
112
- event: { kind: 'synced', error: toErrorShape(error) },
113
- });
114
117
  // §7.8: a retryable drive rejection owes another drive. A retryable
115
118
  // round failure already handed this loop its background intent; the
116
119
  // drive deadline did not. An unreachable endpoint waits for the
@@ -282,29 +285,27 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
282
285
  ? { previousVersionContext: config.previousVersionContext }
283
286
  : {}),
284
287
  onSyncNeeded: (reason) => {
285
- post({ t: 'event', event: { kind: 'sync-needed', reason } });
288
+ emit({ kind: 'sync-needed', reason });
286
289
  consumeSyncIntent({ kind: 'interactive' });
287
290
  },
288
291
  onSyncIntent: consumeSyncIntent,
289
292
  onConflict: (conflict) => {
290
- post({ t: 'event', event: { kind: 'conflict', conflict } });
293
+ emit({ kind: 'conflict', conflict });
291
294
  },
292
295
  onUpgrading: (upgrading) => {
293
296
  // §7.4.5: surface the schema-bump reset + completion to the UI thread.
294
- post({ t: 'event', event: { kind: 'upgrading', upgrading } });
297
+ emit({ kind: 'upgrading', upgrading });
295
298
  },
296
299
  onPresence: (scopeKey, error) => {
297
300
  // §8.6: surface a presence change or rejection to the UI thread.
298
- post({ t: 'event', event: { kind: 'presence', scopeKey, error } });
301
+ emit({ kind: 'presence', scopeKey, error });
299
302
  },
300
303
  });
301
304
  started.onProgress((progress) => {
302
- if (!closed)
303
- post({ t: 'event', event: { kind: 'progress', progress } });
305
+ emit({ kind: 'progress', progress });
304
306
  });
305
307
  started.onChange((batch) => {
306
- if (!closed)
307
- post({ t: 'event', event: { kind: 'change', batch } });
308
+ emit({ kind: 'change', batch });
308
309
  });
309
310
  await started.start();
310
311
  realtimeConnector =
@@ -391,7 +392,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
391
392
  },
392
393
  syncUntilIdle: (options) => {
393
394
  const running = requireClient();
394
- return serializedSync(() => running.syncUntilIdle(options));
395
+ return drive(() => running.syncUntilIdle(options));
395
396
  },
396
397
  proveCurrentBase: (outcome, options) => {
397
398
  const running = requireClient();
@@ -147,7 +147,7 @@ export interface SyncClientHandleConfig {
147
147
  readonly onLeadershipChange?: (state: LeadershipState) => void;
148
148
  readonly onSyncNeeded?: (reason: 'startup' | 'hello' | WakeReason) => void;
149
149
  readonly onConflict?: (conflict: ConflictRecord) => void;
150
- /** The leader worker's automatic drive ended (leader tab only). */
150
+ /** A drive to idle in the leader worker ended (leader tab only). */
151
151
  readonly onSynced?: SyncedListener;
152
152
  /** §7.4.5: schema-bump `upgrading` state changed (reset began/completed). */
153
153
  readonly onUpgrading?: (upgrading: boolean) => void;
@@ -158,8 +158,8 @@ export interface SyncClientHandleConfig {
158
158
  readonly onDiagnostics?: (snapshot: ClientDiagnosticsSnapshot) => void;
159
159
  }
160
160
  /**
161
- * The end of one automatic `syncUntilIdle` drive in the leader worker: its
162
- * summary, or the error it failed with.
161
+ * The end of one `syncUntilIdle` drive in the leader worker, automatic or
162
+ * requested by any tab: its summary, or the error it failed with.
163
163
  */
164
164
  export type SyncedListener = (result: {
165
165
  readonly summary?: SyncSummary;
@@ -231,8 +231,9 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
231
231
  */
232
232
  onPresence(listener: (scopeKey: string, error?: PresenceErrorCode) => void): () => void;
233
233
  /**
234
- * Subscribe to the end of every automatic drive of the current leader's
235
- * worker, in leader and follower tabs alike. A follower receives only the
234
+ * Subscribe to the end of every drive to idle (automatic or requested by
235
+ * any tab) in the current leader's worker, in leader and follower tabs
236
+ * alike. A follower receives only the
236
237
  * drives of the leader it is bound to; a drive that ended before this tab
237
238
  * bound is not replayed. Returns an unsubscribe function.
238
239
  */
@@ -263,8 +263,9 @@ export class SyncClientHandle {
263
263
  };
264
264
  }
265
265
  /**
266
- * Subscribe to the end of every automatic drive of the current leader's
267
- * worker, in leader and follower tabs alike. A follower receives only the
266
+ * Subscribe to the end of every drive to idle (automatic or requested by
267
+ * any tab) in the current leader's worker, in leader and follower tabs
268
+ * alike. A follower receives only the
268
269
  * drives of the leader it is bound to; a drive that ended before this tab
269
270
  * bound is not replayed. Returns an unsubscribe function.
270
271
  */
@@ -225,7 +225,7 @@ export type SyncWorkerEvent = {
225
225
  readonly kind: 'conflict';
226
226
  readonly conflict: ConflictRecord;
227
227
  } | {
228
- /** An autoSync round finished (or failed) inside the worker. */
228
+ /** A drive to idle (automatic or requested) finished or failed inside the worker. */
229
229
  readonly kind: 'synced';
230
230
  readonly summary?: SyncSummary;
231
231
  readonly error?: WorkerErrorShape;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.67.2",
3
+ "version": "0.67.3",
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.67.2"
124
+ "@syncular/core": "0.67.3"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.67.2",
128
+ "@syncular/server": "0.67.3",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
@@ -48,6 +48,7 @@ import {
48
48
  WORKER_FAILED_CODE,
49
49
  WORKER_METHOD_UNAVAILABLE_CODE,
50
50
  type WorkerApi,
51
+ type SyncWorkerEvent,
51
52
  type WorkerCallMessage,
52
53
  type WorkerInitConfig,
53
54
  type WorkerInitResult,
@@ -196,6 +197,10 @@ export function startSyncWorkerCore(
196
197
  let offline = false;
197
198
  let headers: Readonly<Record<string, string>> = {};
198
199
  let closed = false;
200
+ // Every worker event goes through here; a closed worker posts none.
201
+ const emit = (event: SyncWorkerEvent): void => {
202
+ if (!closed) post({ t: 'event', event });
203
+ };
199
204
  let pushingDiagnostics = false;
200
205
 
201
206
  // -- one sync loop: RPC-driven and auto-driven rounds serialize ----------
@@ -209,6 +214,25 @@ export function startSyncWorkerCore(
209
214
  return next;
210
215
  }
211
216
 
217
+ /**
218
+ * One drive to idle, automatic or requested: its end reaches every tab.
219
+ * The event is posted inside the serialized step, so the drive settles
220
+ * before the next queued drive starts, as without it.
221
+ */
222
+ function drive(
223
+ run: () => ReturnType<SyncClient['syncUntilIdle']>,
224
+ ): ReturnType<SyncClient['syncUntilIdle']> {
225
+ return serializedSync(() =>
226
+ run().then(
227
+ (summary) => (emit({ kind: 'synced', summary }), summary),
228
+ (error: unknown) => {
229
+ emit({ kind: 'synced', error: toErrorShape(error) });
230
+ throw error;
231
+ },
232
+ ),
233
+ );
234
+ }
235
+
212
236
  // -- SPEC §7.5 host loop: event-driven intents, no interactive polling --
213
237
  let autoSync = true;
214
238
  let autoSyncScheduled = false;
@@ -230,14 +254,8 @@ export function startSyncWorkerCore(
230
254
  connectivity: offline ? 'offline' : snapshot.host.connectivity,
231
255
  realtime: snapshot.host.realtime,
232
256
  });
233
- const postDiagnostics = (snapshot: ClientDiagnosticsSnapshot): void => {
234
- if (!closed) {
235
- post({
236
- t: 'event',
237
- event: { kind: 'diagnostics', snapshot: workerDiagnostics(snapshot) },
238
- });
239
- }
240
- };
257
+ const postDiagnostics = (snapshot: ClientDiagnosticsSnapshot): void =>
258
+ emit({ kind: 'diagnostics', snapshot: workerDiagnostics(snapshot) });
241
259
 
242
260
  function runAutoSync(): void {
243
261
  if (
@@ -250,7 +268,7 @@ export function startSyncWorkerCore(
250
268
  return;
251
269
  }
252
270
  const running = client;
253
- void serializedSync(() => {
271
+ void drive(() => {
254
272
  // The queued round owns the flag from here. Clearing it at entry would
255
273
  // let every wake-up that arrives while this round waits behind the
256
274
  // running one queue its own full drive (§8.4 coalescing).
@@ -259,15 +277,10 @@ export function startSyncWorkerCore(
259
277
  })
260
278
  .then((summary) => {
261
279
  retryDelayMs = 250;
262
- if (!closed) post({ t: 'event', event: { kind: 'synced', summary } });
263
280
  if (summary.budgetExhausted) consumeSyncIntent({ kind: 'interactive' });
264
281
  })
265
282
  .catch((error: unknown) => {
266
283
  if (closed) return;
267
- post({
268
- t: 'event',
269
- event: { kind: 'synced', error: toErrorShape(error) },
270
- });
271
284
  // §7.8: a retryable drive rejection owes another drive. A retryable
272
285
  // round failure already handed this loop its background intent; the
273
286
  // drive deadline did not. An unreachable endpoint waits for the
@@ -470,27 +483,27 @@ export function startSyncWorkerCore(
470
483
  ? { previousVersionContext: config.previousVersionContext }
471
484
  : {}),
472
485
  onSyncNeeded: (reason) => {
473
- post({ t: 'event', event: { kind: 'sync-needed', reason } });
486
+ emit({ kind: 'sync-needed', reason });
474
487
  consumeSyncIntent({ kind: 'interactive' });
475
488
  },
476
489
  onSyncIntent: consumeSyncIntent,
477
490
  onConflict: (conflict) => {
478
- post({ t: 'event', event: { kind: 'conflict', conflict } });
491
+ emit({ kind: 'conflict', conflict });
479
492
  },
480
493
  onUpgrading: (upgrading) => {
481
494
  // §7.4.5: surface the schema-bump reset + completion to the UI thread.
482
- post({ t: 'event', event: { kind: 'upgrading', upgrading } });
495
+ emit({ kind: 'upgrading', upgrading });
483
496
  },
484
497
  onPresence: (scopeKey, error) => {
485
498
  // §8.6: surface a presence change or rejection to the UI thread.
486
- post({ t: 'event', event: { kind: 'presence', scopeKey, error } });
499
+ emit({ kind: 'presence', scopeKey, error });
487
500
  },
488
501
  });
489
502
  started.onProgress((progress) => {
490
- if (!closed) post({ t: 'event', event: { kind: 'progress', progress } });
503
+ emit({ kind: 'progress', progress });
491
504
  });
492
505
  started.onChange((batch) => {
493
- if (!closed) post({ t: 'event', event: { kind: 'change', batch } });
506
+ emit({ kind: 'change', batch });
494
507
  });
495
508
  await started.start();
496
509
  realtimeConnector =
@@ -585,7 +598,7 @@ export function startSyncWorkerCore(
585
598
  },
586
599
  syncUntilIdle: (options) => {
587
600
  const running = requireClient();
588
- return serializedSync(() => running.syncUntilIdle(options));
601
+ return drive(() => running.syncUntilIdle(options));
589
602
  },
590
603
  proveCurrentBase: (outcome, options) => {
591
604
  const running = requireClient();
@@ -260,7 +260,7 @@ export interface SyncClientHandleConfig {
260
260
  readonly onLeadershipChange?: (state: LeadershipState) => void;
261
261
  readonly onSyncNeeded?: (reason: 'startup' | 'hello' | WakeReason) => void;
262
262
  readonly onConflict?: (conflict: ConflictRecord) => void;
263
- /** The leader worker's automatic drive ended (leader tab only). */
263
+ /** A drive to idle in the leader worker ended (leader tab only). */
264
264
  readonly onSynced?: SyncedListener;
265
265
  /** §7.4.5: schema-bump `upgrading` state changed (reset began/completed). */
266
266
  readonly onUpgrading?: (upgrading: boolean) => void;
@@ -272,8 +272,8 @@ export interface SyncClientHandleConfig {
272
272
  }
273
273
 
274
274
  /**
275
- * The end of one automatic `syncUntilIdle` drive in the leader worker: its
276
- * summary, or the error it failed with.
275
+ * The end of one `syncUntilIdle` drive in the leader worker, automatic or
276
+ * requested by any tab: its summary, or the error it failed with.
277
277
  */
278
278
  export type SyncedListener = (result: {
279
279
  readonly summary?: SyncSummary;
@@ -532,8 +532,9 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
532
532
  }
533
533
 
534
534
  /**
535
- * Subscribe to the end of every automatic drive of the current leader's
536
- * worker, in leader and follower tabs alike. A follower receives only the
535
+ * Subscribe to the end of every drive to idle (automatic or requested by
536
+ * any tab) in the current leader's worker, in leader and follower tabs
537
+ * alike. A follower receives only the
537
538
  * drives of the leader it is bound to; a drive that ended before this tab
538
539
  * bound is not replayed. Returns an unsubscribe function.
539
540
  */
@@ -290,7 +290,7 @@ export type SyncWorkerEvent =
290
290
  }
291
291
  | { readonly kind: 'conflict'; readonly conflict: ConflictRecord }
292
292
  | {
293
- /** An autoSync round finished (or failed) inside the worker. */
293
+ /** A drive to idle (automatic or requested) finished or failed inside the worker. */
294
294
  readonly kind: 'synced';
295
295
  readonly summary?: SyncSummary;
296
296
  readonly error?: WorkerErrorShape;