befly 3.17.0 → 3.17.2

package/lib/sqlBuilder/index.js

@@ -0,0 +1,218 @@
+/**
+ * SQL 构造器 - JavaScript 版本
+ * 提供链式 API 构建 SQL 查询
+ */
+
+import { resolveQuoteIdent, normalizeLimitValue, normalizeOffsetValue } from "./util.js";
+import { appendGroupByItems, appendHavingItems, appendJoinItem, appendOrderByItems, appendSelectItems, appendSelectRaw, appendWhereInput, appendWhereRaw, createWhereRoot, setFromValue } from "./parser.js";
+import { compileCount, compileDelete, compileInsert, compileSelect, compileUpdate, compileWhere } from "./compiler.js";
+import { toDeleteInSql, toUpdateCaseByIdSql } from "./batch.js";
+
+function createModel() {
+    return {
+        select: [],
+        from: null,
+        where: createWhereRoot(),
+        joins: [],
+        orderBy: [],
+        groupBy: [],
+        having: [],
+        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;
+    }
+
+    /**
+     * 获取 WHERE 条件（供 DbHelper 使用）
+     */
+    getWhereConditions() {
+        const result = compileWhere(this._model.where, this._quoteIdent);
+        return { sql: result.sql, params: result.params };
+    }
+
+    /**
+     * SELECT 字段
+     */
+    select(fields = "*") {
+        appendSelectItems(this._model.select, fields);
+        return this;
+    }
+
+    /**
+     * SELECT 原始表达式（不做转义）
+     */
+    selectRaw(expr) {
+        appendSelectRaw(this._model.select, expr);
+        return this;
+    }
+
+    /**
+     * FROM 表名
+     */
+    from(table) {
+        setFromValue(this._model, table, false);
+        return this;
+    }
+
+    /**
+     * FROM 原始表达式（不做转义）
+     */
+    fromRaw(tableExpr) {
+        setFromValue(this._model, tableExpr, true);
+        return this;
+    }
+
+    /**
+     * WHERE 条件
+     */
+    where(conditionOrField, value) {
+        appendWhereInput(this._model.where, conditionOrField, value);
+        return this;
+    }
+
+    /**
+     * WHERE 原始片段（不做转义），可附带参数。
+     */
+    whereRaw(sql, params) {
+        appendWhereRaw(this._model.where, sql, params);
+        return this;
+    }
+
+    /**
+     * LEFT JOIN
+     */
+    leftJoin(table, on) {
+        appendJoinItem(this._model.joins, "left", table, on);
+        return this;
+    }
+
+    /**
+     * RIGHT JOIN
+     */
+    rightJoin(table, on) {
+        appendJoinItem(this._model.joins, "right", table, on);
+        return this;
+    }
+
+    /**
+     * INNER JOIN
+     */
+    innerJoin(table, on) {
+        appendJoinItem(this._model.joins, "inner", table, on);
+        return this;
+    }
+
+    /**
+     * ORDER BY
+     * @param fields - 格式为 ["field#ASC", "field2#DESC"]
+     */
+    orderBy(fields) {
+        appendOrderByItems(this._model.orderBy, fields);
+        return this;
+    }
+
+    /**
+     * GROUP BY
+     */
+    groupBy(field) {
+        appendGroupByItems(this._model.groupBy, field);
+        return this;
+    }
+
+    /**
+     * HAVING
+     */
+    having(condition) {
+        appendHavingItems(this._model.having, condition);
+        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() {
+        return compileSelect(this._model, this._quoteIdent);
+    }
+
+    /**
+     * 构建 INSERT 查询
+     */
+    toInsertSql(table, data) {
+        return compileInsert(table, data, this._quoteIdent);
+    }
+
+    /**
+     * 构建 UPDATE 查询
+     */
+    toUpdateSql(table, data) {
+        return compileUpdate(this._model, table, data, this._quoteIdent);
+    }
+
+    /**
+     * 构建 DELETE 查询
+     */
+    toDeleteSql(table) {
+        return compileDelete(this._model, table, this._quoteIdent);
+    }
+
+    /**
+     * 构建 COUNT 查询
+     */
+    toCountSql() {
+        return compileCount(this._model, this._quoteIdent);
+    }
+
+    static toDeleteInSql(options) {
+        return toDeleteInSql(options);
+    }
+
+    static toUpdateCaseByIdSql(options) {
+        return toUpdateCaseByIdSql(options);
+    }
+}
+
+/**
+ * 创建新的 SQL 构建器实例
+ */
+export function createQueryBuilder() {
+    return new SqlBuilder();
+}

package/lib/sqlBuilder/parser.js

@@ -0,0 +1,296 @@
+import { SqlErrors } from "./errors.js";
+import { validateParam } from "./util.js";
+import { isNonEmptyString, isString } from "../../utils/is.js";
+
+export function createWhereRoot() {
+    return { type: "group", join: "AND", items: [] };
+}
+
+export function appendSelectItems(list, fields) {
+    if (Array.isArray(fields)) {
+        for (const field of fields) {
+            list.push({ type: "field", value: field });
+        }
+        return;
+    }
+
+    if (isString(fields)) {
+        list.push({ type: "field", value: fields });
+        return;
+    }
+
+    throw new Error(SqlErrors.SELECT_FIELDS_INVALID, {
+        cause: null,
+        code: "validation"
+    });
+}
+
+export function appendSelectRaw(list, expr) {
+    if (!isNonEmptyString(expr)) {
+        throw new Error(SqlErrors.SELECT_RAW_NEED_NON_EMPTY(expr), {
+            cause: null,
+            code: "validation"
+        });
+    }
+    list.push({ type: "raw", value: expr });
+}
+
+export function setFromValue(state, table, isRaw) {
+    if (!isNonEmptyString(table)) {
+        const err = isRaw ? SqlErrors.FROM_RAW_NEED_NON_EMPTY(table) : SqlErrors.FROM_NEED_NON_EMPTY(table);
+        throw new Error(err, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    state.from = { type: isRaw ? "raw" : "table", value: table.trim() };
+}
+
+export function appendJoinItem(list, joinType, table, on) {
+    if (!isString(table) || !isString(on)) {
+        throw new Error(SqlErrors.JOIN_NEED_STRING(table, on), {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    list.push({ type: joinType, table: table, on: on });
+}
+
+export function appendOrderByItems(list, fields) {
+    if (!Array.isArray(fields)) {
+        throw new Error(SqlErrors.ORDER_BY_NEED_ARRAY, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    for (const item of fields) {
+        if (!isString(item) || !item.includes("#")) {
+            throw new Error(SqlErrors.ORDER_BY_ITEM_NEED_HASH(item), {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const parts = item.split("#");
+        if (parts.length !== 2) {
+            throw new Error(SqlErrors.ORDER_BY_ITEM_NEED_HASH(item), {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const fieldName = parts[0];
+        const direction = parts[1];
+        const cleanField = fieldName.trim();
+        const cleanDir = direction.trim().toUpperCase();
+
+        if (!cleanField) {
+            throw new Error(SqlErrors.ORDER_BY_FIELD_EMPTY(item), {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        if (!["ASC", "DESC"].includes(cleanDir)) {
+            throw new Error(SqlErrors.ORDER_BY_DIR_INVALID(cleanDir), {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        list.push({ field: cleanField, dir: cleanDir });
+    }
+}
+
+export function appendGroupByItems(list, field) {
+    if (Array.isArray(field)) {
+        for (const item of field) {
+            if (isString(item)) {
+                list.push(item);
+            }
+        }
+        return;
+    }
+
+    if (isString(field)) {
+        list.push(field);
+    }
+}
+
+export function appendHavingItems(list, condition) {
+    if (isString(condition)) {
+        list.push(condition);
+    }
+}
+
+export function appendWhereInput(root, conditionOrField, value) {
+    if (conditionOrField && typeof conditionOrField === "object" && !Array.isArray(conditionOrField)) {
+        const node = parseWhereObject(conditionOrField);
+        if (node && node.items.length > 0) {
+            root.items.push(node);
+        }
+        return;
+    }
+
+    if (isString(conditionOrField)) {
+        if (value === undefined) {
+            throw new Error(SqlErrors.WHERE_VALUE_REQUIRED, {
+                cause: null,
+                code: "validation"
+            });
+        }
+        const node = buildOperatorNode(conditionOrField, "=", value);
+        if (node) {
+            root.items.push(node);
+        }
+    }
+}
+
+export function appendWhereRaw(root, sql, params) {
+    if (!isNonEmptyString(sql)) {
+        throw new Error(SqlErrors.WHERE_RAW_NEED_NON_EMPTY(sql), {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const paramList = Array.isArray(params) ? params : [];
+    for (const param of paramList) {
+        validateParam(param);
+    }
+
+    root.items.push({ type: "raw", sql: sql, params: paramList });
+}
+
+function 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") {
+            if (Array.isArray(value)) {
+                for (const condition of value) {
+                    if (condition && typeof condition === "object" && !Array.isArray(condition)) {
+                        const sub = parseWhereObject(condition);
+                        if (sub.items.length > 0) {
+                            if (sub.join === "AND") {
+                                for (const item of sub.items) {
+                                    group.items.push(item);
+                                }
+                            } else {
+                                group.items.push(sub);
+                            }
+                        }
+                    }
+                }
+            }
+            continue;
+        }
+
+        if (key === "$or") {
+            if (Array.isArray(value)) {
+                const orGroup = { type: "group", join: "OR", items: [] };
+                for (const condition of value) {
+                    if (!condition || typeof condition !== "object" || Array.isArray(condition)) {
+                        continue;
+                    }
+                    const sub = parseWhereObject(condition);
+                    if (sub.items.length > 0) {
+                        orGroup.items.push(sub);
+                    }
+                }
+                if (orGroup.items.length > 0) {
+                    group.items.push(orGroup);
+                }
+            }
+            continue;
+        }
+
+        if (key.includes("$")) {
+            const lastDollarIndex = key.lastIndexOf("$");
+            const fieldName = key.substring(0, lastDollarIndex);
+            const operator = "$" + key.substring(lastDollarIndex + 1);
+            const node = buildOperatorNode(fieldName, operator, value);
+            if (node) {
+                group.items.push(node);
+            }
+            continue;
+        }
+
+        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            for (const [op, val] of Object.entries(value)) {
+                const node = buildOperatorNode(key, op, val);
+                if (node) {
+                    group.items.push(node);
+                }
+            }
+            continue;
+        }
+
+        const node = buildOperatorNode(key, "=", value);
+        if (node) {
+            group.items.push(node);
+        }
+    }
+
+    return group;
+}
+
+function buildOperatorNode(fieldName, operator, value) {
+    switch (operator) {
+        case "$in":
+            if (!Array.isArray(value)) {
+                throw new Error(SqlErrors.IN_NEED_ARRAY(operator), {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+            if (value.length === 0) {
+                throw new Error(SqlErrors.IN_NEED_NON_EMPTY, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+            return { type: "op", field: fieldName, operator: operator, value: value };
+        case "$nin":
+        case "$notIn":
+            if (!Array.isArray(value)) {
+                throw new Error(SqlErrors.NIN_NEED_ARRAY(operator), {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+            if (value.length === 0) {
+                throw new Error(SqlErrors.NIN_NEED_NON_EMPTY, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+            return { type: "op", field: fieldName, operator: operator, value: value };
+        case "$between":
+        case "$notBetween":
+            if (Array.isArray(value) && value.length === 2) {
+                return { type: "op", field: fieldName, operator: operator, value: value };
+            }
+            return null;
+        case "$null":
+        case "$notNull":
+            if (value === true) {
+                return { type: "op", field: fieldName, operator: operator, value: value };
+            }
+            return null;
+        default:
+            validateParam(value);
+            return { type: "op", field: fieldName, operator: operator, value: value };
+    }
+}