@syncular/client 0.57.0 → 0.59.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.
- package/README.md +7 -7
- package/dist/apply.d.ts +20 -11
- package/dist/apply.js +67 -45
- package/dist/blob.d.ts +17 -9
- package/dist/blob.js +5 -6
- package/dist/bun-database.d.ts +1 -0
- package/dist/bun-database.js +28 -0
- package/dist/client.d.ts +27 -10
- package/dist/client.js +357 -190
- package/dist/database.d.ts +5 -0
- package/dist/encryption.d.ts +2 -2
- package/dist/encryption.js +8 -2
- package/dist/errors.d.ts +2 -0
- package/dist/errors.js +4 -0
- package/dist/failed-overlay.d.ts +0 -1
- package/dist/failed-overlay.js +3 -6
- package/dist/http.d.ts +4 -1
- package/dist/http.js +61 -39
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/invalidation.d.ts +11 -10
- package/dist/invalidation.js +15 -26
- package/dist/local-purge.js +9 -12
- package/dist/local-rebootstrap.js +2 -2
- package/dist/multi-tab.d.ts +89 -1
- package/dist/multi-tab.js +70 -31
- package/dist/native-bridge.d.ts +235 -0
- package/dist/native-bridge.js +789 -0
- package/dist/node-database.d.ts +1 -0
- package/dist/node-database.js +29 -0
- package/dist/outbox.d.ts +9 -12
- package/dist/outbox.js +19 -36
- package/dist/outcomes.js +3 -3
- package/dist/previous-version.js +96 -114
- package/dist/query-guard.d.ts +25 -24
- package/dist/query-guard.js +34 -191
- package/dist/reactive-store.js +53 -11
- package/dist/realtime-supervisor.d.ts +9 -2
- package/dist/realtime-supervisor.js +31 -7
- package/dist/remote.js +11 -15
- package/dist/schema.js +15 -10
- package/dist/sync-scheduler.js +28 -2
- package/dist/transport.d.ts +19 -4
- package/dist/wasm-database.js +58 -21
- package/dist/worker-core.d.ts +5 -0
- package/dist/worker-core.js +80 -72
- package/dist/worker-host.d.ts +10 -5
- package/dist/worker-host.js +64 -7
- package/dist/worker-local-authority.js +2 -2
- package/dist/worker-protocol.d.ts +6 -2
- package/package.json +11 -3
- package/src/apply.ts +91 -55
- package/src/blob.ts +27 -15
- package/src/bun-database.ts +29 -0
- package/src/client.ts +477 -261
- package/src/database.ts +5 -0
- package/src/encryption.ts +10 -5
- package/src/errors.ts +8 -0
- package/src/failed-overlay.ts +3 -7
- package/src/http.ts +90 -79
- package/src/index.ts +1 -1
- package/src/invalidation.ts +17 -32
- package/src/local-purge.ts +11 -13
- package/src/local-rebootstrap.ts +2 -3
- package/src/multi-tab.ts +88 -30
- package/src/native-bridge.ts +1189 -0
- package/src/node-database.ts +32 -0
- package/src/outbox.ts +19 -41
- package/src/outcomes.ts +3 -5
- package/src/previous-version.ts +103 -114
- package/src/query-guard.ts +43 -180
- package/src/reactive-store.ts +50 -10
- package/src/realtime-supervisor.ts +37 -12
- package/src/remote.ts +12 -16
- package/src/schema.ts +19 -12
- package/src/sync-scheduler.ts +31 -1
- package/src/transport.ts +21 -2
- package/src/wasm-database.ts +76 -27
- package/src/worker-core.ts +94 -74
- package/src/worker-host.ts +63 -16
- package/src/worker-local-authority.ts +2 -5
- package/src/worker-protocol.ts +6 -2
package/src/worker-host.ts
CHANGED
|
@@ -27,7 +27,11 @@ import type { PromiseMethods } from './client';
|
|
|
27
27
|
* With `multiTab: false`, the loser is an `isLeader === false` handle whose
|
|
28
28
|
* calls reject with `client.not_leader` (the single-tab contract).
|
|
29
29
|
*/
|
|
30
|
-
import
|
|
30
|
+
import {
|
|
31
|
+
type PresenceErrorCode,
|
|
32
|
+
serializeBlobRef,
|
|
33
|
+
type WakeReason,
|
|
34
|
+
} from '@syncular/core';
|
|
31
35
|
import type { BlobRef, CachedBlob } from './blob';
|
|
32
36
|
import type {
|
|
33
37
|
ConflictRecord,
|
|
@@ -59,7 +63,7 @@ import {
|
|
|
59
63
|
withClientDiagnosticsHost,
|
|
60
64
|
} from './diagnostics';
|
|
61
65
|
import type { EncryptionKeyringConfig } from './encryption';
|
|
62
|
-
import { ClientSyncError } from './errors';
|
|
66
|
+
import { ClientSyncError, invalidRequest } from './errors';
|
|
63
67
|
import {
|
|
64
68
|
ChangeEmitter,
|
|
65
69
|
type ClientChangeListener,
|
|
@@ -161,8 +165,7 @@ export function isolatedReplicaNames(options: {
|
|
|
161
165
|
readonly replicaId: string;
|
|
162
166
|
}): IsolatedReplicaNames {
|
|
163
167
|
if (!/^[A-Za-z0-9._-]+$/.test(options.replicaId)) {
|
|
164
|
-
throw
|
|
165
|
-
'sync.invalid_request',
|
|
168
|
+
throw invalidRequest(
|
|
166
169
|
'an isolated replica id must contain only letters, numbers, dot, underscore, or dash',
|
|
167
170
|
);
|
|
168
171
|
}
|
|
@@ -213,6 +216,8 @@ export interface SyncClientHandleConfig {
|
|
|
213
216
|
* `WorkerInitConfig`. Absent ⇒ `optional`.
|
|
214
217
|
*/
|
|
215
218
|
readonly realtimePolicy?: RealtimePolicy;
|
|
219
|
+
/** SPEC §8.5 heartbeat interval, forwarded into `WorkerInitConfig`. */
|
|
220
|
+
readonly realtimeHeartbeatMs?: number;
|
|
216
221
|
/**
|
|
217
222
|
* RFC 0005 previous-version context, forwarded into the worker's
|
|
218
223
|
* `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
|
|
@@ -263,8 +268,9 @@ export interface SyncClientHandleConfig {
|
|
|
263
268
|
}) => void;
|
|
264
269
|
/** §7.4.5: schema-bump `upgrading` state changed (reset began/completed). */
|
|
265
270
|
readonly onUpgrading?: (upgrading: boolean) => void;
|
|
266
|
-
/** §8.6: presence on a scope key changed
|
|
267
|
-
|
|
271
|
+
/** §8.6: presence on a scope key changed, or the server refused this
|
|
272
|
+
* client's publish on it (`error`, §8.6.2). */
|
|
273
|
+
readonly onPresence?: (scopeKey: string, error?: PresenceErrorCode) => void;
|
|
268
274
|
/** Atomic privacy-safe diagnostics changed. */
|
|
269
275
|
readonly onDiagnostics?: (snapshot: ClientDiagnosticsSnapshot) => void;
|
|
270
276
|
}
|
|
@@ -334,7 +340,9 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
334
340
|
readonly #invalidation: InvalidationEmitter;
|
|
335
341
|
readonly #progress = new ProgressEmitter();
|
|
336
342
|
readonly #changes: ChangeEmitter;
|
|
337
|
-
readonly #presence: Set<
|
|
343
|
+
readonly #presence: Set<
|
|
344
|
+
(scopeKey: string, error?: PresenceErrorCode) => void
|
|
345
|
+
>;
|
|
338
346
|
readonly #diagnostics: ClientDiagnosticsEmitter;
|
|
339
347
|
readonly #roleListeners: Set<(role: HandleRole) => void>;
|
|
340
348
|
readonly #leadershipListeners: Set<(state: LeadershipState) => void>;
|
|
@@ -352,7 +360,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
352
360
|
tabs?: TabCoordinator;
|
|
353
361
|
invalidation: InvalidationEmitter;
|
|
354
362
|
changes: ChangeEmitter;
|
|
355
|
-
presence: Set<(scopeKey: string) => void>;
|
|
363
|
+
presence: Set<(scopeKey: string, error?: PresenceErrorCode) => void>;
|
|
356
364
|
diagnostics: ClientDiagnosticsEmitter;
|
|
357
365
|
roleListeners?: Set<(role: HandleRole) => void>;
|
|
358
366
|
leadershipListeners?: Set<(state: LeadershipState) => void>;
|
|
@@ -407,6 +415,13 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
407
415
|
this.#leadership = state;
|
|
408
416
|
if (state.state === 'leader') this.#clientId = state.clientId;
|
|
409
417
|
if (state.state === 'follower') this.#clientId = state.leaderClientId;
|
|
418
|
+
// A new leader starts a fresh core that no tab has pulled from yet.
|
|
419
|
+
if (
|
|
420
|
+
this.#diagnostics.observed &&
|
|
421
|
+
(state.state === 'leader' || state.state === 'follower')
|
|
422
|
+
) {
|
|
423
|
+
this.#pullDiagnostics();
|
|
424
|
+
}
|
|
410
425
|
for (const listener of this.#leadershipListeners) {
|
|
411
426
|
try {
|
|
412
427
|
listener(state);
|
|
@@ -433,7 +448,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
433
448
|
} else if (event.kind === 'presence') {
|
|
434
449
|
for (const listener of this.#presence) {
|
|
435
450
|
try {
|
|
436
|
-
listener(event.scopeKey);
|
|
451
|
+
listener(event.scopeKey, event.error);
|
|
437
452
|
} catch {
|
|
438
453
|
/* a UI listener must never break event dispatch */
|
|
439
454
|
}
|
|
@@ -475,14 +490,27 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
475
490
|
}
|
|
476
491
|
|
|
477
492
|
onDiagnostics(listener: ClientDiagnosticsListener): () => void {
|
|
478
|
-
|
|
493
|
+
const off = this.#diagnostics.on(listener);
|
|
494
|
+
this.#pullDiagnostics();
|
|
495
|
+
return off;
|
|
496
|
+
}
|
|
497
|
+
|
|
498
|
+
/**
|
|
499
|
+
* The worker pushes diagnostics only after a consumer pulled once. A handle
|
|
500
|
+
* that cannot reach a core has nothing to observe, so a failed pull is
|
|
501
|
+
* dropped.
|
|
502
|
+
*/
|
|
503
|
+
#pullDiagnostics(): void {
|
|
504
|
+
void this.diagnosticsSnapshot().catch(() => undefined);
|
|
479
505
|
}
|
|
480
506
|
|
|
481
507
|
/**
|
|
482
508
|
* §8.6: subscribe to presence changes — the identical surface as
|
|
483
509
|
* `SyncClient.onPresence`. Returns an unsubscribe function.
|
|
484
510
|
*/
|
|
485
|
-
onPresence(
|
|
511
|
+
onPresence(
|
|
512
|
+
listener: (scopeKey: string, error?: PresenceErrorCode) => void,
|
|
513
|
+
): () => void {
|
|
486
514
|
this.#presence.add(listener);
|
|
487
515
|
return () => {
|
|
488
516
|
this.#presence.delete(listener);
|
|
@@ -790,6 +818,11 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
790
818
|
return this.#call('uploadBlob', [bytes, options]);
|
|
791
819
|
}
|
|
792
820
|
|
|
821
|
+
/** Serialize a BlobRef to the canonical string a `blob_ref` column holds. */
|
|
822
|
+
blobRefString(ref: BlobRef): string {
|
|
823
|
+
return serializeBlobRef(ref);
|
|
824
|
+
}
|
|
825
|
+
|
|
793
826
|
fetchBlob(blobIdOrRef: string): Promise<CachedBlob> {
|
|
794
827
|
return this.#call('fetchBlob', [blobIdOrRef]);
|
|
795
828
|
}
|
|
@@ -862,7 +895,14 @@ async function startWorkerCore(options: {
|
|
|
862
895
|
dispatchEvent: (event: SyncWorkerEvent) => void;
|
|
863
896
|
}): Promise<LeaderCore> {
|
|
864
897
|
const { config, initConfig, lease } = options;
|
|
865
|
-
|
|
898
|
+
let worker: Worker;
|
|
899
|
+
try {
|
|
900
|
+
worker = config.worker();
|
|
901
|
+
} catch (error) {
|
|
902
|
+
// No worker exists to terminate; the lease is the only thing held.
|
|
903
|
+
await lease.release();
|
|
904
|
+
throw error;
|
|
905
|
+
}
|
|
866
906
|
const pending = new Map<number, Pending>();
|
|
867
907
|
const nextId = { value: 1 };
|
|
868
908
|
let terminated = false;
|
|
@@ -961,6 +1001,9 @@ async function startWorkerCore(options: {
|
|
|
961
1001
|
} as MainToWorkerMessage);
|
|
962
1002
|
},
|
|
963
1003
|
);
|
|
1004
|
+
// A config callback is a consumer from the first round.
|
|
1005
|
+
if (config.onDiagnostics !== undefined)
|
|
1006
|
+
await invoke('diagnosticsSnapshot', []);
|
|
964
1007
|
return {
|
|
965
1008
|
clientId: initResult.clientId,
|
|
966
1009
|
invoke,
|
|
@@ -1012,6 +1055,9 @@ function buildInitConfig(
|
|
|
1012
1055
|
...(config.realtimePolicy !== undefined
|
|
1013
1056
|
? { realtimePolicy: config.realtimePolicy }
|
|
1014
1057
|
: {}),
|
|
1058
|
+
...(config.realtimeHeartbeatMs !== undefined
|
|
1059
|
+
? { realtimeHeartbeatMs: config.realtimeHeartbeatMs }
|
|
1060
|
+
: {}),
|
|
1015
1061
|
...(config.previousVersionContext !== undefined
|
|
1016
1062
|
? { previousVersionContext: config.previousVersionContext }
|
|
1017
1063
|
: {}),
|
|
@@ -1031,7 +1077,7 @@ function fireConfigCallbacks(
|
|
|
1031
1077
|
} else if (event.kind === 'upgrading') {
|
|
1032
1078
|
config.onUpgrading?.(event.upgrading);
|
|
1033
1079
|
} else if (event.kind === 'presence') {
|
|
1034
|
-
config.onPresence?.(event.scopeKey);
|
|
1080
|
+
config.onPresence?.(event.scopeKey, event.error);
|
|
1035
1081
|
} else if (event.kind === 'synced') {
|
|
1036
1082
|
config.onSynced?.({
|
|
1037
1083
|
...(event.summary !== undefined ? { summary: event.summary } : {}),
|
|
@@ -1057,7 +1103,9 @@ export async function createSyncClientHandle(
|
|
|
1057
1103
|
const lockName = resolvedConfig.lockName ?? 'syncular-leader';
|
|
1058
1104
|
const invalidation = new InvalidationEmitter();
|
|
1059
1105
|
const changes = new ChangeEmitter();
|
|
1060
|
-
const presence = new Set<
|
|
1106
|
+
const presence = new Set<
|
|
1107
|
+
(scopeKey: string, error?: PresenceErrorCode) => void
|
|
1108
|
+
>();
|
|
1061
1109
|
const diagnostics = new ClientDiagnosticsEmitter();
|
|
1062
1110
|
const roleListeners = new Set<(role: HandleRole) => void>();
|
|
1063
1111
|
if (resolvedConfig.onRoleChange !== undefined)
|
|
@@ -1213,8 +1261,7 @@ function resolveReplicaConfig(
|
|
|
1213
1261
|
): SyncClientHandleConfig {
|
|
1214
1262
|
if (config.replica?.mode !== 'isolated') return config;
|
|
1215
1263
|
if (config.database.mode !== 'persistent') {
|
|
1216
|
-
throw
|
|
1217
|
-
'sync.invalid_request',
|
|
1264
|
+
throw invalidRequest(
|
|
1218
1265
|
'isolated browser replicas require a named persistent database',
|
|
1219
1266
|
);
|
|
1220
1267
|
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { SiblingDatabase } from './database';
|
|
2
|
-
import { ClientSyncError } from './errors';
|
|
2
|
+
import { ClientSyncError, invalidRequest } from './errors';
|
|
3
3
|
import type { SyncTransport } from './transport';
|
|
4
4
|
import type {
|
|
5
5
|
WorkerLocalAuthority,
|
|
@@ -91,10 +91,7 @@ export const createWorkerLocalAuthority: WorkerLocalAuthorityFactory = (
|
|
|
91
91
|
segments: (request) => {
|
|
92
92
|
if (active()) return local.downloadSegment(request);
|
|
93
93
|
if (segments === undefined) {
|
|
94
|
-
throw
|
|
95
|
-
'sync.invalid_request',
|
|
96
|
-
'no segment endpoint configured',
|
|
97
|
-
);
|
|
94
|
+
throw invalidRequest('no segment endpoint configured');
|
|
98
95
|
}
|
|
99
96
|
return segments(request);
|
|
100
97
|
},
|
package/src/worker-protocol.ts
CHANGED
|
@@ -17,7 +17,7 @@ import type { SyncProgress } from './progress';
|
|
|
17
17
|
* so the UI thread never has to react to keep data flowing. Events are
|
|
18
18
|
* still forwarded to the handle for visibility.
|
|
19
19
|
*/
|
|
20
|
-
import type { WakeReason } from '@syncular/core';
|
|
20
|
+
import type { PresenceErrorCode, WakeReason } from '@syncular/core';
|
|
21
21
|
import type { BlobRef, CachedBlob } from './blob';
|
|
22
22
|
import type {
|
|
23
23
|
ConflictRecord,
|
|
@@ -147,6 +147,8 @@ export interface WorkerInitConfig {
|
|
|
147
147
|
* Absent ⇒ `optional` (a connected socket, otherwise `POST /sync`).
|
|
148
148
|
*/
|
|
149
149
|
readonly realtimePolicy?: RealtimePolicy;
|
|
150
|
+
/** SPEC §8.5 heartbeat interval for the worker-owned core; forwarded verbatim. */
|
|
151
|
+
readonly realtimeHeartbeatMs?: number;
|
|
150
152
|
/**
|
|
151
153
|
* RFC 0005 previous-version context, forwarded verbatim into the worker's
|
|
152
154
|
* `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
|
|
@@ -299,9 +301,11 @@ export type SyncWorkerEvent =
|
|
|
299
301
|
readonly upgrading: boolean;
|
|
300
302
|
}
|
|
301
303
|
| {
|
|
302
|
-
/** §8.6: presence on a scope key changed
|
|
304
|
+
/** §8.6: presence on a scope key changed, or the server refused this
|
|
305
|
+
* client's publish on it (`error`, §8.6.2). */
|
|
303
306
|
readonly kind: 'presence';
|
|
304
307
|
readonly scopeKey: string;
|
|
308
|
+
readonly error?: PresenceErrorCode | undefined;
|
|
305
309
|
}
|
|
306
310
|
| {
|
|
307
311
|
/** Exact revisioned core transaction; Sets and bigint clone directly. */
|