@maiyunnet/kebab 2.0.6 → 2.0.8

package/lib/sql.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-5-27 20:18:50
+ * Last: 2020-3-29 19:37:25, 2022-07-24 22:38:11, 2023-5-24 18:49:18, 2023-6-13 22:20:21, 2023-12-11 13:58:54, 2023-12-14 13:14:40, 2023-12-21 00:04:40, 2024-4-11 19:29:29, 2024-9-2 17:15:28
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -40,14 +45,22 @@ exports.aoMix = aoMix;
 exports.column = column;
 const lText = __importStar(require("../lib/text"));
 const lCore = __importStar(require("../lib/core"));
+// --- 第三方 ---
 const mysql2 = __importStar(require("mysql2/promise"));
+// --- 库和定义 ---
 const ctr = __importStar(require("../sys/ctr"));
+/** --- filed 用 token --- */
 let columnToken = '';
 class Sql {
+    // --- 实例化 ---
     constructor(pre, opt = {}) {
+        /** --- 前置 --- */
         this._pre = '';
+        /** --- 预拼装 Sql 数组 --- */
         this._sql = [];
+        /** --- 所有 data 数据 --- */
         this._data = [];
+        /** --- where 的 data 的开始处和结束处 --- */
         this._whereDataPosition = [0, 0];
         this._pre = pre ?? '';
         if (opt.data) {
@@ -57,21 +70,37 @@ class Sql {
             this._sql = opt.sql;
         }
     }
+    // --- 前导 ---
+    /**
+     * --- 插入数据前导 ---
+     * @param table 表名
+     */
     insert(table) {
         this._data = [];
         const sql = 'INSERT INTO ' + this.field(table, this._pre);
         this._sql = [sql];
         return this;
     }
+    /**
+     * --- 替换已经存在的唯一索引数据，不存在则插入 ---
+     * @param table 表名
+     */
     replace(table) {
         this._data = [];
         const sql = 'REPLACE INTO ' + this.field(table, this._pre);
         this._sql = [sql];
         return this;
     }
+    /**
+     * --- 实际插入数据的数据 ---
+     * @param cs [] 数据列或字段列
+     * @param vs [] | [][] 数据
+     */
     values(cs, vs = []) {
         let sql = ' (';
         if (Array.isArray(cs)) {
+            // --- ['id', 'name'], [['1', 'wow'], ['2', 'oh']] ---
+            // --- ['id', 'name'], ['1', 'wow'] ---
             for (const i of cs) {
                 sql += this.field(i) + ', ';
             }
@@ -79,10 +108,14 @@ class Sql {
             if (!Array.isArray(vs[0])) {
                 vs = [vs];
             }
+            // --- INSERT INTO xx (id, name) VALUES (?, ?) ---
+            // --- INSERT INTO xx (id, name) VALUES (?, ?), (?, ?) ---
             for (const v of vs) {
                 sql += '(';
                 for (const v1 of v) {
+                    // --- v1 是项目值，如 {'x': 1, 'y': 2}, 'string', 0 ---
                     if (v1 === undefined || Number.isNaN(v1)) {
+                        // --- 异常情况 ---
                         lCore.log({
                             'path': '',
                             'urlFull': '',
@@ -92,6 +125,7 @@ class Sql {
                             'cookie': {},
                             'headers': {}
                         }, '(sql.values) value error', '-error').catch(() => {
+                            //
                         });
                         sql += `'', `;
                     }
@@ -105,12 +139,14 @@ class Sql {
                     else if (Array.isArray(v1)) {
                         if (v1[0]?.[0]?.x === undefined && typeof v1[0] === 'string' &&
                             v1[0].includes('(') && v1[0].includes(')')) {
+                            // --- v1: ['POINT(?)', ['20']] ---
                             sql += this.field(v1[0]) + ', ';
                             if (v1[1]) {
                                 this._data.push(...v1[1]);
                             }
                         }
                         else if (v1[0]?.[0]?.y !== undefined) {
+                            // --- v1: [[{'x': 1, 'y': 2}, { ... }], [{ ... }, { ... }]] ---
                             sql += 'ST_POLYGONFROMTEXT(?), ';
                             this._data.push(`POLYGON(${v1.map((item) => {
                                 return `(${item.map((it) => {
@@ -119,28 +155,34 @@ class Sql {
                             }).join(', ')})`);
                         }
                         else {
+                            // --- v1: json ---
                             sql += '?, ';
                             this._data.push(lText.stringifyJson(v1));
                         }
                     }
                     else if (v1.x !== undefined) {
                         if (v1.y !== undefined) {
+                            // --- v1: {'x': 1, 'y': 2} ---
                             sql += 'ST_POINTFROMTEXT(?), ';
                             this._data.push(`POINT(${v1.x} ${v1.y})`);
                         }
                         else {
+                            // --- v1: json ---
                             sql += '?, ';
                             this._data.push(lText.stringifyJson(v1));
                         }
                     }
                     else if (v1 instanceof Buffer) {
+                        // --- Buffer ---
                         sql += '?, ';
                         this._data.push(v);
                     }
                     else if (this._isField(v1)) {
+                        // --- 3 ---
                         sql += this.field(v1.value) + ', ';
                     }
                     else {
+                        // --- json ---
                         sql += '?, ';
                         this._data.push(lText.stringifyJson(v1));
                     }
@@ -150,11 +192,14 @@ class Sql {
             sql = sql.slice(0, -2);
         }
         else {
+            // --- {'id': '1', 'name': 'wow'} ---
+            // --- INSERT INTO xx (id, name) VALUES (?, ?) ---
             let values = '';
             for (const k in cs) {
                 const v = cs[k];
                 sql += this.field(k) + ', ';
                 if (v === undefined || Number.isNaN(v)) {
+                    // --- 异常情况 ---
                     lCore.log({
                         'path': '',
                         'urlFull': '',
@@ -164,6 +209,7 @@ class Sql {
                         'cookie': {},
                         'headers': {}
                     }, '(sql.values) value error', '-error').catch(() => {
+                        //
                     });
                     values += `'', `;
                 }
@@ -177,12 +223,14 @@ class Sql {
                 else if (Array.isArray(v)) {
                     if (v[0]?.[0]?.x === undefined && typeof v[0] === 'string' &&
                         v[0].includes('(') && v[0].includes(')')) {
+                        // --- v: ['POINT(?)', ['20']] ---
                         values += this.field(v[0]) + ', ';
                         if (v[1] !== undefined) {
                             this._data.push(...v[1]);
                         }
                     }
                     else if (v[0]?.[0]?.y !== undefined) {
+                        // --- v: [[{'x': 1, 'y': 2}, { ... }], [{ ... }, { ... }]] ---
                         values += 'ST_POLYGONFROMTEXT(?), ';
                         this._data.push(`POLYGON(${v.map((item) => {
                             return `(${item.map((it) => {
@@ -191,28 +239,34 @@ class Sql {
                         }).join(', ')})`);
                     }
                     else {
+                        // --- v: json ---
                         values += '?, ';
                         this._data.push(lText.stringifyJson(v));
                     }
                 }
                 else if (v.x !== undefined) {
                     if (v.y !== undefined) {
+                        // --- v: {'x': 1, 'y': 2} ---
                         values += 'ST_POINTFROMTEXT(?), ';
                         this._data.push(`POINT(${v.x} ${v.y})`);
                     }
                     else {
+                        // --- v: json ---
                         values += '?, ';
                         this._data.push(lText.stringifyJson(v));
                     }
                 }
                 else if (v instanceof Buffer) {
+                    // --- Buffer ---
                     values += '?, ';
                     this._data.push(v);
                 }
                 else if (this._isField(v)) {
+                    // --- 3 ---
                     values += this.field(v.value) + ', ';
                 }
                 else {
+                    // --- json ---
                     values += '?, ';
                     this._data.push(lText.stringifyJson(v));
                 }
@@ -222,6 +276,12 @@ class Sql {
         this._sql.push(sql);
         return this;
     }
+    /**
+     * --- 不存在则插入，衔接在 insert 之后 ---
+     * @param table 表名
+     * @param insert {'xx': 'xx', 'xx': 'xx'}
+     * @param where [{'xx': 'xx', 'xx': 'xx'}], {'xx': 'xx'}
+     */
     notExists(table, insert, where) {
         let sql = '(';
         const values = [];
@@ -245,6 +305,10 @@ class Sql {
         this._sql.push(sql);
         return this;
     }
+    /**
+     * --- 当不能 insert 时，update（仅能配合 insert 方法用） ---
+     * @param s 更新数据
+     */
     duplicate(s) {
         if (Array.isArray(s) ? s.length : Object.keys(s).length) {
             const sql = ' ON DUPLICATE KEY UPDATE ' + this._updateSub(s);
@@ -252,6 +316,11 @@ class Sql {
         }
         return this;
     }
+    /**
+     * --- '*', 'xx' ---
+     * @param c 字段字符串或字段数组
+     * @param f 表，允许多张表
+     */
     select(c, f) {
         this._data = [];
         let sql = 'SELECT ';
@@ -259,8 +328,10 @@ class Sql {
             sql += this.field(c);
         }
         else {
+            // --- c: ['id', 'name'] ---
             for (const i of c) {
                 if (Array.isArray(i)) {
+                    // --- i: ['xx', ['x']] ---
                     sql += this.field(i[0]) + ', ';
                     this._data.push(...i[1]);
                 }
@@ -275,6 +346,7 @@ class Sql {
             sql += this.field(f, this._pre);
         }
         else {
+            // --- f: ['user', 'order'] ---
             for (const i of f) {
                 sql += this.field(i, this._pre) + ', ';
             }
@@ -283,6 +355,11 @@ class Sql {
         this._sql = [sql];
         return this;
     }
+    /**
+     * --- UPDATE SQL 方法 ---
+     * @param f 表名
+     * @param s 设定 update 的值
+     */
     update(f, s) {
         this._data = [];
         const sql = `UPDATE ${this.field(f, this._pre)} SET ${this._updateSub(s)}`;
@@ -290,11 +367,27 @@ class Sql {
         return this;
     }
     _updateSub(s) {
+        /*
+        [
+            ['total', '+', '1'],    // 1, '1' 可能也是 1 数字类型
+            {
+                'type': '6',        // 2
+                'type': column('type2'),   // 3
+                // 'type': ['type3'],  // 4 - 此写法已被禁止，请用 (3) 代替
+                'type': ['(CASE `id` WHEN 1 THEN ? WHEN 2 THEN ? END)', ['val1', 'val2']],     // 5
+                'point': { 'x': 0, 'y': 0 },  // 6
+                'polygon': [ [ { 'x': 0, 'y': 0 }, { ... } ], [ ... ] ],          // 7
+                'json': { 'a': 1, 'b': { 'c': 2 }, 'c': [ { 'c': 2 } ] },         // 8 - 对象类 json，可能为空对象
+                'json2': ['abc']    // 9 - 数组类 json，可能为空数组
+            }
+        ]
+        */
         s = aoMix(s);
         let sql = '';
         for (const k in s) {
             const v = s[k];
             if (/^[0-9]+$/.test(k)) {
+                // --- 1 ---
                 const nv = v[2];
                 const isf = this._isField(nv);
                 if (isf) {
@@ -316,8 +409,10 @@ class Sql {
                 }
             }
             else {
+                // --- 2, 3, 4, 5, 6, 7, 8 ---
                 sql += this.field(k) + ' = ';
                 if (v === undefined || Number.isNaN(v)) {
+                    // --- 异常情况 ---
                     lCore.log({
                         'path': '',
                         'urlFull': '',
@@ -327,6 +422,7 @@ class Sql {
                         'cookie': {},
                         'headers': {}
                     }, '(sql._updateSub) value error, key: ' + k, '-error').catch(() => {
+                        //
                     });
                     sql += '"", ';
                 }
@@ -334,18 +430,21 @@ class Sql {
                     sql += 'NULL, ';
                 }
                 else if (typeof v === 'string' || typeof v === 'number') {
+                    // --- 2 ---
                     sql += '?, ';
                     this._data.push(v);
                 }
                 else if (Array.isArray(v)) {
                     if (v[0]?.[0]?.x === undefined && typeof v[0] === 'string' &&
                         v[0].includes('(') && v[0].includes(')')) {
+                        // --- 4, 5: ['(CASE `id` WHEN 1 THEN ? WHEN 2 THEN ? END)', ['val1', 'val2']] ---
                         sql += this.field(v[0]) + ', ';
                         if (v[1] !== undefined) {
                             this._data.push(...v[1]);
                         }
                     }
                     else if (v[0]?.[0]?.y !== undefined) {
+                        // --- 7 ---
                         sql += 'ST_POLYGONFROMTEXT(?), ';
                         this._data.push(`POLYGON(${v.map((item) => {
                             return `(${item.map((it) => {
@@ -354,33 +453,41 @@ class Sql {
                         }).join(', ')})`);
                     }
                     else {
+                        // --- v: json ---
                         sql += '?, ';
                         this._data.push(lText.stringifyJson(v));
                     }
                 }
                 else if (v.x !== undefined) {
                     if (v.y !== undefined) {
+                        // --- 6: v: {'x': 1, 'y': 2} ---
                         sql += 'ST_POINTFROMTEXT(?), ';
                         this._data.push(`POINT(${v.x} ${v.y})`);
                     }
                     else {
+                        // --- v: json ---
                         if (this._isField(v)) {
+                            // --- 3 ---
                             sql += this.field(v.value) + ', ';
                         }
                         else {
+                            // --- 8 ---
                             sql += '?, ';
                             this._data.push(lText.stringifyJson(v));
                         }
                     }
                 }
                 else if (v instanceof Buffer) {
+                    // --- Buffer ---
                     sql += '?, ';
                     this._data.push(v);
                 }
                 else if (this._isField(v)) {
+                    // --- 3 ---
                     sql += this.field(v.value) + ', ';
                 }
                 else {
+                    // --- json ---
                     sql += '?, ';
                     this._data.push(lText.stringifyJson(v));
                 }
@@ -389,23 +496,45 @@ class Sql {
         sql = sql.slice(0, -2);
         return sql;
     }
+    /**
+     * --- 'xx' ---
+     * @param f 表名
+     */
     delete(f) {
         this._data = [];
         this._sql = ['DELETE FROM ' + this.field(f, this._pre)];
         return this;
     }
+    /**
+     * --- 联查另一个 sql 对象 ---
+     * @param sql sql 对象
+     * @param type 类型
+     */
     union(lsql, type = '') {
         this._data = this._data.concat(lsql.getData());
         this._sql.push(' UNION ' + (type ? type + ' ' : ''));
         this._sql.push(lsql.getSql());
         return this;
     }
+    /**
+     * --- 所有联查另一个 sql 对象 ---
+     * @param sql sql 对象
+     */
     unionAll(lsql) {
         return this.union(lsql, 'ALL');
     }
+    /**
+     * --- join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param type 类型
+     * @param suf 表后缀
+     * @param pre 表前缀，仅在 join 非默认表前缀时填写
+     */
     join(f, s = [], type = 'INNER', suf = '', pre = '') {
         let field = this.field(f, pre || this._pre, suf ? ('#' + suf) : '');
         if (pre) {
+            // --- 处理不同 pre 的 as 前缀问题 ---
             field = field.replace(new RegExp(`AS \`${pre}(.+?)\``), `AS \`${this._pre}$1\``);
         }
         let sql = ' ' + type + ' JOIN ' + field;
@@ -415,28 +544,68 @@ class Sql {
         this._sql.push(sql);
         return this;
     }
+    /**
+     * --- left join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param suf 表后缀
+     * @param pre 表前缀，仅在 join 非默认表前缀时填写
+     */
     leftJoin(f, s = [], suf = '', pre = '') {
         return this.join(f, s, 'LEFT', suf, pre);
     }
+    /**
+     * --- right join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param suf 表后缀
+     * @param pre 表前缀，仅在 join 非默认表前缀时填写
+     */
     rightJoin(f, s = [], suf = '', pre = '') {
         return this.join(f, s, 'RIGHT', suf, pre);
     }
+    /**
+     * --- inner join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param suf 表后缀
+     * @param pre 表前缀，仅在 join 非默认表前缀时填写
+     */
     innerJoin(f, s = [], suf = '', pre = '') {
         return this.join(f, s, 'INNER', suf, pre);
     }
+    /**
+     * --- full join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param suf 表后缀
+     * @param pre 表前缀，仅在 join 非默认表前缀时填写
+     */
     fullJoin(f, s = [], suf = '', pre = '') {
         return this.join(f, s, 'FULL', suf, pre);
     }
+    /**
+     * --- cross join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param suf 表后缀
+     * @param pre 表前缀，仅在 join 非默认表前缀时填写
+     */
     crossJoin(f, s = [], suf = '', pre = '') {
         return this.join(f, s, 'CROSS', suf, pre);
     }
+    /**
+     * --- having 后置筛选器，用法类似 where ---
+     */
     having(s = '') {
         if (typeof s === 'string') {
+            // --- string ---
             if (s !== '') {
                 this._sql.push(' HAVING ' + s);
             }
         }
         else {
+            // --- array ---
             if (s.length) {
                 const whereSub = this._whereSub(s);
                 if (whereSub !== '') {
@@ -446,15 +615,28 @@ class Sql {
         }
         return this;
     }
+    /**
+     * --- 筛选器 ---
+     * --- 1. 'city': 'bj', 'type': '2' ---
+     * --- 2. ['type', '>', '1'] ---
+     * --- 3. ['type', 'in', ['1', '2']] ---
+     * --- 4. 'type': ['1', '2'] ---
+     * --- 5. '$or': [{'city': 'bj'}, {'city': 'sh'}, [['age', '>', '10']]], 'type': '2' ---
+     * --- 6. 'city_in': column('city_out') ---
+     * --- 7. ['JSON_CONTAINS(`uid`, ?)', ['hello']] ---
+     * @param s 筛选数据
+     */
     where(s) {
         this._whereDataPosition[0] = this._data.length;
         if (typeof s === 'string') {
+            // --- string ---
             if (s !== '') {
                 this._sql.push(' WHERE ' + s);
                 this._whereDataPosition[1] = this._data.length;
             }
         }
         else {
+            // --- array ---
             let go = false;
             if (Array.isArray(s)) {
                 if (s.length) {
@@ -483,13 +665,16 @@ class Sql {
         for (const k in s) {
             const v = s[k];
             if (/^[0-9]+$/.test(k)) {
+                // --- 2, 3, 7 ---
                 if (v[2] === undefined) {
+                    // --- 7 ---
                     sql += this.field(v[0]) + ' AND ';
                     if (v[1] !== undefined) {
                         data.push(...v[1]);
                     }
                 }
                 else if (v[2] === null) {
+                    // --- 3: null ---
                     let opera = v[1];
                     if (opera === '!=' || opera === '!==' || opera === '<>') {
                         opera = 'IS NOT';
@@ -503,6 +688,7 @@ class Sql {
                     sql += this.field(v[0]) + ' ' + opera + ' NULL AND ';
                 }
                 else if (Array.isArray(v[2])) {
+                    // --- 3 ---
                     sql += this.field(v[0]) + ' ' + v[1].toUpperCase() + ' (';
                     for (const v1 of v[2]) {
                         sql += '?, ';
@@ -511,9 +697,11 @@ class Sql {
                     sql = sql.slice(0, -2) + ') AND ';
                 }
                 else {
+                    // --- 2, 6 ---
                     const nv = v[2];
                     const isf = this._isField(nv);
                     if (isf) {
+                        // --- 6. field ---
                         sql += this.field(v[0]) + ' ' + v[1] + ' ' + this.field(nv.value) + ' AND ';
                     }
                     else {
@@ -523,10 +711,13 @@ class Sql {
                 }
             }
             else {
+                // --- 1, 4, 5, 6 ---
                 if (k.startsWith('$')) {
+                    // --- 5 - '$or': [{'city': 'bj'}, {'city': 'sh'}] ---
                     const sp = ' ' + k.slice(1).split('-')[0].toUpperCase() + ' ';
                     sql += '(';
                     for (let v1 of v) {
+                        // --- v1 是 {'city': 'bj'} ---
                         v1 = aoMix(v1);
                         if (Object.keys(v1).length > 1) {
                             sql += '(' + this._whereSub(v1, data) + ')' + sp;
@@ -538,17 +729,21 @@ class Sql {
                     sql = sql.slice(0, -sp.length) + ') AND ';
                 }
                 else {
+                    // --- 1, 4, 6 ---
                     if (v === null) {
                         sql += this.field(k) + ' IS NULL AND ';
                     }
                     else if (typeof v === 'string' || typeof v === 'number') {
+                        // --- 1 ---
                         sql += this.field(k) + ' = ? AND ';
                         data.push(v);
                     }
                     else if (this._isField(v)) {
+                        // --- 6 ---
                         sql += this.field(k) + ' = ' + this.field(v.value) + ' AND ';
                     }
                     else {
+                        // --- 4 - 'type': ['1', '2'] ---
                         if (v.length > 0) {
                             sql += this.field(k) + ' IN (';
                             for (const v1 of v) {
@@ -569,6 +764,11 @@ class Sql {
         }
         return sql.slice(0, -5);
     }
+    /**
+     * --- ORDER BY ---
+     * @param c 字段字符串或数组
+     * @param d 排序规则
+     */
     by(c, d = 'DESC') {
         let sql = ' ORDER BY ';
         if (typeof c === 'string') {
@@ -588,6 +788,10 @@ class Sql {
         this._sql.push(sql);
         return this;
     }
+    /**
+     * --- GROUP BY ---
+     * @param c 字段字符串或数组
+     */
     group(c) {
         let sql = ' GROUP BY ';
         if (typeof c === 'string') {
@@ -602,19 +806,32 @@ class Sql {
         this._sql.push(sql);
         return this;
     }
+    /**
+     * --- LIMIT ---
+     * @param a 起始
+     * @param b 长度
+     */
     limit(a, b = 0) {
         this._sql.push(' LIMIT ' + a.toString() + (b > 0 ? ', ' + b.toString() : ''));
         return this;
     }
+    /**
+     * --- 追加消极锁，通常不建议使用 ---
+     */
     lock() {
         this._sql.push(' FOR UPDATE');
         return this;
     }
+    /**
+     * --- 创建一个本对象的一个新的 sql 对象拷贝 ---
+     * @param f 可为空，可设置新对象的 table 名变化
+     */
     copy(f, opt = {}) {
         const sql = lCore.clone(this._sql);
         const data = lCore.clone(this._data);
         if (opt.where !== undefined) {
             if (typeof opt.where === 'string') {
+                // --- string ---
                 for (let i = 0; i < sql.length; ++i) {
                     if (!sql[i].startsWith(' WHERE ')) {
                         continue;
@@ -625,6 +842,7 @@ class Sql {
                 }
             }
             else {
+                // --- array ---
                 let go = false;
                 if (Array.isArray(opt.where)) {
                     if (opt.where.length) {
@@ -636,16 +854,19 @@ class Sql {
                         go = true;
                     }
                 }
+                // --- 找到原来的 where ---
                 for (let i = 0; i < sql.length; ++i) {
                     if (!sql[i].startsWith(' WHERE ')) {
                         continue;
                     }
                     if (go) {
+                        // --- 修改 where ---
                         const d = [];
                         sql[i] = ' WHERE ' + this._whereSub(opt.where, d);
                         data.splice(this._whereDataPosition[0], this._whereDataPosition[1] - this._whereDataPosition[0], ...d);
                     }
                     else {
+                        // --- 清除 where ---
                         sql.splice(i, 1);
                         data.splice(this._whereDataPosition[0], this._whereDataPosition[1] - this._whereDataPosition[0]);
                     }
@@ -653,12 +874,14 @@ class Sql {
                 }
             }
         }
+        // --- 替换表名 ---
         if (f && sql[0]) {
             let table = '';
             if (typeof f === 'string') {
                 table = this.field(f, this._pre);
             }
             else {
+                // --- f: ['user', 'order'] ---
                 for (const i of f) {
                     table += this.field(i, this._pre) + ', ';
                 }
@@ -671,22 +894,48 @@ class Sql {
             'sql': sql
         });
     }
+    // --- 操作 ---
+    /**
+     * --- 获取 sql 语句 ---
+     */
     getSql() {
         return this._sql.join('');
     }
+    /**
+     * --- 获取全部 data ---
+     */
     getData() {
         return this._data;
     }
+    /**
+     * --- 获取定义的 pre ---
+     */
     getPre() {
         return this._pre;
     }
+    /**
+     * --- 获取带 data 的 sql 语句 ---
+     * @param sql
+     * @param data
+     */
     format(sql, data) {
         return mysql2.format(sql ?? this.getSql(), data ?? this.getData());
     }
+    // --- 特殊方法 ---
+    /**
+     * --- 在 sql 最后追加字符串 ---
+     * @param sql
+     */
     append(sql) {
         this._sql.push(sql);
         return this;
     }
+    /**
+     * --- 对字段进行包裹 ---
+     * @param str
+     * @param pre 表前缀，仅请在 field 表名时倒入前缀
+     * @param suf 表后缀，仅请在 field 表名时倒入后缀，前面加 # 代表要强制 AS
+     */
     field(str, pre = '', suf = '') {
         let left = '';
         let right = '';
@@ -697,26 +946,33 @@ class Sql {
         if (typeof str === 'number') {
             str = str.toString();
         }
-        str = str.trim();
-        str = str.replace(/ {2,}/g, ' ');
+        str = str.trim(); // --- 去除前导尾随 ---
+        str = str.replace(/ {2,}/g, ' '); // --- 去除多余的空格 ---
         str = str.replace(/ +([),])/g, ' $1');
         str = str.replace(/([(,]) +/g, '$1 ');
         str = str.replace(/(\W)(JOIN|WHERE|UNION)(\W)/ig, '$1$3');
+        // --- 先判断 suf 强制性 AS ---
         let sufAs = false;
         if (suf.startsWith('#')) {
+            // --- 强制 AS ---
             suf = suf.slice(1);
             sufAs = true;
         }
+        // --- 先判断有没有别名（也就是 as） ---
         const loStr = str.toLowerCase();
         const asPos = loStr.indexOf(' as ');
         if (asPos === -1) {
+            // --- 没有 as ---
             let spacePos = str.lastIndexOf(' ');
+            // --- 有可能有 aa + bb + cc + 10 这种情况 ---
             if (!/^[a-zA-Z_)]$/.test(str[spacePos - 1])) {
+                // --- 连接符 ---
                 spacePos = -1;
             }
             if (spacePos !== -1) {
                 const spaceRight = str.slice(spacePos + 1);
                 if (/^[a-zA-Z_`][\w`]*$/.test(spaceRight)) {
+                    // --- OK ---
                     left = str.slice(0, spacePos);
                     right = spaceRight;
                 }
@@ -731,10 +987,12 @@ class Sql {
             }
         }
         else {
+            // --- 有 as ---
             left = str.slice(0, asPos);
             right = str.slice(asPos + 4);
         }
         if (right) {
+            // --- 处理右侧 ---
             if (right.startsWith('`')) {
                 right = '`' + pre + right.slice(1);
             }
@@ -744,10 +1002,13 @@ class Sql {
             right = ' AS ' + right;
         }
         else {
+            // --- 没有右侧 ---
             if (sufAs) {
+                // --- 强制 AS ---
                 right = ' AS ' + this.field(left, pre);
             }
         }
+        // --- 处理 left ---
         if (/^[\w`_.*]+$/.test(left)) {
             const l = left.split('.');
             if (l[0] === '*') {
@@ -757,20 +1018,29 @@ class Sql {
                 l[0] = l[0].replace(/`/g, '');
             }
             if (l[1] === undefined) {
+                // --- xxx ---
                 if (/^[A-Z0-9_]+$/.test(l[0])) {
+                    // --- 纯大写是内置函数，不能加 ` ---
                     return l[0] + right;
                 }
                 return '`' + pre + l[0] + suf + '`' + right;
             }
+            // --- x.xxx ---
+            // --- 只有在此模式才知道 . 前面的一定是表名，因此自动加 sql 级的 _pre ---
             const w = l[1] === '*' ? '*' : (l[1].startsWith('`') ? l[1] : ('`' + l[1] + '`'));
             return '`' + this._pre + l[0] + suf + '`.' + w + right;
         }
         else {
+            // return left.replace(/([(, ])([a-zA-Z`_][\w`_.]*)(?=[), ])/g, (
             return left.replace(/(^|[(, ])([a-zA-Z`_][\w`_.]*)(?=[), ]|$)/g, (t, t1, t2) => {
                 return t1 + this.field(t2, pre, suf);
             }) + right;
         }
     }
+    /**
+     * --- 判断传入值是否是 field，还是别的对象 ---
+     * @param str
+     */
     _isField(arg) {
         if (arg.type !== 'column' || arg.token !== columnToken || arg.value === undefined) {
             return false;
@@ -779,12 +1049,26 @@ class Sql {
     }
 }
 exports.Sql = Sql;
+/**
+ * --- 创建 sql 对象 ---
+ * @param ctrPre ctr 对象或 pre 表前缀
+ * @param opt 参数
+ */
 function get(ctrPre, opt = {}) {
     return new Sql(ctrPre instanceof ctr.Ctr ? ctrPre.getPrototype('_config').sql.pre : ctrPre, opt);
 }
+/**
+ * --- 返回代入后的完整 SQL 字符串 ---
+ * @param sql SQL 字符串
+ * @param data DATA 数据
+ */
 function format(sql, data) {
     return mysql2.format(sql, data);
 }
+/**
+ * --- 将数组兑换为组合的对象（Array/Object mix） ---
+ * @param arr 要转换的数组
+ */
 function aoMix(arr) {
     if (!Array.isArray(arr)) {
         return arr;
@@ -804,6 +1088,7 @@ function aoMix(arr) {
     }
     return mix;
 }
+/** --- 创建字段对象 --- */
 function column(field) {
     if (!columnToken) {
         columnToken = lCore.random(8, lCore.RANDOM_LUNS);