@syncular/client 0.70.3 → 0.71.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.
@@ -225,6 +225,7 @@ export declare abstract class NativeBridgeClient implements PromiseMethods<Clien
225
225
  presence(scopeKey: string): Promise<readonly PresencePeer[]>;
226
226
  setPresence(scopeKey: string, doc: Record<string, unknown> | null): Promise<void>;
227
227
  connectRealtime(): Promise<void>;
228
+ /** A closed client holds no socket, so its disconnect succeeds. */
228
229
  disconnectRealtime(): Promise<void>;
229
230
  /**
230
231
  * Shut down the native core, then detach listeners. Every call returns the
@@ -243,6 +243,7 @@ export class NativeBridgeClient {
243
243
  'beginSecurityPreflight',
244
244
  'activateSecurity',
245
245
  'setTransportEnabled',
246
+ 'disconnectRealtime',
246
247
  'purgeLocalData',
247
248
  'previousVersionDiscard',
248
249
  'localRevision',
@@ -769,7 +770,10 @@ export class NativeBridgeClient {
769
770
  async connectRealtime() {
770
771
  await this.command('connectRealtime', {});
771
772
  }
773
+ /** A closed client holds no socket, so its disconnect succeeds. */
772
774
  async disconnectRealtime() {
775
+ if (this.#closed)
776
+ return;
773
777
  await this.command('disconnectRealtime', {});
774
778
  }
775
779
  /**
@@ -26,9 +26,14 @@ export interface RealtimeSupervisorSnapshot {
26
26
  readonly retryDelayMs?: number;
27
27
  /** The latched failure of phase `unsupported` (or `stopped`). */
28
28
  readonly failureCode?: RealtimeSupervisorFailureCode;
29
+ /**
30
+ * The Syncular code (or `unknown`) the latest refused
31
+ * `disconnectRealtime()` rejected with, kept until the next `connected`.
32
+ */
33
+ readonly disconnectCauseCode?: string;
29
34
  }
30
35
  /** SPEC §10.3: client-local supervisor failures, never on the wire. */
31
- export type RealtimeSupervisorFailureCode = 'realtime.diagnostics_unavailable' | 'realtime.disconnect_failed' | 'realtime.cleanup_failed';
36
+ export type RealtimeSupervisorFailureCode = 'realtime.diagnostics_unavailable' | 'realtime.cleanup_failed';
32
37
  export interface RealtimeSupervisorOptions {
33
38
  /**
34
39
  * Host online/offline evidence, the only connectivity the supervisor
@@ -89,8 +94,6 @@ export declare class RealtimeSupervisorError extends ClientSyncError {
89
94
  readonly code: RealtimeSupervisorFailureCode;
90
95
  readonly cleanupFailureCode?: 'realtime.cleanup_failed';
91
96
  readonly diagnosticsFailureCode?: 'realtime.diagnostics_unavailable';
92
- /** The code the client's `disconnectRealtime` rejected with. */
93
- readonly disconnectCauseCode?: string;
94
97
  /** Set by the installed `close()` when the client close failed as well. */
95
98
  readonly stopFailureCode?: RealtimeSupervisorFailureCode;
96
99
  readonly closeFailureCode?: string;
@@ -104,8 +107,9 @@ export declare class RealtimeSupervisorError extends ClientSyncError {
104
107
  * exponential jitter, and the backoff survives offline, background and
105
108
  * protected suspensions. While no socket is connected, each failed connect,
106
109
  * each host `online` report and each foreground return drives one HTTP round
107
- * (§1.8). A disconnect, diagnostics or cleanup failure latches phase
108
- * `unsupported` with its `failureCode`, and `stop()` rejects with it.
110
+ * (§1.8). A refused disconnect counts one retry and names its cause in the
111
+ * snapshot. A diagnostics or cleanup failure latches phase `unsupported` with
112
+ * its `failureCode`, and `stop()` rejects with it.
109
113
  */
110
114
  export declare class RealtimeSupervisor {
111
115
  #private;
@@ -150,8 +150,9 @@ export class RealtimeSupervisorError extends ClientSyncError {
150
150
  * exponential jitter, and the backoff survives offline, background and
151
151
  * protected suspensions. While no socket is connected, each failed connect,
152
152
  * each host `online` report and each foreground return drives one HTTP round
153
- * (§1.8). A disconnect, diagnostics or cleanup failure latches phase
154
- * `unsupported` with its `failureCode`, and `stop()` rejects with it.
153
+ * (§1.8). A refused disconnect counts one retry and names its cause in the
154
+ * snapshot. A diagnostics or cleanup failure latches phase `unsupported` with
155
+ * its `failureCode`, and `stop()` rejects with it.
155
156
  */
156
157
  export class RealtimeSupervisor {
157
158
  #client;
@@ -192,6 +193,7 @@ export class RealtimeSupervisor {
192
193
  #failure;
193
194
  /** Every failure of the lifetime, named for the stop rejection. */
194
195
  #failures = {};
196
+ #disconnectCause;
195
197
  #snapshot = { phase: 'idle', attempt: 0 };
196
198
  constructor(client, options = {}) {
197
199
  this.#client = client;
@@ -334,7 +336,10 @@ export class RealtimeSupervisor {
334
336
  this.#drive();
335
337
  });
336
338
  }
337
- #publish(snapshot) {
339
+ #publish(next) {
340
+ const snapshot = this.#disconnectCause === undefined
341
+ ? next
342
+ : { ...next, disconnectCauseCode: this.#disconnectCause };
338
343
  if (JSON.stringify(this.#snapshot) === JSON.stringify(snapshot))
339
344
  return;
340
345
  this.#snapshot = Object.freeze(snapshot);
@@ -484,6 +489,7 @@ export class RealtimeSupervisor {
484
489
  this.#connected = true;
485
490
  this.#attempt = 0;
486
491
  this.#delayMs = 0;
492
+ this.#disconnectCause = undefined;
487
493
  this.#publish({ phase: 'connected', attempt: 0 });
488
494
  return;
489
495
  }
@@ -517,10 +523,11 @@ export class RealtimeSupervisor {
517
523
  this.#disconnecting = Promise.resolve();
518
524
  this.#disconnecting = new Promise((resolve) => resolve(this.#client.disconnectRealtime()))
519
525
  .catch((error) => {
520
- if (retryable(error))
521
- return this.#retry();
522
- this.#failures.disconnectCauseCode = causeCode(error);
523
- this.#fail('realtime.disconnect_failed');
526
+ // The socket counts as released: one the client kept open reports
527
+ // `connected` in its diagnostics and is adopted after a catch-up.
528
+ this.#disconnectCause = causeCode(error);
529
+ this.#retry();
530
+ this.#publish(this.#snapshot);
524
531
  })
525
532
  .finally(() => {
526
533
  this.#disconnecting = undefined;
@@ -305,6 +305,7 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
305
305
  units(): Promise<UnitRecord[]>;
306
306
  unit(id: string): Promise<UnitRecord | undefined>;
307
307
  connectRealtime(): Promise<void>;
308
+ /** A closed handle holds no socket, so its disconnect succeeds. */
308
309
  disconnectRealtime(): Promise<void>;
309
310
  /** §8.6: publish/clear a scope-keyed presence document. */
310
311
  setPresence(scopeKey: string, doc: Record<string, unknown> | null): Promise<void>;
@@ -451,7 +451,10 @@ export class SyncClientHandle {
451
451
  connectRealtime() {
452
452
  return this.#call('connectRealtime', []);
453
453
  }
454
+ /** A closed handle holds no socket, so its disconnect succeeds. */
454
455
  disconnectRealtime() {
456
+ if (this.#closed)
457
+ return Promise.resolve();
455
458
  return this.#call('disconnectRealtime', []);
456
459
  }
457
460
  /** §8.6: publish/clear a scope-keyed presence document. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.70.3",
3
+ "version": "0.71.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.70.3"
124
+ "@syncular/core": "0.71.0"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.70.3",
128
+ "@syncular/server": "0.71.0",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
@@ -417,6 +417,7 @@ export abstract class NativeBridgeClient implements PromiseMethods<
417
417
  'beginSecurityPreflight',
418
418
  'activateSecurity',
419
419
  'setTransportEnabled',
420
+ 'disconnectRealtime',
420
421
  'purgeLocalData',
421
422
  'previousVersionDiscard',
422
423
  'localRevision',
@@ -1177,7 +1178,9 @@ export abstract class NativeBridgeClient implements PromiseMethods<
1177
1178
  await this.command('connectRealtime', {});
1178
1179
  }
1179
1180
 
1181
+ /** A closed client holds no socket, so its disconnect succeeds. */
1180
1182
  async disconnectRealtime(): Promise<void> {
1183
+ if (this.#closed) return;
1181
1184
  await this.command('disconnectRealtime', {});
1182
1185
  }
1183
1186
 
@@ -48,12 +48,16 @@ export interface RealtimeSupervisorSnapshot {
48
48
  readonly retryDelayMs?: number;
49
49
  /** The latched failure of phase `unsupported` (or `stopped`). */
50
50
  readonly failureCode?: RealtimeSupervisorFailureCode;
51
+ /**
52
+ * The Syncular code (or `unknown`) the latest refused
53
+ * `disconnectRealtime()` rejected with, kept until the next `connected`.
54
+ */
55
+ readonly disconnectCauseCode?: string;
51
56
  }
52
57
 
53
58
  /** SPEC §10.3: client-local supervisor failures, never on the wire. */
54
59
  export type RealtimeSupervisorFailureCode =
55
60
  | 'realtime.diagnostics_unavailable'
56
- | 'realtime.disconnect_failed'
57
61
  | 'realtime.cleanup_failed';
58
62
 
59
63
  export interface RealtimeSupervisorOptions {
@@ -262,8 +266,6 @@ export class RealtimeSupervisorError extends ClientSyncError {
262
266
  declare readonly code: RealtimeSupervisorFailureCode;
263
267
  declare readonly cleanupFailureCode?: 'realtime.cleanup_failed';
264
268
  declare readonly diagnosticsFailureCode?: 'realtime.diagnostics_unavailable';
265
- /** The code the client's `disconnectRealtime` rejected with. */
266
- declare readonly disconnectCauseCode?: string;
267
269
  /** Set by the installed `close()` when the client close failed as well. */
268
270
  declare readonly stopFailureCode?: RealtimeSupervisorFailureCode;
269
271
  declare readonly closeFailureCode?: string;
@@ -285,8 +287,9 @@ export class RealtimeSupervisorError extends ClientSyncError {
285
287
  * exponential jitter, and the backoff survives offline, background and
286
288
  * protected suspensions. While no socket is connected, each failed connect,
287
289
  * each host `online` report and each foreground return drives one HTTP round
288
- * (§1.8). A disconnect, diagnostics or cleanup failure latches phase
289
- * `unsupported` with its `failureCode`, and `stop()` rejects with it.
290
+ * (§1.8). A refused disconnect counts one retry and names its cause in the
291
+ * snapshot. A diagnostics or cleanup failure latches phase `unsupported` with
292
+ * its `failureCode`, and `stop()` rejects with it.
290
293
  */
291
294
  export class RealtimeSupervisor {
292
295
  readonly #client: RealtimeSupervisorClient;
@@ -330,8 +333,8 @@ export class RealtimeSupervisor {
330
333
  readonly #failures: {
331
334
  cleanupFailureCode?: 'realtime.cleanup_failed';
332
335
  diagnosticsFailureCode?: 'realtime.diagnostics_unavailable';
333
- disconnectCauseCode?: string;
334
336
  } = {};
337
+ #disconnectCause: string | undefined;
335
338
  #snapshot: RealtimeSupervisorSnapshot = { phase: 'idle', attempt: 0 };
336
339
 
337
340
  constructor(
@@ -487,7 +490,11 @@ export class RealtimeSupervisor {
487
490
  });
488
491
  }
489
492
 
490
- #publish(snapshot: RealtimeSupervisorSnapshot): void {
493
+ #publish(next: RealtimeSupervisorSnapshot): void {
494
+ const snapshot =
495
+ this.#disconnectCause === undefined
496
+ ? next
497
+ : { ...next, disconnectCauseCode: this.#disconnectCause };
491
498
  if (JSON.stringify(this.#snapshot) === JSON.stringify(snapshot)) return;
492
499
  this.#snapshot = Object.freeze(snapshot);
493
500
  for (const listener of this.#listeners) {
@@ -639,6 +646,7 @@ export class RealtimeSupervisor {
639
646
  this.#connected = true;
640
647
  this.#attempt = 0;
641
648
  this.#delayMs = 0;
649
+ this.#disconnectCause = undefined;
642
650
  this.#publish({ phase: 'connected', attempt: 0 });
643
651
  return;
644
652
  }
@@ -674,9 +682,11 @@ export class RealtimeSupervisor {
674
682
  resolve(this.#client.disconnectRealtime()),
675
683
  )
676
684
  .catch((error: unknown) => {
677
- if (retryable(error)) return this.#retry();
678
- this.#failures.disconnectCauseCode = causeCode(error);
679
- this.#fail('realtime.disconnect_failed');
685
+ // The socket counts as released: one the client kept open reports
686
+ // `connected` in its diagnostics and is adopted after a catch-up.
687
+ this.#disconnectCause = causeCode(error);
688
+ this.#retry();
689
+ this.#publish(this.#snapshot);
680
690
  })
681
691
  .finally(() => {
682
692
  this.#disconnecting = undefined;
@@ -828,7 +828,9 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
828
828
  return this.#call('connectRealtime', []);
829
829
  }
830
830
 
831
+ /** A closed handle holds no socket, so its disconnect succeeds. */
831
832
  disconnectRealtime(): Promise<void> {
833
+ if (this.#closed) return Promise.resolve();
832
834
  return this.#call('disconnectRealtime', []);
833
835
  }
834
836