befly 2.3.2 → 3.0.0

package/utils/{sqlBuilder.js → sqlBuilder.ts}

@@ -1,12 +1,30 @@
 /**
- * SQL 构造器 - 生产级稳定版本
+ * SQL 构建器 - TypeScript 版本
+ * 提供类型安全的 SQL 查询构建功能
  */
-export class SqlBuilder {
-    constructor() {
-        this.reset();
-    }
 
-    reset() {
+import type { OrderDirection, SqlValue } from '../types/common.js';
+import type { SqlQuery, WhereOperator, WhereConditions, InsertData, UpdateData } from '../types/database';
+
+/**
+ * SQL 构建器类
+ */
+export class SqlBuilder {
+    private _select: string[] = [];
+    private _from: string = '';
+    private _where: string[] = [];
+    private _joins: string[] = [];
+    private _orderBy: string[] = [];
+    private _groupBy: string[] = [];
+    private _having: string[] = [];
+    private _limit: number | null = null;
+    private _offset: number | null = null;
+    private _params: SqlValue[] = [];
+
+    /**
+     * 重置构建器状态
+     */
+    reset(): this {
         this._select = [];
         this._from = '';
         this._where = [];
@@ -20,16 +38,17 @@ export class SqlBuilder {
         return this;
     }
 
-    // 字段转义方法 - 处理字段名和表名的着重号转义
-    _escapeField(field) {
+    /**
+     * 转义字段名
+     */
+    private _escapeField(field: string): string {
         if (typeof field !== 'string') {
             return field;
         }
 
-        // 去除前后空格
         field = field.trim();
 
-        // 如果是 * 或已经有着重号，直接返回
+        // 如果是 * 或已经有着重号或包含函数，直接返回
         if (field === '*' || field.startsWith('`') || field.includes('(')) {
             return field;
         }
@@ -48,7 +67,6 @@ export class SqlBuilder {
             return parts
                 .map((part) => {
                     part = part.trim();
-                    // 如果是 * 或已经有着重号，不再处理
                     if (part === '*' || part.startsWith('`')) {
                         return part;
                     }
@@ -61,15 +79,16 @@ export class SqlBuilder {
         return `\`${field}\``;
     }
 
-    // 转义表名
-    _escapeTable(table) {
+    /**
+     * 转义表名
+     */
+    private _escapeTable(table: string): string {
         if (typeof table !== 'string') {
             return table;
         }
 
         table = table.trim();
 
-        // 如果已经有着重号，直接返回
         if (table.startsWith('`')) {
             return table;
         }
@@ -78,12 +97,10 @@ export class SqlBuilder {
         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}`;
             } else {
-                // 复杂情况，直接返回
                 return table;
             }
         }
@@ -91,35 +108,19 @@ export class SqlBuilder {
         return `\`${table}\``;
     }
 
-    select(fields = '*') {
-        if (Array.isArray(fields)) {
-            this._select = [...this._select, ...fields.map((field) => this._escapeField(field))];
-        } else if (typeof fields === 'string') {
-            this._select.push(this._escapeField(fields));
-        } else {
-            throw new Error('SELECT fields must be string or array');
-        }
-        return this;
-    }
-
-    from(table) {
-        if (typeof table !== 'string' || !table.trim()) {
-            throw new Error('FROM table must be a non-empty string');
-        }
-        this._from = this._escapeTable(table.trim());
-        return this;
-    }
-
-    // 安全的参数验证
-    _validateParam(value) {
+    /**
+     * 验证参数
+     */
+    private _validateParam(value: any): void {
         if (value === undefined) {
-            throw new Error('Parameter value cannot be undefined');
+            throw new Error('参数值不能为 undefined');
         }
-        return value;
     }
 
-    // 处理复杂的 where 条件对象
-    _processWhereConditions(whereObj) {
+    /**
+     * 处理复杂的 WHERE 条件对象
+     */
+    private _processWhereConditions(whereObj: WhereConditions): void {
         if (!whereObj || typeof whereObj !== 'object') {
             return;
         }
@@ -136,8 +137,8 @@ export class SqlBuilder {
                 }
             } else if (key === '$or') {
                 if (Array.isArray(value)) {
-                    const orConditions = [];
-                    const tempParams = [];
+                    const orConditions: string[] = [];
+                    const tempParams: SqlValue[] = [];
 
                     value.forEach((condition) => {
                         const tempBuilder = new SqlBuilder();
@@ -158,13 +159,12 @@ export class SqlBuilder {
                 const lastDollarIndex = key.lastIndexOf('$');
                 const fieldName = key.substring(0, lastDollarIndex);
                 const escapedFieldName = this._escapeField(fieldName);
-                const operator = '$' + key.substring(lastDollarIndex + 1);
-
-                this._validateParam(value);
+                const operator = ('$' + key.substring(lastDollarIndex + 1)) as WhereOperator;
 
                 switch (operator) {
                     case '$ne':
                     case '$not':
+                        this._validateParam(value);
                         this._where.push(`${escapedFieldName} != ?`);
                         this._params.push(value);
                         break;
@@ -184,26 +184,32 @@ export class SqlBuilder {
                         }
                         break;
                     case '$like':
+                        this._validateParam(value);
                         this._where.push(`${escapedFieldName} LIKE ?`);
                         this._params.push(value);
                         break;
                     case '$notLike':
+                        this._validateParam(value);
                         this._where.push(`${escapedFieldName} NOT LIKE ?`);
                         this._params.push(value);
                         break;
                     case '$gt':
+                        this._validateParam(value);
                         this._where.push(`${escapedFieldName} > ?`);
                         this._params.push(value);
                         break;
                     case '$gte':
+                        this._validateParam(value);
                         this._where.push(`${escapedFieldName} >= ?`);
                         this._params.push(value);
                         break;
                     case '$lt':
+                        this._validateParam(value);
                         this._where.push(`${escapedFieldName} < ?`);
                         this._params.push(value);
                         break;
                     case '$lte':
+                        this._validateParam(value);
                         this._where.push(`${escapedFieldName} <= ?`);
                         this._params.push(value);
                         break;
@@ -230,26 +236,127 @@ export class SqlBuilder {
                         }
                         break;
                     default:
+                        this._validateParam(value);
                         this._where.push(`${escapedFieldName} = ?`);
                         this._params.push(value);
                 }
             } else {
-                // 简单的等于条件
-                this._validateParam(value);
-                const escapedKey = this._escapeField(key);
-                this._where.push(`${escapedKey} = ?`);
-                this._params.push(value);
+                // 检查值是否为对象（嵌套条件）
+                if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                    // 嵌套条件：如 { age: { $gt: 18 } }
+                    const escapedKey = this._escapeField(key);
+                    for (const [op, val] of Object.entries(value)) {
+                        switch (op as WhereOperator) {
+                            case '$ne':
+                            case '$not':
+                                this._validateParam(val);
+                                this._where.push(`${escapedKey} != ?`);
+                                this._params.push(val);
+                                break;
+                            case '$gt':
+                                this._validateParam(val);
+                                this._where.push(`${escapedKey} > ?`);
+                                this._params.push(val);
+                                break;
+                            case '$gte':
+                                this._validateParam(val);
+                                this._where.push(`${escapedKey} >= ?`);
+                                this._params.push(val);
+                                break;
+                            case '$lt':
+                                this._validateParam(val);
+                                this._where.push(`${escapedKey} < ?`);
+                                this._params.push(val);
+                                break;
+                            case '$lte':
+                                this._validateParam(val);
+                                this._where.push(`${escapedKey} <= ?`);
+                                this._params.push(val);
+                                break;
+                            case '$like':
+                                this._validateParam(val);
+                                this._where.push(`${escapedKey} LIKE ?`);
+                                this._params.push(val);
+                                break;
+                            case '$notLike':
+                                this._validateParam(val);
+                                this._where.push(`${escapedKey} NOT LIKE ?`);
+                                this._params.push(val);
+                                break;
+                            case '$in':
+                                if (Array.isArray(val) && val.length > 0) {
+                                    const placeholders = val.map(() => '?').join(',');
+                                    this._where.push(`${escapedKey} IN (${placeholders})`);
+                                    this._params.push(...val);
+                                }
+                                break;
+                            case '$nin':
+                            case '$notIn':
+                                if (Array.isArray(val) && val.length > 0) {
+                                    const placeholders = val.map(() => '?').join(',');
+                                    this._where.push(`${escapedKey} NOT IN (${placeholders})`);
+                                    this._params.push(...val);
+                                }
+                                break;
+                            case '$null':
+                                if (val) {
+                                    this._where.push(`${escapedKey} IS NULL`);
+                                } else {
+                                    this._where.push(`${escapedKey} IS NOT NULL`);
+                                }
+                                break;
+                            default:
+                                // 未知操作符，按等于处理
+                                this._validateParam(val);
+                                this._where.push(`${escapedKey} = ?`);
+                                this._params.push(val);
+                        }
+                    }
+                } else {
+                    // 简单的等于条件
+                    this._validateParam(value);
+                    const escapedKey = this._escapeField(key);
+                    this._where.push(`${escapedKey} = ?`);
+                    this._params.push(value);
+                }
             }
         });
     }
 
-    where(condition, value = null) {
+    /**
+     * SELECT 字段
+     */
+    select(fields: string | string[] = '*'): this {
+        if (Array.isArray(fields)) {
+            this._select = [...this._select, ...fields.map((field) => this._escapeField(field))];
+        } else if (typeof fields === 'string') {
+            this._select.push(this._escapeField(fields));
+        } else {
+            throw new Error('SELECT 字段必须是字符串或数组');
+        }
+        return this;
+    }
+
+    /**
+     * FROM 表名
+     */
+    from(table: string): this {
+        if (typeof table !== 'string' || !table.trim()) {
+            throw new Error('FROM 表名必须是非空字符串');
+        }
+        this._from = this._escapeTable(table.trim());
+        return this;
+    }
+
+    /**
+     * WHERE 条件
+     */
+    where(condition: WhereConditions | string, value?: SqlValue): this {
         if (typeof condition === 'object' && condition !== null) {
-            // 处理对象形式的where条件，会自动过滤undefined
             this._processWhereConditions(condition);
-        } else if (value !== null) {
+        } else if (value !== undefined && value !== null) {
             this._validateParam(value);
-            const escapedCondition = this._escapeField(condition);
+            const escapedCondition = this._escapeField(condition as string);
             this._where.push(`${escapedCondition} = ?`);
             this._params.push(value);
         } else if (typeof condition === 'string') {
@@ -258,35 +365,42 @@ export class SqlBuilder {
         return this;
     }
 
-    leftJoin(table, on) {
+    /**
+     * LEFT JOIN
+     */
+    leftJoin(table: string, on: string): this {
         if (typeof table !== 'string' || typeof on !== 'string') {
-            throw new Error('JOIN table and condition must be strings');
+            throw new Error('JOIN 表名和条件必须是字符串');
         }
         const escapedTable = this._escapeTable(table);
         this._joins.push(`LEFT JOIN ${escapedTable} ON ${on}`);
         return this;
     }
 
-    orderBy(fields) {
+    /**
+     * ORDER BY
+     * @param fields - 格式为 ["field#ASC", "field2#DESC"]
+     */
+    orderBy(fields: string[]): this {
         if (!Array.isArray(fields)) {
-            throw new Error('orderBy must be an array of strings in "field#direction" format');
+            throw new Error('orderBy 必须是字符串数组，格式为 "字段#方向"');
         }
 
         fields.forEach((item) => {
             if (typeof item !== 'string' || !item.includes('#')) {
-                throw new Error('orderBy field must be a string in "field#direction" format (e.g., "name#ASC", "id#DESC")');
+                throw new Error('orderBy 字段必须是 "字段#方向" 格式的字符串（例如："name#ASC", "id#DESC"）');
             }
 
             const [fieldName, direction] = item.split('#');
             const cleanField = fieldName.trim();
-            const cleanDir = direction.trim().toUpperCase();
+            const cleanDir = direction.trim().toUpperCase() as OrderDirection;
 
             if (!cleanField) {
-                throw new Error('Field name cannot be empty in orderBy');
+                throw new Error('orderBy 中字段名不能为空');
             }
 
             if (!['ASC', 'DESC'].includes(cleanDir)) {
-                throw new Error('ORDER BY direction must be ASC or DESC');
+                throw new Error('ORDER BY 方向必须是 ASC 或 DESC');
             }
 
             const escapedField = this._escapeField(cleanField);
@@ -296,7 +410,10 @@ export class SqlBuilder {
         return this;
     }
 
-    groupBy(field) {
+    /**
+     * GROUP BY
+     */
+    groupBy(field: string | string[]): this {
         if (Array.isArray(field)) {
             const escapedFields = field.filter((f) => typeof f === 'string').map((f) => this._escapeField(f));
             this._groupBy = [...this._groupBy, ...escapedFields];
@@ -306,43 +423,54 @@ export class SqlBuilder {
         return this;
     }
 
-    having(condition) {
+    /**
+     * HAVING
+     */
+    having(condition: string): this {
         if (typeof condition === 'string') {
             this._having.push(condition);
         }
         return this;
     }
 
-    limit(count, offset = null) {
+    /**
+     * LIMIT
+     */
+    limit(count: number, offset?: number): this {
         if (typeof count !== 'number' || count < 0) {
-            throw new Error('LIMIT count must be a non-negative number');
+            throw new Error('LIMIT 数量必须是非负数');
         }
         this._limit = Math.floor(count);
-        if (offset !== null) {
+        if (offset !== undefined && offset !== null) {
             if (typeof offset !== 'number' || offset < 0) {
-                throw new Error('OFFSET must be a non-negative number');
+                throw new Error('OFFSET 必须是非负数');
             }
             this._offset = Math.floor(offset);
         }
         return this;
     }
 
-    offset(count) {
+    /**
+     * OFFSET
+     */
+    offset(count: number): this {
         if (typeof count !== 'number' || count < 0) {
-            throw new Error('OFFSET must be a non-negative number');
+            throw new Error('OFFSET 必须是非负数');
         }
         this._offset = Math.floor(count);
         return this;
     }
 
-    // 构建 SELECT 查询
-    toSelectSql() {
+    /**
+     * 构建 SELECT 查询
+     */
+    toSelectSql(): SqlQuery {
         let sql = 'SELECT ';
 
         sql += this._select.length > 0 ? this._select.join(', ') : '*';
 
         if (!this._from) {
-            throw new Error('FROM table is required');
+            throw new Error('FROM 表名是必需的');
         }
         sql += ` FROM ${this._from}`;
 
@@ -376,26 +504,28 @@ export class SqlBuilder {
         return { sql, params: [...this._params] };
     }
 
-    // 构建 INSERT 查询
-    toInsertSql(table, data) {
+    /**
+     * 构建 INSERT 查询
+     */
+    toInsertSql(table: string, data: InsertData): SqlQuery {
         if (!table || typeof table !== 'string') {
-            throw new Error('Table name is required for INSERT');
+            throw new Error('INSERT 需要表名');
         }
 
         if (!data || typeof data !== 'object') {
-            throw new Error('Data is required for INSERT');
+            throw new Error('INSERT 需要数据');
         }
 
         const escapedTable = this._escapeTable(table);
 
         if (Array.isArray(data)) {
             if (data.length === 0) {
-                throw new Error('Insert data cannot be empty');
+                throw new Error('插入数据不能为空');
             }
 
             const fields = Object.keys(data[0]);
             if (fields.length === 0) {
-                throw new Error('Insert data must have at least one field');
+                throw new Error('插入数据必须至少有一个字段');
             }
 
             const escapedFields = fields.map((field) => this._escapeField(field));
@@ -409,7 +539,7 @@ export class SqlBuilder {
         } else {
             const fields = Object.keys(data);
             if (fields.length === 0) {
-                throw new Error('Insert data must have at least one field');
+                throw new Error('插入数据必须至少有一个字段');
             }
 
             const escapedFields = fields.map((field) => this._escapeField(field));
@@ -421,40 +551,44 @@ export class SqlBuilder {
         }
     }
 
-    // 构建 UPDATE 查询
-    toUpdateSql(table, data) {
+    /**
+     * 构建 UPDATE 查询
+     */
+    toUpdateSql(table: string, data: UpdateData): SqlQuery {
         if (!table || typeof table !== 'string') {
-            throw new Error('Table name is required for UPDATE');
+            throw new Error('UPDATE 需要表名');
         }
 
         if (!data || typeof data !== 'object' || Array.isArray(data)) {
-            throw new Error('Data object is required for UPDATE');
+            throw new Error('UPDATE 需要数据对象');
         }
 
         const fields = Object.keys(data);
         if (fields.length === 0) {
-            throw new Error('Update data must have at least one field');
+            throw new Error('更新数据必须至少有一个字段');
         }
 
         const escapedTable = this._escapeTable(table);
         const setFields = fields.map((field) => `${this._escapeField(field)} = ?`);
-        const params = [...Object.values(data), ...this._params];
+        const params: SqlValue[] = [...Object.values(data), ...this._params];
 
         let sql = `UPDATE ${escapedTable} SET ${setFields.join(', ')}`;
 
         if (this._where.length > 0) {
             sql += ' WHERE ' + this._where.join(' AND ');
         } else {
-            throw new Error('UPDATE requires WHERE condition for safety');
+            throw new Error('为安全起见，UPDATE 需要 WHERE 条件');
         }
 
         return { sql, params };
     }
 
-    // 构建 DELETE 查询
-    toDeleteSql(table) {
+    /**
+     * 构建 DELETE 查询
+     */
+    toDeleteSql(table: string): SqlQuery {
         if (!table || typeof table !== 'string') {
-            throw new Error('Table name is required for DELETE');
+            throw new Error('DELETE 需要表名');
         }
 
         const escapedTable = this._escapeTable(table);
@@ -463,18 +597,20 @@ export class SqlBuilder {
         if (this._where.length > 0) {
             sql += ' WHERE ' + this._where.join(' AND ');
         } else {
-            throw new Error('DELETE requires WHERE condition for safety');
+            throw new Error('为安全起见，DELETE 需要 WHERE 条件');
         }
 
         return { sql, params: [...this._params] };
     }
 
-    // 构建 COUNT 查询
-    toCountSql() {
+    /**
+     * 构建 COUNT 查询
+     */
+    toCountSql(): SqlQuery {
         let sql = 'SELECT COUNT(*) as total';
 
         if (!this._from) {
-            throw new Error('FROM table is required for COUNT');
+            throw new Error('COUNT 需要 FROM 表名');
         }
         sql += ` FROM ${this._from}`;
 
@@ -491,8 +627,8 @@ export class SqlBuilder {
 }
 
 /**
- * 创建新的 SQL 构造器实例
+ * 创建新的 SQL 构建器实例
  */
-export function createQueryBuilder() {
+export function createQueryBuilder(): SqlBuilder {
     return new SqlBuilder();
 }