@syncular/client 0.85.0 → 0.90.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.
Files changed (58) hide show
  1. package/README.md +13 -4
  2. package/dist/apply.d.ts +1 -1
  3. package/dist/apply.js +25 -26
  4. package/dist/blob.d.ts +0 -4
  5. package/dist/blob.js +7 -22
  6. package/dist/client.d.ts +31 -10
  7. package/dist/client.js +501 -465
  8. package/dist/diagnostics.d.ts +2 -4
  9. package/dist/diagnostics.js +3 -17
  10. package/dist/encryption.js +5 -30
  11. package/dist/errors.d.ts +2 -0
  12. package/dist/errors.js +4 -0
  13. package/dist/failed-overlay.d.ts +8 -2
  14. package/dist/failed-overlay.js +33 -22
  15. package/dist/local-purge.d.ts +1 -0
  16. package/dist/local-purge.js +1 -1
  17. package/dist/local-rebootstrap-receipt.js +2 -2
  18. package/dist/local-rebootstrap.js +1 -1
  19. package/dist/native-bridge.d.ts +8 -3
  20. package/dist/native-bridge.js +29 -12
  21. package/dist/outcomes.d.ts +13 -1
  22. package/dist/outcomes.js +21 -20
  23. package/dist/previous-version.js +23 -35
  24. package/dist/progress.d.ts +4 -0
  25. package/dist/progress.js +14 -2
  26. package/dist/realtime-supervisor.d.ts +4 -1
  27. package/dist/realtime-supervisor.js +2 -2
  28. package/dist/schema.js +14 -13
  29. package/dist/state.d.ts +16 -4
  30. package/dist/state.js +83 -44
  31. package/dist/sync-scheduler.d.ts +8 -2
  32. package/dist/sync-scheduler.js +11 -3
  33. package/dist/worker-core.js +14 -10
  34. package/dist/worker-host.d.ts +10 -2
  35. package/dist/worker-host.js +15 -0
  36. package/dist/worker-protocol.d.ts +4 -1
  37. package/package.json +3 -3
  38. package/src/apply.ts +34 -47
  39. package/src/blob.ts +7 -24
  40. package/src/client.ts +699 -553
  41. package/src/diagnostics.ts +3 -19
  42. package/src/encryption.ts +15 -40
  43. package/src/errors.ts +5 -0
  44. package/src/failed-overlay.ts +39 -29
  45. package/src/local-purge.ts +1 -1
  46. package/src/local-rebootstrap-receipt.ts +2 -5
  47. package/src/local-rebootstrap.ts +1 -2
  48. package/src/native-bridge.ts +40 -14
  49. package/src/outcomes.ts +36 -31
  50. package/src/previous-version.ts +31 -40
  51. package/src/progress.ts +18 -2
  52. package/src/realtime-supervisor.ts +7 -3
  53. package/src/schema.ts +13 -13
  54. package/src/state.ts +107 -64
  55. package/src/sync-scheduler.ts +17 -5
  56. package/src/worker-core.ts +14 -18
  57. package/src/worker-host.ts +30 -1
  58. package/src/worker-protocol.ts +4 -0
@@ -235,6 +235,7 @@ export function startSyncWorkerCore(
235
235
 
236
236
  // -- SPEC §7.5 host loop: event-driven intents, no interactive polling --
237
237
  let autoSync = true;
238
+ let coalesceMs = 0;
238
239
  let autoSyncScheduled = false;
239
240
  let cancelBackground: (() => void) | undefined;
240
241
  let backgroundDue = Number.POSITIVE_INFINITY;
@@ -273,7 +274,7 @@ export function startSyncWorkerCore(
273
274
  // let every wake-up that arrives while this round waits behind the
274
275
  // running one queue its own full drive (§8.4 coalescing).
275
276
  autoSyncScheduled = false;
276
- return running.syncUntilIdle();
277
+ return running.syncUntilIdle({ skipEmpty: true });
277
278
  })
278
279
  .then((summary) => {
279
280
  retryDelayMs = 250;
@@ -344,7 +345,8 @@ export function startSyncWorkerCore(
344
345
  return;
345
346
  }
346
347
  autoSyncScheduled = true;
347
- queueMicrotask(runAutoSync);
348
+ if (coalesceMs > 0) scheduleBackground(runAutoSync, coalesceMs);
349
+ else queueMicrotask(runAutoSync);
348
350
  }
349
351
 
350
352
  function requireClient(): SyncClient {
@@ -383,6 +385,7 @@ export function startSyncWorkerCore(
383
385
  );
384
386
  }
385
387
  autoSync = config.autoSync ?? true;
388
+ coalesceMs = config.coalesceMs ?? 0;
386
389
  headers = config.headers ?? {};
387
390
  const http = { headers: () => headers };
388
391
 
@@ -546,6 +549,8 @@ export function startSyncWorkerCore(
546
549
  'commitOutcome',
547
550
  'commitOutcomes',
548
551
  'resolveCommitOutcome',
552
+ 'commitDelivery',
553
+ 'replaceCommitOutcome',
549
554
  'pendingCommits',
550
555
  'units',
551
556
  'unit',
@@ -572,11 +577,11 @@ export function startSyncWorkerCore(
572
577
  await requireClient().beginSecurityPreflight();
573
578
  },
574
579
  activateSecurity: async (options = {}) => {
575
- await requireClient().activateSecurity({
576
- ...(options.encryption !== undefined
577
- ? { encryption: encryptionConfigFromKeyring(options.encryption) }
578
- : {}),
579
- });
580
+ await requireClient().activateSecurity(
581
+ options.encryption === undefined
582
+ ? {}
583
+ : { encryption: encryptionConfigFromKeyring(options.encryption) },
584
+ );
580
585
  },
581
586
  setWindow: async (base, units) => {
582
587
  await requireClient().setWindowCommand(base, units);
@@ -587,13 +592,7 @@ export function startSyncWorkerCore(
587
592
  patch: (table, rowId, partial, options) => {
588
593
  // Same §8.4 rule as `mutate`: a local write must push without the app
589
594
  // orchestrating sync, so consume the core's immediate intent.
590
- const result = requireClient().patchCommand(
591
- table,
592
- rowId,
593
- partial,
594
- options,
595
- );
596
- return result.value;
595
+ return requireClient().patchCommand(table, rowId, partial, options).value;
597
596
  },
598
597
  sync: () => {
599
598
  const running = requireClient();
@@ -681,10 +680,7 @@ export function startSyncWorkerCore(
681
680
  void (async () => {
682
681
  try {
683
682
  const value = await fn();
684
- post(
685
- { t: 'result', id, value },
686
- transfer !== undefined ? transfer(value) : undefined,
687
- );
683
+ post({ t: 'result', id, value }, transfer?.(value));
688
684
  } catch (error) {
689
685
  post({ t: 'error', id, error: toErrorShape(error) });
690
686
  }
@@ -3,7 +3,7 @@ import {
3
3
  type SyncProgress,
4
4
  type SyncProgressListener,
5
5
  } from './progress';
6
- import type { PromiseMethods } from './client';
6
+ import type { CommitDelivery, PromiseMethods } from './client';
7
7
  /**
8
8
  * Main-thread side of the worker mode and the
9
9
  * multi-tab topology.
@@ -37,6 +37,7 @@ import type {
37
37
  ConflictRecord,
38
38
  CurrentBaseProof,
39
39
  MutationInput,
40
+ ReplaceCommitOutcomeInput,
40
41
  PresencePeer,
41
42
  QueryReadSpec,
42
43
  QuerySnapshot,
@@ -223,6 +224,11 @@ export interface SyncClientHandleConfig {
223
224
  readonly previousVersionContext?: SyncClientConfig['previousVersionContext'];
224
225
  /** Worker-side host loop (§8.4); default true. */
225
226
  readonly autoSync?: boolean;
227
+ /**
228
+ * §8.4: milliseconds a queued `autoSync` drive waits before it starts, so
229
+ * the claims and writes of one burst ride in one round. Default 0.
230
+ */
231
+ readonly coalesceMs?: number;
226
232
  /**
227
233
  * Default: Web Locks. A runtime without Web Locks refuses the handle with
228
234
  * `client.web_locks_unavailable` unless the host injects a lock.
@@ -823,6 +829,21 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
823
829
  return this.#call('resolveCommitOutcome', [input]);
824
830
  }
825
831
 
832
+ commitDelivery(id: string): Promise<CommitDelivery> {
833
+ return this.#call('commitDelivery', [id]);
834
+ }
835
+
836
+ /** §7.2.2: record a decision as a replacement held for a proven base. */
837
+ replaceCommitOutcome({
838
+ clientCommitId,
839
+ sequence,
840
+ replacement,
841
+ }: ReplaceCommitOutcomeInput): Promise<string> {
842
+ return this.#call('replaceCommitOutcome', [
843
+ { clientCommitId, sequence, replacement },
844
+ ]);
845
+ }
846
+
826
847
  /** §7.4.5: true while a schema-bump reset + first re-bootstrap runs. */
827
848
  pendingCommits(): Promise<OutboxCommit[]> {
828
849
  return this.#call('pendingCommits', []);
@@ -1121,6 +1142,9 @@ function buildInitConfig(
1121
1142
  ? { previousVersionContext: config.previousVersionContext }
1122
1143
  : {}),
1123
1144
  ...(config.autoSync !== undefined ? { autoSync: config.autoSync } : {}),
1145
+ ...(config.coalesceMs !== undefined
1146
+ ? { coalesceMs: config.coalesceMs }
1147
+ : {}),
1124
1148
  };
1125
1149
  }
1126
1150
 
@@ -1164,6 +1188,11 @@ export async function createSyncClientHandle(
1164
1188
  config: SyncClientHandleConfig,
1165
1189
  ): Promise<SyncClientHandle> {
1166
1190
  const resolvedConfig = resolveReplicaConfig(config);
1191
+ if (
1192
+ config.coalesceMs !== undefined &&
1193
+ !(Number.isFinite(config.coalesceMs) && config.coalesceMs >= 0)
1194
+ )
1195
+ throw invalidRequest('coalesceMs must be a non-negative finite number');
1167
1196
  const lock = resolvedConfig.leaderLock ?? defaultLeaderLock();
1168
1197
  const lockName = resolvedConfig.lockName ?? 'syncular-leader';
1169
1198
  const invalidation = new InvalidationEmitter();
@@ -23,6 +23,7 @@ import type {
23
23
  ConflictRecord,
24
24
  CurrentBaseProof,
25
25
  ClientSnapshotMethods,
26
+ ReplaceCommitOutcomeInput,
26
27
  MutationInput,
27
28
  PresencePeer,
28
29
  QueryReadSpec,
@@ -160,6 +161,8 @@ export interface WorkerInitConfig {
160
161
  * `syncUntilIdle` rounds inside the worker. Default true.
161
162
  */
162
163
  readonly autoSync?: boolean;
164
+ /** Delay of a queued `autoSync` drive (§8.4); validated by the handle. */
165
+ readonly coalesceMs?: number;
163
166
  }
164
167
 
165
168
  /** Successful init reply. */
@@ -221,6 +224,7 @@ export interface WorkerApi extends Omit<
221
224
  outcome: Pick<CommitOutcome, 'clientCommitId' | 'sequence'>,
222
225
  maxRounds?: number,
223
226
  ): Promise<CurrentBaseProof>;
227
+ replaceCommitOutcome(input: ReplaceCommitOutcomeInput): string;
224
228
  resetClientId(): string;
225
229
  query(sql: string, params?: readonly SqlValue[]): SqlRow[];
226
230
  authoritySnapshot(): import('./authority').AuthoritySnapshot;