sqlite-zod-orm 3.3.0 → 3.4.0

package/README.md

@@ -207,9 +207,37 @@ const db = new Database(':memory:', schemas, {
 
 ---
 
-## Reactivity — `select().subscribe()`
+## Reactivity
 
-One API to watch any query for changes. Detects **all** mutations (inserts, updates, deletes) with zero disk overhead.
+Two complementary APIs for watching data changes:
+
+| API | Receives | Fires on | Use case |
+|---|---|---|---|
+| **`db.table.on(cb)`** | One row at a time, in order | New inserts only | Message streams, event queues |
+| **`select().subscribe(cb)`** | Full result snapshot | Any change (insert/update/delete) | Live dashboards, filtered views |
+
+---
+
+### Row Stream — `db.table.on(callback)`
+
+Streams new rows one at a time, in insertion order. Only emits rows created **after** subscription starts.
+
+```typescript
+const unsub = db.messages.on((msg) => {
+  console.log(`${msg.author}: ${msg.text}`);
+}, { interval: 200 });
+
+// Later: stop listening
+unsub();
+```
+
+If 5 messages arrive between polls, the callback fires 5 times — once per row, in order. Uses a watermark (`id > lastSeen`) internally.
+
+---
+
+### Snapshot — `select().subscribe(callback)`
+
+Returns the **full query result** whenever data changes. Detects all mutations (inserts, updates, deletes).
 
 ```typescript
 const unsub = db.users.select()
@@ -236,38 +264,64 @@ 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
 
 ---
 
 ## Examples & Tests
 
 ```bash
-bun examples/example.ts    # comprehensive demo
-bun test                    # 91 tests
+bun examples/messages-demo.ts  # .on() vs .subscribe() demo
+bun examples/example.ts        # comprehensive demo
+bun test                        # 93 tests
 ```
 
 ---
@@ -294,7 +348,8 @@ bun test                    # 91 tests
 | `entity.update(data)` | Update entity in-place |
 | `entity.delete()` | Delete entity |
 | **Reactivity** | |
-| `select().subscribe(cb, opts?)` | Watch any query for changes (all mutations) |
+| `db.table.on(cb, opts?)` | Stream new rows one at a time, in order |
+| `select().subscribe(cb, opts?)` | Watch query result snapshot (all mutations) |
 
 ## License
 

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;
@@ -4679,6 +4680,7 @@ class _Database {
         upsert: (conditions, data) => this.upsert(entityName, data, conditions),
         delete: (id) => this.delete(entityName, id),
         select: (...cols) => this._createQueryBuilder(entityName, cols),
+        on: (callback, options2) => this._createOnStream(entityName, callback, options2),
         _tableName: entityName
       };
       this[key] = accessor;
@@ -4724,7 +4726,28 @@ 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}`;
+  }
+  _createOnStream(entityName, callback, options) {
+    const { interval = 500 } = options ?? {};
+    const maxRow = this.db.query(`SELECT MAX(id) as _max FROM "${entityName}"`).get();
+    let lastMaxId = maxRow?._max ?? 0;
+    let lastRevision = this._getRevision(entityName);
+    const timer = setInterval(() => {
+      const currentRevision = this._getRevision(entityName);
+      if (currentRevision === lastRevision)
+        return;
+      lastRevision = currentRevision;
+      const newRows = this.db.query(`SELECT * FROM "${entityName}" WHERE id > ? ORDER BY id ASC`).all(lastMaxId);
+      for (const rawRow of newRows) {
+        const entity = this._attachMethods(entityName, transformFromStorage(rawRow, this.schemas[entityName]));
+        callback(entity);
+        lastMaxId = rawRow.id;
+      }
+    }, interval);
+    return () => clearInterval(timer);
   }
   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.4.0",
   "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;
@@ -56,6 +57,8 @@ class _Database<Schemas extends SchemaMap> {
                 upsert: (conditions, data) => this.upsert(entityName, data, conditions),
                 delete: (id) => this.delete(entityName, id),
                 select: (...cols: string[]) => this._createQueryBuilder(entityName, cols),
+                on: (callback: (row: any) => void, options?: { interval?: number }) =>
+                    this._createOnStream(entityName, callback, options),
                 _tableName: entityName,
             };
             (this as any)[key] = accessor;
@@ -112,7 +115,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 +123,67 @@ 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}`;
+    }
+
+    // ===========================================================================
+    // Row Stream — .on(callback)
+    // ===========================================================================
+
+    /**
+     * Stream new rows one at a time, in insertion order.
+     *
+     * Uses a watermark (last seen id) to query only `WHERE id > ?`.
+     * Checks revision + data_version first to avoid unnecessary queries.
+     */
+    public _createOnStream(
+        entityName: string,
+        callback: (row: any) => void,
+        options?: { interval?: number },
+    ): () => void {
+        const { interval = 500 } = options ?? {};
+
+        // Initialize watermark to current max id (only emit NEW rows)
+        const maxRow = this.db.query(`SELECT MAX(id) as _max FROM "${entityName}"`).get() as any;
+        let lastMaxId: number = maxRow?._max ?? 0;
+        let lastRevision: string = this._getRevision(entityName);
+
+        const timer = setInterval(() => {
+            // Fast check: did anything change?
+            const currentRevision = this._getRevision(entityName);
+            if (currentRevision === lastRevision) return;
+            lastRevision = currentRevision;
+
+            // Fetch new rows since watermark
+            const newRows = this.db.query(
+                `SELECT * FROM "${entityName}" WHERE id > ? ORDER BY id ASC`
+            ).all(lastMaxId) as any[];
+
+            for (const rawRow of newRows) {
+                // Hydrate with entity methods and schema transforms
+                const entity = this._attachMethods(
+                    entityName,
+                    transformFromStorage(rawRow, this.schemas[entityName]!)
+                );
+                callback(entity);
+                lastMaxId = rawRow.id;
+            }
+        }, interval);
+
+        return () => clearInterval(timer);
     }
 
     // ===========================================================================

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) {

package/src/types.ts

@@ -143,6 +143,12 @@ export type NavEntityAccessor<
     upsert: (conditions?: Partial<z.infer<S[Table & keyof S]>>, data?: Partial<z.infer<S[Table & keyof S]>>) => NavEntity<S, R, Table>;
     delete: (id: number) => void;
     select: (...cols: (keyof z.infer<S[Table & keyof S]> & string)[]) => QueryBuilder<NavEntity<S, R, Table>>;
+    /**
+     * Stream new rows one at a time, in insertion order.
+     * Only emits rows inserted AFTER subscription starts.
+     * @returns Unsubscribe function.
+     */
+    on: (callback: (row: NavEntity<S, R, Table>) => void, options?: { interval?: number }) => () => void;
     _tableName: string;
     readonly _schema?: S[Table & keyof S];
 };
@@ -168,6 +174,12 @@ export type EntityAccessor<S extends z.ZodType<any>> = {
     upsert: (conditions?: Partial<InferSchema<S>>, data?: Partial<InferSchema<S>>) => AugmentedEntity<S>;
     delete: (id: number) => void;
     select: (...cols: (keyof InferSchema<S> & string)[]) => QueryBuilder<AugmentedEntity<S>>;
+    /**
+     * Stream new rows one at a time, in insertion order.
+     * Only emits rows inserted AFTER subscription starts.
+     * @returns Unsubscribe function.
+     */
+    on: (callback: (row: AugmentedEntity<S>) => void, options?: { interval?: number }) => () => void;
     _tableName: string;
     readonly _schema?: S;
 };