@syncular/client 0.65.1 → 0.65.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
@@ -150,17 +150,21 @@ installRealtimeSupervisor(handle, {
150
150
  });
151
151
  ```
152
152
 
153
- It owns one connection attempt, retries initial failure and later socket loss
154
- with bounded exponential jitter, suspends while offline/background/protected,
155
- runs `syncUntilIdle()` before reporting `connected`, and cancels before
156
- `close()`.
153
+ It owns one connection attempt at a time, retries initial failure and later
154
+ socket loss with bounded exponential jitter, suspends while
155
+ offline/background/protected without resetting that backoff, runs
156
+ `syncUntilIdle()` before reporting `connected`, and settles its attempt and
157
+ disconnect before `close()` closes the client. A failed disconnect, an
158
+ unreadable first diagnostics read, or a throwing timer cancel latches phase
159
+ `unsupported` with a `failureCode`, and `close()` rejects with a
160
+ `RealtimeSupervisorError` of that code.
157
161
 
158
162
  Multi-tab handles share ONE leader socket across every tab, so pass
159
163
  `sharedTransport: true` (the templates do): backgrounding this tab then
160
164
  leaves the shared socket alone — a sibling tab may still be visible — while
161
165
  offline and protection continue to suspend. Each client accepts exactly one
162
166
  supervisor for its lifetime; a second `installRealtimeSupervisor` call
163
- throws. `realtimeSupervisorSnapshot()` and
167
+ throws `realtime.supervisor_already_installed`. `realtimeSupervisorSnapshot()` and
164
168
  `subscribeRealtimeSupervisor()` expose only `phase`, `attempt`, and the bounded
165
169
  library delay for UI/diagnostics—never raw transport prose or identities.
166
170
 
@@ -1,5 +1,6 @@
1
1
  import type { SecurityLifecycle } from './client.js';
2
2
  import type { ClientDiagnosticsConnectivity, ClientDiagnosticsListener, ClientDiagnosticsSnapshot } from './diagnostics.js';
3
+ import { ClientSyncError } from './errors.js';
3
4
  type CancelTimer = () => void;
4
5
  export interface RealtimeSupervisorClient {
5
6
  connectRealtime(): Promise<void>;
@@ -23,13 +24,18 @@ export interface RealtimeSupervisorSnapshot {
23
24
  readonly attempt: number;
24
25
  /** Bounded host-policy delay, never server or transport prose. */
25
26
  readonly retryDelayMs?: number;
27
+ /** The latched failure of phase `unsupported` (or `stopped`). */
28
+ readonly failureCode?: RealtimeSupervisorFailureCode;
26
29
  }
30
+ /** SPEC §10.3: client-local supervisor failures, never on the wire. */
31
+ export type RealtimeSupervisorFailureCode = 'realtime.diagnostics_unavailable' | 'realtime.disconnect_failed' | 'realtime.cleanup_failed';
27
32
  export interface RealtimeSupervisorOptions {
28
33
  /**
29
34
  * Host online/offline evidence, the only connectivity the supervisor
30
35
  * trusts: a failed round does not suspend it. Unknown remains connectable
31
- * and observable. Each `online` report drives `syncUntilIdle`, so work a
32
- * failed round left behind resumes without realtime.
36
+ * and observable. Each `online` report drives `syncUntilIdle` while no
37
+ * socket is connected, so work a failed round left behind resumes without
38
+ * realtime.
33
39
  */
34
40
  readonly connectivity?: RealtimeSupervisorSignal<ClientDiagnosticsConnectivity>;
35
41
  /** Browser/native foreground evidence. Background suspends a tab-owned
@@ -73,12 +79,33 @@ export declare function browserConnectivitySignal(options?: BrowserConnectivityS
73
79
  /** Browser/Tauri-webview visibility evidence without importing DOM types. */
74
80
  export declare function documentLifecycleSignal(options?: DocumentLifecycleSignalOptions): RealtimeSupervisorSignal<RealtimeSupervisorLifecycleState>;
75
81
  /**
76
- * Supported host policy for Syncular's explicit realtime transport. It owns
77
- * exactly one connect attempt, runs an explicit catch-up round before claiming
78
- * connected, retries transient loss with bounded exponential jitter, and
79
- * suspends across offline, background, or protected-preflight state. Each
80
- * failed attempt, each host `online` report, and each foreground return
81
- * while no attempt starts at once drives one HTTP round (§1.8).
82
+ * SPEC §8.4: a supervisor failure. `code` is the latest latched failure, or
83
+ * `realtime.cleanup_failed` when only a cancel threw. Every failure of the
84
+ * lifetime is also named in its own field. Cause codes are Syncular codes or
85
+ * `unknown`; no message or original error is retained.
86
+ */
87
+ export declare class RealtimeSupervisorError extends ClientSyncError {
88
+ readonly name = "RealtimeSupervisorError";
89
+ readonly code: RealtimeSupervisorFailureCode;
90
+ readonly cleanupFailureCode?: 'realtime.cleanup_failed';
91
+ readonly diagnosticsFailureCode?: 'realtime.diagnostics_unavailable';
92
+ /** The code the client's `disconnectRealtime` rejected with. */
93
+ readonly disconnectCauseCode?: string;
94
+ /** Set by the installed `close()` when the client close failed as well. */
95
+ readonly stopFailureCode?: RealtimeSupervisorFailureCode;
96
+ readonly closeFailureCode?: string;
97
+ constructor(code: RealtimeSupervisorFailureCode, fields?: Omit<Partial<RealtimeSupervisorError>, 'code'>);
98
+ }
99
+ /**
100
+ * Supported host policy for Syncular's explicit realtime transport (§8.4). It
101
+ * owns one attempt at a time: a connect, then an explicit catch-up round
102
+ * before it claims connected. A successor never starts before the previous
103
+ * attempt and its disconnect settle. Transient loss retries with bounded
104
+ * exponential jitter, and the backoff survives offline, background and
105
+ * protected suspensions. While no socket is connected, each failed connect,
106
+ * 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.
82
109
  */
83
110
  export declare class RealtimeSupervisor {
84
111
  #private;
@@ -86,13 +113,20 @@ export declare class RealtimeSupervisor {
86
113
  snapshot(): RealtimeSupervisorSnapshot;
87
114
  subscribe(listener: () => void): () => void;
88
115
  start(): void;
89
- stop(): void;
116
+ /**
117
+ * Cancel the timer and every subscription, release the socket, and settle
118
+ * once the in-flight attempt, its disconnect and any driven round have
119
+ * settled. Rejects with a {@link RealtimeSupervisorError} when a failure
120
+ * latched during the lifetime or a cancel threw; every caller shares it.
121
+ */
122
+ stop(): Promise<void>;
90
123
  }
91
124
  /**
92
- * Install one supervisor and make client disposal cancel it before close.
93
- * A client accepts exactly one supervisor for its lifetime; installing a
94
- * second throws, because silently keeping the first would discard the second
95
- * call's options.
125
+ * Install one supervisor and make client disposal stop it before close.
126
+ * Repeated and reentrant `close()` calls share one operation. A client accepts
127
+ * exactly one supervisor for its lifetime; installing a second throws
128
+ * `realtime.supervisor_already_installed`, because silently keeping the first
129
+ * would discard the second call's options.
96
130
  */
97
131
  export declare function installRealtimeSupervisor<T extends RealtimeSupervisorClient>(client: T, options?: RealtimeSupervisorOptions): T;
98
132
  export declare function realtimeSupervisorSnapshot(client: object): RealtimeSupervisorSnapshot;