sqlite-zod-orm 3.21.0 → 3.22.0

package/dist/index.js

@@ -4493,6 +4493,12 @@ class QueryBuilder {
   first() {
     return this.get();
   }
+  firstOrFail() {
+    const row = this.get();
+    if (row === null)
+      throw new Error("No matching row found");
+    return row;
+  }
   exists() {
     const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
     const existsSql = selectSql.replace(/^SELECT .+? FROM/, "SELECT 1 FROM").replace(/ LIMIT \d+/, "") + " LIMIT 1";
@@ -4572,6 +4578,9 @@ class QueryBuilder {
     const aggSql = selectSql.replace(/^SELECT .+? FROM/, `SELECT ${groupCols}, COUNT(*) as count FROM`);
     return this.executor(aggSql, params, true);
   }
+  toSQL() {
+    return compileIQO(this.tableName, this.iqo);
+  }
   pluck(column) {
     const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
     const pluckSql = selectSql.replace(/^SELECT .+? FROM/, `SELECT "${column}" FROM`);

package/package.json

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

package/src/builder.ts

@@ -330,6 +330,19 @@ export class QueryBuilder<T extends Record<string, any>, TResult extends Record<
         return this.get();
     }
 
+    /**
+     * Return the first matching row or throw if none found.
+     * ```ts
+     * const user = db.users.select().where({ id: 1 }).firstOrFail();
+     * // throws Error('No matching row found') if id=1 doesn't exist
+     * ```
+     */
+    firstOrFail(): TResult {
+        const row = this.get();
+        if (row === null) throw new Error('No matching row found');
+        return row;
+    }
+
     /** Returns true if at least one row matches the query. */
     exists(): boolean {
         const { sql: selectSql, params } = compileIQO(this.tableName, this.iqo);
@@ -465,6 +478,19 @@ export class QueryBuilder<T extends Record<string, any>, TResult extends Record<
         return this.executor(aggSql, params, true) as any;
     }
 
+    // ---------- Query Inspection ----------
+
+    /**
+     * Compile and return the SQL string + params without executing.
+     * ```ts
+     * db.users.select().where({ role: 'admin' }).toSQL()
+     * // → { sql: 'SELECT * FROM "users" WHERE "role" = ?', params: ['admin'] }
+     * ```
+     */
+    toSQL(): { sql: string; params: any[] } {
+        return compileIQO(this.tableName, this.iqo);
+    }
+
     // ---------- Convenience Methods ----------
 
     /**