befly 3.9.38 → 3.9.40

package/lib/sqlBuilder.ts

@@ -1,17 +1,16 @@
-/**
+/**
  * SQL 构造器 - TypeScript 版本
  * 提供链式 API 构建 SQL 查询
  */
 
-import type { WhereConditions, OrderByField, WhereOperator, OrderDirection, SqlQuery, InsertData, UpdateData } from '../types/common.js';
-import type { SqlValue } from 'befly-shared/types';
+import type { WhereConditions, WhereOperator, OrderDirection, SqlQuery, InsertData, UpdateData, SqlValue } from "../types/common.js";
 
 /**
  * SQL 构建器类
  */
 export class SqlBuilder {
     private _select: string[] = [];
-    private _from: string = '';
+    private _from: string = "";
     private _where: string[] = [];
     private _joins: string[] = [];
     private _orderBy: string[] = [];
@@ -26,7 +25,7 @@ export class SqlBuilder {
      */
     reset(): this {
         this._select = [];
-        this._from = '';
+        this._from = "";
         this._where = [];
         this._joins = [];
         this._orderBy = [];
@@ -42,19 +41,19 @@ export class SqlBuilder {
      * 转义字段名
      */
     private _escapeField(field: string): string {
-        if (typeof field !== 'string') {
+        if (typeof field !== "string") {
             return field;
         }
 
         field = field.trim();
 
         // 如果是 * 或已经有着重号或包含函数，直接返回
-        if (field === '*' || field.startsWith('`') || field.includes('(')) {
+        if (field === "*" || field.startsWith("`") || field.includes("(")) {
             return field;
         }
 
         // 处理别名（AS关键字）
-        if (field.toUpperCase().includes(' AS ')) {
+        if (field.toUpperCase().includes(" AS ")) {
             const parts = field.split(/\s+AS\s+/i);
             const fieldPart = parts[0].trim();
             const aliasPart = parts[1].trim();
@@ -62,17 +61,17 @@ export class SqlBuilder {
         }
 
         // 处理表名.字段名的情况（多表联查）
-        if (field.includes('.')) {
-            const parts = field.split('.');
+        if (field.includes(".")) {
+            const parts = field.split(".");
             return parts
                 .map((part) => {
                     part = part.trim();
-                    if (part === '*' || part.startsWith('`')) {
+                    if (part === "*" || part.startsWith("`")) {
                         return part;
                     }
                     return `\`${part}\``;
                 })
-                .join('.');
+                .join(".");
         }
 
         // 处理单个字段名
@@ -83,18 +82,18 @@ export class SqlBuilder {
      * 转义表名
      */
     private _escapeTable(table: string): string {
-        if (typeof table !== 'string') {
+        if (typeof table !== "string") {
             return table;
         }
 
         table = table.trim();
 
-        if (table.startsWith('`')) {
+        if (table.startsWith("`")) {
             return table;
         }
 
         // 处理表别名（表名 + 空格 + 别名）
-        if (table.includes(' ')) {
+        if (table.includes(" ")) {
             const parts = table.split(/\s+/);
             if (parts.length === 2) {
                 const tableName = parts[0].trim();
@@ -124,75 +123,75 @@ export class SqlBuilder {
         const escapedField = this._escapeField(fieldName);
 
         switch (operator) {
-            case '$ne':
-            case '$not':
+            case "$ne":
+            case "$not":
                 this._validateParam(value);
                 this._where.push(`${escapedField} != ?`);
                 this._params.push(value);
                 break;
 
-            case '$in':
+            case "$in":
                 if (!Array.isArray(value)) {
                     throw new Error(`$in 操作符的值必须是数组 (operator: ${operator})`);
                 }
                 if (value.length === 0) {
                     throw new Error(`$in 操作符的数组不能为空。提示：空数组会导致查询永远不匹配任何记录，这通常不是预期行为。请检查查询条件或移除该字段。`);
                 }
-                const placeholders = value.map(() => '?').join(',');
+                const placeholders = value.map(() => "?").join(",");
                 this._where.push(`${escapedField} IN (${placeholders})`);
                 this._params.push(...value);
                 break;
 
-            case '$nin':
-            case '$notIn':
+            case "$nin":
+            case "$notIn":
                 if (!Array.isArray(value)) {
                     throw new Error(`$nin/$notIn 操作符的值必须是数组 (operator: ${operator})`);
                 }
                 if (value.length === 0) {
                     throw new Error(`$nin/$notIn 操作符的数组不能为空。提示：空数组会导致查询匹配所有记录，这通常不是预期行为。请检查查询条件或移除该字段。`);
                 }
-                const placeholders2 = value.map(() => '?').join(',');
+                const placeholders2 = value.map(() => "?").join(",");
                 this._where.push(`${escapedField} NOT IN (${placeholders2})`);
                 this._params.push(...value);
                 break;
 
-            case '$like':
+            case "$like":
                 this._validateParam(value);
                 this._where.push(`${escapedField} LIKE ?`);
                 this._params.push(value);
                 break;
 
-            case '$notLike':
+            case "$notLike":
                 this._validateParam(value);
                 this._where.push(`${escapedField} NOT LIKE ?`);
                 this._params.push(value);
                 break;
 
-            case '$gt':
+            case "$gt":
                 this._validateParam(value);
                 this._where.push(`${escapedField} > ?`);
                 this._params.push(value);
                 break;
 
-            case '$gte':
+            case "$gte":
                 this._validateParam(value);
                 this._where.push(`${escapedField} >= ?`);
                 this._params.push(value);
                 break;
 
-            case '$lt':
+            case "$lt":
                 this._validateParam(value);
                 this._where.push(`${escapedField} < ?`);
                 this._params.push(value);
                 break;
 
-            case '$lte':
+            case "$lte":
                 this._validateParam(value);
                 this._where.push(`${escapedField} <= ?`);
                 this._params.push(value);
                 break;
 
-            case '$between':
+            case "$between":
                 if (Array.isArray(value) && value.length === 2) {
                     this._validateParam(value[0]);
                     this._validateParam(value[1]);
@@ -201,7 +200,7 @@ export class SqlBuilder {
                 }
                 break;
 
-            case '$notBetween':
+            case "$notBetween":
                 if (Array.isArray(value) && value.length === 2) {
                     this._validateParam(value[0]);
                     this._validateParam(value[1]);
@@ -210,13 +209,13 @@ export class SqlBuilder {
                 }
                 break;
 
-            case '$null':
+            case "$null":
                 if (value === true) {
                     this._where.push(`${escapedField} IS NULL`);
                 }
                 break;
 
-            case '$notNull':
+            case "$notNull":
                 if (value === true) {
                     this._where.push(`${escapedField} IS NOT NULL`);
                 }
@@ -234,7 +233,7 @@ export class SqlBuilder {
      * 处理复杂的 WHERE 条件对象
      */
     private _processWhereConditions(whereObj: WhereConditions): void {
-        if (!whereObj || typeof whereObj !== 'object') {
+        if (!whereObj || typeof whereObj !== "object") {
             return;
         }
 
@@ -244,11 +243,11 @@ export class SqlBuilder {
                 return;
             }
 
-            if (key === '$and') {
+            if (key === "$and") {
                 if (Array.isArray(value)) {
                     value.forEach((condition) => this._processWhereConditions(condition));
                 }
-            } else if (key === '$or') {
+            } else if (key === "$or") {
                 if (Array.isArray(value)) {
                     const orConditions: string[] = [];
                     const tempParams: SqlValue[] = [];
@@ -257,25 +256,25 @@ export class SqlBuilder {
                         const tempBuilder = new SqlBuilder();
                         tempBuilder._processWhereConditions(condition);
                         if (tempBuilder._where.length > 0) {
-                            orConditions.push(`(${tempBuilder._where.join(' AND ')})`);
+                            orConditions.push(`(${tempBuilder._where.join(" AND ")})`);
                             tempParams.push(...tempBuilder._params);
                         }
                     });
 
                     if (orConditions.length > 0) {
-                        this._where.push(`(${orConditions.join(' OR ')})`);
+                        this._where.push(`(${orConditions.join(" OR ")})`);
                         this._params.push(...tempParams);
                     }
                 }
-            } else if (key.includes('$')) {
+            } else if (key.includes("$")) {
                 // 一级属性格式：age$gt, role$in 等
-                const lastDollarIndex = key.lastIndexOf('$');
+                const lastDollarIndex = key.lastIndexOf("$");
                 const fieldName = key.substring(0, lastDollarIndex);
-                const operator = ('$' + key.substring(lastDollarIndex + 1)) as WhereOperator;
+                const operator = ("$" + key.substring(lastDollarIndex + 1)) as WhereOperator;
                 this._applyOperator(fieldName, operator, value);
             } else {
                 // 检查值是否为对象（嵌套条件）
-                if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                if (typeof value === "object" && value !== null && !Array.isArray(value)) {
                     // 嵌套条件：如 { age: { $gt: 18 } }
                     for (const [op, val] of Object.entries(value)) {
                         this._applyOperator(key, op as WhereOperator, val);
@@ -296,7 +295,7 @@ export class SqlBuilder {
      */
     getWhereConditions(): { sql: string; params: SqlValue[] } {
         return {
-            sql: this._where.length > 0 ? this._where.join(' AND ') : '',
+            sql: this._where.length > 0 ? this._where.join(" AND ") : "",
             params: [...this._params]
         };
     }
@@ -304,13 +303,13 @@ export class SqlBuilder {
     /**
      * SELECT 字段
      */
-    select(fields: string | string[] = '*'): this {
+    select(fields: string | string[] = "*"): this {
         if (Array.isArray(fields)) {
             this._select = [...this._select, ...fields.map((field) => this._escapeField(field))];
-        } else if (typeof fields === 'string') {
+        } else if (typeof fields === "string") {
             this._select.push(this._escapeField(fields));
         } else {
-            throw new Error('SELECT 字段必须是字符串或数组');
+            throw new Error("SELECT 字段必须是字符串或数组");
         }
         return this;
     }
@@ -319,7 +318,7 @@ export class SqlBuilder {
      * FROM 表名
      */
     from(table: string): this {
-        if (typeof table !== 'string' || !table.trim()) {
+        if (typeof table !== "string" || !table.trim()) {
             throw new Error(`FROM 表名必须是非空字符串 (table: ${table})`);
         }
         this._from = this._escapeTable(table.trim());
@@ -330,14 +329,14 @@ export class SqlBuilder {
      * WHERE 条件
      */
     where(condition: WhereConditions | string, value?: SqlValue): this {
-        if (typeof condition === 'object' && condition !== null) {
+        if (typeof condition === "object" && condition !== null) {
             this._processWhereConditions(condition);
         } else if (value !== undefined && value !== null) {
             this._validateParam(value);
             const escapedCondition = this._escapeField(condition as string);
             this._where.push(`${escapedCondition} = ?`);
             this._params.push(value);
-        } else if (typeof condition === 'string') {
+        } else if (typeof condition === "string") {
             this._where.push(condition);
         }
         return this;
@@ -347,7 +346,7 @@ export class SqlBuilder {
      * LEFT JOIN
      */
     leftJoin(table: string, on: string): this {
-        if (typeof table !== 'string' || typeof on !== 'string') {
+        if (typeof table !== "string" || typeof on !== "string") {
             throw new Error(`JOIN 表名和条件必须是字符串 (table: ${table}, on: ${on})`);
         }
         const escapedTable = this._escapeTable(table);
@@ -359,7 +358,7 @@ export class SqlBuilder {
      * RIGHT JOIN
      */
     rightJoin(table: string, on: string): this {
-        if (typeof table !== 'string' || typeof on !== 'string') {
+        if (typeof table !== "string" || typeof on !== "string") {
             throw new Error(`JOIN 表名和条件必须是字符串 (table: ${table}, on: ${on})`);
         }
         const escapedTable = this._escapeTable(table);
@@ -371,7 +370,7 @@ export class SqlBuilder {
      * INNER JOIN
      */
     innerJoin(table: string, on: string): this {
-        if (typeof table !== 'string' || typeof on !== 'string') {
+        if (typeof table !== "string" || typeof on !== "string") {
             throw new Error(`JOIN 表名和条件必须是字符串 (table: ${table}, on: ${on})`);
         }
         const escapedTable = this._escapeTable(table);
@@ -389,11 +388,11 @@ export class SqlBuilder {
         }
 
         fields.forEach((item) => {
-            if (typeof item !== 'string' || !item.includes('#')) {
+            if (typeof item !== "string" || !item.includes("#")) {
                 throw new Error(`orderBy 字段必须是 "字段#方向" 格式的字符串（例如："name#ASC", "id#DESC"） (item: ${item})`);
             }
 
-            const [fieldName, direction] = item.split('#');
+            const [fieldName, direction] = item.split("#");
             const cleanField = fieldName.trim();
             const cleanDir = direction.trim().toUpperCase() as OrderDirection;
 
@@ -401,7 +400,7 @@ export class SqlBuilder {
                 throw new Error(`orderBy 中字段名不能为空 (item: ${item})`);
             }
 
-            if (!['ASC', 'DESC'].includes(cleanDir)) {
+            if (!["ASC", "DESC"].includes(cleanDir)) {
                 throw new Error(`ORDER BY 方向必须是 ASC 或 DESC (direction: ${cleanDir})`);
             }
 
@@ -417,9 +416,9 @@ export class SqlBuilder {
      */
     groupBy(field: string | string[]): this {
         if (Array.isArray(field)) {
-            const escapedFields = field.filter((f) => typeof f === 'string').map((f) => this._escapeField(f));
+            const escapedFields = field.filter((f) => typeof f === "string").map((f) => this._escapeField(f));
             this._groupBy = [...this._groupBy, ...escapedFields];
-        } else if (typeof field === 'string') {
+        } else if (typeof field === "string") {
             this._groupBy.push(this._escapeField(field));
         }
         return this;
@@ -429,7 +428,7 @@ export class SqlBuilder {
      * HAVING
      */
     having(condition: string): this {
-        if (typeof condition === 'string') {
+        if (typeof condition === "string") {
             this._having.push(condition);
         }
         return this;
@@ -439,12 +438,12 @@ export class SqlBuilder {
      * LIMIT
      */
     limit(count: number, offset?: number): this {
-        if (typeof count !== 'number' || count < 0) {
+        if (typeof count !== "number" || count < 0) {
             throw new Error(`LIMIT 数量必须是非负数 (count: ${count})`);
         }
         this._limit = Math.floor(count);
         if (offset !== undefined && offset !== null) {
-            if (typeof offset !== 'number' || offset < 0) {
+            if (typeof offset !== "number" || offset < 0) {
                 throw new Error(`OFFSET 必须是非负数 (offset: ${offset})`);
             }
             this._offset = Math.floor(offset);
@@ -456,7 +455,7 @@ export class SqlBuilder {
      * OFFSET
      */
     offset(count: number): this {
-        if (typeof count !== 'number' || count < 0) {
+        if (typeof count !== "number" || count < 0) {
             throw new Error(`OFFSET 必须是非负数 (count: ${count})`);
         }
         this._offset = Math.floor(count);
@@ -467,33 +466,33 @@ export class SqlBuilder {
      * 构建 SELECT 查询
      */
     toSelectSql(): SqlQuery {
-        let sql = 'SELECT ';
+        let sql = "SELECT ";
 
-        sql += this._select.length > 0 ? this._select.join(', ') : '*';
+        sql += this._select.length > 0 ? this._select.join(", ") : "*";
 
         if (!this._from) {
-            throw new Error('FROM 表名是必需的');
+            throw new Error("FROM 表名是必需的");
         }
         sql += ` FROM ${this._from}`;
 
         if (this._joins.length > 0) {
-            sql += ' ' + this._joins.join(' ');
+            sql += " " + this._joins.join(" ");
         }
 
         if (this._where.length > 0) {
-            sql += ' WHERE ' + this._where.join(' AND ');
+            sql += " WHERE " + this._where.join(" AND ");
         }
 
         if (this._groupBy.length > 0) {
-            sql += ' GROUP BY ' + this._groupBy.join(', ');
+            sql += " GROUP BY " + this._groupBy.join(", ");
         }
 
         if (this._having.length > 0) {
-            sql += ' HAVING ' + this._having.join(' AND ');
+            sql += " HAVING " + this._having.join(" AND ");
         }
 
         if (this._orderBy.length > 0) {
-            sql += ' ORDER BY ' + this._orderBy.join(', ');
+            sql += " ORDER BY " + this._orderBy.join(", ");
         }
 
         if (this._limit !== null) {
@@ -510,11 +509,11 @@ export class SqlBuilder {
      * 构建 INSERT 查询
      */
     toInsertSql(table: string, data: InsertData): SqlQuery {
-        if (!table || typeof table !== 'string') {
+        if (!table || typeof table !== "string") {
             throw new Error(`INSERT 需要表名 (table: ${table})`);
         }
 
-        if (!data || typeof data !== 'object') {
+        if (!data || typeof data !== "object") {
             throw new Error(`INSERT 需要数据 (table: ${table}, data: ${JSON.stringify(data)})`);
         }
 
@@ -531,10 +530,10 @@ export class SqlBuilder {
             }
 
             const escapedFields = fields.map((field) => this._escapeField(field));
-            const placeholders = fields.map(() => '?').join(', ');
-            const values = data.map(() => `(${placeholders})`).join(', ');
+            const placeholders = fields.map(() => "?").join(", ");
+            const values = data.map(() => `(${placeholders})`).join(", ");
 
-            const sql = `INSERT INTO ${escapedTable} (${escapedFields.join(', ')}) VALUES ${values}`;
+            const sql = `INSERT INTO ${escapedTable} (${escapedFields.join(", ")}) VALUES ${values}`;
             const params = data.flatMap((row) => fields.map((field) => row[field]));
 
             return { sql, params };
@@ -545,8 +544,8 @@ export class SqlBuilder {
             }
 
             const escapedFields = fields.map((field) => this._escapeField(field));
-            const placeholders = fields.map(() => '?').join(', ');
-            const sql = `INSERT INTO ${escapedTable} (${escapedFields.join(', ')}) VALUES (${placeholders})`;
+            const placeholders = fields.map(() => "?").join(", ");
+            const sql = `INSERT INTO ${escapedTable} (${escapedFields.join(", ")}) VALUES (${placeholders})`;
             const params = fields.map((field) => data[field]);
 
             return { sql, params };
@@ -557,29 +556,29 @@ export class SqlBuilder {
      * 构建 UPDATE 查询
      */
     toUpdateSql(table: string, data: UpdateData): SqlQuery {
-        if (!table || typeof table !== 'string') {
-            throw new Error('UPDATE 需要表名');
+        if (!table || typeof table !== "string") {
+            throw new Error("UPDATE 需要表名");
         }
 
-        if (!data || typeof data !== 'object' || Array.isArray(data)) {
-            throw new Error('UPDATE 需要数据对象');
+        if (!data || typeof data !== "object" || Array.isArray(data)) {
+            throw new Error("UPDATE 需要数据对象");
         }
 
         const fields = Object.keys(data);
         if (fields.length === 0) {
-            throw new Error('更新数据必须至少有一个字段');
+            throw new Error("更新数据必须至少有一个字段");
         }
 
         const escapedTable = this._escapeTable(table);
         const setFields = fields.map((field) => `${this._escapeField(field)} = ?`);
         const params: SqlValue[] = [...Object.values(data), ...this._params];
 
-        let sql = `UPDATE ${escapedTable} SET ${setFields.join(', ')}`;
+        let sql = `UPDATE ${escapedTable} SET ${setFields.join(", ")}`;
 
         if (this._where.length > 0) {
-            sql += ' WHERE ' + this._where.join(' AND ');
+            sql += " WHERE " + this._where.join(" AND ");
         } else {
-            throw new Error('为安全起见，UPDATE 需要 WHERE 条件');
+            throw new Error("为安全起见，UPDATE 需要 WHERE 条件");
         }
 
         return { sql, params };
@@ -589,17 +588,17 @@ export class SqlBuilder {
      * 构建 DELETE 查询
      */
     toDeleteSql(table: string): SqlQuery {
-        if (!table || typeof table !== 'string') {
-            throw new Error('DELETE 需要表名');
+        if (!table || typeof table !== "string") {
+            throw new Error("DELETE 需要表名");
         }
 
         const escapedTable = this._escapeTable(table);
         let sql = `DELETE FROM ${escapedTable}`;
 
         if (this._where.length > 0) {
-            sql += ' WHERE ' + this._where.join(' AND ');
+            sql += " WHERE " + this._where.join(" AND ");
         } else {
-            throw new Error('为安全起见，DELETE 需要 WHERE 条件');
+            throw new Error("为安全起见，DELETE 需要 WHERE 条件");
         }
 
         return { sql, params: [...this._params] };
@@ -609,19 +608,19 @@ export class SqlBuilder {
      * 构建 COUNT 查询
      */
     toCountSql(): SqlQuery {
-        let sql = 'SELECT COUNT(*) as total';
+        let sql = "SELECT COUNT(*) as total";
 
         if (!this._from) {
-            throw new Error('COUNT 需要 FROM 表名');
+            throw new Error("COUNT 需要 FROM 表名");
         }
         sql += ` FROM ${this._from}`;
 
         if (this._joins.length > 0) {
-            sql += ' ' + this._joins.join(' ');
+            sql += " " + this._joins.join(" ");
         }
 
         if (this._where.length > 0) {
-            sql += ' WHERE ' + this._where.join(' AND ');
+            sql += " WHERE " + this._where.join(" AND ");
         }
 
         return { sql, params: [...this._params] };