sqlite-zod-orm 3.3.1 → 3.4.1

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

@@ -112,6 +112,8 @@ function compileIQO(tableName, iqo) {
     sql += ` WHERE ${compiled.sql}`;
     params.push(...compiled.params);
   } else if (iqo.wheres.length > 0) {
+    const hasJoins = iqo.joins.length > 0;
+    const qualify = (field) => hasJoins && !field.includes(".") ? `${tableName}.${field}` : field;
     const whereParts = [];
     for (const w of iqo.wheres) {
       if (w.operator === "IN") {
@@ -120,11 +122,11 @@ function compileIQO(tableName, iqo) {
           whereParts.push("1 = 0");
         } else {
           const placeholders = arr.map(() => "?").join(", ");
-          whereParts.push(`${w.field} IN (${placeholders})`);
+          whereParts.push(`${qualify(w.field)} IN (${placeholders})`);
           params.push(...arr.map(transformValueForStorage));
         }
       } else {
-        whereParts.push(`${w.field} ${w.operator} ?`);
+        whereParts.push(`${qualify(w.field)} ${w.operator} ?`);
         params.push(transformValueForStorage(w.value));
       }
     }
@@ -4680,6 +4682,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 +4732,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);
@@ -4935,7 +4957,29 @@ class _Database {
       return null;
     };
     const revisionGetter = () => this._getRevision(entityName);
-    const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, null, revisionGetter);
+    const conditionResolver = (conditions) => {
+      const resolved = {};
+      for (const [key, value] of Object.entries(conditions)) {
+        if (value && typeof value === "object" && typeof value.id === "number" && typeof value.delete === "function") {
+          const fkCol = key + "_id";
+          const rel = this.relationships.find((r) => r.type === "belongs-to" && r.from === entityName && r.foreignKey === fkCol);
+          if (rel) {
+            resolved[fkCol] = value.id;
+          } else {
+            const relByNav = this.relationships.find((r) => r.type === "belongs-to" && r.from === entityName && r.to === key + "s") || this.relationships.find((r) => r.type === "belongs-to" && r.from === entityName && r.to === key);
+            if (relByNav) {
+              resolved[relByNav.foreignKey] = value.id;
+            } else {
+              resolved[key] = value;
+            }
+          }
+        } else {
+          resolved[key] = value;
+        }
+      }
+      return resolved;
+    };
+    const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter);
     if (initialCols.length > 0)
       builder.select(...initialCols);
     return builder;

package/package.json

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

@@ -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
     // ===========================================================================
@@ -404,7 +453,40 @@ class _Database<Schemas extends SchemaMap> {
         // Pass revision getter — allows .subscribe() to detect ALL changes
         const revisionGetter = () => this._getRevision(entityName);
 
-        const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, null, revisionGetter);
+        // Condition resolver: { author: aliceEntity } → { author_id: 1 }
+        const conditionResolver = (conditions: Record<string, any>): Record<string, any> => {
+            const resolved: Record<string, any> = {};
+            for (const [key, value] of Object.entries(conditions)) {
+                // Detect entity references: objects with `id` and `delete` (augmented entities)
+                if (value && typeof value === 'object' && typeof value.id === 'number' && typeof value.delete === 'function') {
+                    // Find a belongs-to relationship: entityName has a FK named `key_id` pointing to another table
+                    const fkCol = key + '_id';
+                    const rel = this.relationships.find(
+                        r => r.type === 'belongs-to' && r.from === entityName && r.foreignKey === fkCol
+                    );
+                    if (rel) {
+                        resolved[fkCol] = value.id;
+                    } else {
+                        // Fallback: try any relationship that matches the key as the nav name
+                        const relByNav = this.relationships.find(
+                            r => r.type === 'belongs-to' && r.from === entityName && r.to === key + 's'
+                        ) || this.relationships.find(
+                            r => r.type === 'belongs-to' && r.from === entityName && r.to === key
+                        );
+                        if (relByNav) {
+                            resolved[relByNav.foreignKey] = value.id;
+                        } else {
+                            resolved[key] = value; // pass through
+                        }
+                    }
+                } else {
+                    resolved[key] = value;
+                }
+            }
+            return resolved;
+        };
+
+        const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter);
         if (initialCols.length > 0) builder.select(...initialCols);
         return builder;
     }

package/src/query-builder.ts

@@ -86,6 +86,11 @@ export function compileIQO(tableName: string, iqo: IQO): { sql: string; params:
         sql += ` WHERE ${compiled.sql}`;
         params.push(...compiled.params);
     } else if (iqo.wheres.length > 0) {
+        const hasJoins = iqo.joins.length > 0;
+        // When joins exist, qualify bare column names with the main table
+        const qualify = (field: string) =>
+            hasJoins && !field.includes('.') ? `${tableName}.${field}` : field;
+
         const whereParts: string[] = [];
         for (const w of iqo.wheres) {
             if (w.operator === 'IN') {
@@ -94,11 +99,11 @@ export function compileIQO(tableName: string, iqo: IQO): { sql: string; params:
                     whereParts.push('1 = 0');
                 } else {
                     const placeholders = arr.map(() => '?').join(', ');
-                    whereParts.push(`${w.field} IN (${placeholders})`);
+                    whereParts.push(`${qualify(w.field)} IN (${placeholders})`);
                     params.push(...arr.map(transformValueForStorage));
                 }
             } else {
-                whereParts.push(`${w.field} ${w.operator} ?`);
+                whereParts.push(`${qualify(w.field)} ${w.operator} ?`);
                 params.push(transformValueForStorage(w.value));
             }
         }

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