@syncular/client 0.66.1 → 0.67.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/apply.d.ts CHANGED
@@ -81,8 +81,9 @@ export interface SqliteSegmentDescriptor {
81
81
  export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, bytes: Uint8Array, descriptor: SqliteSegmentDescriptor, options: {
82
82
  readonly clearFirst: boolean;
83
83
  readonly effective: ScopeMap;
84
- /** Pair scopes of the units that own rows of the table (§3.3). */
85
- readonly owners: readonly ScopeMap[];
84
+ /** Pair scopes of the units that own rows of the table (§3.3), read
85
+ * inside the clearing transaction. */
86
+ readonly owners: () => readonly ScopeMap[];
86
87
  readonly transaction?: ApplyTransaction;
87
88
  readonly onProgress?: (rowsProcessed: number) => void;
88
89
  readonly isCurrent?: () => boolean;
@@ -98,8 +99,9 @@ export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledC
98
99
  export declare function applyRowsSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, segment: RowsSegment, options: {
99
100
  readonly clearFirst: boolean;
100
101
  readonly effective: ScopeMap;
101
- /** Pair scopes of the units that own rows of the table (§3.3). */
102
- readonly owners: readonly ScopeMap[];
102
+ /** Pair scopes of the units that own rows of the table (§3.3), read
103
+ * inside the clearing transaction. */
104
+ readonly owners: () => readonly ScopeMap[];
103
105
  readonly transaction?: ApplyTransaction;
104
106
  readonly onProgress?: (rowsProcessed: number) => void;
105
107
  readonly isCurrent?: () => boolean;
package/dist/apply.js CHANGED
@@ -150,23 +150,39 @@ export function localScopePredicate(table, effective, owners) {
150
150
  if (!entries.length || entries.some(([, values]) => !values.length))
151
151
  return;
152
152
  const params = [];
153
- const sql = entries
154
- .map(([variable, values]) => {
153
+ const within = (variable, list) => {
155
154
  const column = table.scopeColumnByVariable.get(variable);
156
155
  if (column === undefined)
157
156
  throw new ClientSyncError('sync.scope_revoked', 'table has no local scope-column mapping');
158
- params.push(...values);
159
- return `${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`;
160
- })
161
- .join(' AND ');
162
- const kept = owners.flatMap((owner) => {
163
- const scope = localScopePredicate(table, owner, []);
164
- if (scope === undefined)
165
- return [];
166
- params.push(...scope.params);
167
- return [` AND NOT (${scope.sql})`];
157
+ return `${quoteIdent(column)} IN (SELECT value FROM json_each(${list}))`;
158
+ };
159
+ const clauses = entries.map(([variable, values]) => {
160
+ params.push(JSON.stringify(values));
161
+ return within(variable, '?');
168
162
  });
169
- return { sql: sql + kept.join(''), params };
163
+ // Owners bind as one JSON parameter per variable set, so the statement
164
+ // stays the same size at any owner count; owners of one variable bind the
165
+ // union of their values. An owner holding another value of a variable
166
+ // `effective` names owns none of its rows and drops out.
167
+ const groups = new Map();
168
+ for (const owner of owners) {
169
+ const keys = Object.keys(owner).sort();
170
+ if (keys.some((key) => effective[key]?.every((value) => !owner[key].includes(value))))
171
+ continue;
172
+ const tuples = groups.get(keys.join()) ?? [];
173
+ tuples.push(keys.map((key) => owner[key]));
174
+ groups.set(keys.join(), tuples);
175
+ }
176
+ for (const [key, tuples] of groups) {
177
+ const keys = key.split(',');
178
+ params.push(JSON.stringify(keys[1] ? tuples : tuples.flat(2)));
179
+ clauses.push(keys[1]
180
+ ? `NOT EXISTS (SELECT 1 FROM json_each(?) o WHERE ${keys
181
+ .map((variable, i) => within(variable, `o.value,'$[${i}]'`))
182
+ .join(' AND ')})`
183
+ : `NOT ${within(key, '?')}`);
184
+ }
185
+ return { sql: clauses.join(' AND '), params };
170
186
  }
171
187
  /** {@link localScopePredicate} over decoded row values (retained rows). */
172
188
  export function ownsLocalRow(table, effective, owners, values) {
@@ -340,13 +356,13 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
340
356
  : [
341
357
  ...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
342
358
  ...(first && options.clearFirst
343
- ? bootstrapScope(db, table, options.effective, options.owners)
359
+ ? bootstrapScope(db, table, options.effective, options.owners())
344
360
  : []),
345
361
  ...rows.map((row) => JSON.stringify([table.name, String(row[table.primaryKey])])),
346
362
  ];
347
363
  const protectedRows = restoreFailedBases(db, schema, scope);
348
364
  if (first && options.clearFirst)
349
- deleteScopedRows(db, table, options.effective, options.owners);
365
+ deleteScopedRows(db, table, options.effective, options.owners());
350
366
  const kept = new Set();
351
367
  const skipped = new Set();
352
368
  const landing = rows.filter((row) => lands(db, table, String(row[table.primaryKey]), Number(row._syncular_version), kept, skipped));
@@ -421,7 +437,7 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
421
437
  const scope = [
422
438
  ...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
423
439
  ...(clearThisBlock
424
- ? bootstrapScope(db, table, options.effective, options.owners)
440
+ ? bootstrapScope(db, table, options.effective, options.owners())
425
441
  : []),
426
442
  ...rows.map((row) => JSON.stringify([
427
443
  table.name,
@@ -430,7 +446,7 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
430
446
  ];
431
447
  const protectedRows = restoreFailedBases(db, schema, scope);
432
448
  if (clearThisBlock) {
433
- deleteScopedRows(db, table, options.effective, options.owners);
449
+ deleteScopedRows(db, table, options.effective, options.owners());
434
450
  }
435
451
  const kept = new Set();
436
452
  const skipped = new Set();
package/dist/client.js CHANGED
@@ -4373,7 +4373,7 @@ export class SyncClient {
4373
4373
  let written = started;
4374
4374
  const result = this.#applyBatch((batch) => {
4375
4375
  if (hasRows ||
4376
- (clearFirst && this.#scopedRowsExist(table, effective, owners)))
4376
+ (clearFirst && this.#scopedRowsExist(table, effective, owners())))
4377
4377
  batch.table(table.name);
4378
4378
  const result = fn();
4379
4379
  this.#replayOutbox(result, false);
@@ -4406,8 +4406,14 @@ export class SyncClient {
4406
4406
  : undefined;
4407
4407
  if (effective === undefined)
4408
4408
  throw invalidRequest('a segment names no active pair of its unit');
4409
+ // §3.3 owners matter only for rows the clear would reach, so a pair
4410
+ // with no matching local or retained row never reads the unit list.
4411
+ let owners;
4409
4412
  try {
4410
- summary.segmentRowsApplied += await apply(table, !section.seeded.has(tableName), effective, unitOwners(loadUnits(this.#db), table, unit.id));
4413
+ summary.segmentRowsApplied += await apply(table, !section.seeded.has(tableName), effective, () => (owners ??=
4414
+ this.#db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? LIMIT 1`, [table.name]).length > 0 || this.#scopedRowsExist(table, effective, [])
4415
+ ? unitOwners(loadUnits(this.#db), table, unit.id)
4416
+ : []));
4411
4417
  section.seeded.add(tableName);
4412
4418
  }
4413
4419
  catch (error) {
@@ -4512,7 +4518,7 @@ export class SyncClient {
4512
4518
  return;
4513
4519
  }
4514
4520
  const revoked = start.status === 'revoked';
4515
- const units = loadUnits(this.#db);
4521
+ let units;
4516
4522
  let failed = false;
4517
4523
  let rearmed = false;
4518
4524
  for (const table of this.#schema.tables.values()) {
@@ -4530,7 +4536,7 @@ export class SyncClient {
4530
4536
  // §3.3: purge a pair the response revokes, keyed on the echo the
4531
4537
  // client persisted while the pair was active.
4532
4538
  if (last !== undefined && next === undefined)
4533
- failed ||= !this.#purgePair(batch, table, last, unitOwners(units, table, unit.id));
4539
+ failed ||= !this.#purgePair(batch, table, last, unitOwners((units ??= loadUnits(this.#db)), table, unit.id));
4534
4540
  }
4535
4541
  if (revoked || failed) {
4536
4542
  saveUnit(this.#db, {
package/dist/schema.js CHANGED
@@ -433,6 +433,7 @@ export function ensureLocalBookkeepingSchema(db) {
433
433
  // §4.8 window registry: base + value → the unit it holds, the
434
434
  // completeness oracle and one of a unit's references (§4.1).
435
435
  createTable(WINDOWS_TABLE, 'base TEXT NOT NULL,unit TEXT NOT NULL,sub_id TEXT NOT NULL,PRIMARY KEY(base,unit)');
436
+ db.exec(`CREATE INDEX IF NOT EXISTS ${WINDOWS_TABLE}_unit ON ${WINDOWS_TABLE}(sub_id)`);
436
437
  // §4.8 E1: per-table scopes of units that left with pinned or unevicted
437
438
  // rows. Retried when the outbox drains; cancelled when the unit re-enters.
438
439
  createTable(PENDING_EVICTIONS, 'unit_id TEXT NOT NULL,tbl TEXT NOT NULL,effective_scopes TEXT NOT NULL,PRIMARY KEY(unit_id,tbl)');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.66.1",
3
+ "version": "0.67.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.66.1"
124
+ "@syncular/core": "0.67.0"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.66.1",
128
+ "@syncular/server": "0.67.0",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
package/src/apply.ts CHANGED
@@ -248,25 +248,48 @@ export function localScopePredicate(
248
248
  const entries = Object.entries(effective);
249
249
  if (!entries.length || entries.some(([, values]) => !values.length)) return;
250
250
  const params: string[] = [];
251
- const sql = entries
252
- .map(([variable, values]) => {
253
- const column = table.scopeColumnByVariable.get(variable);
254
- if (column === undefined)
255
- throw new ClientSyncError(
256
- 'sync.scope_revoked',
257
- 'table has no local scope-column mapping',
258
- );
259
- params.push(...values);
260
- return `${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`;
261
- })
262
- .join(' AND ');
263
- const kept = owners.flatMap((owner) => {
264
- const scope = localScopePredicate(table, owner, []);
265
- if (scope === undefined) return [];
266
- params.push(...scope.params);
267
- return [` AND NOT (${scope.sql})`];
251
+ const within = (variable: string, list: string) => {
252
+ const column = table.scopeColumnByVariable.get(variable);
253
+ if (column === undefined)
254
+ throw new ClientSyncError(
255
+ 'sync.scope_revoked',
256
+ 'table has no local scope-column mapping',
257
+ );
258
+ return `${quoteIdent(column)} IN (SELECT value FROM json_each(${list}))`;
259
+ };
260
+ const clauses = entries.map(([variable, values]) => {
261
+ params.push(JSON.stringify(values));
262
+ return within(variable, '?');
268
263
  });
269
- return { sql: sql + kept.join(''), params };
264
+ // Owners bind as one JSON parameter per variable set, so the statement
265
+ // stays the same size at any owner count; owners of one variable bind the
266
+ // union of their values. An owner holding another value of a variable
267
+ // `effective` names owns none of its rows and drops out.
268
+ const groups = new Map<string, string[][][]>();
269
+ for (const owner of owners) {
270
+ const keys = Object.keys(owner).sort();
271
+ if (
272
+ keys.some((key) =>
273
+ effective[key]?.every((value) => !owner[key]!.includes(value)),
274
+ )
275
+ )
276
+ continue;
277
+ const tuples = groups.get(keys.join()) ?? [];
278
+ tuples.push(keys.map((key) => owner[key]!));
279
+ groups.set(keys.join(), tuples);
280
+ }
281
+ for (const [key, tuples] of groups) {
282
+ const keys = key.split(',');
283
+ params.push(JSON.stringify(keys[1] ? tuples : tuples.flat(2)));
284
+ clauses.push(
285
+ keys[1]
286
+ ? `NOT EXISTS (SELECT 1 FROM json_each(?) o WHERE ${keys
287
+ .map((variable, i) => within(variable, `o.value,'$[${i}]'`))
288
+ .join(' AND ')})`
289
+ : `NOT ${within(key, '?')}`,
290
+ );
291
+ }
292
+ return { sql: clauses.join(' AND '), params };
270
293
  }
271
294
 
272
295
  /** {@link localScopePredicate} over decoded row values (retained rows). */
@@ -436,8 +459,9 @@ export async function applySqliteSegment(
436
459
  options: {
437
460
  readonly clearFirst: boolean;
438
461
  readonly effective: ScopeMap;
439
- /** Pair scopes of the units that own rows of the table (§3.3). */
440
- readonly owners: readonly ScopeMap[];
462
+ /** Pair scopes of the units that own rows of the table (§3.3), read
463
+ * inside the clearing transaction. */
464
+ readonly owners: () => readonly ScopeMap[];
441
465
  readonly transaction?: ApplyTransaction;
442
466
  readonly onProgress?: (rowsProcessed: number) => void;
443
467
  readonly isCurrent?: () => boolean;
@@ -554,7 +578,7 @@ export async function applySqliteSegment(
554
578
  : [
555
579
  ...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
556
580
  ...(first && options.clearFirst
557
- ? bootstrapScope(db, table, options.effective, options.owners)
581
+ ? bootstrapScope(db, table, options.effective, options.owners())
558
582
  : []),
559
583
  ...rows.map((row) =>
560
584
  JSON.stringify([table.name, String(row[table.primaryKey])]),
@@ -562,7 +586,7 @@ export async function applySqliteSegment(
562
586
  ];
563
587
  const protectedRows = restoreFailedBases(db, schema, scope);
564
588
  if (first && options.clearFirst)
565
- deleteScopedRows(db, table, options.effective, options.owners);
589
+ deleteScopedRows(db, table, options.effective, options.owners());
566
590
  const kept = new Set<string>();
567
591
  const skipped = new Set<string>();
568
592
  const landing = rows.filter((row) =>
@@ -641,8 +665,9 @@ export async function applyRowsSegment(
641
665
  options: {
642
666
  readonly clearFirst: boolean;
643
667
  readonly effective: ScopeMap;
644
- /** Pair scopes of the units that own rows of the table (§3.3). */
645
- readonly owners: readonly ScopeMap[];
668
+ /** Pair scopes of the units that own rows of the table (§3.3), read
669
+ * inside the clearing transaction. */
670
+ readonly owners: () => readonly ScopeMap[];
646
671
  readonly transaction?: ApplyTransaction;
647
672
  readonly onProgress?: (rowsProcessed: number) => void;
648
673
  readonly isCurrent?: () => boolean;
@@ -677,7 +702,7 @@ export async function applyRowsSegment(
677
702
  const scope: OverlayScope = [
678
703
  ...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
679
704
  ...(clearThisBlock
680
- ? bootstrapScope(db, table, options.effective, options.owners)
705
+ ? bootstrapScope(db, table, options.effective, options.owners())
681
706
  : []),
682
707
  ...rows.map((row) =>
683
708
  JSON.stringify([
@@ -688,7 +713,7 @@ export async function applyRowsSegment(
688
713
  ];
689
714
  const protectedRows = restoreFailedBases(db, schema, scope);
690
715
  if (clearThisBlock) {
691
- deleteScopedRows(db, table, options.effective, options.owners);
716
+ deleteScopedRows(db, table, options.effective, options.owners());
692
717
  }
693
718
  const kept = new Set<string>();
694
719
  const skipped = new Set<string>();
package/src/client.ts CHANGED
@@ -6003,7 +6003,7 @@ export class SyncClient {
6003
6003
  table: CompiledClientTable,
6004
6004
  clearFirst: boolean,
6005
6005
  effective: ScopeMap,
6006
- owners: readonly ScopeMap[],
6006
+ owners: () => readonly ScopeMap[],
6007
6007
  hasRows: boolean,
6008
6008
  resetEpoch: number,
6009
6009
  image: boolean,
@@ -6022,7 +6022,7 @@ export class SyncClient {
6022
6022
  const result = this.#applyBatch((batch) => {
6023
6023
  if (
6024
6024
  hasRows ||
6025
- (clearFirst && this.#scopedRowsExist(table, effective, owners))
6025
+ (clearFirst && this.#scopedRowsExist(table, effective, owners()))
6026
6026
  )
6027
6027
  batch.table(table.name);
6028
6028
  const result = fn();
@@ -6057,7 +6057,7 @@ export class SyncClient {
6057
6057
  table: CompiledClientTable,
6058
6058
  clearFirst: boolean,
6059
6059
  effective: ScopeMap,
6060
- owners: readonly ScopeMap[],
6060
+ owners: () => readonly ScopeMap[],
6061
6061
  ) => number | Promise<number>,
6062
6062
  ): Promise<void> {
6063
6063
  const { unit } = section;
@@ -6067,12 +6067,22 @@ export class SyncClient {
6067
6067
  : undefined;
6068
6068
  if (effective === undefined)
6069
6069
  throw invalidRequest('a segment names no active pair of its unit');
6070
+ // §3.3 owners matter only for rows the clear would reach, so a pair
6071
+ // with no matching local or retained row never reads the unit list.
6072
+ let owners: readonly ScopeMap[] | undefined;
6070
6073
  try {
6071
6074
  summary.segmentRowsApplied += await apply(
6072
6075
  table,
6073
6076
  !section.seeded.has(tableName),
6074
6077
  effective,
6075
- unitOwners(loadUnits(this.#db), table, unit.id),
6078
+ () =>
6079
+ (owners ??=
6080
+ this.#db.query(
6081
+ `SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? LIMIT 1`,
6082
+ [table.name],
6083
+ ).length > 0 || this.#scopedRowsExist(table, effective, [])
6084
+ ? unitOwners(loadUnits(this.#db), table, unit.id)
6085
+ : []),
6076
6086
  );
6077
6087
  section.seeded.add(tableName);
6078
6088
  } catch (error) {
@@ -6205,7 +6215,7 @@ export class SyncClient {
6205
6215
  return;
6206
6216
  }
6207
6217
  const revoked = start.status === 'revoked';
6208
- const units = loadUnits(this.#db);
6218
+ let units: UnitRecord[] | undefined;
6209
6219
  let failed = false;
6210
6220
  let rearmed = false;
6211
6221
  for (const table of this.#schema.tables.values()) {
@@ -6227,7 +6237,7 @@ export class SyncClient {
6227
6237
  batch,
6228
6238
  table,
6229
6239
  last,
6230
- unitOwners(units, table, unit.id),
6240
+ unitOwners((units ??= loadUnits(this.#db)), table, unit.id),
6231
6241
  );
6232
6242
  }
6233
6243
  if (revoked || failed) {
package/src/schema.ts CHANGED
@@ -646,6 +646,9 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
646
646
  WINDOWS_TABLE,
647
647
  'base TEXT NOT NULL,unit TEXT NOT NULL,sub_id TEXT NOT NULL,PRIMARY KEY(base,unit)',
648
648
  );
649
+ db.exec(
650
+ `CREATE INDEX IF NOT EXISTS ${WINDOWS_TABLE}_unit ON ${WINDOWS_TABLE}(sub_id)`,
651
+ );
649
652
  // §4.8 E1: per-table scopes of units that left with pinned or unevicted
650
653
  // rows. Retried when the outbox drains; cancelled when the unit re-enters.
651
654
  createTable(