@syncular/client 0.58.0 → 0.60.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 (99) hide show
  1. package/README.md +34 -34
  2. package/dist/apply.d.ts +24 -14
  3. package/dist/apply.js +119 -70
  4. package/dist/authority.js +21 -16
  5. package/dist/blob.d.ts +17 -9
  6. package/dist/blob.js +5 -6
  7. package/dist/bun-database.d.ts +1 -0
  8. package/dist/bun-database.js +15 -0
  9. package/dist/client.d.ts +83 -75
  10. package/dist/client.js +982 -910
  11. package/dist/database.d.ts +5 -0
  12. package/dist/devtools.d.ts +2 -2
  13. package/dist/devtools.js +3 -3
  14. package/dist/diagnostics.d.ts +17 -28
  15. package/dist/diagnostics.js +1 -2
  16. package/dist/encryption.d.ts +2 -2
  17. package/dist/encryption.js +8 -2
  18. package/dist/errors.d.ts +3 -1
  19. package/dist/errors.js +5 -1
  20. package/dist/failed-overlay.d.ts +0 -1
  21. package/dist/failed-overlay.js +6 -6
  22. package/dist/http.d.ts +4 -1
  23. package/dist/http.js +67 -39
  24. package/dist/index.d.ts +1 -1
  25. package/dist/index.js +1 -1
  26. package/dist/invalidation.d.ts +14 -14
  27. package/dist/invalidation.js +24 -48
  28. package/dist/local-purge.js +9 -12
  29. package/dist/local-rebootstrap.js +2 -2
  30. package/dist/multi-tab.d.ts +89 -1
  31. package/dist/multi-tab.js +70 -31
  32. package/dist/native-bridge.d.ts +226 -0
  33. package/dist/native-bridge.js +764 -0
  34. package/dist/node-database.d.ts +1 -0
  35. package/dist/node-database.js +21 -1
  36. package/dist/outbox.d.ts +9 -12
  37. package/dist/outbox.js +20 -36
  38. package/dist/outcomes.js +3 -3
  39. package/dist/previous-version.js +96 -114
  40. package/dist/progress.d.ts +2 -2
  41. package/dist/query-guard.d.ts +34 -24
  42. package/dist/query-guard.js +61 -186
  43. package/dist/reactive-store.js +55 -13
  44. package/dist/realtime-supervisor.d.ts +9 -2
  45. package/dist/realtime-supervisor.js +31 -7
  46. package/dist/remote.js +19 -23
  47. package/dist/schema.d.ts +3 -2
  48. package/dist/schema.js +43 -22
  49. package/dist/state.d.ts +69 -36
  50. package/dist/state.js +178 -89
  51. package/dist/sync-scheduler.js +28 -2
  52. package/dist/transport.d.ts +19 -4
  53. package/dist/wasm-database.js +58 -21
  54. package/dist/window.d.ts +30 -52
  55. package/dist/window.js +33 -77
  56. package/dist/worker-core.d.ts +5 -0
  57. package/dist/worker-core.js +83 -75
  58. package/dist/worker-host.d.ts +19 -13
  59. package/dist/worker-host.js +75 -18
  60. package/dist/worker-local-authority.js +2 -2
  61. package/dist/worker-protocol.d.ts +15 -10
  62. package/package.json +11 -3
  63. package/src/apply.ts +176 -86
  64. package/src/authority.ts +31 -17
  65. package/src/blob.ts +28 -15
  66. package/src/bun-database.ts +24 -0
  67. package/src/client.ts +1282 -1217
  68. package/src/database.ts +5 -0
  69. package/src/devtools.ts +5 -5
  70. package/src/diagnostics.ts +17 -37
  71. package/src/encryption.ts +10 -5
  72. package/src/errors.ts +9 -1
  73. package/src/failed-overlay.ts +8 -7
  74. package/src/http.ts +95 -79
  75. package/src/index.ts +1 -1
  76. package/src/invalidation.ts +26 -61
  77. package/src/local-purge.ts +11 -13
  78. package/src/local-rebootstrap.ts +2 -3
  79. package/src/multi-tab.ts +88 -30
  80. package/src/native-bridge.ts +1153 -0
  81. package/src/node-database.ts +32 -1
  82. package/src/outbox.ts +20 -41
  83. package/src/outcomes.ts +3 -5
  84. package/src/previous-version.ts +103 -114
  85. package/src/progress.ts +2 -2
  86. package/src/query-guard.ts +77 -177
  87. package/src/reactive-store.ts +52 -12
  88. package/src/realtime-supervisor.ts +37 -12
  89. package/src/remote.ts +23 -31
  90. package/src/schema.ts +67 -25
  91. package/src/state.ts +246 -125
  92. package/src/sync-scheduler.ts +31 -1
  93. package/src/transport.ts +21 -2
  94. package/src/wasm-database.ts +76 -27
  95. package/src/window.ts +55 -134
  96. package/src/worker-core.ts +97 -77
  97. package/src/worker-host.ts +76 -32
  98. package/src/worker-local-authority.ts +2 -5
  99. package/src/worker-protocol.ts +14 -10
@@ -1,6 +1,30 @@
1
1
  import { ProgressEmitter, } from './progress.js';
2
+ /**
3
+ * Main-thread side of the worker mode and the
4
+ * multi-tab topology.
5
+ *
6
+ * `createSyncClientHandle` acquires the Web Locks leader lock and, when it
7
+ * wins, spawns the worker running the WHOLE core — so exactly one core runs
8
+ * per origin (the lock IS the invariant: a worker is NEVER spawned without
9
+ * holding the lock). The returned {@link SyncClientHandle} is a thin, fully
10
+ * async proxy over the `worker-protocol` RPC.
11
+ *
12
+ * Multi-tab is the DEFAULT. The follower path is
13
+ * conformance-covered): a tab that LOSES the election becomes a FOLLOWER
14
+ * (`role === 'follower'`) that proxies every call to the leader tab over a
15
+ * BroadcastChannel (see `multi-tab.ts`). When the leader tab closes, its
16
+ * lock releases; the followers contest, the winner PROMOTES in place —
17
+ * spawns the worker over the persisted OPFS database and re-announces — and
18
+ * the handle's `role` flips to `'leader'` with `onRoleChange` firing. The
19
+ * same handle object is kept across the transition so React bindings hold a
20
+ * stable reference.
21
+ *
22
+ * With `multiTab: false`, the loser is an `isLeader === false` handle whose
23
+ * calls reject with `client.not_leader` (the single-tab contract).
24
+ */
25
+ import { serializeBlobRef, } from '@syncular/core';
2
26
  import { ClientDiagnosticsEmitter, withClientDiagnosticsHost, } from './diagnostics.js';
3
- import { ClientSyncError } from './errors.js';
27
+ import { ClientSyncError, invalidRequest } from './errors.js';
4
28
  import { ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
5
29
  import { singleOwnerLock, webLocksLeaderLock, } from './leader-lock.js';
6
30
  import { decodeLocalDataRebootstrapResult, } from './local-rebootstrap.js';
@@ -18,7 +42,7 @@ export function workerStartupError(message) {
18
42
  /** Derive the complete ownership tuple for an independently owned replica. */
19
43
  export function isolatedReplicaNames(options) {
20
44
  if (!/^[A-Za-z0-9._-]+$/.test(options.replicaId)) {
21
- throw new ClientSyncError('sync.invalid_request', 'an isolated replica id must contain only letters, numbers, dot, underscore, or dash');
45
+ throw invalidRequest('an isolated replica id must contain only letters, numbers, dot, underscore, or dash');
22
46
  }
23
47
  const suffix = `--replica-${options.replicaId}`;
24
48
  const databaseName = `${options.databaseName}${suffix}`;
@@ -113,7 +137,7 @@ export class SyncClientHandle {
113
137
  clientId: () => this.#clientId,
114
138
  role: () => this.#role,
115
139
  outbox: async () => (await this.statusSnapshot()).outbox,
116
- subscriptions: () => this.subscriptions(),
140
+ units: () => this.units(),
117
141
  conflicts: async () => (await this.conflicts()).length,
118
142
  rejections: async () => (await this.rejections()).length,
119
143
  syncNeeded: async () => (await this.statusSnapshot()).syncNeeded,
@@ -131,6 +155,11 @@ export class SyncClientHandle {
131
155
  this.#clientId = state.clientId;
132
156
  if (state.state === 'follower')
133
157
  this.#clientId = state.leaderClientId;
158
+ // A new leader starts a fresh core that no tab has pulled from yet.
159
+ if (this.#diagnostics.observed &&
160
+ (state.state === 'leader' || state.state === 'follower')) {
161
+ this.#pullDiagnostics();
162
+ }
134
163
  for (const listener of this.#leadershipListeners) {
135
164
  try {
136
165
  listener(state);
@@ -160,7 +189,7 @@ export class SyncClientHandle {
160
189
  else if (event.kind === 'presence') {
161
190
  for (const listener of this.#presence) {
162
191
  try {
163
- listener(event.scopeKey);
192
+ listener(event.scopeKey, event.error);
164
193
  }
165
194
  catch {
166
195
  /* a UI listener must never break event dispatch */
@@ -200,7 +229,17 @@ export class SyncClientHandle {
200
229
  return this.#changes.on(listener);
201
230
  }
202
231
  onDiagnostics(listener) {
203
- return this.#diagnostics.on(listener);
232
+ const off = this.#diagnostics.on(listener);
233
+ this.#pullDiagnostics();
234
+ return off;
235
+ }
236
+ /**
237
+ * The worker pushes diagnostics only after a consumer pulled once. A handle
238
+ * that cannot reach a core has nothing to observe, so a failed pull is
239
+ * dropped.
240
+ */
241
+ #pullDiagnostics() {
242
+ void this.diagnosticsSnapshot().catch(() => undefined);
204
243
  }
205
244
  /**
206
245
  * §8.6: subscribe to presence changes — the identical surface as
@@ -264,11 +303,11 @@ export class SyncClientHandle {
264
303
  }
265
304
  return this.#core.invoke(method, args);
266
305
  }
267
- subscribe(input) {
268
- return this.#call('subscribe', [input]);
306
+ subscribe(scopes) {
307
+ return this.#call('subscribe', [scopes]);
269
308
  }
270
- subscribeMany(inputs) {
271
- return this.#call('subscribeMany', [inputs]);
309
+ subscribeMany(units) {
310
+ return this.#call('subscribeMany', [units]);
272
311
  }
273
312
  securityLifecycle() {
274
313
  return this.#call('securityLifecycle', []);
@@ -352,8 +391,8 @@ export class SyncClientHandle {
352
391
  statusSnapshot() {
353
392
  return this.#call('statusSnapshot', []);
354
393
  }
355
- async diagnosticsSnapshot(request = {}) {
356
- const snapshot = await this.#call('diagnosticsSnapshot', [request]);
394
+ async diagnosticsSnapshot() {
395
+ const snapshot = await this.#call('diagnosticsSnapshot', []);
357
396
  return withClientDiagnosticsHost(snapshot, {
358
397
  ...snapshot.host,
359
398
  kind: 'worker',
@@ -379,11 +418,11 @@ export class SyncClientHandle {
379
418
  pendingCommits() {
380
419
  return this.#call('pendingCommits', []);
381
420
  }
382
- subscriptions() {
383
- return this.#call('subscriptions', []);
421
+ units() {
422
+ return this.#call('units', []);
384
423
  }
385
- subscription(id) {
386
- return this.#call('subscription', [id]);
424
+ unit(id) {
425
+ return this.#call('unit', [id]);
387
426
  }
388
427
  connectRealtime() {
389
428
  return this.#call('connectRealtime', []);
@@ -402,6 +441,10 @@ export class SyncClientHandle {
402
441
  uploadBlob(bytes, options) {
403
442
  return this.#call('uploadBlob', [bytes, options]);
404
443
  }
444
+ /** Serialize a BlobRef to the canonical string a `blob_ref` column holds. */
445
+ blobRefString(ref) {
446
+ return serializeBlobRef(ref);
447
+ }
405
448
  fetchBlob(blobIdOrRef) {
406
449
  return this.#call('fetchBlob', [blobIdOrRef]);
407
450
  }
@@ -461,7 +504,15 @@ export class SyncClientHandle {
461
504
  */
462
505
  async function startWorkerCore(options) {
463
506
  const { config, initConfig, lease } = options;
464
- const worker = config.worker();
507
+ let worker;
508
+ try {
509
+ worker = config.worker();
510
+ }
511
+ catch (error) {
512
+ // No worker exists to terminate; the lease is the only thing held.
513
+ await lease.release();
514
+ throw error;
515
+ }
465
516
  const pending = new Map();
466
517
  const nextId = { value: 1 };
467
518
  let terminated = false;
@@ -546,6 +597,9 @@ async function startWorkerCore(options) {
546
597
  config: initConfig,
547
598
  });
548
599
  });
600
+ // A config callback is a consumer from the first round.
601
+ if (config.onDiagnostics !== undefined)
602
+ await invoke('diagnosticsSnapshot', []);
549
603
  return {
550
604
  clientId: initResult.clientId,
551
605
  invoke,
@@ -596,6 +650,9 @@ function buildInitConfig(config, headers = config.headers) {
596
650
  ...(config.realtimePolicy !== undefined
597
651
  ? { realtimePolicy: config.realtimePolicy }
598
652
  : {}),
653
+ ...(config.realtimeHeartbeatMs !== undefined
654
+ ? { realtimeHeartbeatMs: config.realtimeHeartbeatMs }
655
+ : {}),
599
656
  ...(config.previousVersionContext !== undefined
600
657
  ? { previousVersionContext: config.previousVersionContext }
601
658
  : {}),
@@ -614,7 +671,7 @@ function fireConfigCallbacks(config, event) {
614
671
  config.onUpgrading?.(event.upgrading);
615
672
  }
616
673
  else if (event.kind === 'presence') {
617
- config.onPresence?.(event.scopeKey);
674
+ config.onPresence?.(event.scopeKey, event.error);
618
675
  }
619
676
  else if (event.kind === 'synced') {
620
677
  config.onSynced?.({
@@ -783,7 +840,7 @@ function resolveReplicaConfig(config) {
783
840
  if (config.replica?.mode !== 'isolated')
784
841
  return config;
785
842
  if (config.database.mode !== 'persistent') {
786
- throw new ClientSyncError('sync.invalid_request', 'isolated browser replicas require a named persistent database');
843
+ throw invalidRequest('isolated browser replicas require a named persistent database');
787
844
  }
788
845
  const names = isolatedReplicaNames({
789
846
  databaseName: config.database.name,
@@ -1,4 +1,4 @@
1
- import { ClientSyncError } from './errors.js';
1
+ import { ClientSyncError, invalidRequest } from './errors.js';
2
2
  import { LOCAL_AUTHORITY_UNCONFIGURED_CODE } from './worker-protocol.js';
3
3
  /** §12 behavior loaded by the authority-enabled worker entry. */
4
4
  export const createWorkerLocalAuthority = (context) => {
@@ -58,7 +58,7 @@ export const createWorkerLocalAuthority = (context) => {
58
58
  if (active())
59
59
  return local.downloadSegment(request);
60
60
  if (segments === undefined) {
61
- throw new ClientSyncError('sync.invalid_request', 'no segment endpoint configured');
61
+ throw invalidRequest('no segment endpoint configured');
62
62
  }
63
63
  return segments(request);
64
64
  },
@@ -17,9 +17,9 @@ import type { SyncProgress } from './progress.js';
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.js';
22
- import type { ConflictRecord, CurrentBaseProof, ClientSnapshotMethods, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleOptions, SyncIdleResult, WindowState } from './client.js';
22
+ import type { ConflictRecord, CurrentBaseProof, ClientSnapshotMethods, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleOptions, SyncIdleResult, WindowState } from './client.js';
23
23
  import type { SqlRow, SqlValue } from './database.js';
24
24
  import type { ClientDiagnosticsSnapshot, RealtimePolicy } from './diagnostics.js';
25
25
  import type { EncryptionKeyringConfig } from './encryption.js';
@@ -30,7 +30,8 @@ import type { OutboxCommit } from './outbox.js';
30
30
  import type { CommitOutcome } from './outcomes.js';
31
31
  import type { PreviousVersionAudit, PreviousVersionReadSpec, PreviousVersionSnapshot } from './previous-version.js';
32
32
  import type { ClientSchema } from './schema.js';
33
- import type { SubscriptionRecord } from './state.js';
33
+ import type { UnitScopes } from '@syncular/core';
34
+ import type { UnitRecord } from './state.js';
34
35
  import type { WindowBase } from './window.js';
35
36
  /** The handle exists but this tab lost the leader election. */
36
37
  export declare const NOT_LEADER_CODE = "client.not_leader";
@@ -107,6 +108,8 @@ export interface WorkerInitConfig {
107
108
  * Absent ⇒ `optional` (a connected socket, otherwise `POST /sync`).
108
109
  */
109
110
  readonly realtimePolicy?: RealtimePolicy;
111
+ /** SPEC §8.5 heartbeat interval for the worker-owned core; forwarded verbatim. */
112
+ readonly realtimeHeartbeatMs?: number;
110
113
  /**
111
114
  * RFC 0005 previous-version context, forwarded verbatim into the worker's
112
115
  * `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
@@ -131,12 +134,12 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
131
134
  securityLifecycle(): SecurityLifecycle;
132
135
  beginSecurityPreflight(): Promise<void>;
133
136
  activateSecurity(options?: WorkerSecurityActivation): Promise<void>;
134
- subscribe(input: SubscribeInput): void;
135
- subscribeMany(inputs: readonly SubscribeInput[]): void;
137
+ subscribe(scopes: UnitScopes): string;
138
+ subscribeMany(units: readonly UnitScopes[]): string[];
136
139
  unsubscribe(id: string): void;
137
- /** §4.8 windowed subscriptions: set the live units for a window base. */
140
+ /** §4.8 windows: set the windowed-in values of a base. */
138
141
  setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
139
- /** §4.8 completeness oracle (I3): the windowed-in units for a base. */
142
+ /** §4.8 completeness oracle: the windowed-in values of a base. */
140
143
  windowState(base: WindowBase): WindowState;
141
144
  mutate(mutations: readonly MutationInput[]): string;
142
145
  /** Partial-update convenience: read-merge-write one full-row upsert. */
@@ -165,8 +168,8 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
165
168
  querySnapshot(spec: QueryReadSpec): QuerySnapshot;
166
169
  localRevision(): LocalRevision;
167
170
  pendingCommits(): OutboxCommit[];
168
- subscriptions(): SubscriptionRecord[];
169
- subscription(id: string): SubscriptionRecord | undefined;
171
+ units(): UnitRecord[];
172
+ unit(id: string): UnitRecord | undefined;
170
173
  connectRealtime(): Promise<void>;
171
174
  disconnectRealtime(): void;
172
175
  /** §8.6 presence: publish/clear a scope-keyed presence document. */
@@ -231,9 +234,11 @@ export type SyncWorkerEvent = {
231
234
  readonly kind: 'upgrading';
232
235
  readonly upgrading: boolean;
233
236
  } | {
234
- /** §8.6: presence on a scope key changed inside the worker. */
237
+ /** §8.6: presence on a scope key changed, or the server refused this
238
+ * client's publish on it (`error`, §8.6.2). */
235
239
  readonly kind: 'presence';
236
240
  readonly scopeKey: string;
241
+ readonly error?: PresenceErrorCode | undefined;
237
242
  } | {
238
243
  /** Exact revisioned core transaction; Sets and bigint clone directly. */
239
244
  readonly kind: 'change';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.58.0",
3
+ "version": "0.60.0",
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",
@@ -89,6 +89,14 @@
89
89
  "types": "./dist/authority.d.ts",
90
90
  "default": "./dist/authority.js"
91
91
  }
92
+ },
93
+ "./native-bridge": {
94
+ "bun": "./src/native-bridge.ts",
95
+ "browser": "./dist/native-bridge.js",
96
+ "import": {
97
+ "types": "./dist/native-bridge.d.ts",
98
+ "default": "./dist/native-bridge.js"
99
+ }
92
100
  }
93
101
  },
94
102
  "files": [
@@ -105,11 +113,11 @@
105
113
  },
106
114
  "dependencies": {
107
115
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
108
- "@syncular/core": "0.58.0"
116
+ "@syncular/core": "0.60.0"
109
117
  },
110
118
  "devDependencies": {
111
119
  "@electric-sql/pglite": "^0.5.4",
112
- "@syncular/server": "0.58.0",
120
+ "@syncular/server": "0.60.0",
113
121
  "playwright": "1.63.0",
114
122
  "vite": "8.3.4"
115
123
  }