@syncular/client 0.91.0 → 0.93.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/src/encryption.ts CHANGED
@@ -19,6 +19,7 @@ import {
19
19
  type PlainValue,
20
20
  type RowColumn,
21
21
  type RowValue,
22
+ definedObject,
22
23
  } from '@syncular/core';
23
24
  import { invalidRequest } from './errors';
24
25
  import type { CompiledClientTable } from './schema';
@@ -90,12 +91,10 @@ export function encryptionConfigFromKeyring(
90
91
  // and take the clean DecryptError path.
91
92
  keyProvider: (keyId) =>
92
93
  Object.hasOwn(keyring.keys, keyId) ? keyring.keys[keyId] : undefined,
93
- ...(keyring.keyIdColumns !== undefined
94
- ? { keyIdColumns: keyring.keyIdColumns }
95
- : {}),
96
- ...(keyring.missingKey !== undefined
97
- ? { missingKey: keyring.missingKey }
98
- : {}),
94
+ ...definedObject({
95
+ keyIdColumns: keyring.keyIdColumns,
96
+ missingKey: keyring.missingKey,
97
+ }),
99
98
  };
100
99
  }
101
100
 
package/src/errors.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { DecryptError } from '@syncular/core';
1
+ import { DecryptError, definedObject } from '@syncular/core';
2
2
  import type { RealtimeState } from './diagnostics';
3
3
  import { WORKER_FAILED_CODE, type WorkerErrorShape } from './worker-protocol';
4
4
 
@@ -273,12 +273,12 @@ export function toErrorShape(caught: unknown): WorkerErrorShape {
273
273
  error instanceof ClientSyncError || error instanceof DecryptError
274
274
  ? error.details
275
275
  : undefined;
276
- return {
276
+ return definedObject({
277
277
  code: error.code,
278
278
  message: error.message,
279
279
  retryable: 'retryable' in error && error.retryable === true,
280
- ...(details !== undefined ? { details } : {}),
281
- };
280
+ details,
281
+ });
282
282
  }
283
283
  return {
284
284
  code: WORKER_FAILED_CODE,
package/src/http.ts CHANGED
@@ -5,6 +5,7 @@
5
5
  * protocol core conformance uses loopback.
6
6
  */
7
7
  import type { BlobTransport } from './blob';
8
+ import { definedObject } from '@syncular/core';
8
9
  import { SSP2_CONTENT_TYPE } from './content-type';
9
10
  import { ClientSyncError, transportFailed } from './errors';
10
11
  import { hexToBytes } from './schema';
@@ -38,7 +39,7 @@ async function transfer<T>(
38
39
  : 'unknown';
39
40
  throw transportFailed(message, {
40
41
  causeKind,
41
- ...(httpStatus !== undefined ? { httpStatus } : {}),
42
+ ...definedObject({ httpStatus }),
42
43
  });
43
44
  }
44
45
  }
@@ -127,7 +128,7 @@ export function httpSyncTransport(
127
128
  ...hostHeaders(options),
128
129
  },
129
130
  body: request.slice().buffer as ArrayBuffer,
130
- ...(signal !== undefined ? { signal } : {}),
131
+ ...definedObject({ signal }),
131
132
  }),
132
133
  );
133
134
  if (!response.ok) await throwHttpError(response);
@@ -326,7 +327,7 @@ export function httpSegmentDownloader(
326
327
  'X-Syncular-Scopes': request.requestedScopesJson,
327
328
  ...hostHeaders(options),
328
329
  },
329
- ...(request.signal !== undefined ? { signal: request.signal } : {}),
330
+ ...definedObject({ signal: request.signal }),
330
331
  },
331
332
  request.onProgress,
332
333
  false,
@@ -338,14 +339,7 @@ export function httpSegmentDownloader(
338
339
  onProgress?: (bytesReceived: number) => void,
339
340
  signal?: AbortSignal,
340
341
  byteLength?: number,
341
- ) =>
342
- download(
343
- url,
344
- signal !== undefined ? { signal } : undefined,
345
- onProgress,
346
- true,
347
- byteLength,
348
- );
342
+ ) => download(url, signal && { signal }, onProgress, true, byteLength);
349
343
  return Object.assign(direct, { fetchUrl });
350
344
  }
351
345
 
@@ -372,7 +366,7 @@ export function httpBlobTransport(
372
366
  ...hostHeaders(options),
373
367
  },
374
368
  body: bytes.slice().buffer as ArrayBuffer,
375
- ...(signal !== undefined ? { signal } : {}),
369
+ ...definedObject({ signal }),
376
370
  }),
377
371
  );
378
372
  if (!response.ok) await throwHttpError(response);
@@ -444,9 +438,9 @@ export function httpBlobTransport(
444
438
  },
445
439
  body: JSON.stringify({
446
440
  byteLength,
447
- ...(mediaType !== undefined ? { mediaType } : {}),
441
+ mediaType,
448
442
  }),
449
- ...(signal !== undefined ? { signal } : {}),
443
+ ...definedObject({ signal }),
450
444
  }),
451
445
  );
452
446
  if (!response.ok) await throwHttpError(response);
@@ -482,7 +476,7 @@ export function httpBlobTransport(
482
476
  'x-amz-checksum-sha256': checksum,
483
477
  },
484
478
  body,
485
- ...(signal !== undefined ? { signal } : {}),
479
+ ...definedObject({ signal }),
486
480
  }),
487
481
  );
488
482
  if (!response.ok) {
package/src/multi-tab.ts CHANGED
@@ -97,9 +97,10 @@ export const TAKEOVER_REFUSED_CODE = 'client.takeover_refused';
97
97
  /**
98
98
  * Version of the leader/follower wire and the forwarded handle API. Bump it
99
99
  * with every change to a message shape or to a forwarded method's arguments
100
- * or result, so tabs of different builds never serve each other.
100
+ * or result, so tabs of different builds never serve each other;
101
+ * test/multi-tab-protocol.test.ts pins the surface's fingerprint to it.
101
102
  */
102
- export const MULTI_TAB_PROTOCOL_VERSION = 3;
103
+ export const MULTI_TAB_PROTOCOL_VERSION = 4;
103
104
 
104
105
  /** What a tab must share with its leader to be served by it. */
105
106
  export interface TabIdentity {
@@ -326,6 +326,8 @@ interface CachedObservation {
326
326
  reclaim?(): void;
327
327
  /** A leader serves this tab again (it leads or follows a bound leader). */
328
328
  reread(): void;
329
+ /** The running sync attempt stopped importing (SPEC §7.8). */
330
+ imported?(): void;
329
331
  reset(): void;
330
332
  dispose(): void;
331
333
  }
@@ -373,6 +375,9 @@ class ObservationCache {
373
375
  reread(): void {
374
376
  for (const entry of this.#active) entry.reread();
375
377
  }
378
+ imported(): void {
379
+ for (const entry of this.#active) entry.imported?.();
380
+ }
376
381
  clear(): void {
377
382
  for (const entry of this.#entries.values()) entry.dispose();
378
383
  this.#entries.clear();
@@ -438,6 +443,14 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
438
443
  #running = false;
439
444
  #requested = false;
440
445
  #desiredRevision = 0n;
446
+ /** SPEC §7.8: the newest matching revision an incomplete answer may not lag. */
447
+ #currentRevision = 0n;
448
+ #complete = false;
449
+ /** Incomplete units of the last answer no window change has named since. */
450
+ #waiting = new Set<string>();
451
+ /** Units window changes named since the running read started. */
452
+ #named = new Set<string>();
453
+ #deferred = false;
441
454
  #claimError: Error | undefined;
442
455
  #claimPending = false;
443
456
  #claimGated = false;
@@ -553,6 +566,11 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
553
566
  this.#running = false;
554
567
  this.#requested = false;
555
568
  this.#desiredRevision = 0n;
569
+ this.#currentRevision = 0n;
570
+ this.#complete = false;
571
+ this.#waiting = new Set();
572
+ this.#named = new Set();
573
+ this.#deferred = false;
556
574
  this.#claimError = undefined;
557
575
  this.#claimPending = false;
558
576
  this.#claimGated = false;
@@ -586,11 +604,32 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
586
604
  else this.#requestRead();
587
605
  }
588
606
 
607
+ imported(): void {
608
+ if (!this.#deferred) return;
609
+ this.#deferred = false;
610
+ this.#requestRead();
611
+ }
612
+
589
613
  onChange(batch: ClientChangeBatch): void {
590
614
  if (!batchMatches(batch, this.spec)) return;
591
615
  if (batch.revision > this.#desiredRevision) {
592
616
  this.#desiredRevision = batch.revision;
593
617
  }
618
+ // SPEC §7.8: while an attempt imports, an incomplete answer waits for
619
+ // the import unless the batch carries status (a local write) or names
620
+ // the last of its incomplete units.
621
+ for (const change of batch.windows)
622
+ for (const unit of change.units) {
623
+ this.#waiting.delete(`${change.baseKey}\0${unit}`);
624
+ this.#named.add(`${change.baseKey}\0${unit}`);
625
+ }
626
+ const lag =
627
+ this.store.importing &&
628
+ !this.#complete &&
629
+ batch.status === undefined &&
630
+ (batch.windows.length === 0 || this.#waiting.size > 0);
631
+ if (!lag && batch.revision > this.#currentRevision)
632
+ this.#currentRevision = batch.revision;
594
633
  if (this.#listeners.size === 0) return;
595
634
  // A committed row change of a dependency claims again; a window-only
596
635
  // batch, which a failed window edit can itself produce, does not.
@@ -600,7 +639,9 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
600
639
  ),
601
640
  );
602
641
  if (rowChange && this.#claimError !== undefined) this.reclaim();
603
- else this.#requestRead();
642
+ else if (lag) this.#deferred ||= !this.#running;
643
+ // A running read reads again only when its snapshot predates the batch.
644
+ else if (!this.#running) this.#requestRead();
604
645
  }
605
646
 
606
647
  #publish(next: LiveQueryResult<Row>): void {
@@ -743,9 +784,13 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
743
784
  if (this.#running || this.#listeners.size === 0) return;
744
785
  const generation = this.#generation;
745
786
  this.#running = true;
787
+ let asked = this.#desiredRevision;
746
788
  try {
747
789
  do {
748
790
  this.#requested = false;
791
+ this.#deferred = false;
792
+ this.#named.clear();
793
+ asked = this.#desiredRevision;
749
794
  if (localReadsBlocked(this.store.availabilitySnapshot())) break;
750
795
 
751
796
  if (generation !== this.#generation || this.#listeners.size === 0)
@@ -783,9 +828,22 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
783
828
  break;
784
829
  }
785
830
  if (snapshot.revision < this.#desiredRevision) {
786
- this.#requested = true;
787
- continue;
831
+ if (
832
+ snapshot.coverage.complete ||
833
+ snapshot.revision < this.#currentRevision ||
834
+ !this.store.importing
835
+ ) {
836
+ this.#requested = true;
837
+ continue;
838
+ }
839
+ this.#deferred = true;
788
840
  }
841
+ this.#complete = snapshot.coverage.complete;
842
+ this.#waiting = new Set(
843
+ [...snapshot.coverage.pending, ...snapshot.coverage.missing]
844
+ .map((ref) => `${ref.baseKey}\0${ref.unit}`)
845
+ .filter((key) => !this.#named.has(key)),
846
+ );
789
847
  if (
790
848
  !snapshot.coverage.complete &&
791
849
  claimWasPending &&
@@ -827,6 +885,8 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
827
885
  this.#gate();
828
886
  return;
829
887
  }
888
+ // A batch that arrived during the failed read reads again.
889
+ if (this.#desiredRevision > asked) this.#requested = true;
830
890
  // SPEC §7.5: a failed latest read is never `ready`; the last
831
891
  // successful rows and revision stay available beside the error.
832
892
  this.#publish({
@@ -1024,8 +1084,14 @@ export class ReactiveClientStore {
1024
1084
  readonly outcomes: ExternalStoreEntry<OutcomeStoreSnapshot>;
1025
1085
  /** The latest sync attempt's failure until the next attempt starts. */
1026
1086
  readonly roundFailure: ExternalStoreEntry<SyncRoundFailedError | undefined>;
1087
+ #importing = false;
1027
1088
  #offProgress: (() => void) | undefined;
1028
1089
 
1090
+ /** SPEC §7.8: a running sync attempt downloads or imports a response. */
1091
+ get importing(): boolean {
1092
+ return this.#importing;
1093
+ }
1094
+
1029
1095
  constructor(readonly client: ReactiveQueryClient) {
1030
1096
  const status = new ValueEntry<StatusStoreSnapshot>(
1031
1097
  {
@@ -1348,6 +1414,12 @@ export class ReactiveClientStore {
1348
1414
  >;
1349
1415
  let claimedAttempt: number | undefined;
1350
1416
  this.#offProgress = this.client.onProgress((progress) => {
1417
+ const importing =
1418
+ progress.state === 'running' && progress.phase !== 'request';
1419
+ if (this.#importing !== importing) {
1420
+ this.#importing = importing;
1421
+ if (!importing) this.#queries.imported();
1422
+ }
1351
1423
  // A new sync attempt is the client's retry schedule (§7.7): window
1352
1424
  // claims that failed are claimed again once per attempt.
1353
1425
  if (progress.state === 'running' && progress.attempt !== claimedAttempt) {
@@ -1407,6 +1479,7 @@ export class ReactiveClientStore {
1407
1479
  this.#offLeadership = undefined;
1408
1480
  this.#offProgress?.();
1409
1481
  this.#offProgress = undefined;
1482
+ this.#importing = false;
1410
1483
  (this.roundFailure as ValueEntry<SyncRoundFailedError | undefined>).set(
1411
1484
  undefined,
1412
1485
  );
package/src/schema.ts CHANGED
@@ -16,7 +16,7 @@ import { ensureFailedOverlaySchema, RETAINED_ROWS } from './failed-overlay';
16
16
  * DDL, the generated row codec, mutation helpers, and the §3.3 purge
17
17
  * mapping (scope variable → local column).
18
18
  */
19
- import type { RowColumn, RowValue } from '@syncular/core';
19
+ import { definedObject, type RowColumn, type RowValue } from '@syncular/core';
20
20
  import type { ClientDatabase, SqlRow, SqlValue } from './database';
21
21
  import { invalidRequest, localStateCorrupt } from './errors';
22
22
  import { snakeToCamel } from './naming';
@@ -250,9 +250,7 @@ export function compileClientSchema(
250
250
  }
251
251
  tables.set(table.name, {
252
252
  name: table.name,
253
- ...(table.generation !== undefined
254
- ? { generation: table.generation }
255
- : {}),
253
+ ...definedObject({ generation: table.generation }),
256
254
  columns: table.columns,
257
255
  primaryKey: table.primaryKey,
258
256
  primaryKeyIndex,
@@ -13,6 +13,7 @@
13
13
  * RPC-driven and auto-driven sync rounds serialize on one queue because
14
14
  * the core owns exactly one loop.
15
15
  */
16
+ import { definedObject } from '@syncular/core';
16
17
  import type { defineAuthorityReads } from './authority';
17
18
  import { SyncClient } from './client';
18
19
  import type { ClientDatabase } from './database';
@@ -409,11 +410,8 @@ export function startSyncWorkerCore(
409
410
  // Retain the leader lease while the previous worker's OPFS handles
410
411
  // drain. Only opening is retried; core initialization has not started.
411
412
  const delayMs = Math.min(50 * 2 ** attempt, 1000);
412
- if (overrides.waitForStorageRetry !== undefined) {
413
- await overrides.waitForStorageRetry(delayMs);
414
- } else {
415
- await new Promise<void>((resolve) => setTimeout(resolve, delayMs));
416
- }
413
+ await (overrides.waitForStorageRetry?.(delayMs) ??
414
+ new Promise<void>((resolve) => setTimeout(resolve, delayMs)));
417
415
  }
418
416
  }
419
417
  const remote =
@@ -442,14 +440,26 @@ export function startSyncWorkerCore(
442
440
  let realtimeConnector: RealtimeConnector | undefined;
443
441
  offline = config.transportEnabled === false;
444
442
  const started = new SyncClient({
443
+ ...definedObject({
444
+ segments: bindings.segments,
445
+ blobs,
446
+ clientId: config.clientId,
447
+ limits: config.limits,
448
+ retainFailedCommits: config.retainFailedCommits,
449
+ realtimePolicy: config.realtimePolicy,
450
+ realtimeHeartbeatMs: config.realtimeHeartbeatMs,
451
+ encryption:
452
+ config.encryption && encryptionConfigFromKeyring(config.encryption),
453
+ authorityReads:
454
+ config.authorityReads &&
455
+ overrides.createAuthorityReads!(config.authorityReads),
456
+ securityPreflight: config.securityPreflight,
457
+ previousVersionContext: config.previousVersionContext,
458
+ }),
445
459
  transportEnabled: !offline,
446
460
  database,
447
461
  schema: config.schema,
448
462
  transport: bindings.transport,
449
- ...(bindings.segments !== undefined
450
- ? { segments: bindings.segments }
451
- : {}),
452
- ...(blobs !== undefined ? { blobs } : {}),
453
463
  realtime: (handlers, clientId) => {
454
464
  // §12.2: a local authority has no realtime channel.
455
465
  if (realtimeConnector === undefined || local?.active()) {
@@ -457,34 +467,7 @@ export function startSyncWorkerCore(
457
467
  }
458
468
  return realtimeConnector(handlers, clientId);
459
469
  },
460
- ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
461
- ...(config.limits !== undefined ? { limits: config.limits } : {}),
462
- ...(config.retainFailedCommits !== undefined
463
- ? { retainFailedCommits: config.retainFailedCommits }
464
- : {}),
465
- ...(config.realtimePolicy !== undefined
466
- ? { realtimePolicy: config.realtimePolicy }
467
- : {}),
468
- ...(config.realtimeHeartbeatMs !== undefined
469
- ? { realtimeHeartbeatMs: config.realtimeHeartbeatMs }
470
- : {}),
471
470
  schedule: scheduleBackground,
472
- ...(config.encryption !== undefined
473
- ? { encryption: encryptionConfigFromKeyring(config.encryption) }
474
- : {}),
475
- ...(config.authorityReads !== undefined
476
- ? {
477
- authorityReads: overrides.createAuthorityReads!(
478
- config.authorityReads,
479
- ),
480
- }
481
- : {}),
482
- ...(config.securityPreflight !== undefined
483
- ? { securityPreflight: config.securityPreflight }
484
- : {}),
485
- ...(config.previousVersionContext !== undefined
486
- ? { previousVersionContext: config.previousVersionContext }
487
- : {}),
488
471
  onSyncNeeded: (reason) => {
489
472
  emit({ kind: 'sync-needed', reason });
490
473
  consumeSyncIntent({ kind: 'interactive' });
@@ -731,10 +714,11 @@ async function defaultOpenDatabase(
731
714
  "database mode 'custom' requires startSyncWorker({ openDatabase })",
732
715
  );
733
716
  }
734
- return openPersistentWasmDatabase(config.database.name, {
735
- ...(config.database.directory !== undefined
736
- ? { directory: config.database.directory }
737
- : {}),
738
- ...(config.takeOverStorage === true ? { takeOver: true } : {}),
739
- });
717
+ return openPersistentWasmDatabase(
718
+ config.database.name,
719
+ definedObject({
720
+ directory: config.database.directory,
721
+ takeOver: config.takeOverStorage || undefined,
722
+ }),
723
+ );
740
724
  }