befly 3.20.11 → 3.21.0

package/lib/sqlBuilder.js

@@ -0,0 +1,714 @@
+/**
+ * SQL 构造器 - JavaScript 版本
+ * 提供链式 API 构建 SQL 查询
+ */
+
+import { assertBatchInsertRowsConsistent, assertNoUndefinedParam, escapeField, escapeTable, normalizeLimitValue, normalizeOffsetValue, resolveQuoteIdent, validateParam } from "./dbUtil.js";
+import { isNonEmptyString, isString } from "../utils/is.js";
+
+function createModel() {
+    return {
+        select: [],
+        from: null,
+        where: { type: "group", join: "AND", items: [] },
+        joins: [],
+        orderBy: [],
+        limit: null,
+        offset: null
+    };
+}
+
+/**
+ * SQL 构建器类
+ */
+export class SqlBuilder {
+    _model;
+    _quoteIdent;
+
+    constructor(options = {}) {
+        this._quoteIdent = resolveQuoteIdent(options);
+        this._model = createModel();
+    }
+
+    /**
+     * 重置构建器状态
+     */
+    reset() {
+        this._model = createModel();
+        return this;
+    }
+
+    _appendWhereNode(root, node) {
+        if (node) {
+            root.items.push(node);
+        }
+    }
+
+    _buildArrayOperatorNode(fieldName, operator, value, errorFactory, emptyMessage) {
+        if (!Array.isArray(value)) {
+            throw new Error(errorFactory(operator), {
+                cause: null,
+                code: "validation"
+            });
+        }
+        if (value.length === 0) {
+            throw new Error(emptyMessage, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        return { type: "op", field: fieldName, operator: operator, value: value };
+    }
+
+    _buildRangeOrNullOperatorNode(fieldName, operator, value) {
+        if (operator === "$between" || operator === "$notBetween") {
+            if (Array.isArray(value) && value.length === 2) {
+                return { type: "op", field: fieldName, operator: operator, value: value };
+            }
+            return null;
+        }
+
+        if (value === true) {
+            return { type: "op", field: fieldName, operator: operator, value: value };
+        }
+
+        return null;
+    }
+
+    _buildOperatorNode(fieldName, operator, value) {
+        switch (operator) {
+            case "$in":
+                return this._buildArrayOperatorNode(fieldName, operator, value, (currentOperator) => `$in 操作符的值必须是数组 (operator: ${currentOperator})`, "$in 操作符的数组不能为空。提示：空数组会导致查询永远不匹配任何记录，这通常不是预期行为。请检查查询条件或移除该字段。");
+            case "$nin":
+            case "$notIn":
+                return this._buildArrayOperatorNode(fieldName, operator, value, (currentOperator) => `$nin/$notIn 操作符的值必须是数组 (operator: ${currentOperator})`, "$nin/$notIn 操作符的数组不能为空。提示：空数组会导致查询匹配所有记录，这通常不是预期行为。请检查查询条件或移除该字段。");
+            case "$between":
+            case "$notBetween":
+            case "$null":
+            case "$notNull":
+                return this._buildRangeOrNullOperatorNode(fieldName, operator, value);
+            case "$like":
+            case "like":
+            case "$leftLike":
+            case "leftLike":
+            case "$rightLike":
+            case "rightLike":
+                if (isString(value) && value.trim() === "") {
+                    return null;
+                }
+                validateParam(value);
+                return { type: "op", field: fieldName, operator: operator, value: value };
+            default:
+                validateParam(value);
+                return { type: "op", field: fieldName, operator: operator, value: value };
+        }
+    }
+
+    _appendFieldCondition(group, key, value) {
+        if (key.includes("$")) {
+            const lastDollarIndex = key.lastIndexOf("$");
+            this._appendWhereNode(group, this._buildOperatorNode(key.substring(0, lastDollarIndex), `$${key.substring(lastDollarIndex + 1)}`, value));
+            return;
+        }
+
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            for (const [operator, operatorValue] of Object.entries(value)) {
+                this._appendWhereNode(group, this._buildOperatorNode(key, operator, operatorValue));
+            }
+            return;
+        }
+
+        this._appendWhereNode(group, this._buildOperatorNode(key, "=", value));
+    }
+
+    _appendAndConditions(group, value) {
+        if (!Array.isArray(value)) {
+            return;
+        }
+
+        for (const condition of value) {
+            if (!condition || typeof condition !== "object" || Array.isArray(condition)) {
+                continue;
+            }
+
+            const sub = this._parseWhereObject(condition);
+            if (sub.items.length === 0) {
+                continue;
+            }
+
+            if (sub.join === "AND") {
+                for (const item of sub.items) {
+                    group.items.push(item);
+                }
+                continue;
+            }
+
+            group.items.push(sub);
+        }
+    }
+
+    _appendOrConditions(group, value) {
+        if (!Array.isArray(value)) {
+            return;
+        }
+
+        const orGroup = { type: "group", join: "OR", items: [] };
+        for (const condition of value) {
+            if (!condition || typeof condition !== "object" || Array.isArray(condition)) {
+                continue;
+            }
+
+            const sub = this._parseWhereObject(condition);
+            if (sub.items.length > 0) {
+                orGroup.items.push(sub);
+            }
+        }
+
+        if (orGroup.items.length > 0) {
+            group.items.push(orGroup);
+        }
+    }
+
+    _parseWhereObject(whereObj) {
+        if (!whereObj || typeof whereObj !== "object") {
+            return { type: "group", join: "AND", items: [] };
+        }
+
+        const group = { type: "group", join: "AND", items: [] };
+
+        for (const [key, value] of Object.entries(whereObj)) {
+            if (value === undefined) {
+                continue;
+            }
+
+            if (key === "$and") {
+                this._appendAndConditions(group, value);
+                continue;
+            }
+
+            if (key === "$or") {
+                this._appendOrConditions(group, value);
+                continue;
+            }
+
+            this._appendFieldCondition(group, key, value);
+        }
+
+        return group;
+    }
+
+    _pushWhereParams(target, source) {
+        for (const param of source) {
+            target.push(param);
+        }
+    }
+
+    _compileOperatorNode(node) {
+        const escapedField = escapeField(node.field, this._quoteIdent);
+
+        if (node.operator === "$ne" || node.operator === "$not") {
+            validateParam(node.value);
+            return { sql: `${escapedField} != ?`, params: [node.value] };
+        }
+
+        if (node.operator === "$in") {
+            return {
+                sql: `${escapedField} IN (${node.value.map(() => "?").join(",")})`,
+                params: node.value.slice()
+            };
+        }
+
+        if (node.operator === "$nin" || node.operator === "$notIn") {
+            return {
+                sql: `${escapedField} NOT IN (${node.value.map(() => "?").join(",")})`,
+                params: node.value.slice()
+            };
+        }
+
+        if (node.operator === "$like" || node.operator === "like") {
+            validateParam(node.value);
+            return { sql: `${escapedField} LIKE ?`, params: [`%${String(node.value)}%`] };
+        }
+
+        if (node.operator === "$leftLike" || node.operator === "leftLike") {
+            validateParam(node.value);
+            return { sql: `${escapedField} LIKE ?`, params: [`%${String(node.value)}`] };
+        }
+
+        if (node.operator === "$rightLike" || node.operator === "rightLike") {
+            validateParam(node.value);
+            return { sql: `${escapedField} LIKE ?`, params: [`${String(node.value)}%`] };
+        }
+
+        if (node.operator === "$notLike") {
+            validateParam(node.value);
+            return { sql: `${escapedField} NOT LIKE ?`, params: [node.value] };
+        }
+
+        if (node.operator === "$gt") {
+            validateParam(node.value);
+            return { sql: `${escapedField} > ?`, params: [node.value] };
+        }
+
+        if (node.operator === "$gte") {
+            validateParam(node.value);
+            return { sql: `${escapedField} >= ?`, params: [node.value] };
+        }
+
+        if (node.operator === "$lt") {
+            validateParam(node.value);
+            return { sql: `${escapedField} < ?`, params: [node.value] };
+        }
+
+        if (node.operator === "$lte") {
+            validateParam(node.value);
+            return { sql: `${escapedField} <= ?`, params: [node.value] };
+        }
+
+        if (node.operator === "$between") {
+            return { sql: `${escapedField} BETWEEN ? AND ?`, params: [node.value[0], node.value[1]] };
+        }
+
+        if (node.operator === "$notBetween") {
+            return { sql: `${escapedField} NOT BETWEEN ? AND ?`, params: [node.value[0], node.value[1]] };
+        }
+
+        if (node.operator === "$null") {
+            return { sql: `${escapedField} IS NULL`, params: [] };
+        }
+
+        if (node.operator === "$notNull") {
+            return { sql: `${escapedField} IS NOT NULL`, params: [] };
+        }
+
+        validateParam(node.value);
+        return { sql: `${escapedField} = ?`, params: [node.value] };
+    }
+
+    _compileWhereNode(node) {
+        if (!node) {
+            return { sql: "", params: [] };
+        }
+
+        if (node.type === "raw") {
+            return { sql: node.sql, params: Array.isArray(node.params) ? node.params.slice() : [] };
+        }
+
+        if (node.type === "op") {
+            return this._compileOperatorNode(node);
+        }
+
+        if (node.type !== "group" || !node.items || node.items.length === 0) {
+            return { sql: "", params: [] };
+        }
+
+        const parts = [];
+        const params = [];
+
+        for (const item of node.items) {
+            const built = this._compileWhereNode(item);
+            if (!built.sql) {
+                continue;
+            }
+
+            let clause = built.sql;
+            if (node.join === "OR") {
+                clause = `(${clause})`;
+            } else if (item.type === "group" && item.join === "OR") {
+                clause = `(${clause})`;
+            }
+
+            parts.push(clause);
+            this._pushWhereParams(params, built.params);
+        }
+
+        return { sql: parts.join(` ${node.join} `), params: params };
+    }
+
+    /**
+     * 获取 WHERE 条件（供 DbHelper 使用）
+     */
+    getWhereConditions() {
+        const result = this._compileWhereNode(this._model.where);
+        return { sql: result.sql, params: result.params };
+    }
+
+    /**
+     * SELECT 字段
+     */
+    select(fields = "*") {
+        if (Array.isArray(fields)) {
+            for (const field of fields) {
+                this._model.select.push({ type: "field", value: field });
+            }
+            return this;
+        }
+
+        if (isString(fields)) {
+            this._model.select.push({ type: "field", value: fields });
+        }
+        return this;
+    }
+
+    /**
+     * SELECT 原始表达式（不做转义）
+     */
+    selectRaw(expr) {
+        this._model.select.push({ type: "raw", value: expr });
+        return this;
+    }
+
+    /**
+     * FROM 表名
+     */
+    from(table) {
+        this._model.from = { type: "table", value: table.trim() };
+        return this;
+    }
+
+    /**
+     * FROM 原始表达式（不做转义）
+     */
+    fromRaw(tableExpr) {
+        this._model.from = { type: "raw", value: tableExpr.trim() };
+        return this;
+    }
+
+    /**
+     * WHERE 条件
+     */
+    where(conditionOrField, value) {
+        if (conditionOrField && typeof conditionOrField === "object" && !Array.isArray(conditionOrField)) {
+            const node = this._parseWhereObject(conditionOrField);
+            if (node.items.length > 0) {
+                this._model.where.items.push(node);
+            }
+            return this;
+        }
+
+        if (isString(conditionOrField)) {
+            this._appendWhereNode(this._model.where, this._buildOperatorNode(conditionOrField, "=", value));
+        }
+        return this;
+    }
+
+    /**
+     * WHERE 原始片段（不做转义），可附带参数。
+     */
+    whereRaw(sql, params) {
+        const paramList = Array.isArray(params) ? params : [];
+        for (const param of paramList) {
+            validateParam(param);
+        }
+
+        this._model.where.items.push({ type: "raw", sql: sql, params: paramList });
+        return this;
+    }
+
+    /**
+     * LEFT JOIN
+     */
+    leftJoin(table, on) {
+        this._model.joins.push({ type: "left", table: table, on: on });
+        return this;
+    }
+
+    /**
+     * ORDER BY
+     * @param fields - 格式为 ["field#ASC", "field2#DESC"]
+     */
+    orderBy(fields) {
+        for (const item of fields) {
+            if (!isString(item) || !item.includes("#")) {
+                throw new Error(`orderBy 字段必须是 "字段#方向" 格式的字符串（例如："name#ASC", "id#DESC"） (item: ${String(item)})`, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+
+            const parts = item.split("#");
+            if (parts.length !== 2) {
+                throw new Error(`orderBy 字段必须是 "字段#方向" 格式的字符串（例如："name#ASC", "id#DESC"） (item: ${String(item)})`, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+
+            const cleanField = parts[0].trim();
+            const cleanDir = parts[1].trim().toUpperCase();
+
+            if (!cleanField) {
+                throw new Error(`orderBy 中字段名不能为空 (item: ${item})`, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+
+            if (!["ASC", "DESC"].includes(cleanDir)) {
+                throw new Error(`ORDER BY 方向必须是 ASC 或 DESC (direction: ${cleanDir})`, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+
+            this._model.orderBy.push({ field: cleanField, dir: cleanDir });
+        }
+        return this;
+    }
+
+    /**
+     * LIMIT
+     */
+    limit(count, offset) {
+        const result = normalizeLimitValue(count, offset);
+        this._model.limit = result.limitValue;
+        this._model.offset = result.offsetValue;
+        return this;
+    }
+
+    /**
+     * OFFSET
+     */
+    offset(count) {
+        const offsetValue = normalizeOffsetValue(count);
+        this._model.offset = offsetValue;
+        return this;
+    }
+
+    /**
+     * 构建 SELECT 查询
+     */
+    toSelectSql() {
+        const selectSql =
+            this._model.select.length > 0
+                ? this._model.select
+                      .map((item) => {
+                          if (item.type === "raw") {
+                              return item.value;
+                          }
+                          return escapeField(item.value, this._quoteIdent);
+                      })
+                      .join(", ")
+                : "*";
+
+        const params = [];
+        const fromSql = this._model.from.type === "raw" ? this._model.from.value : escapeTable(this._model.from.value, this._quoteIdent);
+        let sql = `SELECT ${selectSql} FROM ${fromSql}`;
+
+        if (this._model.joins.length > 0) {
+            sql += ` ${this._model.joins.map((join) => `${join.type.toUpperCase()} JOIN ${escapeTable(join.table, this._quoteIdent)} ON ${join.on}`).join(" ")}`;
+        }
+
+        const whereResult = this._compileWhereNode(this._model.where);
+        if (whereResult.sql) {
+            sql += ` WHERE ${whereResult.sql}`;
+            for (const param of whereResult.params) {
+                params.push(param);
+            }
+        }
+
+        if (this._model.orderBy.length > 0) {
+            sql += ` ORDER BY ${this._model.orderBy.map((item) => `${escapeField(item.field, this._quoteIdent)} ${item.dir}`).join(", ")}`;
+        }
+
+        if (this._model.limit !== null) {
+            sql += ` LIMIT ${this._model.limit}`;
+            if (this._model.offset !== null) {
+                sql += ` OFFSET ${this._model.offset}`;
+            }
+        }
+
+        return { sql: sql, params: params };
+    }
+
+    /**
+     * 构建 INSERT 查询
+     */
+    toInsertSql(table, data) {
+        const escapedTable = escapeTable(table, this._quoteIdent);
+
+        if (Array.isArray(data)) {
+            const fields = assertBatchInsertRowsConsistent(data, { table: table });
+            const escapedFields = fields.map((field) => escapeField(field, this._quoteIdent));
+            const placeholders = fields.map(() => "?").join(", ");
+            const values = data.map(() => `(${placeholders})`).join(", ");
+            const params = [];
+
+            for (const row of data) {
+                for (const field of fields) {
+                    const value = row[field];
+                    validateParam(value);
+                    params.push(value);
+                }
+            }
+
+            return {
+                sql: `INSERT INTO ${escapedTable} (${escapedFields.join(", ")}) VALUES ${values}`,
+                params: params
+            };
+        }
+
+        const fields = Object.keys(data);
+        if (fields.length === 0) {
+            throw new Error(`插入数据必须至少有一个字段 (table: ${table})`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        for (const field of fields) {
+            validateParam(data[field]);
+        }
+
+        const escapedFields = fields.map((field) => escapeField(field, this._quoteIdent));
+        const placeholders = fields.map(() => "?").join(", ");
+        const params = [];
+        for (const field of fields) {
+            params.push(data[field]);
+        }
+
+        return {
+            sql: `INSERT INTO ${escapedTable} (${escapedFields.join(", ")}) VALUES (${placeholders})`,
+            params: params
+        };
+    }
+
+    /**
+     * 构建 UPDATE 查询
+     */
+    toUpdateSql(table, data) {
+        const fields = Object.keys(data);
+        if (fields.length === 0) {
+            throw new Error("更新数据必须至少有一个字段", {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const params = [];
+        for (const value of Object.values(data)) {
+            params.push(value);
+        }
+
+        const whereResult = this._compileWhereNode(this._model.where);
+        for (const param of whereResult.params) {
+            params.push(param);
+        }
+
+        return {
+            sql: `UPDATE ${escapeTable(table, this._quoteIdent)} SET ${fields.map((field) => `${escapeField(field, this._quoteIdent)} = ?`).join(", ")} WHERE ${whereResult.sql}`,
+            params: params
+        };
+    }
+
+    /**
+     * 构建 DELETE 查询
+     */
+    toDeleteSql(table) {
+        const whereResult = this._compileWhereNode(this._model.where);
+        return {
+            sql: `DELETE FROM ${escapeTable(table, this._quoteIdent)} WHERE ${whereResult.sql}`,
+            params: whereResult.params
+        };
+    }
+
+    /**
+     * 构建 COUNT 查询
+     */
+    toCountSql() {
+        const params = [];
+        const fromSql = this._model.from.type === "raw" ? this._model.from.value : escapeTable(this._model.from.value, this._quoteIdent);
+        let sql = `SELECT COUNT(*) as total FROM ${fromSql}`;
+
+        if (this._model.joins.length > 0) {
+            sql += ` ${this._model.joins.map((join) => `${join.type.toUpperCase()} JOIN ${escapeTable(join.table, this._quoteIdent)} ON ${join.on}`).join(" ")}`;
+        }
+
+        const whereResult = this._compileWhereNode(this._model.where);
+        if (whereResult.sql) {
+            sql += ` WHERE ${whereResult.sql}`;
+            for (const param of whereResult.params) {
+                params.push(param);
+            }
+        }
+
+        return { sql: sql, params: params };
+    }
+
+    static toDeleteInSql(options) {
+        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})`;
+        const params = [];
+        for (const id of options.ids) {
+            params.push(id);
+        }
+
+        return { sql: sql, params: params };
+    }
+
+    static toUpdateCaseByIdSql(options) {
+        if (options.rows.length === 0) {
+            return { sql: "", params: [] };
+        }
+        if (options.fields.length === 0) {
+            return { sql: "", params: [] };
+        }
+
+        const ids = options.rows.map((row) => row.id);
+        const placeholders = ids.map(() => "?").join(",");
+        const setSqlList = [];
+        const args = [];
+        const quotedId = options.quoteIdent(options.idField);
+
+        for (const field of options.fields) {
+            const whenList = [];
+
+            for (const row of options.rows) {
+                if (!(field in row.data)) {
+                    continue;
+                }
+
+                whenList.push("WHEN ? THEN ?");
+                args.push(row.id);
+                const value = row.data[field];
+                assertNoUndefinedParam(value, "SQL 参数值");
+                args.push(value);
+            }
+
+            if (whenList.length === 0) {
+                continue;
+            }
+
+            const quotedField = options.quoteIdent(field);
+            setSqlList.push(`${quotedField} = CASE ${quotedId} ${whenList.join(" ")} ELSE ${quotedField} END`);
+        }
+
+        if (isNonEmptyString(options.updatedAtField)) {
+            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 };
+    }
+}
+
+/**
+ * 创建新的 SQL 构建器实例
+ */
+export function createQueryBuilder() {
+    return new SqlBuilder();
+}