tempest-db-js 0.5.0 → 0.6.0

package/dist/index.cjs

@@ -14,6 +14,142 @@ function toCondNode(input) {
 function wrap(node) {
   return { [CONDITION]: true, node };
 }
+function toExprNode(operand) {
+  return isExpression(operand) ? operand.node : { kind: "value", value: operand };
+}
+function assertValueOperands(op, operands) {
+  if (operands.some(isExpression)) {
+    throw new Error(
+      `The "${op}" operator binds its operands, so it takes values, not expressions.`
+    );
+  }
+}
+function isExpression(value) {
+  return value instanceof Expression;
+}
+var Expression = class {
+  constructor(node) {
+    this.node = node;
+  }
+  node;
+  /** Compare this expression against another expression or a bound value. */
+  compare(op, operand) {
+    return wrap({ kind: "compare", left: this.node, op, right: toExprNode(operand) });
+  }
+  /** `=` (or `IS NULL` for a null value). */
+  eq(operand) {
+    return this.compare("eq", operand);
+  }
+  /** `<>` (or `IS NOT NULL` for a null value). */
+  ne(operand) {
+    return this.compare("ne", operand);
+  }
+  /** `>`. */
+  gt(operand) {
+    return this.compare("gt", operand);
+  }
+  /** `>=`. */
+  gte(operand) {
+    return this.compare("gte", operand);
+  }
+  /** `<`. */
+  lt(operand) {
+    return this.compare("lt", operand);
+  }
+  /** `<=`. */
+  lte(operand) {
+    return this.compare("lte", operand);
+  }
+  /** `LIKE` — `%` and `_` in the operand are wildcards. */
+  like(pattern) {
+    return this.compare("like", pattern);
+  }
+  /** `ILIKE` — case-insensitive **pattern** matching, wildcards included. */
+  ilike(pattern) {
+    return this.compare("ilike", pattern);
+  }
+  /** Case-insensitive equality (`lower(a) = lower(b)`), with no wildcards. */
+  ieq(operand) {
+    return this.compare("ieq", operand);
+  }
+  /**
+   * `IN (...)` over a list of values.
+   *
+   * @param values The values to test against.
+   * @returns The condition.
+   * @throws Error When an entry is an {@link Expression} — a list operand is
+   *   bound, so an expression there would be serialized as a parameter instead of
+   *   rendered as SQL.
+   */
+  in(values) {
+    assertValueOperands("in", values);
+    return this.compare("in", values);
+  }
+  /**
+   * `NOT IN (...)` over a list of values.
+   *
+   * @param values The values to exclude.
+   * @returns The condition.
+   * @throws Error When an entry is an {@link Expression} (see {@link Expression.in}).
+   */
+  notIn(values) {
+    assertValueOperands("notIn", values);
+    return this.compare("notIn", values);
+  }
+  /**
+   * `BETWEEN lo AND hi` (inclusive).
+   *
+   * @param lo The lower bound.
+   * @param hi The upper bound.
+   * @returns The condition.
+   * @throws Error When a bound is an {@link Expression} (see {@link Expression.in}).
+   */
+  between(lo, hi) {
+    assertValueOperands("between", [lo, hi]);
+    return this.compare("between", [lo, hi]);
+  }
+  /** `IS NULL` (true) / `IS NOT NULL` (false). */
+  isNull(value = true) {
+    return this.compare("isNull", value);
+  }
+};
+function col(name) {
+  return new Expression({ kind: "column", name });
+}
+function val(value) {
+  return new Expression({ kind: "value", value });
+}
+var FUNCTION_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function toArg(arg) {
+  return typeof arg === "string" ? { kind: "column", name: arg } : arg.node;
+}
+function call(name, ...args) {
+  if (!FUNCTION_NAME.test(name)) {
+    throw new Error(
+      `fn.call() takes a plain SQL function name; got ${JSON.stringify(name)}.`
+    );
+  }
+  return new Expression({ kind: "fn", name, args: args.map(toArg) });
+}
+var fn = {
+  /** `lower(x)`. */
+  lower: (arg) => call("lower", arg),
+  /** `upper(x)`. */
+  upper: (arg) => call("upper", arg),
+  /** `trim(x)`. */
+  trim: (arg) => call("trim", arg),
+  /** `length(x)`. */
+  length: (arg) => call("length", arg),
+  /** `abs(x)`. */
+  abs: (arg) => call("abs", arg),
+  /** `coalesce(a, b, ...)`. */
+  coalesce: (...args) => call("coalesce", ...args),
+  /**
+   * Any other SQL function, by name. Portability is the caller's problem —
+   * `date_trunc` is PostgreSQL, `strftime` is SQLite.
+   */
+  call
+};
 function and(...inputs) {
   return wrap({
     kind: "and",
@@ -31,6 +167,9 @@ function not(input) {
 }
 
 // src/query.ts
+function isSubquery(value) {
+  return typeof value === "object" && value !== null && value.node?.kind === "select";
+}
 var OPERATORS = [
   "eq",
   "ne",
@@ -50,8 +189,8 @@ var OPERATORS = [
   "overlaps"
 ];
 var Agg = class {
-  constructor(fn, column2) {
-    this.fn = fn;
+  constructor(fn2, column2) {
+    this.fn = fn2;
     this.column = column2;
   }
   fn;
@@ -80,12 +219,41 @@ var SelectBuilder = class _SelectBuilder {
   node;
   source;
   with(patch) {
-    return new _SelectBuilder({ ...this.node, ...patch }, this.source);
+    return new _SelectBuilder(
+      { ...this.node, ...patch },
+      this.source
+    );
   }
   /** Add a WHERE filter: the object form (keys typed) or an `and`/`or`/`not`. */
   where(input) {
     return this.with({ where: toCondNode(input) });
   }
+  /**
+   * Filter by the result of the aggregation (`HAVING`).
+   *
+   * Only available on a grouped builder — `.having()` before `.aggregate()` is a
+   * compile error, not invalid SQL at runtime. Keys are the aggregate aliases you
+   * named plus the grouped columns; `WHERE` still filters rows *before* grouping,
+   * which is a different question.
+   *
+   * @param input The condition, keyed by alias or grouped column.
+   * @returns A builder carrying the `HAVING` clause.
+   *
+   * @example
+   * ```ts
+   * select(Outbound)
+   *   .where({ status: "queued" })
+   *   .aggregate(["consumer"], { n: count() })
+   *   .having({ n: { gt: 100 } });
+   * // ... GROUP BY "consumer" HAVING COUNT(*) > $2
+   * ```
+   */
+  having(input) {
+    return new _SelectBuilder(
+      { ...this.node, having: toCondNode(input) },
+      this.source
+    );
+  }
   /** Emit `SELECT DISTINCT` — drop duplicate rows. */
   distinct() {
     return this.with({ distinct: true });
@@ -117,7 +285,15 @@ var SelectBuilder = class _SelectBuilder {
       this.source
     );
   }
-  /** Order by a column of `Full`. */
+  /**
+   * Order by a column of the model, or — on a grouped query — by an aggregate
+   * alias. Unlike `HAVING`, every dialect accepts the output alias in `ORDER BY`,
+   * so the alias is emitted as written.
+   *
+   * @param column A model column, or a projected alias.
+   * @param direction `"asc"` (default) or `"desc"`.
+   * @returns A builder carrying the ordering term.
+   */
   orderBy(column2, direction = "asc") {
     return this.with({
       orderBy: [...this.node.orderBy, { column: column2, direction }]
@@ -131,6 +307,37 @@ var SelectBuilder = class _SelectBuilder {
   offset(n) {
     return this.with({ offset: n });
   }
+  /**
+   * Narrow this SELECT to a single column and mark it as a subquery, so it can be
+   * the operand of `in` / `notIn`.
+   *
+   * The whole query — `where`, `orderBy`, `limit`, and a locking clause — is
+   * embedded in the outer statement, which is what collapses the claim-a-batch
+   * pattern into one round trip instead of selecting ids and sending them back.
+   *
+   * @param column The single column to project (checked against the model).
+   * @returns A subquery carrying that column's type.
+   *
+   * @example
+   * ```ts
+   * update(Outbound)
+   *   .set({ status: "sending", attempts: sql.raw("attempts + 1") })
+   *   .where({
+   *     id: {
+   *       in: select(Outbound)
+   *         .where({ status: "queued" })
+   *         .orderBy("nextAttemptAt")
+   *         .limit(10)
+   *         .forUpdate({ skipLocked: true })
+   *         .asSubquery("id"),
+   *     },
+   *   })
+   *   .returning();
+   * ```
+   */
+  asSubquery(column2) {
+    return { node: { ...this.node, columns: [column2] } };
+  }
   /**
    * Lock the selected rows for update (`SELECT ... FOR UPDATE`), à la
    * SQLAlchemy's `with_for_update()`.
@@ -284,8 +491,8 @@ function toDict(model, row) {
 function toJSON(model, row) {
   const columns = columnsOf(model);
   const out = {};
-  for (const [name, col] of Object.entries(columns)) {
-    out[name] = encodeValue(col, row[name] ?? null);
+  for (const [name, col2] of Object.entries(columns)) {
+    out[name] = encodeValue(col2, row[name] ?? null);
   }
   return out;
 }
@@ -296,10 +503,10 @@ function fromDict(model, data) {
   const columns = columnsOf(model);
   const out = {};
   const issues = [];
-  for (const [name, col] of Object.entries(columns)) {
+  for (const [name, col2] of Object.entries(columns)) {
     const present = name in data && data[name] !== void 0 && data[name] !== null;
     if (!present) {
-      const required = col.flags.notNull && !col.flags.hasDefault;
+      const required = col2.flags.notNull && !col2.flags.hasDefault;
       if (required) {
         issues.push(`missing required column "${name}"`);
         continue;
@@ -308,7 +515,7 @@ function fromDict(model, data) {
       continue;
     }
     try {
-      out[name] = decodeValue(col, data[name]);
+      out[name] = decodeValue(col2, data[name]);
     } catch (error) {
       issues.push(`column "${name}": ${error.message}`);
     }
@@ -359,8 +566,8 @@ function mapperFor(model) {
   const props = columnPropsOf(model);
   const names = props ? Object.fromEntries(Object.entries(props).map(([db, prop]) => [prop, db])) : null;
   const decoders = /* @__PURE__ */ new Map();
-  for (const [prop, col] of Object.entries(columnsOf(model))) {
-    const decoder = decoderFor(col.type);
+  for (const [prop, col2] of Object.entries(columnsOf(model))) {
+    const decoder = decoderFor(col2.type);
     if (decoder) decoders.set(names?.[prop] ?? prop, decoder);
   }
   const mapper = { props, decoders };
@@ -391,15 +598,15 @@ function assertWritableValues(model, values, clause) {
   const columns = columnsOf(model);
   const issues = [];
   for (const [key, value] of Object.entries(values)) {
-    const col = columns[key];
-    if (!col) {
+    const col2 = columns[key];
+    if (!col2) {
       issues.push(`${clause}: "${key}" is not a column of ${model.tablename}`);
       continue;
     }
     if (isSqlExpression(value) || isBindableScalar(value)) continue;
-    if (typeof value === "object" && STRUCTURED_KINDS.has(col.type.kind)) continue;
+    if (typeof value === "object" && STRUCTURED_KINDS.has(col2.type.kind)) continue;
     issues.push(
-      `${clause}: "${key}" got ${describeValue(value)}, which cannot be bound to a ${col.type.kind} column \u2014 use sql.raw()/sql.expr\`...\` for a SQL expression`
+      `${clause}: "${key}" got ${describeValue(value)}, which cannot be bound to a ${col2.type.kind} column \u2014 use sql.raw()/sql.expr\`...\` for a SQL expression`
     );
   }
   if (issues.length > 0) throw new ValidationError(model.tablename, issues);
@@ -755,6 +962,15 @@ var BaseDialect = class _BaseDialect {
   static insertTemplates = /* @__PURE__ */ new Map();
   /** Quoted-identifier cache (see {@link quoteId}). Shared across dialects. */
   static quotedIds = /* @__PURE__ */ new Map();
+  /**
+   * Validate a subquery operand before it is rendered, for dialects that restrict
+   * what an `IN (SELECT ...)` may contain. The default accepts everything.
+   *
+   * @param _node The subquery's AST.
+   * @throws Error When the dialect cannot execute this subquery.
+   */
+  checkSubquery(_node) {
+  }
   /**
    * The SQL operator for an array containment/overlap test.
    *
@@ -878,6 +1094,19 @@ var BaseDialect = class _BaseDialect {
     return ` ${strength}${of}${wait}`;
   }
   // ---- statements -------------------------------------------------------
+  /**
+   * Compile a SELECT.
+   *
+   * Two alias rules differ between clauses and are handled here: PostgreSQL does
+   * NOT accept a `SELECT` alias in `HAVING`, so an aggregate key is re-emitted as
+   * its expression (`COUNT(*) > $1`), a form every dialect accepts; `ORDER BY`,
+   * by contrast, accepts the output alias everywhere, so it is emitted as
+   * written.
+   *
+   * @param node The select AST.
+   * @param params The parameter collector.
+   * @returns The SQL text.
+   */
   compileSelect(node, params) {
     const names = node.names;
     let cols;
@@ -901,10 +1130,21 @@ var BaseDialect = class _BaseDialect {
     if (node.groupBy.length > 0) {
       sql2 += ` GROUP BY ${node.groupBy.map((c) => this.columnId(c, names)).join(", ")}`;
     }
+    const aggByAlias = new Map(node.aggregates.map((a) => [a.alias, a]));
+    if (node.having) {
+      const having = this.compileCondition(node.having, params, (key) => {
+        const agg = aggByAlias.get(key);
+        if (!agg) return this.columnId(key, names);
+        const inner = agg.column === "*" ? "*" : this.columnId(agg.column, names);
+        return `${agg.fn.toUpperCase()}(${inner})`;
+      });
+      if (having) sql2 += ` HAVING ${having}`;
+    }
     if (node.orderBy.length > 0) {
-      const terms = node.orderBy.map(
-        (t) => `${this.columnId(t.column, names)} ${t.direction === "desc" ? "DESC" : "ASC"}`
-      ).join(", ");
+      const terms = node.orderBy.map((t) => {
+        const id = aggByAlias.has(t.column) ? this.quoteId(t.column) : this.columnId(t.column, names);
+        return `${id} ${t.direction === "desc" ? "DESC" : "ASC"}`;
+      }).join(", ");
       sql2 += ` ORDER BY ${terms}`;
     }
     if (node.limit !== void 0) sql2 += ` LIMIT ${params.bind(node.limit)}`;
@@ -1040,7 +1280,7 @@ var BaseDialect = class _BaseDialect {
   compileUpdate(node, params) {
     const names = node.names;
     const sets = Object.entries(node.set).map(
-      ([col, value]) => `${this.columnId(col, names)} = ${this.renderValue(value, params)}`
+      ([col2, value]) => `${this.columnId(col2, names)} = ${this.renderValue(value, params)}`
     ).join(", ");
     let sql2 = `UPDATE ${this.quoteId(node.table)} SET ${sets}`;
     const where = this.compileCondition(
@@ -1133,6 +1373,83 @@ var BaseDialect = class _BaseDialect {
         const inner = this.compileCondition(node.part, params, idFor);
         return inner ? `NOT (${inner})` : "";
       }
+      case "compare": {
+        const left = this.renderExpr(node.left, params, idFor);
+        if (node.right.kind === "value") {
+          return this.compileOperator(left, node.op, node.right.value, params);
+        }
+        return this.compileExprOperator(
+          left,
+          node.op,
+          this.renderExpr(node.right, params, idFor)
+        );
+      }
+    }
+  }
+  /**
+   * Render one side of a comparison.
+   *
+   * A column reference goes through `idFor`, so an explicit `.name()` mapping and
+   * join qualification apply here exactly as they do in the object form of
+   * `where` — `col()` is not a way around them. Only a `value` node binds.
+   *
+   * @param node The expression AST.
+   * @param params The parameter collector.
+   * @param idFor The identifier resolver for the enclosing statement.
+   * @returns The SQL text of the expression.
+   */
+  renderExpr(node, params, idFor) {
+    switch (node.kind) {
+      case "column":
+        return idFor(node.name);
+      case "value":
+        return params.bind(node.value);
+      case "fn": {
+        const args = node.args.map((a) => this.renderExpr(a, params, idFor)).join(", ");
+        return `${node.name}(${args})`;
+      }
+    }
+  }
+  /**
+   * Compile a comparison whose right-hand side is another expression rather than
+   * a bound value (`total > paid`, `lower(a) = lower(b)`).
+   *
+   * The list and null operators are excluded: `IN`, `BETWEEN` and `IS NULL` take
+   * a value operand, and accepting an expression there would silently compile to
+   * something else.
+   *
+   * @param left The rendered left-hand side.
+   * @param op The operator name.
+   * @param right The rendered right-hand side.
+   * @returns The SQL text of the predicate.
+   * @throws Error When the operator needs a value operand.
+   */
+  compileExprOperator(left, op, right) {
+    switch (op) {
+      case "eq":
+        return `${left} = ${right}`;
+      case "ne":
+        return `${left} <> ${right}`;
+      case "gt":
+        return `${left} > ${right}`;
+      case "gte":
+        return `${left} >= ${right}`;
+      case "lt":
+        return `${left} < ${right}`;
+      case "lte":
+        return `${left} <= ${right}`;
+      case "like":
+        return `${left} LIKE ${right}`;
+      case "ilike":
+        return this.ilike(left, right);
+      case "ieq":
+        return `lower(${left}) = lower(${right})`;
+      case "contains":
+      case "containedBy":
+      case "overlaps":
+        return `${left} ${this.arrayOperator(op)} ${right}`;
+      default:
+        throw new Error(`The "${op}" operator takes a value operand, not an expression.`);
     }
   }
   compileOperator(id, op, operand, params) {
@@ -1175,12 +1492,33 @@ var BaseDialect = class _BaseDialect {
         throw new Error(`Unknown operator ${JSON.stringify(op)}`);
     }
   }
-  compileIn(id, values, params, negate) {
+  /**
+   * Compile `IN` / `NOT IN`, whose operand is either a value list or a
+   * single-column subquery.
+   *
+   * The subquery is rendered at the position it appears in the outer statement
+   * and shares the same parameter collector, so its own placeholders land in the
+   * right order — and it keeps its own `names` map, since the inner model may use
+   * a different naming convention than the outer one.
+   *
+   * @param id The quoted column identifier being tested.
+   * @param operand A list of values, or a {@link Subquery}.
+   * @param params The parameter collector for the statement being compiled.
+   * @param negate True for `NOT IN`.
+   * @returns The SQL text of the predicate.
+   */
+  compileIn(id, operand, params, negate) {
+    const keyword = negate ? "NOT IN" : "IN";
+    if (isSubquery(operand)) {
+      this.checkSubquery(operand.node);
+      return `${id} ${keyword} (${this.compileSelect(operand.node, params)})`;
+    }
+    const values = operand;
     if (values.length === 0) {
       return negate ? "1 = 1" : "1 = 0";
     }
     const list = values.map((v) => params.bind(v)).join(", ");
-    return `${id} ${negate ? "NOT IN" : "IN"} (${list})`;
+    return `${id} ${keyword} (${list})`;
   }
 };
 var SqliteDialect = class extends BaseDialect {
@@ -1232,6 +1570,19 @@ var MysqlDialect = class extends BaseDialect {
     mysqlQuotedIds.set(name, quoted);
     return quoted;
   }
+  /**
+   * MySQL rejects `LIMIT` inside an `IN` subquery with
+   * `ER_NOT_SUPPORTED_YET: This version of MySQL doesn't yet support
+   * 'LIMIT & IN/ALL/ANY/SOME subquery'`. Failing at compile time names the fix
+   * instead of surfacing that error from the driver at runtime.
+   */
+  checkSubquery(node) {
+    if (node.limit !== void 0 || node.offset !== void 0) {
+      throw new Error(
+        "MySQL does not support LIMIT/OFFSET inside an IN subquery. Select the ids first and pass them as a list, or wrap the subquery in a derived table."
+      );
+    }
+  }
   renderConflict(onConflict, conflictCols, nextValue, names) {
     if (onConflict.targetWhere || onConflict.updateWhere) {
       throw new Error(
@@ -1239,16 +1590,25 @@ var MysqlDialect = class extends BaseDialect {
       );
     }
     if (onConflict.update === "nothing") {
-      const col = this.columnId(onConflict.target[0] ?? "id", names);
-      return ` ON DUPLICATE KEY UPDATE ${col} = ${col}`;
+      const col2 = this.columnId(onConflict.target[0] ?? "id", names);
+      return ` ON DUPLICATE KEY UPDATE ${col2} = ${col2}`;
     }
     const assignments = conflictCols.map((c) => `${this.columnId(c, names)} = ${nextValue()}`).join(", ");
     return ` ON DUPLICATE KEY UPDATE ${assignments}`;
   }
+  /**
+   * MySQL has no `RETURNING`, so it cannot be compiled into a statement.
+   *
+   * `session.execute()` still honors `.returning()` on a **single-row INSERT** by
+   * running the insert and reading the row back by key on the same connection —
+   * that is execution, not compilation, so it never reaches here. Compiling a
+   * node with `returning` directly is an error, rather than SQL that silently
+   * returns nothing.
+   */
   compileReturning(returning) {
     if (returning === null) return "";
     throw new Error(
-      "RETURNING is not supported on MySQL \u2014 insert, then SELECT by key (e.g. LAST_INSERT_ID())."
+      "RETURNING cannot be compiled for MySQL. session.execute() reads a single-row INSERT back by key (LAST_INSERT_ID()); UPDATE/DELETE have no equivalent \u2014 run a SELECT yourself."
     );
   }
 };
@@ -1361,8 +1721,8 @@ var RecordNotFound = class extends Error {
   }
 };
 function primaryKeyOf(model) {
-  for (const [name, col] of Object.entries(columnsOf(model))) {
-    if (col.flags.primaryKey) return name;
+  for (const [name, col2] of Object.entries(columnsOf(model))) {
+    if (col2.flags.primaryKey) return name;
   }
   throw new Error(`${model.tablename} has no primary key`);
 }
@@ -1450,8 +1810,8 @@ var BaseRepository = class {
 
 // src/active-record.ts
 function primaryKeyOf2(model) {
-  for (const [name, col] of Object.entries(columnsOf(model))) {
-    if (col.flags.primaryKey) return name;
+  for (const [name, col2] of Object.entries(columnsOf(model))) {
+    if (col2.flags.primaryKey) return name;
   }
   throw new Error(`${model.tablename} has no primary key`);
 }
@@ -1787,6 +2147,18 @@ var AsyncResult = class {
   }
 };
 var savepointCounter = 0;
+function needsInsertReadBack(dialect, node) {
+  return dialect.name === "mysql" && node.kind === "insert" && node.returning !== null;
+}
+function singlePrimaryKey(model) {
+  const keys = Object.entries(columnsOf(model)).filter(([, column2]) => column2.flags.primaryKey).map(([name]) => name);
+  if (keys.length !== 1) {
+    throw new Error(
+      `${model.tablename} needs exactly one primary key to read an insert back on a dialect without RETURNING; found ${keys.length}.`
+    );
+  }
+  return keys[0];
+}
 function assertRawParams(params) {
   if (!Array.isArray(params)) {
     throw new TypeError(
@@ -1859,10 +2231,10 @@ var SyncSession = class {
     return new SyncResult(rows, result.changes);
   }
   /** Run `fn` inside a transaction: commit on success, rollback on throw. */
-  transaction(fn) {
+  transaction(fn2) {
     this.exec("BEGIN", []);
     try {
-      const out = fn(this);
+      const out = fn2(this);
       this.exec("COMMIT", []);
       return out;
     } catch (error) {
@@ -1871,12 +2243,12 @@ var SyncSession = class {
     }
   }
   /** Run `fn` inside a SAVEPOINT (nested transaction). */
-  beginNested(fn) {
+  beginNested(fn2) {
     savepointCounter += 1;
     const name = `qsp_${savepointCounter}`;
     this.exec(`SAVEPOINT ${name}`, []);
     try {
-      const out = fn(this);
+      const out = fn2(this);
       this.exec(`RELEASE ${name}`, []);
       return out;
     } catch (error) {
@@ -1974,6 +2346,11 @@ var AsyncSession = class _AsyncSession {
   }
   execute(builder) {
     const node = builder.node;
+    if (needsInsertReadBack(this.dialect, node)) {
+      return new AsyncResult(
+        this.insertAndReadBack(builder, node)
+      );
+    }
     const { sql: sql2, params } = this.dialect.compile(node);
     const inner = this.exec(sql2, params).then((result) => {
       const rows = mapRows(builder, result.rows);
@@ -1981,6 +2358,53 @@ var AsyncSession = class _AsyncSession {
     });
     return new AsyncResult(inner);
   }
+  /**
+   * Honor `.returning()` on a dialect without `RETURNING`, by inserting and then
+   * reading the row back by key.
+   *
+   * Both statements must run on **one** connection, because `LAST_INSERT_ID()` is
+   * per-connection: outside a transaction the pooled driver is reserved for the
+   * pair; inside one, the session already holds a pinned connection (a reserved
+   * driver exposes no `reserve`), so it runs there directly.
+   *
+   * @param builder The insert builder, for its source model.
+   * @param node The insert AST, whose `returning` drives the read-back.
+   * @returns The result view over the read-back row.
+   * @throws Error When the insert writes more than one row — `LAST_INSERT_ID()`
+   *   identifies only the first, and the rest are consecutive only under some
+   *   auto-increment lock modes.
+   */
+  async insertAndReadBack(builder, node) {
+    if (node.values.length !== 1) {
+      throw new Error(
+        `${this.dialect.name} has no RETURNING, and reading back a multi-row insert is not reliable \u2014 insert one row at a time, or drop .returning().`
+      );
+    }
+    const model = builder.source;
+    const pk = singlePrimaryKey(model);
+    const supplied = node.values[0][pk];
+    const readBack = select(model).where(
+      supplied === void 0 || supplied === null ? col(pk).eq(fn.call("LAST_INSERT_ID")) : { [pk]: supplied }
+    );
+    const insertSql = this.dialect.compile({ ...node, returning: null });
+    const selectSql = this.dialect.compile(
+      node.returning === "*" || node.returning === null ? readBack.node : { ...readBack.node, columns: node.returning }
+    );
+    const run = async (driver) => {
+      const scoped = new _AsyncSession(driver, this.dialect, this.logger);
+      const written = await scoped.exec(insertSql.sql, insertSql.params);
+      const read = await scoped.exec(selectSql.sql, selectSql.params);
+      const rows = read.rows.map((row) => coerceRow(model, row));
+      return new SyncResult(rows, written.changes);
+    };
+    if (!this.driver.reserve) return run(this.driver);
+    const reserved = await this.driver.reserve();
+    try {
+      return await run(reserved);
+    } finally {
+      await reserved.release();
+    }
+  }
   /** Lazily iterate result rows. Uses driver streaming when available. */
   async *stream(builder) {
     const node = builder.node;
@@ -2001,13 +2425,13 @@ var AsyncSession = class _AsyncSession {
       yield coerceOne(builder, raw);
     }
   }
-  async transaction(fn) {
+  async transaction(fn2) {
     if (this.driver.reserve) {
       const reserved = await this.driver.reserve();
       const scoped = new _AsyncSession(reserved, this.dialect, this.logger);
       try {
         await scoped.exec("BEGIN", []);
-        const out = await fn(scoped);
+        const out = await fn2(scoped);
         await scoped.exec("COMMIT", []);
         return out;
       } catch (error) {
@@ -2019,7 +2443,7 @@ var AsyncSession = class _AsyncSession {
     }
     await this.exec("BEGIN", []);
     try {
-      const out = await fn(this);
+      const out = await fn2(this);
       await this.exec("COMMIT", []);
       return out;
     } catch (error) {
@@ -2046,8 +2470,8 @@ var SyncEngine = class {
   session() {
     return new SyncSession(this.driver, getDialect("sqlite"), this.logger);
   }
-  transaction(fn) {
-    return this.session().transaction(fn);
+  transaction(fn2) {
+    return this.session().transaction(fn2);
   }
   close() {
     this.driver.close();
@@ -2069,8 +2493,8 @@ var AsyncEngine = class {
   session() {
     return new AsyncSession(this.driver, getDialect(this.dialect), this.logger);
   }
-  transaction(fn) {
-    return this.session().transaction(fn);
+  transaction(fn2) {
+    return this.session().transaction(fn2);
   }
   async close() {
     await this.driver.close();
@@ -2080,6 +2504,16 @@ var AsyncEngine = class {
     await this.close();
   }
 };
+function toAsyncDriver(driver) {
+  return {
+    async execute(sql2, params) {
+      return await driver.execute(sql2, params);
+    },
+    async close() {
+      await driver.close();
+    }
+  };
+}
 function asAsync(driver) {
   const syncIterate = driver.iterate?.bind(driver);
   return {
@@ -2558,8 +2992,8 @@ function columnNamesOf(model) {
   const map = {};
   const seen = /* @__PURE__ */ new Map();
   let renamed = false;
-  for (const [prop, col] of Object.entries(columnsOf(model))) {
-    const dbName = col.dbName ?? (strategy === "snake_case" ? toSnakeCase(prop) : prop);
+  for (const [prop, col2] of Object.entries(columnsOf(model))) {
+    const dbName = col2.dbName ?? (strategy === "snake_case" ? toSnakeCase(prop) : prop);
     const collision = seen.get(dbName);
     if (collision !== void 0) {
       throw new Error(
@@ -2600,6 +3034,7 @@ exports.BaseDialect = BaseDialect;
 exports.BaseRepository = BaseRepository;
 exports.Column = Column;
 exports.DeleteBuilder = DeleteBuilder;
+exports.Expression = Expression;
 exports.InsertBuilder = InsertBuilder;
 exports.InvalidDatabaseUrl = InvalidDatabaseUrl;
 exports.JoinBuilder = JoinBuilder;
@@ -2623,6 +3058,7 @@ exports.activeRecord = activeRecord;
 exports.and = and;
 exports.avg = avg;
 exports.belongsTo = belongsTo;
+exports.col = col;
 exports.column = column;
 exports.columnNamesOf = columnNamesOf;
 exports.columnPropsOf = columnPropsOf;
@@ -2633,13 +3069,16 @@ exports.createSyncEngine = createSyncEngine;
 exports.dbColumn = dbColumn;
 exports.del = del;
 exports.detectDialect = detectDialect;
+exports.fn = fn;
 exports.foreignKey = foreignKey;
 exports.fromDict = fromDict;
 exports.getDialect = getDialect;
 exports.hasMany = hasMany;
 exports.insert = insert;
 exports.isCondition = isCondition;
+exports.isExpression = isExpression;
 exports.isSqlExpression = isSqlExpression;
+exports.isSubquery = isSubquery;
 exports.join = join;
 exports.loadRelations = loadRelations;
 exports.max = max;
@@ -2652,11 +3091,13 @@ exports.select = select;
 exports.sql = sql;
 exports.stringify = stringify;
 exports.sum = sum;
+exports.toAsyncDriver = toAsyncDriver;
 exports.toCondNode = toCondNode;
 exports.toDict = toDict;
 exports.toJSON = toJSON;
 exports.toSnakeCase = toSnakeCase;
 exports.unique = unique;
 exports.update = update;
+exports.val = val;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map