sqlite-zod-orm 3.3.1 → 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()
@@ -291,8 +319,9 @@ Run `bun examples/messages-demo.ts` for a full working demo.
 ## 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
 ```
 
 ---
@@ -319,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

@@ -4680,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;
@@ -4729,6 +4730,25 @@ class _Database {
     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];
     const validatedData = asZodObject(schema).passthrough().parse(data);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlite-zod-orm",
-  "version": "3.3.1",
+  "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

@@ -57,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;
@@ -137,6 +139,53 @@ class _Database<Schemas extends SchemaMap> {
         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);
+    }
+
     // ===========================================================================
     // CRUD
     // ===========================================================================

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;
 };