@maiyunnet/kebab 2.0.7 → 2.0.9

package/sys/mod.js

@@ -33,22 +33,31 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Project: Mutton, User: JianSuoQiYue
+ * Date: 2019-6-4 21:35
+ * Last: 2020-4-14 13:33:51, 2022-07-23 16:01:34, 2022-09-06 22:59:26, 2023-5-24 19:11:37, 2023-6-13 21:47:58, 2023-7-10 18:54:03, 2023-8-23 17:03:16, 2023-12-11 15:21:22, 2023-12-20 23:12:03, 2024-3-8 16:05:29, 2024-3-20 19:58:15, 2024-8-11 21:14:54, 2024-10-5 14:00:22, 2024-12-14 19:58:34
+ */
 const lSql = __importStar(require("../lib/sql"));
 const lTime = __importStar(require("../lib/time"));
 const lCore = __importStar(require("../lib/core"));
 const lText = __importStar(require("../lib/text"));
 const sCtr = __importStar(require("../sys/ctr"));
+/** --- 条数列表 --- */
 class Rows {
     constructor(initialItems = []) {
         this._items = [];
         this._items = initialItems;
     }
+    /** --- 总行数 --- */
     get length() {
         return this._items.length;
     }
+    /** --- 通过索引获取一个对象 --- */
     item(index) {
         return this._items[index];
     }
+    /** --- 转换为数组对象 --- */
     toArray() {
         const arr = [];
         for (const item of this._items) {
@@ -56,6 +65,7 @@ class Rows {
         }
         return arr;
     }
+    /** --- 根据规则筛掉项，predicate 返回 true 代表保留 --- */
     filter(predicate) {
         const items = [];
         for (let i = 0; i < this._items.length; ++i) {
@@ -66,6 +76,7 @@ class Rows {
         }
         return new Rows(items);
     }
+    /** --- 重塑对象内容 --- */
     map(allbackfn) {
         const items = [];
         for (let i = 0; i < this._items.length; ++i) {
@@ -93,17 +104,35 @@ class Rows {
         };
     }
 }
+/**
+ * --- 开启软更需要在表添加字段：ALTER TABLE `table_name` ADD `time_remove` bigint NOT NULL DEFAULT '0' AFTER `xxx`; ---
+ */
 class Mod {
+    /**
+     * --- 构造函数 ---
+     * @param ctr Ctr 对象
+     * @param opt 选项
+     */
     constructor(opt) {
+        /** --- 要 update 的内容 --- */
         this._updates = {};
+        /** --- 模型获取的属性 --- */
         this._data = {};
+        /** --- 当前选择的分表 _ 后缀，多个代表联查 --- */
         this._index = null;
+        /** --- 必须追加的数据筛选 key 与 values，仅单表模式有效 --- */
         this._contain = null;
+        /** --- 已算出的 total --- */
         this._total = [];
+        /** --- ctr 对象, Mutton: false, Kebab: true --- */
         this._ctr = undefined;
+        /** --- 设置的 limit --- */
         this._limit = [0, 0];
+        /** --- 导入 ctr 对象 --- */
         this._ctr = opt.ctr;
+        /** --- 导入数据库连接 --- */
         this._db = opt.db;
+        /** --- 新建 sql 对象 --- */
         this._sql = lSql.get(opt.pre ?? opt.ctr);
         if (opt.index) {
             this._index = typeof opt.index === 'string' ? [opt.index] : [...new Set(opt.index)];
@@ -111,6 +140,7 @@ class Mod {
         if (opt.contain) {
             this._contain = opt.contain;
         }
+        // --- 第三个参数用于内部数据导入，将 data 数据合并到本实例化类 ---
         if (opt.row) {
             for (const k in opt.row) {
                 const v = opt.row[k];
@@ -118,6 +148,7 @@ class Mod {
                 this[k] = v;
             }
         }
+        /** --- 是否有 select --- */
         const select = opt.select ?? (opt.where ? '*' : '');
         if (select) {
             this._sql.select(select, this.constructor._$table +
@@ -141,9 +172,18 @@ class Mod {
             this._sql.where(opt.where);
         }
     }
+    // --- 静态方法 ---
+    /** --- 创建字段对象 --- */
     static column(field) {
         return lSql.column(field);
     }
+    /**
+     * --- 添加一个序列 ---
+     * @param db 数据库对象
+     * @param cs 字段列表
+     * @param vs 数据列表
+     * @param opt 选项
+     */
     static async insert(db, cs, vs, opt = {}) {
         const sq = lSql.get(opt.pre);
         sq.insert(this._$table + (opt.index ? ('_' + opt.index) : '')).values(cs, vs);
@@ -167,11 +207,24 @@ class Mod {
             return null;
         }
     }
+    /**
+     * --- 获取添加一个序列的模拟 SQL ---
+     * @param cs 字段列表
+     * @param vs 数据列表
+     * @param opt 选项
+     */
     static insertSql(cs, vs, opt = {}) {
         const sq = lSql.get(opt.pre);
         sq.insert(this._$table + (opt.index ? ('_' + opt.index) : '')).values(cs, vs);
         return sq.format();
     }
+    /**
+     * --- 插入数据如果唯一键冲突则更新 ---
+     * @param db 数据库对象
+     * @param data 要插入的数据
+     * @param update 要更新的数据
+     * @param opt 选项
+     */
     static async insertDuplicate(db, data, update, opt = {}) {
         const sq = lSql.get(opt.pre);
         sq.insert(this._$table + (opt.index ? ('_' + opt.index) : '')).values(data).duplicate(update);
@@ -195,10 +248,17 @@ class Mod {
             return null;
         }
     }
+    /**
+     * --- 根据条件移除条目 ---
+     * @param db 数据库对象
+     * @param where 筛选条件
+     * @param opt 选项
+     */
     static async removeByWhere(db, where, opt = {}) {
         const tim = lTime.stamp();
         const sq = lSql.get(opt.pre);
         if (this._$soft && !opt.raw) {
+            // --- 软删除 ---
             sq.update(this._$table + (opt.index ? ('_' + opt.index) : ''), [{
                     'time_remove': tim
                 }]);
@@ -215,6 +275,7 @@ class Mod {
             }
         }
         else {
+            // --- 真删除 ---
             sq.delete(this._$table + (opt.index ? ('_' + opt.index) : ''));
         }
         sq.where(where);
@@ -242,10 +303,17 @@ class Mod {
         }
         return null;
     }
+    /**
+     * --- 根据条件移除条目（仅获取 SQL 对象） ---
+     * @param db 数据库对象
+     * @param where 筛选条件
+     * @param opt 选项
+     */
     static removeByWhereSql(db, where, opt = {}) {
         const tim = lTime.stamp();
         const sq = lSql.get(opt.pre);
         if (this._$soft && !opt.raw) {
+            // --- 软删除 ---
             sq.update(this._$table + (opt.index ? ('_' + opt.index) : ''), [{
                     'time_remove': tim
                 }]);
@@ -262,6 +330,7 @@ class Mod {
             }
         }
         else {
+            // --- 真删除 ---
             sq.delete(this._$table + (opt.index ? ('_' + opt.index) : ''));
         }
         sq.where(where);
@@ -273,6 +342,13 @@ class Mod {
         }
         return sq;
     }
+    /**
+     * --- 根据条件更新数据 ---
+     * @param db 数据库对象
+     * @param data 要更新的数据
+     * @param where 筛选条件
+     * @param opt 选项
+     */
     static async updateByWhere(db, data, where, opt = {}) {
         if (typeof opt.index === 'string') {
             opt.index = [opt.index];
@@ -323,6 +399,12 @@ class Mod {
         }
         return ar ? ar : null;
     }
+    /**
+     * --- 根据条件更新数据（仅获取 SQL 对象） ---
+     * @param data 要更新的数据
+     * @param where 筛选条件
+     * @param opt 选项
+     */
     static updateByWhereSql(data, where, opt = {}) {
         const sq = lSql.get(opt.pre);
         sq.update(this._$table + (opt.index ? ('_' + opt.index) : ''), data);
@@ -348,6 +430,12 @@ class Mod {
         }
         return sq;
     }
+    /**
+     * --- select 自定字段 ---
+     * @param db 数据库对象
+     * @param c 字段字符串或字段数组
+     * @param opt 选项
+     */
     static select(db, c, opt = {}) {
         return new this({
             'db': db,
@@ -359,6 +447,12 @@ class Mod {
             'contain': opt.contain
         });
     }
+    /**
+     * --- 通过 where 条件获取模型 ---
+     * @param db 数据库对象
+     * @param s 筛选条件数组或字符串
+     * @param opt 选项
+     */
     static where(db, s = '', opt = {}) {
         return new this({
             'db': db,
@@ -370,6 +464,11 @@ class Mod {
             'contain': opt.contain
         });
     }
+    /**
+     * --- 获取创建对象，通常用于新建数据库条目 ---
+     * @param db 数据库对象
+     * @param opt 选项
+     */
     static getCreate(db, opt = {}) {
         return new this({
             'db': db,
@@ -378,6 +477,13 @@ class Mod {
             'index': opt.index
         });
     }
+    /**
+     * --- 根据主键获取对象 ---
+     * @param db 数据库对象
+     * @param val 主键值
+     * @param lock 是否加锁
+     * @param opt 选项
+     */
     static find(db, val, opt = {}) {
         return new this({
             'db': db,
@@ -390,6 +496,12 @@ class Mod {
             'index': opt.index
         }).first(opt.lock);
     }
+    /**
+     * --- 通过 where 条件筛选单条数据 ---
+     * @param db 数据库对象
+     * @param s 筛选条件数组或字符串
+     * @param opt 选项
+     */
     static async one(db, s, opt = {}) {
         if (!opt.index) {
             const o = new this({
@@ -426,16 +538,30 @@ class Mod {
             if (rowr === false) {
                 return false;
             }
+            // --- 如果是 null 再去下个 index 找一下 ---
         }
         return null;
     }
+    /**
+     * --- 通过 where 条件筛选单条数据返回原生对象 ---
+     * @param db 数据库对象
+     * @param s 筛选条件数组或字符串
+     * @param opt 选项
+     */
     static async oneArray(db, s, opt = {}) {
         opt.array = true;
         return this.one(db, s, opt);
     }
+    /**
+     * --- 根据 where 条件获取主键值列表 ---
+     * @param db 数据库对象
+     * @param where where 条件
+     * @param opt 选项
+     */
     static async primarys(db, where = '', opt = {}) {
         const sq = lSql.get(opt.pre ?? opt.ctr);
         if (this._$soft && !opt.raw) {
+            // --- 不包含已删除 ---
             if (typeof where === 'string') {
                 if (where !== '') {
                     where = '(' + where + ') AND `time_remove` = 0';
@@ -470,6 +596,10 @@ class Mod {
         }
         return primarys;
     }
+    /**
+     * --- 将 key val 组成的数据列表转换为原生对象模式 ---
+     * @param obj 要转换的 kv 数据列表
+     */
     static toArrayByRecord(obj) {
         const rtn = {};
         for (const key in obj) {
@@ -477,19 +607,27 @@ class Mod {
         }
         return rtn;
     }
+    /**
+     * --- 设置一个/多个属性 ---
+     * @param n 字符串或键/值
+     * @param v 可能是数字
+     */
     set(n, v) {
         if (typeof n === 'object') {
+            // --- { x: y } ---
             for (const k in n) {
                 const v = n[k];
                 if (v === undefined) {
                     continue;
                 }
+                // --- 强制更新，因为有的可能就是要强制更新既然设置了 ---
                 this._updates[k] = true;
                 this._data[k] = v;
                 this[k] = v;
             }
         }
         else {
+            // --- x, y ---
             if (v === undefined) {
                 return;
             }
@@ -501,9 +639,18 @@ class Mod {
             this[n] = v;
         }
     }
+    /**
+     * --- 获取一个字段值
+     * @param n 字段名
+     */
     get(n) {
         return this._data[n];
     }
+    /**
+     * --- 创建数据 ---
+     * @param notWhere 若要不存在才成功，则要传入限定条件
+     * @param table 可对限定条件传入适当的表
+     */
     async create(notWhere, table) {
         const cstr = this.constructor;
         const updates = {};
@@ -583,6 +730,9 @@ class Mod {
             return false;
         }
     }
+    /**
+     * --- 唯一键冲突则替换，不冲突则创建数据 ---
+     */
     async replace() {
         const cstr = this.constructor;
         const updates = {};
@@ -613,6 +763,10 @@ class Mod {
             return false;
         }
     }
+    /**
+     * --- 刷新当前模型获取最新数据 ---
+     * @param lock 是否加锁
+     */
     async refresh(lock = false) {
         const cstr = this.constructor;
         this._sql.select('*', cstr._$table + (this._index ? ('_' + this._index[0]) : '')).where([{
@@ -644,6 +798,9 @@ class Mod {
         }
         return true;
     }
+    /**
+     * --- 更新 set 的数据到数据库，有未保存数据时才保存 ---
+     */
     async save() {
         if (Object.keys(this._updates).length === 0) {
             return true;
@@ -677,6 +834,10 @@ class Mod {
             return false;
         }
     }
+    /**
+     * --- 移除本条目 ---
+     * @param raw 是否真实移除
+     */
     async remove(raw = false) {
         const tim = lTime.stamp();
         const cstr = this.constructor;
@@ -713,6 +874,11 @@ class Mod {
             return false;
         }
     }
+    /**
+     * --- 获取数据库第一个对象 ---
+     * @param lock 是否加锁
+     * @param array 是否返回原生对象
+     */
     async first(lock = false, array = false) {
         this._sql.limit(1);
         if (lock) {
@@ -744,9 +910,18 @@ class Mod {
         }
         return this;
     }
+    /**
+     * --- 获取数据库第一个原生对象 ---
+     * @param lock 是否加锁
+     */
     async firstArray(lock = false) {
         return this.first(lock, true);
     }
+    /**
+     * --- 联合查询表数据 ---
+     * @param f 要联合查询的表列表、单个表、sql 对象
+     * @param type 类型
+     */
     union(f, type = '') {
         if (f instanceof lSql.Sql) {
             this._sql.union(f, type);
@@ -772,6 +947,10 @@ class Mod {
         }
         return this;
     }
+    /**
+     * --- 所有联合查询表数据 ---
+     * @param f 要联合查询的表列表、单个表、sql 对象
+     */
     unionAll(f) {
         if (f instanceof lSql.Sql) {
             this._sql.unionAll(f);
@@ -797,15 +976,25 @@ class Mod {
         }
         return this;
     }
+    /**
+     * --- 获取列表 ---
+     * @param key 是否以某个字段为主键
+     */
     async all(key) {
         this._total.length = 0;
         if (this._index && this._index.length > 1) {
+            // --- 多表 ---
             let sql = this._sql.getSql();
+            /** --- 返回的最终 list --- */
             const list = key ? {} : [];
+            /** --- 用户传输的起始值 --- */
             const limit = [this._limit[0] ?? 0, this._limit[1] ?? 200];
+            /** --- 已过的 offset，-1 代表不再计算 offset 了 --- */
             let offset = 0;
+            /** --- 剩余条数 --- */
             let remain = limit[1];
             for (let i = 0; i < this._index.length; ++i) {
+                // --- 先计算 total ---
                 if (i > 0) {
                     sql = sql.replace(/(FROM [a-zA-Z0-9`_.]+?_)[0-9_]+/, '$1' + this._index[i]);
                 }
@@ -820,8 +1009,11 @@ class Mod {
                 }
                 this._total.push(count);
                 if (remain === 0) {
+                    // --- 下一个表需要接着执行 total 计算，所以不能 break ---
                     continue;
                 }
+                // --- 开始查数据 ---
+                /** --- 差值 --- */
                 let cz = 0;
                 if (offset > -1) {
                     cz = limit[0] - offset;
@@ -873,6 +1065,7 @@ class Mod {
             }
             return Array.isArray(list) ? new Rows(list) : list;
         }
+        // --- 单表 ---
         const contain = this._contain ? lCore.clone(this._contain.list) : null;
         const r = await this._db.query(this._sql.getSql(), this._sql.getData());
         if (r.rows === null) {
@@ -887,6 +1080,7 @@ class Mod {
             }, '[all, mod] ' + lText.stringifyJson(r.error?.message ?? '').slice(1, -1).replace(/"/g, '""'), '-error');
             return false;
         }
+        // --- 检查没被查到的必包含项 ---
         for (const row of r.rows) {
             if (this._contain && contain) {
                 const io = contain.indexOf(row[this._contain.key]);
@@ -916,6 +1110,7 @@ class Mod {
                 });
                 list[row[key]] = obj;
             }
+            // --- 有没有必须包含的项 ---
             if (cr?.rows) {
                 for (const crow of cr.rows) {
                     const obj = new this.constructor({
@@ -941,6 +1136,7 @@ class Mod {
             });
             list.push(obj);
         }
+        // --- 有没有必须包含的项 ---
         if (cr?.rows) {
             for (const crow of cr.rows) {
                 const obj = new this.constructor({
@@ -955,15 +1151,25 @@ class Mod {
         }
         return new Rows(list);
     }
+    /**
+     * --- 获取列表（得到的为原生对象或数组，不是模型） ---
+     * @param key 是否以某个字段为主键
+     */
     async allArray(key) {
         this._total.length = 0;
         if (this._index && this._index.length > 1) {
+            // --- 多表 ---
             let sql = this._sql.getSql();
+            /** --- 返回的最终 list --- */
             const list = key ? {} : [];
+            /** --- 用户传输的起始值 --- */
             const limit = [this._limit[0] ?? 0, this._limit[1] ?? 200];
+            /** --- 已过的 offset，-1 代表不再计算 offset 了 --- */
             let offset = 0;
+            /** --- 剩余条数 --- */
             let remain = limit[1];
             for (let i = 0; i < this._index.length; ++i) {
+                // --- 先计算 total ---
                 if (i > 0) {
                     sql = sql.replace(/(FROM [a-zA-Z0-9`_.]+?_)[0-9_]+/, '$1' + this._index[i]);
                 }
@@ -978,8 +1184,11 @@ class Mod {
                 }
                 this._total.push(count);
                 if (remain === 0) {
+                    // --- 下一个表需要接着执行 total 计算，所以不能 break ---
                     continue;
                 }
+                // --- 开始查数据 ---
+                /** --- 差值 --- */
                 let cz = 0;
                 if (offset > -1) {
                     cz = limit[0] - offset;
@@ -987,6 +1196,7 @@ class Mod {
                         offset += count;
                         continue;
                     }
+                    // --- 在本表开始找之后，后面表无需再跳过 ---
                     offset = -1;
                 }
                 const lsql = sql.replace(/ LIMIT [0-9 ,]+/g, ` LIMIT ${cz}, ${remain}`);
@@ -1018,6 +1228,7 @@ class Mod {
             }
             return list;
         }
+        // --- 单表 ---
         const contain = this._contain ? lCore.clone(this._contain.list) : null;
         const r = await this._db.query(this._sql.getSql(), this._sql.getData());
         if (r.rows === null) {
@@ -1032,6 +1243,7 @@ class Mod {
             }, '[allArray, mod] ' + lText.stringifyJson(r.error?.message ?? '').slice(1, -1).replace(/"/g, '""'), '-error');
             return false;
         }
+        // --- 检查没被查到的必包含项 ---
         for (const row of r.rows) {
             if (this._contain && contain) {
                 const io = contain.indexOf(row[this._contain.key]);
@@ -1054,6 +1266,7 @@ class Mod {
             for (const row of r.rows) {
                 list[row[key]] = row;
             }
+            // --- 有没有必须包含的项 ---
             if (cr?.rows) {
                 for (const crow of cr.rows) {
                     list[crow[key]] = crow;
@@ -1061,6 +1274,7 @@ class Mod {
             }
             return list;
         }
+        // --- 有没有必须包含的项 ---
         if (cr?.rows) {
             for (const crow of cr.rows) {
                 r.rows.push(crow);
@@ -1068,6 +1282,10 @@ class Mod {
         }
         return r.rows;
     }
+    /**
+     * --- 获取数查询（SELECT）扫描情况，获取字符串或kv数组 ---
+     * @param all 是否获取完全的情况，默认不获取，只返回扫描情况
+     */
     async explain(all = false) {
         const r = await this._db.query('EXPLAIN ' + this._sql.getSql(), this._sql.getData());
         if (r.rows === null) {
@@ -1100,6 +1318,9 @@ class Mod {
         return sql
             .replace(/SELECT .+? FROM/g, 'SELECT COUNT(' + this._sql.field(f) + ') AS `count` FROM');
     }
+    /**
+     * --- 获取总条数，自动抛弃 LIMIT，仅用于获取数据的情况（select） ---
+     */
     async total(f = '*') {
         if (this._total.length) {
             let count = 0;
@@ -1128,6 +1349,9 @@ class Mod {
         }
         return count;
     }
+    /**
+     * --- 根据当前条件，筛选出当前条目该有的数据条数 ---
+     */
     async count() {
         const sql = this._sql.getSql().replace(/SELECT .+? FROM/, 'SELECT COUNT(*) AS `count` FROM');
         const r = await this._db.query(sql, this._sql.getData());
@@ -1149,34 +1373,80 @@ class Mod {
         }
         return count;
     }
+    /**
+     * @param f 表名
+     * @param s ON 信息
+     * @param type 类型
+     * @param index 给本表增加 index 分表项
+     * @param pre 前缀
+     */
     join(f, s = [], type = 'INNER', index = '', pre = '') {
         this._sql.join(f, s, type, index ? '_' + index : '', pre);
         return this;
     }
+    /**
+     * --- left join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param index 给本表增加 index 分表项
+     */
     leftJoin(f, s, index = '', pre = '') {
         this._sql.leftJoin(f, s, index ? '_' + index : '', pre);
         return this;
     }
+    /**
+     * --- right join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param index 给本表增加 index 分表项
+     */
     rightJoin(f, s, index = '', pre = '') {
         this._sql.rightJoin(f, s, index ? '_' + index : '', pre);
         return this;
     }
+    /**
+     * --- inner join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param index 给本表增加 index 分表项
+     */
     innerJoin(f, s, index = '', pre = '') {
         this._sql.innerJoin(f, s, index ? '_' + index : '', pre);
         return this;
     }
+    /**
+     * --- full join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param index 给本表增加 index 分表项
+     */
     fullJoin(f, s, index = '', pre = '') {
         this._sql.fullJoin(f, s, index ? '_' + index : '', pre);
         return this;
     }
+    /**
+     * --- cross join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param index 给本表增加 index 分表项
+     */
     crossJoin(f, s, index = '', pre = '') {
         this._sql.crossJoin(f, s, index ? '_' + index : '', pre);
         return this;
     }
+    /**
+     * --- 筛选器 ---
+     * @param s 筛选条件数组或字符串
+     */
     having(s) {
         this._sql.having(s);
         return this;
     }
+    /**
+     * --- 筛选器 ---
+     * @param s 筛选条件数组或字符串
+     * @param raw 是否包含已被软删除的数据
+     */
     filter(s, raw = false) {
         const cstr = this.constructor;
         if (cstr._soft && !raw) {
@@ -1195,48 +1465,97 @@ class Mod {
         this._sql.where(s);
         return this;
     }
+    /**
+     * --- 是 filter 的别名 ---
+     * @param s 筛选条件数组或字符串
+     * @param raw 是否包含已被软删除的数据
+     */
     where(s, raw = false) {
         return this.filter(s, raw);
     }
+    /**
+     * --- ORDER BY ---
+     * @param c 字段字符串或数组
+     * @param d 排序规则
+     */
     by(c, d = 'DESC') {
         this._sql.by(c, d);
         return this;
     }
+    /**
+     * --- GROUP BY ---
+     * @param c 字段字符串或数组
+     */
     group(c) {
         this._sql.group(c);
         return this;
     }
+    /**
+     * --- LIMIT ---
+     * @param a 起始
+     * @param b 长度
+     */
     limit(a, b = 0) {
         this._sql.limit(a, b);
         this._limit = [a, b];
         return this;
     }
+    /**
+     * --- 分页 ---
+     * @param count 每页条数
+     * @param page 当前页数
+     */
     page(count, page = 1) {
         const a = count * (page - 1);
         this._sql.limit(a, count);
         this._limit = [a, count];
         return this;
     }
+    /**
+     * --- 在 sql 最后追加字符串 ---
+     * @param sql
+     */
     append(sql) {
         this._sql.append(sql);
         return this;
     }
+    /**
+     * --- 设置闭包含数据 ---
+     * @param contain 设置项
+     */
     contain(contain) {
         this._contain = contain;
         return this;
     }
+    /**
+     * --- 获取 sql 语句 ---
+     */
     getSql() {
         return this._sql.getSql();
     }
+    /**
+     * --- 获取全部 data ---
+     */
     getData() {
         return this._sql.getData();
     }
+    /**
+     * --- 获取带 data 的 sql 语句 ---
+     * @param sql sql 语句
+     * @param data 数据
+     */
     format(sql, data) {
         return this._sql.format(sql, data);
     }
+    /**
+     * --- 获取值对象 ---
+     */
     toArray() {
         return this._data;
     }
+    /**
+     * --- 获取当前设置要提交的数据 ---
+     */
     updates() {
         const updates = {};
         for (const k in this._updates) {
@@ -1244,9 +1563,17 @@ class Mod {
         }
         return updates;
     }
+    /**
+     * --- 当前是否设置了未保存 --=
+     */
     unsaved() {
         return Object.keys(this._updates).length ? true : false;
     }
+    /**
+     * --- 获取字段的可用语种文本 ---
+     * @param col 字段名
+     * @param lang 当前请求语种，如 sc
+     */
     langText(col, lang) {
         const key = `${col}_${lang}`;
         if (this._data[key]) {
@@ -1257,17 +1584,25 @@ class Mod {
         }
         for (const k in this._data) {
             if (k.startsWith(`${col}_`) && this._data[k]) {
+                // --- 符合要求的字段并且字段有值（不为空） ---
                 return this._data[k];
             }
         }
         return '';
     }
+    /**
+     * --- 当 _key 不为空时，则依据继承此方法的方法自动生成填充 key ---
+     */
     _keyGenerator() {
         return '';
     }
 }
+/** --- 表名 --- */
 Mod._$table = '';
+/** --- 主键字段名 --- */
 Mod._$primary = 'id';
+/** --- 设置后将由 _keyGenerator 函数生成唯一字段 --- */
 Mod._$key = '';
+/** ---- 可开启软删软更新软新增 --- */
 Mod._$soft = false;
 exports.default = Mod;