@syncular/client 0.64.0 → 0.65.1
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 +1 -0
- package/dist/dev-profiler.d.ts +127 -0
- package/dist/dev-profiler.js +338 -0
- package/dist/devtools.d.ts +5 -0
- package/dist/devtools.js +13 -10
- package/dist/realtime-supervisor.d.ts +3 -3
- package/dist/realtime-supervisor.js +58 -72
- package/dist/worker-core.d.ts +4 -1
- package/dist/worker-core.js +2 -3
- package/package.json +11 -3
- package/src/dev-profiler.ts +525 -0
- package/src/devtools.ts +17 -14
- package/src/realtime-supervisor.ts +66 -84
- package/src/worker-core.ts +7 -4
|
@@ -104,9 +104,9 @@ export function documentLifecycleSignal(options = {}) {
|
|
|
104
104
|
* Supported host policy for Syncular's explicit realtime transport. It owns
|
|
105
105
|
* exactly one connect attempt, runs an explicit catch-up round before claiming
|
|
106
106
|
* connected, retries transient loss with bounded exponential jitter, and
|
|
107
|
-
* suspends across offline, background, or protected-preflight state.
|
|
108
|
-
*
|
|
109
|
-
*
|
|
107
|
+
* suspends across offline, background, or protected-preflight state. Each
|
|
108
|
+
* failed attempt, each host `online` report, and each foreground return
|
|
109
|
+
* while no attempt starts at once drives one HTTP round (§1.8).
|
|
110
110
|
*/
|
|
111
111
|
export class RealtimeSupervisor {
|
|
112
112
|
#client;
|
|
@@ -160,18 +160,21 @@ export class RealtimeSupervisor {
|
|
|
160
160
|
return;
|
|
161
161
|
this.#started = true;
|
|
162
162
|
this.#unsubscribeDiagnostics = this.#client.onDiagnostics((snapshot) => this.#observeDiagnostics(snapshot));
|
|
163
|
-
this.#unsubscribeConnectivity = this.#connectivity?.subscribe(() => {
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
// socket that cannot connect does not hold back an HTTP round.
|
|
167
|
-
if (this.#connectivity?.current() === 'online' && !this.#hostBlock()) {
|
|
168
|
-
void Promise.resolve()
|
|
169
|
-
.then(() => this.#client.syncUntilIdle())
|
|
170
|
-
.catch(() => undefined);
|
|
171
|
-
}
|
|
163
|
+
this.#unsubscribeConnectivity = this.#connectivity?.subscribe((state) => {
|
|
164
|
+
if (state === 'online')
|
|
165
|
+
this.#drive();
|
|
172
166
|
this.#reconcileHostState();
|
|
173
167
|
});
|
|
174
|
-
this.#unsubscribeLifecycle = this.#lifecycle?.subscribe(() =>
|
|
168
|
+
this.#unsubscribeLifecycle = this.#lifecycle?.subscribe((state) => {
|
|
169
|
+
this.#reconcileHostState();
|
|
170
|
+
// An immediate attempt brings its own round; a pending retry or an
|
|
171
|
+
// absent socket does not.
|
|
172
|
+
const phase = this.#snapshot.phase;
|
|
173
|
+
if (state === 'active' &&
|
|
174
|
+
(phase === 'retrying' || phase === 'unsupported')) {
|
|
175
|
+
this.#drive();
|
|
176
|
+
}
|
|
177
|
+
});
|
|
175
178
|
this.#unsubscribeProtection = this.#protection?.subscribe(() => this.#reconcileHostState());
|
|
176
179
|
this.#reconcileHostState();
|
|
177
180
|
const generation = this.#generation;
|
|
@@ -181,21 +184,12 @@ export class RealtimeSupervisor {
|
|
|
181
184
|
if (this.#stopped)
|
|
182
185
|
return;
|
|
183
186
|
this.#stopped = true;
|
|
184
|
-
this.#
|
|
185
|
-
const disconnect = this.#connected || this.#transportConnected || this.#connecting;
|
|
186
|
-
this.#connected = false;
|
|
187
|
-
this.#transportConnected = false;
|
|
188
|
-
this.#connecting = false;
|
|
189
|
-
this.#attempt = 0;
|
|
190
|
-
this.#clearRetry();
|
|
187
|
+
this.#suspend('stopped');
|
|
191
188
|
this.#unsubscribeDiagnostics?.();
|
|
192
189
|
this.#unsubscribeConnectivity?.();
|
|
193
190
|
this.#unsubscribeLifecycle?.();
|
|
194
191
|
this.#unsubscribeProtection?.();
|
|
195
|
-
this.#publish({ phase: 'stopped', attempt: 0 });
|
|
196
192
|
this.#listeners.clear();
|
|
197
|
-
if (disconnect)
|
|
198
|
-
this.#disconnect();
|
|
199
193
|
}
|
|
200
194
|
async #initialize(generation) {
|
|
201
195
|
let snapshot;
|
|
@@ -230,6 +224,18 @@ export class RealtimeSupervisor {
|
|
|
230
224
|
}
|
|
231
225
|
return undefined;
|
|
232
226
|
}
|
|
227
|
+
/**
|
|
228
|
+
* §1.8: one HTTP round that re-arms the drive a refused fetch left behind.
|
|
229
|
+
* It does not wait for the socket, so a socket that cannot connect does not
|
|
230
|
+
* hold back the round.
|
|
231
|
+
*/
|
|
232
|
+
#drive() {
|
|
233
|
+
if (this.#hostBlock())
|
|
234
|
+
return;
|
|
235
|
+
void Promise.resolve()
|
|
236
|
+
.then(() => this.#client.syncUntilIdle())
|
|
237
|
+
.catch(() => undefined);
|
|
238
|
+
}
|
|
233
239
|
#canConnect() {
|
|
234
240
|
return (this.#initialized &&
|
|
235
241
|
!this.#stopped &&
|
|
@@ -256,14 +262,26 @@ export class RealtimeSupervisor {
|
|
|
256
262
|
this.#cancelRetry?.();
|
|
257
263
|
this.#cancelRetry = undefined;
|
|
258
264
|
}
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
this.#
|
|
263
|
-
|
|
265
|
+
/** A retry counts one attempt and backs off with bounded jitter. */
|
|
266
|
+
#schedule(retry) {
|
|
267
|
+
if (!this.#canConnect())
|
|
268
|
+
return this.#reconcileHostState();
|
|
269
|
+
// Count an attempt only when this call actually schedules one. Repeated
|
|
270
|
+
// 'disconnected' diagnostics beside a pending retry keep the backoff and
|
|
271
|
+
// the worker-mode reconnect nudge intact.
|
|
272
|
+
if (this.#connected || this.#connecting || this.#cancelRetry)
|
|
264
273
|
return;
|
|
274
|
+
let delayMs = 0;
|
|
275
|
+
if (retry) {
|
|
276
|
+
const exponential = Math.min(this.#maximumDelayMs, this.#initialDelayMs * 2 ** this.#attempt);
|
|
277
|
+
const random = this.#random();
|
|
278
|
+
const boundedRandom = Number.isFinite(random)
|
|
279
|
+
? Math.max(0, Math.min(1, random))
|
|
280
|
+
: 0;
|
|
281
|
+
delayMs = Math.min(this.#maximumDelayMs, exponential + Math.floor(exponential * 0.25 * boundedRandom));
|
|
282
|
+
this.#attempt = Math.min(32, this.#attempt + 1);
|
|
265
283
|
}
|
|
266
|
-
this.#publish(
|
|
284
|
+
this.#publish(retry
|
|
267
285
|
? { phase: 'retrying', attempt: this.#attempt, retryDelayMs: delayMs }
|
|
268
286
|
: { phase: 'connecting', attempt: this.#attempt });
|
|
269
287
|
this.#cancelRetry = this.#scheduleTimer(() => {
|
|
@@ -271,32 +289,6 @@ export class RealtimeSupervisor {
|
|
|
271
289
|
void this.#connect();
|
|
272
290
|
}, delayMs);
|
|
273
291
|
}
|
|
274
|
-
#retryDelay() {
|
|
275
|
-
const exponential = Math.min(this.#maximumDelayMs, this.#initialDelayMs * 2 ** this.#attempt);
|
|
276
|
-
const random = this.#random();
|
|
277
|
-
const boundedRandom = Number.isFinite(random)
|
|
278
|
-
? Math.max(0, Math.min(1, random))
|
|
279
|
-
: 0;
|
|
280
|
-
const jitter = Math.floor(exponential * 0.25 * boundedRandom);
|
|
281
|
-
return Math.min(this.#maximumDelayMs, exponential + jitter);
|
|
282
|
-
}
|
|
283
|
-
#scheduleRetry() {
|
|
284
|
-
if (!this.#canConnect()) {
|
|
285
|
-
this.#reconcileHostState();
|
|
286
|
-
return;
|
|
287
|
-
}
|
|
288
|
-
// Count an attempt only when this call actually schedules one. Repeated
|
|
289
|
-
// 'disconnected' diagnostics beside a pending retry keep the backoff and
|
|
290
|
-
// the worker-mode reconnect nudge intact.
|
|
291
|
-
if (this.#connected ||
|
|
292
|
-
this.#connecting ||
|
|
293
|
-
this.#cancelRetry !== undefined) {
|
|
294
|
-
return;
|
|
295
|
-
}
|
|
296
|
-
const delay = this.#retryDelay();
|
|
297
|
-
this.#attempt = Math.min(32, this.#attempt + 1);
|
|
298
|
-
this.#schedule(delay);
|
|
299
|
-
}
|
|
300
292
|
/**
|
|
301
293
|
* A superseded attempt observed a generation bump mid-flight. Whenever a
|
|
302
294
|
* newer generation is mid-connect or holds the transport, that generation
|
|
@@ -350,8 +342,10 @@ export class RealtimeSupervisor {
|
|
|
350
342
|
if (generation === this.#generation)
|
|
351
343
|
this.#connecting = false;
|
|
352
344
|
}
|
|
353
|
-
if (failed && generation === this.#generation)
|
|
354
|
-
this.#
|
|
345
|
+
if (failed && generation === this.#generation) {
|
|
346
|
+
this.#schedule(true);
|
|
347
|
+
this.#drive();
|
|
348
|
+
}
|
|
355
349
|
}
|
|
356
350
|
async #catchUpConnectedTransport(generation) {
|
|
357
351
|
await this.#client.syncUntilIdle();
|
|
@@ -395,7 +389,7 @@ export class RealtimeSupervisor {
|
|
|
395
389
|
this.#connecting = false;
|
|
396
390
|
}
|
|
397
391
|
if (failed && generation === this.#generation)
|
|
398
|
-
this.#
|
|
392
|
+
this.#schedule(true);
|
|
399
393
|
}
|
|
400
394
|
#observeDiagnostics(snapshot, initial = false) {
|
|
401
395
|
if (this.#stopped)
|
|
@@ -403,16 +397,8 @@ export class RealtimeSupervisor {
|
|
|
403
397
|
this.#diagnosticSecurity = snapshot.securityLifecycle;
|
|
404
398
|
if (snapshot.host.realtime === 'unsupported' ||
|
|
405
399
|
snapshot.host.realtime === 'disabled') {
|
|
406
|
-
const disconnect = this.#connected || this.#transportConnected || this.#connecting;
|
|
407
400
|
this.#realtimeSupported = false;
|
|
408
|
-
this.#
|
|
409
|
-
this.#connected = false;
|
|
410
|
-
this.#transportConnected = false;
|
|
411
|
-
this.#attempt = 0;
|
|
412
|
-
this.#clearRetry();
|
|
413
|
-
this.#publish({ phase: 'unsupported', attempt: 0 });
|
|
414
|
-
if (disconnect)
|
|
415
|
-
this.#disconnect();
|
|
401
|
+
this.#suspend('unsupported');
|
|
416
402
|
return;
|
|
417
403
|
}
|
|
418
404
|
if (!this.#realtimeSupported) {
|
|
@@ -460,7 +446,7 @@ export class RealtimeSupervisor {
|
|
|
460
446
|
if (this.#connecting)
|
|
461
447
|
return;
|
|
462
448
|
if (this.#initialized && !initial)
|
|
463
|
-
this.#
|
|
449
|
+
this.#schedule(true);
|
|
464
450
|
return;
|
|
465
451
|
}
|
|
466
452
|
this.#reconcileHostState();
|
|
@@ -485,14 +471,14 @@ export class RealtimeSupervisor {
|
|
|
485
471
|
this.#publish({ phase: 'connected', attempt: 0 });
|
|
486
472
|
return;
|
|
487
473
|
}
|
|
488
|
-
this.#schedule(
|
|
474
|
+
this.#schedule(false);
|
|
489
475
|
}
|
|
476
|
+
/** Cancel every attempt and release the socket, then publish `phase`. */
|
|
490
477
|
#suspend(phase) {
|
|
491
478
|
const disconnect = this.#connected || this.#transportConnected || this.#connecting;
|
|
492
|
-
|
|
493
|
-
const phaseChanged = this.#snapshot.phase !== phase;
|
|
494
|
-
if (!disconnect && !hadScheduledWork && !phaseChanged)
|
|
479
|
+
if (!disconnect && !this.#cancelRetry && this.#snapshot.phase === phase) {
|
|
495
480
|
return;
|
|
481
|
+
}
|
|
496
482
|
this.#generation += 1;
|
|
497
483
|
this.#connected = false;
|
|
498
484
|
this.#transportConnected = false;
|
package/dist/worker-core.d.ts
CHANGED
|
@@ -31,7 +31,10 @@ export interface SyncWorkerOverrides {
|
|
|
31
31
|
* deadlines and the client's §8.5 heartbeat watchdog.
|
|
32
32
|
*/
|
|
33
33
|
readonly scheduleBackground?: (callback: () => void, delayMs: number) => () => void;
|
|
34
|
-
|
|
34
|
+
/** `http` reads the current host auth set, as the default transport does. */
|
|
35
|
+
readonly createTransport?: (config: WorkerInitConfig, http: {
|
|
36
|
+
readonly headers: () => Readonly<Record<string, string>>;
|
|
37
|
+
}) => SyncTransport;
|
|
35
38
|
readonly createSegments?: (config: WorkerInitConfig) => SegmentDownloader | undefined;
|
|
36
39
|
/**
|
|
37
40
|
* Custom realtime connector, e.g. one that mints a fresh ticket per
|
package/dist/worker-core.js
CHANGED
|
@@ -220,7 +220,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
220
220
|
}
|
|
221
221
|
}
|
|
222
222
|
const remote = overrides.createTransport !== undefined
|
|
223
|
-
? overrides.createTransport(config)
|
|
223
|
+
? overrides.createTransport(config, http)
|
|
224
224
|
: httpSyncTransport(config.endpoints.syncUrl, http);
|
|
225
225
|
const remoteSegments = overrides.createSegments !== undefined
|
|
226
226
|
? overrides.createSegments(config)
|
|
@@ -485,8 +485,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
485
485
|
}
|
|
486
486
|
async function defaultOpenDatabase(config) {
|
|
487
487
|
if (config.database.mode !== 'persistent') {
|
|
488
|
-
throw new ClientSyncError(WORKER_FAILED_CODE, "database mode 'custom' requires
|
|
489
|
-
'worker bootstrap (startSyncWorker({ openDatabase }))');
|
|
488
|
+
throw new ClientSyncError(WORKER_FAILED_CODE, "database mode 'custom' requires startSyncWorker({ openDatabase })");
|
|
490
489
|
}
|
|
491
490
|
return openPersistentWasmDatabase(config.database.name, {
|
|
492
491
|
...(config.database.directory !== undefined
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/client",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.65.1",
|
|
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",
|
|
@@ -97,6 +97,14 @@
|
|
|
97
97
|
"types": "./dist/native-bridge.d.ts",
|
|
98
98
|
"default": "./dist/native-bridge.js"
|
|
99
99
|
}
|
|
100
|
+
},
|
|
101
|
+
"./dev": {
|
|
102
|
+
"bun": "./src/dev-profiler.ts",
|
|
103
|
+
"browser": "./dist/dev-profiler.js",
|
|
104
|
+
"import": {
|
|
105
|
+
"types": "./dist/dev-profiler.d.ts",
|
|
106
|
+
"default": "./dist/dev-profiler.js"
|
|
107
|
+
}
|
|
100
108
|
}
|
|
101
109
|
},
|
|
102
110
|
"files": [
|
|
@@ -113,11 +121,11 @@
|
|
|
113
121
|
},
|
|
114
122
|
"dependencies": {
|
|
115
123
|
"@sqlite.org/sqlite-wasm": "^3.53.0-build1",
|
|
116
|
-
"@syncular/core": "0.
|
|
124
|
+
"@syncular/core": "0.65.1"
|
|
117
125
|
},
|
|
118
126
|
"devDependencies": {
|
|
119
127
|
"@electric-sql/pglite": "^0.5.4",
|
|
120
|
-
"@syncular/server": "0.
|
|
128
|
+
"@syncular/server": "0.65.1",
|
|
121
129
|
"playwright": "1.63.0",
|
|
122
130
|
"vite": "8.3.4"
|
|
123
131
|
}
|