bun-query-builder 0.1.31 → 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))
@@ -13093,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;
@@ -13211,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) {
@@ -14105,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;
       },
@@ -14473,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;
       },
@@ -14506,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;
       },
@@ -14697,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);
@@ -15014,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);
@@ -15410,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,
@@ -15418,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() {
@@ -15457,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;
             }
           };
         }
@@ -15533,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,
@@ -15541,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;
         },
@@ -15640,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,
@@ -15648,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;
         },
@@ -18000,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;
     }
@@ -18060,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)");
@@ -24651,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)
@@ -29120,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._;
@@ -29169,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);
   }
@@ -30031,7 +30125,7 @@ function getPrefix() {
 }
 var prefix = getPrefix();
 // package.json
-var version2 = "0.1.31";
+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))
@@ -13093,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;
@@ -13211,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) {
@@ -14105,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;
       },
@@ -14473,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;
       },
@@ -14506,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;
       },
@@ -14697,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);
@@ -15014,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);
@@ -15410,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,
@@ -15418,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() {
@@ -15457,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;
             }
           };
         }
@@ -15533,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,
@@ -15541,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;
         },
@@ -15640,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,
@@ -15648,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;
         },
@@ -18000,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;
     }
@@ -18060,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)");
@@ -24651,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)
@@ -28021,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.31",
+  "version": "0.1.32",
   "description": "A simple yet performant query builder for TypeScript. Built with Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",