@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.
Files changed (82) hide show
  1. package/README.md +7 -7
  2. package/dist/apply.d.ts +20 -11
  3. package/dist/apply.js +67 -45
  4. package/dist/blob.d.ts +17 -9
  5. package/dist/blob.js +5 -6
  6. package/dist/bun-database.d.ts +1 -0
  7. package/dist/bun-database.js +28 -0
  8. package/dist/client.d.ts +27 -10
  9. package/dist/client.js +357 -190
  10. package/dist/database.d.ts +5 -0
  11. package/dist/encryption.d.ts +2 -2
  12. package/dist/encryption.js +8 -2
  13. package/dist/errors.d.ts +2 -0
  14. package/dist/errors.js +4 -0
  15. package/dist/failed-overlay.d.ts +0 -1
  16. package/dist/failed-overlay.js +3 -6
  17. package/dist/http.d.ts +4 -1
  18. package/dist/http.js +61 -39
  19. package/dist/index.d.ts +1 -1
  20. package/dist/index.js +1 -1
  21. package/dist/invalidation.d.ts +11 -10
  22. package/dist/invalidation.js +15 -26
  23. package/dist/local-purge.js +9 -12
  24. package/dist/local-rebootstrap.js +2 -2
  25. package/dist/multi-tab.d.ts +89 -1
  26. package/dist/multi-tab.js +70 -31
  27. package/dist/native-bridge.d.ts +235 -0
  28. package/dist/native-bridge.js +789 -0
  29. package/dist/node-database.d.ts +1 -0
  30. package/dist/node-database.js +29 -0
  31. package/dist/outbox.d.ts +9 -12
  32. package/dist/outbox.js +19 -36
  33. package/dist/outcomes.js +3 -3
  34. package/dist/previous-version.js +96 -114
  35. package/dist/query-guard.d.ts +25 -24
  36. package/dist/query-guard.js +34 -191
  37. package/dist/reactive-store.js +53 -11
  38. package/dist/realtime-supervisor.d.ts +9 -2
  39. package/dist/realtime-supervisor.js +31 -7
  40. package/dist/remote.js +11 -15
  41. package/dist/schema.js +15 -10
  42. package/dist/sync-scheduler.js +28 -2
  43. package/dist/transport.d.ts +19 -4
  44. package/dist/wasm-database.js +58 -21
  45. package/dist/worker-core.d.ts +5 -0
  46. package/dist/worker-core.js +80 -72
  47. package/dist/worker-host.d.ts +10 -5
  48. package/dist/worker-host.js +64 -7
  49. package/dist/worker-local-authority.js +2 -2
  50. package/dist/worker-protocol.d.ts +6 -2
  51. package/package.json +11 -3
  52. package/src/apply.ts +91 -55
  53. package/src/blob.ts +27 -15
  54. package/src/bun-database.ts +29 -0
  55. package/src/client.ts +477 -261
  56. package/src/database.ts +5 -0
  57. package/src/encryption.ts +10 -5
  58. package/src/errors.ts +8 -0
  59. package/src/failed-overlay.ts +3 -7
  60. package/src/http.ts +90 -79
  61. package/src/index.ts +1 -1
  62. package/src/invalidation.ts +17 -32
  63. package/src/local-purge.ts +11 -13
  64. package/src/local-rebootstrap.ts +2 -3
  65. package/src/multi-tab.ts +88 -30
  66. package/src/native-bridge.ts +1189 -0
  67. package/src/node-database.ts +32 -0
  68. package/src/outbox.ts +19 -41
  69. package/src/outcomes.ts +3 -5
  70. package/src/previous-version.ts +103 -114
  71. package/src/query-guard.ts +43 -180
  72. package/src/reactive-store.ts +50 -10
  73. package/src/realtime-supervisor.ts +37 -12
  74. package/src/remote.ts +12 -16
  75. package/src/schema.ts +19 -12
  76. package/src/sync-scheduler.ts +31 -1
  77. package/src/transport.ts +21 -2
  78. package/src/wasm-database.ts +76 -27
  79. package/src/worker-core.ts +94 -74
  80. package/src/worker-host.ts +63 -16
  81. package/src/worker-local-authority.ts +2 -5
  82. package/src/worker-protocol.ts +6 -2
@@ -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 type { WakeReason } from '@syncular/core';
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 new ClientSyncError(
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
- readonly onPresence?: (scopeKey: string) => void;
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<(scopeKey: string) => void>;
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
- return this.#diagnostics.on(listener);
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(listener: (scopeKey: string) => void): () => void {
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
- const worker = config.worker();
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<(scopeKey: string) => void>();
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 new ClientSyncError(
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 new ClientSyncError(
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
  },
@@ -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 inside the worker. */
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. */