@syncular/client 0.67.3 → 0.69.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.
package/dist/outbox.js CHANGED
@@ -8,9 +8,22 @@ export const OUTBOX_IMAGES = '_syncular_outbox_before_images';
8
8
  * request is built — a commit recorded under schema N replays after an
9
9
  * upgrade to N+1 by re-encoding.
10
10
  */
11
- import { encodeSparseRow, } from '@syncular/core';
11
+ import { definedObject, encodeSparseRow, } from '@syncular/core';
12
12
  import { ClientSyncError, invalidRequest } from './errors.js';
13
13
  import { jsonToRowValue, } from './schema.js';
14
+ /**
15
+ * §7.1 chained base: `later` repeats `earlier`'s positive base on the same row
16
+ * and presents only columns `earlier` presents.
17
+ */
18
+ export function chainsOn(earlier, later) {
19
+ // Only an upsert carries values, and it always carries its primary key.
20
+ return (later.op === 'upsert' &&
21
+ earlier.rowId === later.rowId &&
22
+ earlier.table === later.table &&
23
+ later.baseVersion > 0 &&
24
+ earlier.baseVersion === later.baseVersion &&
25
+ Object.keys(later.values ?? {}).every((column) => earlier.values?.[column] !== undefined));
26
+ }
14
27
  export function appendOutboxCommit(db, clientCommitId, operations, nowMs, beforeImages = []) {
15
28
  if (operations.length === 0) {
16
29
  throw new ClientSyncError('sync.empty_commit', 'a local commit must carry at least one operation (§6.1)');
@@ -110,8 +123,8 @@ export function replaceOutboxBeforeImages(db, commit, replacements) {
110
123
  * so the caller can drop the commit through the rejection channel.
111
124
  */
112
125
  export class OutboxEncodeError extends ClientSyncError {
113
- constructor(message) {
114
- super('sync.outbox_incompatible', message, false);
126
+ constructor() {
127
+ super('sync.outbox_incompatible', 'the persisted commit cannot encode under the current schema', false);
115
128
  }
116
129
  }
117
130
  function sparseValues(table, values, insert) {
@@ -119,7 +132,7 @@ function sparseValues(table, values, insert) {
119
132
  // bump removed (or renamed) it — the commit cannot be expressed now.
120
133
  for (const key of Object.keys(values)) {
121
134
  if (!table.columnIndex.has(key)) {
122
- throw new OutboxEncodeError(`outbox column ${JSON.stringify(key)} is absent from table ${JSON.stringify(table.name)} (§7.4.4)`);
135
+ throw new OutboxEncodeError();
123
136
  }
124
137
  }
125
138
  return table.columns.map((column) => {
@@ -130,7 +143,7 @@ function sparseValues(table, values, insert) {
130
143
  return undefined;
131
144
  // §7.1: an insert-intent operation presents every current column.
132
145
  if (!column.nullable) {
133
- throw new OutboxEncodeError('an outbox insert lacks a non-nullable column (§7.4.4)');
146
+ throw new OutboxEncodeError();
134
147
  }
135
148
  return null;
136
149
  });
@@ -147,23 +160,21 @@ export async function encodeOutboxCommit(schema, commit, encryption, storedKeyId
147
160
  const operations = [];
148
161
  for (const op of commit.operations) {
149
162
  if (op.op === 'delete') {
150
- operations.push({
163
+ operations.push(definedObject({
151
164
  table: op.table,
152
165
  rowId: op.rowId,
153
166
  op: 'delete',
154
- ...(op.baseVersion !== undefined
155
- ? { baseVersion: op.baseVersion }
156
- : {}),
157
- });
167
+ baseVersion: op.baseVersion,
168
+ }));
158
169
  continue;
159
170
  }
160
171
  const table = schema.tables.get(op.table);
161
172
  if (table === undefined) {
162
173
  // §7.4.4: the bump removed this table — the commit cannot be encoded.
163
- throw new OutboxEncodeError(`outbox table ${JSON.stringify(op.table)} is absent from the current schema (§7.4.4)`);
174
+ throw new OutboxEncodeError();
164
175
  }
165
176
  if (op.values === undefined) {
166
- throw invalidRequest(`outbox upsert on ${op.table}/${op.rowId} has no values`);
177
+ throw invalidRequest('an outbox upsert has no values');
167
178
  }
168
179
  let values = sparseValues(table, op.values, op.insert === true);
169
180
  if (table.hasEncryptedColumns) {
@@ -171,13 +182,13 @@ export async function encodeOutboxCommit(schema, commit, encryption, storedKeyId
171
182
  const { encryptRowValues } = await import('./encryption.js');
172
183
  values = await encryptRowValues(encryption, table, op.rowId, values, storedKeyIdFor?.(table, op.rowId));
173
184
  }
174
- operations.push({
185
+ operations.push(definedObject({
175
186
  table: op.table,
176
187
  rowId: op.rowId,
177
188
  op: 'upsert',
178
- ...(op.baseVersion !== undefined ? { baseVersion: op.baseVersion } : {}),
189
+ baseVersion: op.baseVersion,
179
190
  payload: encodeSparseRow(table.columns, table.primaryKeyIndex, values),
180
- });
191
+ }));
181
192
  }
182
193
  return {
183
194
  type: 'PUSH_COMMIT',
package/dist/outcomes.js CHANGED
@@ -187,10 +187,13 @@ export function recordCommitOutcome(db, outcome) {
187
187
  ]);
188
188
  return commitOutcome(db, outcome.clientCommitId);
189
189
  }
190
- export function commitOutcome(db, clientCommitId) {
191
- const row = db.query(`${SELECT_OUTCOME} WHERE client_commit_id=?`, [
190
+ function outcomeRow(db, clientCommitId) {
191
+ return db.query(`${SELECT_OUTCOME} WHERE client_commit_id=?`, [
192
192
  clientCommitId,
193
193
  ])[0];
194
+ }
195
+ export function commitOutcome(db, clientCommitId) {
196
+ const row = outcomeRow(db, clientCommitId);
194
197
  return row === undefined ? undefined : parseOutcome(db, row);
195
198
  }
196
199
  /**
@@ -200,9 +203,7 @@ export function commitOutcome(db, clientCommitId) {
200
203
  * native sidecar reports, never a raw `SyntaxError`.
201
204
  */
202
205
  export function persistedCommitOutcome(db, clientCommitId) {
203
- const row = db.query(`${SELECT_OUTCOME} WHERE client_commit_id=?`, [
204
- clientCommitId,
205
- ])[0];
206
+ const row = outcomeRow(db, clientCommitId);
206
207
  if (row === undefined)
207
208
  return undefined;
208
209
  function corrupt() {
@@ -4,13 +4,13 @@ export interface SyncProgress {
4
4
  readonly attempt: number;
5
5
  readonly state: 'running' | 'complete' | 'failed';
6
6
  readonly phase: 'request' | 'download' | 'import';
7
- readonly unitId?: string;
8
- readonly table?: string;
7
+ readonly unitId?: string | undefined;
8
+ readonly table?: string | undefined;
9
9
  readonly segmentId?: string | undefined;
10
10
  readonly bytesReceived: number;
11
- readonly bytesTotal?: number;
11
+ readonly bytesTotal?: number | undefined;
12
12
  readonly rowsProcessed: number;
13
- readonly rowsTotal?: number;
13
+ readonly rowsTotal?: number | undefined;
14
14
  /** Time in this payload's import transactions before COMMIT, in ms. */
15
15
  readonly importWriteMs?: number | undefined;
16
16
  /** Time committing them and publishing their changes, in ms. */
@@ -49,8 +49,12 @@ export interface ExternalStoreEntry<T> {
49
49
  export interface WindowRetention {
50
50
  /** Resolves once this retained claim has reached the core window. */
51
51
  readonly ready: Promise<void>;
52
- /** Release only this retention owner's units from the composable union. */
53
- readonly release: () => void;
52
+ /**
53
+ * Release only this retention owner's units from the composable union.
54
+ * Settles with the core window edit that applies the release, after its
55
+ * eviction (§4.8); rejects with that edit's error.
56
+ */
57
+ readonly release: () => Promise<void>;
54
58
  }
55
59
  export interface StatusStoreSnapshot {
56
60
  readonly status: SyncStatusSnapshot | undefined;
@@ -87,7 +91,8 @@ export declare class ReactiveClientStore {
87
91
  retainWindow(base: WindowBase, units: readonly string[]): WindowRetention;
88
92
  window(base: WindowBase): ExternalStoreEntry<WindowState>;
89
93
  setWindowClaim(owner: symbol, base: WindowBase, units: readonly string[]): Promise<void>;
90
- releaseWindowClaims(owner: symbol): void;
94
+ /** Settles once every core window edit that drops the owner's claims ran. */
95
+ releaseWindowClaims(owner: symbol): Promise<void>;
91
96
  /** Retained observation counts for diagnostics and resource benchmarks. */
92
97
  cacheStats(): {
93
98
  queries: number;
@@ -329,7 +329,9 @@ class QueryEntry {
329
329
  this.#offStatus = undefined;
330
330
  this.#offRound?.();
331
331
  this.#offRound = undefined;
332
- this.store.releaseWindowClaims(this.#owner);
332
+ // A failed release leaves the group unapplied; the next claim on
333
+ // the base applies it again. Only a retention handle reports it.
334
+ this.store.releaseWindowClaims(this.#owner).catch(() => { });
333
335
  }
334
336
  };
335
337
  };
@@ -401,7 +403,7 @@ class QueryEntry {
401
403
  this.#offStatus = undefined;
402
404
  this.#offRound?.();
403
405
  this.#offRound = undefined;
404
- this.store.releaseWindowClaims(this.#owner);
406
+ this.store.releaseWindowClaims(this.#owner).catch(() => { });
405
407
  this.reset();
406
408
  }
407
409
  /** SPEC §7.8: a rejected claim is claimed again; its stored error would
@@ -894,9 +896,9 @@ export class ReactiveClientStore {
894
896
  ready,
895
897
  release: () => {
896
898
  if (!active)
897
- return;
899
+ return Promise.resolve();
898
900
  active = false;
899
- this.releaseWindowClaims(owner);
901
+ return this.releaseWindowClaims(owner);
900
902
  },
901
903
  };
902
904
  }
@@ -939,11 +941,18 @@ export class ReactiveClientStore {
939
941
  this.#scheduleWindow(group);
940
942
  return result;
941
943
  }
944
+ /** Settles once every core window edit that drops the owner's claims ran. */
942
945
  releaseWindowClaims(owner) {
946
+ const edits = [];
943
947
  for (const group of this.#windowClaims.values()) {
944
- if (group.claims.delete(owner))
945
- this.#scheduleWindow(group);
948
+ if (!group.claims.delete(owner))
949
+ continue;
950
+ edits.push(new Promise((resolve, reject) => {
951
+ group.waiters.push({ resolve, reject });
952
+ }));
953
+ this.#scheduleWindow(group);
946
954
  }
955
+ return Promise.all(edits).then(() => undefined);
947
956
  }
948
957
  /** Apply every claimed window group again and claim again for query entries
949
958
  * whose claim was rejected. An applied group compares equal and makes no
@@ -377,8 +377,8 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
377
377
  setWindow: async (base, units) => {
378
378
  await requireClient().setWindowCommand(base, units);
379
379
  },
380
- mutate: (mutations) => {
381
- return requireClient().mutateCommand(mutations).value;
380
+ mutate: (mutations, options) => {
381
+ return requireClient().mutateCommand(mutations, options).value;
382
382
  },
383
383
  patch: (table, rowId, partial, options) => {
384
384
  // Same §8.4 rule as `mutate`: a local write must push without the app
@@ -111,7 +111,10 @@ 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
- /** Default: Web Locks when available, else single-owner. */
114
+ /**
115
+ * Default: Web Locks. A runtime without Web Locks refuses the handle with
116
+ * `client.web_locks_unavailable` unless the host injects a lock.
117
+ */
115
118
  readonly leaderLock?: LeaderLock;
116
119
  readonly lockName?: string;
117
120
  /** Shared by default; isolated derives the database/lock/channel tuple. */
@@ -261,7 +264,9 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
261
264
  unsubscribe(id: string): Promise<void>;
262
265
  setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
263
266
  windowState(base: WindowBase): Promise<WindowState>;
264
- mutate(mutations: readonly MutationInput[]): Promise<string>;
267
+ mutate(mutations: readonly MutationInput[], options?: {
268
+ readonly clientCommitId?: string;
269
+ }): Promise<string>;
265
270
  /** Partial-update convenience: read-merge-write one full-row upsert. */
266
271
  patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
267
272
  readonly baseVersion?: number;
@@ -26,7 +26,7 @@ import { serializeBlobRef, } from '@syncular/core';
26
26
  import { ClientDiagnosticsEmitter, withClientDiagnosticsHost, } from './diagnostics.js';
27
27
  import { ClientSyncError, invalidRequest } from './errors.js';
28
28
  import { ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
29
- import { singleOwnerLock, webLocksLeaderLock, } from './leader-lock.js';
29
+ import { webLocksLeaderLock, } from './leader-lock.js';
30
30
  import { decodeLocalDataRebootstrapResult, } from './local-rebootstrap.js';
31
31
  import { createTabCoordinator, multiTabChannelName, TAKEOVER_REFUSED_CODE, } from './multi-tab.js';
32
32
  import { decodePreviousVersionAuditResult, decodePreviousVersionDiscardResult, decodePreviousVersionSnapshot, } from './previous-version.js';
@@ -56,9 +56,9 @@ export function isolatedReplicaNames(options) {
56
56
  }
57
57
  function defaultLeaderLock() {
58
58
  const nav = globalThis.navigator;
59
- return nav?.locks !== undefined
60
- ? webLocksLeaderLock(nav.locks)
61
- : singleOwnerLock();
59
+ if (nav?.locks === undefined)
60
+ throw new ClientSyncError('client.web_locks_unavailable', 'this runtime has no Web Locks; inject a leaderLock');
61
+ return webLocksLeaderLock(nav.locks);
62
62
  }
63
63
  /**
64
64
  * The main-thread proxy: the same logical API as `SyncClient`, every method a
@@ -351,8 +351,8 @@ export class SyncClientHandle {
351
351
  windowState(base) {
352
352
  return this.#call('windowState', [base]);
353
353
  }
354
- mutate(mutations) {
355
- return this.#call('mutate', [mutations]);
354
+ mutate(mutations, options) {
355
+ return this.#call('mutate', [mutations, options]);
356
356
  }
357
357
  /** Partial-update convenience: read-merge-write one full-row upsert. */
358
358
  patch(table, rowId, partial, options) {
@@ -141,7 +141,9 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
141
141
  setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
142
142
  /** §4.8 completeness oracle: the windowed-in values of a base. */
143
143
  windowState(base: WindowBase): WindowState;
144
- mutate(mutations: readonly MutationInput[]): string;
144
+ mutate(mutations: readonly MutationInput[], options?: {
145
+ readonly clientCommitId?: string;
146
+ }): string;
145
147
  /** Partial-update convenience: read-merge-write one full-row upsert. */
146
148
  patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
147
149
  readonly baseVersion?: number;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.67.3",
3
+ "version": "0.69.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.67.3"
124
+ "@syncular/core": "0.69.0"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.67.3",
128
+ "@syncular/server": "0.69.0",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
package/src/apply.ts CHANGED
@@ -1,5 +1,12 @@
1
1
  import { hasUniqueIndex } from './schema';
2
- import { OUTBOX_IMAGES, countOutbox } from './outbox';
2
+ import {
3
+ chainsOn,
4
+ countOutbox,
5
+ listOutbox,
6
+ OUTBOX_IMAGES,
7
+ OUTBOX_TABLE,
8
+ type OutboxOperation,
9
+ } from './outbox';
3
10
  import { RETAINED_ROWS, type OverlayScope } from './failed-overlay';
4
11
  import { retainedBaseWrite, restoreFailedBases } from './failed-overlay';
5
12
  /**
@@ -186,6 +193,25 @@ export async function applyCommitFrame(
186
193
  `UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE tbl=? AND row_id=?`,
187
194
  [frame.commitSeq, change.table.name, rowId],
188
195
  );
196
+ // §7.1 chained base: this change names the version an acknowledged own
197
+ // commit wrote; pending upserts chained on it move to that version.
198
+ for (const { op } of db.query(
199
+ `SELECT op FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq=?`,
200
+ [change.table.name, rowId, frame.commitSeq],
201
+ )) {
202
+ const earlier: OutboxOperation = JSON.parse(op as string);
203
+ for (const commit of listOutbox(db, scope))
204
+ db.exec(`UPDATE ${OUTBOX_TABLE} SET operations=? WHERE seq=?`, [
205
+ JSON.stringify(
206
+ commit.operations.map((operation) =>
207
+ chainsOn(earlier, operation)
208
+ ? { ...operation, baseVersion: rowVersion }
209
+ : operation,
210
+ ),
211
+ ),
212
+ commit.seq,
213
+ ]);
214
+ }
189
215
  db.exec(
190
216
  `DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`,
191
217
  [change.table.name, rowId, frame.commitSeq],