bun-query-builder 0.1.30 → 0.1.32

package/dist/bin/cli.js

@@ -12344,6 +12344,14 @@ function* iterateAllPivots(meta, options = {}) {
 function isRawExpression(expr) {
   return typeof expr === "object" && expr !== null && "raw" in expr && typeof expr.raw === "string";
 }
+function raw(strings, ...values) {
+  if (typeof strings === "string")
+    return { raw: strings };
+  let out = strings[0];
+  for (let i = 0;i < values.length; i++)
+    out += formatSubqueryValue(values[i]) + strings[i + 1];
+  return { raw: out };
+}
 function quoteInsertIdent(id) {
   return config5.dialect === "mysql" ? `\`${id.replace(/`/g, "``")}\`` : `"${id.replace(/"/g, '""')}"`;
 }
@@ -12412,13 +12420,31 @@ function validateQualifiedIdentifier(value, context) {
       throw new TypeError(`[query-builder] ${context}: identifier segment '${part}' contains characters outside [A-Za-z0-9_]`);
   }
 }
-function assertSqlFragment(fragment, context) {
-  if (fragment === null || fragment === undefined) {
-    throw new TypeError(`[query-builder] ${context}: fragment must be a SqlFragment, got ${fragment}`);
-  }
+function renderRawFragment(fragment, context) {
   if (typeof fragment === "string") {
     warnOnceBareSqlFragment(context);
+    return fragment;
   }
+  if (fragment === null || fragment === undefined)
+    throw new TypeError(`[query-builder] ${context}: fragment must be a SqlFragment, got ${fragment}`);
+  if (isRawExpression(fragment))
+    return fragment.raw;
+  if (typeof fragment === "object") {
+    const f = fragment;
+    if (typeof f.raw === "string")
+      return f.raw;
+    if (typeof f.raw === "function") {
+      const r = f.raw();
+      if (typeof r === "string")
+        return r;
+    }
+    if (typeof f.sql === "string")
+      return f.sql;
+    const s = String(fragment);
+    if (s !== "[object Object]" && s !== "[object Promise]")
+      return s;
+  }
+  throw new TypeError(`[query-builder] ${context}: cannot render this value as a SQL fragment. ` + `A Bun \`sql\`...\`\` query object cannot be converted to SQL text \u2014 pass a ` + `string, or use the exported \`raw\` helper: raw\`count(*) as c\` / raw('age > 18').`);
 }
 function warnOnceBareSqlFragment(context) {
   if (warnedSqlFragmentContexts.has(context))
@@ -12435,6 +12461,8 @@ function formatSubqueryValue(val) {
     return val ? "1" : "0";
   if (typeof val === "string")
     return `'${val.replace(/'/g, "''")}'`;
+  if (val instanceof Date)
+    return `'${val.toISOString()}'`;
   throw new TypeError(`[query-builder] subquery condition: refusing to interpolate value of type ${typeof val}`);
 }
 function buildOverClause(partitionBy, orderBy) {
@@ -13091,12 +13119,12 @@ function createQueryBuilder(state) {
         return this;
       },
       selectRaw(fragment) {
-        assertSqlFragment(fragment, "selectRaw(fragment)");
+        const frag = renderRawFragment(fragment, "selectRaw(fragment)");
         const fromIdx = text.indexOf(" FROM ");
         if (fromIdx !== -1) {
-          text = `${text.substring(0, fromIdx)}, ${String(fragment)}${text.substring(fromIdx)}`;
+          text = `${text.substring(0, fromIdx)}, ${frag}${text.substring(fromIdx)}`;
         } else {
-          text += `, ${String(fragment)}`;
+          text += `, ${frag}`;
         }
         built = null;
         return this;
@@ -13209,12 +13237,15 @@ function createQueryBuilder(state) {
         if (cols.length === 0)
           return this;
         const rendered = cols.map(renderSelectColumn);
+        const distinctMatch = /^SELECT\s+(DISTINCT(?:\s+ON\s+\([^)]*\))?\s+)/i.exec(text);
+        const distinctPrefix = distinctMatch ? distinctMatch[1] : "";
         const fromIndex = text.indexOf(" FROM ");
         if (fromIndex !== -1) {
-          text = `SELECT ${rendered.join(", ")}${text.substring(fromIndex)}`;
+          text = `SELECT ${distinctPrefix}${rendered.join(", ")}${text.substring(fromIndex)}`;
         } else {
-          text = `SELECT ${rendered.join(", ")} FROM ${table}`;
+          text = `SELECT ${distinctPrefix}${rendered.join(", ")} FROM ${table}`;
         }
+        built = null;
         return this;
       },
       addSelect(...columns2) {
@@ -13292,6 +13323,54 @@ function createQueryBuilder(state) {
             }
             return "";
           };
+          const buildJoinConstraint = (targetTbl) => {
+            if (!condition)
+              return "";
+            const frags = [];
+            const addCmp = (col, op, val) => {
+              validateIdentifier(String(col), "with() constraint column");
+              const operator = assertSafeWhereOperator(op, "with() constraint operator");
+              frags.push(`${targetTbl}.${String(col)} ${operator} ${formatSubqueryValue(val)}`);
+            };
+            const unsupported = (m) => () => {
+              throw new Error(`[query-builder] with('${relationKey}', ...): ${m} is not supported inside a constraint callback on the JOIN-based builder \u2014 apply it to the outer query, or use the model layer's eager loading. (Silently ignoring it would return wrong data.)`);
+            };
+            const constraintQb = {
+              where: (expr, op, val) => {
+                if (Array.isArray(expr))
+                  addCmp(expr[0], expr[1], expr[2]);
+                else if (expr && typeof expr === "object")
+                  for (const k of Object.keys(expr))
+                    addCmp(k, "=", expr[k]);
+                else if (op !== undefined && val !== undefined)
+                  addCmp(expr, op, val);
+                else if (op !== undefined)
+                  addCmp(expr, "=", op);
+                return constraintQb;
+              },
+              whereIn: (col, vals) => {
+                validateIdentifier(String(col), "with() constraint column");
+                frags.push(`${targetTbl}.${String(col)} IN (${vals.map(formatSubqueryValue).join(", ")})`);
+                return constraintQb;
+              },
+              whereNull: (col) => {
+                validateIdentifier(String(col), "with() constraint column");
+                frags.push(`${targetTbl}.${String(col)} IS NULL`);
+                return constraintQb;
+              },
+              whereNotNull: (col) => {
+                validateIdentifier(String(col), "with() constraint column");
+                frags.push(`${targetTbl}.${String(col)} IS NOT NULL`);
+                return constraintQb;
+              },
+              orderBy: unsupported("orderBy()"),
+              limit: unsupported("limit()"),
+              offset: unsupported("offset()"),
+              take: unsupported("take()")
+            };
+            condition(constraintQb);
+            return frags.length ? ` AND ${frags.join(" AND ")}` : "";
+          };
           const resolveTarget = () => {
             const pick = (m) => {
               const modelName = m?.[relationKey];
@@ -13336,7 +13415,7 @@ function createQueryBuilder(state) {
             const throughPk = meta.primaryKeys[throughTable] ?? "id";
             const fkInThrough = `${singularize(fromTable)}_id`;
             const fkInFinal = `${singularize(throughTable)}_id`;
-            built = sql`${ensureBuilt()} LEFT JOIN ${sql(throughTable)} ON ${sql(`${throughTable}.${fkInThrough}`)} = ${sql(`${fromTable}.${fromPk}`)} LEFT JOIN ${sql(finalTable)} ON ${sql(`${finalTable}.${fkInFinal}`)} = ${sql(`${throughTable}.${throughPk}`)}`;
+            insertJoin(`LEFT JOIN ${throughTable} ON ${throughTable}.${fkInThrough} = ${fromTable}.${fromPk} LEFT JOIN ${finalTable} ON ${finalTable}.${fkInFinal} = ${throughTable}.${throughPk}`);
             joinedTables.add(throughTable);
             joinedTables.add(finalTable);
             return finalTable;
@@ -13349,7 +13428,7 @@ function createQueryBuilder(state) {
             const childPk = meta.primaryKeys[childTable] ?? "id";
             const fkA = resolved?.fkParent ?? `${singularize(fromTable)}_id`;
             const fkB = resolved?.fkRelated ?? `${singularize(childTable)}_id`;
-            built = sql`${ensureBuilt()} LEFT JOIN ${sql(pivot)} ON ${sql(`${pivot}.${fkA}`)} = ${sql(`${fromTable}.${fromPk}`)} LEFT JOIN ${sql(childTable)} ON ${sql(`${childTable}.${childPk}`)} = ${sql(`${pivot}.${fkB}`)}`;
+            insertJoin(`LEFT JOIN ${pivot} ON ${pivot}.${fkA} = ${fromTable}.${fromPk} LEFT JOIN ${childTable} ON ${childTable}.${childPk} = ${pivot}.${fkB}${buildJoinConstraint(childTable)}`);
             joinedTables.add(pivot);
             joinedTables.add(childTable);
             return childTable;
@@ -13363,7 +13442,8 @@ function createQueryBuilder(state) {
             const morphType = `${morphName}_type`;
             const morphId = `${morphName}_id`;
             const targetFk = `${singularize(childTable)}_id`;
-            built = sql`${ensureBuilt()} LEFT JOIN ${sql(pivotTable)} ON ${sql(`${pivotTable}.${morphId}`)} = ${sql(`${fromTable}.${fromPk}`)} AND ${sql(`${pivotTable}.${morphType}`)} = ${sql(meta.tableToModel[fromTable] || fromTable)} LEFT JOIN ${sql(childTable)} ON ${sql(`${childTable}.${childPk}`)} = ${sql(`${pivotTable}.${targetFk}`)}`;
+            const morphVal = formatSubqueryValue(meta.tableToModel[fromTable] || fromTable);
+            insertJoin(`LEFT JOIN ${pivotTable} ON ${pivotTable}.${morphId} = ${fromTable}.${fromPk} AND ${pivotTable}.${morphType} = ${morphVal} LEFT JOIN ${childTable} ON ${childTable}.${childPk} = ${pivotTable}.${targetFk}`);
             joinedTables.add(pivotTable);
             joinedTables.add(childTable);
             return childTable;
@@ -13379,7 +13459,8 @@ function createQueryBuilder(state) {
             const morphType = `${morphName}_type`;
             const morphId = `${morphName}_id`;
             const relatedFk = `${singularize(relatedTable)}_id`;
-            built = sql`${ensureBuilt()} LEFT JOIN ${sql(pivotTable)} ON ${sql(`${pivotTable}.${relatedFk}`)} = ${sql(`${fromTable}.${fromPk}`)} LEFT JOIN ${sql(relatedTable)} ON ${sql(`${relatedTable}.${relatedPk}`)} = ${sql(`${pivotTable}.${morphId}`)} AND ${sql(`${pivotTable}.${morphType}`)} = ${sql(meta.tableToModel[relatedTable] || relatedTable)}`;
+            const morphVal = formatSubqueryValue(meta.tableToModel[relatedTable] || relatedTable);
+            insertJoin(`LEFT JOIN ${pivotTable} ON ${pivotTable}.${relatedFk} = ${fromTable}.${fromPk} LEFT JOIN ${relatedTable} ON ${relatedTable}.${relatedPk} = ${pivotTable}.${morphId} AND ${pivotTable}.${morphType} = ${morphVal}`);
             joinedTables.add(pivotTable);
             joinedTables.add(relatedTable);
             return relatedTable;
@@ -13388,7 +13469,7 @@ function createQueryBuilder(state) {
           if (isBt) {
             const fkInParent = `${singularize(childTable)}_id`;
             const childPk = meta.primaryKeys[childTable] ?? "id";
-            built = sql`${ensureBuilt()} LEFT JOIN ${sql(childTable)} ON ${sql(`${fromTable}.${fkInParent}`)} = ${sql(`${childTable}.${childPk}`)}`;
+            insertJoin(`LEFT JOIN ${childTable} ON ${fromTable}.${fkInParent} = ${childTable}.${childPk}${buildJoinConstraint(childTable)}`);
             joinedTables.add(childTable);
             return childTable;
           }
@@ -13398,20 +13479,15 @@ function createQueryBuilder(state) {
             const morphType = `${relationKey}_type`;
             const morphId = `${relationKey}_id`;
             const fromPk = meta.primaryKeys[fromTable] ?? "id";
-            built = sql`${ensureBuilt()} LEFT JOIN ${sql(childTable)} ON ${sql(`${childTable}.${morphId}`)} = ${sql(`${fromTable}.${fromPk}`)} AND ${sql(`${childTable}.${morphType}`)} = ${sql(meta.tableToModel[fromTable] || fromTable)}`;
+            const morphVal = formatSubqueryValue(meta.tableToModel[fromTable] || fromTable);
+            insertJoin(`LEFT JOIN ${childTable} ON ${childTable}.${morphId} = ${fromTable}.${fromPk} AND ${childTable}.${morphType} = ${morphVal}`);
             joinedTables.add(childTable);
             return childTable;
           }
           const fkInChild = `${singularize(fromTable)}_id`;
           const pk = meta.primaryKeys[fromTable] ?? "id";
-          const softDeleteCheck = addSoftDeleteCheck(childTable);
-          if (softDeleteCheck) {
-            const currentSql = String(ensureBuilt());
-            const joinCondition = `${childTable}.${fkInChild} = ${fromTable}.${pk}${softDeleteCheck}`;
-            built = sql`${sql(currentSql)} LEFT JOIN ${sql(childTable)} ON ${sql(joinCondition)}`;
-          } else {
-            built = sql`${ensureBuilt()} LEFT JOIN ${sql(childTable)} ON ${sql(`${childTable}.${fkInChild}`)} = ${sql(`${fromTable}.${pk}`)}`;
-          }
+          const extraOn = `${addSoftDeleteCheck(childTable)}${buildJoinConstraint(childTable)}`;
+          insertJoin(`LEFT JOIN ${childTable} ON ${childTable}.${fkInChild} = ${fromTable}.${pk}${extraOn}`);
           joinedTables.add(childTable);
           return childTable;
         };
@@ -13448,7 +13524,7 @@ function createQueryBuilder(state) {
             addToSelectClause(pivotColumnsStr);
           }
         }
-        text = computeSqlText(ensureBuilt());
+        built = null;
         return this;
       },
       whereHas(relation, callback) {
@@ -14058,9 +14134,9 @@ function createQueryBuilder(state) {
         return this;
       },
       whereRaw(fragment) {
-        assertSqlFragment(fragment, "whereRaw(fragment)");
+        const frag = renderRawFragment(fragment, "whereRaw(fragment)");
         const keyword = SQL_PATTERNS.WHERE.test(text) ? "AND" : "WHERE";
-        text += ` ${keyword} ${String(fragment)}`;
+        text += ` ${keyword} ${frag}`;
         built = null;
         return this;
       },
@@ -14426,8 +14502,8 @@ function createQueryBuilder(state) {
         return this;
       },
       groupByRaw(fragment) {
-        assertSqlFragment(fragment, "groupByRaw(fragment)");
-        text = SQL_PATTERNS.GROUP_BY.test(text) ? `${text}, ${String(fragment)}` : `${text} GROUP BY ${String(fragment)}`;
+        const frag = renderRawFragment(fragment, "groupByRaw(fragment)");
+        text = SQL_PATTERNS.GROUP_BY.test(text) ? `${text}, ${frag}` : `${text} GROUP BY ${frag}`;
         built = null;
         return this;
       },
@@ -14459,15 +14535,15 @@ function createQueryBuilder(state) {
         return this;
       },
       havingRaw(fragment) {
-        assertSqlFragment(fragment, "havingRaw(fragment)");
+        const frag = renderRawFragment(fragment, "havingRaw(fragment)");
         const kw = /\bHAVING\b/i.test(text) ? "AND" : "HAVING";
-        text += ` ${kw} ${String(fragment)}`;
+        text += ` ${kw} ${frag}`;
         built = null;
         return this;
       },
       orderByRaw(fragment) {
-        assertSqlFragment(fragment, "orderByRaw(fragment)");
-        text = SQL_PATTERNS.ORDER_BY.test(text) ? `${text}, ${String(fragment)}` : `${text} ORDER BY ${String(fragment)}`;
+        const frag = renderRawFragment(fragment, "orderByRaw(fragment)");
+        text = SQL_PATTERNS.ORDER_BY.test(text) ? `${text}, ${frag}` : `${text} ORDER BY ${frag}`;
         built = null;
         return this;
       },
@@ -14650,20 +14726,20 @@ function createQueryBuilder(state) {
         includeTrashed = true;
         onlyTrashed = true;
         const softDeleteColumn = config5.softDeletes?.column || "deleted_at";
-        const splice = (raw, predicate2) => {
-          const upper = raw.toUpperCase();
+        const splice = (raw2, predicate2) => {
+          const upper = raw2.toUpperCase();
           let depth = 0;
-          for (let i = 0;i < raw.length; i++) {
-            const c = raw[i];
+          for (let i = 0;i < raw2.length; i++) {
+            const c = raw2[i];
             if (c === "(")
               depth++;
             else if (c === ")")
               depth--;
-            else if (depth === 0 && upper.substring(i, i + 5) === "WHERE" && (i === 0 || /\s/.test(raw[i - 1] ?? "")) && /\s/.test(raw[i + 5] ?? "")) {
-              return `${raw.substring(0, i)}WHERE ${predicate2} AND ${raw.substring(i + 6)}`;
+            else if (depth === 0 && upper.substring(i, i + 5) === "WHERE" && (i === 0 || /\s/.test(raw2[i - 1] ?? "")) && /\s/.test(raw2[i + 5] ?? "")) {
+              return `${raw2.substring(0, i)}WHERE ${predicate2} AND ${raw2.substring(i + 6)}`;
             }
           }
-          return `${raw} WHERE ${predicate2}`;
+          return `${raw2} WHERE ${predicate2}`;
         };
         const predicate = `${table}.${softDeleteColumn} IS NOT NULL`;
         text = splice(text, predicate);
@@ -14967,13 +15043,13 @@ function createQueryBuilder(state) {
           const cacheKey = `${String(table)}|${prop}`;
           let chosen = dynamicWhereColumnCache.get(cacheKey);
           if (chosen === undefined) {
-            const raw = prop.replace(/^(?:or|and)?where/i, "");
-            if (!raw) {
+            const raw2 = prop.replace(/^(?:or|and)?where/i, "");
+            if (!raw2) {
               dynamicWhereColumnCache.set(cacheKey, "");
               chosen = "";
             } else {
-              const lowerFirst = raw.charAt(0).toLowerCase() + raw.slice(1);
-              const snake = raw.replace(/([A-Z])/g, "_$1").toLowerCase().replace(/^_/, "");
+              const lowerFirst = raw2.charAt(0).toLowerCase() + raw2.slice(1);
+              const snake = raw2.replace(/([A-Z])/g, "_$1").toLowerCase().replace(/^_/, "");
               const available = schema ? Object.keys(schema[String(table)]?.columns ?? {}) : [];
               chosen = [snake, lowerFirst, lowerFirst.toLowerCase()].find((n) => available.includes(n)) ?? snake;
               dynamicWhereColumnCache.set(cacheKey, chosen);
@@ -15363,6 +15439,10 @@ function createQueryBuilder(state) {
         returning(...cols) {
           const returningSql = `${sqlText} RETURNING ${cols.join(", ")}`;
           const q = _sql.unsafe(returningSql, params);
+          const runFirst = async () => {
+            const rows = await runWithHooks(q, "insert");
+            return Array.isArray(rows) ? rows[0] : rows;
+          };
           return {
             where: () => this,
             andWhere: () => this,
@@ -15371,7 +15451,22 @@ function createQueryBuilder(state) {
             limit: () => this,
             offset: () => this,
             toSQL: () => makeExecutableQuery(q, returningSql),
-            execute: () => runWithHooks(q, "insert")
+            execute: () => runWithHooks(q, "insert"),
+            get: () => runWithHooks(q, "insert"),
+            first: runFirst,
+            executeTakeFirst: runFirst,
+            async firstOrFail() {
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Insert with RETURNING returned no rows");
+              return row;
+            },
+            async executeTakeFirstOrThrow() {
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Insert with RETURNING returned no rows");
+              return row;
+            }
           };
         },
         toSQL() {
@@ -15410,19 +15505,27 @@ function createQueryBuilder(state) {
         returningAll() {
           const returningSql = `${sqlText} RETURNING *`;
           const q = _sql.unsafe(returningSql, params);
+          const runFirst = async () => {
+            const result = await runWithHooks(q, "insert");
+            return Array.isArray(result) ? result[0] : result;
+          };
           return {
             toSQL: () => makeExecutableQuery(q, returningSql),
             execute: () => runWithHooks(q, "insert"),
-            async executeTakeFirst() {
-              const result = await runWithHooks(q, "insert");
-              return Array.isArray(result) ? result[0] : result;
+            get: () => runWithHooks(q, "insert"),
+            first: runFirst,
+            executeTakeFirst: runFirst,
+            async firstOrFail() {
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Insert with RETURNING returned no rows");
+              return row;
             },
             async executeTakeFirstOrThrow() {
-              const result = await runWithHooks(q, "insert");
-              const first = Array.isArray(result) ? result[0] : result;
-              if (!first)
-                throw new Error("Insert with RETURNING failed");
-              return first;
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Insert with RETURNING returned no rows");
+              return row;
             }
           };
         }
@@ -15486,6 +15589,10 @@ function createQueryBuilder(state) {
         returning(...cols) {
           const retText = `${sqlText} RETURNING ${cols.join(", ")}`;
           const q = params.length > 0 ? _sql.unsafe(retText, params) : _sql.unsafe(retText);
+          const runFirst = async () => {
+            const rows = await runWithHooks(q, "update");
+            return Array.isArray(rows) ? rows[0] : rows;
+          };
           const obj = {
             where: () => obj,
             andWhere: () => obj,
@@ -15494,7 +15601,22 @@ function createQueryBuilder(state) {
             limit: () => obj,
             offset: () => obj,
             toSQL: () => makeExecutableQuery(q, retText),
-            execute: () => runWithHooks(q, "update")
+            execute: () => runWithHooks(q, "update"),
+            get: () => runWithHooks(q, "update"),
+            first: runFirst,
+            executeTakeFirst: runFirst,
+            async firstOrFail() {
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Update with RETURNING returned no rows");
+              return row;
+            },
+            async executeTakeFirstOrThrow() {
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Update with RETURNING returned no rows");
+              return row;
+            }
           };
           return obj;
         },
@@ -15593,6 +15715,10 @@ function createQueryBuilder(state) {
         returning(...cols) {
           const retText = `${sqlText} RETURNING ${cols.join(", ")}`;
           const q = delParams.length > 0 ? _sql.unsafe(retText, delParams) : _sql.unsafe(retText);
+          const runFirst = async () => {
+            const rows = await runWithHooks(q, "delete");
+            return Array.isArray(rows) ? rows[0] : rows;
+          };
           const obj = {
             where: () => obj,
             andWhere: () => obj,
@@ -15601,7 +15727,22 @@ function createQueryBuilder(state) {
             limit: () => obj,
             offset: () => obj,
             toSQL: () => makeExecutableQuery(q, retText),
-            execute: () => runWithHooks(q, "delete")
+            execute: () => runWithHooks(q, "delete"),
+            get: () => runWithHooks(q, "delete"),
+            first: runFirst,
+            executeTakeFirst: runFirst,
+            async firstOrFail() {
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Delete with RETURNING returned no rows");
+              return row;
+            },
+            async executeTakeFirstOrThrow() {
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Delete with RETURNING returned no rows");
+              return row;
+            }
           };
           return obj;
         },
@@ -17953,8 +18094,8 @@ function loadPlanSnapshot(workspaceRoot, dialect) {
     return;
   }
   try {
-    const raw = readFileSync3(snapshotPath, "utf8");
-    const parsed = JSON.parse(raw);
+    const raw2 = readFileSync3(snapshotPath, "utf8");
+    const parsed = JSON.parse(raw2);
     if (parsed?.plan && Array.isArray(parsed.plan.tables) && parsed.plan.dialect) {
       return parsed.plan;
     }
@@ -18013,8 +18154,8 @@ async function generateMigration(dir, opts = {}) {
       const statePath = String(opts.state || defaultStatePath);
       if (existsSync16(statePath)) {
         try {
-          const raw = readFileSync3(statePath, "utf8");
-          const parsed = JSON.parse(raw);
+          const raw2 = readFileSync3(statePath, "utf8");
+          const parsed = JSON.parse(raw2);
           previous = parsed?.plan && parsed.plan.tables ? parsed.plan : parsed?.tables ? parsed : undefined;
           if (previous) {
             info("-- Comparing with legacy state file (will migrate to new snapshot format)");
@@ -24604,10 +24745,10 @@ class BelongsToManyRelationBuilder {
   hydrateRows(rows) {
     const fkParent = this.fkParent;
     const fkRelated = this.fkRelated;
-    return rows.map((raw) => {
+    return rows.map((raw2) => {
       const relatedRow = {};
       const pivotExtras = {};
-      for (const [k2, v2] of Object.entries(raw)) {
+      for (const [k2, v2] of Object.entries(raw2)) {
         if (k2.startsWith(BTM_RELATED_ALIAS))
           relatedRow[k2.slice(BTM_RELATED_ALIAS.length)] = v2;
         else if (k2 !== fkParent && k2 !== fkRelated)
@@ -29073,11 +29214,11 @@ Received ${signal}, cleaning up...`);
       argsAfterDoubleDashes = argv.slice(doubleDashesIndex + 1);
       argv = argv.slice(0, doubleDashesIndex);
     }
-    const raw = parseArgv(argv, mriOptions);
-    const parsed = { _: raw._ };
-    for (const name of Object.keys(raw)) {
+    const raw2 = parseArgv(argv, mriOptions);
+    const parsed = { _: raw2._ };
+    for (const name of Object.keys(raw2)) {
       if (name !== "_") {
-        parsed[camelcaseOptionName(name)] = raw[name];
+        parsed[camelcaseOptionName(name)] = raw2[name];
       }
     }
     const args = parsed._;
@@ -29122,11 +29263,11 @@ Received ${signal}, cleaning up...`);
     if (!isUsage)
       return;
     const e2 = err;
-    const raw = e2.message ?? "command-line error";
+    const raw2 = e2.message ?? "command-line error";
     const label = this.name ? `${this.name}: ` : "";
-    const suffix = /--help/.test(raw) ? "" : `
+    const suffix = /--help/.test(raw2) ? "" : `
 Run \`${this.name ?? "cli"} --help\` for usage.`;
-    process52.stderr.write(`${label}${raw}${suffix}
+    process52.stderr.write(`${label}${raw2}${suffix}
 `);
     process52.exit(e2.exitCode ?? 2);
   }
@@ -29984,7 +30125,7 @@ function getPrefix() {
 }
 var prefix = getPrefix();
 // package.json
-var version2 = "0.1.30";
+var version2 = "0.1.32";
 
 // bin/cli.ts
 init_actions();

package/dist/client.d.ts

@@ -2,6 +2,33 @@ import { config } from './config';
 import { resetConnection } from './db';
 import type { DatabaseSchema } from './schema';
 import type { SchemaMeta } from './meta';
+/**
+ * # `raw`
+ *
+ * Build a raw SQL fragment for the `*Raw` builder methods (`whereRaw`,
+ * `selectRaw`, `orderByRaw`, `groupByRaw`, `havingRaw`) and `select()`.
+ *
+ * Use this INSTEAD of a Bun `sql\`...\`` tag: a Bun query object cannot be
+ * converted back to SQL text (it stringifies to "[object Promise]"), so it
+ * silently corrupts the generated SQL. `raw` returns a `{ raw: string }`
+ * fragment that the builder renders correctly and that satisfies the
+ * `SqlFragment` type (so it passes the bare-string injection guard).
+ *
+ * Interpolated values in the tagged-template form are SQL-escaped (strings
+ * single-quote-doubled, dates → ISO, numbers/booleans/null inlined) — the
+ * same escaping the relation-subquery builders use. For user input that must
+ * be parameterised, prefer the typed `where(...)` methods over `raw`.
+ *
+ * @example
+ * ```ts
+ * import { raw } from 'bun-query-builder'
+ * db.selectFrom('users').selectRaw(raw`count(*) as c`)
+ * db.selectFrom('users').whereRaw(raw('age > 18'))
+ * db.selectFrom('users').orderByRaw(raw`created_at desc`)
+ * db.selectFrom('orders').whereRaw(raw`status = ${userStatus}`) // value escaped
+ * ```
+ */
+export declare function raw(strings: TemplateStringsArray | string, ...values: unknown[]): RawExpression;
 // eslint-disable-next-line pickier/no-unused-vars
 export declare function createQueryBuilder<DB extends DatabaseSchema<any>>(state?: Partial<InternalState>): QueryBuilder<DB>;
 /**
@@ -26,6 +53,10 @@ export declare function clearQueryCache(): void;
  * ```
  */
 export declare function setQueryCacheMaxSize(size: number): void;
+// Type guard for raw SQL expressions
+declare interface RawExpression {
+  raw: string
+}
 export declare interface WhereRaw {
   raw: any
 }

package/dist/src/index.js

@@ -12344,6 +12344,14 @@ function* iterateAllPivots(meta, options = {}) {
 function isRawExpression(expr) {
   return typeof expr === "object" && expr !== null && "raw" in expr && typeof expr.raw === "string";
 }
+function raw(strings, ...values) {
+  if (typeof strings === "string")
+    return { raw: strings };
+  let out = strings[0];
+  for (let i = 0;i < values.length; i++)
+    out += formatSubqueryValue(values[i]) + strings[i + 1];
+  return { raw: out };
+}
 function quoteInsertIdent(id) {
   return config5.dialect === "mysql" ? `\`${id.replace(/`/g, "``")}\`` : `"${id.replace(/"/g, '""')}"`;
 }
@@ -12412,13 +12420,31 @@ function validateQualifiedIdentifier(value, context) {
       throw new TypeError(`[query-builder] ${context}: identifier segment '${part}' contains characters outside [A-Za-z0-9_]`);
   }
 }
-function assertSqlFragment(fragment, context) {
-  if (fragment === null || fragment === undefined) {
-    throw new TypeError(`[query-builder] ${context}: fragment must be a SqlFragment, got ${fragment}`);
-  }
+function renderRawFragment(fragment, context) {
   if (typeof fragment === "string") {
     warnOnceBareSqlFragment(context);
+    return fragment;
   }
+  if (fragment === null || fragment === undefined)
+    throw new TypeError(`[query-builder] ${context}: fragment must be a SqlFragment, got ${fragment}`);
+  if (isRawExpression(fragment))
+    return fragment.raw;
+  if (typeof fragment === "object") {
+    const f = fragment;
+    if (typeof f.raw === "string")
+      return f.raw;
+    if (typeof f.raw === "function") {
+      const r = f.raw();
+      if (typeof r === "string")
+        return r;
+    }
+    if (typeof f.sql === "string")
+      return f.sql;
+    const s = String(fragment);
+    if (s !== "[object Object]" && s !== "[object Promise]")
+      return s;
+  }
+  throw new TypeError(`[query-builder] ${context}: cannot render this value as a SQL fragment. ` + `A Bun \`sql\`...\`\` query object cannot be converted to SQL text \u2014 pass a ` + `string, or use the exported \`raw\` helper: raw\`count(*) as c\` / raw('age > 18').`);
 }
 function warnOnceBareSqlFragment(context) {
   if (warnedSqlFragmentContexts.has(context))
@@ -12435,6 +12461,8 @@ function formatSubqueryValue(val) {
     return val ? "1" : "0";
   if (typeof val === "string")
     return `'${val.replace(/'/g, "''")}'`;
+  if (val instanceof Date)
+    return `'${val.toISOString()}'`;
   throw new TypeError(`[query-builder] subquery condition: refusing to interpolate value of type ${typeof val}`);
 }
 function buildOverClause(partitionBy, orderBy) {
@@ -13091,12 +13119,12 @@ function createQueryBuilder(state) {
         return this;
       },
       selectRaw(fragment) {
-        assertSqlFragment(fragment, "selectRaw(fragment)");
+        const frag = renderRawFragment(fragment, "selectRaw(fragment)");
         const fromIdx = text.indexOf(" FROM ");
         if (fromIdx !== -1) {
-          text = `${text.substring(0, fromIdx)}, ${String(fragment)}${text.substring(fromIdx)}`;
+          text = `${text.substring(0, fromIdx)}, ${frag}${text.substring(fromIdx)}`;
         } else {
-          text += `, ${String(fragment)}`;
+          text += `, ${frag}`;
         }
         built = null;
         return this;
@@ -13209,12 +13237,15 @@ function createQueryBuilder(state) {
         if (cols.length === 0)
           return this;
         const rendered = cols.map(renderSelectColumn);
+        const distinctMatch = /^SELECT\s+(DISTINCT(?:\s+ON\s+\([^)]*\))?\s+)/i.exec(text);
+        const distinctPrefix = distinctMatch ? distinctMatch[1] : "";
         const fromIndex = text.indexOf(" FROM ");
         if (fromIndex !== -1) {
-          text = `SELECT ${rendered.join(", ")}${text.substring(fromIndex)}`;
+          text = `SELECT ${distinctPrefix}${rendered.join(", ")}${text.substring(fromIndex)}`;
         } else {
-          text = `SELECT ${rendered.join(", ")} FROM ${table}`;
+          text = `SELECT ${distinctPrefix}${rendered.join(", ")} FROM ${table}`;
         }
+        built = null;
         return this;
       },
       addSelect(...columns2) {
@@ -13292,6 +13323,54 @@ function createQueryBuilder(state) {
             }
             return "";
           };
+          const buildJoinConstraint = (targetTbl) => {
+            if (!condition)
+              return "";
+            const frags = [];
+            const addCmp = (col, op, val) => {
+              validateIdentifier(String(col), "with() constraint column");
+              const operator = assertSafeWhereOperator(op, "with() constraint operator");
+              frags.push(`${targetTbl}.${String(col)} ${operator} ${formatSubqueryValue(val)}`);
+            };
+            const unsupported = (m) => () => {
+              throw new Error(`[query-builder] with('${relationKey}', ...): ${m} is not supported inside a constraint callback on the JOIN-based builder \u2014 apply it to the outer query, or use the model layer's eager loading. (Silently ignoring it would return wrong data.)`);
+            };
+            const constraintQb = {
+              where: (expr, op, val) => {
+                if (Array.isArray(expr))
+                  addCmp(expr[0], expr[1], expr[2]);
+                else if (expr && typeof expr === "object")
+                  for (const k of Object.keys(expr))
+                    addCmp(k, "=", expr[k]);
+                else if (op !== undefined && val !== undefined)
+                  addCmp(expr, op, val);
+                else if (op !== undefined)
+                  addCmp(expr, "=", op);
+                return constraintQb;
+              },
+              whereIn: (col, vals) => {
+                validateIdentifier(String(col), "with() constraint column");
+                frags.push(`${targetTbl}.${String(col)} IN (${vals.map(formatSubqueryValue).join(", ")})`);
+                return constraintQb;
+              },
+              whereNull: (col) => {
+                validateIdentifier(String(col), "with() constraint column");
+                frags.push(`${targetTbl}.${String(col)} IS NULL`);
+                return constraintQb;
+              },
+              whereNotNull: (col) => {
+                validateIdentifier(String(col), "with() constraint column");
+                frags.push(`${targetTbl}.${String(col)} IS NOT NULL`);
+                return constraintQb;
+              },
+              orderBy: unsupported("orderBy()"),
+              limit: unsupported("limit()"),
+              offset: unsupported("offset()"),
+              take: unsupported("take()")
+            };
+            condition(constraintQb);
+            return frags.length ? ` AND ${frags.join(" AND ")}` : "";
+          };
           const resolveTarget = () => {
             const pick = (m) => {
               const modelName = m?.[relationKey];
@@ -13336,7 +13415,7 @@ function createQueryBuilder(state) {
             const throughPk = meta.primaryKeys[throughTable] ?? "id";
             const fkInThrough = `${singularize(fromTable)}_id`;
             const fkInFinal = `${singularize(throughTable)}_id`;
-            built = sql`${ensureBuilt()} LEFT JOIN ${sql(throughTable)} ON ${sql(`${throughTable}.${fkInThrough}`)} = ${sql(`${fromTable}.${fromPk}`)} LEFT JOIN ${sql(finalTable)} ON ${sql(`${finalTable}.${fkInFinal}`)} = ${sql(`${throughTable}.${throughPk}`)}`;
+            insertJoin(`LEFT JOIN ${throughTable} ON ${throughTable}.${fkInThrough} = ${fromTable}.${fromPk} LEFT JOIN ${finalTable} ON ${finalTable}.${fkInFinal} = ${throughTable}.${throughPk}`);
             joinedTables.add(throughTable);
             joinedTables.add(finalTable);
             return finalTable;
@@ -13349,7 +13428,7 @@ function createQueryBuilder(state) {
             const childPk = meta.primaryKeys[childTable] ?? "id";
             const fkA = resolved?.fkParent ?? `${singularize(fromTable)}_id`;
             const fkB = resolved?.fkRelated ?? `${singularize(childTable)}_id`;
-            built = sql`${ensureBuilt()} LEFT JOIN ${sql(pivot)} ON ${sql(`${pivot}.${fkA}`)} = ${sql(`${fromTable}.${fromPk}`)} LEFT JOIN ${sql(childTable)} ON ${sql(`${childTable}.${childPk}`)} = ${sql(`${pivot}.${fkB}`)}`;
+            insertJoin(`LEFT JOIN ${pivot} ON ${pivot}.${fkA} = ${fromTable}.${fromPk} LEFT JOIN ${childTable} ON ${childTable}.${childPk} = ${pivot}.${fkB}${buildJoinConstraint(childTable)}`);
             joinedTables.add(pivot);
             joinedTables.add(childTable);
             return childTable;
@@ -13363,7 +13442,8 @@ function createQueryBuilder(state) {
             const morphType = `${morphName}_type`;
             const morphId = `${morphName}_id`;
             const targetFk = `${singularize(childTable)}_id`;
-            built = sql`${ensureBuilt()} LEFT JOIN ${sql(pivotTable)} ON ${sql(`${pivotTable}.${morphId}`)} = ${sql(`${fromTable}.${fromPk}`)} AND ${sql(`${pivotTable}.${morphType}`)} = ${sql(meta.tableToModel[fromTable] || fromTable)} LEFT JOIN ${sql(childTable)} ON ${sql(`${childTable}.${childPk}`)} = ${sql(`${pivotTable}.${targetFk}`)}`;
+            const morphVal = formatSubqueryValue(meta.tableToModel[fromTable] || fromTable);
+            insertJoin(`LEFT JOIN ${pivotTable} ON ${pivotTable}.${morphId} = ${fromTable}.${fromPk} AND ${pivotTable}.${morphType} = ${morphVal} LEFT JOIN ${childTable} ON ${childTable}.${childPk} = ${pivotTable}.${targetFk}`);
             joinedTables.add(pivotTable);
             joinedTables.add(childTable);
             return childTable;
@@ -13379,7 +13459,8 @@ function createQueryBuilder(state) {
             const morphType = `${morphName}_type`;
             const morphId = `${morphName}_id`;
             const relatedFk = `${singularize(relatedTable)}_id`;
-            built = sql`${ensureBuilt()} LEFT JOIN ${sql(pivotTable)} ON ${sql(`${pivotTable}.${relatedFk}`)} = ${sql(`${fromTable}.${fromPk}`)} LEFT JOIN ${sql(relatedTable)} ON ${sql(`${relatedTable}.${relatedPk}`)} = ${sql(`${pivotTable}.${morphId}`)} AND ${sql(`${pivotTable}.${morphType}`)} = ${sql(meta.tableToModel[relatedTable] || relatedTable)}`;
+            const morphVal = formatSubqueryValue(meta.tableToModel[relatedTable] || relatedTable);
+            insertJoin(`LEFT JOIN ${pivotTable} ON ${pivotTable}.${relatedFk} = ${fromTable}.${fromPk} LEFT JOIN ${relatedTable} ON ${relatedTable}.${relatedPk} = ${pivotTable}.${morphId} AND ${pivotTable}.${morphType} = ${morphVal}`);
             joinedTables.add(pivotTable);
             joinedTables.add(relatedTable);
             return relatedTable;
@@ -13388,7 +13469,7 @@ function createQueryBuilder(state) {
           if (isBt) {
             const fkInParent = `${singularize(childTable)}_id`;
             const childPk = meta.primaryKeys[childTable] ?? "id";
-            built = sql`${ensureBuilt()} LEFT JOIN ${sql(childTable)} ON ${sql(`${fromTable}.${fkInParent}`)} = ${sql(`${childTable}.${childPk}`)}`;
+            insertJoin(`LEFT JOIN ${childTable} ON ${fromTable}.${fkInParent} = ${childTable}.${childPk}${buildJoinConstraint(childTable)}`);
             joinedTables.add(childTable);
             return childTable;
           }
@@ -13398,20 +13479,15 @@ function createQueryBuilder(state) {
             const morphType = `${relationKey}_type`;
             const morphId = `${relationKey}_id`;
             const fromPk = meta.primaryKeys[fromTable] ?? "id";
-            built = sql`${ensureBuilt()} LEFT JOIN ${sql(childTable)} ON ${sql(`${childTable}.${morphId}`)} = ${sql(`${fromTable}.${fromPk}`)} AND ${sql(`${childTable}.${morphType}`)} = ${sql(meta.tableToModel[fromTable] || fromTable)}`;
+            const morphVal = formatSubqueryValue(meta.tableToModel[fromTable] || fromTable);
+            insertJoin(`LEFT JOIN ${childTable} ON ${childTable}.${morphId} = ${fromTable}.${fromPk} AND ${childTable}.${morphType} = ${morphVal}`);
             joinedTables.add(childTable);
             return childTable;
           }
           const fkInChild = `${singularize(fromTable)}_id`;
           const pk = meta.primaryKeys[fromTable] ?? "id";
-          const softDeleteCheck = addSoftDeleteCheck(childTable);
-          if (softDeleteCheck) {
-            const currentSql = String(ensureBuilt());
-            const joinCondition = `${childTable}.${fkInChild} = ${fromTable}.${pk}${softDeleteCheck}`;
-            built = sql`${sql(currentSql)} LEFT JOIN ${sql(childTable)} ON ${sql(joinCondition)}`;
-          } else {
-            built = sql`${ensureBuilt()} LEFT JOIN ${sql(childTable)} ON ${sql(`${childTable}.${fkInChild}`)} = ${sql(`${fromTable}.${pk}`)}`;
-          }
+          const extraOn = `${addSoftDeleteCheck(childTable)}${buildJoinConstraint(childTable)}`;
+          insertJoin(`LEFT JOIN ${childTable} ON ${childTable}.${fkInChild} = ${fromTable}.${pk}${extraOn}`);
           joinedTables.add(childTable);
           return childTable;
         };
@@ -13448,7 +13524,7 @@ function createQueryBuilder(state) {
             addToSelectClause(pivotColumnsStr);
           }
         }
-        text = computeSqlText(ensureBuilt());
+        built = null;
         return this;
       },
       whereHas(relation, callback) {
@@ -14058,9 +14134,9 @@ function createQueryBuilder(state) {
         return this;
       },
       whereRaw(fragment) {
-        assertSqlFragment(fragment, "whereRaw(fragment)");
+        const frag = renderRawFragment(fragment, "whereRaw(fragment)");
         const keyword = SQL_PATTERNS.WHERE.test(text) ? "AND" : "WHERE";
-        text += ` ${keyword} ${String(fragment)}`;
+        text += ` ${keyword} ${frag}`;
         built = null;
         return this;
       },
@@ -14426,8 +14502,8 @@ function createQueryBuilder(state) {
         return this;
       },
       groupByRaw(fragment) {
-        assertSqlFragment(fragment, "groupByRaw(fragment)");
-        text = SQL_PATTERNS.GROUP_BY.test(text) ? `${text}, ${String(fragment)}` : `${text} GROUP BY ${String(fragment)}`;
+        const frag = renderRawFragment(fragment, "groupByRaw(fragment)");
+        text = SQL_PATTERNS.GROUP_BY.test(text) ? `${text}, ${frag}` : `${text} GROUP BY ${frag}`;
         built = null;
         return this;
       },
@@ -14459,15 +14535,15 @@ function createQueryBuilder(state) {
         return this;
       },
       havingRaw(fragment) {
-        assertSqlFragment(fragment, "havingRaw(fragment)");
+        const frag = renderRawFragment(fragment, "havingRaw(fragment)");
         const kw = /\bHAVING\b/i.test(text) ? "AND" : "HAVING";
-        text += ` ${kw} ${String(fragment)}`;
+        text += ` ${kw} ${frag}`;
         built = null;
         return this;
       },
       orderByRaw(fragment) {
-        assertSqlFragment(fragment, "orderByRaw(fragment)");
-        text = SQL_PATTERNS.ORDER_BY.test(text) ? `${text}, ${String(fragment)}` : `${text} ORDER BY ${String(fragment)}`;
+        const frag = renderRawFragment(fragment, "orderByRaw(fragment)");
+        text = SQL_PATTERNS.ORDER_BY.test(text) ? `${text}, ${frag}` : `${text} ORDER BY ${frag}`;
         built = null;
         return this;
       },
@@ -14650,20 +14726,20 @@ function createQueryBuilder(state) {
         includeTrashed = true;
         onlyTrashed = true;
         const softDeleteColumn = config5.softDeletes?.column || "deleted_at";
-        const splice = (raw, predicate2) => {
-          const upper = raw.toUpperCase();
+        const splice = (raw2, predicate2) => {
+          const upper = raw2.toUpperCase();
           let depth = 0;
-          for (let i = 0;i < raw.length; i++) {
-            const c = raw[i];
+          for (let i = 0;i < raw2.length; i++) {
+            const c = raw2[i];
             if (c === "(")
               depth++;
             else if (c === ")")
               depth--;
-            else if (depth === 0 && upper.substring(i, i + 5) === "WHERE" && (i === 0 || /\s/.test(raw[i - 1] ?? "")) && /\s/.test(raw[i + 5] ?? "")) {
-              return `${raw.substring(0, i)}WHERE ${predicate2} AND ${raw.substring(i + 6)}`;
+            else if (depth === 0 && upper.substring(i, i + 5) === "WHERE" && (i === 0 || /\s/.test(raw2[i - 1] ?? "")) && /\s/.test(raw2[i + 5] ?? "")) {
+              return `${raw2.substring(0, i)}WHERE ${predicate2} AND ${raw2.substring(i + 6)}`;
             }
           }
-          return `${raw} WHERE ${predicate2}`;
+          return `${raw2} WHERE ${predicate2}`;
         };
         const predicate = `${table}.${softDeleteColumn} IS NOT NULL`;
         text = splice(text, predicate);
@@ -14967,13 +15043,13 @@ function createQueryBuilder(state) {
           const cacheKey = `${String(table)}|${prop}`;
           let chosen = dynamicWhereColumnCache.get(cacheKey);
           if (chosen === undefined) {
-            const raw = prop.replace(/^(?:or|and)?where/i, "");
-            if (!raw) {
+            const raw2 = prop.replace(/^(?:or|and)?where/i, "");
+            if (!raw2) {
               dynamicWhereColumnCache.set(cacheKey, "");
               chosen = "";
             } else {
-              const lowerFirst = raw.charAt(0).toLowerCase() + raw.slice(1);
-              const snake = raw.replace(/([A-Z])/g, "_$1").toLowerCase().replace(/^_/, "");
+              const lowerFirst = raw2.charAt(0).toLowerCase() + raw2.slice(1);
+              const snake = raw2.replace(/([A-Z])/g, "_$1").toLowerCase().replace(/^_/, "");
               const available = schema ? Object.keys(schema[String(table)]?.columns ?? {}) : [];
               chosen = [snake, lowerFirst, lowerFirst.toLowerCase()].find((n) => available.includes(n)) ?? snake;
               dynamicWhereColumnCache.set(cacheKey, chosen);
@@ -15363,6 +15439,10 @@ function createQueryBuilder(state) {
         returning(...cols) {
           const returningSql = `${sqlText} RETURNING ${cols.join(", ")}`;
           const q = _sql.unsafe(returningSql, params);
+          const runFirst = async () => {
+            const rows = await runWithHooks(q, "insert");
+            return Array.isArray(rows) ? rows[0] : rows;
+          };
           return {
             where: () => this,
             andWhere: () => this,
@@ -15371,7 +15451,22 @@ function createQueryBuilder(state) {
             limit: () => this,
             offset: () => this,
             toSQL: () => makeExecutableQuery(q, returningSql),
-            execute: () => runWithHooks(q, "insert")
+            execute: () => runWithHooks(q, "insert"),
+            get: () => runWithHooks(q, "insert"),
+            first: runFirst,
+            executeTakeFirst: runFirst,
+            async firstOrFail() {
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Insert with RETURNING returned no rows");
+              return row;
+            },
+            async executeTakeFirstOrThrow() {
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Insert with RETURNING returned no rows");
+              return row;
+            }
           };
         },
         toSQL() {
@@ -15410,19 +15505,27 @@ function createQueryBuilder(state) {
         returningAll() {
           const returningSql = `${sqlText} RETURNING *`;
           const q = _sql.unsafe(returningSql, params);
+          const runFirst = async () => {
+            const result = await runWithHooks(q, "insert");
+            return Array.isArray(result) ? result[0] : result;
+          };
           return {
             toSQL: () => makeExecutableQuery(q, returningSql),
             execute: () => runWithHooks(q, "insert"),
-            async executeTakeFirst() {
-              const result = await runWithHooks(q, "insert");
-              return Array.isArray(result) ? result[0] : result;
+            get: () => runWithHooks(q, "insert"),
+            first: runFirst,
+            executeTakeFirst: runFirst,
+            async firstOrFail() {
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Insert with RETURNING returned no rows");
+              return row;
             },
             async executeTakeFirstOrThrow() {
-              const result = await runWithHooks(q, "insert");
-              const first = Array.isArray(result) ? result[0] : result;
-              if (!first)
-                throw new Error("Insert with RETURNING failed");
-              return first;
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Insert with RETURNING returned no rows");
+              return row;
             }
           };
         }
@@ -15486,6 +15589,10 @@ function createQueryBuilder(state) {
         returning(...cols) {
           const retText = `${sqlText} RETURNING ${cols.join(", ")}`;
           const q = params.length > 0 ? _sql.unsafe(retText, params) : _sql.unsafe(retText);
+          const runFirst = async () => {
+            const rows = await runWithHooks(q, "update");
+            return Array.isArray(rows) ? rows[0] : rows;
+          };
           const obj = {
             where: () => obj,
             andWhere: () => obj,
@@ -15494,7 +15601,22 @@ function createQueryBuilder(state) {
             limit: () => obj,
             offset: () => obj,
             toSQL: () => makeExecutableQuery(q, retText),
-            execute: () => runWithHooks(q, "update")
+            execute: () => runWithHooks(q, "update"),
+            get: () => runWithHooks(q, "update"),
+            first: runFirst,
+            executeTakeFirst: runFirst,
+            async firstOrFail() {
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Update with RETURNING returned no rows");
+              return row;
+            },
+            async executeTakeFirstOrThrow() {
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Update with RETURNING returned no rows");
+              return row;
+            }
           };
           return obj;
         },
@@ -15593,6 +15715,10 @@ function createQueryBuilder(state) {
         returning(...cols) {
           const retText = `${sqlText} RETURNING ${cols.join(", ")}`;
           const q = delParams.length > 0 ? _sql.unsafe(retText, delParams) : _sql.unsafe(retText);
+          const runFirst = async () => {
+            const rows = await runWithHooks(q, "delete");
+            return Array.isArray(rows) ? rows[0] : rows;
+          };
           const obj = {
             where: () => obj,
             andWhere: () => obj,
@@ -15601,7 +15727,22 @@ function createQueryBuilder(state) {
             limit: () => obj,
             offset: () => obj,
             toSQL: () => makeExecutableQuery(q, retText),
-            execute: () => runWithHooks(q, "delete")
+            execute: () => runWithHooks(q, "delete"),
+            get: () => runWithHooks(q, "delete"),
+            first: runFirst,
+            executeTakeFirst: runFirst,
+            async firstOrFail() {
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Delete with RETURNING returned no rows");
+              return row;
+            },
+            async executeTakeFirstOrThrow() {
+              const row = await runFirst();
+              if (!row)
+                throw new Error("Delete with RETURNING returned no rows");
+              return row;
+            }
           };
           return obj;
         },
@@ -17953,8 +18094,8 @@ function loadPlanSnapshot(workspaceRoot, dialect) {
     return;
   }
   try {
-    const raw = readFileSync3(snapshotPath, "utf8");
-    const parsed = JSON.parse(raw);
+    const raw2 = readFileSync3(snapshotPath, "utf8");
+    const parsed = JSON.parse(raw2);
     if (parsed?.plan && Array.isArray(parsed.plan.tables) && parsed.plan.dialect) {
       return parsed.plan;
     }
@@ -18013,8 +18154,8 @@ async function generateMigration(dir, opts = {}) {
       const statePath = String(opts.state || defaultStatePath);
       if (existsSync16(statePath)) {
         try {
-          const raw = readFileSync3(statePath, "utf8");
-          const parsed = JSON.parse(raw);
+          const raw2 = readFileSync3(statePath, "utf8");
+          const parsed = JSON.parse(raw2);
           previous = parsed?.plan && parsed.plan.tables ? parsed.plan : parsed?.tables ? parsed : undefined;
           if (previous) {
             info("-- Comparing with legacy state file (will migrate to new snapshot format)");
@@ -24604,10 +24745,10 @@ class BelongsToManyRelationBuilder {
   hydrateRows(rows) {
     const fkParent = this.fkParent;
     const fkRelated = this.fkRelated;
-    return rows.map((raw) => {
+    return rows.map((raw2) => {
       const relatedRow = {};
       const pivotExtras = {};
-      for (const [k2, v2] of Object.entries(raw)) {
+      for (const [k2, v2] of Object.entries(raw2)) {
         if (k2.startsWith(BTM_RELATED_ALIAS))
           relatedRow[k2.slice(BTM_RELATED_ALIAS.length)] = v2;
         else if (k2 !== fkParent && k2 !== fkRelated)
@@ -27974,6 +28115,7 @@ export {
   relationDiagram,
   registerModel,
   registerBrowserModels,
+  raw,
   queryExplainAll,
   ping,
   parseStacksModels,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bun-query-builder",
   "type": "module",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "A simple yet performant query builder for TypeScript. Built with Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",