befly 3.9.40 → 3.10.0

package/lib/sqlBuilder.ts

@@ -5,6 +5,63 @@
 
 import type { WhereConditions, WhereOperator, OrderDirection, SqlQuery, InsertData, UpdateData, SqlValue } from "../types/common.js";
 
+import { SqlCheck } from "./sqlCheck.js";
+
+const SqlBuilderError = {
+    QUOTE_IDENT_NEED_STRING: (identifier: unknown) => `quoteIdent 需要字符串类型标识符 (identifier: ${String(identifier)})`,
+    IDENT_EMPTY: "SQL 标识符不能为空",
+
+    FIELD_EXPR_NOT_ALLOWED: (field: string) => `字段包含函数/表达式，请使用 selectRaw/whereRaw (field: ${field})`,
+
+    FROM_EMPTY: "FROM 表名不能为空",
+    FROM_NEED_NON_EMPTY: (table: unknown) => `FROM 表名必须是非空字符串 (table: ${String(table)})`,
+    FROM_REQUIRED: "FROM 表名是必需的",
+    COUNT_NEED_FROM: "COUNT 需要 FROM 表名",
+
+    TABLE_REF_TOO_MANY_PARTS: (table: string) => `不支持的表引用格式（包含过多片段）。请使用 fromRaw 显式传入复杂表达式 (table: ${table})`,
+    TABLE_REF_SCHEMA_TOO_DEEP: (table: string) => `不支持的表引用格式（schema 层级过深）。请使用 fromRaw (table: ${table})`,
+    SCHEMA_QUOTE_NOT_PAIRED: (schema: string) => `schema 标识符引用不完整，请使用成对的 \`...\` 或 "..." (schema: ${schema})`,
+    TABLE_QUOTE_NOT_PAIRED: (tableName: string) => `table 标识符引用不完整，请使用成对的 \`...\` 或 "..." (table: ${tableName})`,
+
+    SELECT_FIELDS_INVALID: "SELECT 字段必须是字符串或数组",
+    SELECT_RAW_NEED_NON_EMPTY: (expr: unknown) => `selectRaw 需要非空字符串 (expr: ${String(expr)})`,
+    FROM_RAW_NEED_NON_EMPTY: (tableExpr: unknown) => `fromRaw 需要非空字符串 (tableExpr: ${String(tableExpr)})`,
+    WHERE_RAW_NEED_NON_EMPTY: (sql: unknown) => `whereRaw 需要非空字符串 (sql: ${String(sql)})`,
+    WHERE_VALUE_REQUIRED: "where(field, value) 不允许省略 value。若需传入原始 WHERE，请使用 whereRaw",
+
+    JOIN_NEED_STRING: (table: unknown, on: unknown) => `JOIN 表名和条件必须是字符串 (table: ${String(table)}, on: ${String(on)})`,
+
+    ORDER_BY_NEED_ARRAY: 'orderBy 必须是字符串数组，格式为 "字段#方向"',
+    ORDER_BY_ITEM_NEED_HASH: (item: unknown) => `orderBy 字段必须是 "字段#方向" 格式的字符串（例如："name#ASC", "id#DESC"） (item: ${String(item)})`,
+    ORDER_BY_FIELD_EMPTY: (item: string) => `orderBy 中字段名不能为空 (item: ${item})`,
+    ORDER_BY_DIR_INVALID: (direction: string) => `ORDER BY 方向必须是 ASC 或 DESC (direction: ${direction})`,
+
+    LIMIT_MUST_NON_NEGATIVE: (count: unknown) => `LIMIT 数量必须是非负数 (count: ${String(count)})`,
+    OFFSET_MUST_NON_NEGATIVE: (offset: unknown) => `OFFSET 必须是非负数 (offset: ${String(offset)})`,
+    OFFSET_COUNT_MUST_NON_NEGATIVE: (count: unknown) => `OFFSET 必须是非负数 (count: ${String(count)})`,
+
+    INSERT_NEED_TABLE: (table: unknown) => `INSERT 需要表名 (table: ${String(table)})`,
+    INSERT_NEED_DATA: (table: unknown, data: unknown) => `INSERT 需要数据 (table: ${String(table)}, data: ${JSON.stringify(data)})`,
+    INSERT_NEED_AT_LEAST_ONE_FIELD: (table: string) => `插入数据必须至少有一个字段 (table: ${table})`,
+
+    UPDATE_NEED_TABLE: "UPDATE 需要表名",
+    UPDATE_NEED_OBJECT: "UPDATE 需要数据对象",
+    UPDATE_NEED_AT_LEAST_ONE_FIELD: "更新数据必须至少有一个字段",
+    UPDATE_NEED_WHERE: "为安全起见，UPDATE 需要 WHERE 条件",
+
+    DELETE_NEED_TABLE: "DELETE 需要表名",
+    DELETE_NEED_WHERE: "为安全起见，DELETE 需要 WHERE 条件",
+
+    TO_DELETE_IN_NEED_TABLE: (table: unknown) => `toDeleteInSql 需要非空表名 (table: ${String(table)})`,
+    TO_DELETE_IN_NEED_ID_FIELD: (idField: unknown) => `toDeleteInSql 需要非空 idField (idField: ${String(idField)})`,
+    TO_DELETE_IN_NEED_IDS: "toDeleteInSql 需要 ids 数组",
+
+    TO_UPDATE_CASE_NEED_TABLE: (table: unknown) => `toUpdateCaseByIdSql 需要非空表名 (table: ${String(table)})`,
+    TO_UPDATE_CASE_NEED_ID_FIELD: (idField: unknown) => `toUpdateCaseByIdSql 需要非空 idField (idField: ${String(idField)})`,
+    TO_UPDATE_CASE_NEED_ROWS: "toUpdateCaseByIdSql 需要 rows 数组",
+    TO_UPDATE_CASE_NEED_FIELDS: "toUpdateCaseByIdSql 需要 fields 数组"
+} as const;
+
 /**
  * SQL 构建器类
  */
@@ -19,6 +76,36 @@ export class SqlBuilder {
     private _limit: number | null = null;
     private _offset: number | null = null;
     private _params: SqlValue[] = [];
+    private _quoteIdent: (identifier: string) => string;
+
+    constructor(options?: { quoteIdent?: (identifier: string) => string }) {
+        if (options && options.quoteIdent) {
+            this._quoteIdent = options.quoteIdent;
+        } else {
+            this._quoteIdent = (identifier: string) => {
+                if (typeof identifier !== "string") {
+                    throw new Error(SqlBuilderError.QUOTE_IDENT_NEED_STRING(identifier));
+                }
+
+                const trimmed = identifier.trim();
+                if (!trimmed) {
+                    throw new Error(SqlBuilderError.IDENT_EMPTY);
+                }
+
+                // 默认行为（MySQL 风格）：允许特殊字符，但对反引号进行转义
+                const escaped = trimmed.replace(/`/g, "``");
+                return `\`${escaped}\``;
+            };
+        }
+    }
+
+    private _isQuotedIdent(value: string): boolean {
+        return SqlCheck.isQuotedIdentPaired(value);
+    }
+
+    private _startsWithQuote(value: string): boolean {
+        return SqlCheck.startsWithQuote(value);
+    }
 
     /**
      * 重置构建器状态
@@ -47,16 +134,28 @@ export class SqlBuilder {
 
         field = field.trim();
 
-        // 如果是 * 或已经有着重号或包含函数，直接返回
-        if (field === "*" || field.startsWith("`") || field.includes("(")) {
+        // 防止不完整引用被误认为“已安全引用”
+        SqlCheck.assertPairedQuotedIdentIfStartsWithQuote(field, "字段标识符");
+
+        // 如果是 * 或已经被引用，直接返回
+        if (field === "*" || this._isQuotedIdent(field)) {
             return field;
         }
 
+        try {
+            SqlCheck.assertNoExprField(field);
+        } catch {
+            // 保持 SqlBuilder 报错文案统一
+            throw new Error(SqlBuilderError.FIELD_EXPR_NOT_ALLOWED(field));
+        }
+
         // 处理别名（AS关键字）
         if (field.toUpperCase().includes(" AS ")) {
             const parts = field.split(/\s+AS\s+/i);
             const fieldPart = parts[0].trim();
             const aliasPart = parts[1].trim();
+            // alias 仅允许安全标识符或已被引用
+            SqlCheck.assertSafeAlias(aliasPart);
             return `${this._escapeField(fieldPart)} AS ${aliasPart}`;
         }
 
@@ -66,16 +165,21 @@ export class SqlBuilder {
             return parts
                 .map((part) => {
                     part = part.trim();
-                    if (part === "*" || part.startsWith("`")) {
+                    if (part === "*" || this._isQuotedIdent(part)) {
                         return part;
                     }
-                    return `\`${part}\``;
+                    SqlCheck.assertPairedQuotedIdentIfStartsWithQuote(part, "字段标识符");
+                    return this._quoteIdent(part);
                 })
                 .join(".");
         }
 
         // 处理单个字段名
-        return `\`${field}\``;
+        return this._quoteIdent(field);
+    }
+
+    private _validateIdentifierPart(part: string, kind: "table" | "schema" | "alias" | "field"): void {
+        SqlCheck.assertSafeIdentifierPart(part, kind);
     }
 
     /**
@@ -88,32 +192,86 @@ export class SqlBuilder {
 
         table = table.trim();
 
-        if (table.startsWith("`")) {
+        // 防止不完整引用被误认为“已安全引用”
+        if (this._startsWithQuote(table) && !this._isQuotedIdent(table)) {
+            // 注意：这里可能是 `table` alias 的形式，整体不成对，但 namePart 可能成对。
+            // 因此这里只做“整体是单段引用”的判断，具体在后续 namePart 分支里校验。
+        }
+
+        if (this._isQuotedIdent(table)) {
             return table;
         }
 
-        // 处理表别名（表名 + 空格 + 别名）
-        if (table.includes(" ")) {
-            const parts = table.split(/\s+/);
-            if (parts.length === 2) {
-                const tableName = parts[0].trim();
-                const alias = parts[1].trim();
-                return `\`${tableName}\` ${alias}`;
+        const parts = table.split(/\s+/).filter((p) => p.length > 0);
+        if (parts.length === 0) {
+            throw new Error(SqlBuilderError.FROM_EMPTY);
+        }
+
+        if (parts.length > 2) {
+            throw new Error(SqlBuilderError.TABLE_REF_TOO_MANY_PARTS(table));
+        }
+
+        const namePart = parts[0].trim();
+        const aliasPart = parts.length === 2 ? parts[1].trim() : null;
+
+        const nameSegments = namePart.split(".");
+        if (nameSegments.length > 2) {
+            throw new Error(SqlBuilderError.TABLE_REF_SCHEMA_TOO_DEEP(table));
+        }
+
+        let escapedName = "";
+        if (nameSegments.length === 2) {
+            const schema = nameSegments[0].trim();
+            const tableName = nameSegments[1].trim();
+
+            const escapedSchema = this._isQuotedIdent(schema)
+                ? schema
+                : (() => {
+                      if (this._startsWithQuote(schema) && !this._isQuotedIdent(schema)) {
+                          throw new Error(SqlBuilderError.SCHEMA_QUOTE_NOT_PAIRED(schema));
+                      }
+                      this._validateIdentifierPart(schema, "schema");
+                      return this._quoteIdent(schema);
+                  })();
+
+            const escapedTableName = this._isQuotedIdent(tableName)
+                ? tableName
+                : (() => {
+                      if (this._startsWithQuote(tableName) && !this._isQuotedIdent(tableName)) {
+                          throw new Error(SqlBuilderError.TABLE_QUOTE_NOT_PAIRED(tableName));
+                      }
+                      this._validateIdentifierPart(tableName, "table");
+                      return this._quoteIdent(tableName);
+                  })();
+
+            escapedName = `${escapedSchema}.${escapedTableName}`;
+        } else {
+            const tableName = nameSegments[0].trim();
+
+            if (this._isQuotedIdent(tableName)) {
+                escapedName = tableName;
             } else {
-                return table;
+                if (this._startsWithQuote(tableName) && !this._isQuotedIdent(tableName)) {
+                    throw new Error(SqlBuilderError.TABLE_QUOTE_NOT_PAIRED(tableName));
+                }
+                this._validateIdentifierPart(tableName, "table");
+                escapedName = this._quoteIdent(tableName);
             }
         }
 
-        return `\`${table}\``;
+        if (aliasPart) {
+            this._validateIdentifierPart(aliasPart, "alias");
+            return `${escapedName} ${aliasPart}`;
+        }
+
+        return escapedName;
     }
 
     /**
      * 验证参数
      */
     private _validateParam(value: any): void {
-        if (value === undefined) {
-            throw new Error(`参数值不能为 undefined`);
-        }
+        SqlCheck.assertNoUndefinedParam(value, "SQL 参数值");
     }
 
     /**
@@ -253,7 +411,7 @@ export class SqlBuilder {
                     const tempParams: SqlValue[] = [];
 
                     value.forEach((condition) => {
-                        const tempBuilder = new SqlBuilder();
+                        const tempBuilder = new SqlBuilder({ quoteIdent: this._quoteIdent });
                         tempBuilder._processWhereConditions(condition);
                         if (tempBuilder._where.length > 0) {
                             orConditions.push(`(${tempBuilder._where.join(" AND ")})`);
@@ -309,8 +467,19 @@ export class SqlBuilder {
         } else if (typeof fields === "string") {
             this._select.push(this._escapeField(fields));
         } else {
-            throw new Error("SELECT 字段必须是字符串或数组");
+            throw new Error(SqlBuilderError.SELECT_FIELDS_INVALID);
+        }
+        return this;
+    }
+
+    /**
+     * SELECT 原始表达式（不做转义）
+     */
+    selectRaw(expr: string): this {
+        if (typeof expr !== "string" || !expr.trim()) {
+            throw new Error(SqlBuilderError.SELECT_RAW_NEED_NON_EMPTY(expr));
         }
+        this._select.push(expr);
         return this;
     }
 
@@ -319,26 +488,61 @@ export class SqlBuilder {
      */
     from(table: string): this {
         if (typeof table !== "string" || !table.trim()) {
-            throw new Error(`FROM 表名必须是非空字符串 (table: ${table})`);
+            throw new Error(SqlBuilderError.FROM_NEED_NON_EMPTY(table));
         }
         this._from = this._escapeTable(table.trim());
         return this;
     }
 
+    /**
+     * FROM 原始表达式（不做转义）
+     */
+    fromRaw(tableExpr: string): this {
+        if (typeof tableExpr !== "string" || !tableExpr.trim()) {
+            throw new Error(SqlBuilderError.FROM_RAW_NEED_NON_EMPTY(tableExpr));
+        }
+        this._from = tableExpr;
+        return this;
+    }
+
     /**
      * WHERE 条件
      */
-    where(condition: WhereConditions | string, value?: SqlValue): this {
-        if (typeof condition === "object" && condition !== null) {
-            this._processWhereConditions(condition);
-        } else if (value !== undefined && value !== null) {
+    where(condition: WhereConditions): this;
+    where(field: string, value: SqlValue): this;
+    where(conditionOrField: WhereConditions | string, value?: SqlValue): this {
+        if (typeof conditionOrField === "object" && conditionOrField !== null) {
+            this._processWhereConditions(conditionOrField);
+            return this;
+        }
+
+        if (typeof conditionOrField === "string") {
+            if (value === undefined) {
+                throw new Error(SqlBuilderError.WHERE_VALUE_REQUIRED);
+            }
             this._validateParam(value);
-            const escapedCondition = this._escapeField(condition as string);
+            const escapedCondition = this._escapeField(conditionOrField);
             this._where.push(`${escapedCondition} = ?`);
             this._params.push(value);
-        } else if (typeof condition === "string") {
-            this._where.push(condition);
+            return this;
         }
+
+        return this;
+    }
+
+    /**
+     * WHERE 原始片段（不做转义），可附带参数。
+     */
+    whereRaw(sql: string, params?: SqlValue[]): this {
+        if (typeof sql !== "string" || !sql.trim()) {
+            throw new Error(SqlBuilderError.WHERE_RAW_NEED_NON_EMPTY(sql));
+        }
+
+        this._where.push(sql);
+        if (params && params.length > 0) {
+            this._params.push(...params);
+        }
+
         return this;
     }
 
@@ -347,7 +551,7 @@ export class SqlBuilder {
      */
     leftJoin(table: string, on: string): this {
         if (typeof table !== "string" || typeof on !== "string") {
-            throw new Error(`JOIN 表名和条件必须是字符串 (table: ${table}, on: ${on})`);
+            throw new Error(SqlBuilderError.JOIN_NEED_STRING(table, on));
         }
         const escapedTable = this._escapeTable(table);
         this._joins.push(`LEFT JOIN ${escapedTable} ON ${on}`);
@@ -359,7 +563,7 @@ export class SqlBuilder {
      */
     rightJoin(table: string, on: string): this {
         if (typeof table !== "string" || typeof on !== "string") {
-            throw new Error(`JOIN 表名和条件必须是字符串 (table: ${table}, on: ${on})`);
+            throw new Error(SqlBuilderError.JOIN_NEED_STRING(table, on));
         }
         const escapedTable = this._escapeTable(table);
         this._joins.push(`RIGHT JOIN ${escapedTable} ON ${on}`);
@@ -371,7 +575,7 @@ export class SqlBuilder {
      */
     innerJoin(table: string, on: string): this {
         if (typeof table !== "string" || typeof on !== "string") {
-            throw new Error(`JOIN 表名和条件必须是字符串 (table: ${table}, on: ${on})`);
+            throw new Error(SqlBuilderError.JOIN_NEED_STRING(table, on));
         }
         const escapedTable = this._escapeTable(table);
         this._joins.push(`INNER JOIN ${escapedTable} ON ${on}`);
@@ -384,12 +588,12 @@ export class SqlBuilder {
      */
     orderBy(fields: string[]): this {
         if (!Array.isArray(fields)) {
-            throw new Error('orderBy 必须是字符串数组，格式为 "字段#方向"');
+            throw new Error(SqlBuilderError.ORDER_BY_NEED_ARRAY);
         }
 
         fields.forEach((item) => {
             if (typeof item !== "string" || !item.includes("#")) {
-                throw new Error(`orderBy 字段必须是 "字段#方向" 格式的字符串（例如："name#ASC", "id#DESC"） (item: ${item})`);
+                throw new Error(SqlBuilderError.ORDER_BY_ITEM_NEED_HASH(item));
             }
 
             const [fieldName, direction] = item.split("#");
@@ -397,11 +601,11 @@ export class SqlBuilder {
             const cleanDir = direction.trim().toUpperCase() as OrderDirection;
 
             if (!cleanField) {
-                throw new Error(`orderBy 中字段名不能为空 (item: ${item})`);
+                throw new Error(SqlBuilderError.ORDER_BY_FIELD_EMPTY(item));
             }
 
             if (!["ASC", "DESC"].includes(cleanDir)) {
-                throw new Error(`ORDER BY 方向必须是 ASC 或 DESC (direction: ${cleanDir})`);
+                throw new Error(SqlBuilderError.ORDER_BY_DIR_INVALID(cleanDir));
             }
 
             const escapedField = this._escapeField(cleanField);
@@ -439,12 +643,12 @@ export class SqlBuilder {
      */
     limit(count: number, offset?: number): this {
         if (typeof count !== "number" || count < 0) {
-            throw new Error(`LIMIT 数量必须是非负数 (count: ${count})`);
+            throw new Error(SqlBuilderError.LIMIT_MUST_NON_NEGATIVE(count));
         }
         this._limit = Math.floor(count);
         if (offset !== undefined && offset !== null) {
             if (typeof offset !== "number" || offset < 0) {
-                throw new Error(`OFFSET 必须是非负数 (offset: ${offset})`);
+                throw new Error(SqlBuilderError.OFFSET_MUST_NON_NEGATIVE(offset));
             }
             this._offset = Math.floor(offset);
         }
@@ -456,7 +660,7 @@ export class SqlBuilder {
      */
     offset(count: number): this {
         if (typeof count !== "number" || count < 0) {
-            throw new Error(`OFFSET 必须是非负数 (count: ${count})`);
+            throw new Error(SqlBuilderError.OFFSET_COUNT_MUST_NON_NEGATIVE(count));
         }
         this._offset = Math.floor(count);
         return this;
@@ -471,7 +675,7 @@ export class SqlBuilder {
         sql += this._select.length > 0 ? this._select.join(", ") : "*";
 
         if (!this._from) {
-            throw new Error("FROM 表名是必需的");
+            throw new Error(SqlBuilderError.FROM_REQUIRED);
         }
         sql += ` FROM ${this._from}`;
 
@@ -510,37 +714,40 @@ export class SqlBuilder {
      */
     toInsertSql(table: string, data: InsertData): SqlQuery {
         if (!table || typeof table !== "string") {
-            throw new Error(`INSERT 需要表名 (table: ${table})`);
+            throw new Error(SqlBuilderError.INSERT_NEED_TABLE(table));
         }
 
         if (!data || typeof data !== "object") {
-            throw new Error(`INSERT 需要数据 (table: ${table}, data: ${JSON.stringify(data)})`);
+            throw new Error(SqlBuilderError.INSERT_NEED_DATA(table, data));
         }
 
         const escapedTable = this._escapeTable(table);
 
         if (Array.isArray(data)) {
-            if (data.length === 0) {
-                throw new Error(`插入数据不能为空 (table: ${table})`);
-            }
-
-            const fields = Object.keys(data[0]);
-            if (fields.length === 0) {
-                throw new Error(`插入数据必须至少有一个字段 (table: ${table})`);
-            }
+            const fields = SqlCheck.assertBatchInsertRowsConsistent(data as Array<Record<string, unknown>>, { table: table });
 
             const escapedFields = fields.map((field) => this._escapeField(field));
             const placeholders = fields.map(() => "?").join(", ");
             const values = data.map(() => `(${placeholders})`).join(", ");
 
             const sql = `INSERT INTO ${escapedTable} (${escapedFields.join(", ")}) VALUES ${values}`;
-            const params = data.flatMap((row) => fields.map((field) => row[field]));
+            const params: SqlValue[] = [];
+            for (let i = 0; i < data.length; i++) {
+                const row = data[i] as Record<string, SqlValue>;
+                for (const field of fields) {
+                    params.push(row[field]);
+                }
+            }
 
             return { sql, params };
         } else {
             const fields = Object.keys(data);
             if (fields.length === 0) {
-                throw new Error(`插入数据必须至少有一个字段 (table: ${table})`);
+                throw new Error(SqlBuilderError.INSERT_NEED_AT_LEAST_ONE_FIELD(table));
+            }
+
+            for (const field of fields) {
+                this._validateParam((data as any)[field]);
             }
 
             const escapedFields = fields.map((field) => this._escapeField(field));
@@ -557,16 +764,16 @@ export class SqlBuilder {
      */
     toUpdateSql(table: string, data: UpdateData): SqlQuery {
         if (!table || typeof table !== "string") {
-            throw new Error("UPDATE 需要表名");
+            throw new Error(SqlBuilderError.UPDATE_NEED_TABLE);
         }
 
         if (!data || typeof data !== "object" || Array.isArray(data)) {
-            throw new Error("UPDATE 需要数据对象");
+            throw new Error(SqlBuilderError.UPDATE_NEED_OBJECT);
         }
 
         const fields = Object.keys(data);
         if (fields.length === 0) {
-            throw new Error("更新数据必须至少有一个字段");
+            throw new Error(SqlBuilderError.UPDATE_NEED_AT_LEAST_ONE_FIELD);
         }
 
         const escapedTable = this._escapeTable(table);
@@ -578,7 +785,7 @@ export class SqlBuilder {
         if (this._where.length > 0) {
             sql += " WHERE " + this._where.join(" AND ");
         } else {
-            throw new Error("为安全起见，UPDATE 需要 WHERE 条件");
+            throw new Error(SqlBuilderError.UPDATE_NEED_WHERE);
         }
 
         return { sql, params };
@@ -589,7 +796,7 @@ export class SqlBuilder {
      */
     toDeleteSql(table: string): SqlQuery {
         if (!table || typeof table !== "string") {
-            throw new Error("DELETE 需要表名");
+            throw new Error(SqlBuilderError.DELETE_NEED_TABLE);
         }
 
         const escapedTable = this._escapeTable(table);
@@ -598,7 +805,7 @@ export class SqlBuilder {
         if (this._where.length > 0) {
             sql += " WHERE " + this._where.join(" AND ");
         } else {
-            throw new Error("为安全起见，DELETE 需要 WHERE 条件");
+            throw new Error(SqlBuilderError.DELETE_NEED_WHERE);
         }
 
         return { sql, params: [...this._params] };
@@ -611,7 +818,7 @@ export class SqlBuilder {
         let sql = "SELECT COUNT(*) as total";
 
         if (!this._from) {
-            throw new Error("COUNT 需要 FROM 表名");
+            throw new Error(SqlBuilderError.COUNT_NEED_FROM);
         }
         sql += ` FROM ${this._from}`;
 
@@ -625,6 +832,99 @@ export class SqlBuilder {
 
         return { sql, params: [...this._params] };
     }
+
+    static toDeleteInSql(options: { table: string; idField: string; ids: SqlValue[]; quoteIdent: (identifier: string) => string }): SqlQuery {
+        if (typeof options.table !== "string" || !options.table.trim()) {
+            throw new Error(SqlBuilderError.TO_DELETE_IN_NEED_TABLE(options.table));
+        }
+        if (typeof options.idField !== "string" || !options.idField.trim()) {
+            throw new Error(SqlBuilderError.TO_DELETE_IN_NEED_ID_FIELD(options.idField));
+        }
+        if (!Array.isArray(options.ids)) {
+            throw new Error(SqlBuilderError.TO_DELETE_IN_NEED_IDS);
+        }
+        if (options.ids.length === 0) {
+            return { sql: "", params: [] };
+        }
+
+        const placeholders = options.ids.map(() => "?").join(",");
+        const sql = `DELETE FROM ${options.quoteIdent(options.table)} WHERE ${options.quoteIdent(options.idField)} IN (${placeholders})`;
+        return { sql: sql, params: [...options.ids] };
+    }
+
+    static toUpdateCaseByIdSql(options: {
+        table: string;
+        idField: string;
+        rows: Array<{ id: SqlValue; data: Record<string, SqlValue> }>;
+        fields: string[];
+        quoteIdent: (identifier: string) => string;
+        updatedAtField: string;
+        updatedAtValue: SqlValue;
+        stateField?: string;
+        stateGtZero?: boolean;
+    }): SqlQuery {
+        if (typeof options.table !== "string" || !options.table.trim()) {
+            throw new Error(SqlBuilderError.TO_UPDATE_CASE_NEED_TABLE(options.table));
+        }
+        if (typeof options.idField !== "string" || !options.idField.trim()) {
+            throw new Error(SqlBuilderError.TO_UPDATE_CASE_NEED_ID_FIELD(options.idField));
+        }
+        if (!Array.isArray(options.rows)) {
+            throw new Error(SqlBuilderError.TO_UPDATE_CASE_NEED_ROWS);
+        }
+        if (options.rows.length === 0) {
+            return { sql: "", params: [] };
+        }
+        if (!Array.isArray(options.fields)) {
+            throw new Error(SqlBuilderError.TO_UPDATE_CASE_NEED_FIELDS);
+        }
+        if (options.fields.length === 0) {
+            return { sql: "", params: [] };
+        }
+
+        const ids: SqlValue[] = options.rows.map((r) => r.id);
+        const placeholders = ids.map(() => "?").join(",");
+
+        const setSqlList: string[] = [];
+        const args: SqlValue[] = [];
+
+        const quotedId = options.quoteIdent(options.idField);
+
+        for (const field of options.fields) {
+            const whenList: string[] = [];
+
+            for (const row of options.rows) {
+                if (!(field in row.data)) {
+                    continue;
+                }
+
+                whenList.push("WHEN ? THEN ?");
+                args.push(row.id);
+                args.push(row.data[field]);
+            }
+
+            if (whenList.length === 0) {
+                continue;
+            }
+
+            const quotedField = options.quoteIdent(field);
+            setSqlList.push(`${quotedField} = CASE ${quotedId} ${whenList.join(" ")} ELSE ${quotedField} END`);
+        }
+
+        setSqlList.push(`${options.quoteIdent(options.updatedAtField)} = ?`);
+        args.push(options.updatedAtValue);
+
+        for (const id of ids) {
+            args.push(id);
+        }
+
+        let sql = `UPDATE ${options.quoteIdent(options.table)} SET ${setSqlList.join(", ")} WHERE ${quotedId} IN (${placeholders})`;
+        if (options.stateGtZero && options.stateField) {
+            sql += ` AND ${options.quoteIdent(options.stateField)} > 0`;
+        }
+
+        return { sql: sql, params: args };
+    }
 }
 
 /**