oakbun 0.1.1 → 0.2.0

package/dist/{db-XTXH6OKV.js → db-YSUNURBB.js}

@@ -28,6 +28,14 @@ var ValidationError = class extends VelnError {
 };
 
 // src/db/sql.ts
+function buildSubquery(sql, params, col) {
+  if (!sql) throw new Error("buildSubquery: sql must not be empty");
+  return {
+    _sql: `(${sql})`,
+    _params: params,
+    _phantom: { col, type: void 0 }
+  };
+}
 var ON_CLAUSE_PATTERN = /^([\w]+)\.([\w]+)\s*=\s*([\w]+)\.([\w]+)$/;
 function validateAndQuoteOnClause(on) {
   const trimmed = on.trim();
@@ -50,6 +58,9 @@ function filterDefined(data) {
 function isWhereOp(val) {
   return typeof val === "object" && val !== null && "op" in val && typeof val["op"] === "string";
 }
+function isSubqueryResult(val) {
+  return typeof val === "object" && val !== null && "_sql" in val && "_params" in val;
+}
 function buildFieldCondition(key, condition, dialect) {
   if (!isWhereOp(condition)) {
     return { sql: `"${key}" = ?`, params: [condition] };
@@ -69,7 +80,11 @@ function buildFieldCondition(key, condition, dialect) {
     case "<=":
       return { sql: `"${key}" <= ?`, params: [op.value] };
     case "IN": {
-      const vals = op.value;
+      const inVal = op.value;
+      if (isSubqueryResult(inVal)) {
+        return { sql: `"${key}" IN ${inVal._sql}`, params: inVal._params };
+      }
+      const vals = inVal;
       if (vals.length === 0) {
         return { sql: "1 = 0", params: [] };
       }
@@ -77,7 +92,11 @@ function buildFieldCondition(key, condition, dialect) {
       return { sql: `"${key}" IN (${placeholders})`, params: vals };
     }
     case "NOT IN": {
-      const vals = op.value;
+      const inVal = op.value;
+      if (isSubqueryResult(inVal)) {
+        return { sql: `"${key}" NOT IN ${inVal._sql}`, params: inVal._params };
+      }
+      const vals = inVal;
       if (vals.length === 0) {
         return { sql: "1 = 1", params: [] };
       }
@@ -148,6 +167,37 @@ function buildInsert(tableName, data, returning = true) {
   const sql = `INSERT INTO "${tableName}" (${cols}) VALUES (${placeholders})${returning_clause}`;
   return { sql, params };
 }
+function buildInsertMany(tableName, rows, returning = true) {
+  if (rows.length === 0) {
+    throw new Error("insertMany: rows array must not be empty");
+  }
+  const columns = Object.keys(rows[0]);
+  const quotedCols = columns.map((c) => `"${c}"`).join(", ");
+  const params = [];
+  const valueClauses = [];
+  for (const row of rows) {
+    const placeholders = [];
+    for (const col of columns) {
+      const val = row[col];
+      if (val === void 0) {
+        throw new Error(`insertMany: column "${col}" has undefined value \u2014 apply defaults before calling buildInsertMany`);
+      }
+      params.push(val);
+      placeholders.push("?");
+    }
+    valueClauses.push(`(${placeholders.join(", ")})`);
+  }
+  const returning_clause = returning ? " RETURNING *" : "";
+  const sql = `INSERT INTO "${tableName}" (${quotedCols}) VALUES ${valueClauses.join(", ")}${returning_clause}`;
+  return { sql, params };
+}
+function buildSoftDeleteUpdate(tableName, col, value, where, dialect = "sqlite") {
+  const serialized = value instanceof Date ? value.toISOString() : null;
+  const { sql: whereSql, params: whereParams } = buildWhere(where, dialect);
+  const setSql = `"${col}" = ?`;
+  const sql = whereSql ? `UPDATE "${tableName}" SET ${setSql} WHERE ${whereSql}` : `UPDATE "${tableName}" SET ${setSql}`;
+  return { sql, params: [serialized, ...whereParams] };
+}
 function buildUpdate(tableName, patch, pk, pkValue) {
   const entries = filterDefined(patch);
   const sets = entries.map(([key]) => `"${key}" = ?`).join(", ");
@@ -203,11 +253,27 @@ function appendPaginationAndOrder(parts, options) {
     }
   }
 }
+function buildUnion(parts, kind, options = {}) {
+  if (parts.length < 2) {
+    throw new Error("buildUnion: at least 2 parts required");
+  }
+  const sqls = parts.map((p) => p.sql);
+  const params = parts.flatMap((p) => p.params);
+  let sql = sqls.join(` ${kind} `);
+  if (options.orderBy) {
+    sql += ` ORDER BY "${options.orderBy.col}" ${options.orderBy.dir ?? "ASC"}`;
+  }
+  if (options.limit !== void 0) {
+    sql += ` LIMIT ${Math.trunc(Math.max(0, options.limit))}`;
+  }
+  return { sql, params };
+}
 function buildSelect(tableName, conditions, options, dialect = "sqlite") {
   const selectList = buildSelectListFromOptions(options);
   const { sql: whereSql, params } = buildWhere(conditions, dialect);
+  const selectKeyword = options?.distinct ? "SELECT DISTINCT" : "SELECT";
   const parts = [
-    whereSql ? `SELECT ${selectList} FROM "${tableName}" WHERE ${whereSql}` : `SELECT ${selectList} FROM "${tableName}"`
+    whereSql ? `${selectKeyword} ${selectList} FROM "${tableName}" WHERE ${whereSql}` : `${selectKeyword} ${selectList} FROM "${tableName}"`
   ];
   if (options?.groupBy && options.groupBy.length > 0) {
     parts.push(`GROUP BY ${options.groupBy.map((c) => `"${c}"`).join(", ")}`);
@@ -260,10 +326,11 @@ var VelnDB = class {
   }
 };
 var BoundVelnDB = class _BoundVelnDB {
-  constructor(adapter, hooks, ctx, queue, queryLog) {
+  constructor(adapter, hooks, ctx, queue, queryLog, dialect = "sqlite") {
     this.hooks = hooks;
     this.ctx = ctx;
     this.queue = queue;
+    this.dialect = dialect;
     if (queryLog) {
       const log = queryLog;
       this.adapter = {
@@ -298,9 +365,11 @@ var BoundVelnDB = class _BoundVelnDB {
   hooks;
   ctx;
   queue;
+  dialect;
   /** Per-request query counter — incremented for every query() and execute() call on this instance. */
   _queryCount = 0;
   adapter;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   from(table) {
     return new SelectBuilder(this.adapter, this.hooks, this.ctx, this.queue, table, {});
   }
@@ -320,20 +389,20 @@ var BoundVelnDB = class _BoundVelnDB {
     return new JoinBuilder(this.adapter, tableName, [], [], "", []);
   }
   into(table) {
-    return new InsertBuilder(this.adapter, this.hooks, this.ctx, this.queue, table);
-  }
-  /**
-   * DataLoader-pattern relation fetch — single IN-query, no N+1.
-   * Returns a Map keyed by the foreign-key value; each entry is an array of
-   * matching child rows (for one-to-many relations).
-   *
-   * @example
-   * const posts = await db.from(postsTable).select()
-   * const authorMap = await db.loadRelation(posts, 'authorId', usersTable, 'id')
-   * // → SELECT * FROM "users" WHERE "id" IN (1, 2, 3)
-   * const withAuthors = posts.map(p => ({ ...p, author: authorMap.get(p.authorId)?.[0] ?? null }))
-   */
-  async loadRelation(parents, foreignKey, childTable, primaryKey) {
+    return new InsertBuilder(this.adapter, this.hooks, this.ctx, this.queue, table, this.dialect);
+  }
+  // Implementation
+  async loadRelation(parents, keyOrRelationName, tableOrSource, primaryKey) {
+    if (primaryKey === void 0) {
+      return this._loadRelationByName(
+        parents,
+        keyOrRelationName,
+        tableOrSource,
+        "many"
+      );
+    }
+    const foreignKey = keyOrRelationName;
+    const childTable = tableOrSource;
     const result = /* @__PURE__ */ new Map();
     if (parents.length === 0) return result;
     const ids = [...new Set(parents.map((p) => p[foreignKey]))];
@@ -349,15 +418,18 @@ var BoundVelnDB = class _BoundVelnDB {
     }
     return result;
   }
-  /**
-   * Convenience variant of loadRelation for belongs-to (many-to-one) relations.
-   * Returns Map<fkValue, TChild> — single child per key instead of an array.
-   *
-   * @example
-   * const authorMap = await db.loadRelationOne(posts, 'authorId', usersTable, 'id')
-   * const author = authorMap.get(post.authorId) ?? null
-   */
-  async loadRelationOne(parents, foreignKey, childTable, primaryKey) {
+  // Implementation
+  async loadRelationOne(parents, keyOrRelationName, tableOrSource, primaryKey) {
+    if (primaryKey === void 0) {
+      return this._loadRelationByName(
+        parents,
+        keyOrRelationName,
+        tableOrSource,
+        "one"
+      );
+    }
+    const foreignKey = keyOrRelationName;
+    const childTable = tableOrSource;
     const result = /* @__PURE__ */ new Map();
     if (parents.length === 0) return result;
     const ids = [...new Set(parents.map((p) => p[foreignKey]))];
@@ -367,6 +439,55 @@ var BoundVelnDB = class _BoundVelnDB {
     }
     return result;
   }
+  /**
+   * Shared implementation for name-based loadRelation / loadRelationOne.
+   * Reads RelationMeta from sourceTable.relations, validates the kind,
+   * and delegates to the explicit overload.
+   */
+  async _loadRelationByName(parents, relationName, sourceTable, mode) {
+    const rel = sourceTable.relations[relationName];
+    if (rel === void 0) {
+      const available = Object.keys(sourceTable.relations).join(", ") || "(none)";
+      throw new Error(
+        `Relation '${relationName}' is not defined on table '${sourceTable.name}'. Available relations: ${available}`
+      );
+    }
+    if (rel.kind === "manyToMany") {
+      throw new Error(
+        `manyToMany relations are not yet supported in loadRelation. Use a manual JOIN for relation '${relationName}' on table '${sourceTable.name}'.`
+      );
+    }
+    if (mode === "one" && rel.kind === "hasMany") {
+      throw new Error(
+        `loadRelationOne cannot be used with hasMany relation '${relationName}' on table '${sourceTable.name}'. Use loadRelation to get an array of results.`
+      );
+    }
+    const foreignTable = rel.getTable();
+    const pk = foreignTable.primaryKey;
+    if (rel.kind === "belongsTo") {
+      const ft = foreignTable;
+      const fk = rel.foreignKey;
+      if (mode === "one") {
+        return this.loadRelationOne(parents, fk, ft, pk);
+      }
+      return this.loadRelation(parents, fk, ft, pk);
+    }
+    const parentPk = sourceTable.primaryKey;
+    const result = /* @__PURE__ */ new Map();
+    if (parents.length === 0) return result;
+    const ids = [...new Set(parents.map((p) => p[parentPk]))];
+    const children = await this.from(foreignTable).where({ [rel.foreignKey]: { op: "IN", value: ids } }).select();
+    for (const child of children) {
+      const key = child[rel.foreignKey];
+      const group = result.get(key);
+      if (group) {
+        group.push(child);
+      } else {
+        result.set(key, [child]);
+      }
+    }
+    return result;
+  }
   async transaction(fn) {
     const txQueue = new RequestEventQueue();
     const result = await this.adapter.transaction(async (txAdapter) => {
@@ -411,7 +532,7 @@ function mergeWhereAnd(a, b) {
   return { AND: [a, b] };
 }
 var SelectBuilder = class _SelectBuilder {
-  constructor(adapter, hooks, ctx, queue, table, conditions, _options = {}, _rawWhere = [], _dialect = "sqlite") {
+  constructor(adapter, hooks, ctx, queue, table, conditions, _options = {}, _rawWhere = [], _dialect = "sqlite", _withRelations = [], _includeDeleted = false) {
     this.adapter = adapter;
     this.hooks = hooks;
     this.ctx = ctx;
@@ -421,6 +542,8 @@ var SelectBuilder = class _SelectBuilder {
     this._options = _options;
     this._rawWhere = _rawWhere;
     this._dialect = _dialect;
+    this._withRelations = _withRelations;
+    this._includeDeleted = _includeDeleted;
   }
   adapter;
   hooks;
@@ -431,6 +554,8 @@ var SelectBuilder = class _SelectBuilder {
   _options;
   _rawWhere;
   _dialect;
+  _withRelations;
+  _includeDeleted;
   _cloneWith(conditions, rawWhere) {
     return new _SelectBuilder(
       this.adapter,
@@ -441,7 +566,9 @@ var SelectBuilder = class _SelectBuilder {
       conditions,
       this._options,
       rawWhere ?? this._rawWhere,
-      this._dialect
+      this._dialect,
+      this._withRelations,
+      this._includeDeleted
     );
   }
   _clone(patch) {
@@ -454,7 +581,60 @@ var SelectBuilder = class _SelectBuilder {
       this.conditions,
       { ...this._options, ...patch },
       this._rawWhere,
-      this._dialect
+      this._dialect,
+      this._withRelations,
+      this._includeDeleted
+    );
+  }
+  /**
+   * Eager-load relations alongside the main query.
+   * One additional IN-query per relation — never N+1 regardless of row count.
+   *
+   * @example
+   * const posts = await db.from(postsTable).with({ author: true }).select()
+   * posts[0].author  // → User | null  (fully typed)
+   * posts[0].title   // → string       (original fields preserved)
+   */
+  with(relations) {
+    const keys = Object.keys(relations);
+    return new _SelectBuilder(
+      this.adapter,
+      this.hooks,
+      this.ctx,
+      this.queue,
+      // table type cast: the schema/relations are unchanged; only T changes in the generic
+      this.table,
+      this.conditions,
+      this._options,
+      this._rawWhere,
+      this._dialect,
+      [...this._withRelations, ...keys],
+      this._includeDeleted
+    );
+  }
+  /**
+   * Include soft-deleted rows in the query result.
+   * By default, tables with `.withSoftDelete()` automatically exclude rows
+   * where the soft-delete column is not null.
+   *
+   * Has no effect on tables without soft delete configured.
+   *
+   * @example
+   * const allUsers = await db.from(usersTable).withDeleted().select()
+   */
+  withDeleted() {
+    return new _SelectBuilder(
+      this.adapter,
+      this.hooks,
+      this.ctx,
+      this.queue,
+      this.table,
+      this.conditions,
+      this._options,
+      this._rawWhere,
+      this._dialect,
+      this._withRelations,
+      true
     );
   }
   /**
@@ -481,6 +661,17 @@ var SelectBuilder = class _SelectBuilder {
   whereRaw(sql, params) {
     return this._cloneWith(this.conditions, [...this._rawWhere, { sql, params }]);
   }
+  /**
+   * Apply SELECT DISTINCT — deduplicate rows in the result set.
+   * Combine with `.columns()` to deduplicate on specific columns.
+   *
+   * @example
+   * await db.from(usersTable).columns('name').distinct().select()
+   * // → SELECT DISTINCT "name" FROM "users"
+   */
+  distinct() {
+    return this._clone({ distinct: true });
+  }
   /** Limit the number of rows returned. Bound as a parameter — never interpolated. */
   limit(n) {
     return this._clone({ limit: n });
@@ -502,14 +693,74 @@ var SelectBuilder = class _SelectBuilder {
   page(page, size) {
     return this._clone({ limit: size, offset: (page - 1) * size });
   }
+  columns(...cols) {
+    const cloned = this._clone({ columns: cols });
+    if (cols.length === 1) {
+      return new ColumnRestrictedBuilder(cloned, cols[0]);
+    }
+    return cloned;
+  }
   /**
-   * Restrict which columns are returned.
-   * SELECT "id", "name" FROM "table" — instead of SELECT *
-   *
-   * Return type is narrowed to Pick<T, K> for full type safety.
+   * Build SELECT SQL + params without executing the query.
+   * Used internally by ColumnRestrictedBuilder.subquery().
    */
-  columns(...cols) {
-    return this._clone({ columns: cols });
+  /** Internal accessor for ColumnRestrictedBuilder / UnionBuilder — returns the adapter. */
+  _getAdapter() {
+    return this.adapter;
+  }
+  /** Internal accessor for ColumnRestrictedBuilder / UnionBuilder — returns the SQL dialect. */
+  _getDialect() {
+    return this._dialect;
+  }
+  /**
+   * Returns the effective WHERE conditions, injecting the soft-delete IS NULL
+   * filter when the table has a soft-delete column and .withDeleted() was not called.
+   */
+  _effectiveConditions() {
+    const col = this.table.softDeleteColumn;
+    if (col === null || this._includeDeleted) return this.conditions;
+    const softFilter = { [col]: { op: "IS NULL" } };
+    return mergeWhereAnd(this.conditions, softFilter);
+  }
+  _buildSelectSQL() {
+    const conditions = this._effectiveConditions();
+    if (this._rawWhere.length === 0) {
+      return buildSelect(
+        this.table.name,
+        conditions,
+        this._options,
+        this._dialect
+      );
+    }
+    const { sql: whereSql, params: whereParams } = buildWhere(
+      conditions,
+      this._dialect
+    );
+    const allWhereParts = [];
+    const allParams = [...whereParams];
+    if (whereSql) allWhereParts.push(whereSql);
+    for (const raw of this._rawWhere) {
+      allWhereParts.push(raw.sql);
+      allParams.push(...raw.params);
+    }
+    const combinedWhere = allWhereParts.join(" AND ");
+    const selectList = buildSelectListFromOptions(this._options);
+    const selectKeyword = this._options.distinct ? "SELECT DISTINCT" : "SELECT";
+    const parts = [
+      combinedWhere ? `${selectKeyword} ${selectList} FROM "${this.table.name}" WHERE ${combinedWhere}` : `${selectKeyword} ${selectList} FROM "${this.table.name}"`
+    ];
+    if (this._options.orderBy && this._options.orderBy.length > 0) {
+      const clause = this._options.orderBy.map(({ col, dir }) => `"${col}" ${dir}`).join(", ");
+      parts.push(`ORDER BY ${clause}`);
+    }
+    if (this._options.limit !== void 0 || this._options.offset !== void 0) {
+      const limitVal = this._options.limit !== void 0 ? Math.trunc(Math.max(0, this._options.limit)) : -1;
+      parts.push(`LIMIT ${limitVal}`);
+      if (this._options.offset !== void 0) {
+        parts.push(`OFFSET ${Math.trunc(Math.max(0, this._options.offset))}`);
+      }
+    }
+    return { sql: parts.join(" "), params: allParams };
   }
   /**
    * Add a GROUP BY clause. Multiple columns are comma-separated.
@@ -546,7 +797,7 @@ var SelectBuilder = class _SelectBuilder {
     }));
     const { sql, params } = buildSelect(
       this.table.name,
-      this.conditions,
+      this._effectiveConditions(),
       { ...this._options, aggregates: aggClauses },
       this._dialect
     );
@@ -584,7 +835,7 @@ var SelectBuilder = class _SelectBuilder {
     const alias = "_agg";
     const colExpr = col ? `"${col}"` : "*";
     const { sql: whereSql, params } = buildWhere(
-      this.conditions,
+      this._effectiveConditions(),
       this._dialect
     );
     let sqlStr;
@@ -610,10 +861,11 @@ var SelectBuilder = class _SelectBuilder {
   async select() {
     let finalSql;
     let finalParams;
+    const effectiveConditions = this._effectiveConditions();
     if (this._rawWhere.length === 0) {
       const { sql, params } = buildSelect(
         this.table.name,
-        this.conditions,
+        effectiveConditions,
         this._options,
         this._dialect
       );
@@ -621,7 +873,7 @@ var SelectBuilder = class _SelectBuilder {
       finalParams = params;
     } else {
       const { sql: whereSql, params: whereParams } = buildWhere(
-        this.conditions,
+        effectiveConditions,
         this._dialect
       );
       const allWhereParts = [];
@@ -660,16 +912,103 @@ var SelectBuilder = class _SelectBuilder {
       finalSql = parts.join(" ");
       finalParams = allParams;
     }
-    const rows = await this.adapter.query(finalSql, finalParams);
+    const rawRows = await this.adapter.query(finalSql, finalParams);
+    let rows;
     if (this._options.columns && this._options.columns.length > 0) {
-      return rows;
+      rows = rawRows;
+    } else {
+      rows = rawRows.map((row) => deserializeRow(this.table, row));
     }
-    return rows.map((row) => deserializeRow(this.table, row));
+    if (this._withRelations.length === 0) return rows;
+    return this._executeWith(rows);
   }
   async first() {
     const rows = await this.select();
     return rows[0] ?? null;
   }
+  // ── Eager loading — _executeWith ────────────────────────────────────────
+  async _executeWith(rows) {
+    if (rows.length === 0) return rows;
+    const mutableRows = rows.map((r) => ({ ...r }));
+    for (const relationName of this._withRelations) {
+      const meta = this.table.relations[relationName];
+      if (!meta) continue;
+      if (meta.kind === "manyToMany") {
+        throw new Error(
+          `manyToMany eager loading is not yet supported. Use loadRelation manually for relation '${relationName}'.`
+        );
+      }
+      if (meta.kind === "belongsTo") {
+        await this._attachBelongsTo(mutableRows, relationName, meta);
+      } else if (meta.kind === "hasMany") {
+        await this._attachHasMany(mutableRows, relationName, meta);
+      }
+    }
+    return mutableRows;
+  }
+  async _attachBelongsTo(rows, relationName, meta) {
+    const foreignTable = meta.getTable();
+    const fkValues = rows.map((r) => r[meta.foreignKey]).filter((v) => v !== null && v !== void 0);
+    if (fkValues.length === 0) {
+      for (const r of rows) r[relationName] = null;
+      return;
+    }
+    const uniqueFkValues = [...new Set(fkValues)];
+    const pk = foreignTable.primaryKey;
+    const baseConditions = { [pk]: { op: "IN", value: uniqueFkValues } };
+    if (foreignTable.softDeleteColumn !== null) {
+      baseConditions[foreignTable.softDeleteColumn] = { op: "IS NULL" };
+    }
+    const { sql, params } = buildSelect(
+      foreignTable.name,
+      baseConditions,
+      {},
+      this._dialect
+    );
+    const related = await this.adapter.query(sql, params);
+    const relatedMap = /* @__PURE__ */ new Map();
+    for (const r of related) {
+      relatedMap.set(r[pk], deserializeRow(foreignTable, r));
+    }
+    for (const r of rows) {
+      r[relationName] = relatedMap.get(r[meta.foreignKey]) ?? null;
+    }
+  }
+  async _attachHasMany(rows, relationName, meta) {
+    const foreignTable = meta.getTable();
+    const pk = this.table.primaryKey;
+    const pkValues = rows.map((r) => r[pk]).filter((v) => v !== null && v !== void 0);
+    if (pkValues.length === 0) {
+      for (const r of rows) r[relationName] = [];
+      return;
+    }
+    const hasManyConditions = { [meta.foreignKey]: { op: "IN", value: pkValues } };
+    if (foreignTable.softDeleteColumn !== null) {
+      hasManyConditions[foreignTable.softDeleteColumn] = { op: "IS NULL" };
+    }
+    const { sql, params } = buildSelect(
+      foreignTable.name,
+      hasManyConditions,
+      {},
+      this._dialect
+    );
+    const related = await this.adapter.query(sql, params);
+    const grouped = /* @__PURE__ */ new Map();
+    for (const pkVal of pkValues) grouped.set(pkVal, []);
+    for (const r of related) {
+      const fkVal = r[meta.foreignKey];
+      const deserialized = deserializeRow(foreignTable, r);
+      const group = grouped.get(fkVal);
+      if (group) {
+        group.push(deserialized);
+      } else {
+        grouped.set(fkVal, [deserialized]);
+      }
+    }
+    for (const r of rows) {
+      r[relationName] = grouped.get(r[pk]) ?? [];
+    }
+  }
   async update(patch) {
     const hasConditions = !(Object.keys(this.conditions).length === 0 && this._rawWhere.length === 0);
     if (!hasConditions) {
@@ -697,6 +1036,58 @@ var SelectBuilder = class _SelectBuilder {
     await this.hooks.runAfterUpdate(this.table, this.ctx, result, current, this.queue);
     return result;
   }
+  /**
+   * Update multiple rows atomically inside a single transaction.
+   * Each row must include the primary key. beforeUpdate and afterUpdate hooks
+   * run per row. If any row fails, the entire transaction rolls back.
+   *
+   * @example
+   * const updated = await db.from(usersTable).updateMany([
+   *   { id: 1, name: 'Alice Updated' },
+   *   { id: 2, role: 'admin' },
+   * ])
+   */
+  async updateMany(rows) {
+    if (rows.length === 0) return [];
+    const pk = this.table.primaryKey;
+    const results = await this.adapter.transaction(async (txAdapter) => {
+      const txQueue = new RequestEventQueue();
+      const inner = [];
+      for (const row of rows) {
+        const pkValue = row[pk];
+        if (pkValue === void 0 || pkValue === null) {
+          throw new Error(
+            `updateMany: row is missing primary key "${pk}" \u2014 every row must include the PK`
+          );
+        }
+        const selectSql = `SELECT * FROM "${this.table.name}" WHERE "${pk}" = ?`;
+        const currentRows = await txAdapter.query(selectSql, [pkValue]);
+        if (currentRows.length === 0) {
+          throw new Error(`updateMany: record with ${pk}=${String(pkValue)} not found`);
+        }
+        const current = deserializeRow(this.table, currentRows[0]);
+        const { [pk]: _pk, ...patchWithoutPk } = row;
+        const patch = patchWithoutPk;
+        const finalPatch = await this.hooks.runBeforeUpdate(this.table, this.ctx, current, patch);
+        const { sql, params } = buildUpdate(
+          this.table.name,
+          finalPatch,
+          pk,
+          pkValue
+        );
+        await txAdapter.execute(sql, params);
+        const updatedRow = {
+          ...current,
+          ...finalPatch
+        };
+        const result = deserializeRow(this.table, updatedRow);
+        await this.hooks.runAfterUpdate(this.table, this.ctx, result, current, txQueue);
+        inner.push(result);
+      }
+      return inner;
+    });
+    return results;
+  }
   async delete() {
     const hasConditions = !(Object.keys(this.conditions).length === 0 && this._rawWhere.length === 0);
     if (!hasConditions) {
@@ -714,20 +1105,235 @@ var SelectBuilder = class _SelectBuilder {
     await this.hooks.runAfterDelete(this.table, this.ctx, current, this.queue);
     return current;
   }
+  /**
+   * Soft-delete rows by setting the soft-delete column to the current timestamp.
+   * The table must have `.withSoftDelete()` configured — throws otherwise (at execute() time).
+   *
+   * Does NOT call beforeUpdate/afterUpdate hooks.
+   * Without .where(), all rows in the table are soft-deleted.
+   *
+   * @example
+   * await db.from(usersTable).softDelete().where({ id: 1 }).execute()
+   */
+  softDelete() {
+    return new SoftDeleteBuilder(this.adapter, this.table, /* @__PURE__ */ new Date(), this._dialect);
+  }
+  /**
+   * Restore soft-deleted rows by setting the soft-delete column back to null.
+   * The table must have `.withSoftDelete()` configured — throws otherwise (at execute() time).
+   *
+   * @example
+   * await db.from(usersTable).restore().where({ id: 1 }).execute()
+   */
+  restore() {
+    return new SoftDeleteBuilder(this.adapter, this.table, null, this._dialect);
+  }
+};
+var ColumnRestrictedBuilder = class _ColumnRestrictedBuilder {
+  // _builder is typed as SelectBuilder<unknown, ...> to avoid variance issues
+  // when constructing from SelectBuilder<Pick<T,K>, ...> — the runtime shape is identical.
+  constructor(_builder, _col) {
+    this._builder = _builder;
+    this._col = _col;
+  }
+  _builder;
+  _col;
+  where(conditions) {
+    return new _ColumnRestrictedBuilder(
+      this._builder.where(conditions),
+      this._col
+    );
+  }
+  limit(n) {
+    return new _ColumnRestrictedBuilder(
+      this._builder.limit(n),
+      this._col
+    );
+  }
+  orderBy(col, dir = "ASC") {
+    return new _ColumnRestrictedBuilder(
+      // _builder is SelectBuilder<unknown,...> so keyof unknown = never;
+      // col is a valid schema key at runtime — cast is safe.
+      this._builder.orderBy(col, dir),
+      this._col
+    );
+  }
+  /**
+   * Build the SQL for this query as a subquery fragment.
+   * The result can be used directly in WHERE IN / NOT IN conditions.
+   *
+   * @example
+   * const activeIds = db.from(usersTable).columns('id').where({ active: true }).subquery()
+   * // → SubqueryResult<'id', number>
+   *
+   * const posts = await db.from(postsTable)
+   *   .where({ authorId: { op: 'IN', value: activeIds } })
+   *   .select()
+   */
+  subquery() {
+    const { sql, params } = this._builder._buildSelectSQL();
+    return buildSubquery(sql, params, this._col);
+  }
+  /** Build raw SELECT SQL + params without parentheses (for UNION). */
+  _buildRawSQL() {
+    return this._builder._buildSelectSQL();
+  }
+  /**
+   * Combine this query with another same-type column query via UNION (deduplicates).
+   * Both sides must produce the same column type — enforced at compile time.
+   *
+   * @example
+   * db.from(usersTable).columns('id')
+   *   .union(db.from(adminsTable).columns('id'))
+   *   .select()
+   */
+  union(other) {
+    return new UnionBuilder(
+      [this._buildRawSQL(), other._buildRawSQL()],
+      "UNION",
+      this._builder._getAdapter(),
+      this._builder._getDialect()
+    );
+  }
+  /**
+   * Combine via UNION ALL — keeps duplicate rows.
+   */
+  unionAll(other) {
+    return new UnionBuilder(
+      [this._buildRawSQL(), other._buildRawSQL()],
+      "UNION ALL",
+      this._builder._getAdapter(),
+      this._builder._getDialect()
+    );
+  }
+};
+var SoftDeleteBuilder = class {
+  constructor(adapter, table, _value, _dialect = "sqlite") {
+    this.adapter = adapter;
+    this.table = table;
+    this._value = _value;
+    this._dialect = _dialect;
+  }
+  adapter;
+  table;
+  _value;
+  _dialect;
+  _conditions = {};
+  /**
+   * Add WHERE conditions to scope which rows are soft-deleted / restored.
+   * Multiple calls accumulate with AND.
+   * Without .where(), all rows in the table are affected.
+   */
+  where(conditions) {
+    this._conditions = mergeWhereAnd(this._conditions, conditions);
+    return this;
+  }
+  /**
+   * Execute the soft-delete or restore UPDATE.
+   * Throws if the table has no softDeleteColumn configured.
+   */
+  async execute() {
+    const col = this.table.softDeleteColumn;
+    if (col === null) {
+      throw new Error(
+        `softDelete() called on table '${this.table.name}' which has no soft delete column. Add .withSoftDelete('deletedAt') to the table definition.`
+      );
+    }
+    const { sql, params } = buildSoftDeleteUpdate(
+      this.table.name,
+      col,
+      this._value,
+      this._conditions,
+      this._dialect
+    );
+    await this.adapter.execute(sql, params);
+  }
+};
+var UnionBuilder = class _UnionBuilder {
+  constructor(_parts, _kind, _adapter, _dialect) {
+    this._parts = _parts;
+    this._kind = _kind;
+    this._adapter = _adapter;
+    this._dialect = _dialect;
+  }
+  _parts;
+  _kind;
+  _adapter;
+  _dialect;
+  _orderBy;
+  _limit;
+  /** Append another UNION (deduplicating) leg. */
+  union(other) {
+    return new _UnionBuilder(
+      [...this._parts, other._buildRawSQL()],
+      "UNION",
+      this._adapter,
+      this._dialect
+    );
+  }
+  /** Append another UNION ALL (keep duplicates) leg. */
+  unionAll(other) {
+    return new _UnionBuilder(
+      [...this._parts, other._buildRawSQL()],
+      "UNION ALL",
+      this._adapter,
+      this._dialect
+    );
+  }
+  /** Add ORDER BY to the entire UNION result. */
+  orderBy(col, dir = "ASC") {
+    const next = new _UnionBuilder(this._parts, this._kind, this._adapter, this._dialect);
+    next._orderBy = { col, dir };
+    next._limit = this._limit;
+    return next;
+  }
+  /** Add LIMIT to the entire UNION result. */
+  limit(n) {
+    const next = new _UnionBuilder(this._parts, this._kind, this._adapter, this._dialect);
+    next._orderBy = this._orderBy;
+    next._limit = n;
+    return next;
+  }
+  /** Execute the UNION query and return typed rows. */
+  async select() {
+    const { sql, params } = buildUnion(this._parts, this._kind, {
+      orderBy: this._orderBy,
+      limit: this._limit
+    });
+    return this._adapter.query(sql, params);
+  }
+  /**
+   * Build the UNION as a subquery — wrapped in parentheses.
+   * Usable in WHERE IN / NOT IN conditions.
+   *
+   * @example
+   * const adminOrModIds = db.from(usersTable).columns('id').where({ role: 'admin' })
+   *   .union(db.from(usersTable).columns('id').where({ role: 'mod' }))
+   *   .subquery()
+   */
+  subquery() {
+    const { sql, params } = buildUnion(this._parts, this._kind, {
+      orderBy: this._orderBy,
+      limit: this._limit
+    });
+    return buildSubquery(sql, params, "");
+  }
 };
 var InsertBuilder = class {
-  constructor(adapter, hooks, ctx, queue, table) {
+  constructor(adapter, hooks, ctx, queue, table, dialect = "sqlite") {
     this.adapter = adapter;
     this.hooks = hooks;
     this.ctx = ctx;
     this.queue = queue;
     this.table = table;
+    this.dialect = dialect;
   }
   adapter;
   hooks;
   ctx;
   queue;
   table;
+  dialect;
   async insert(data) {
     const originalInput = { ...data };
     let current = { ...data };
@@ -751,7 +1357,59 @@ var InsertBuilder = class {
     await this.hooks.runAfterInsert(this.table, this.ctx, result, originalInput, this.queue);
     return result;
   }
-  /** Serialize values for SQLite storage. Date → ISO string. */
+  /**
+   * Insert multiple rows in a single SQL statement.
+   * beforeInsert and afterInsert hooks run per row.
+   * Defaults (defaultFn / defaultValue) are applied per row.
+   *
+   * MySQL is not yet supported (no RETURNING *) — throws an informative error.
+   *
+   * @example
+   * const users = await db.into(usersTable).insertMany([
+   *   { name: 'Alice', email: 'alice@example.com' },
+   *   { name: 'Bob',   email: 'bob@example.com' },
+   * ])
+   */
+  async insertMany(data) {
+    if (data.length === 0) return [];
+    if (this.dialect === "mysql") {
+      throw new Error(
+        "insertMany is not yet supported for MySQL \u2014 MySQL does not support RETURNING *. Use individual insert() calls inside a transaction() instead."
+      );
+    }
+    const serializedRows = [];
+    for (const row of data) {
+      let processed = await this.hooks.runBeforeInsert(
+        this.table,
+        this.ctx,
+        { ...row }
+      );
+      for (const [field, col] of Object.entries(this.table.schema)) {
+        if (col.def.primaryKey && col.def.autoIncrement) continue;
+        if (processed[field] === void 0) {
+          if (col.def.defaultFn !== void 0) {
+            ;
+            processed[field] = col.def.defaultFn();
+          } else if (col.def.defaultValue !== void 0) {
+            ;
+            processed[field] = col.def.defaultValue;
+          }
+        }
+      }
+      const serialized = this._serializeForInsert(processed);
+      serializedRows.push(serialized);
+    }
+    const { sql, params } = buildInsertMany(this.table.name, serializedRows, true);
+    const rawRows = await this.adapter.query(sql, params);
+    const results = [];
+    for (const rawRow of rawRows) {
+      const deserialized = deserializeRow(this.table, rawRow);
+      await this.hooks.runAfterInsert(this.table, this.ctx, deserialized, {}, this.queue);
+      results.push(deserialized);
+    }
+    return results;
+  }
+  /** Serialize values for storage. Date → ISO string. Drops undefined values. */
   _serializeForInsert(data) {
     const result = {};
     for (const [key, val] of Object.entries(data)) {
@@ -882,8 +1540,11 @@ var JoinBuilder = class _JoinBuilder {
 };
 export {
   BoundVelnDB,
+  ColumnRestrictedBuilder,
   InsertBuilder,
   JoinBuilder,
   SelectBuilder,
+  SoftDeleteBuilder,
+  UnionBuilder,
   VelnDB
 };