sqlite-zod-orm 3.4.0 → 3.5.0

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

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

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

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