@syncular/client 0.54.0 → 0.55.1

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/dist/client.js CHANGED
@@ -173,13 +173,10 @@ export class SyncClient {
173
173
  #needsPull = false;
174
174
  #progress = new ProgressEmitter();
175
175
  #progressAttempt = 0;
176
- #syncing = false;
177
176
  /**
178
177
  * True from the synchronous entry of `sync()` until its serialized round
179
178
  * settles — the "one loop owns the database" guard that rejects a
180
- * concurrent `sync()` before the op chain would queue it. Distinct from
181
- * `#syncing`, which is true only while `#runSync`'s body actually runs
182
- * (the fast-bail the delta path reads).
179
+ * concurrent `sync()` before the op chain would queue it.
183
180
  */
184
181
  #syncOutstanding = false;
185
182
  /**
@@ -2999,10 +2996,7 @@ export class SyncClient {
2999
2996
  schemaFloor: this.#schemaFloor,
3000
2997
  };
3001
2998
  }
3002
- this.#syncing = true;
3003
- // Cleared before the round, not after: a wake-up (or a delta dropped
3004
- // because this pull is mid-flight) that lands during the round must
3005
- // survive it — the reference server keeps no replay buffer (§8.2).
2999
+ // A wake-up that lands during the round must survive it (§8.4).
3006
3000
  this.#setSyncNeeded(false);
3007
3001
  try {
3008
3002
  await this.#drainPendingEvictions();
@@ -3180,9 +3174,6 @@ export class SyncClient {
3180
3174
  }
3181
3175
  throw error;
3182
3176
  }
3183
- finally {
3184
- this.#syncing = false;
3185
- }
3186
3177
  }
3187
3178
  /**
3188
3179
  * Pull repeatedly until quiescent: no commits delivered, no bootstrap
@@ -3654,19 +3645,24 @@ export class SyncClient {
3654
3645
  async #handleRealtimeBinary(bytes) {
3655
3646
  if (!this.#transportEnabled)
3656
3647
  return;
3657
- if (this.#syncing) {
3658
- // Fast path: a pull is mid-flight; let it win and recover the gap
3659
- // itself — re-pulling is idempotent, interleaved application is not
3660
- // worth it. (An optimization; the op chain below is the correctness
3661
- // mechanism — it also excludes a delta from racing a `setWindow` or a
3662
- // sync round that started between this check and the apply.)
3663
- this.#setSyncNeeded(true);
3664
- return;
3665
- }
3648
+ const resetEpoch = this.#localResetEpoch;
3649
+ const securityEpoch = this.#securityEpoch;
3650
+ const transportEpoch = this.#transportEpoch;
3666
3651
  // Serialize the apply on the operation chain: a delta must never
3667
3652
  // interleave its transactions or share the `#batch` accumulator with a
3668
3653
  // pull round or a `setWindow` at an await point (§8.2).
3669
3654
  await this.#serialize(async () => {
3655
+ if (!this.#started ||
3656
+ !this.#transportEnabled ||
3657
+ this.#securityLifecycle !== 'active' ||
3658
+ securityEpoch !== this.#securityEpoch ||
3659
+ transportEpoch !== this.#transportEpoch)
3660
+ return;
3661
+ if (resetEpoch !== this.#localResetEpoch) {
3662
+ this.#setSyncNeeded(true);
3663
+ this.#emitSyncNeeded('catchup-required');
3664
+ return;
3665
+ }
3670
3666
  try {
3671
3667
  const message = decodeMessage(bytes);
3672
3668
  if (message.msgKind !== 'response')
@@ -3942,7 +3938,9 @@ export class SyncClient {
3942
3938
  break;
3943
3939
  }
3944
3940
  case 'COMMIT':
3945
- if (section !== undefined && !section.skip) {
3941
+ if (section !== undefined &&
3942
+ !section.skip &&
3943
+ section.sub !== undefined) {
3946
3944
  const changes = frame.changes.filter((change) => {
3947
3945
  if (change.op !== 'delete')
3948
3946
  return true;
@@ -3951,7 +3949,7 @@ export class SyncClient {
3951
3949
  !coalescedDeletes.has(deleteKey(frame.commitSeq, table, change.rowId)));
3952
3950
  });
3953
3951
  if (changes.length > 0) {
3954
- await this.#applyCommit({ ...frame, changes }, summary);
3952
+ await this.#applyCommit({ ...frame, changes }, summary, section.sub.id, mode);
3955
3953
  }
3956
3954
  }
3957
3955
  break;
@@ -4261,11 +4259,20 @@ export class SyncClient {
4261
4259
  });
4262
4260
  return names;
4263
4261
  }
4264
- async #applyCommit(frame, summary) {
4262
+ async #applyCommit(frame, summary, subscriptionId, source) {
4265
4263
  await applyCommitFrame(this.#db, this.#schema, frame, this.#encryption, (fn) => this.#applyBatch((batch) => {
4266
4264
  this.#recordCommitChanges(batch, frame);
4267
4265
  const result = fn();
4268
4266
  this.#replayOutbox(result, false);
4267
+ for (const table of new Set(frame.changes.map((change) => frame.tables[change.tableIndex]))) {
4268
+ if (table !== undefined)
4269
+ batch.appliedCommit({
4270
+ subscriptionId,
4271
+ table,
4272
+ commitSeq: frame.commitSeq,
4273
+ source,
4274
+ });
4275
+ }
4269
4276
  return result;
4270
4277
  }));
4271
4278
  summary.commitsApplied += 1;
@@ -44,6 +44,13 @@ export interface ClientChangeBatch {
44
44
  readonly conflictsChanged: boolean;
45
45
  readonly rejectionsChanged: boolean;
46
46
  readonly outcomesChanged: boolean;
47
+ /** Server COMMIT frames applied by this transaction, when present. */
48
+ readonly appliedCommits?: readonly {
49
+ readonly subscriptionId: string;
50
+ readonly table: string;
51
+ readonly commitSeq: number;
52
+ readonly source: 'delta' | 'pull';
53
+ }[];
47
54
  }
48
55
  export type ClientChangeListener = (batch: ClientChangeBatch) => void;
49
56
  /** Network work created by a core command (SPEC §7.5). */
@@ -69,6 +76,7 @@ export declare const NO_COMMAND_EFFECTS: CommandEffects;
69
76
  */
70
77
  export declare class ChangeAccumulator {
71
78
  #private;
79
+ appliedCommit(entry: NonNullable<ClientChangeBatch['appliedCommits']>[number]): void;
72
80
  /** Mark a whole table dirty, discarding any weaker scope-only facts. */
73
81
  table(name: string): void;
74
82
  /** Associate a precise `prefix:value` key with its table. */
@@ -12,6 +12,10 @@ export class ChangeAccumulator {
12
12
  #conflicts = false;
13
13
  #rejections = false;
14
14
  #outcomes = false;
15
+ #appliedCommits = [];
16
+ appliedCommit(entry) {
17
+ this.#appliedCommits.push(entry);
18
+ }
15
19
  /** Mark a whole table dirty, discarding any weaker scope-only facts. */
16
20
  table(name) {
17
21
  this.#tables.set(name, { tableWide: true, scopeKeys: undefined });
@@ -113,6 +117,9 @@ export class ChangeAccumulator {
113
117
  conflictsChanged: this.#conflicts,
114
118
  rejectionsChanged: this.#rejections,
115
119
  outcomesChanged: this.#outcomes,
120
+ ...(this.#appliedCommits.length > 0
121
+ ? { appliedCommits: this.#appliedCommits }
122
+ : {}),
116
123
  };
117
124
  }
118
125
  }
package/dist/multi-tab.js CHANGED
@@ -716,6 +716,7 @@ export async function createTabCoordinator(config) {
716
716
  let leading;
717
717
  let follower;
718
718
  let closed = false;
719
+ let closing;
719
720
  let takingOver = false;
720
721
  /** Start of the current `leader-unreachable` period. */
721
722
  let unreachableSince;
@@ -925,21 +926,22 @@ export async function createTabCoordinator(config) {
925
926
  takingOver = false;
926
927
  }
927
928
  },
928
- close: async () => {
929
- if (closed)
930
- return;
931
- closed = true;
932
- endUnreachable('closed');
933
- follower?.close();
934
- follower = undefined;
935
- const ending = leading;
936
- leading = undefined;
937
- if (ending !== undefined) {
938
- ending.end();
939
- await ending.leader.close();
940
- await ending.lease.release();
941
- }
942
- await tabLease.release();
929
+ close: () => {
930
+ closing ??= (async () => {
931
+ closed = true;
932
+ endUnreachable('closed');
933
+ follower?.close();
934
+ follower = undefined;
935
+ const ending = leading;
936
+ leading = undefined;
937
+ if (ending !== undefined) {
938
+ ending.end();
939
+ await ending.leader.close();
940
+ await ending.lease.release();
941
+ }
942
+ await tabLease.release();
943
+ })();
944
+ return closing;
943
945
  },
944
946
  };
945
947
  // Leadership before any core exists: a losing tab never starts one.
@@ -313,7 +313,10 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
313
313
  attachLocalAuthority(): Promise<void>;
314
314
  /** SPEC §12.3: delete the rows a stopped attach uploaded, then sync locally. */
315
315
  abandonLocalAuthorityAttach(): Promise<void>;
316
- /** Close the core (leader) or the link (follower), release leadership. */
316
+ /**
317
+ * Close the core (leader) or the link (follower), release leadership. Every
318
+ * call returns the same promise, which settles with the one close.
319
+ */
317
320
  close(): Promise<void>;
318
321
  }
319
322
  /**
@@ -80,6 +80,7 @@ export class SyncClientHandle {
80
80
  #unreachableListeners;
81
81
  #devtoolsUnregister;
82
82
  #closed = false;
83
+ #closing;
83
84
  /** @internal — use {@link createSyncClientHandle}. */
84
85
  constructor(internals) {
85
86
  this.#role = internals.role;
@@ -435,19 +436,23 @@ export class SyncClientHandle {
435
436
  abandonLocalAuthorityAttach() {
436
437
  return this.#call('abandonLocalAuthorityAttach', []);
437
438
  }
438
- /** Close the core (leader) or the link (follower), release leadership. */
439
- async close() {
440
- if (this.#closed)
441
- return;
442
- this.#closed = true;
443
- this.#progress.clear();
444
- this.#devtoolsUnregister?.();
445
- await this.#tabs?.close();
446
- if (this.#core !== undefined) {
447
- const core = this.#core;
448
- this.#core = undefined;
449
- await core.close();
450
- }
439
+ /**
440
+ * Close the core (leader) or the link (follower), release leadership. Every
441
+ * call returns the same promise, which settles with the one close.
442
+ */
443
+ close() {
444
+ this.#closing ??= (async () => {
445
+ this.#closed = true;
446
+ this.#progress.clear();
447
+ this.#devtoolsUnregister?.();
448
+ await this.#tabs?.close();
449
+ if (this.#core !== undefined) {
450
+ const core = this.#core;
451
+ this.#core = undefined;
452
+ await core.close();
453
+ }
454
+ })();
455
+ return this.#closing;
451
456
  }
452
457
  }
453
458
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.54.0",
3
+ "version": "0.55.1",
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",
@@ -105,11 +105,11 @@
105
105
  },
106
106
  "dependencies": {
107
107
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
108
- "@syncular/core": "0.54.0"
108
+ "@syncular/core": "0.55.1"
109
109
  },
110
110
  "devDependencies": {
111
111
  "@electric-sql/pglite": "^0.5.4",
112
- "@syncular/server": "0.54.0",
112
+ "@syncular/server": "0.55.1",
113
113
  "playwright": "1.63.0",
114
114
  "vite": "8.3.4"
115
115
  }
package/src/client.ts CHANGED
@@ -922,13 +922,10 @@ export class SyncClient {
922
922
  #needsPull = false;
923
923
  readonly #progress = new ProgressEmitter();
924
924
  #progressAttempt = 0;
925
- #syncing = false;
926
925
  /**
927
926
  * True from the synchronous entry of `sync()` until its serialized round
928
927
  * settles — the "one loop owns the database" guard that rejects a
929
- * concurrent `sync()` before the op chain would queue it. Distinct from
930
- * `#syncing`, which is true only while `#runSync`'s body actually runs
931
- * (the fast-bail the delta path reads).
928
+ * concurrent `sync()` before the op chain would queue it.
932
929
  */
933
930
  #syncOutstanding = false;
934
931
  /**
@@ -4347,10 +4344,7 @@ export class SyncClient {
4347
4344
  schemaFloor: this.#schemaFloor,
4348
4345
  };
4349
4346
  }
4350
- this.#syncing = true;
4351
- // Cleared before the round, not after: a wake-up (or a delta dropped
4352
- // because this pull is mid-flight) that lands during the round must
4353
- // survive it — the reference server keeps no replay buffer (§8.2).
4347
+ // A wake-up that lands during the round must survive it (§8.4).
4354
4348
  this.#setSyncNeeded(false);
4355
4349
  try {
4356
4350
  await this.#drainPendingEvictions();
@@ -4554,8 +4548,6 @@ export class SyncClient {
4554
4548
  this.#emitSyncIntent(intent);
4555
4549
  }
4556
4550
  throw error;
4557
- } finally {
4558
- this.#syncing = false;
4559
4551
  }
4560
4552
  }
4561
4553
 
@@ -5096,19 +5088,26 @@ export class SyncClient {
5096
5088
 
5097
5089
  async #handleRealtimeBinary(bytes: Uint8Array): Promise<void> {
5098
5090
  if (!this.#transportEnabled) return;
5099
- if (this.#syncing) {
5100
- // Fast path: a pull is mid-flight; let it win and recover the gap
5101
- // itself — re-pulling is idempotent, interleaved application is not
5102
- // worth it. (An optimization; the op chain below is the correctness
5103
- // mechanism — it also excludes a delta from racing a `setWindow` or a
5104
- // sync round that started between this check and the apply.)
5105
- this.#setSyncNeeded(true);
5106
- return;
5107
- }
5091
+ const resetEpoch = this.#localResetEpoch;
5092
+ const securityEpoch = this.#securityEpoch;
5093
+ const transportEpoch = this.#transportEpoch;
5108
5094
  // Serialize the apply on the operation chain: a delta must never
5109
5095
  // interleave its transactions or share the `#batch` accumulator with a
5110
5096
  // pull round or a `setWindow` at an await point (§8.2).
5111
5097
  await this.#serialize(async () => {
5098
+ if (
5099
+ !this.#started ||
5100
+ !this.#transportEnabled ||
5101
+ this.#securityLifecycle !== 'active' ||
5102
+ securityEpoch !== this.#securityEpoch ||
5103
+ transportEpoch !== this.#transportEpoch
5104
+ )
5105
+ return;
5106
+ if (resetEpoch !== this.#localResetEpoch) {
5107
+ this.#setSyncNeeded(true);
5108
+ this.#emitSyncNeeded('catchup-required');
5109
+ return;
5110
+ }
5112
5111
  try {
5113
5112
  const message = decodeMessage(bytes);
5114
5113
  if (message.msgKind !== 'response') return;
@@ -5445,7 +5444,11 @@ export class SyncClient {
5445
5444
  break;
5446
5445
  }
5447
5446
  case 'COMMIT':
5448
- if (section !== undefined && !section.skip) {
5447
+ if (
5448
+ section !== undefined &&
5449
+ !section.skip &&
5450
+ section.sub !== undefined
5451
+ ) {
5449
5452
  const changes = frame.changes.filter((change) => {
5450
5453
  if (change.op !== 'delete') return true;
5451
5454
  const table = frame.tables[change.tableIndex];
@@ -5457,7 +5460,12 @@ export class SyncClient {
5457
5460
  );
5458
5461
  });
5459
5462
  if (changes.length > 0) {
5460
- await this.#applyCommit({ ...frame, changes }, summary);
5463
+ await this.#applyCommit(
5464
+ { ...frame, changes },
5465
+ summary,
5466
+ section.sub.id,
5467
+ mode,
5468
+ );
5461
5469
  }
5462
5470
  }
5463
5471
  break;
@@ -5875,6 +5883,8 @@ export class SyncClient {
5875
5883
  async #applyCommit(
5876
5884
  frame: CommitFrame,
5877
5885
  summary: MutableSummary,
5886
+ subscriptionId: string,
5887
+ source: 'delta' | 'pull',
5878
5888
  ): Promise<void> {
5879
5889
  await applyCommitFrame(
5880
5890
  this.#db,
@@ -5886,6 +5896,17 @@ export class SyncClient {
5886
5896
  this.#recordCommitChanges(batch, frame);
5887
5897
  const result = fn();
5888
5898
  this.#replayOutbox(result, false);
5899
+ for (const table of new Set(
5900
+ frame.changes.map((change) => frame.tables[change.tableIndex]),
5901
+ )) {
5902
+ if (table !== undefined)
5903
+ batch.appliedCommit({
5904
+ subscriptionId,
5905
+ table,
5906
+ commitSeq: frame.commitSeq,
5907
+ source,
5908
+ });
5909
+ }
5889
5910
  return result;
5890
5911
  }),
5891
5912
  );
@@ -49,6 +49,13 @@ export interface ClientChangeBatch {
49
49
  readonly conflictsChanged: boolean;
50
50
  readonly rejectionsChanged: boolean;
51
51
  readonly outcomesChanged: boolean;
52
+ /** Server COMMIT frames applied by this transaction, when present. */
53
+ readonly appliedCommits?: readonly {
54
+ readonly subscriptionId: string;
55
+ readonly table: string;
56
+ readonly commitSeq: number;
57
+ readonly source: 'delta' | 'pull';
58
+ }[];
52
59
  }
53
60
 
54
61
  export type ClientChangeListener = (batch: ClientChangeBatch) => void;
@@ -93,6 +100,15 @@ export class ChangeAccumulator {
93
100
  #conflicts = false;
94
101
  #rejections = false;
95
102
  #outcomes = false;
103
+ readonly #appliedCommits: NonNullable<
104
+ ClientChangeBatch['appliedCommits']
105
+ >[number][] = [];
106
+
107
+ appliedCommit(
108
+ entry: NonNullable<ClientChangeBatch['appliedCommits']>[number],
109
+ ): void {
110
+ this.#appliedCommits.push(entry);
111
+ }
96
112
 
97
113
  /** Mark a whole table dirty, discarding any weaker scope-only facts. */
98
114
  table(name: string): void {
@@ -214,6 +230,9 @@ export class ChangeAccumulator {
214
230
  conflictsChanged: this.#conflicts,
215
231
  rejectionsChanged: this.#rejections,
216
232
  outcomesChanged: this.#outcomes,
233
+ ...(this.#appliedCommits.length > 0
234
+ ? { appliedCommits: this.#appliedCommits }
235
+ : {}),
217
236
  };
218
237
  }
219
238
  }
package/src/multi-tab.ts CHANGED
@@ -1133,6 +1133,7 @@ export async function createTabCoordinator<E>(
1133
1133
  | undefined;
1134
1134
  let follower: FollowerLink<E> | undefined;
1135
1135
  let closed = false;
1136
+ let closing: Promise<void> | undefined;
1136
1137
  let takingOver = false;
1137
1138
  /** Start of the current `leader-unreachable` period. */
1138
1139
  let unreachableSince: number | undefined;
@@ -1362,20 +1363,22 @@ export async function createTabCoordinator<E>(
1362
1363
  takingOver = false;
1363
1364
  }
1364
1365
  },
1365
- close: async () => {
1366
- if (closed) return;
1367
- closed = true;
1368
- endUnreachable('closed');
1369
- follower?.close();
1370
- follower = undefined;
1371
- const ending = leading;
1372
- leading = undefined;
1373
- if (ending !== undefined) {
1374
- ending.end();
1375
- await ending.leader.close();
1376
- await ending.lease.release();
1377
- }
1378
- await tabLease.release();
1366
+ close: () => {
1367
+ closing ??= (async () => {
1368
+ closed = true;
1369
+ endUnreachable('closed');
1370
+ follower?.close();
1371
+ follower = undefined;
1372
+ const ending = leading;
1373
+ leading = undefined;
1374
+ if (ending !== undefined) {
1375
+ ending.end();
1376
+ await ending.leader.close();
1377
+ await ending.lease.release();
1378
+ }
1379
+ await tabLease.release();
1380
+ })();
1381
+ return closing;
1379
1382
  },
1380
1383
  };
1381
1384
 
@@ -341,6 +341,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
341
341
  readonly #unreachableListeners: Set<(event: LeaderUnreachableEvent) => void>;
342
342
  readonly #devtoolsUnregister: (() => void) | undefined;
343
343
  #closed = false;
344
+ #closing: Promise<void> | undefined;
344
345
 
345
346
  /** @internal — use {@link createSyncClientHandle}. */
346
347
  constructor(internals: {
@@ -830,18 +831,23 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
830
831
  return this.#call('abandonLocalAuthorityAttach', []);
831
832
  }
832
833
 
833
- /** Close the core (leader) or the link (follower), release leadership. */
834
- async close(): Promise<void> {
835
- if (this.#closed) return;
836
- this.#closed = true;
837
- this.#progress.clear();
838
- this.#devtoolsUnregister?.();
839
- await this.#tabs?.close();
840
- if (this.#core !== undefined) {
841
- const core = this.#core;
842
- this.#core = undefined;
843
- await core.close();
844
- }
834
+ /**
835
+ * Close the core (leader) or the link (follower), release leadership. Every
836
+ * call returns the same promise, which settles with the one close.
837
+ */
838
+ close(): Promise<void> {
839
+ this.#closing ??= (async () => {
840
+ this.#closed = true;
841
+ this.#progress.clear();
842
+ this.#devtoolsUnregister?.();
843
+ await this.#tabs?.close();
844
+ if (this.#core !== undefined) {
845
+ const core = this.#core;
846
+ this.#core = undefined;
847
+ await core.close();
848
+ }
849
+ })();
850
+ return this.#closing;
845
851
  }
846
852
  }
847
853