@syncular/client 0.85.0 → 0.86.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.
@@ -719,7 +719,11 @@ export class NativeBridgeClient {
719
719
  async sync() {
720
720
  return this.command('sync', {});
721
721
  }
722
- async syncUntilIdle(maxRounds, timeoutMs) {
722
+ /** The Rust core has no §8.4 empty-replica gate: `skipEmpty` is not sent. */
723
+ async syncUntilIdle(options, timeoutMs) {
724
+ const maxRounds = typeof options === 'object' ? options.maxRounds : options;
725
+ if (typeof options === 'object')
726
+ timeoutMs = options.timeoutMs;
723
727
  return this.command('syncUntilIdle', {
724
728
  ...(maxRounds !== undefined ? { maxRounds } : {}),
725
729
  ...(timeoutMs !== undefined ? { timeoutMs } : {}),
@@ -111,7 +111,8 @@ export declare function listCommitOutcomes(db: ClientDatabase, query?: CommitOut
111
111
  export declare function persistCommitOutcomeResolution(db: ClientDatabase, input: ResolveCommitOutcomeInput, nowMs: number): CommitOutcome | undefined;
112
112
  /**
113
113
  * Bound journal growth without deleting active failures. If active failures
114
- * alone exceed the cap the journal intentionally remains over-capacity.
114
+ * alone exceed the cap the journal intentionally remains over-capacity. The
115
+ * client constructor validates `maxEntries`.
115
116
  */
116
117
  export declare function pruneCommitOutcomes(db: ClientDatabase, maxEntries: number): number;
117
118
  export declare function activeFailureRecords(outcomes: readonly CommitOutcome[]): {
package/dist/outcomes.js CHANGED
@@ -272,12 +272,10 @@ export function persistCommitOutcomeResolution(db, input, nowMs) {
272
272
  }
273
273
  /**
274
274
  * Bound journal growth without deleting active failures. If active failures
275
- * alone exceed the cap the journal intentionally remains over-capacity.
275
+ * alone exceed the cap the journal intentionally remains over-capacity. The
276
+ * client constructor validates `maxEntries`.
276
277
  */
277
278
  export function pruneCommitOutcomes(db, maxEntries) {
278
- if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
279
- throw invalidRequest('outcome retention maxEntries must be a positive safe integer');
280
- }
281
279
  const count = db.query(`SELECT COUNT(*) AS count FROM ${OUTCOMES_TABLE}`)[0]
282
280
  ?.count;
283
281
  const excess = Math.max(0, (count ?? 0) - maxEntries);
@@ -13,6 +13,10 @@ export interface SyncProgress {
13
13
  readonly bytesTotal?: number | undefined;
14
14
  readonly rowsProcessed: number;
15
15
  readonly rowsTotal?: number | undefined;
16
+ /** The unit's bootstrap rows as the server counted them (SPEC §4.4, §7.7). */
17
+ readonly unitRowsTotal?: number | undefined;
18
+ /** Rows of the unit's bootstrap imported so far, across its sections. */
19
+ readonly unitRowsProcessed?: number | undefined;
16
20
  /** Time in this payload's import transactions before COMMIT, in ms. */
17
21
  readonly importWriteMs?: number | undefined;
18
22
  /** Time committing them and publishing their changes, in ms. */
package/dist/progress.js CHANGED
@@ -36,7 +36,19 @@ export class ProgressEmitter {
36
36
  }
37
37
  }
38
38
  update(update) {
39
- if (this.#snapshot?.state === 'running')
40
- this.emit({ ...this.#snapshot, ...update });
39
+ const before = this.#snapshot;
40
+ if (before?.state !== 'running')
41
+ return;
42
+ const next = { ...before, ...update };
43
+ // §7.7: each rise of the payload counter raises the unit's, and the unit
44
+ // total never falls below what was imported.
45
+ if (next.unitRowsProcessed !== undefined) {
46
+ const processed = next.unitRowsProcessed +
47
+ Math.max(0, next.rowsProcessed - before.rowsProcessed);
48
+ next.unitRowsProcessed = processed;
49
+ if (next.unitRowsTotal !== undefined)
50
+ next.unitRowsTotal = Math.max(next.unitRowsTotal, processed);
51
+ }
52
+ this.emit(next);
41
53
  }
42
54
  }
@@ -5,7 +5,10 @@ type CancelTimer = () => void;
5
5
  export interface RealtimeSupervisorClient {
6
6
  connectRealtime(): Promise<void>;
7
7
  disconnectRealtime(): void | Promise<void>;
8
- syncUntilIdle(maxRounds?: number): unknown | Promise<unknown>;
8
+ /** Receives `{ skipEmpty: true }` (§8.4); a numeric-budget signature also fits. */
9
+ syncUntilIdle(options?: number | {
10
+ readonly skipEmpty?: boolean;
11
+ }): unknown | Promise<unknown>;
9
12
  diagnosticsSnapshot(): ClientDiagnosticsSnapshot | Promise<ClientDiagnosticsSnapshot>;
10
13
  onDiagnostics(listener: ClientDiagnosticsListener): () => void;
11
14
  close(): void | Promise<void>;
@@ -326,7 +326,7 @@ export class RealtimeSupervisor {
326
326
  return;
327
327
  }
328
328
  this.#round = Promise.resolve()
329
- .then(() => this.#client.syncUntilIdle())
329
+ .then(() => this.#client.syncUntilIdle({ skipEmpty: true }))
330
330
  .then(() => undefined, () => undefined)
331
331
  .finally(() => {
332
332
  this.#round = undefined;
@@ -479,7 +479,7 @@ export class RealtimeSupervisor {
479
479
  this.#transport = true;
480
480
  }
481
481
  if (generation === this.#generation)
482
- await this.#client.syncUntilIdle();
482
+ await this.#client.syncUntilIdle({ skipEmpty: true });
483
483
  caughtUp = generation === this.#generation && this.#transport;
484
484
  }
485
485
  catch {
@@ -1,17 +1,23 @@
1
1
  import type { WakeReason } from '@syncular/core';
2
- import type { SecurityLifecycle } from './client.js';
2
+ import type { SecurityLifecycle, SyncIdleOptions } from './client.js';
3
3
  import type { SyncIntent } from './invalidation.js';
4
4
  export interface SyncSchedulerClient {
5
5
  statusSnapshot(): {
6
6
  readonly syncNeeded: boolean;
7
7
  };
8
8
  securityLifecycle(): SecurityLifecycle;
9
- syncUntilIdle(maxRounds?: number): Promise<unknown>;
9
+ syncUntilIdle(options: SyncIdleOptions): Promise<unknown>;
10
10
  onSyncNeeded(listener: (reason: 'startup' | 'hello' | WakeReason) => void): () => void;
11
11
  onSyncIntent(listener: (intent: SyncIntent) => void): () => void;
12
12
  }
13
13
  export interface SyncSchedulerOptions {
14
14
  readonly maxRounds?: number;
15
+ /**
16
+ * §8.4: milliseconds a queued drive waits before it starts, so the claims
17
+ * and writes of one burst ride in one round. Default 0: the drive starts
18
+ * in the next microtask.
19
+ */
20
+ readonly coalesceMs?: number;
15
21
  readonly onError?: (error: unknown) => void;
16
22
  readonly now?: () => number;
17
23
  readonly queueMicrotask?: (callback: () => void) => void;
@@ -1,5 +1,9 @@
1
+ import { invalidRequest } from './errors.js';
1
2
  /** Install the event-driven single-flight host loop for a direct client. */
2
3
  export function installSyncScheduler(client, options = {}) {
4
+ const coalesceMs = options.coalesceMs ?? 0;
5
+ if (!(Number.isFinite(coalesceMs) && coalesceMs >= 0))
6
+ throw invalidRequest('coalesceMs must be a non-negative finite number');
3
7
  const now = options.now ?? Date.now;
4
8
  const enqueue = options.queueMicrotask ?? globalThis.queueMicrotask;
5
9
  const schedule = options.schedule ??
@@ -38,13 +42,17 @@ export function installSyncScheduler(client, options = {}) {
38
42
  if (stopped || running || immediateQueued)
39
43
  return;
40
44
  immediateQueued = true;
41
- enqueue(() => {
45
+ const start = () => {
42
46
  immediateQueued = false;
43
47
  if (stopped || !immediatePending)
44
48
  return;
45
49
  immediatePending = false;
46
50
  run();
47
- });
51
+ };
52
+ if (coalesceMs > 0)
53
+ schedule(start, coalesceMs);
54
+ else
55
+ enqueue(start);
48
56
  };
49
57
  const run = () => {
50
58
  if (stopped || running)
@@ -56,7 +64,7 @@ export function installSyncScheduler(client, options = {}) {
56
64
  running = true;
57
65
  backgroundReady = false;
58
66
  void client
59
- .syncUntilIdle(options.maxRounds)
67
+ .syncUntilIdle({ maxRounds: options.maxRounds, skipEmpty: true })
60
68
  .then((result) => {
61
69
  retryDelayMs = 250;
62
70
  if (result !== null &&
@@ -73,6 +73,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
73
73
  }
74
74
  // -- SPEC §7.5 host loop: event-driven intents, no interactive polling --
75
75
  let autoSync = true;
76
+ let coalesceMs = 0;
76
77
  let autoSyncScheduled = false;
77
78
  let cancelBackground;
78
79
  let backgroundDue = Number.POSITIVE_INFINITY;
@@ -104,7 +105,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
104
105
  // let every wake-up that arrives while this round waits behind the
105
106
  // running one queue its own full drive (§8.4 coalescing).
106
107
  autoSyncScheduled = false;
107
- return running.syncUntilIdle();
108
+ return running.syncUntilIdle({ skipEmpty: true });
108
109
  })
109
110
  .then((summary) => {
110
111
  retryDelayMs = 250;
@@ -169,7 +170,10 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
169
170
  return;
170
171
  }
171
172
  autoSyncScheduled = true;
172
- queueMicrotask(runAutoSync);
173
+ if (coalesceMs > 0)
174
+ scheduleBackground(runAutoSync, coalesceMs);
175
+ else
176
+ queueMicrotask(runAutoSync);
173
177
  }
174
178
  function requireClient() {
175
179
  if (client === undefined) {
@@ -193,6 +197,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
193
197
  throw new ClientSyncError(WORKER_FAILED_CODE, 'the worker is already initialized');
194
198
  }
195
199
  autoSync = config.autoSync ?? true;
200
+ coalesceMs = config.coalesceMs ?? 0;
196
201
  headers = config.headers ?? {};
197
202
  const http = { headers: () => headers };
198
203
  for (let attempt = 0;; attempt++) {
@@ -111,6 +111,11 @@ export interface SyncClientHandleConfig {
111
111
  readonly previousVersionContext?: SyncClientConfig['previousVersionContext'];
112
112
  /** Worker-side host loop (§8.4); default true. */
113
113
  readonly autoSync?: boolean;
114
+ /**
115
+ * §8.4: milliseconds a queued `autoSync` drive waits before it starts, so
116
+ * the claims and writes of one burst ride in one round. Default 0.
117
+ */
118
+ readonly coalesceMs?: number;
114
119
  /**
115
120
  * Default: Web Locks. A runtime without Web Locks refuses the handle with
116
121
  * `client.web_locks_unavailable` unless the host injects a lock.
@@ -705,6 +705,9 @@ function buildInitConfig(config, headers = config.headers) {
705
705
  ? { previousVersionContext: config.previousVersionContext }
706
706
  : {}),
707
707
  ...(config.autoSync !== undefined ? { autoSync: config.autoSync } : {}),
708
+ ...(config.coalesceMs !== undefined
709
+ ? { coalesceMs: config.coalesceMs }
710
+ : {}),
708
711
  };
709
712
  }
710
713
  function syncedResult(event) {
@@ -743,6 +746,9 @@ function fireConfigCallbacks(config, event) {
743
746
  */
744
747
  export async function createSyncClientHandle(config) {
745
748
  const resolvedConfig = resolveReplicaConfig(config);
749
+ if (config.coalesceMs !== undefined &&
750
+ !(Number.isFinite(config.coalesceMs) && config.coalesceMs >= 0))
751
+ throw invalidRequest('coalesceMs must be a non-negative finite number');
746
752
  const lock = resolvedConfig.leaderLock ?? defaultLeaderLock();
747
753
  const lockName = resolvedConfig.lockName ?? 'syncular-leader';
748
754
  const invalidation = new InvalidationEmitter();
@@ -121,6 +121,8 @@ export interface WorkerInitConfig {
121
121
  * `syncUntilIdle` rounds inside the worker. Default true.
122
122
  */
123
123
  readonly autoSync?: boolean;
124
+ /** Delay of a queued `autoSync` drive (§8.4); validated by the handle. */
125
+ readonly coalesceMs?: number;
124
126
  }
125
127
  /** Successful init reply. */
126
128
  export interface WorkerInitResult {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.85.0",
3
+ "version": "0.86.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.85.0"
124
+ "@syncular/core": "0.86.0"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.85.0",
128
+ "@syncular/server": "0.86.0",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
package/src/apply.ts CHANGED
@@ -36,7 +36,6 @@ import {
36
36
  SEALED_KEY_COLUMN,
37
37
  SYNC_VERSION_COLUMN,
38
38
  toSqlValue,
39
- rowValueToJson,
40
39
  } from './schema';
41
40
 
42
41
  /** Lets the client wrap the physical write in its revision transaction. */
@@ -63,7 +62,6 @@ export function upsertLocalRow(
63
62
  table: CompiledClientTable,
64
63
  values: readonly RowValue[],
65
64
  syncVersion: number,
66
- serverWrite = true,
67
65
  sealed?: SealedRow,
68
66
  ): void {
69
67
  db.exec(upsertSql(table), [
@@ -73,19 +71,6 @@ export function upsertLocalRow(
73
71
  ? [sealed?.keyId ?? null, sealed?.envelopes ?? null]
74
72
  : []),
75
73
  ]);
76
- if (serverWrite)
77
- retainedBaseWrite(
78
- db,
79
- table,
80
- String(values[table.primaryKeyIndex]),
81
- Object.fromEntries(
82
- table.columns.map((column, index) => [
83
- column.name,
84
- rowValueToJson(values[index] ?? null),
85
- ]),
86
- ),
87
- syncVersion,
88
- );
89
74
  }
90
75
 
91
76
  export function deleteLocalRow(
@@ -94,11 +79,11 @@ export function deleteLocalRow(
94
79
  rowId: string,
95
80
  serverWrite = true,
96
81
  ): void {
97
- if (serverWrite) retainedBaseWrite(db, table, rowId);
98
82
  db.exec(
99
83
  `DELETE FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
100
84
  [pkSqlValue(table, rowId)],
101
85
  );
86
+ if (serverWrite) retainedBaseWrite(db, table, new Map([[rowId, undefined]]));
102
87
  }
103
88
 
104
89
  /**
@@ -238,15 +223,20 @@ export async function applyCommitFrame(
238
223
  );
239
224
  if (!land) continue;
240
225
  if (change.op === 'delete') deleteLocalRow(db, change.table, rowId);
241
- else
226
+ else {
242
227
  upsertLocalRow(
243
228
  db,
244
229
  change.table,
245
230
  change.values,
246
231
  rowVersion,
247
- true,
248
232
  change.sealed,
249
233
  );
234
+ retainedBaseWrite(
235
+ db,
236
+ change.table,
237
+ new Map([[rowId, [change.values, rowVersion]]]),
238
+ );
239
+ }
250
240
  }
251
241
  return rebaseScope(scope, kept, skipped);
252
242
  });
@@ -416,11 +406,13 @@ export function deleteScopedRows(
416
406
  const scope = localScopePredicate(table, effective, owners);
417
407
  if (!scope) return;
418
408
  const { sql, params } = scope;
419
- if (retainsRows(db, table))
420
- for (const row of scopedRows(db, table, scope)) {
421
- retainedBaseWrite(db, table, String(row.id));
422
- }
409
+ const retained = retainsRows(db, table) ? scopedRows(db, table, scope) : [];
423
410
  db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${sql}`, params);
411
+ retainedBaseWrite(
412
+ db,
413
+ table,
414
+ new Map(retained.map((row) => [String(row.id), undefined])),
415
+ );
424
416
  }
425
417
 
426
418
  /**
@@ -668,7 +660,7 @@ export async function applySqliteSegment(
668
660
  JSON.stringify([table.name, String(row[table.primaryKey])]),
669
661
  ),
670
662
  ];
671
- const protectedRows = restoreFailedBases(db, schema, scope);
663
+ restoreFailedBases(db, schema, scope);
672
664
  if (first && options.clearFirst)
673
665
  deleteScopedRows(db, table, options.effective, options.owners());
674
666
  const kept = new Set<string>();
@@ -709,21 +701,19 @@ export async function applySqliteSegment(
709
701
  Math.min(1024, size - chunk),
710
702
  );
711
703
  }
712
- if (protectedRows)
713
- for (const row of landing) {
714
- retainedBaseWrite(
715
- db,
716
- table,
704
+ retainedBaseWrite(
705
+ db,
706
+ table,
707
+ new Map(
708
+ landing.map((row) => [
717
709
  String(row[table.primaryKey]),
718
- Object.fromEntries(
719
- table.columns.map((column) => [
720
- column.name,
721
- rowValueToJson(row[column.name] as RowValue),
722
- ]),
723
- ),
724
- Number(row._syncular_version),
725
- );
726
- }
710
+ [
711
+ table.columns.map((column) => row[column.name] as RowValue),
712
+ Number(row._syncular_version),
713
+ ],
714
+ ]),
715
+ ),
716
+ );
727
717
  options.onChunk?.(applied);
728
718
  return rebaseScope(scope, kept, skipped);
729
719
  });
@@ -812,26 +802,23 @@ export async function applyRowsSegment(
812
802
  ]),
813
803
  ),
814
804
  ];
815
- const protectedRows = restoreFailedBases(db, schema, scope);
805
+ restoreFailedBases(db, schema, scope);
816
806
  if (clearThisBlock) {
817
807
  deleteScopedRows(db, table, options.effective, options.owners());
818
808
  }
819
809
  const kept = new Set<string>();
820
810
  const skipped = new Set<string>();
811
+ const written = new Map<string, readonly [readonly RowValue[], number]>();
821
812
  for (const row of rows) {
822
813
  const rowId = String(row.values[table.primaryKeyIndex]);
823
- if (lands(db, table, rowId, row.serverVersion, kept, skipped))
824
- upsertLocalRow(
825
- db,
826
- table,
827
- row.values,
828
- row.serverVersion,
829
- protectedRows,
830
- row.sealed,
831
- );
814
+ if (lands(db, table, rowId, row.serverVersion, kept, skipped)) {
815
+ upsertLocalRow(db, table, row.values, row.serverVersion, row.sealed);
816
+ written.set(rowId, [row.values, row.serverVersion]);
817
+ }
832
818
  applied += 1;
833
819
  if (applied % 1024 === 0) options.onProgress?.(applied);
834
820
  }
821
+ retainedBaseWrite(db, table, written);
835
822
  return rebaseScope(scope, kept, skipped);
836
823
  });
837
824
  options.onProgress?.(applied);