sqlite-zod-orm 3.2.0 → 3.3.0

package/README.md

@@ -207,29 +207,60 @@ const db = new Database(':memory:', schemas, {
 
 ---
 
-## Change Tracking & Events
+## Reactivity — `select().subscribe()`
 
-```typescript
-const db = new Database(':memory:', schemas, { changeTracking: true });
-db.getChangesSince(0);
-
-db.users.subscribe('insert', (user) => console.log('New:', user.name));
-```
-
----
-
-## Smart Polling
+One API to watch any query for changes. Detects **all** mutations (inserts, updates, deletes) with zero disk overhead.
 
 ```typescript
 const unsub = db.users.select()
   .where({ role: 'admin' })
+  .orderBy('name', 'asc')
   .subscribe((admins) => {
-    console.log('Admin list changed:', admins);
+    console.log('Admin list:', admins.map(a => a.name));
   }, { interval: 1000 });
 
+// Stop watching
 unsub();
 ```
 
+**Options:**
+
+| Option | Default | Description |
+|---|---|---|
+| `interval` | `500` | Polling interval in milliseconds |
+| `immediate` | `true` | Fire callback immediately with current data |
+
+### How it works
+
+```
+┌──────────────────────────────────────────────────┐
+│  Every {interval}ms:                             │
+│                                                  │
+│  1. Check in-memory revision counter (free)      │
+│  2. Run: SELECT COUNT(*), MAX(id)                │
+│     FROM users WHERE role = 'admin'              │
+│                                                  │
+│  3. Combine into fingerprint: "count:max:rev"    │
+│                                                  │
+│  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.
+
+| Operation | Detected | How |
+|---|---|---|
+| INSERT | ✅ | MAX(id) increases + revision bumps |
+| DELETE | ✅ | COUNT changes + revision bumps |
+| UPDATE | ✅ | revision bumps |
+
+**Use cases:**
+- Live dashboards (poll every 1-5s)
+- Real-time chat / message lists
+- Auto-refreshing data tables
+- Watching filtered subsets of data
+
 ---
 
 ## Examples & Tests
@@ -262,10 +293,8 @@ bun test                    # 91 tests
 | `entity.navMethod()` | Lazy navigation (FK name minus `_id`) |
 | `entity.update(data)` | Update entity in-place |
 | `entity.delete()` | Delete entity |
-| **Events** | |
-| `db.table.subscribe(event, callback)` | Listen for insert/update/delete |
-| `db.table.select().subscribe(cb, opts)` | Smart polling |
-| `db.getChangesSince(version, table?)` | Change tracking |
+| **Reactivity** | |
+| `select().subscribe(cb, opts?)` | Watch any query for changes (all mutations) |
 
 ## License
 

package/dist/index.js

@@ -12,7 +12,6 @@ var __export = (target, all) => {
 
 // src/database.ts
 import { Database as SqliteDatabase } from "bun:sqlite";
-import { EventEmitter } from "events";
 
 // src/ast.ts
 var wrapNode = (val) => val !== null && typeof val === "object" && ("type" in val) ? val : { type: "literal", value: val };
@@ -174,12 +173,14 @@ class QueryBuilder {
   singleExecutor;
   joinResolver;
   conditionResolver;
-  constructor(tableName, executor, singleExecutor, joinResolver, conditionResolver) {
+  revisionGetter;
+  constructor(tableName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter) {
     this.tableName = tableName;
     this.executor = executor;
     this.singleExecutor = singleExecutor;
     this.joinResolver = joinResolver ?? null;
     this.conditionResolver = conditionResolver ?? null;
+    this.revisionGetter = revisionGetter ?? null;
     this.iqo = {
       selects: [],
       wheres: [],
@@ -333,7 +334,8 @@ class QueryBuilder {
       try {
         const fpRows = this.executor(fingerprintSQL.sql, fingerprintSQL.params, true);
         const fpRow = fpRows[0];
-        const currentFingerprint = `${fpRow?._cnt ?? 0}:${fpRow?._max ?? 0}`;
+        const rev = this.revisionGetter?.() ?? 0;
+        const currentFingerprint = `${fpRow?._cnt ?? 0}:${fpRow?._max ?? 0}:${rev}`;
         if (currentFingerprint !== lastFingerprint) {
           lastFingerprint = currentFingerprint;
           const rows = this.all();
@@ -4649,26 +4651,22 @@ function transformFromStorage(row, schema) {
 }
 
 // src/database.ts
-class _Database extends EventEmitter {
+class _Database {
   db;
   schemas;
   relationships;
-  subscriptions;
   options;
+  _revisions = {};
   constructor(dbFile, schemas, options = {}) {
-    super();
     this.db = new SqliteDatabase(dbFile);
     this.db.run("PRAGMA foreign_keys = ON");
     this.schemas = schemas;
     this.options = options;
-    this.subscriptions = { insert: {}, update: {}, delete: {} };
     this.relationships = options.relations ? parseRelationsConfig(options.relations, schemas) : [];
     this.initializeTables();
     this.runMigrations();
     if (options.indexes)
       this.createIndexes(options.indexes);
-    if (options.changeTracking)
-      this.setupChangeTracking();
     for (const entityName of Object.keys(schemas)) {
       const key = entityName;
       const accessor = {
@@ -4680,8 +4678,6 @@ class _Database extends EventEmitter {
         },
         upsert: (conditions, data) => this.upsert(entityName, data, conditions),
         delete: (id) => this.delete(entityName, id),
-        subscribe: (event, callback) => this.subscribe(event, entityName, callback),
-        unsubscribe: (event, callback) => this.unsubscribe(event, entityName, callback),
         select: (...cols) => this._createQueryBuilder(entityName, cols),
         _tableName: entityName
       };
@@ -4703,66 +4699,32 @@ class _Database extends EventEmitter {
     }
   }
   runMigrations() {
-    this.db.run(`CREATE TABLE IF NOT EXISTS _schema_meta (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      table_name TEXT NOT NULL,
-      column_name TEXT NOT NULL,
-      added_at TEXT DEFAULT (datetime('now')),
-      UNIQUE(table_name, column_name)
-    )`);
     for (const [entityName, schema] of Object.entries(this.schemas)) {
-      const existingCols = new Set(this.db.query(`PRAGMA table_info(${entityName})`).all().map((c) => c.name));
+      const existingColumns = this.db.query(`PRAGMA table_info(${entityName})`).all();
+      const existingNames = new Set(existingColumns.map((c) => c.name));
       const storableFields = getStorableFields(schema);
       for (const field of storableFields) {
-        if (!existingCols.has(field.name)) {
-          this.db.run(`ALTER TABLE ${entityName} ADD COLUMN ${field.name} ${zodTypeToSqlType(field.type)}`);
-          this.db.query(`INSERT OR IGNORE INTO _schema_meta (table_name, column_name) VALUES (?, ?)`).run(entityName, field.name);
+        if (!existingNames.has(field.name)) {
+          const sqlType = zodTypeToSqlType(field.type);
+          this.db.run(`ALTER TABLE ${entityName} ADD COLUMN ${field.name} ${sqlType}`);
         }
       }
     }
   }
-  createIndexes(indexDefs) {
-    for (const [tableName, indexes] of Object.entries(indexDefs)) {
-      if (!this.schemas[tableName])
-        throw new Error(`Cannot create index on unknown table '${tableName}'`);
-      const indexList = Array.isArray(indexes) ? indexes : [indexes];
-      for (const indexDef of indexList) {
-        const columns = Array.isArray(indexDef) ? indexDef : [indexDef];
-        const indexName = `idx_${tableName}_${columns.join("_")}`;
-        this.db.run(`CREATE INDEX IF NOT EXISTS ${indexName} ON ${tableName} (${columns.join(", ")})`);
+  createIndexes(indexes) {
+    for (const [tableName, indexDefs] of Object.entries(indexes)) {
+      for (const def of indexDefs) {
+        const cols = Array.isArray(def) ? def : [def];
+        const idxName = `idx_${tableName}_${cols.join("_")}`;
+        this.db.run(`CREATE INDEX IF NOT EXISTS ${idxName} ON ${tableName} (${cols.join(", ")})`);
       }
     }
   }
-  setupChangeTracking() {
-    this.db.run(`CREATE TABLE IF NOT EXISTS _changes (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      table_name TEXT NOT NULL,
-      row_id INTEGER NOT NULL,
-      action TEXT NOT NULL CHECK(action IN ('INSERT', 'UPDATE', 'DELETE')),
-      changed_at TEXT DEFAULT (datetime('now'))
-    )`);
-    this.db.run(`CREATE INDEX IF NOT EXISTS idx_changes_table ON _changes (table_name, id)`);
-    for (const entityName of Object.keys(this.schemas)) {
-      for (const action of ["insert", "update", "delete"]) {
-        const ref = action === "delete" ? "OLD" : "NEW";
-        this.db.run(`CREATE TRIGGER IF NOT EXISTS _trg_${entityName}_${action}
-          AFTER ${action.toUpperCase()} ON ${entityName}
-          BEGIN
-            INSERT INTO _changes (table_name, row_id, action) VALUES ('${entityName}', ${ref}.id, '${action.toUpperCase()}');
-          END`);
-      }
-    }
+  _bumpRevision(entityName) {
+    this._revisions[entityName] = (this._revisions[entityName] ?? 0) + 1;
   }
-  getChangeSeq(tableName) {
-    if (!this.options.changeTracking)
-      return -1;
-    const sql = tableName ? `SELECT MAX(id) as seq FROM _changes WHERE table_name = ?` : `SELECT MAX(id) as seq FROM _changes`;
-    const row = this.db.query(sql).get(...tableName ? [tableName] : []);
-    return row?.seq ?? 0;
-  }
-  getChangesSince(sinceSeq, tableName) {
-    const sql = tableName ? `SELECT * FROM _changes WHERE id > ? AND table_name = ? ORDER BY id ASC` : `SELECT * FROM _changes WHERE id > ? ORDER BY id ASC`;
-    return this.db.query(sql).all(...tableName ? [sinceSeq, tableName] : [sinceSeq]);
+  _getRevision(entityName) {
+    return this._revisions[entityName] ?? 0;
   }
   insert(entityName, data) {
     const schema = this.schemas[entityName];
@@ -4774,8 +4736,7 @@ class _Database extends EventEmitter {
     const newEntity = this._getById(entityName, result.lastInsertRowid);
     if (!newEntity)
       throw new Error("Failed to retrieve entity after insertion");
-    this.emit("insert", entityName, newEntity);
-    this.subscriptions.insert[entityName]?.forEach((cb) => cb(newEntity));
+    this._bumpRevision(entityName);
     return newEntity;
   }
   _getById(entityName, id) {
@@ -4804,11 +4765,8 @@ class _Database extends EventEmitter {
       return this._getById(entityName, id);
     const setClause = Object.keys(transformed).map((key) => `${key} = ?`).join(", ");
     this.db.query(`UPDATE ${entityName} SET ${setClause} WHERE id = ?`).run(...Object.values(transformed), id);
+    this._bumpRevision(entityName);
     const updatedEntity = this._getById(entityName, id);
-    if (updatedEntity) {
-      this.emit("update", entityName, updatedEntity);
-      this.subscriptions.update[entityName]?.forEach((cb) => cb(updatedEntity));
-    }
     return updatedEntity;
   }
   _updateWhere(entityName, data, conditions) {
@@ -4824,12 +4782,8 @@ class _Database extends EventEmitter {
     const setClause = setCols.map((key) => `${key} = ?`).join(", ");
     const result = this.db.query(`UPDATE ${entityName} SET ${setClause} ${clause}`).run(...setCols.map((key) => transformed[key]), ...whereValues);
     const affected = result.changes ?? 0;
-    if (affected > 0 && (this.subscriptions.update[entityName]?.length || this.options.changeTracking)) {
-      for (const entity of this._findMany(entityName, conditions)) {
-        this.emit("update", entityName, entity);
-        this.subscriptions.update[entityName]?.forEach((cb) => cb(entity));
-      }
-    }
+    if (affected > 0)
+      this._bumpRevision(entityName);
     return affected;
   }
   _createUpdateBuilder(entityName, data) {
@@ -4859,8 +4813,7 @@ class _Database extends EventEmitter {
     const entity = this._getById(entityName, id);
     if (entity) {
       this.db.query(`DELETE FROM ${entityName} WHERE id = ?`).run(id);
-      this.emit("delete", entityName, entity);
-      this.subscriptions.delete[entityName]?.forEach((cb) => cb(entity));
+      this._bumpRevision(entityName);
     }
   }
   _attachMethods(entityName, entity) {
@@ -4957,15 +4910,6 @@ class _Database extends EventEmitter {
       throw new Error(`Transaction failed: ${error.message}`);
     }
   }
-  subscribe(event, entityName, callback) {
-    this.subscriptions[event][entityName] = this.subscriptions[event][entityName] || [];
-    this.subscriptions[event][entityName].push(callback);
-  }
-  unsubscribe(event, entityName, callback) {
-    if (this.subscriptions[event][entityName]) {
-      this.subscriptions[event][entityName] = this.subscriptions[event][entityName].filter((cb) => cb !== callback);
-    }
-  }
   _createQueryBuilder(entityName, initialCols) {
     const schema = this.schemas[entityName];
     const executor = (sql, params, raw) => {
@@ -4987,7 +4931,8 @@ class _Database extends EventEmitter {
         return { fk: "id", pk: reverse.foreignKey };
       return null;
     };
-    const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver);
+    const revisionGetter = () => this._getRevision(entityName);
+    const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, null, revisionGetter);
     if (initialCols.length > 0)
       builder.select(...initialCols);
     return builder;

package/package.json

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

@@ -5,7 +5,6 @@
  * query builders, and event handling.
  */
 import { Database as SqliteDatabase } from 'bun:sqlite';
-import { EventEmitter } from 'events';
 import { z } from 'zod';
 import { QueryBuilder } from './query-builder';
 import { executeProxyQuery, type ProxyQueryResult } from './proxy-query';
@@ -25,25 +24,25 @@ import {
 // Database Class
 // =============================================================================
 
-class _Database<Schemas extends SchemaMap> extends EventEmitter {
+class _Database<Schemas extends SchemaMap> {
     private db: SqliteDatabase;
     private schemas: Schemas;
     private relationships: Relationship[];
-    private subscriptions: Record<'insert' | 'update' | 'delete', Record<string, ((data: any) => void)[]>>;
     private options: DatabaseOptions;
 
+    /** In-memory revision counter per table — bumps on every write (insert/update/delete).
+     *  Used by QueryBuilder.subscribe() fingerprint to detect ALL changes with zero overhead. */
+    private _revisions: Record<string, number> = {};
+
     constructor(dbFile: string, schemas: Schemas, options: DatabaseOptions = {}) {
-        super();
         this.db = new SqliteDatabase(dbFile);
         this.db.run('PRAGMA foreign_keys = ON');
         this.schemas = schemas;
         this.options = options;
-        this.subscriptions = { insert: {}, update: {}, delete: {} };
         this.relationships = options.relations ? parseRelationsConfig(options.relations, schemas) : [];
         this.initializeTables();
         this.runMigrations();
         if (options.indexes) this.createIndexes(options.indexes);
-        if (options.changeTracking) this.setupChangeTracking();
 
         // Create typed entity accessors (db.users, db.posts, etc.)
         for (const entityName of Object.keys(schemas)) {
@@ -56,8 +55,6 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
                 },
                 upsert: (conditions, data) => this.upsert(entityName, data, conditions),
                 delete: (id) => this.delete(entityName, id),
-                subscribe: (event, callback) => this.subscribe(event, entityName, callback),
-                unsubscribe: (event, callback) => this.unsubscribe(event, entityName, callback),
                 select: (...cols: string[]) => this._createQueryBuilder(entityName, cols),
                 _tableName: entityName,
             };
@@ -90,85 +87,42 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
     }
 
     private runMigrations(): void {
-        this.db.run(`CREATE TABLE IF NOT EXISTS _schema_meta (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      table_name TEXT NOT NULL,
-      column_name TEXT NOT NULL,
-      added_at TEXT DEFAULT (datetime('now')),
-      UNIQUE(table_name, column_name)
-    )`);
-
         for (const [entityName, schema] of Object.entries(this.schemas)) {
-            const existingCols = new Set(
-                (this.db.query(`PRAGMA table_info(${entityName})`).all() as any[]).map(c => c.name)
-            );
-            const storableFields = getStorableFields(schema);
+            const existingColumns = this.db.query(`PRAGMA table_info(${entityName})`).all() as any[];
+            const existingNames = new Set(existingColumns.map(c => c.name));
 
+            const storableFields = getStorableFields(schema);
             for (const field of storableFields) {
-                if (!existingCols.has(field.name)) {
-                    this.db.run(`ALTER TABLE ${entityName} ADD COLUMN ${field.name} ${zodTypeToSqlType(field.type)}`);
-                    this.db.query(`INSERT OR IGNORE INTO _schema_meta (table_name, column_name) VALUES (?, ?)`).run(entityName, field.name);
+                if (!existingNames.has(field.name)) {
+                    const sqlType = zodTypeToSqlType(field.type);
+                    this.db.run(`ALTER TABLE ${entityName} ADD COLUMN ${field.name} ${sqlType}`);
                 }
             }
         }
     }
 
-    // ===========================================================================
-    // Indexes
-    // ===========================================================================
-
-    private createIndexes(indexDefs: Record<string, string | (string | string[])[]>): void {
-        for (const [tableName, indexes] of Object.entries(indexDefs)) {
-            if (!this.schemas[tableName]) throw new Error(`Cannot create index on unknown table '${tableName}'`);
-            const indexList = Array.isArray(indexes) ? indexes : [indexes];
-            for (const indexDef of indexList) {
-                const columns = Array.isArray(indexDef) ? indexDef : [indexDef];
-                const indexName = `idx_${tableName}_${columns.join('_')}`;
-                this.db.run(`CREATE INDEX IF NOT EXISTS ${indexName} ON ${tableName} (${columns.join(', ')})`);
+    private createIndexes(indexes: Record<string, (string | string[])[]>): void {
+        for (const [tableName, indexDefs] of Object.entries(indexes)) {
+            for (const def of indexDefs) {
+                const cols = Array.isArray(def) ? def : [def];
+                const idxName = `idx_${tableName}_${cols.join('_')}`;
+                this.db.run(`CREATE INDEX IF NOT EXISTS ${idxName} ON ${tableName} (${cols.join(', ')})`);
             }
         }
     }
 
     // ===========================================================================
-    // Change Tracking
+    // Revision Tracking (in-memory, zero overhead)
     // ===========================================================================
 
-    private setupChangeTracking(): void {
-        this.db.run(`CREATE TABLE IF NOT EXISTS _changes (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      table_name TEXT NOT NULL,
-      row_id INTEGER NOT NULL,
-      action TEXT NOT NULL CHECK(action IN ('INSERT', 'UPDATE', 'DELETE')),
-      changed_at TEXT DEFAULT (datetime('now'))
-    )`);
-        this.db.run(`CREATE INDEX IF NOT EXISTS idx_changes_table ON _changes (table_name, id)`);
-
-        for (const entityName of Object.keys(this.schemas)) {
-            for (const action of ['insert', 'update', 'delete'] as const) {
-                const ref = action === 'delete' ? 'OLD' : 'NEW';
-                this.db.run(`CREATE TRIGGER IF NOT EXISTS _trg_${entityName}_${action}
-          AFTER ${action.toUpperCase()} ON ${entityName}
-          BEGIN
-            INSERT INTO _changes (table_name, row_id, action) VALUES ('${entityName}', ${ref}.id, '${action.toUpperCase()}');
-          END`);
-            }
-        }
-    }
-
-    public getChangeSeq(tableName?: string): number {
-        if (!this.options.changeTracking) return -1;
-        const sql = tableName
-            ? `SELECT MAX(id) as seq FROM _changes WHERE table_name = ?`
-            : `SELECT MAX(id) as seq FROM _changes`;
-        const row = this.db.query(sql).get(...(tableName ? [tableName] : [])) as any;
-        return row?.seq ?? 0;
+    /** Bump the revision counter for a table. Called on every write. */
+    private _bumpRevision(entityName: string): void {
+        this._revisions[entityName] = (this._revisions[entityName] ?? 0) + 1;
     }
 
-    public getChangesSince(sinceSeq: number, tableName?: string) {
-        const sql = tableName
-            ? `SELECT * FROM _changes WHERE id > ? AND table_name = ? ORDER BY id ASC`
-            : `SELECT * FROM _changes WHERE id > ? ORDER BY id ASC`;
-        return this.db.query(sql).all(...(tableName ? [sinceSeq, tableName] : [sinceSeq])) as any[];
+    /** Get the current revision for a table. Used by QueryBuilder.subscribe() fingerprint. */
+    public _getRevision(entityName: string): number {
+        return this._revisions[entityName] ?? 0;
     }
 
     // ===========================================================================
@@ -189,8 +143,7 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
         const newEntity = this._getById(entityName, result.lastInsertRowid as number);
         if (!newEntity) throw new Error('Failed to retrieve entity after insertion');
 
-        this.emit('insert', entityName, newEntity);
-        this.subscriptions.insert[entityName]?.forEach(cb => cb(newEntity));
+        this._bumpRevision(entityName);
         return newEntity;
     }
 
@@ -227,11 +180,8 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
         const setClause = Object.keys(transformed).map(key => `${key} = ?`).join(', ');
         this.db.query(`UPDATE ${entityName} SET ${setClause} WHERE id = ?`).run(...Object.values(transformed), id);
 
+        this._bumpRevision(entityName);
         const updatedEntity = this._getById(entityName, id);
-        if (updatedEntity) {
-            this.emit('update', entityName, updatedEntity);
-            this.subscriptions.update[entityName]?.forEach(cb => cb(updatedEntity));
-        }
         return updatedEntity;
     }
 
@@ -252,12 +202,7 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
         );
 
         const affected = (result as any).changes ?? 0;
-        if (affected > 0 && (this.subscriptions.update[entityName]?.length || this.options.changeTracking)) {
-            for (const entity of this._findMany(entityName, conditions)) {
-                this.emit('update', entityName, entity);
-                this.subscriptions.update[entityName]?.forEach(cb => cb(entity));
-            }
-        }
+        if (affected > 0) this._bumpRevision(entityName);
         return affected;
     }
 
@@ -292,8 +237,7 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
         const entity = this._getById(entityName, id);
         if (entity) {
             this.db.query(`DELETE FROM ${entityName} WHERE id = ?`).run(id);
-            this.emit('delete', entityName, entity);
-            this.subscriptions.delete[entityName]?.forEach(cb => cb(entity));
+            this._bumpRevision(entityName);
         }
     }
 
@@ -415,21 +359,6 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
         }
     }
 
-    // ===========================================================================
-    // Events
-    // ===========================================================================
-
-    private subscribe(event: 'insert' | 'update' | 'delete', entityName: string, callback: (data: any) => void): void {
-        this.subscriptions[event][entityName] = this.subscriptions[event][entityName] || [];
-        this.subscriptions[event][entityName].push(callback);
-    }
-
-    private unsubscribe(event: 'insert' | 'update' | 'delete', entityName: string, callback: (data: any) => void): void {
-        if (this.subscriptions[event][entityName]) {
-            this.subscriptions[event][entityName] = this.subscriptions[event][entityName].filter(cb => cb !== callback);
-        }
-    }
-
     // ===========================================================================
     // Query Builders
     // ===========================================================================
@@ -460,7 +389,10 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
             return null;
         };
 
-        const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver);
+        // Pass revision getter — allows .subscribe() to detect ALL changes
+        const revisionGetter = () => this._getRevision(entityName);
+
+        const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, null, revisionGetter);
         if (initialCols.length > 0) builder.select(...initialCols);
         return builder;
     }

package/src/query-builder.ts

@@ -167,6 +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;
 
     constructor(
         tableName: string,
@@ -174,12 +175,14 @@ 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,
     ) {
         this.tableName = tableName;
         this.executor = executor;
         this.singleExecutor = singleExecutor;
         this.joinResolver = joinResolver ?? null;
         this.conditionResolver = conditionResolver ?? null;
+        this.revisionGetter = revisionGetter ?? null;
         this.iqo = {
             selects: [],
             wheres: [],
@@ -420,9 +423,9 @@ export class QueryBuilder<T extends Record<string, any>> {
     /**
      * Subscribe to query result changes using smart interval-based polling.
      *
-     * Instead of re-fetching all rows every tick, it runs a lightweight
-     * fingerprint query (`SELECT COUNT(*), MAX(id)`) with the same WHERE clause.
-     * The full query is only re-executed when the fingerprint changes.
+     * Uses a lightweight fingerprint (`COUNT(*), MAX(id)`) combined with an
+     * in-memory revision counter to detect ALL changes (inserts, updates, deletes)
+     * with zero disk overhead.
      *
      * ```ts
      * const unsub = db.messages.select()
@@ -456,7 +459,10 @@ 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;
-                const currentFingerprint = `${fpRow?._cnt ?? 0}:${fpRow?._max ?? 0}`;
+                // Include in-memory revision in fingerprint.
+                // This ensures ALL changes (insert/update/delete) are detected.
+                const rev = this.revisionGetter?.() ?? 0;
+                const currentFingerprint = `${fpRow?._cnt ?? 0}:${fpRow?._max ?? 0}:${rev}`;
 
                 if (currentFingerprint !== lastFingerprint) {
                     lastFingerprint = currentFingerprint;

package/src/types.ts

@@ -21,7 +21,6 @@ export type IndexDef = string | string[];
 
 /** Options for the Database constructor */
 export type DatabaseOptions<R extends RelationsConfig = RelationsConfig> = {
-    changeTracking?: boolean;
     indexes?: Record<string, IndexDef[]>;
     /**
      * Declare relationships between tables.
@@ -143,8 +142,6 @@ export type NavEntityAccessor<
     & ((data: Partial<Omit<z.input<S[Table & keyof S]>, 'id'>>) => UpdateBuilder<NavEntity<S, R, Table>>);
     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;
-    subscribe: (event: 'insert' | 'update' | 'delete', callback: (data: NavEntity<S, R, Table>) => void) => void;
-    unsubscribe: (event: 'insert' | 'update' | 'delete', callback: (data: NavEntity<S, R, Table>) => void) => void;
     select: (...cols: (keyof z.infer<S[Table & keyof S]> & string)[]) => QueryBuilder<NavEntity<S, R, Table>>;
     _tableName: string;
     readonly _schema?: S[Table & keyof S];
@@ -170,8 +167,6 @@ export type EntityAccessor<S extends z.ZodType<any>> = {
     update: ((id: number, data: Partial<EntityData<S>>) => AugmentedEntity<S> | null) & ((data: Partial<EntityData<S>>) => UpdateBuilder<AugmentedEntity<S>>);
     upsert: (conditions?: Partial<InferSchema<S>>, data?: Partial<InferSchema<S>>) => AugmentedEntity<S>;
     delete: (id: number) => void;
-    subscribe: (event: 'insert' | 'update' | 'delete', callback: (data: AugmentedEntity<S>) => void) => void;
-    unsubscribe: (event: 'insert' | 'update' | 'delete', callback: (data: AugmentedEntity<S>) => void) => void;
     select: (...cols: (keyof InferSchema<S> & string)[]) => QueryBuilder<AugmentedEntity<S>>;
     _tableName: string;
     readonly _schema?: S;