sqlite-zod-orm 3.7.3 → 3.9.0

package/src/database.ts

@@ -1,49 +1,86 @@
 /**
  * database.ts — Main Database class for sqlite-zod-orm
  *
- * Orchestrates schema-driven table creation, CRUD, relationships,
- * query builders, and event handling.
+ * Slim orchestrator: initializes the schema, creates tables/triggers,
+ * and delegates CRUD, entity augmentation, and query building to
+ * focused modules.
  */
 import { Database as SqliteDatabase } from 'bun:sqlite';
 import { z } from 'zod';
-import { QueryBuilder } from './query-builder';
-import { executeProxyQuery, type ProxyQueryResult } from './proxy-query';
+import { QueryBuilder, executeProxyQuery, createQueryBuilder, type ProxyQueryResult } from './query';
 import type {
     SchemaMap, DatabaseOptions, Relationship, RelationsConfig,
     EntityAccessor, TypedAccessors, TypedNavAccessors, AugmentedEntity, UpdateBuilder,
-    ProxyColumns, InferSchema,
+    ProxyColumns, InferSchema, ChangeEvent,
 } from './types';
 import { asZodObject } from './types';
 import {
     parseRelationsConfig,
     getStorableFields,
-    zodTypeToSqlType, transformForStorage, transformFromStorage,
+    zodTypeToSqlType,
 } from './schema';
+import { transformFromStorage } from './schema';
+import type { DatabaseContext } from './context';
+import { buildWhereClause } from './helpers';
+import { attachMethods } from './entity';
+import {
+    insert, insertMany, update, upsert, deleteEntity,
+    getById, getOne, findMany, updateWhere, createUpdateBuilder,
+} from './crud';
 
 // =============================================================================
 // Database Class
 // =============================================================================
 
+type Listener = {
+    table: string;
+    event: ChangeEvent;
+    callback: (row: any) => void | Promise<void>;
+};
+
 class _Database<Schemas extends SchemaMap> {
     private db: SqliteDatabase;
+    private _reactive: boolean;
     private schemas: Schemas;
     private relationships: Relationship[];
     private options: DatabaseOptions;
-    private pollInterval: number;
 
-    /** 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> = {};
+    /** Shared context for extracted modules. */
+    private _ctx: DatabaseContext;
+
+    /** Registered change listeners. */
+    private _listeners: Listener[] = [];
+
+    /** Watermark: last processed change id from _changes table. */
+    private _changeWatermark: number = 0;
+
+    /** Global poll timer (single loop for all listeners). */
+    private _pollTimer: ReturnType<typeof setInterval> | null = null;
+
+    /** Poll interval in ms. */
+    private _pollInterval: number;
 
     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 journal_mode = WAL');
         this.db.run('PRAGMA foreign_keys = ON');
         this.schemas = schemas;
         this.options = options;
-        this.pollInterval = options.pollInterval ?? 500;
+        this._reactive = options.reactive !== false; // default true
+        this._pollInterval = options.pollInterval ?? 100;
         this.relationships = options.relations ? parseRelationsConfig(options.relations, schemas) : [];
+
+        // Build the context that extracted modules use
+        this._ctx = {
+            db: this.db,
+            schemas: this.schemas as SchemaMap,
+            relationships: this.relationships,
+            attachMethods: (name, entity) => attachMethods(this._ctx, name, entity),
+            buildWhereClause: (conds, prefix) => buildWhereClause(conds, prefix),
+        };
+
         this.initializeTables();
+        if (this._reactive) this.initializeChangeTracking();
         this.runMigrations();
         if (options.indexes) this.createIndexes(options.indexes);
 
@@ -51,54 +88,100 @@ class _Database<Schemas extends SchemaMap> {
         for (const entityName of Object.keys(schemas)) {
             const key = entityName as keyof Schemas;
             const accessor: EntityAccessor<Schemas[typeof key]> = {
-                insert: (data) => this.insert(entityName, data),
+                insert: (data) => insert(this._ctx, entityName, data),
+                insertMany: (rows: any[]) => insertMany(this._ctx, entityName, rows),
                 update: (idOrData: any, data?: any) => {
-                    if (typeof idOrData === 'number') return this.update(entityName, idOrData, data);
-                    return this._createUpdateBuilder(entityName, idOrData);
+                    if (typeof idOrData === 'number') return update(this._ctx, entityName, idOrData, data);
+                    return createUpdateBuilder(this._ctx, entityName, idOrData);
+                },
+                upsert: (conditions, data) => upsert(this._ctx, entityName, data, conditions),
+                delete: (id) => deleteEntity(this._ctx, entityName, id),
+                select: (...cols: string[]) => createQueryBuilder(this._ctx, entityName, cols),
+                on: (event: ChangeEvent, callback: (row: any) => void | Promise<void>) => {
+                    return this._registerListener(entityName, event, callback);
                 },
-                upsert: (conditions, data) => this.upsert(entityName, data, conditions),
-                delete: (id) => this.delete(entityName, id),
-                select: (...cols: string[]) => this._createQueryBuilder(entityName, cols),
                 _tableName: entityName,
             };
             (this as any)[key] = accessor;
         }
     }
 
-    // ===========================================================================
+    // =========================================================================
     // Table Initialization & Migrations
-    // ===========================================================================
+    // =========================================================================
 
     private initializeTables(): void {
         for (const [entityName, schema] of Object.entries(this.schemas)) {
             const storableFields = getStorableFields(schema);
-            const columnDefs = storableFields.map(f => `${f.name} ${zodTypeToSqlType(f.type)}`);
+            const columnDefs = storableFields.map(f => `"${f.name}" ${zodTypeToSqlType(f.type)}`);
             const constraints: string[] = [];
 
-            // Add FOREIGN KEY constraints for FK columns declared in the schema
             const belongsToRels = this.relationships.filter(
                 rel => rel.type === 'belongs-to' && rel.from === entityName
             );
             for (const rel of belongsToRels) {
-                constraints.push(`FOREIGN KEY (${rel.foreignKey}) REFERENCES ${rel.to}(id) ON DELETE SET NULL`);
+                constraints.push(`FOREIGN KEY ("${rel.foreignKey}") REFERENCES "${rel.to}"(id) ON DELETE SET NULL`);
             }
 
             const allCols = columnDefs.join(', ');
             const allConstraints = constraints.length > 0 ? ', ' + constraints.join(', ') : '';
-            this.db.run(`CREATE TABLE IF NOT EXISTS ${entityName} (id INTEGER PRIMARY KEY AUTOINCREMENT, ${allCols}${allConstraints})`);
+            this.db.run(`CREATE TABLE IF NOT EXISTS "${entityName}" (id INTEGER PRIMARY KEY AUTOINCREMENT, ${allCols}${allConstraints})`);
+        }
+    }
+
+    /**
+     * Initialize per-table change tracking using triggers.
+     *
+     * Creates a `_changes` table that logs every insert/update/delete with
+     * the table name, operation, and affected row id. This enables
+     * row-level change detection for the `on()` API.
+     */
+    private initializeChangeTracking(): void {
+        this.db.run(`CREATE TABLE IF NOT EXISTS "_changes" (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            tbl TEXT NOT NULL,
+            op TEXT NOT NULL,
+            row_id INTEGER NOT NULL
+        )`);
+
+        for (const entityName of Object.keys(this.schemas)) {
+            // INSERT trigger — logs NEW.id
+            this.db.run(`CREATE TRIGGER IF NOT EXISTS "_trg_${entityName}_insert"
+                AFTER INSERT ON "${entityName}"
+                BEGIN
+                    INSERT INTO "_changes" (tbl, op, row_id) VALUES ('${entityName}', 'insert', NEW.id);
+                END`);
+
+            // UPDATE trigger — logs NEW.id (post-update row)
+            this.db.run(`CREATE TRIGGER IF NOT EXISTS "_trg_${entityName}_update"
+                AFTER UPDATE ON "${entityName}"
+                BEGIN
+                    INSERT INTO "_changes" (tbl, op, row_id) VALUES ('${entityName}', 'update', NEW.id);
+                END`);
+
+            // DELETE trigger — logs OLD.id (row that was deleted)
+            this.db.run(`CREATE TRIGGER IF NOT EXISTS "_trg_${entityName}_delete"
+                AFTER DELETE ON "${entityName}"
+                BEGIN
+                    INSERT INTO "_changes" (tbl, op, row_id) VALUES ('${entityName}', 'delete', OLD.id);
+                END`);
         }
+
+        // Initialize watermark to current max (skip replaying historical changes)
+        const row = this.db.query('SELECT MAX(id) as maxId FROM "_changes"').get() as any;
+        this._changeWatermark = row?.maxId ?? 0;
     }
 
     private runMigrations(): void {
         for (const [entityName, schema] of Object.entries(this.schemas)) {
-            const existingColumns = this.db.query(`PRAGMA table_info(${entityName})`).all() as any[];
+            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 (!existingNames.has(field.name)) {
                     const sqlType = zodTypeToSqlType(field.type);
-                    this.db.run(`ALTER TABLE ${entityName} ADD COLUMN ${field.name} ${sqlType}`);
+                    this.db.run(`ALTER TABLE "${entityName}" ADD COLUMN "${field.name}" ${sqlType}`);
                 }
             }
         }
@@ -109,389 +192,110 @@ class _Database<Schemas extends SchemaMap> {
             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(', ')})`);
+                this.db.run(`CREATE INDEX IF NOT EXISTS "${idxName}" ON "${tableName}" (${cols.map(c => `"${c}"`).join(', ')})`);
             }
         }
     }
 
-    // ===========================================================================
-    // Revision Tracking (in-memory + cross-process)
-    // ===========================================================================
-
-    /** Bump the revision counter for a table. Called on every write. */
-    private _bumpRevision(entityName: string): void {
-        this._revisions[entityName] = (this._revisions[entityName] ?? 0) + 1;
-    }
+    // =========================================================================
+    // Change Listeners — db.table.on('insert' | 'update' | 'delete', cb)
+    // =========================================================================
 
-    /**
-     * 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}`;
-    }
-
-    // ===========================================================================
-    // CRUD
-    // ===========================================================================
-
-    private insert<T extends Record<string, any>>(entityName: string, data: Omit<T, 'id'>): AugmentedEntity<any> {
-        const schema = this.schemas[entityName]!;
-        const validatedData = asZodObject(schema).passthrough().parse(data);
-        const transformed = transformForStorage(validatedData);
-        const columns = Object.keys(transformed);
-
-        const sql = columns.length === 0
-            ? `INSERT INTO ${entityName} DEFAULT VALUES`
-            : `INSERT INTO ${entityName} (${columns.join(', ')}) VALUES (${columns.map(() => '?').join(', ')})`;
-
-        const result = this.db.query(sql).run(...Object.values(transformed));
-        const newEntity = this._getById(entityName, result.lastInsertRowid as number);
-        if (!newEntity) throw new Error('Failed to retrieve entity after insertion');
-
-        this._bumpRevision(entityName);
-        return newEntity;
-    }
-
-    /** Internal: get a single entity by ID */
-    private _getById(entityName: string, id: number): AugmentedEntity<any> | null {
-        const row = this.db.query(`SELECT * FROM ${entityName} WHERE id = ?`).get(id) as any;
-        if (!row) return null;
-        return this._attachMethods(entityName, transformFromStorage(row, this.schemas[entityName]!));
-    }
-
-    /** Internal: get a single entity by conditions */
-    private _getOne(entityName: string, conditions: Record<string, any>): AugmentedEntity<any> | null {
-        const { clause, values } = this.buildWhereClause(conditions);
-        const row = this.db.query(`SELECT * FROM ${entityName} ${clause} LIMIT 1`).get(...values) as any;
-        if (!row) return null;
-        return this._attachMethods(entityName, transformFromStorage(row, this.schemas[entityName]!));
-    }
-
-    /** Internal: find multiple entities by conditions */
-    private _findMany(entityName: string, conditions: Record<string, any> = {}): AugmentedEntity<any>[] {
-        const { clause, values } = this.buildWhereClause(conditions);
-        const rows = this.db.query(`SELECT * FROM ${entityName} ${clause}`).all(...values);
-        return rows.map((row: any) =>
-            this._attachMethods(entityName, transformFromStorage(row, this.schemas[entityName]!))
-        );
-    }
-
-    private update<T extends Record<string, any>>(entityName: string, id: number, data: Partial<Omit<T, 'id'>>): AugmentedEntity<any> | null {
-        const schema = this.schemas[entityName]!;
-        const validatedData = asZodObject(schema).partial().parse(data);
-        const transformed = transformForStorage(validatedData);
-        if (Object.keys(transformed).length === 0) 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);
-        return updatedEntity;
-    }
-
-    private _updateWhere(entityName: string, data: Record<string, any>, conditions: Record<string, any>): number {
-        const schema = this.schemas[entityName]!;
-        const validatedData = asZodObject(schema).partial().parse(data);
-        const transformed = transformForStorage(validatedData);
-        if (Object.keys(transformed).length === 0) return 0;
-
-        const { clause, values: whereValues } = this.buildWhereClause(conditions);
-        if (!clause) throw new Error('update().where() requires at least one condition');
-
-        const setCols = Object.keys(transformed);
-        const setClause = setCols.map(key => `${key} = ?`).join(', ');
-        const result = this.db.query(`UPDATE ${entityName} SET ${setClause} ${clause}`).run(
-            ...setCols.map(key => transformed[key]),
-            ...whereValues
-        );
+    private _registerListener(table: string, event: ChangeEvent, callback: (row: any) => void | Promise<void>): () => void {
+        if (!this._reactive) {
+            throw new Error(
+                'Change listeners are disabled. Set { reactive: true } (or omit it) in Database options to enable .on().'
+            );
+        }
 
-        const affected = (result as any).changes ?? 0;
-        if (affected > 0) this._bumpRevision(entityName);
-        return affected;
-    }
+        const listener: Listener = { table, event, callback };
+        this._listeners.push(listener);
+        this._startPolling();
 
-    private _createUpdateBuilder(entityName: string, data: Record<string, any>): UpdateBuilder<any> {
-        let _conditions: Record<string, any> = {};
-        const builder: UpdateBuilder<any> = {
-            where: (conditions) => { _conditions = { ..._conditions, ...conditions }; return builder; },
-            exec: () => this._updateWhere(entityName, data, _conditions),
+        return () => {
+            const idx = this._listeners.indexOf(listener);
+            if (idx >= 0) this._listeners.splice(idx, 1);
+            if (this._listeners.length === 0) this._stopPolling();
         };
-        return builder;
     }
 
-    private upsert<T extends Record<string, any>>(entityName: string, data: any, conditions: any = {}): AugmentedEntity<any> {
-        const hasId = data?.id && typeof data.id === 'number';
-        const existing = hasId
-            ? this._getById(entityName, data.id)
-            : Object.keys(conditions ?? {}).length > 0
-                ? this._getOne(entityName, conditions)
-                : null;
-
-        if (existing) {
-            const updateData = { ...data };
-            delete updateData.id;
-            return this.update(entityName, existing.id, updateData) as AugmentedEntity<any>;
-        }
-        const insertData = { ...(conditions ?? {}), ...(data ?? {}) };
-        delete insertData.id;
-        return this.insert(entityName, insertData);
+    private _startPolling(): void {
+        if (this._pollTimer) return;
+        this._pollTimer = setInterval(() => this._processChanges(), this._pollInterval);
     }
 
-    private delete(entityName: string, id: number): void {
-        const entity = this._getById(entityName, id);
-        if (entity) {
-            this.db.query(`DELETE FROM ${entityName} WHERE id = ?`).run(id);
-            this._bumpRevision(entityName);
+    private _stopPolling(): void {
+        if (this._pollTimer) {
+            clearInterval(this._pollTimer);
+            this._pollTimer = null;
         }
     }
 
-    // ===========================================================================
-    // Entity Methods
-    // ===========================================================================
-
-    private _attachMethods<T extends Record<string, any>>(
-        entityName: string, entity: T
-    ): AugmentedEntity<any> {
-        const augmented = entity as any;
-        augmented.update = (data: any) => this.update(entityName, entity.id, data);
-        augmented.delete = () => this.delete(entityName, entity.id);
-
-        // Attach lazy relationship navigation
-        for (const rel of this.relationships) {
-            if (rel.from === entityName && rel.type === 'belongs-to') {
-                // book.author() → lazy load parent via author_id FK
-                augmented[rel.relationshipField] = () => {
-                    const fkValue = entity[rel.foreignKey];
-                    return fkValue ? this._getById(rel.to, fkValue) : null;
-                };
-            } else if (rel.from === entityName && rel.type === 'one-to-many') {
-                // author.books() → lazy load children
-                const belongsToRel = this.relationships.find(
-                    r => r.type === 'belongs-to' && r.from === rel.to && r.to === rel.from
-                );
-                if (belongsToRel) {
-                    const fk = belongsToRel.foreignKey;
-                    augmented[rel.relationshipField] = () => {
-                        return this._findMany(rel.to, { [fk]: entity.id });
-                    };
-                }
-            }
-        }
-
-        // Auto-persist proxy: setting a field auto-updates the DB row
-        const storableFieldNames = new Set(getStorableFields(this.schemas[entityName]!).map(f => f.name));
-        return new Proxy(augmented, {
-            set: (target, prop: string, value) => {
-                if (storableFieldNames.has(prop) && target[prop] !== value) {
-                    this.update(entityName, target.id, { [prop]: value });
-                }
-                target[prop] = value;
-                return true;
-            },
-            get: (target, prop, receiver) => Reflect.get(target, prop, receiver),
-        });
-    }
+    /**
+     * Core change dispatch loop.
+     *
+     * Fast path: checks MAX(id) against watermark first — if equal,
+     * there are no new changes and we skip entirely (no row materialization).
+     * Only fetches actual change rows when something has changed.
+     */
+    private _processChanges(): void {
+        // Fast path: check if anything changed at all (single scalar, index-only)
+        const head = this.db.query('SELECT MAX(id) as m FROM "_changes"').get() as any;
+        const maxId: number = head?.m ?? 0;
+        if (maxId <= this._changeWatermark) return;
+
+        const changes = this.db.query(
+            'SELECT id, tbl, op, row_id FROM "_changes" WHERE id > ? ORDER BY id'
+        ).all(this._changeWatermark) as { id: number; tbl: string; op: string; row_id: number }[];
+
+        for (const change of changes) {
+            const listeners = this._listeners.filter(
+                l => l.table === change.tbl && l.event === change.op
+            );
 
-    // ===========================================================================
-    // SQL Helpers
-    // ===========================================================================
-
-    private buildWhereClause(conditions: Record<string, any>, tablePrefix?: string): { clause: string; values: any[] } {
-        const parts: string[] = [];
-        const values: any[] = [];
-
-        for (const key in conditions) {
-            if (key.startsWith('$')) {
-                if (key === '$or' && Array.isArray(conditions[key])) {
-                    const orBranches = conditions[key] as Record<string, any>[];
-                    const orParts: string[] = [];
-                    for (const branch of orBranches) {
-                        const sub = this.buildWhereClause(branch, tablePrefix);
-                        if (sub.clause) {
-                            orParts.push(`(${sub.clause.replace(/^WHERE /, '')})`);
-                            values.push(...sub.values);
+            if (listeners.length > 0) {
+                if (change.op === 'delete') {
+                    // Row is gone — pass just the id
+                    const payload = { id: change.row_id };
+                    for (const l of listeners) {
+                        try { l.callback(payload); } catch { /* listener error */ }
+                    }
+                } else {
+                    // insert or update — re-fetch the current row
+                    const row = getById(this._ctx, change.tbl, change.row_id);
+                    if (row) {
+                        for (const l of listeners) {
+                            try { l.callback(row); } catch { /* listener error */ }
                         }
                     }
-                    if (orParts.length > 0) parts.push(`(${orParts.join(' OR ')})`);
                 }
-                continue;
             }
-            const value = conditions[key];
-            const fieldName = tablePrefix ? `${tablePrefix}.${key}` : key;
-
-            if (typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date)) {
-                const operator = Object.keys(value)[0];
-                if (!operator?.startsWith('$')) {
-                    throw new Error(`Querying on nested object '${key}' not supported. Use operators like $gt.`);
-                }
-                const operand = value[operator];
-
-                if (operator === '$in') {
-                    if (!Array.isArray(operand)) throw new Error(`$in for '${key}' requires an array`);
-                    if (operand.length === 0) { parts.push('1 = 0'); continue; }
-                    parts.push(`${fieldName} IN (${operand.map(() => '?').join(', ')})`);
-                    values.push(...operand.map((v: any) => transformForStorage({ v }).v));
-                    continue;
-                }
 
-                const sqlOp = ({ $gt: '>', $gte: '>=', $lt: '<', $lte: '<=', $ne: '!=' } as Record<string, string>)[operator];
-                if (!sqlOp) throw new Error(`Unsupported operator '${operator}' on '${key}'`);
-                parts.push(`${fieldName} ${sqlOp} ?`);
-                values.push(transformForStorage({ operand }).operand);
-            } else {
-                parts.push(`${fieldName} = ?`);
-                values.push(transformForStorage({ value }).value);
-            }
+            this._changeWatermark = change.id;
         }
 
-        return { clause: parts.length > 0 ? `WHERE ${parts.join(' AND ')}` : '', values };
+        // Clean up consumed changes
+        this.db.run('DELETE FROM "_changes" WHERE id <= ?', this._changeWatermark);
     }
 
-    // ===========================================================================
+    // =========================================================================
     // Transactions
-    // ===========================================================================
+    // =========================================================================
 
     public transaction<T>(callback: () => T): T {
-        try {
-            this.db.run('BEGIN TRANSACTION');
-            const result = callback();
-            this.db.run('COMMIT');
-            return result;
-        } catch (error) {
-            this.db.run('ROLLBACK');
-            throw new Error(`Transaction failed: ${(error as Error).message}`);
-        }
+        return this.db.transaction(callback)();
     }
 
-    // ===========================================================================
-    // Query Builders
-    // ===========================================================================
-
-    private _createQueryBuilder(entityName: string, initialCols: string[]): QueryBuilder<any> {
-        const schema = this.schemas[entityName]!;
-
-        const executor = (sql: string, params: any[], raw: boolean): any[] => {
-            const rows = this.db.query(sql).all(...params);
-            if (raw) return rows;
-            return rows.map((row: any) => this._attachMethods(entityName, transformFromStorage(row, schema)));
-        };
-
-        const singleExecutor = (sql: string, params: any[], raw: boolean): any | null => {
-            const results = executor(sql, params, raw);
-            return results.length > 0 ? results[0] : null;
-        };
-
-        const joinResolver = (fromTable: string, toTable: string): { fk: string; pk: string } | null => {
-            const belongsTo = this.relationships.find(
-                r => r.type === 'belongs-to' && r.from === fromTable && r.to === toTable
-            );
-            if (belongsTo) return { fk: belongsTo.foreignKey, pk: 'id' };
-            const reverse = this.relationships.find(
-                r => r.type === 'belongs-to' && r.from === toTable && r.to === fromTable
-            );
-            if (reverse) return { fk: 'id', pk: reverse.foreignKey };
-            return null;
-        };
-
-        // Pass revision getter — allows .subscribe() to detect ALL changes
-        const revisionGetter = () => this._getRevision(entityName);
-
-        // 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;
-        };
-
-        // Eager loader: resolves .with('books') → batch load children
-        const eagerLoader = (parentTable: string, relation: string, parentIds: number[]): { key: string; groups: Map<number, any[]> } | null => {
-            // 1. Try one-to-many: parentTable has-many relation (e.g., authors → books)
-            const hasMany = this.relationships.find(
-                r => r.type === 'one-to-many' && r.from === parentTable && r.relationshipField === relation
-            );
-            if (hasMany) {
-                // Find the belongs-to FK on the child table
-                const belongsTo = this.relationships.find(
-                    r => r.type === 'belongs-to' && r.from === hasMany.to && r.to === parentTable
-                );
-                if (belongsTo) {
-                    const fk = belongsTo.foreignKey;
-                    const placeholders = parentIds.map(() => '?').join(', ');
-                    const childRows = this.db.query(
-                        `SELECT * FROM ${hasMany.to} WHERE ${fk} IN (${placeholders})`
-                    ).all(...parentIds) as any[];
-
-                    const groups = new Map<number, any[]>();
-                    const childSchema = this.schemas[hasMany.to]!;
-                    for (const rawRow of childRows) {
-                        const entity = this._attachMethods(
-                            hasMany.to,
-                            transformFromStorage(rawRow, childSchema)
-                        );
-                        const parentId = rawRow[fk] as number;
-                        if (!groups.has(parentId)) groups.set(parentId, []);
-                        groups.get(parentId)!.push(entity);
-                    }
-                    return { key: relation, groups };
-                }
-            }
-
-            // 2. Try belongs-to: parentTable belongs-to relation (e.g., books → author)
-            const belongsTo = this.relationships.find(
-                r => r.type === 'belongs-to' && r.from === parentTable && r.relationshipField === relation
-            );
-            if (belongsTo) {
-                // Load parent entities and map by id
-                const fkValues = [...new Set(parentIds)];
-                // Actually we need FK values from parent rows, not parent IDs
-                // This case is trickier — skip for now, belongs-to is already handled by lazy nav
-                return null;
-            }
-
-            return null;
-        };
-
-        const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter, eagerLoader, this.pollInterval);
-        if (initialCols.length > 0) builder.select(...initialCols);
-        return builder;
+    /** Close the database: stops polling and releases the SQLite handle. */
+    public close(): void {
+        this._stopPolling();
+        this.db.close();
     }
 
+    // =========================================================================
+    // Proxy Query
+    // =========================================================================
+
     /** Proxy callback query for complex SQL-like JOINs */
     public query<T extends Record<string, any> = Record<string, any>>(
         callback: (ctx: { [K in keyof Schemas]: ProxyColumns<InferSchema<Schemas[K]>> }) => ProxyQueryResult