sqlite-zod-orm 3.7.1 → 3.7.3

package/dist/index.js

@@ -361,31 +361,45 @@ class QueryBuilder {
   subscribe(callback, options = {}) {
     const { interval = this.defaultPollInterval, immediate = true } = options;
     const fingerprintSQL = this.buildFingerprintSQL();
-    let lastFingerprint = null;
-    const poll = () => {
+    let lastCount = null;
+    let lastMax = null;
+    let lastInMemoryRev = null;
+    let stopped = false;
+    const poll = async () => {
+      if (stopped)
+        return;
       try {
+        const rev = this.revisionGetter?.() ?? "0";
+        const inMemoryChanged = rev !== lastInMemoryRev;
+        lastInMemoryRev = rev;
         const fpRows = this.executor(fingerprintSQL.sql, fingerprintSQL.params, true);
         const fpRow = fpRows[0];
-        const rev = this.revisionGetter?.() ?? "0";
-        const currentFingerprint = `${fpRow?._cnt ?? 0}:${fpRow?._max ?? 0}:${rev}`;
-        if (currentFingerprint !== lastFingerprint) {
-          lastFingerprint = currentFingerprint;
+        const cnt = fpRow?._cnt ?? 0;
+        const max = fpRow?._max ?? 0;
+        const fpChanged = cnt !== lastCount || max !== lastMax;
+        lastCount = cnt;
+        lastMax = max;
+        if (inMemoryChanged || fpChanged) {
           const rows = this.all();
-          callback(rows);
+          await callback(rows);
         }
       } catch {}
+      if (!stopped)
+        setTimeout(poll, interval);
     };
     if (immediate) {
       poll();
+    } else {
+      setTimeout(poll, interval);
     }
-    const timer = setInterval(poll, interval);
     return () => {
-      clearInterval(timer);
+      stopped = true;
     };
   }
   each(callback, options = {}) {
     const { interval = this.defaultPollInterval } = options;
-    const maxRows = this.executor(`SELECT MAX(id) as _max FROM ${this.tableName}`, [], true);
+    const userWhere = this.buildWhereClause();
+    const maxRows = this.executor(`SELECT MAX(id) as _max FROM ${this.tableName} ${userWhere.sql ? `WHERE ${userWhere.sql}` : ""}`, userWhere.params, true);
     let lastMaxId = maxRows[0]?._max ?? 0;
     let lastRevision = this.revisionGetter?.() ?? "0";
     let stopped = false;
@@ -395,12 +409,15 @@ class QueryBuilder {
       const rev = this.revisionGetter?.() ?? "0";
       if (rev !== lastRevision) {
         lastRevision = rev;
-        const newRows = this.executor(`SELECT * FROM ${this.tableName} WHERE id > ? ORDER BY id ASC`, [lastMaxId], true);
-        for (const rawRow of newRows) {
+        const params = [...userWhere.params, lastMaxId];
+        const whereClause = userWhere.sql ? `WHERE ${userWhere.sql} AND id > ? ORDER BY id ASC` : `WHERE id > ? ORDER BY id ASC`;
+        const sql = `SELECT * FROM ${this.tableName} ${whereClause}`;
+        const newRows = this.executor(sql, params, false);
+        for (const row of newRows) {
           if (stopped)
             return;
-          await callback(rawRow);
-          lastMaxId = rawRow.id;
+          await callback(row);
+          lastMaxId = row.id;
         }
       }
       if (!stopped)
@@ -411,14 +428,13 @@ class QueryBuilder {
       stopped = true;
     };
   }
-  buildFingerprintSQL() {
+  buildWhereClause() {
     const params = [];
-    let sql = `SELECT COUNT(*) as _cnt, MAX(id) as _max FROM ${this.tableName}`;
     if (this.iqo.whereAST) {
       const compiled = compileAST(this.iqo.whereAST);
-      sql += ` WHERE ${compiled.sql}`;
-      params.push(...compiled.params);
-    } else if (this.iqo.wheres.length > 0) {
+      return { sql: compiled.sql, params: compiled.params };
+    }
+    if (this.iqo.wheres.length > 0) {
       const whereParts = [];
       for (const w of this.iqo.wheres) {
         if (w.operator === "IN") {
@@ -435,9 +451,14 @@ class QueryBuilder {
           params.push(transformValueForStorage(w.value));
         }
       }
-      sql += ` WHERE ${whereParts.join(" AND ")}`;
+      return { sql: whereParts.join(" AND "), params };
     }
-    return { sql, params };
+    return { sql: "", params: [] };
+  }
+  buildFingerprintSQL() {
+    const where = this.buildWhereClause();
+    const sql = `SELECT COUNT(*) as _cnt, MAX(id) as _max FROM ${this.tableName}${where.sql ? ` WHERE ${where.sql}` : ""}`;
+    return { sql, params: where.params };
   }
   then(onfulfilled, onrejected) {
     try {

package/package.json

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

package/src/query-builder.ts

@@ -479,6 +479,9 @@ export class QueryBuilder<T extends Record<string, any>> {
      * in-memory revision counter to detect ALL changes (inserts, updates, deletes)
      * with zero disk overhead.
      *
+     * Uses a self-scheduling async loop: each callback (sync or async) completes
+     * before the next poll starts. No overlapping polls.
+     *
      * ```ts
      * const unsub = db.messages.select()
      *   .where({ groupId: 1 })
@@ -492,52 +495,68 @@ export class QueryBuilder<T extends Record<string, any>> {
      * unsub();
      * ```
      *
-     * @param callback  Called with the full result set whenever the data changes.
+     * @param callback  Called with the full result set whenever the data changes. Async callbacks are awaited.
      * @param options   `interval` in ms (default 500). Set `immediate` to false to skip the first call.
-     * @returns An unsubscribe function that clears the polling interval.
+     * @returns An unsubscribe function.
      */
     subscribe(
-        callback: (rows: T[]) => void,
+        callback: (rows: T[]) => void | Promise<void>,
         options: { interval?: number; immediate?: boolean } = {},
     ): () => void {
         const { interval = this.defaultPollInterval, immediate = true } = options;
 
         // Build the fingerprint SQL (COUNT + MAX(id)) using the same WHERE
         const fingerprintSQL = this.buildFingerprintSQL();
-        let lastFingerprint: string | null = null;
+        let lastCount: number | null = null;
+        let lastMax: number | null = null;
+        let lastInMemoryRev: string | null = null;
+        let stopped = false;
 
-        const poll = () => {
+        const poll = async () => {
+            if (stopped) return;
             try {
-                // Run lightweight fingerprint check
-                const fpRows = this.executor(fingerprintSQL.sql, fingerprintSQL.params, true);
-                const fpRow = fpRows[0] as any;
-                // Include revision in fingerprint (combines in-memory counter + PRAGMA data_version).
-                // This detects ALL changes: same-process and cross-process.
+                // Two-signal change detection:
+                //   1. In-memory revision (table-specific) → catches same-process writes
+                //   2. COUNT+MAX fingerprint (table-specific) → catches cross-process inserts/deletes
+                //
+                // Note: cross-process UPDATEs that don't change count/max are only caught
+                // by PRAGMA data_version, which is database-wide. We accept this tradeoff
+                // to avoid re-querying on writes to OTHER tables.
                 const rev = this.revisionGetter?.() ?? '0';
-                const currentFingerprint = `${fpRow?._cnt ?? 0}:${fpRow?._max ?? 0}:${rev}`;
 
-                if (currentFingerprint !== lastFingerprint) {
-                    lastFingerprint = currentFingerprint;
-                    // Fingerprint changed → re-execute the full query
+                // Fast path: in-memory revision changed → our CRUD wrote to this table
+                const inMemoryChanged = rev !== lastInMemoryRev;
+                lastInMemoryRev = rev;
+
+                // Check table-specific fingerprint (COUNT + MAX(id))
+                const fpRows = this.executor(fingerprintSQL.sql, fingerprintSQL.params, true);
+                const fpRow = fpRows[0] as any;
+                const cnt = fpRow?._cnt ?? 0;
+                const max = fpRow?._max ?? 0;
+                const fpChanged = cnt !== lastCount || max !== lastMax;
+                lastCount = cnt;
+                lastMax = max;
+
+                // Fire callback only if THIS table actually changed
+                if (inMemoryChanged || fpChanged) {
                     const rows = this.all();
-                    callback(rows);
+                    await callback(rows);
                 }
             } catch {
                 // Silently skip on error (table might be in transition)
             }
+            // Self-scheduling: next poll only after this one completes
+            if (!stopped) setTimeout(poll, interval);
         };
 
         // Immediate first execution
         if (immediate) {
             poll();
+        } else {
+            setTimeout(poll, interval);
         }
 
-        const timer = setInterval(poll, interval);
-
-        // Return unsubscribe function
-        return () => {
-            clearInterval(timer);
-        };
+        return () => { stopped = true; };
     }
 
     /**
@@ -548,10 +567,19 @@ export class QueryBuilder<T extends Record<string, any>> {
      * `WHERE id > watermark` is rebuilt each poll with the latest value,
      * so it's always O(new_rows) — not O(table_size).
      *
+     * Composes with the query builder chain: any `.where()` conditions
+     * are combined with the watermark clause.
+     *
      * ```ts
+     * // All new messages
      * const unsub = db.messages.select().each((msg) => {
      *     console.log('New:', msg.text);
      * });
+     *
+     * // Only new messages by Alice
+     * const unsub2 = db.messages.select()
+     *     .where({ author: 'Alice' })
+     *     .each((msg) => console.log(msg.text));
      * ```
      *
      * @param callback  Called once per new row. Async callbacks are awaited.
@@ -564,9 +592,14 @@ export class QueryBuilder<T extends Record<string, any>> {
     ): () => void {
         const { interval = this.defaultPollInterval } = options;
 
-        // Initialize watermark to current max id
+        // Compile the user's WHERE clause (if any) so we can combine with watermark
+        const userWhere = this.buildWhereClause();
+
+        // Initialize watermark to current max id, respecting user's WHERE clause
         const maxRows = this.executor(
-            `SELECT MAX(id) as _max FROM ${this.tableName}`, [], true
+            `SELECT MAX(id) as _max FROM ${this.tableName} ${userWhere.sql ? `WHERE ${userWhere.sql}` : ''}`,
+            userWhere.params,
+            true
         );
         let lastMaxId: number = (maxRows[0] as any)?._max ?? 0;
         let lastRevision = this.revisionGetter?.() ?? '0';
@@ -579,16 +612,20 @@ export class QueryBuilder<T extends Record<string, any>> {
             if (rev !== lastRevision) {
                 lastRevision = rev;
 
-                // Fetch only new rows since watermark — O(new_rows)
-                const newRows = this.executor(
-                    `SELECT * FROM ${this.tableName} WHERE id > ? ORDER BY id ASC`,
-                    [lastMaxId], true
-                );
+                // Combine user WHERE with watermark: WHERE (user_conditions) AND id > ?
+                const params = [...userWhere.params, lastMaxId];
+                const whereClause = userWhere.sql
+                    ? `WHERE ${userWhere.sql} AND id > ? ORDER BY id ASC`
+                    : `WHERE id > ? ORDER BY id ASC`;
+                const sql = `SELECT * FROM ${this.tableName} ${whereClause}`;
 
-                for (const rawRow of newRows) {
+                // raw=false → rows go through transform + get .update()/.delete() methods
+                const newRows = this.executor(sql, params, false);
+
+                for (const row of newRows) {
                     if (stopped) return;
-                    await callback(rawRow as unknown as T);
-                    lastMaxId = (rawRow as any).id;
+                    await callback(row as T);
+                    lastMaxId = (row as any).id;
                 }
             }
 
@@ -599,16 +636,16 @@ export class QueryBuilder<T extends Record<string, any>> {
         return () => { stopped = true; };
     }
 
-    /** Build a lightweight fingerprint query (COUNT + MAX(id)) that shares the same WHERE clause. */
-    private buildFingerprintSQL(): { sql: string; params: any[] } {
+    /** Compile the IQO's WHERE conditions into a SQL fragment + params (without the WHERE keyword). */
+    private buildWhereClause(): { sql: string; params: any[] } {
         const params: any[] = [];
-        let sql = `SELECT COUNT(*) as _cnt, MAX(id) as _max FROM ${this.tableName}`;
 
         if (this.iqo.whereAST) {
             const compiled = compileAST(this.iqo.whereAST);
-            sql += ` WHERE ${compiled.sql}`;
-            params.push(...compiled.params);
-        } else if (this.iqo.wheres.length > 0) {
+            return { sql: compiled.sql, params: compiled.params };
+        }
+
+        if (this.iqo.wheres.length > 0) {
             const whereParts: string[] = [];
             for (const w of this.iqo.wheres) {
                 if (w.operator === 'IN') {
@@ -625,10 +662,17 @@ export class QueryBuilder<T extends Record<string, any>> {
                     params.push(transformValueForStorage(w.value));
                 }
             }
-            sql += ` WHERE ${whereParts.join(' AND ')}`;
+            return { sql: whereParts.join(' AND '), params };
         }
 
-        return { sql, params };
+        return { sql: '', params: [] };
+    }
+
+    /** Build a lightweight fingerprint query (COUNT + MAX(id)) that shares the same WHERE clause. */
+    private buildFingerprintSQL(): { sql: string; params: any[] } {
+        const where = this.buildWhereClause();
+        const sql = `SELECT COUNT(*) as _cnt, MAX(id) as _max FROM ${this.tableName}${where.sql ? ` WHERE ${where.sql}` : ''}`;
+        return { sql, params: where.params };
     }
 
     // ---------- Thenable (async/await support) ----------