@syncular/client 0.67.0 → 0.67.2

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
@@ -86,7 +86,8 @@ acquires the Web Locks leader lock *before* spawning the worker — one
86
86
  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
- events for rendering.
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
91
 
91
92
  For a reviewed recovery from a retained conflict or rejection, call
92
93
  `await client.proveCurrentBase(outcome)`. The result contains bases for every
@@ -147,11 +147,8 @@ 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
- /** A worker-side autoSync round finished (or failed). */
151
- readonly onSynced?: (result: {
152
- readonly summary?: SyncSummary;
153
- readonly error?: WorkerErrorShape;
154
- }) => void;
150
+ /** The leader worker's automatic drive ended (leader tab only). */
151
+ readonly onSynced?: SyncedListener;
155
152
  /** §7.4.5: schema-bump `upgrading` state changed (reset began/completed). */
156
153
  readonly onUpgrading?: (upgrading: boolean) => void;
157
154
  /** §8.6: presence on a scope key changed, or the server refused this
@@ -160,6 +157,14 @@ export interface SyncClientHandleConfig {
160
157
  /** Atomic privacy-safe diagnostics changed. */
161
158
  readonly onDiagnostics?: (snapshot: ClientDiagnosticsSnapshot) => void;
162
159
  }
160
+ /**
161
+ * The end of one automatic `syncUntilIdle` drive in the leader worker: its
162
+ * summary, or the error it failed with.
163
+ */
164
+ export type SyncedListener = (result: {
165
+ readonly summary?: SyncSummary;
166
+ readonly error?: WorkerErrorShape;
167
+ }) => void;
163
168
  /**
164
169
  * A running worker core owned by THIS tab (the leader). Wraps the worker and
165
170
  * the RPC pending map. Torn down on `close()` or on a graceful demotion.
@@ -225,6 +230,13 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
225
230
  * `SyncClient.onPresence`. Returns an unsubscribe function.
226
231
  */
227
232
  onPresence(listener: (scopeKey: string, error?: PresenceErrorCode) => void): () => void;
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
236
+ * drives of the leader it is bound to; a drive that ended before this tab
237
+ * bound is not replayed. Returns an unsubscribe function.
238
+ */
239
+ onSynced(listener: SyncedListener): () => void;
228
240
  /** Subscribe to role transitions (follower → leader on promotion). */
229
241
  onRoleChange(listener: (role: HandleRole) => void): () => void;
230
242
  onLeadershipChange(listener: (state: LeadershipState) => void): () => void;
@@ -96,6 +96,7 @@ export class SyncClientHandle {
96
96
  #core;
97
97
  #invalidation;
98
98
  #progress = new ProgressEmitter();
99
+ #synced = new Set();
99
100
  #changes;
100
101
  #presence;
101
102
  #diagnostics;
@@ -202,6 +203,16 @@ export class SyncClientHandle {
202
203
  if (legacy !== undefined)
203
204
  this.#invalidation.emit(legacy);
204
205
  }
206
+ else if (event.kind === 'synced') {
207
+ for (const listener of this.#synced) {
208
+ try {
209
+ listener(syncedResult(event));
210
+ }
211
+ catch {
212
+ /* a UI listener must never break event dispatch */
213
+ }
214
+ }
215
+ }
205
216
  else if (event.kind === 'diagnostics') {
206
217
  this.#diagnostics.emit(withClientDiagnosticsHost(event.snapshot, {
207
218
  ...event.snapshot.host,
@@ -251,6 +262,18 @@ export class SyncClientHandle {
251
262
  this.#presence.delete(listener);
252
263
  };
253
264
  }
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
268
+ * drives of the leader it is bound to; a drive that ended before this tab
269
+ * bound is not replayed. Returns an unsubscribe function.
270
+ */
271
+ onSynced(listener) {
272
+ this.#synced.add(listener);
273
+ return () => {
274
+ this.#synced.delete(listener);
275
+ };
276
+ }
254
277
  /** Subscribe to role transitions (follower → leader on promotion). */
255
278
  onRoleChange(listener) {
256
279
  this.#roleListeners.add(listener);
@@ -668,6 +691,12 @@ function buildInitConfig(config, headers = config.headers) {
668
691
  ...(config.autoSync !== undefined ? { autoSync: config.autoSync } : {}),
669
692
  };
670
693
  }
694
+ function syncedResult(event) {
695
+ return {
696
+ ...(event.summary !== undefined ? { summary: event.summary } : {}),
697
+ ...(event.error !== undefined ? { error: event.error } : {}),
698
+ };
699
+ }
671
700
  /** Route a worker event to the config-level callbacks (leader visibility). */
672
701
  function fireConfigCallbacks(config, event) {
673
702
  if (event.kind === 'sync-needed') {
@@ -683,10 +712,7 @@ function fireConfigCallbacks(config, event) {
683
712
  config.onPresence?.(event.scopeKey, event.error);
684
713
  }
685
714
  else if (event.kind === 'synced') {
686
- config.onSynced?.({
687
- ...(event.summary !== undefined ? { summary: event.summary } : {}),
688
- ...(event.error !== undefined ? { error: event.error } : {}),
689
- });
715
+ config.onSynced?.(syncedResult(event));
690
716
  }
691
717
  else if (event.kind === 'diagnostics') {
692
718
  config.onDiagnostics?.(event.snapshot);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.67.0",
3
+ "version": "0.67.2",
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.0"
124
+ "@syncular/core": "0.67.2"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.67.0",
128
+ "@syncular/server": "0.67.2",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
@@ -260,11 +260,8 @@ 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
- /** A worker-side autoSync round finished (or failed). */
264
- readonly onSynced?: (result: {
265
- readonly summary?: SyncSummary;
266
- readonly error?: WorkerErrorShape;
267
- }) => void;
263
+ /** The leader worker's automatic drive ended (leader tab only). */
264
+ readonly onSynced?: SyncedListener;
268
265
  /** §7.4.5: schema-bump `upgrading` state changed (reset began/completed). */
269
266
  readonly onUpgrading?: (upgrading: boolean) => void;
270
267
  /** §8.6: presence on a scope key changed, or the server refused this
@@ -274,6 +271,15 @@ export interface SyncClientHandleConfig {
274
271
  readonly onDiagnostics?: (snapshot: ClientDiagnosticsSnapshot) => void;
275
272
  }
276
273
 
274
+ /**
275
+ * The end of one automatic `syncUntilIdle` drive in the leader worker: its
276
+ * summary, or the error it failed with.
277
+ */
278
+ export type SyncedListener = (result: {
279
+ readonly summary?: SyncSummary;
280
+ readonly error?: WorkerErrorShape;
281
+ }) => void;
282
+
277
283
  interface Pending {
278
284
  resolve(value: unknown): void;
279
285
  reject(error: unknown): void;
@@ -338,6 +344,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
338
344
  #core: LeaderCore | undefined;
339
345
  readonly #invalidation: InvalidationEmitter;
340
346
  readonly #progress = new ProgressEmitter();
347
+ readonly #synced = new Set<SyncedListener>();
341
348
  readonly #changes: ChangeEmitter;
342
349
  readonly #presence: Set<
343
350
  (scopeKey: string, error?: PresenceErrorCode) => void
@@ -456,6 +463,14 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
456
463
  this.#changes.emit(event.batch);
457
464
  const legacy = invalidationFromChange(event.batch);
458
465
  if (legacy !== undefined) this.#invalidation.emit(legacy);
466
+ } else if (event.kind === 'synced') {
467
+ for (const listener of this.#synced) {
468
+ try {
469
+ listener(syncedResult(event));
470
+ } catch {
471
+ /* a UI listener must never break event dispatch */
472
+ }
473
+ }
459
474
  } else if (event.kind === 'diagnostics') {
460
475
  this.#diagnostics.emit(
461
476
  withClientDiagnosticsHost(event.snapshot, {
@@ -516,6 +531,19 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
516
531
  };
517
532
  }
518
533
 
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
537
+ * drives of the leader it is bound to; a drive that ended before this tab
538
+ * bound is not replayed. Returns an unsubscribe function.
539
+ */
540
+ onSynced(listener: SyncedListener): () => void {
541
+ this.#synced.add(listener);
542
+ return () => {
543
+ this.#synced.delete(listener);
544
+ };
545
+ }
546
+
519
547
  /** Subscribe to role transitions (follower → leader on promotion). */
520
548
  onRoleChange(listener: (role: HandleRole) => void): () => void {
521
549
  this.#roleListeners.add(listener);
@@ -1073,6 +1101,15 @@ function buildInitConfig(
1073
1101
  };
1074
1102
  }
1075
1103
 
1104
+ function syncedResult(
1105
+ event: Extract<SyncWorkerEvent, { kind: 'synced' }>,
1106
+ ): Parameters<SyncedListener>[0] {
1107
+ return {
1108
+ ...(event.summary !== undefined ? { summary: event.summary } : {}),
1109
+ ...(event.error !== undefined ? { error: event.error } : {}),
1110
+ };
1111
+ }
1112
+
1076
1113
  /** Route a worker event to the config-level callbacks (leader visibility). */
1077
1114
  function fireConfigCallbacks(
1078
1115
  config: SyncClientHandleConfig,
@@ -1087,10 +1124,7 @@ function fireConfigCallbacks(
1087
1124
  } else if (event.kind === 'presence') {
1088
1125
  config.onPresence?.(event.scopeKey, event.error);
1089
1126
  } else if (event.kind === 'synced') {
1090
- config.onSynced?.({
1091
- ...(event.summary !== undefined ? { summary: event.summary } : {}),
1092
- ...(event.error !== undefined ? { error: event.error } : {}),
1093
- });
1127
+ config.onSynced?.(syncedResult(event));
1094
1128
  } else if (event.kind === 'diagnostics') {
1095
1129
  config.onDiagnostics?.(event.snapshot);
1096
1130
  }