@syncular/client 0.70.1 → 0.70.3

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.js CHANGED
@@ -27,7 +27,7 @@ import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatch
27
27
  import { compileLocalDataRebootstrap, localDataRebootstrapMetaKey, } from './local-rebootstrap.js';
28
28
  import { decodeLocalDataRebootstrapReceipt, encodeLocalDataRebootstrapReceipt, } from './local-rebootstrap-receipt.js';
29
29
  import { appendOutboxCommit, chainsOn, deleteOutboxCommit, encodeOutboxCommit, listOutbox, iterateOutbox, countOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
30
- import { activeFailureRecords, isStoredOperation, listCommitOutcomes, persistCommitOutcomeResolution, persistedCommitOutcome, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
30
+ import { activeFailureRecords, isStoredOperation, listCommitOutcomes, persistCommitOutcomeResolution, persistedCommitOutcome, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, scrubPurgedOutcomes, } from './outcomes.js';
31
31
  import { buildPreviousVersionAudit, capturePreviousVersion, clearPreviousVersionAudit, clearPreviousVersionRefusal, dropPreviousVersionContainer, loadLocalSchemaDescriptor, PREVIOUS_VERSION_CONTAINER_NAME, PREVIOUS_VERSION_MAX_LIMIT, readPreviousVersionContainer, readPreviousVersionRows, setLocalSchemaDescriptor, storedPreviousVersionAudit, storedPreviousVersionRefusal, withPreviousVersionContainer, writePreviousVersionAudit, writePreviousVersionRefusal, } from './previous-version.js';
32
32
  import { bytesToHex, compileClientSchema, hexToBytes, matchesLocalScopes, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, localColumnType, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
33
33
  import { bootstrapping, bumpLocalRevision, covers, deleteUnit, ECHO_DIGEST_KEY, getLocalRevision, getMeta, getUnit, loadUnits, META_TABLE, owning, pairScopes, pruneUnknownUnits, REGISTERED_DIGEST_KEY, REPLICA_CURSOR_KEY, replicaCursor, resetUnits, saveUnit, saveUnitScopeSchema, setMeta, unitOwners, } from './state.js';
@@ -2437,6 +2437,8 @@ export class SyncClient {
2437
2437
  if (appliedPlan !== purge.canonicalPlan) {
2438
2438
  throw invalidRequest(`local purge id ${JSON.stringify(purge.purgeId)} was already used with a different plan`);
2439
2439
  }
2440
+ // A retry after a failed rewrite finishes it.
2441
+ this.#erasePurgedPages();
2440
2442
  return { alreadyApplied: true, purgedRows: 0, droppedCommits: 0 };
2441
2443
  }
2442
2444
  // RFC 0005 D7: the container file cannot be a purge target (its name is not
@@ -2445,8 +2447,9 @@ export class SyncClient {
2445
2447
  this.#dropPreviousVersion();
2446
2448
  const priorRejections = [...this.#rejections];
2447
2449
  const priorConflicts = [...this.#conflicts];
2450
+ let result;
2448
2451
  try {
2449
- return this.#applyBatch((batch) => {
2452
+ result = this.#applyBatch((batch) => {
2450
2453
  const targetsByTable = this.#localPurgeTargetsByTable(purge);
2451
2454
  restoreFailedBases(this.#db, this.#schema);
2452
2455
  this.#dropRetainedRows(batch, (table, values) => (targetsByTable.get(table) ?? []).some((target) => target.selectors.every((selector) => selector.values.includes(String(values[selector.column])))));
@@ -2505,16 +2508,21 @@ export class SyncClient {
2505
2508
  this.#db.exec(`DELETE FROM ${quoteIdent(tableName)} WHERE ${quoteIdent(table.primaryKey)} IN(${chunk.map(() => '?').join(', ')})`, chunk);
2506
2509
  }
2507
2510
  }
2511
+ if (scrubPurgedOutcomes(this.#db, (table, rowId, values) => (targetsByTable.get(table) ?? []).some((target) => rowIds.get(table)?.has(rowId) === true ||
2512
+ (values !== undefined &&
2513
+ localDataPurgeTargetMatches(target, values)))))
2514
+ batch.outcomes();
2508
2515
  if (doomed.length > 0) {
2516
+ // §5.11 purge erasure: the journal keeps a dropped commit's identity and codes,
2517
+ // never its operations, so no purged value survives in it.
2509
2518
  for (const commit of doomed) {
2510
- const results = commit.operations.map((operation, opIndex) => {
2519
+ const results = commit.operations.map((_operation, opIndex) => {
2511
2520
  const rejection = {
2512
2521
  clientCommitId: commit.clientCommitId,
2513
2522
  opIndex,
2514
2523
  code: 'client.local_data_purged',
2515
2524
  message: 'the commit was dropped by an application-authorized local data purge',
2516
2525
  retryable: false,
2517
- operation,
2518
2526
  };
2519
2527
  this.#rejections.push(rejection);
2520
2528
  return { status: 'error', rejection };
@@ -2524,7 +2532,6 @@ export class SyncClient {
2524
2532
  status: 'rejected',
2525
2533
  recordedAtMs: this.#now(),
2526
2534
  results,
2527
- operations: commit.operations,
2528
2535
  });
2529
2536
  }
2530
2537
  pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
@@ -2549,6 +2556,24 @@ export class SyncClient {
2549
2556
  this.#conflicts = priorConflicts;
2550
2557
  throw error;
2551
2558
  }
2559
+ this.#erasePurgedPages();
2560
+ return result;
2561
+ }
2562
+ /**
2563
+ * §5.11 purge erasure: SQLite leaves a deleted value in the freed pages of the database
2564
+ * file, and a file replica's WAL keeps the frames written before the
2565
+ * purge, until either is rewritten. VACUUM rebuilds the file from the
2566
+ * remaining rows, and the checkpoint truncates the WAL.
2567
+ */
2568
+ #erasePurgedPages() {
2569
+ this.#db.exec('PRAGMA secure_delete = ON');
2570
+ try {
2571
+ this.#db.exec('VACUUM');
2572
+ this.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
2573
+ }
2574
+ finally {
2575
+ this.#db.exec('PRAGMA secure_delete = OFF');
2576
+ }
2552
2577
  }
2553
2578
  /**
2554
2579
  * Rebuild the server-derived local projection without sacrificing offline
@@ -118,3 +118,9 @@ export declare function activeFailureRecords(outcomes: readonly CommitOutcome[])
118
118
  readonly conflicts: ConflictRecord[];
119
119
  readonly rejections: RejectionRecord[];
120
120
  };
121
+ /**
122
+ * §5.11 purge erasure: every journal entry with an operation, or a conflict
123
+ * row, that `touches` accepts keeps its identity, status, ids and codes only.
124
+ * Returns whether an entry changed.
125
+ */
126
+ export declare function scrubPurgedOutcomes(db: ClientDatabase, touches: (table: string, rowId: string, values: Readonly<Record<string, unknown>> | undefined) => boolean): boolean;
package/dist/outcomes.js CHANGED
@@ -306,3 +306,67 @@ export function activeFailureRecords(outcomes) {
306
306
  }
307
307
  return { conflicts, rejections };
308
308
  }
309
+ /**
310
+ * §5.11 purge erasure: every journal entry with an operation, or a conflict
311
+ * row, that `touches` accepts keeps its identity, status, ids and codes only.
312
+ * Returns whether an entry changed.
313
+ */
314
+ export function scrubPurgedOutcomes(db, touches) {
315
+ let changed = false;
316
+ for (const row of db.query(`SELECT client_commit_id,results,operations FROM ${OUTCOMES_TABLE}`)) {
317
+ const results = JSON.parse(String(row.results));
318
+ const operations = typeof row.operations === 'string'
319
+ ? JSON.parse(row.operations)
320
+ : [];
321
+ const named = [
322
+ ...operations,
323
+ ...results.flatMap((result) => result.status === 'conflict'
324
+ ? [
325
+ {
326
+ table: result.conflict.table,
327
+ rowId: result.conflict.rowId,
328
+ values: result.conflict.serverRow,
329
+ },
330
+ ...(result.conflict.operation === undefined
331
+ ? []
332
+ : [result.conflict.operation]),
333
+ ]
334
+ : result.status === 'error' &&
335
+ result.rejection.operation !== undefined
336
+ ? [result.rejection.operation]
337
+ : []),
338
+ ];
339
+ if (!named.some((op) => touches(op.table, op.rowId, op.values)))
340
+ continue;
341
+ const scrubbed = results.map((result) => {
342
+ if (result.status === 'conflict') {
343
+ const { clientCommitId, opIndex, table, rowId, code, message } = result.conflict;
344
+ return {
345
+ status: 'conflict',
346
+ conflict: {
347
+ clientCommitId,
348
+ opIndex,
349
+ table,
350
+ rowId,
351
+ code,
352
+ message,
353
+ serverVersion: result.conflict.serverVersion,
354
+ serverRow: {},
355
+ conflictColumns: [],
356
+ },
357
+ };
358
+ }
359
+ if (result.status === 'error') {
360
+ const { clientCommitId, opIndex, code, message, retryable } = result.rejection;
361
+ return {
362
+ status: 'error',
363
+ rejection: { clientCommitId, opIndex, code, message, retryable },
364
+ };
365
+ }
366
+ return result;
367
+ });
368
+ db.exec(`UPDATE ${OUTCOMES_TABLE} SET results=?,operations=NULL WHERE client_commit_id=?`, [JSON.stringify(scrubbed), String(row.client_commit_id)]);
369
+ changed = true;
370
+ }
371
+ return changed;
372
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.70.1",
3
+ "version": "0.70.3",
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.70.1"
124
+ "@syncular/core": "0.70.3"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.70.1",
128
+ "@syncular/server": "0.70.3",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
package/src/client.ts CHANGED
@@ -191,6 +191,7 @@ import {
191
191
  type ResolveCommitOutcomeInput,
192
192
  commitOutcome as readCommitOutcome,
193
193
  recordCommitOutcome,
194
+ scrubPurgedOutcomes,
194
195
  } from './outcomes';
195
196
  import {
196
197
  buildPreviousVersionAudit,
@@ -3688,6 +3689,8 @@ export class SyncClient {
3688
3689
  `local purge id ${JSON.stringify(purge.purgeId)} was already used with a different plan`,
3689
3690
  );
3690
3691
  }
3692
+ // A retry after a failed rewrite finishes it.
3693
+ this.#erasePurgedPages();
3691
3694
  return { alreadyApplied: true, purgedRows: 0, droppedCommits: 0 };
3692
3695
  }
3693
3696
  // RFC 0005 D7: the container file cannot be a purge target (its name is not
@@ -3697,8 +3700,9 @@ export class SyncClient {
3697
3700
 
3698
3701
  const priorRejections = [...this.#rejections];
3699
3702
  const priorConflicts = [...this.#conflicts];
3703
+ let result: LocalDataPurgeResult;
3700
3704
  try {
3701
- return this.#applyBatch((batch) => {
3705
+ result = this.#applyBatch((batch) => {
3702
3706
  const targetsByTable = this.#localPurgeTargetsByTable(purge);
3703
3707
  restoreFailedBases(this.#db, this.#schema);
3704
3708
  this.#dropRetainedRows(batch, (table, values) =>
@@ -3778,11 +3782,24 @@ export class SyncClient {
3778
3782
  );
3779
3783
  }
3780
3784
  }
3785
+ if (
3786
+ scrubPurgedOutcomes(this.#db, (table, rowId, values) =>
3787
+ (targetsByTable.get(table) ?? []).some(
3788
+ (target) =>
3789
+ rowIds.get(table)?.has(rowId) === true ||
3790
+ (values !== undefined &&
3791
+ localDataPurgeTargetMatches(target, values)),
3792
+ ),
3793
+ )
3794
+ )
3795
+ batch.outcomes();
3781
3796
 
3782
3797
  if (doomed.length > 0) {
3798
+ // §5.11 purge erasure: the journal keeps a dropped commit's identity and codes,
3799
+ // never its operations, so no purged value survives in it.
3783
3800
  for (const commit of doomed) {
3784
3801
  const results: CommitOperationOutcome[] = commit.operations.map(
3785
- (operation, opIndex) => {
3802
+ (_operation, opIndex) => {
3786
3803
  const rejection: RejectionRecord = {
3787
3804
  clientCommitId: commit.clientCommitId,
3788
3805
  opIndex,
@@ -3790,7 +3807,6 @@ export class SyncClient {
3790
3807
  message:
3791
3808
  'the commit was dropped by an application-authorized local data purge',
3792
3809
  retryable: false,
3793
- operation,
3794
3810
  };
3795
3811
  this.#rejections.push(rejection);
3796
3812
  return { status: 'error', rejection };
@@ -3801,7 +3817,6 @@ export class SyncClient {
3801
3817
  status: 'rejected',
3802
3818
  recordedAtMs: this.#now(),
3803
3819
  results,
3804
- operations: commit.operations,
3805
3820
  });
3806
3821
  }
3807
3822
  pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
@@ -3825,6 +3840,24 @@ export class SyncClient {
3825
3840
  this.#conflicts = priorConflicts;
3826
3841
  throw error;
3827
3842
  }
3843
+ this.#erasePurgedPages();
3844
+ return result;
3845
+ }
3846
+
3847
+ /**
3848
+ * §5.11 purge erasure: SQLite leaves a deleted value in the freed pages of the database
3849
+ * file, and a file replica's WAL keeps the frames written before the
3850
+ * purge, until either is rewritten. VACUUM rebuilds the file from the
3851
+ * remaining rows, and the checkpoint truncates the WAL.
3852
+ */
3853
+ #erasePurgedPages(): void {
3854
+ this.#db.exec('PRAGMA secure_delete = ON');
3855
+ try {
3856
+ this.#db.exec('VACUUM');
3857
+ this.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
3858
+ } finally {
3859
+ this.#db.exec('PRAGMA secure_delete = OFF');
3860
+ }
3828
3861
  }
3829
3862
 
3830
3863
  /**
package/src/outcomes.ts CHANGED
@@ -530,3 +530,86 @@ export function activeFailureRecords(outcomes: readonly CommitOutcome[]): {
530
530
  }
531
531
  return { conflicts, rejections };
532
532
  }
533
+
534
+ /**
535
+ * §5.11 purge erasure: every journal entry with an operation, or a conflict
536
+ * row, that `touches` accepts keeps its identity, status, ids and codes only.
537
+ * Returns whether an entry changed.
538
+ */
539
+ export function scrubPurgedOutcomes(
540
+ db: ClientDatabase,
541
+ touches: (
542
+ table: string,
543
+ rowId: string,
544
+ values: Readonly<Record<string, unknown>> | undefined,
545
+ ) => boolean,
546
+ ): boolean {
547
+ let changed = false;
548
+ for (const row of db.query(
549
+ `SELECT client_commit_id,results,operations FROM ${OUTCOMES_TABLE}`,
550
+ )) {
551
+ const results = JSON.parse(
552
+ String(row.results),
553
+ ) as StoredCommitOperationOutcome[];
554
+ const operations =
555
+ typeof row.operations === 'string'
556
+ ? (JSON.parse(row.operations) as OutboxOperation[])
557
+ : [];
558
+ const named = [
559
+ ...operations,
560
+ ...results.flatMap((result) =>
561
+ result.status === 'conflict'
562
+ ? [
563
+ {
564
+ table: result.conflict.table,
565
+ rowId: result.conflict.rowId,
566
+ values: result.conflict.serverRow,
567
+ },
568
+ ...(result.conflict.operation === undefined
569
+ ? []
570
+ : [result.conflict.operation]),
571
+ ]
572
+ : result.status === 'error' &&
573
+ result.rejection.operation !== undefined
574
+ ? [result.rejection.operation]
575
+ : [],
576
+ ),
577
+ ];
578
+ if (!named.some((op) => touches(op.table, op.rowId, op.values))) continue;
579
+ const scrubbed: StoredCommitOperationOutcome[] = results.map((result) => {
580
+ if (result.status === 'conflict') {
581
+ const { clientCommitId, opIndex, table, rowId, code, message } =
582
+ result.conflict;
583
+ return {
584
+ status: 'conflict',
585
+ conflict: {
586
+ clientCommitId,
587
+ opIndex,
588
+ table,
589
+ rowId,
590
+ code,
591
+ message,
592
+ serverVersion: result.conflict.serverVersion,
593
+ serverRow: {},
594
+ conflictColumns: [],
595
+ },
596
+ };
597
+ }
598
+ if (result.status === 'error') {
599
+ const { clientCommitId, opIndex, code, message, retryable } =
600
+ result.rejection;
601
+ return {
602
+ status: 'error',
603
+ rejection: { clientCommitId, opIndex, code, message, retryable },
604
+ };
605
+ }
606
+ return result;
607
+ });
608
+ db.exec(
609
+ `UPDATE ${OUTCOMES_TABLE} SET results=?,operations=NULL WHERE client_commit_id=?`,
610
+ [JSON.stringify(scrubbed), String(row.client_commit_id)],
611
+ );
612
+ changed = true;
613
+ }
614
+ return changed;
615
+ }