sqlite-zod-orm 3.3.0 → 3.3.1

package/README.md

@@ -236,30 +236,55 @@ unsub();
 ┌──────────────────────────────────────────────────┐
 │  Every {interval}ms:                             │
 │                                                  │
-│  1. Check in-memory revision counter (free)      │
+│  1. Check revision (in-memory + data_version)    │
 │  2. Run: SELECT COUNT(*), MAX(id)                │
 │     FROM users WHERE role = 'admin'              │
 │                                                  │
-│  3. Combine into fingerprint: "count:max:rev"    │
+│  3. Combine into fingerprint: "count:max:rev:dv" │
 │                                                  │
 │  4. If fingerprint changed → re-run full query   │
 │     and call your callback                       │
 └──────────────────────────────────────────────────┘
 ```
 
-Since `_Database` controls all writes, it bumps an in-memory revision counter on every insert, update, and delete. The fingerprint includes this counter, so **all changes are always detected** — no triggers, no WAL, no `_changes` table.
+Two signals combine to detect **all** changes from **any** source:
 
-| Operation | Detected | How |
+| Signal | Catches | How |
 |---|---|---|
-| INSERT | ✅ | MAX(id) increases + revision bumps |
-| DELETE | ✅ | COUNT changes + revision bumps |
-| UPDATE | ✅ | revision bumps |
+| **In-memory revision** | Same-process writes | Bumped by CRUD methods |
+| **PRAGMA data_version** | Cross-process writes | SQLite bumps it on external commits |
+
+| Operation | Detected | Source |
+|---|---|---|
+| INSERT | ✅ | Same or other process |
+| DELETE | ✅ | Same or other process |
+| UPDATE | ✅ | Same or other process |
+
+No triggers. No `_changes` table. Zero disk overhead. WAL mode is enabled by default for concurrent read/write.
+
+### Multi-process example
+
+```typescript
+// Process A — watches for new/edited messages
+const unsub = db.messages.select()
+  .orderBy('id', 'asc')
+  .subscribe((messages) => {
+    console.log('Messages:', messages);
+  }, { interval: 200 });
+
+// Process B — writes to the same DB file (different process)
+// sqlite3 chat.db "INSERT INTO messages (text, author) VALUES ('hello', 'Bob')"
+// → Process A's callback fires with updated message list!
+```
+
+Run `bun examples/messages-demo.ts` for a full working demo.
 
 **Use cases:**
 - Live dashboards (poll every 1-5s)
 - Real-time chat / message lists
 - Auto-refreshing data tables
 - Watching filtered subsets of data
+- Cross-process data synchronization
 
 ---
 

package/dist/index.js

@@ -334,7 +334,7 @@ class QueryBuilder {
       try {
         const fpRows = this.executor(fingerprintSQL.sql, fingerprintSQL.params, true);
         const fpRow = fpRows[0];
-        const rev = this.revisionGetter?.() ?? 0;
+        const rev = this.revisionGetter?.() ?? "0";
         const currentFingerprint = `${fpRow?._cnt ?? 0}:${fpRow?._max ?? 0}:${rev}`;
         if (currentFingerprint !== lastFingerprint) {
           lastFingerprint = currentFingerprint;
@@ -4659,6 +4659,7 @@ class _Database {
   _revisions = {};
   constructor(dbFile, schemas, options = {}) {
     this.db = new SqliteDatabase(dbFile);
+    this.db.run("PRAGMA journal_mode = WAL");
     this.db.run("PRAGMA foreign_keys = ON");
     this.schemas = schemas;
     this.options = options;
@@ -4724,7 +4725,9 @@ class _Database {
     this._revisions[entityName] = (this._revisions[entityName] ?? 0) + 1;
   }
   _getRevision(entityName) {
-    return this._revisions[entityName] ?? 0;
+    const rev = this._revisions[entityName] ?? 0;
+    const dataVersion = this.db.query("PRAGMA data_version").get()?.data_version ?? 0;
+    return `${rev}:${dataVersion}`;
   }
   insert(entityName, data) {
     const schema = this.schemas[entityName];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlite-zod-orm",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "description": "Type-safe SQLite ORM for Bun — Zod schemas, fluent queries, auto relationships, zero SQL",
   "type": "module",
   "main": "./dist/index.js",

package/src/database.ts

@@ -36,6 +36,7 @@ class _Database<Schemas extends SchemaMap> {
 
     constructor(dbFile: string, schemas: Schemas, options: DatabaseOptions = {}) {
         this.db = new SqliteDatabase(dbFile);
+        this.db.run('PRAGMA journal_mode = WAL');  // WAL enables concurrent read + write
         this.db.run('PRAGMA foreign_keys = ON');
         this.schemas = schemas;
         this.options = options;
@@ -112,7 +113,7 @@ class _Database<Schemas extends SchemaMap> {
     }
 
     // ===========================================================================
-    // Revision Tracking (in-memory, zero overhead)
+    // Revision Tracking (in-memory + cross-process)
     // ===========================================================================
 
     /** Bump the revision counter for a table. Called on every write. */
@@ -120,9 +121,20 @@ class _Database<Schemas extends SchemaMap> {
         this._revisions[entityName] = (this._revisions[entityName] ?? 0) + 1;
     }
 
-    /** Get the current revision for a table. Used by QueryBuilder.subscribe() fingerprint. */
-    public _getRevision(entityName: string): number {
-        return this._revisions[entityName] ?? 0;
+    /**
+     * Get a composite revision string for a table.
+     *
+     * Combines two signals:
+     *  - In-memory counter: catches writes from THIS process (our CRUD methods bump it)
+     *  - PRAGMA data_version: catches writes from OTHER processes (SQLite bumps it
+     *    whenever another connection commits, but NOT for the current connection)
+     *
+     * Together they detect ALL changes regardless of source, with zero disk overhead.
+     */
+    public _getRevision(entityName: string): string {
+        const rev = this._revisions[entityName] ?? 0;
+        const dataVersion = (this.db.query('PRAGMA data_version').get() as any)?.data_version ?? 0;
+        return `${rev}:${dataVersion}`;
     }
 
     // ===========================================================================

package/src/query-builder.ts

@@ -167,7 +167,7 @@ export class QueryBuilder<T extends Record<string, any>> {
     private singleExecutor: (sql: string, params: any[], raw: boolean) => any | null;
     private joinResolver: ((fromTable: string, toTable: string) => { fk: string; pk: string } | null) | null;
     private conditionResolver: ((conditions: Record<string, any>) => Record<string, any>) | null;
-    private revisionGetter: (() => number) | null;
+    private revisionGetter: (() => string) | null;
 
     constructor(
         tableName: string,
@@ -175,7 +175,7 @@ export class QueryBuilder<T extends Record<string, any>> {
         singleExecutor: (sql: string, params: any[], raw: boolean) => any | null,
         joinResolver?: ((fromTable: string, toTable: string) => { fk: string; pk: string } | null) | null,
         conditionResolver?: ((conditions: Record<string, any>) => Record<string, any>) | null,
-        revisionGetter?: (() => number) | null,
+        revisionGetter?: (() => string) | null,
     ) {
         this.tableName = tableName;
         this.executor = executor;
@@ -459,9 +459,9 @@ export class QueryBuilder<T extends Record<string, any>> {
                 // Run lightweight fingerprint check
                 const fpRows = this.executor(fingerprintSQL.sql, fingerprintSQL.params, true);
                 const fpRow = fpRows[0] as any;
-                // Include in-memory revision in fingerprint.
-                // This ensures ALL changes (insert/update/delete) are detected.
-                const rev = this.revisionGetter?.() ?? 0;
+                // Include revision in fingerprint (combines in-memory counter + PRAGMA data_version).
+                // This detects ALL changes: same-process and cross-process.
+                const rev = this.revisionGetter?.() ?? '0';
                 const currentFingerprint = `${fpRow?._cnt ?? 0}:${fpRow?._max ?? 0}:${rev}`;
 
                 if (currentFingerprint !== lastFingerprint) {