@syncular/client 0.67.2 → 0.67.3
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 +2 -1
- package/dist/worker-core.js +25 -24
- package/dist/worker-host.d.ts +6 -5
- package/dist/worker-host.js +3 -2
- package/dist/worker-protocol.d.ts +1 -1
- package/package.json +3 -3
- package/src/worker-core.ts +34 -21
- package/src/worker-host.ts +6 -5
- package/src/worker-protocol.ts +1 -1
package/README.md
CHANGED
|
@@ -87,7 +87,8 @@ 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
89
|
events for rendering in the leader tab; `handle.onSynced(listener)` reports the
|
|
90
|
-
end of each automatic
|
|
90
|
+
end of each drive to idle, automatic or requested by any tab, in every tab,
|
|
91
|
+
followers included.
|
|
91
92
|
|
|
92
93
|
For a reviewed recovery from a retained conflict or rejection, call
|
|
93
94
|
`await client.proveCurrentBase(outcome)`. The result contains bases for every
|
package/dist/worker-core.js
CHANGED
|
@@ -47,6 +47,11 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
47
47
|
let offline = false;
|
|
48
48
|
let headers = {};
|
|
49
49
|
let closed = false;
|
|
50
|
+
// Every worker event goes through here; a closed worker posts none.
|
|
51
|
+
const emit = (event) => {
|
|
52
|
+
if (!closed)
|
|
53
|
+
post({ t: 'event', event });
|
|
54
|
+
};
|
|
50
55
|
let pushingDiagnostics = false;
|
|
51
56
|
// -- one sync loop: RPC-driven and auto-driven rounds serialize ----------
|
|
52
57
|
let syncChain = Promise.resolve();
|
|
@@ -55,6 +60,17 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
55
60
|
syncChain = next.then(() => undefined, () => undefined);
|
|
56
61
|
return next;
|
|
57
62
|
}
|
|
63
|
+
/**
|
|
64
|
+
* One drive to idle, automatic or requested: its end reaches every tab.
|
|
65
|
+
* The event is posted inside the serialized step, so the drive settles
|
|
66
|
+
* before the next queued drive starts, as without it.
|
|
67
|
+
*/
|
|
68
|
+
function drive(run) {
|
|
69
|
+
return serializedSync(() => run().then((summary) => (emit({ kind: 'synced', summary }), summary), (error) => {
|
|
70
|
+
emit({ kind: 'synced', error: toErrorShape(error) });
|
|
71
|
+
throw error;
|
|
72
|
+
}));
|
|
73
|
+
}
|
|
58
74
|
// -- SPEC §7.5 host loop: event-driven intents, no interactive polling --
|
|
59
75
|
let autoSync = true;
|
|
60
76
|
let autoSyncScheduled = false;
|
|
@@ -73,14 +89,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
73
89
|
connectivity: offline ? 'offline' : snapshot.host.connectivity,
|
|
74
90
|
realtime: snapshot.host.realtime,
|
|
75
91
|
});
|
|
76
|
-
const postDiagnostics = (snapshot) => {
|
|
77
|
-
if (!closed) {
|
|
78
|
-
post({
|
|
79
|
-
t: 'event',
|
|
80
|
-
event: { kind: 'diagnostics', snapshot: workerDiagnostics(snapshot) },
|
|
81
|
-
});
|
|
82
|
-
}
|
|
83
|
-
};
|
|
92
|
+
const postDiagnostics = (snapshot) => emit({ kind: 'diagnostics', snapshot: workerDiagnostics(snapshot) });
|
|
84
93
|
function runAutoSync() {
|
|
85
94
|
if (closed ||
|
|
86
95
|
client === undefined ||
|
|
@@ -90,7 +99,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
90
99
|
return;
|
|
91
100
|
}
|
|
92
101
|
const running = client;
|
|
93
|
-
void
|
|
102
|
+
void drive(() => {
|
|
94
103
|
// The queued round owns the flag from here. Clearing it at entry would
|
|
95
104
|
// let every wake-up that arrives while this round waits behind the
|
|
96
105
|
// running one queue its own full drive (§8.4 coalescing).
|
|
@@ -99,18 +108,12 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
99
108
|
})
|
|
100
109
|
.then((summary) => {
|
|
101
110
|
retryDelayMs = 250;
|
|
102
|
-
if (!closed)
|
|
103
|
-
post({ t: 'event', event: { kind: 'synced', summary } });
|
|
104
111
|
if (summary.budgetExhausted)
|
|
105
112
|
consumeSyncIntent({ kind: 'interactive' });
|
|
106
113
|
})
|
|
107
114
|
.catch((error) => {
|
|
108
115
|
if (closed)
|
|
109
116
|
return;
|
|
110
|
-
post({
|
|
111
|
-
t: 'event',
|
|
112
|
-
event: { kind: 'synced', error: toErrorShape(error) },
|
|
113
|
-
});
|
|
114
117
|
// §7.8: a retryable drive rejection owes another drive. A retryable
|
|
115
118
|
// round failure already handed this loop its background intent; the
|
|
116
119
|
// drive deadline did not. An unreachable endpoint waits for the
|
|
@@ -282,29 +285,27 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
282
285
|
? { previousVersionContext: config.previousVersionContext }
|
|
283
286
|
: {}),
|
|
284
287
|
onSyncNeeded: (reason) => {
|
|
285
|
-
|
|
288
|
+
emit({ kind: 'sync-needed', reason });
|
|
286
289
|
consumeSyncIntent({ kind: 'interactive' });
|
|
287
290
|
},
|
|
288
291
|
onSyncIntent: consumeSyncIntent,
|
|
289
292
|
onConflict: (conflict) => {
|
|
290
|
-
|
|
293
|
+
emit({ kind: 'conflict', conflict });
|
|
291
294
|
},
|
|
292
295
|
onUpgrading: (upgrading) => {
|
|
293
296
|
// §7.4.5: surface the schema-bump reset + completion to the UI thread.
|
|
294
|
-
|
|
297
|
+
emit({ kind: 'upgrading', upgrading });
|
|
295
298
|
},
|
|
296
299
|
onPresence: (scopeKey, error) => {
|
|
297
300
|
// §8.6: surface a presence change or rejection to the UI thread.
|
|
298
|
-
|
|
301
|
+
emit({ kind: 'presence', scopeKey, error });
|
|
299
302
|
},
|
|
300
303
|
});
|
|
301
304
|
started.onProgress((progress) => {
|
|
302
|
-
|
|
303
|
-
post({ t: 'event', event: { kind: 'progress', progress } });
|
|
305
|
+
emit({ kind: 'progress', progress });
|
|
304
306
|
});
|
|
305
307
|
started.onChange((batch) => {
|
|
306
|
-
|
|
307
|
-
post({ t: 'event', event: { kind: 'change', batch } });
|
|
308
|
+
emit({ kind: 'change', batch });
|
|
308
309
|
});
|
|
309
310
|
await started.start();
|
|
310
311
|
realtimeConnector =
|
|
@@ -391,7 +392,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
391
392
|
},
|
|
392
393
|
syncUntilIdle: (options) => {
|
|
393
394
|
const running = requireClient();
|
|
394
|
-
return
|
|
395
|
+
return drive(() => running.syncUntilIdle(options));
|
|
395
396
|
},
|
|
396
397
|
proveCurrentBase: (outcome, options) => {
|
|
397
398
|
const running = requireClient();
|
package/dist/worker-host.d.ts
CHANGED
|
@@ -147,7 +147,7 @@ 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
|
-
/**
|
|
150
|
+
/** A drive to idle in the leader worker ended (leader tab only). */
|
|
151
151
|
readonly onSynced?: SyncedListener;
|
|
152
152
|
/** §7.4.5: schema-bump `upgrading` state changed (reset began/completed). */
|
|
153
153
|
readonly onUpgrading?: (upgrading: boolean) => void;
|
|
@@ -158,8 +158,8 @@ export interface SyncClientHandleConfig {
|
|
|
158
158
|
readonly onDiagnostics?: (snapshot: ClientDiagnosticsSnapshot) => void;
|
|
159
159
|
}
|
|
160
160
|
/**
|
|
161
|
-
* The end of one
|
|
162
|
-
* summary, or the error it failed with.
|
|
161
|
+
* The end of one `syncUntilIdle` drive in the leader worker, automatic or
|
|
162
|
+
* requested by any tab: its summary, or the error it failed with.
|
|
163
163
|
*/
|
|
164
164
|
export type SyncedListener = (result: {
|
|
165
165
|
readonly summary?: SyncSummary;
|
|
@@ -231,8 +231,9 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
231
231
|
*/
|
|
232
232
|
onPresence(listener: (scopeKey: string, error?: PresenceErrorCode) => void): () => void;
|
|
233
233
|
/**
|
|
234
|
-
* Subscribe to the end of every
|
|
235
|
-
* worker, in leader and follower tabs
|
|
234
|
+
* Subscribe to the end of every drive to idle (automatic or requested by
|
|
235
|
+
* any tab) in the current leader's worker, in leader and follower tabs
|
|
236
|
+
* alike. A follower receives only the
|
|
236
237
|
* drives of the leader it is bound to; a drive that ended before this tab
|
|
237
238
|
* bound is not replayed. Returns an unsubscribe function.
|
|
238
239
|
*/
|
package/dist/worker-host.js
CHANGED
|
@@ -263,8 +263,9 @@ export class SyncClientHandle {
|
|
|
263
263
|
};
|
|
264
264
|
}
|
|
265
265
|
/**
|
|
266
|
-
* Subscribe to the end of every
|
|
267
|
-
* worker, in leader and follower tabs
|
|
266
|
+
* Subscribe to the end of every drive to idle (automatic or requested by
|
|
267
|
+
* any tab) in the current leader's worker, in leader and follower tabs
|
|
268
|
+
* alike. A follower receives only the
|
|
268
269
|
* drives of the leader it is bound to; a drive that ended before this tab
|
|
269
270
|
* bound is not replayed. Returns an unsubscribe function.
|
|
270
271
|
*/
|
|
@@ -225,7 +225,7 @@ export type SyncWorkerEvent = {
|
|
|
225
225
|
readonly kind: 'conflict';
|
|
226
226
|
readonly conflict: ConflictRecord;
|
|
227
227
|
} | {
|
|
228
|
-
/**
|
|
228
|
+
/** A drive to idle (automatic or requested) finished or failed inside the worker. */
|
|
229
229
|
readonly kind: 'synced';
|
|
230
230
|
readonly summary?: SyncSummary;
|
|
231
231
|
readonly error?: WorkerErrorShape;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/client",
|
|
3
|
-
"version": "0.67.
|
|
3
|
+
"version": "0.67.3",
|
|
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.
|
|
124
|
+
"@syncular/core": "0.67.3"
|
|
125
125
|
},
|
|
126
126
|
"devDependencies": {
|
|
127
127
|
"@electric-sql/pglite": "^0.5.4",
|
|
128
|
-
"@syncular/server": "0.67.
|
|
128
|
+
"@syncular/server": "0.67.3",
|
|
129
129
|
"playwright": "1.63.0",
|
|
130
130
|
"vite": "8.3.4"
|
|
131
131
|
}
|
package/src/worker-core.ts
CHANGED
|
@@ -48,6 +48,7 @@ import {
|
|
|
48
48
|
WORKER_FAILED_CODE,
|
|
49
49
|
WORKER_METHOD_UNAVAILABLE_CODE,
|
|
50
50
|
type WorkerApi,
|
|
51
|
+
type SyncWorkerEvent,
|
|
51
52
|
type WorkerCallMessage,
|
|
52
53
|
type WorkerInitConfig,
|
|
53
54
|
type WorkerInitResult,
|
|
@@ -196,6 +197,10 @@ export function startSyncWorkerCore(
|
|
|
196
197
|
let offline = false;
|
|
197
198
|
let headers: Readonly<Record<string, string>> = {};
|
|
198
199
|
let closed = false;
|
|
200
|
+
// Every worker event goes through here; a closed worker posts none.
|
|
201
|
+
const emit = (event: SyncWorkerEvent): void => {
|
|
202
|
+
if (!closed) post({ t: 'event', event });
|
|
203
|
+
};
|
|
199
204
|
let pushingDiagnostics = false;
|
|
200
205
|
|
|
201
206
|
// -- one sync loop: RPC-driven and auto-driven rounds serialize ----------
|
|
@@ -209,6 +214,25 @@ export function startSyncWorkerCore(
|
|
|
209
214
|
return next;
|
|
210
215
|
}
|
|
211
216
|
|
|
217
|
+
/**
|
|
218
|
+
* One drive to idle, automatic or requested: its end reaches every tab.
|
|
219
|
+
* The event is posted inside the serialized step, so the drive settles
|
|
220
|
+
* before the next queued drive starts, as without it.
|
|
221
|
+
*/
|
|
222
|
+
function drive(
|
|
223
|
+
run: () => ReturnType<SyncClient['syncUntilIdle']>,
|
|
224
|
+
): ReturnType<SyncClient['syncUntilIdle']> {
|
|
225
|
+
return serializedSync(() =>
|
|
226
|
+
run().then(
|
|
227
|
+
(summary) => (emit({ kind: 'synced', summary }), summary),
|
|
228
|
+
(error: unknown) => {
|
|
229
|
+
emit({ kind: 'synced', error: toErrorShape(error) });
|
|
230
|
+
throw error;
|
|
231
|
+
},
|
|
232
|
+
),
|
|
233
|
+
);
|
|
234
|
+
}
|
|
235
|
+
|
|
212
236
|
// -- SPEC §7.5 host loop: event-driven intents, no interactive polling --
|
|
213
237
|
let autoSync = true;
|
|
214
238
|
let autoSyncScheduled = false;
|
|
@@ -230,14 +254,8 @@ export function startSyncWorkerCore(
|
|
|
230
254
|
connectivity: offline ? 'offline' : snapshot.host.connectivity,
|
|
231
255
|
realtime: snapshot.host.realtime,
|
|
232
256
|
});
|
|
233
|
-
const postDiagnostics = (snapshot: ClientDiagnosticsSnapshot): void =>
|
|
234
|
-
|
|
235
|
-
post({
|
|
236
|
-
t: 'event',
|
|
237
|
-
event: { kind: 'diagnostics', snapshot: workerDiagnostics(snapshot) },
|
|
238
|
-
});
|
|
239
|
-
}
|
|
240
|
-
};
|
|
257
|
+
const postDiagnostics = (snapshot: ClientDiagnosticsSnapshot): void =>
|
|
258
|
+
emit({ kind: 'diagnostics', snapshot: workerDiagnostics(snapshot) });
|
|
241
259
|
|
|
242
260
|
function runAutoSync(): void {
|
|
243
261
|
if (
|
|
@@ -250,7 +268,7 @@ export function startSyncWorkerCore(
|
|
|
250
268
|
return;
|
|
251
269
|
}
|
|
252
270
|
const running = client;
|
|
253
|
-
void
|
|
271
|
+
void drive(() => {
|
|
254
272
|
// The queued round owns the flag from here. Clearing it at entry would
|
|
255
273
|
// let every wake-up that arrives while this round waits behind the
|
|
256
274
|
// running one queue its own full drive (§8.4 coalescing).
|
|
@@ -259,15 +277,10 @@ export function startSyncWorkerCore(
|
|
|
259
277
|
})
|
|
260
278
|
.then((summary) => {
|
|
261
279
|
retryDelayMs = 250;
|
|
262
|
-
if (!closed) post({ t: 'event', event: { kind: 'synced', summary } });
|
|
263
280
|
if (summary.budgetExhausted) consumeSyncIntent({ kind: 'interactive' });
|
|
264
281
|
})
|
|
265
282
|
.catch((error: unknown) => {
|
|
266
283
|
if (closed) return;
|
|
267
|
-
post({
|
|
268
|
-
t: 'event',
|
|
269
|
-
event: { kind: 'synced', error: toErrorShape(error) },
|
|
270
|
-
});
|
|
271
284
|
// §7.8: a retryable drive rejection owes another drive. A retryable
|
|
272
285
|
// round failure already handed this loop its background intent; the
|
|
273
286
|
// drive deadline did not. An unreachable endpoint waits for the
|
|
@@ -470,27 +483,27 @@ export function startSyncWorkerCore(
|
|
|
470
483
|
? { previousVersionContext: config.previousVersionContext }
|
|
471
484
|
: {}),
|
|
472
485
|
onSyncNeeded: (reason) => {
|
|
473
|
-
|
|
486
|
+
emit({ kind: 'sync-needed', reason });
|
|
474
487
|
consumeSyncIntent({ kind: 'interactive' });
|
|
475
488
|
},
|
|
476
489
|
onSyncIntent: consumeSyncIntent,
|
|
477
490
|
onConflict: (conflict) => {
|
|
478
|
-
|
|
491
|
+
emit({ kind: 'conflict', conflict });
|
|
479
492
|
},
|
|
480
493
|
onUpgrading: (upgrading) => {
|
|
481
494
|
// §7.4.5: surface the schema-bump reset + completion to the UI thread.
|
|
482
|
-
|
|
495
|
+
emit({ kind: 'upgrading', upgrading });
|
|
483
496
|
},
|
|
484
497
|
onPresence: (scopeKey, error) => {
|
|
485
498
|
// §8.6: surface a presence change or rejection to the UI thread.
|
|
486
|
-
|
|
499
|
+
emit({ kind: 'presence', scopeKey, error });
|
|
487
500
|
},
|
|
488
501
|
});
|
|
489
502
|
started.onProgress((progress) => {
|
|
490
|
-
|
|
503
|
+
emit({ kind: 'progress', progress });
|
|
491
504
|
});
|
|
492
505
|
started.onChange((batch) => {
|
|
493
|
-
|
|
506
|
+
emit({ kind: 'change', batch });
|
|
494
507
|
});
|
|
495
508
|
await started.start();
|
|
496
509
|
realtimeConnector =
|
|
@@ -585,7 +598,7 @@ export function startSyncWorkerCore(
|
|
|
585
598
|
},
|
|
586
599
|
syncUntilIdle: (options) => {
|
|
587
600
|
const running = requireClient();
|
|
588
|
-
return
|
|
601
|
+
return drive(() => running.syncUntilIdle(options));
|
|
589
602
|
},
|
|
590
603
|
proveCurrentBase: (outcome, options) => {
|
|
591
604
|
const running = requireClient();
|
package/src/worker-host.ts
CHANGED
|
@@ -260,7 +260,7 @@ 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
|
-
/**
|
|
263
|
+
/** A drive to idle in the leader worker ended (leader tab only). */
|
|
264
264
|
readonly onSynced?: SyncedListener;
|
|
265
265
|
/** §7.4.5: schema-bump `upgrading` state changed (reset began/completed). */
|
|
266
266
|
readonly onUpgrading?: (upgrading: boolean) => void;
|
|
@@ -272,8 +272,8 @@ export interface SyncClientHandleConfig {
|
|
|
272
272
|
}
|
|
273
273
|
|
|
274
274
|
/**
|
|
275
|
-
* The end of one
|
|
276
|
-
* summary, or the error it failed with.
|
|
275
|
+
* The end of one `syncUntilIdle` drive in the leader worker, automatic or
|
|
276
|
+
* requested by any tab: its summary, or the error it failed with.
|
|
277
277
|
*/
|
|
278
278
|
export type SyncedListener = (result: {
|
|
279
279
|
readonly summary?: SyncSummary;
|
|
@@ -532,8 +532,9 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
532
532
|
}
|
|
533
533
|
|
|
534
534
|
/**
|
|
535
|
-
* Subscribe to the end of every
|
|
536
|
-
* worker, in leader and follower tabs
|
|
535
|
+
* Subscribe to the end of every drive to idle (automatic or requested by
|
|
536
|
+
* any tab) in the current leader's worker, in leader and follower tabs
|
|
537
|
+
* alike. A follower receives only the
|
|
537
538
|
* drives of the leader it is bound to; a drive that ended before this tab
|
|
538
539
|
* bound is not replayed. Returns an unsubscribe function.
|
|
539
540
|
*/
|
package/src/worker-protocol.ts
CHANGED
|
@@ -290,7 +290,7 @@ export type SyncWorkerEvent =
|
|
|
290
290
|
}
|
|
291
291
|
| { readonly kind: 'conflict'; readonly conflict: ConflictRecord }
|
|
292
292
|
| {
|
|
293
|
-
/**
|
|
293
|
+
/** A drive to idle (automatic or requested) finished or failed inside the worker. */
|
|
294
294
|
readonly kind: 'synced';
|
|
295
295
|
readonly summary?: SyncSummary;
|
|
296
296
|
readonly error?: WorkerErrorShape;
|