@syncular/client 0.67.1 → 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 +3 -1
- package/dist/worker-core.js +25 -24
- package/dist/worker-host.d.ts +18 -5
- package/dist/worker-host.js +31 -4
- 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 +44 -9
- package/src/worker-protocol.ts +1 -1
package/README.md
CHANGED
|
@@ -86,7 +86,9 @@ acquires the Web Locks leader lock *before* spawning the worker — one
|
|
|
86
86
|
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
|
-
events for rendering.
|
|
89
|
+
events for rendering in the leader tab; `handle.onSynced(listener)` reports the
|
|
90
|
+
end of each drive to idle, automatic or requested by any tab, in every tab,
|
|
91
|
+
followers included.
|
|
90
92
|
|
|
91
93
|
For a reviewed recovery from a retained conflict or rejection, call
|
|
92
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,11 +147,8 @@ 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
|
-
/** A
|
|
151
|
-
readonly onSynced?:
|
|
152
|
-
readonly summary?: SyncSummary;
|
|
153
|
-
readonly error?: WorkerErrorShape;
|
|
154
|
-
}) => void;
|
|
150
|
+
/** A drive to idle in the leader worker ended (leader tab only). */
|
|
151
|
+
readonly onSynced?: SyncedListener;
|
|
155
152
|
/** §7.4.5: schema-bump `upgrading` state changed (reset began/completed). */
|
|
156
153
|
readonly onUpgrading?: (upgrading: boolean) => void;
|
|
157
154
|
/** §8.6: presence on a scope key changed, or the server refused this
|
|
@@ -160,6 +157,14 @@ export interface SyncClientHandleConfig {
|
|
|
160
157
|
/** Atomic privacy-safe diagnostics changed. */
|
|
161
158
|
readonly onDiagnostics?: (snapshot: ClientDiagnosticsSnapshot) => void;
|
|
162
159
|
}
|
|
160
|
+
/**
|
|
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
|
+
*/
|
|
164
|
+
export type SyncedListener = (result: {
|
|
165
|
+
readonly summary?: SyncSummary;
|
|
166
|
+
readonly error?: WorkerErrorShape;
|
|
167
|
+
}) => void;
|
|
163
168
|
/**
|
|
164
169
|
* A running worker core owned by THIS tab (the leader). Wraps the worker and
|
|
165
170
|
* the RPC pending map. Torn down on `close()` or on a graceful demotion.
|
|
@@ -225,6 +230,14 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
225
230
|
* `SyncClient.onPresence`. Returns an unsubscribe function.
|
|
226
231
|
*/
|
|
227
232
|
onPresence(listener: (scopeKey: string, error?: PresenceErrorCode) => void): () => void;
|
|
233
|
+
/**
|
|
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
|
|
237
|
+
* drives of the leader it is bound to; a drive that ended before this tab
|
|
238
|
+
* bound is not replayed. Returns an unsubscribe function.
|
|
239
|
+
*/
|
|
240
|
+
onSynced(listener: SyncedListener): () => void;
|
|
228
241
|
/** Subscribe to role transitions (follower → leader on promotion). */
|
|
229
242
|
onRoleChange(listener: (role: HandleRole) => void): () => void;
|
|
230
243
|
onLeadershipChange(listener: (state: LeadershipState) => void): () => void;
|
package/dist/worker-host.js
CHANGED
|
@@ -96,6 +96,7 @@ export class SyncClientHandle {
|
|
|
96
96
|
#core;
|
|
97
97
|
#invalidation;
|
|
98
98
|
#progress = new ProgressEmitter();
|
|
99
|
+
#synced = new Set();
|
|
99
100
|
#changes;
|
|
100
101
|
#presence;
|
|
101
102
|
#diagnostics;
|
|
@@ -202,6 +203,16 @@ export class SyncClientHandle {
|
|
|
202
203
|
if (legacy !== undefined)
|
|
203
204
|
this.#invalidation.emit(legacy);
|
|
204
205
|
}
|
|
206
|
+
else if (event.kind === 'synced') {
|
|
207
|
+
for (const listener of this.#synced) {
|
|
208
|
+
try {
|
|
209
|
+
listener(syncedResult(event));
|
|
210
|
+
}
|
|
211
|
+
catch {
|
|
212
|
+
/* a UI listener must never break event dispatch */
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
}
|
|
205
216
|
else if (event.kind === 'diagnostics') {
|
|
206
217
|
this.#diagnostics.emit(withClientDiagnosticsHost(event.snapshot, {
|
|
207
218
|
...event.snapshot.host,
|
|
@@ -251,6 +262,19 @@ export class SyncClientHandle {
|
|
|
251
262
|
this.#presence.delete(listener);
|
|
252
263
|
};
|
|
253
264
|
}
|
|
265
|
+
/**
|
|
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
|
|
269
|
+
* drives of the leader it is bound to; a drive that ended before this tab
|
|
270
|
+
* bound is not replayed. Returns an unsubscribe function.
|
|
271
|
+
*/
|
|
272
|
+
onSynced(listener) {
|
|
273
|
+
this.#synced.add(listener);
|
|
274
|
+
return () => {
|
|
275
|
+
this.#synced.delete(listener);
|
|
276
|
+
};
|
|
277
|
+
}
|
|
254
278
|
/** Subscribe to role transitions (follower → leader on promotion). */
|
|
255
279
|
onRoleChange(listener) {
|
|
256
280
|
this.#roleListeners.add(listener);
|
|
@@ -668,6 +692,12 @@ function buildInitConfig(config, headers = config.headers) {
|
|
|
668
692
|
...(config.autoSync !== undefined ? { autoSync: config.autoSync } : {}),
|
|
669
693
|
};
|
|
670
694
|
}
|
|
695
|
+
function syncedResult(event) {
|
|
696
|
+
return {
|
|
697
|
+
...(event.summary !== undefined ? { summary: event.summary } : {}),
|
|
698
|
+
...(event.error !== undefined ? { error: event.error } : {}),
|
|
699
|
+
};
|
|
700
|
+
}
|
|
671
701
|
/** Route a worker event to the config-level callbacks (leader visibility). */
|
|
672
702
|
function fireConfigCallbacks(config, event) {
|
|
673
703
|
if (event.kind === 'sync-needed') {
|
|
@@ -683,10 +713,7 @@ function fireConfigCallbacks(config, event) {
|
|
|
683
713
|
config.onPresence?.(event.scopeKey, event.error);
|
|
684
714
|
}
|
|
685
715
|
else if (event.kind === 'synced') {
|
|
686
|
-
config.onSynced?.(
|
|
687
|
-
...(event.summary !== undefined ? { summary: event.summary } : {}),
|
|
688
|
-
...(event.error !== undefined ? { error: event.error } : {}),
|
|
689
|
-
});
|
|
716
|
+
config.onSynced?.(syncedResult(event));
|
|
690
717
|
}
|
|
691
718
|
else if (event.kind === 'diagnostics') {
|
|
692
719
|
config.onDiagnostics?.(event.snapshot);
|
|
@@ -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,11 +260,8 @@ 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
|
-
/** A
|
|
264
|
-
readonly onSynced?:
|
|
265
|
-
readonly summary?: SyncSummary;
|
|
266
|
-
readonly error?: WorkerErrorShape;
|
|
267
|
-
}) => void;
|
|
263
|
+
/** A drive to idle in the leader worker ended (leader tab only). */
|
|
264
|
+
readonly onSynced?: SyncedListener;
|
|
268
265
|
/** §7.4.5: schema-bump `upgrading` state changed (reset began/completed). */
|
|
269
266
|
readonly onUpgrading?: (upgrading: boolean) => void;
|
|
270
267
|
/** §8.6: presence on a scope key changed, or the server refused this
|
|
@@ -274,6 +271,15 @@ export interface SyncClientHandleConfig {
|
|
|
274
271
|
readonly onDiagnostics?: (snapshot: ClientDiagnosticsSnapshot) => void;
|
|
275
272
|
}
|
|
276
273
|
|
|
274
|
+
/**
|
|
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
|
+
*/
|
|
278
|
+
export type SyncedListener = (result: {
|
|
279
|
+
readonly summary?: SyncSummary;
|
|
280
|
+
readonly error?: WorkerErrorShape;
|
|
281
|
+
}) => void;
|
|
282
|
+
|
|
277
283
|
interface Pending {
|
|
278
284
|
resolve(value: unknown): void;
|
|
279
285
|
reject(error: unknown): void;
|
|
@@ -338,6 +344,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
338
344
|
#core: LeaderCore | undefined;
|
|
339
345
|
readonly #invalidation: InvalidationEmitter;
|
|
340
346
|
readonly #progress = new ProgressEmitter();
|
|
347
|
+
readonly #synced = new Set<SyncedListener>();
|
|
341
348
|
readonly #changes: ChangeEmitter;
|
|
342
349
|
readonly #presence: Set<
|
|
343
350
|
(scopeKey: string, error?: PresenceErrorCode) => void
|
|
@@ -456,6 +463,14 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
456
463
|
this.#changes.emit(event.batch);
|
|
457
464
|
const legacy = invalidationFromChange(event.batch);
|
|
458
465
|
if (legacy !== undefined) this.#invalidation.emit(legacy);
|
|
466
|
+
} else if (event.kind === 'synced') {
|
|
467
|
+
for (const listener of this.#synced) {
|
|
468
|
+
try {
|
|
469
|
+
listener(syncedResult(event));
|
|
470
|
+
} catch {
|
|
471
|
+
/* a UI listener must never break event dispatch */
|
|
472
|
+
}
|
|
473
|
+
}
|
|
459
474
|
} else if (event.kind === 'diagnostics') {
|
|
460
475
|
this.#diagnostics.emit(
|
|
461
476
|
withClientDiagnosticsHost(event.snapshot, {
|
|
@@ -516,6 +531,20 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
516
531
|
};
|
|
517
532
|
}
|
|
518
533
|
|
|
534
|
+
/**
|
|
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
|
|
538
|
+
* drives of the leader it is bound to; a drive that ended before this tab
|
|
539
|
+
* bound is not replayed. Returns an unsubscribe function.
|
|
540
|
+
*/
|
|
541
|
+
onSynced(listener: SyncedListener): () => void {
|
|
542
|
+
this.#synced.add(listener);
|
|
543
|
+
return () => {
|
|
544
|
+
this.#synced.delete(listener);
|
|
545
|
+
};
|
|
546
|
+
}
|
|
547
|
+
|
|
519
548
|
/** Subscribe to role transitions (follower → leader on promotion). */
|
|
520
549
|
onRoleChange(listener: (role: HandleRole) => void): () => void {
|
|
521
550
|
this.#roleListeners.add(listener);
|
|
@@ -1073,6 +1102,15 @@ function buildInitConfig(
|
|
|
1073
1102
|
};
|
|
1074
1103
|
}
|
|
1075
1104
|
|
|
1105
|
+
function syncedResult(
|
|
1106
|
+
event: Extract<SyncWorkerEvent, { kind: 'synced' }>,
|
|
1107
|
+
): Parameters<SyncedListener>[0] {
|
|
1108
|
+
return {
|
|
1109
|
+
...(event.summary !== undefined ? { summary: event.summary } : {}),
|
|
1110
|
+
...(event.error !== undefined ? { error: event.error } : {}),
|
|
1111
|
+
};
|
|
1112
|
+
}
|
|
1113
|
+
|
|
1076
1114
|
/** Route a worker event to the config-level callbacks (leader visibility). */
|
|
1077
1115
|
function fireConfigCallbacks(
|
|
1078
1116
|
config: SyncClientHandleConfig,
|
|
@@ -1087,10 +1125,7 @@ function fireConfigCallbacks(
|
|
|
1087
1125
|
} else if (event.kind === 'presence') {
|
|
1088
1126
|
config.onPresence?.(event.scopeKey, event.error);
|
|
1089
1127
|
} else if (event.kind === 'synced') {
|
|
1090
|
-
config.onSynced?.(
|
|
1091
|
-
...(event.summary !== undefined ? { summary: event.summary } : {}),
|
|
1092
|
-
...(event.error !== undefined ? { error: event.error } : {}),
|
|
1093
|
-
});
|
|
1128
|
+
config.onSynced?.(syncedResult(event));
|
|
1094
1129
|
} else if (event.kind === 'diagnostics') {
|
|
1095
1130
|
config.onDiagnostics?.(event.snapshot);
|
|
1096
1131
|
}
|
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;
|