@syncular/client 0.79.3 → 0.80.0

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/dist/client.d.ts CHANGED
@@ -586,6 +586,13 @@ export declare class SyncClient {
586
586
  * Returns an unsubscribe function.
587
587
  */
588
588
  onPresence(listener: (scopeKey: string, error?: PresenceErrorCode) => void): () => void;
589
+ /**
590
+ * §8.7: subscribe to the server's announcement that this client's actor
591
+ * gained scopes. The event carries no scope values and starts no round: the
592
+ * app runs its own discovery and subscribes the units it did not know.
593
+ * Returns an unsubscribe function.
594
+ */
595
+ onScopesChanged(listener: () => void): () => void;
589
596
  /**
590
597
  * §8.6.2 publish (or clear, `doc: null`) this client's presence document
591
598
  * for `scopeKey`. Requires a live socket; the document is ephemeral and
package/dist/client.js CHANGED
@@ -244,6 +244,8 @@ export class SyncClient {
244
244
  #invalidation = new InvalidationEmitter();
245
245
  /** §8.6: subscribable presence-change listeners (twin of onPresence). */
246
246
  #presenceListeners = new Set();
247
+ /** §8.7: listeners for the server's `scopes` announcement. */
248
+ #scopesChanged = new ChangeEmitter();
247
249
  #syncNeededListeners = new Set();
248
250
  #syncIntentListeners = new Set();
249
251
  #diagnostics = new ClientDiagnosticsEmitter();
@@ -1942,6 +1944,15 @@ export class SyncClient {
1942
1944
  this.#presenceListeners.delete(listener);
1943
1945
  };
1944
1946
  }
1947
+ /**
1948
+ * §8.7: subscribe to the server's announcement that this client's actor
1949
+ * gained scopes. The event carries no scope values and starts no round: the
1950
+ * app runs its own discovery and subscribes the units it did not know.
1951
+ * Returns an unsubscribe function.
1952
+ */
1953
+ onScopesChanged(listener) {
1954
+ return this.#scopesChanged.on(listener);
1955
+ }
1945
1956
  /**
1946
1957
  * §8.6.2 publish (or clear, `doc: null`) this client's presence document
1947
1958
  * for `scopeKey`. Requires a live socket; the document is ephemeral and
@@ -3720,6 +3731,8 @@ export class SyncClient {
3720
3731
  }
3721
3732
  if (event.event === 'presence')
3722
3733
  this.#applyPresence(event.data);
3734
+ if (event.event === 'scopes')
3735
+ this.#scopesChanged.emit();
3723
3736
  return event.event === 'heartbeat';
3724
3737
  }
3725
3738
  /**
@@ -139,6 +139,8 @@ export declare abstract class NativeBridgeClient implements PromiseMethods<Clien
139
139
  onChange(listener: ClientChangeListener): () => void;
140
140
  onDiagnostics(listener: ClientDiagnosticsListener): () => void;
141
141
  onPresence(listener: (scopeKey: string, error?: PresenceErrorCode) => void): () => void;
142
+ /** §8.7: the server announced that the actor gained scopes. */
143
+ onScopesChanged(listener: () => void): () => void;
142
144
  query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
143
145
  querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
144
146
  /**
@@ -182,6 +182,7 @@ export class NativeBridgeClient {
182
182
  #progress = new ProgressEmitter();
183
183
  #diagnosticsListeners = new Set();
184
184
  #presenceListeners = new Set();
185
+ #scopesChangedListeners = new Set();
185
186
  #closed = false;
186
187
  #closing;
187
188
  #host;
@@ -384,6 +385,9 @@ export class NativeBridgeClient {
384
385
  case 'presence':
385
386
  fanOut(this.#presenceListeners, typeof event.scopeKey === 'string' ? event.scopeKey : '', event.error);
386
387
  break;
388
+ case 'scopes-changed':
389
+ fanOut(this.#scopesChangedListeners);
390
+ break;
387
391
  case 'diagnostics': {
388
392
  const snapshot = event.snapshot;
389
393
  if (snapshot === null ||
@@ -475,6 +479,12 @@ export class NativeBridgeClient {
475
479
  this.#presenceListeners.add(listener);
476
480
  return () => this.#presenceListeners.delete(listener);
477
481
  }
482
+ /** §8.7: the server announced that the actor gained scopes. */
483
+ onScopesChanged(listener) {
484
+ this.requireOpen();
485
+ this.#scopesChangedListeners.add(listener);
486
+ return () => this.#scopesChangedListeners.delete(listener);
487
+ }
478
488
  async query(sql, params = []) {
479
489
  this.#requireActive();
480
490
  const result = (await this.#reply(() => this.sendQuery(sql, encodeValue(params))));
@@ -304,6 +304,9 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
304
304
  started.onProgress((progress) => {
305
305
  emit({ kind: 'progress', progress });
306
306
  });
307
+ started.onScopesChanged(() => {
308
+ emit({ kind: 'scopes-changed' });
309
+ });
307
310
  started.onChange((batch) => {
308
311
  emit({ kind: 'change', batch });
309
312
  });
@@ -233,6 +233,12 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
233
233
  * `SyncClient.onPresence`. Returns an unsubscribe function.
234
234
  */
235
235
  onPresence(listener: (scopeKey: string, error?: PresenceErrorCode) => void): () => void;
236
+ /**
237
+ * §8.7: subscribe to the server's announcement that the actor gained
238
+ * scopes — the identical surface as `SyncClient.onScopesChanged`. Every
239
+ * tab's handle receives it. Returns an unsubscribe function.
240
+ */
241
+ onScopesChanged(listener: () => void): () => void;
236
242
  /**
237
243
  * Subscribe to the end of every drive to idle (automatic or requested by
238
244
  * any tab) in the current leader's worker, in leader and follower tabs
@@ -100,6 +100,7 @@ export class SyncClientHandle {
100
100
  #changes;
101
101
  #presence;
102
102
  #diagnostics;
103
+ #scopesChanged = new ChangeEmitter();
103
104
  #roleListeners;
104
105
  #leadershipListeners;
105
106
  #unreachableListeners;
@@ -197,6 +198,9 @@ export class SyncClientHandle {
197
198
  }
198
199
  }
199
200
  }
201
+ else if (event.kind === 'scopes-changed') {
202
+ this.#scopesChanged.emit();
203
+ }
200
204
  else if (event.kind === 'change') {
201
205
  this.#changes.emit(event.batch);
202
206
  const legacy = invalidationFromChange(event.batch);
@@ -262,6 +266,14 @@ export class SyncClientHandle {
262
266
  this.#presence.delete(listener);
263
267
  };
264
268
  }
269
+ /**
270
+ * §8.7: subscribe to the server's announcement that the actor gained
271
+ * scopes — the identical surface as `SyncClient.onScopesChanged`. Every
272
+ * tab's handle receives it. Returns an unsubscribe function.
273
+ */
274
+ onScopesChanged(listener) {
275
+ return this.#scopesChanged.on(listener);
276
+ }
265
277
  /**
266
278
  * Subscribe to the end of every drive to idle (automatic or requested by
267
279
  * any tab) in the current leader's worker, in leader and follower tabs
@@ -241,6 +241,9 @@ export type SyncWorkerEvent = {
241
241
  readonly kind: 'presence';
242
242
  readonly scopeKey: string;
243
243
  readonly error?: PresenceErrorCode | undefined;
244
+ } | {
245
+ /** §8.7: the server announced that the actor gained scopes. */
246
+ readonly kind: 'scopes-changed';
244
247
  } | {
245
248
  /** Exact revisioned core transaction; Sets and bigint clone directly. */
246
249
  readonly kind: 'change';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.79.3",
3
+ "version": "0.80.0",
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.79.3"
124
+ "@syncular/core": "0.80.0"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.79.3",
128
+ "@syncular/server": "0.80.0",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
package/src/client.ts CHANGED
@@ -1034,6 +1034,8 @@ export class SyncClient {
1034
1034
  readonly #presenceListeners = new Set<
1035
1035
  (scopeKey: string, error?: PresenceErrorCode) => void
1036
1036
  >();
1037
+ /** §8.7: listeners for the server's `scopes` announcement. */
1038
+ readonly #scopesChanged = new ChangeEmitter<void>();
1037
1039
  readonly #syncNeededListeners = new Set<
1038
1040
  (reason: 'startup' | 'hello' | WakeReason) => void
1039
1041
  >();
@@ -3075,6 +3077,16 @@ export class SyncClient {
3075
3077
  };
3076
3078
  }
3077
3079
 
3080
+ /**
3081
+ * §8.7: subscribe to the server's announcement that this client's actor
3082
+ * gained scopes. The event carries no scope values and starts no round: the
3083
+ * app runs its own discovery and subscribes the units it did not know.
3084
+ * Returns an unsubscribe function.
3085
+ */
3086
+ onScopesChanged(listener: () => void): () => void {
3087
+ return this.#scopesChanged.on(listener);
3088
+ }
3089
+
3078
3090
  /**
3079
3091
  * §8.6.2 publish (or clear, `doc: null`) this client's presence document
3080
3092
  * for `scopeKey`. Requires a live socket; the document is ephemeral and
@@ -5235,6 +5247,7 @@ export class SyncClient {
5235
5247
  return;
5236
5248
  }
5237
5249
  if (event.event === 'presence') this.#applyPresence(event.data);
5250
+ if (event.event === 'scopes') this.#scopesChanged.emit();
5238
5251
  return event.event === 'heartbeat';
5239
5252
  }
5240
5253
 
@@ -309,6 +309,7 @@ export abstract class NativeBridgeClient implements PromiseMethods<
309
309
  readonly #presenceListeners = new Set<
310
310
  (scopeKey: string, error?: PresenceErrorCode) => void
311
311
  >();
312
+ readonly #scopesChangedListeners = new Set<() => void>();
312
313
  #closed = false;
313
314
  #closing: Promise<void> | undefined;
314
315
  #host: object | undefined;
@@ -591,6 +592,9 @@ export abstract class NativeBridgeClient implements PromiseMethods<
591
592
  event.error as PresenceErrorCode | undefined,
592
593
  );
593
594
  break;
595
+ case 'scopes-changed':
596
+ fanOut(this.#scopesChangedListeners);
597
+ break;
594
598
  case 'diagnostics': {
595
599
  const snapshot = event.snapshot as ClientDiagnosticsSnapshot | null;
596
600
  if (
@@ -709,6 +713,13 @@ export abstract class NativeBridgeClient implements PromiseMethods<
709
713
  return () => this.#presenceListeners.delete(listener);
710
714
  }
711
715
 
716
+ /** §8.7: the server announced that the actor gained scopes. */
717
+ onScopesChanged(listener: () => void): () => void {
718
+ this.requireOpen();
719
+ this.#scopesChangedListeners.add(listener);
720
+ return () => this.#scopesChangedListeners.delete(listener);
721
+ }
722
+
712
723
  async query(
713
724
  sql: string,
714
725
  params: readonly SqlValue[] = [],
@@ -502,6 +502,9 @@ export function startSyncWorkerCore(
502
502
  started.onProgress((progress) => {
503
503
  emit({ kind: 'progress', progress });
504
504
  });
505
+ started.onScopesChanged(() => {
506
+ emit({ kind: 'scopes-changed' });
507
+ });
505
508
  started.onChange((batch) => {
506
509
  emit({ kind: 'change', batch });
507
510
  });
@@ -355,6 +355,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
355
355
  (scopeKey: string, error?: PresenceErrorCode) => void
356
356
  >;
357
357
  readonly #diagnostics: ClientDiagnosticsEmitter;
358
+ readonly #scopesChanged = new ChangeEmitter<void>();
358
359
  readonly #roleListeners: Set<(role: HandleRole) => void>;
359
360
  readonly #leadershipListeners: Set<(state: LeadershipState) => void>;
360
361
  readonly #unreachableListeners: Set<(event: LeaderUnreachableEvent) => void>;
@@ -464,6 +465,8 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
464
465
  /* a UI listener must never break event dispatch */
465
466
  }
466
467
  }
468
+ } else if (event.kind === 'scopes-changed') {
469
+ this.#scopesChanged.emit();
467
470
  } else if (event.kind === 'change') {
468
471
  this.#changes.emit(event.batch);
469
472
  const legacy = invalidationFromChange(event.batch);
@@ -536,6 +539,15 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
536
539
  };
537
540
  }
538
541
 
542
+ /**
543
+ * §8.7: subscribe to the server's announcement that the actor gained
544
+ * scopes — the identical surface as `SyncClient.onScopesChanged`. Every
545
+ * tab's handle receives it. Returns an unsubscribe function.
546
+ */
547
+ onScopesChanged(listener: () => void): () => void {
548
+ return this.#scopesChanged.on(listener);
549
+ }
550
+
539
551
  /**
540
552
  * Subscribe to the end of every drive to idle (automatic or requested by
541
553
  * any tab) in the current leader's worker, in leader and follower tabs
@@ -310,6 +310,10 @@ export type SyncWorkerEvent =
310
310
  readonly scopeKey: string;
311
311
  readonly error?: PresenceErrorCode | undefined;
312
312
  }
313
+ | {
314
+ /** §8.7: the server announced that the actor gained scopes. */
315
+ readonly kind: 'scopes-changed';
316
+ }
313
317
  | {
314
318
  /** Exact revisioned core transaction; Sets and bigint clone directly. */
315
319
  readonly kind: 'change';