@syncular/client 0.92.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.
@@ -86,6 +86,8 @@ export declare class ReactiveClientStore {
86
86
  readonly outcomes: ExternalStoreEntry<OutcomeStoreSnapshot>;
87
87
  /** The latest sync attempt's failure until the next attempt starts. */
88
88
  readonly roundFailure: ExternalStoreEntry<SyncRoundFailedError | undefined>;
89
+ /** SPEC §7.8: a running sync attempt downloads or imports a response. */
90
+ get importing(): boolean;
89
91
  constructor(client: ReactiveQueryClient);
90
92
  query<Row>(spec: ReactiveQuerySpec<Row>): ExternalStoreEntry<LiveQueryResult<Row>>;
91
93
  availabilitySnapshot(): SyncAvailability;
@@ -241,6 +241,10 @@ class ObservationCache {
241
241
  for (const entry of this.#active)
242
242
  entry.reread();
243
243
  }
244
+ imported() {
245
+ for (const entry of this.#active)
246
+ entry.imported?.();
247
+ }
244
248
  clear() {
245
249
  for (const entry of this.#entries.values())
246
250
  entry.dispose();
@@ -299,6 +303,14 @@ class QueryEntry {
299
303
  #running = false;
300
304
  #requested = false;
301
305
  #desiredRevision = 0n;
306
+ /** SPEC §7.8: the newest matching revision an incomplete answer may not lag. */
307
+ #currentRevision = 0n;
308
+ #complete = false;
309
+ /** Incomplete units of the last answer no window change has named since. */
310
+ #waiting = new Set();
311
+ /** Units window changes named since the running read started. */
312
+ #named = new Set();
313
+ #deferred = false;
302
314
  #claimError;
303
315
  #claimPending = false;
304
316
  #claimGated = false;
@@ -405,6 +417,11 @@ class QueryEntry {
405
417
  this.#running = false;
406
418
  this.#requested = false;
407
419
  this.#desiredRevision = 0n;
420
+ this.#currentRevision = 0n;
421
+ this.#complete = false;
422
+ this.#waiting = new Set();
423
+ this.#named = new Set();
424
+ this.#deferred = false;
408
425
  this.#claimError = undefined;
409
426
  this.#claimPending = false;
410
427
  this.#claimGated = false;
@@ -437,12 +454,32 @@ class QueryEntry {
437
454
  else
438
455
  this.#requestRead();
439
456
  }
457
+ imported() {
458
+ if (!this.#deferred)
459
+ return;
460
+ this.#deferred = false;
461
+ this.#requestRead();
462
+ }
440
463
  onChange(batch) {
441
464
  if (!batchMatches(batch, this.spec))
442
465
  return;
443
466
  if (batch.revision > this.#desiredRevision) {
444
467
  this.#desiredRevision = batch.revision;
445
468
  }
469
+ // SPEC §7.8: while an attempt imports, an incomplete answer waits for
470
+ // the import unless the batch carries status (a local write) or names
471
+ // the last of its incomplete units.
472
+ for (const change of batch.windows)
473
+ for (const unit of change.units) {
474
+ this.#waiting.delete(`${change.baseKey}\0${unit}`);
475
+ this.#named.add(`${change.baseKey}\0${unit}`);
476
+ }
477
+ const lag = this.store.importing &&
478
+ !this.#complete &&
479
+ batch.status === undefined &&
480
+ (batch.windows.length === 0 || this.#waiting.size > 0);
481
+ if (!lag && batch.revision > this.#currentRevision)
482
+ this.#currentRevision = batch.revision;
446
483
  if (this.#listeners.size === 0)
447
484
  return;
448
485
  // A committed row change of a dependency claims again; a window-only
@@ -450,6 +487,8 @@ class QueryEntry {
450
487
  const rowChange = batch.tables.some((change) => this.spec.dependencies.some((dependency) => dependency.table === change.table));
451
488
  if (rowChange && this.#claimError !== undefined)
452
489
  this.reclaim();
490
+ else if (lag)
491
+ this.#deferred ||= !this.#running;
453
492
  // A running read reads again only when its snapshot predates the batch.
454
493
  else if (!this.#running)
455
494
  this.#requestRead();
@@ -587,6 +626,8 @@ class QueryEntry {
587
626
  try {
588
627
  do {
589
628
  this.#requested = false;
629
+ this.#deferred = false;
630
+ this.#named.clear();
590
631
  asked = this.#desiredRevision;
591
632
  if (localReadsBlocked(this.store.availabilitySnapshot()))
592
633
  break;
@@ -623,9 +664,18 @@ class QueryEntry {
623
664
  break;
624
665
  }
625
666
  if (snapshot.revision < this.#desiredRevision) {
626
- this.#requested = true;
627
- continue;
667
+ if (snapshot.coverage.complete ||
668
+ snapshot.revision < this.#currentRevision ||
669
+ !this.store.importing) {
670
+ this.#requested = true;
671
+ continue;
672
+ }
673
+ this.#deferred = true;
628
674
  }
675
+ this.#complete = snapshot.coverage.complete;
676
+ this.#waiting = new Set([...snapshot.coverage.pending, ...snapshot.coverage.missing]
677
+ .map((ref) => `${ref.baseKey}\0${ref.unit}`)
678
+ .filter((key) => !this.#named.has(key)));
629
679
  if (!snapshot.coverage.complete &&
630
680
  claimWasPending &&
631
681
  !this.#claimPending)
@@ -853,7 +903,12 @@ export class ReactiveClientStore {
853
903
  outcomes;
854
904
  /** The latest sync attempt's failure until the next attempt starts. */
855
905
  roundFailure;
906
+ #importing = false;
856
907
  #offProgress;
908
+ /** SPEC §7.8: a running sync attempt downloads or imports a response. */
909
+ get importing() {
910
+ return this.#importing;
911
+ }
857
912
  constructor(client) {
858
913
  this.client = client;
859
914
  const status = new ValueEntry({
@@ -1143,6 +1198,12 @@ export class ReactiveClientStore {
1143
1198
  const roundFailure = this.roundFailure;
1144
1199
  let claimedAttempt;
1145
1200
  this.#offProgress = this.client.onProgress((progress) => {
1201
+ const importing = progress.state === 'running' && progress.phase !== 'request';
1202
+ if (this.#importing !== importing) {
1203
+ this.#importing = importing;
1204
+ if (!importing)
1205
+ this.#queries.imported();
1206
+ }
1146
1207
  // A new sync attempt is the client's retry schedule (§7.7): window
1147
1208
  // claims that failed are claimed again once per attempt.
1148
1209
  if (progress.state === 'running' && progress.attempt !== claimedAttempt) {
@@ -1194,6 +1255,7 @@ export class ReactiveClientStore {
1194
1255
  this.#offLeadership = undefined;
1195
1256
  this.#offProgress?.();
1196
1257
  this.#offProgress = undefined;
1258
+ this.#importing = false;
1197
1259
  this.roundFailure.set(undefined);
1198
1260
  for (const group of this.#windowClaims.values()) {
1199
1261
  for (const waiter of group.waiters.splice(0)) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.92.0",
3
+ "version": "0.93.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",
@@ -121,11 +121,11 @@
121
121
  },
122
122
  "dependencies": {
123
123
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
124
- "@syncular/core": "0.92.0"
124
+ "@syncular/core": "0.93.0"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.92.0",
128
+ "@syncular/server": "0.93.0",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
@@ -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,6 +639,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
600
639
  ),
601
640
  );
602
641
  if (rowChange && this.#claimError !== undefined) this.reclaim();
642
+ else if (lag) this.#deferred ||= !this.#running;
603
643
  // A running read reads again only when its snapshot predates the batch.
604
644
  else if (!this.#running) this.#requestRead();
605
645
  }
@@ -748,6 +788,8 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
748
788
  try {
749
789
  do {
750
790
  this.#requested = false;
791
+ this.#deferred = false;
792
+ this.#named.clear();
751
793
  asked = this.#desiredRevision;
752
794
  if (localReadsBlocked(this.store.availabilitySnapshot())) break;
753
795
 
@@ -786,9 +828,22 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
786
828
  break;
787
829
  }
788
830
  if (snapshot.revision < this.#desiredRevision) {
789
- this.#requested = true;
790
- 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;
791
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
+ );
792
847
  if (
793
848
  !snapshot.coverage.complete &&
794
849
  claimWasPending &&
@@ -1029,8 +1084,14 @@ export class ReactiveClientStore {
1029
1084
  readonly outcomes: ExternalStoreEntry<OutcomeStoreSnapshot>;
1030
1085
  /** The latest sync attempt's failure until the next attempt starts. */
1031
1086
  readonly roundFailure: ExternalStoreEntry<SyncRoundFailedError | undefined>;
1087
+ #importing = false;
1032
1088
  #offProgress: (() => void) | undefined;
1033
1089
 
1090
+ /** SPEC §7.8: a running sync attempt downloads or imports a response. */
1091
+ get importing(): boolean {
1092
+ return this.#importing;
1093
+ }
1094
+
1034
1095
  constructor(readonly client: ReactiveQueryClient) {
1035
1096
  const status = new ValueEntry<StatusStoreSnapshot>(
1036
1097
  {
@@ -1353,6 +1414,12 @@ export class ReactiveClientStore {
1353
1414
  >;
1354
1415
  let claimedAttempt: number | undefined;
1355
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
+ }
1356
1423
  // A new sync attempt is the client's retry schedule (§7.7): window
1357
1424
  // claims that failed are claimed again once per attempt.
1358
1425
  if (progress.state === 'running' && progress.attempt !== claimedAttempt) {
@@ -1412,6 +1479,7 @@ export class ReactiveClientStore {
1412
1479
  this.#offLeadership = undefined;
1413
1480
  this.#offProgress?.();
1414
1481
  this.#offProgress = undefined;
1482
+ this.#importing = false;
1415
1483
  (this.roundFailure as ValueEntry<SyncRoundFailedError | undefined>).set(
1416
1484
  undefined,
1417
1485
  );