@syncular/client 0.77.1 → 0.77.2

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.d.ts CHANGED
@@ -90,8 +90,9 @@ export interface SyncSummary {
90
90
  }
91
91
  /**
92
92
  * The result of `syncUntilIdle`. The report aggregates every round that ran;
93
- * `budgetExhausted` is true when the round budget ran out with the client not
94
- * idle. An exhausted run is a partial success, never idle.
93
+ * `budgetExhausted` is true when the round budget or the drive deadline ran
94
+ * out with the client not idle. An exhausted run is a partial success, never
95
+ * idle.
95
96
  */
96
97
  export interface SyncIdleResult extends SyncSummary {
97
98
  readonly budgetExhausted: boolean;
@@ -100,9 +101,11 @@ export interface SyncIdleOptions {
100
101
  /** §7.8: a strict positive round count. Default: 20. */
101
102
  readonly maxRounds?: number;
102
103
  /**
103
- * Total wall-clock budget for one drive, across every round. When it
104
- * elapses the drive rejects with `sync.idle_timeout`; a socket round in
105
- * flight is aborted. Default: 60,000 ms. `Infinity` disables the bound.
104
+ * Total budget for one drive, across every round, on the client clock. A
105
+ * drive past it after a completed round resolves with `budgetExhausted`.
106
+ * Each round is bounded by it on its own: a round that reaches it rejects
107
+ * the drive with `sync.idle_timeout` and is aborted. Default: 60,000 ms.
108
+ * `Infinity` disables the bound.
106
109
  */
107
110
  readonly timeoutMs?: number;
108
111
  }
@@ -699,10 +702,11 @@ export declare class SyncClient {
699
702
  * Callers that arrive during the same drive with the same budget share that
700
703
  * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
701
704
  *
702
- * §7.8: one drive is bounded by a total deadline (`timeoutMs`, default
703
- * 60 s). A drive that reaches it rejects with `sync.idle_timeout` and
704
- * aborts a socket round in flight; the round budget does not bound elapsed
705
- * time, and a transport that never answers must not hang the caller.
705
+ * §7.8: one drive has a total deadline (`timeoutMs`, default 60 s), checked
706
+ * between rounds: a drive past it after a completed round resolves with
707
+ * `budgetExhausted`. Each round is bounded by `timeoutMs` on its own; a
708
+ * round that reaches it rejects the drive with `sync.idle_timeout` and
709
+ * aborts the round, so a transport that never answers cannot hang the caller.
706
710
  */
707
711
  syncUntilIdle(options?: number | SyncIdleOptions): Promise<SyncIdleResult>;
708
712
  connectRealtime(): Promise<void>;
package/dist/client.js CHANGED
@@ -3293,10 +3293,11 @@ export class SyncClient {
3293
3293
  * Callers that arrive during the same drive with the same budget share that
3294
3294
  * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
3295
3295
  *
3296
- * §7.8: one drive is bounded by a total deadline (`timeoutMs`, default
3297
- * 60 s). A drive that reaches it rejects with `sync.idle_timeout` and
3298
- * aborts a socket round in flight; the round budget does not bound elapsed
3299
- * time, and a transport that never answers must not hang the caller.
3296
+ * §7.8: one drive has a total deadline (`timeoutMs`, default 60 s), checked
3297
+ * between rounds: a drive past it after a completed round resolves with
3298
+ * `budgetExhausted`. Each round is bounded by `timeoutMs` on its own; a
3299
+ * round that reaches it rejects the drive with `sync.idle_timeout` and
3300
+ * aborts the round, so a transport that never answers cannot hang the caller.
3300
3301
  */
3301
3302
  async syncUntilIdle(options) {
3302
3303
  const maxRounds = typeof options === 'number' ? options : options?.maxRounds;
@@ -3362,75 +3363,69 @@ export class SyncClient {
3362
3363
  : {}),
3363
3364
  budgetExhausted,
3364
3365
  });
3365
- let round = 0;
3366
- let expired = false;
3367
- let timer;
3368
- // One signal reaches every transport call of the drive's rounds.
3369
- const controller = new AbortController();
3370
- const expiredError = () => new ClientSyncError('sync.idle_timeout', 'syncUntilIdle exceeded its deadline', true, { timeoutMs, rounds: round });
3371
- const deadline = timeoutMs === Number.POSITIVE_INFINITY
3372
- ? undefined
3373
- : new Promise((_, reject) => {
3374
- timer = setTimeout(() => {
3375
- expired = true;
3376
- const error = expiredError();
3377
- // The transport may never answer; release the round so the
3378
- // client can run another one after the caller sees the error.
3379
- controller.abort(error);
3380
- this.#abortPendingRound('syncUntilIdle deadline exceeded');
3381
- reject(error);
3382
- }, timeoutMs);
3383
- });
3384
- const drive = (async () => {
3385
- for (; round < budget; round++) {
3386
- // The race already rejected; stop spending rounds on a dead drive.
3387
- if (expired)
3388
- throw expiredError();
3389
- const before = JSON.stringify(loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]));
3390
- const last = await this.#sync(controller.signal);
3391
- // Historical counters accumulate; current readiness (`bootstrapping`,
3392
- // `deferredCommits`, `schemaFloor`) describes the latest round.
3393
- aggregate.pushed += last.pushed;
3394
- aggregate.applied.push(...last.applied);
3395
- aggregate.rejected.push(...last.rejected);
3396
- aggregate.retryable.push(...last.retryable);
3397
- aggregate.conflicts.push(...last.conflicts);
3398
- aggregate.commitsApplied += last.commitsApplied;
3399
- aggregate.segmentRowsApplied += last.segmentRowsApplied;
3400
- aggregate.bootstrapping = [...last.bootstrapping];
3401
- aggregate.resets.push(...last.resets);
3402
- aggregate.revoked.push(...last.revoked);
3403
- aggregate.failed.push(...last.failed);
3404
- aggregate.deferredCommits = last.deferredCommits ?? 0;
3405
- aggregate.schemaFloor = last.schemaFloor;
3406
- // A disabled transport or a schema floor ends the loop, not the budget.
3407
- if (!this.#transportEnabled || last.schemaFloor !== undefined)
3408
- return result(false);
3409
- if (maxRounds === undefined &&
3410
- last.segmentRowsApplied > 0 &&
3411
- last.bootstrapping.length > 0 &&
3412
- before !==
3413
- JSON.stringify(loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState])))
3414
- round = -1;
3415
- if (last.commitsApplied === 0 &&
3416
- last.segmentRowsApplied === 0 &&
3417
- last.bootstrapping.length === 0 &&
3418
- last.resets.length === 0 &&
3419
- (last.deferredCommits ?? 0) === 0 &&
3420
- !this.#needsPull) {
3421
- return result(false);
3422
- }
3366
+ const startedAtMs = this.#now();
3367
+ let completed = false;
3368
+ for (let round = 0; round < budget; round++) {
3369
+ // §7.8: a deadline that elapsed across completed rounds ends the drive
3370
+ // like an exhausted round budget; the next drive resumes.
3371
+ if (completed && this.#now() - startedAtMs >= timeoutMs)
3372
+ return result(true);
3373
+ const before = JSON.stringify(loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]));
3374
+ // Each round is bounded by `timeoutMs` on its own. One signal reaches
3375
+ // every transport call of the round.
3376
+ const controller = new AbortController();
3377
+ let timer;
3378
+ const sync = this.#sync(controller.signal);
3379
+ const last = await (timeoutMs === Number.POSITIVE_INFINITY
3380
+ ? sync
3381
+ : Promise.race([
3382
+ sync,
3383
+ new Promise((_, reject) => {
3384
+ timer = setTimeout(() => {
3385
+ const error = new ClientSyncError('sync.idle_timeout', 'syncUntilIdle exceeded its deadline', true, { timeoutMs, rounds: round });
3386
+ // The transport may never answer; release the round so the
3387
+ // client can run another one after the caller sees the error.
3388
+ controller.abort(error);
3389
+ this.#abortPendingRound('syncUntilIdle deadline exceeded');
3390
+ reject(error);
3391
+ }, timeoutMs);
3392
+ }),
3393
+ ])).finally(() => clearTimeout(timer));
3394
+ completed = true;
3395
+ // Historical counters accumulate; current readiness (`bootstrapping`,
3396
+ // `deferredCommits`, `schemaFloor`) describes the latest round.
3397
+ aggregate.pushed += last.pushed;
3398
+ aggregate.applied.push(...last.applied);
3399
+ aggregate.rejected.push(...last.rejected);
3400
+ aggregate.retryable.push(...last.retryable);
3401
+ aggregate.conflicts.push(...last.conflicts);
3402
+ aggregate.commitsApplied += last.commitsApplied;
3403
+ aggregate.segmentRowsApplied += last.segmentRowsApplied;
3404
+ aggregate.bootstrapping = [...last.bootstrapping];
3405
+ aggregate.resets.push(...last.resets);
3406
+ aggregate.revoked.push(...last.revoked);
3407
+ aggregate.failed.push(...last.failed);
3408
+ aggregate.deferredCommits = last.deferredCommits ?? 0;
3409
+ aggregate.schemaFloor = last.schemaFloor;
3410
+ // A disabled transport or a schema floor ends the loop, not the budget.
3411
+ if (!this.#transportEnabled || last.schemaFloor !== undefined)
3412
+ return result(false);
3413
+ if (maxRounds === undefined &&
3414
+ last.segmentRowsApplied > 0 &&
3415
+ last.bootstrapping.length > 0 &&
3416
+ before !==
3417
+ JSON.stringify(loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState])))
3418
+ round = -1;
3419
+ if (last.commitsApplied === 0 &&
3420
+ last.segmentRowsApplied === 0 &&
3421
+ last.bootstrapping.length === 0 &&
3422
+ last.resets.length === 0 &&
3423
+ (last.deferredCommits ?? 0) === 0 &&
3424
+ !this.#needsPull) {
3425
+ return result(false);
3423
3426
  }
3424
- return result(true);
3425
- })();
3426
- try {
3427
- return await (deadline === undefined
3428
- ? drive
3429
- : Promise.race([drive, deadline]));
3430
- }
3431
- finally {
3432
- clearTimeout(timer);
3433
3427
  }
3428
+ return result(true);
3434
3429
  }
3435
3430
  /**
3436
3431
  * One request/response round trip (§8.7): over the socket whenever it
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.77.1",
3
+ "version": "0.77.2",
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.77.1"
124
+ "@syncular/core": "0.77.2"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.77.1",
128
+ "@syncular/server": "0.77.2",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
package/src/client.ts CHANGED
@@ -369,8 +369,9 @@ export interface SyncSummary {
369
369
 
370
370
  /**
371
371
  * The result of `syncUntilIdle`. The report aggregates every round that ran;
372
- * `budgetExhausted` is true when the round budget ran out with the client not
373
- * idle. An exhausted run is a partial success, never idle.
372
+ * `budgetExhausted` is true when the round budget or the drive deadline ran
373
+ * out with the client not idle. An exhausted run is a partial success, never
374
+ * idle.
374
375
  */
375
376
  export interface SyncIdleResult extends SyncSummary {
376
377
  readonly budgetExhausted: boolean;
@@ -380,9 +381,11 @@ export interface SyncIdleOptions {
380
381
  /** §7.8: a strict positive round count. Default: 20. */
381
382
  readonly maxRounds?: number;
382
383
  /**
383
- * Total wall-clock budget for one drive, across every round. When it
384
- * elapses the drive rejects with `sync.idle_timeout`; a socket round in
385
- * flight is aborted. Default: 60,000 ms. `Infinity` disables the bound.
384
+ * Total budget for one drive, across every round, on the client clock. A
385
+ * drive past it after a completed round resolves with `budgetExhausted`.
386
+ * Each round is bounded by it on its own: a round that reaches it rejects
387
+ * the drive with `sync.idle_timeout` and is aborted. Default: 60,000 ms.
388
+ * `Infinity` disables the bound.
386
389
  */
387
390
  readonly timeoutMs?: number;
388
391
  }
@@ -4742,10 +4745,11 @@ export class SyncClient {
4742
4745
  * Callers that arrive during the same drive with the same budget share that
4743
4746
  * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
4744
4747
  *
4745
- * §7.8: one drive is bounded by a total deadline (`timeoutMs`, default
4746
- * 60 s). A drive that reaches it rejects with `sync.idle_timeout` and
4747
- * aborts a socket round in flight; the round budget does not bound elapsed
4748
- * time, and a transport that never answers must not hang the caller.
4748
+ * §7.8: one drive has a total deadline (`timeoutMs`, default 60 s), checked
4749
+ * between rounds: a drive past it after a completed round resolves with
4750
+ * `budgetExhausted`. Each round is bounded by `timeoutMs` on its own; a
4751
+ * round that reaches it rejects the drive with `sync.idle_timeout` and
4752
+ * aborts the round, so a transport that never answers cannot hang the caller.
4749
4753
  */
4750
4754
  async syncUntilIdle(
4751
4755
  options?: number | SyncIdleOptions,
@@ -4821,88 +4825,84 @@ export class SyncClient {
4821
4825
  : {}),
4822
4826
  budgetExhausted,
4823
4827
  });
4824
- let round = 0;
4825
- let expired = false;
4826
- let timer: ReturnType<typeof setTimeout> | undefined;
4827
- // One signal reaches every transport call of the drive's rounds.
4828
- const controller = new AbortController();
4829
- const expiredError = () =>
4830
- new ClientSyncError(
4831
- 'sync.idle_timeout',
4832
- 'syncUntilIdle exceeded its deadline',
4833
- true,
4834
- { timeoutMs, rounds: round },
4828
+ const startedAtMs = this.#now();
4829
+ let completed = false;
4830
+ for (let round = 0; round < budget; round++) {
4831
+ // §7.8: a deadline that elapsed across completed rounds ends the drive
4832
+ // like an exhausted round budget; the next drive resumes.
4833
+ if (completed && this.#now() - startedAtMs >= timeoutMs)
4834
+ return result(true);
4835
+ const before = JSON.stringify(
4836
+ loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]),
4835
4837
  );
4836
- const deadline =
4837
- timeoutMs === Number.POSITIVE_INFINITY
4838
- ? undefined
4839
- : new Promise<never>((_, reject) => {
4840
- timer = setTimeout(() => {
4841
- expired = true;
4842
- const error = expiredError();
4843
- // The transport may never answer; release the round so the
4844
- // client can run another one after the caller sees the error.
4845
- controller.abort(error);
4846
- this.#abortPendingRound('syncUntilIdle deadline exceeded');
4847
- reject(error);
4848
- }, timeoutMs);
4849
- });
4850
- const drive = (async (): Promise<SyncIdleResult> => {
4851
- for (; round < budget; round++) {
4852
- // The race already rejected; stop spending rounds on a dead drive.
4853
- if (expired) throw expiredError();
4854
- const before = JSON.stringify(
4855
- loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]),
4856
- );
4857
- const last = await this.#sync(controller.signal);
4858
- // Historical counters accumulate; current readiness (`bootstrapping`,
4859
- // `deferredCommits`, `schemaFloor`) describes the latest round.
4860
- aggregate.pushed += last.pushed;
4861
- aggregate.applied.push(...last.applied);
4862
- aggregate.rejected.push(...last.rejected);
4863
- aggregate.retryable.push(...last.retryable);
4864
- aggregate.conflicts.push(...last.conflicts);
4865
- aggregate.commitsApplied += last.commitsApplied;
4866
- aggregate.segmentRowsApplied += last.segmentRowsApplied;
4867
- aggregate.bootstrapping = [...last.bootstrapping];
4868
- aggregate.resets.push(...last.resets);
4869
- aggregate.revoked.push(...last.revoked);
4870
- aggregate.failed.push(...last.failed);
4871
- aggregate.deferredCommits = last.deferredCommits ?? 0;
4872
- aggregate.schemaFloor = last.schemaFloor;
4873
- // A disabled transport or a schema floor ends the loop, not the budget.
4874
- if (!this.#transportEnabled || last.schemaFloor !== undefined)
4875
- return result(false);
4876
- if (
4877
- maxRounds === undefined &&
4878
- last.segmentRowsApplied > 0 &&
4879
- last.bootstrapping.length > 0 &&
4880
- before !==
4881
- JSON.stringify(
4882
- loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]),
4883
- )
4884
- )
4885
- round = -1;
4886
- if (
4887
- last.commitsApplied === 0 &&
4888
- last.segmentRowsApplied === 0 &&
4889
- last.bootstrapping.length === 0 &&
4890
- last.resets.length === 0 &&
4891
- (last.deferredCommits ?? 0) === 0 &&
4892
- !this.#needsPull
4893
- ) {
4894
- return result(false);
4895
- }
4838
+ // Each round is bounded by `timeoutMs` on its own. One signal reaches
4839
+ // every transport call of the round.
4840
+ const controller = new AbortController();
4841
+ let timer: ReturnType<typeof setTimeout> | undefined;
4842
+ const sync = this.#sync(controller.signal);
4843
+ const last = await (
4844
+ timeoutMs === Number.POSITIVE_INFINITY
4845
+ ? sync
4846
+ : Promise.race([
4847
+ sync,
4848
+ new Promise<never>((_, reject) => {
4849
+ timer = setTimeout(() => {
4850
+ const error = new ClientSyncError(
4851
+ 'sync.idle_timeout',
4852
+ 'syncUntilIdle exceeded its deadline',
4853
+ true,
4854
+ { timeoutMs, rounds: round },
4855
+ );
4856
+ // The transport may never answer; release the round so the
4857
+ // client can run another one after the caller sees the error.
4858
+ controller.abort(error);
4859
+ this.#abortPendingRound('syncUntilIdle deadline exceeded');
4860
+ reject(error);
4861
+ }, timeoutMs);
4862
+ }),
4863
+ ])
4864
+ ).finally(() => clearTimeout(timer));
4865
+ completed = true;
4866
+ // Historical counters accumulate; current readiness (`bootstrapping`,
4867
+ // `deferredCommits`, `schemaFloor`) describes the latest round.
4868
+ aggregate.pushed += last.pushed;
4869
+ aggregate.applied.push(...last.applied);
4870
+ aggregate.rejected.push(...last.rejected);
4871
+ aggregate.retryable.push(...last.retryable);
4872
+ aggregate.conflicts.push(...last.conflicts);
4873
+ aggregate.commitsApplied += last.commitsApplied;
4874
+ aggregate.segmentRowsApplied += last.segmentRowsApplied;
4875
+ aggregate.bootstrapping = [...last.bootstrapping];
4876
+ aggregate.resets.push(...last.resets);
4877
+ aggregate.revoked.push(...last.revoked);
4878
+ aggregate.failed.push(...last.failed);
4879
+ aggregate.deferredCommits = last.deferredCommits ?? 0;
4880
+ aggregate.schemaFloor = last.schemaFloor;
4881
+ // A disabled transport or a schema floor ends the loop, not the budget.
4882
+ if (!this.#transportEnabled || last.schemaFloor !== undefined)
4883
+ return result(false);
4884
+ if (
4885
+ maxRounds === undefined &&
4886
+ last.segmentRowsApplied > 0 &&
4887
+ last.bootstrapping.length > 0 &&
4888
+ before !==
4889
+ JSON.stringify(
4890
+ loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]),
4891
+ )
4892
+ )
4893
+ round = -1;
4894
+ if (
4895
+ last.commitsApplied === 0 &&
4896
+ last.segmentRowsApplied === 0 &&
4897
+ last.bootstrapping.length === 0 &&
4898
+ last.resets.length === 0 &&
4899
+ (last.deferredCommits ?? 0) === 0 &&
4900
+ !this.#needsPull
4901
+ ) {
4902
+ return result(false);
4896
4903
  }
4897
- return result(true);
4898
- })();
4899
- try {
4900
- return await (deadline === undefined
4901
- ? drive
4902
- : Promise.race([drive, deadline]));
4903
- } finally {
4904
- clearTimeout(timer);
4905
4904
  }
4905
+ return result(true);
4906
4906
  }
4907
4907
 
4908
4908
  /**