sqlite-zod-orm 3.4.1 → 3.5.1

package/README.md

@@ -321,7 +321,7 @@ Run `bun examples/messages-demo.ts` for a full working demo.
 ```bash
 bun examples/messages-demo.ts  # .on() vs .subscribe() demo
 bun examples/example.ts        # comprehensive demo
-bun test                        # 93 tests
+bun test                        # 100 tests
 ```
 
 ---
@@ -336,6 +336,8 @@ bun test                        # 93 tests
 | `db.table.select(...cols?).where(filter).all()` | Array of rows |
 | `db.table.select().count()` | Count rows |
 | `db.table.select().join(db.other, cols?).all()` | Fluent join (auto FK) |
+| `db.table.select().with('children').all()` | Eager load related entities (no N+1) |
+| `.where({ relation: entity })` | Filter by entity reference |
 | `db.query(c => { ... })` | Proxy callback (SQL-like JOINs) |
 | **Writing** | |
 | `db.table.insert(data)` | Insert with validation |

package/dist/index.js

@@ -176,13 +176,15 @@ class QueryBuilder {
   joinResolver;
   conditionResolver;
   revisionGetter;
-  constructor(tableName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter) {
+  eagerLoader;
+  constructor(tableName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter, eagerLoader) {
     this.tableName = tableName;
     this.executor = executor;
     this.singleExecutor = singleExecutor;
     this.joinResolver = joinResolver ?? null;
     this.conditionResolver = conditionResolver ?? null;
     this.revisionGetter = revisionGetter ?? null;
+    this.eagerLoader = eagerLoader ?? null;
     this.iqo = {
       selects: [],
       wheres: [],
@@ -290,14 +292,40 @@ class QueryBuilder {
     this.iqo.raw = true;
     return this;
   }
+  with(...relations) {
+    this.iqo.includes.push(...relations);
+    return this;
+  }
+  _applyEagerLoads(results) {
+    if (this.iqo.includes.length === 0 || !this.eagerLoader || results.length === 0) {
+      return results;
+    }
+    const parentIds = results.map((r) => r.id).filter((id) => typeof id === "number");
+    if (parentIds.length === 0)
+      return results;
+    for (const relation of this.iqo.includes) {
+      const loaded = this.eagerLoader(this.tableName, relation, parentIds);
+      if (!loaded)
+        continue;
+      for (const row of results) {
+        row[loaded.key] = loaded.groups.get(row.id) ?? [];
+      }
+    }
+    return results;
+  }
   all() {
     const { sql, params } = compileIQO(this.tableName, this.iqo);
-    return this.executor(sql, params, this.iqo.raw);
+    const results = this.executor(sql, params, this.iqo.raw);
+    return this._applyEagerLoads(results);
   }
   get() {
     this.iqo.limit = 1;
     const { sql, params } = compileIQO(this.tableName, this.iqo);
-    return this.singleExecutor(sql, params, this.iqo.raw);
+    const result = this.singleExecutor(sql, params, this.iqo.raw);
+    if (!result)
+      return null;
+    const [loaded] = this._applyEagerLoads([result]);
+    return loaded ?? null;
   }
   count() {
     const params = [];
@@ -4737,19 +4765,29 @@ class _Database {
     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)
+    let stopped = false;
+    const poll = async () => {
+      if (stopped)
         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;
+      const currentRevision = this._getRevision(entityName);
+      if (currentRevision !== lastRevision) {
+        lastRevision = currentRevision;
+        const newRows = this.db.query(`SELECT * FROM "${entityName}" WHERE id > ? ORDER BY id ASC`).all(lastMaxId);
+        for (const rawRow of newRows) {
+          if (stopped)
+            return;
+          const entity = this._attachMethods(entityName, transformFromStorage(rawRow, this.schemas[entityName]));
+          await callback(entity);
+          lastMaxId = rawRow.id;
+        }
       }
-    }, interval);
-    return () => clearInterval(timer);
+      if (!stopped)
+        setTimeout(poll, interval);
+    };
+    setTimeout(poll, interval);
+    return () => {
+      stopped = true;
+    };
   }
   insert(entityName, data) {
     const schema = this.schemas[entityName];
@@ -4979,7 +5017,34 @@ class _Database {
       }
       return resolved;
     };
-    const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter);
+    const eagerLoader = (parentTable, relation, parentIds) => {
+      const hasMany = this.relationships.find((r) => r.type === "one-to-many" && r.from === parentTable && r.relationshipField === relation);
+      if (hasMany) {
+        const belongsTo2 = this.relationships.find((r) => r.type === "belongs-to" && r.from === hasMany.to && r.to === parentTable);
+        if (belongsTo2) {
+          const fk = belongsTo2.foreignKey;
+          const placeholders = parentIds.map(() => "?").join(", ");
+          const childRows = this.db.query(`SELECT * FROM ${hasMany.to} WHERE ${fk} IN (${placeholders})`).all(...parentIds);
+          const groups = new Map;
+          const childSchema = this.schemas[hasMany.to];
+          for (const rawRow of childRows) {
+            const entity = this._attachMethods(hasMany.to, transformFromStorage(rawRow, childSchema));
+            const parentId = rawRow[fk];
+            if (!groups.has(parentId))
+              groups.set(parentId, []);
+            groups.get(parentId).push(entity);
+          }
+          return { key: relation, groups };
+        }
+      }
+      const belongsTo = this.relationships.find((r) => r.type === "belongs-to" && r.from === parentTable && r.relationshipField === relation);
+      if (belongsTo) {
+        const fkValues = [...new Set(parentIds)];
+        return null;
+      }
+      return null;
+    };
+    const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter, eagerLoader);
     if (initialCols.length > 0)
       builder.select(...initialCols);
     return builder;

package/package.json

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

@@ -151,7 +151,7 @@ class _Database<Schemas extends SchemaMap> {
      */
     public _createOnStream(
         entityName: string,
-        callback: (row: any) => void,
+        callback: (row: any) => void | Promise<void>,
         options?: { interval?: number },
     ): () => void {
         const { interval = 500 } = options ?? {};
@@ -160,30 +160,43 @@ class _Database<Schemas extends SchemaMap> {
         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);
+        let stopped = false;
+
+        // Self-scheduling async loop: guarantees strict ordering
+        // - Each callback (sync or async) completes before the next row is emitted
+        // - Next poll only starts after the current batch is fully processed
+        const poll = async () => {
+            if (stopped) return;
 
-        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;
+            if (currentRevision !== lastRevision) {
+                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) {
+                    if (stopped) return; // bail if unsubscribed mid-batch
+                    const entity = this._attachMethods(
+                        entityName,
+                        transformFromStorage(rawRow, this.schemas[entityName]!)
+                    );
+                    await callback(entity); // await async callbacks
+                    lastMaxId = rawRow.id;
+                }
             }
-        }, interval);
 
-        return () => clearInterval(timer);
+            // Schedule next poll only after this one is done
+            if (!stopped) setTimeout(poll, interval);
+        };
+
+        // Start the loop
+        setTimeout(poll, interval);
+
+        return () => { stopped = true; };
     }
 
     // ===========================================================================
@@ -486,7 +499,55 @@ class _Database<Schemas extends SchemaMap> {
             return resolved;
         };
 
-        const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter);
+        // 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);
         if (initialCols.length > 0) builder.select(...initialCols);
         return builder;
     }

package/src/query-builder.ts

@@ -173,6 +173,7 @@ export class QueryBuilder<T extends Record<string, any>> {
     private joinResolver: ((fromTable: string, toTable: string) => { fk: string; pk: string } | null) | null;
     private conditionResolver: ((conditions: Record<string, any>) => Record<string, any>) | null;
     private revisionGetter: (() => string) | null;
+    private eagerLoader: ((parentTable: string, relation: string, parentIds: number[]) => { key: string; groups: Map<number, any[]> } | null) | null;
 
     constructor(
         tableName: string,
@@ -181,6 +182,7 @@ export class QueryBuilder<T extends Record<string, any>> {
         joinResolver?: ((fromTable: string, toTable: string) => { fk: string; pk: string } | null) | null,
         conditionResolver?: ((conditions: Record<string, any>) => Record<string, any>) | null,
         revisionGetter?: (() => string) | null,
+        eagerLoader?: ((parentTable: string, relation: string, parentIds: number[]) => { key: string; groups: Map<number, any[]> } | null) | null,
     ) {
         this.tableName = tableName;
         this.executor = executor;
@@ -188,6 +190,7 @@ export class QueryBuilder<T extends Record<string, any>> {
         this.joinResolver = joinResolver ?? null;
         this.conditionResolver = conditionResolver ?? null;
         this.revisionGetter = revisionGetter ?? null;
+        this.eagerLoader = eagerLoader ?? null;
         this.iqo = {
             selects: [],
             wheres: [],
@@ -374,19 +377,60 @@ export class QueryBuilder<T extends Record<string, any>> {
         return this;
     }
 
+    /**
+     * Eagerly load a related entity and attach as an array property.
+     *
+     * ```ts
+     * const authors = db.authors.select().with('books').all();
+     * // authors[0].books → [{ title: 'War and Peace', ... }, ...]
+     * ```
+     *
+     * Runs a single batched query (WHERE fk IN (...)) per relation,
+     * avoiding the N+1 problem of lazy navigation.
+     */
+    with(...relations: string[]): this {
+        this.iqo.includes.push(...relations);
+        return this;
+    }
+
+    /** Internal: apply eager loads to a set of results */
+    private _applyEagerLoads(results: T[]): T[] {
+        if (this.iqo.includes.length === 0 || !this.eagerLoader || results.length === 0) {
+            return results;
+        }
+
+        const parentIds = results.map((r: any) => r.id).filter((id: any) => typeof id === 'number');
+        if (parentIds.length === 0) return results;
+
+        for (const relation of this.iqo.includes) {
+            const loaded = this.eagerLoader(this.tableName, relation, parentIds);
+            if (!loaded) continue;
+
+            for (const row of results as any[]) {
+                row[loaded.key] = loaded.groups.get(row.id) ?? [];
+            }
+        }
+
+        return results;
+    }
+
     // ---------- Terminal / Execution Methods ----------
 
     /** Execute the query and return all matching rows. */
     all(): T[] {
         const { sql, params } = compileIQO(this.tableName, this.iqo);
-        return this.executor(sql, params, this.iqo.raw);
+        const results = this.executor(sql, params, this.iqo.raw);
+        return this._applyEagerLoads(results);
     }
 
     /** Execute the query and return the first matching row, or null. */
     get(): T | null {
         this.iqo.limit = 1;
         const { sql, params } = compileIQO(this.tableName, this.iqo);
-        return this.singleExecutor(sql, params, this.iqo.raw);
+        const result = this.singleExecutor(sql, params, this.iqo.raw);
+        if (!result) return null;
+        const [loaded] = this._applyEagerLoads([result]);
+        return loaded ?? null;
     }
 
     /** Execute the query and return the count of matching rows. */

package/src/types.ts

@@ -146,9 +146,10 @@ export type NavEntityAccessor<
     /**
      * Stream new rows one at a time, in insertion order.
      * Only emits rows inserted AFTER subscription starts.
+     * Callbacks are awaited — strict ordering guaranteed even with async handlers.
      * @returns Unsubscribe function.
      */
-    on: (callback: (row: NavEntity<S, R, Table>) => void, options?: { interval?: number }) => () => void;
+    on: (callback: (row: NavEntity<S, R, Table>) => void | Promise<void>, options?: { interval?: number }) => () => void;
     _tableName: string;
     readonly _schema?: S[Table & keyof S];
 };
@@ -177,9 +178,10 @@ export type EntityAccessor<S extends z.ZodType<any>> = {
     /**
      * Stream new rows one at a time, in insertion order.
      * Only emits rows inserted AFTER subscription starts.
+     * Callbacks are awaited — strict ordering guaranteed even with async handlers.
      * @returns Unsubscribe function.
      */
-    on: (callback: (row: AugmentedEntity<S>) => void, options?: { interval?: number }) => () => void;
+    on: (callback: (row: AugmentedEntity<S>) => void | Promise<void>, options?: { interval?: number }) => () => void;
     _tableName: string;
     readonly _schema?: S;
 };