@syncular/client 0.16.1 → 0.17.0

package/README.md

@@ -543,6 +543,14 @@ Node 22.13 or newer. No SQLite package or native addon is required. Both
 adapters support synchronous `exec`, `query`, nested transactions, boolean
 bindings, `null`, `Uint8Array` BLOB values, and §5.3 SQLite-image attachment.
 
+Persistent Bun and Node databases use SQLite WAL journaling with
+`synchronous=FULL`. Each application or sync commit retains its own durable
+transaction. SQLite keeps in-memory databases on its memory journal. Use a
+local filesystem path; WAL uses adjacent `-wal` and `-shm` files. Close every
+connection before copying the database file, or use SQLite's backup facilities
+while it is open. Copying only the main file while writers are active can omit
+committed WAL contents.
+
 Runtime-specific imports remain available:
 
 ```ts

package/dist/bun-database.js

@@ -20,6 +20,17 @@ export class BunClientDatabase {
     #tx = { depth: 0 };
     constructor(path = ':memory:') {
         this.db = new Database(path);
+        // Match native Rust persistence: append durable commits to the WAL
+        // instead of creating and syncing a rollback journal per transaction.
+        // SQLite retains its in-memory journal for :memory: databases.
+        try {
+            this.db.run('PRAGMA journal_mode = WAL');
+            this.db.run('PRAGMA synchronous = FULL');
+        }
+        catch (error) {
+            this.db.close();
+            throw error;
+        }
     }
     exec(sql, params = []) {
         this.db.query(sql).run(...coerceParams(params));

package/dist/client.js

@@ -770,7 +770,7 @@ export class SyncClient {
      * Re-entrant calls share the outer batch so a nested apply never
      * double-emits (e.g. purge → blob reconcile → replay inside one round).
      */
-    #applyBatch(fn, statusSnapshotOverride) {
+    #applyBatch(fn, statusSnapshotOverride, onRollback) {
         if (this.#batch !== undefined)
             return fn(this.#batch);
         const batch = new ChangeAccumulator();
@@ -796,6 +796,7 @@ export class SyncClient {
         }
         catch (error) {
             this.#batch = undefined;
+            onRollback?.(error);
             throw error;
         }
         if (revision !== undefined) {
@@ -929,6 +930,9 @@ export class SyncClient {
             throw new ClientSyncError('sync.invalid_request', `blob content address mismatch for ${blobId} (§5.9.5)`);
         }
         putCachedBlob(this.#db, blobId, bytes, this.#now());
+        // The referencing row can arrive before its body. Pin the new cache entry
+        // from current visible references before applying the size cap (§5.9.7 B1).
+        this.#reconcileBlobs(false);
         this.#enforceBlobCacheCap();
         const stored = getCachedBlob(this.#db, blobId);
         if (stored === undefined) {
@@ -2067,8 +2071,16 @@ export class SyncClient {
         }
         let openedSocket;
         const socket = await connector({
-            onText: (text) => this.#handleRealtimeText(text),
-            onBinary: (bytes) => this.#routeRealtimeBinary(bytes),
+            onText: (text) => {
+                if (generation !== this.#realtimeGeneration || !this.#started)
+                    return;
+                this.#handleRealtimeText(text);
+            },
+            onBinary: (bytes) => {
+                if (generation !== this.#realtimeGeneration || !this.#started)
+                    return;
+                this.#routeRealtimeBinary(bytes);
+            },
             onClose: () => {
                 if (openedSocket === undefined || this.#socket !== openedSocket)
                     return;
@@ -2311,12 +2323,14 @@ export class SyncClient {
         let section;
         let errorFrame;
         let deltaCursor = -1;
-        let responseOutboxCount;
         // Each durable observer transaction emits its own revisioned batch.
         // Async decrypt/download work happens outside SQLite transactions.
         this.#beginDiagnosticsDeferral();
         try {
-            for (const frame of message.frames.slice(1)) {
+            for (let index = 1; index < message.frames.length; index += 1) {
+                const frame = message.frames[index];
+                if (frame === undefined)
+                    break;
                 switch (frame.type) {
                     case 'RESP_HEADER':
                         break;
@@ -2329,13 +2343,41 @@ export class SyncClient {
                         });
                         break;
                     case 'PUSH_RESULT': {
-                        let outboxCount = responseOutboxCount ?? countOutbox(this.#db);
+                        const results = [frame];
+                        if (frame.status !== 'rejected') {
+                            while (index + 1 < message.frames.length) {
+                                const next = message.frames[index + 1];
+                                if (next?.type !== 'PUSH_RESULT' || next.status === 'rejected')
+                                    break;
+                                results.push(next);
+                                index += 1;
+                            }
+                        }
+                        const conflictCount = this.#conflicts.length;
+                        const rejectionCount = this.#rejections.length;
+                        let outboxCount = countOutbox(this.#db);
                         this.#applyBatch((batch) => {
-                            const drained = this.#handlePushResult(frame, commitsById, summary, batch, rejectionDetailsByCommit.get(frame.clientCommitId), frame === lastFinalPushResult);
-                            if (drained)
-                                outboxCount -= 1;
-                        }, () => this.#statusSnapshot(outboxCount));
-                        responseOutboxCount = outboxCount;
+                            let drained = false;
+                            for (const result of results) {
+                                if (this.#handlePushResult(result, commitsById, summary, batch, rejectionDetailsByCommit.get(result.clientCommitId))) {
+                                    outboxCount -= 1;
+                                    drained = true;
+                                }
+                            }
+                            if (drained &&
+                                results.some((result) => result === lastFinalPushResult)) {
+                                pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+                            }
+                        }, () => this.#statusSnapshot(outboxCount), (cause) => {
+                            this.#conflicts.length = conflictCount;
+                            this.#rejections.length = rejectionCount;
+                            const error = new ClientSyncError('client.outcome_persistence_failed', 'local commit outcome could not be persisted');
+                            error.cause = cause;
+                            throw error;
+                        });
+                        for (const conflict of this.#conflicts.slice(conflictCount)) {
+                            this.#config.onConflict?.(conflict);
+                        }
                         break;
                     }
                     case 'PUSH_RESULT_DETAILS':
@@ -2501,7 +2543,7 @@ export class SyncClient {
         }
         return { ...summary, bootstrapping };
     }
-    #handlePushResult(frame, commitsById, summary, batch, rejectionDetails, pruneOutcomes) {
+    #handlePushResult(frame, commitsById, summary, batch, rejectionDetails) {
         const commit = commitsById.get(frame.clientCommitId);
         if (commit === undefined)
             return false;
@@ -2525,9 +2567,6 @@ export class SyncClient {
                 })),
             });
             deleteOutboxCommit(this.#db, frame.clientCommitId);
-            if (pruneOutcomes) {
-                pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
-            }
             batch.status();
             batch.outcomes();
             summary.applied.push(frame.clientCommitId);
@@ -2562,7 +2601,6 @@ export class SyncClient {
                 outcomeResults.push({ status: 'conflict', conflict });
                 batch.conflicts();
                 summary.conflicts.push(conflict);
-                this.#config.onConflict?.(conflict);
             }
             else if (result.status === 'error') {
                 const details = rejectionDetails?.get(result.opIndex);
@@ -2592,9 +2630,6 @@ export class SyncClient {
             results: outcomeResults,
             operations: commit.operations,
         });
-        if (pruneOutcomes) {
-            pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
-        }
         batch.outcomes();
         // §7.2: remove the rejected optimistic layer. Before-images restore
         // validator-rejected updates even when the server emitted no new COMMIT;

package/dist/node-database.js

@@ -32,6 +32,14 @@ export class NodeClientDatabase {
     #tx = { depth: 0 };
     constructor(path = ':memory:') {
         this.db = new DatabaseSync(path);
+        try {
+            this.db.exec('PRAGMA journal_mode = WAL');
+            this.db.exec('PRAGMA synchronous = FULL');
+        }
+        catch (error) {
+            this.db.close();
+            throw error;
+        }
     }
     exec(sql, params = []) {
         this.db.prepare(sql).run(...coerceParams(params));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,9 +89,9 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.16.1"
+    "@syncular/core": "0.17.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.16.1"
+    "@syncular/server": "0.17.0"
   }
 }

package/src/bun-database.ts

@@ -36,6 +36,16 @@ export class BunClientDatabase implements ClientDatabase {
 
   constructor(path = ':memory:') {
     this.db = new Database(path);
+    // Match native Rust persistence: append durable commits to the WAL
+    // instead of creating and syncing a rollback journal per transaction.
+    // SQLite retains its in-memory journal for :memory: databases.
+    try {
+      this.db.run('PRAGMA journal_mode = WAL');
+      this.db.run('PRAGMA synchronous = FULL');
+    } catch (error) {
+      this.db.close();
+      throw error;
+    }
   }
 
   exec(sql: string, params: readonly SqlValue[] = []): void {

package/src/client.ts

@@ -1360,6 +1360,7 @@ export class SyncClient {
   #applyBatch<T>(
     fn: (batch: ChangeAccumulator) => T,
     statusSnapshotOverride?: () => SyncStatusSnapshot,
+    onRollback?: (error: unknown) => never,
   ): T {
     if (this.#batch !== undefined) return fn(this.#batch);
     const batch = new ChangeAccumulator();
@@ -1383,6 +1384,7 @@ export class SyncClient {
       });
     } catch (error) {
       this.#batch = undefined;
+      onRollback?.(error);
       throw error;
     }
     if (revision !== undefined) {
@@ -1552,6 +1554,9 @@ export class SyncClient {
       );
     }
     putCachedBlob(this.#db, blobId, bytes, this.#now());
+    // The referencing row can arrive before its body. Pin the new cache entry
+    // from current visible references before applying the size cap (§5.9.7 B1).
+    this.#reconcileBlobs(false);
     this.#enforceBlobCacheCap();
     const stored = getCachedBlob(this.#db, blobId);
     if (stored === undefined) {
@@ -2931,8 +2936,14 @@ export class SyncClient {
     }
     let openedSocket: RealtimeSocket | undefined;
     const socket = await connector({
-      onText: (text) => this.#handleRealtimeText(text),
-      onBinary: (bytes) => this.#routeRealtimeBinary(bytes),
+      onText: (text) => {
+        if (generation !== this.#realtimeGeneration || !this.#started) return;
+        this.#handleRealtimeText(text);
+      },
+      onBinary: (bytes) => {
+        if (generation !== this.#realtimeGeneration || !this.#started) return;
+        this.#routeRealtimeBinary(bytes);
+      },
       onClose: () => {
         if (openedSocket === undefined || this.#socket !== openedSocket) return;
         this.#socket = undefined;
@@ -3223,13 +3234,14 @@ export class SyncClient {
     let section: OpenSection | undefined;
     let errorFrame: ClientSyncError | undefined;
     let deltaCursor = -1;
-    let responseOutboxCount: number | undefined;
 
     // Each durable observer transaction emits its own revisioned batch.
     // Async decrypt/download work happens outside SQLite transactions.
     this.#beginDiagnosticsDeferral();
     try {
-      for (const frame of message.frames.slice(1)) {
+      for (let index = 1; index < message.frames.length; index += 1) {
+        const frame = message.frames[index];
+        if (frame === undefined) break;
         switch (frame.type) {
           case 'RESP_HEADER':
             break;
@@ -3242,22 +3254,61 @@ export class SyncClient {
             });
             break;
           case 'PUSH_RESULT': {
-            let outboxCount = responseOutboxCount ?? countOutbox(this.#db);
+            const results: PushResultFrame[] = [frame];
+            if (frame.status !== 'rejected') {
+              while (index + 1 < message.frames.length) {
+                const next = message.frames[index + 1];
+                if (next?.type !== 'PUSH_RESULT' || next.status === 'rejected')
+                  break;
+                results.push(next);
+                index += 1;
+              }
+            }
+            const conflictCount = this.#conflicts.length;
+            const rejectionCount = this.#rejections.length;
+            let outboxCount = countOutbox(this.#db);
             this.#applyBatch(
               (batch) => {
-                const drained = this.#handlePushResult(
-                  frame,
-                  commitsById,
-                  summary,
-                  batch,
-                  rejectionDetailsByCommit.get(frame.clientCommitId),
-                  frame === lastFinalPushResult,
-                );
-                if (drained) outboxCount -= 1;
+                let drained = false;
+                for (const result of results) {
+                  if (
+                    this.#handlePushResult(
+                      result,
+                      commitsById,
+                      summary,
+                      batch,
+                      rejectionDetailsByCommit.get(result.clientCommitId),
+                    )
+                  ) {
+                    outboxCount -= 1;
+                    drained = true;
+                  }
+                }
+                if (
+                  drained &&
+                  results.some((result) => result === lastFinalPushResult)
+                ) {
+                  pruneCommitOutcomes(
+                    this.#db,
+                    this.#outcomeRetentionMaxEntries,
+                  );
+                }
               },
               () => this.#statusSnapshot(outboxCount),
+              (cause) => {
+                this.#conflicts.length = conflictCount;
+                this.#rejections.length = rejectionCount;
+                const error = new ClientSyncError(
+                  'client.outcome_persistence_failed',
+                  'local commit outcome could not be persisted',
+                );
+                error.cause = cause;
+                throw error;
+              },
             );
-            responseOutboxCount = outboxCount;
+            for (const conflict of this.#conflicts.slice(conflictCount)) {
+              this.#config.onConflict?.(conflict);
+            }
             break;
           }
           case 'PUSH_RESULT_DETAILS':
@@ -3506,7 +3557,6 @@ export class SyncClient {
     summary: MutableSummary,
     batch: ChangeAccumulator,
     rejectionDetails: ReadonlyMap<number, RejectionDetails> | undefined,
-    pruneOutcomes: boolean,
   ): boolean {
     const commit = commitsById.get(frame.clientCommitId);
     if (commit === undefined) return false;
@@ -3529,9 +3579,6 @@ export class SyncClient {
         })),
       });
       deleteOutboxCommit(this.#db, frame.clientCommitId);
-      if (pruneOutcomes) {
-        pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
-      }
       batch.status();
       batch.outcomes();
       summary.applied.push(frame.clientCommitId);
@@ -3569,7 +3616,6 @@ export class SyncClient {
         outcomeResults.push({ status: 'conflict', conflict });
         batch.conflicts();
         summary.conflicts.push(conflict);
-        this.#config.onConflict?.(conflict);
       } else if (result.status === 'error') {
         const details = rejectionDetails?.get(result.opIndex);
         const rejection: RejectionRecord = {
@@ -3597,9 +3643,6 @@ export class SyncClient {
       results: outcomeResults,
       operations: commit.operations,
     });
-    if (pruneOutcomes) {
-      pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
-    }
     batch.outcomes();
     // §7.2: remove the rejected optimistic layer. Before-images restore
     // validator-rejected updates even when the server emitted no new COMMIT;

package/src/node-database.ts

@@ -40,6 +40,13 @@ export class NodeClientDatabase implements ClientDatabase {
 
   constructor(path = ':memory:') {
     this.db = new DatabaseSync(path);
+    try {
+      this.db.exec('PRAGMA journal_mode = WAL');
+      this.db.exec('PRAGMA synchronous = FULL');
+    } catch (error) {
+      this.db.close();
+      throw error;
+    }
   }
 
   exec(sql: string, params: readonly SqlValue[] = []): void {