@maiyunnet/kebab 5.3.1 → 6.1.0

package/lib/text.js

@@ -205,7 +205,7 @@ export function isIPv6(ip) {
 export const REGEXP_DOMAIN = /^.+?\.((?![0-9]).)+$/i;
 /**
  * --- 判断是否是域名 ---
- * @param string $domain
+ * @param domain 域名
  * @return bool
  */
 export function isDomain(domain) {
@@ -432,7 +432,7 @@ export function getFilename(path) {
 }
 /**
  * --- 将普通的返回 JSON 对象序列化为字符串 ---
- * @param o 返回 JSON 对象
+ * @param rtn 返回 JSON 对象
  */
 export function stringifyResult(rtn) {
     if (Array.isArray(rtn)) {

package/lib/vector.d.ts

@@ -66,6 +66,6 @@ export declare class Vector {
 }
 /**
  * --- 创建一个 Vector 对象 ---
- * @param opt 选项
+ * @param ctrEtc 控制器或配置信息
  */
 export declare function get(ctrEtc: sCtr.Ctr | kebab.IConfigVector): Vector;

package/lib/vector.js

@@ -31,8 +31,8 @@ export class Vector {
             return res;
         }
         catch (e) {
-            lCore.log({}, '[VECTOR][seach][error] ' + e.message, '-error');
-            lCore.debug('[VECTOR][seach]', e.code, e.message);
+            lCore.log({}, '[VECTOR][seach][error] ' + (e.status?.reason ?? ''), '-error');
+            lCore.debug('[VECTOR][seach]', e);
             return false;
         }
     }
@@ -50,8 +50,8 @@ export class Vector {
             return res;
         }
         catch (e) {
-            lCore.log({}, '[VECTOR][insert][error] ' + e.message, '-error');
-            lCore.debug('[VECTOR][insert]', e.code, e.message);
+            lCore.log({}, '[VECTOR][insert][error] ' + (e.status?.reason ?? ''), '-error');
+            lCore.debug('[VECTOR][insert]', e);
             return false;
         }
     }
@@ -69,8 +69,8 @@ export class Vector {
             return res;
         }
         catch (e) {
-            lCore.log({}, '[VECTOR][delete][error] ' + e.message, '-error');
-            lCore.debug('[VECTOR][delete]', e.code, e.message);
+            lCore.log({}, '[VECTOR][delete][error] ' + (e.status?.reason ?? ''), '-error');
+            lCore.debug('[VECTOR][delete]', e);
             return false;
         }
     }
@@ -107,7 +107,7 @@ export class Vector {
 }
 /**
  * --- 创建一个 Vector 对象 ---
- * @param opt 选项
+ * @param ctrEtc 控制器或配置信息
  */
 export function get(ctrEtc) {
     if (ctrEtc instanceof sCtr.Ctr) {

package/lib/ws.d.ts

@@ -166,6 +166,5 @@ export declare function rproxy(ctr: sCtr.Ctr, url: string, opt?: IRproxyOptions)
  * @param ctr 当前控制器
  * @param host 反代真实请求地址
  * @param port 反代真实请求端口
- * @param opt 参数
  */
 export declare function rsocket(ctr: sCtr.Ctr, host: string, port: number): Promise<boolean>;

package/lib/ws.js

@@ -418,7 +418,6 @@ export async function rproxy(ctr, url, opt = {}) {
  * @param ctr 当前控制器
  * @param host 反代真实请求地址
  * @param port 反代真实请求端口
- * @param opt 参数
  */
 export async function rsocket(ctr, host, port) {
     return new Promise(resolve => {

package/lib/zip.d.ts

@@ -29,7 +29,6 @@ export declare class Zip {
     /**
      * --- 获取对象是否存在，存在则返回 stats 对象，否则返回 null ---
      * @param path 对象路径
-     * @param options 选项
      */
     stats(path: string): IZipStats | null;
     /**

package/lib/zip.js

@@ -58,7 +58,6 @@ export class Zip {
     /**
      * --- 获取对象是否存在，存在则返回 stats 对象，否则返回 null ---
      * @param path 对象路径
-     * @param options 选项
      */
     stats(path) {
         path = lText.urlResolve(this._path, path);

package/lib/zlib.d.ts

@@ -49,8 +49,7 @@ export declare function createBrotliDecompress(): zlib.BrotliDecompress;
 export declare function createCompress(types: string, options?: zlib.ZlibOptions): ICompress | null;
 /**
  * --- 根据字符串创建解压类型 ---
- * @param types 用 , 间隔的字符串，如 gzip,deflate
- * @param options 选项
+ * @param types 用 , 间隔的字符串，如 gzip, deflate
  */
 export declare function createDecompress(types: string): ICompress | null;
 /**

package/lib/zlib.js

@@ -81,8 +81,7 @@ export function createCompress(types, options = {}) {
 }
 /**
  * --- 根据字符串创建解压类型 ---
- * @param types 用 , 间隔的字符串，如 gzip,deflate
- * @param options 选项
+ * @param types 用 , 间隔的字符串，如 gzip, deflate
  */
 export function createDecompress(types) {
     const type = getTypeByTypes(types);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maiyunnet/kebab",
-  "version": "5.3.1",
+  "version": "6.1.0",
   "description": "Simple, easy-to-use, and fully-featured Node.js framework that is ready-to-use out of the box.",
   "type": "module",
   "keywords": [
@@ -12,6 +12,9 @@
   "author": "hanguoshuai",
   "license": "Apache-2.0",
   "types": "./index.d.ts",
+  "scripts": {
+    "build-md-doc": "bash ./utils/generate-api-doc-md.sh"
+  },
   "bin": {
     "kebab": "./bin/kebab.js"
   },
@@ -19,29 +22,31 @@
     "#kebab/*": "./*"
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.927.0",
-    "@aws-sdk/lib-storage": "^3.927.0",
+    "@aws-sdk/client-s3": "^3.939.0",
+    "@aws-sdk/lib-storage": "^3.939.0",
     "@litert/http-client": "^1.1.2",
     "@litert/mime": "^0.1.3",
-    "@litert/redis": "^3.0.5",
+    "@litert/redis": "^3.0.6",
     "@litert/websocket": "^0.2.8",
     "@types/ssh2": "^1.15.5",
-    "@zilliz/milvus2-sdk-node": "^2.6.4",
+    "@zilliz/milvus2-sdk-node": "^2.6.5",
     "ejs": "^3.1.10",
     "jszip": "^3.10.1",
     "mysql2": "^3.15.3",
     "node-cron": "^4.2.1",
-    "openai": "^6.8.1",
+    "openai": "^6.9.1",
     "pg": "^8.16.3",
     "ssh2": "^1.17.0",
     "svg-captcha": "^1.4.0",
-    "tencentcloud-sdk-nodejs": "^4.1.140"
+    "tencentcloud-sdk-nodejs": "^4.1.149"
   },
   "devDependencies": {
     "@litert/eslint-plugin-rules": "^0.3.1",
     "@types/ejs": "^3.1.5",
-    "@types/node": "^24.10.0",
+    "@types/node": "^24.10.1",
     "@types/pg": "^8.15.6",
+    "typedoc": "^0.28.14",
+    "typedoc-plugin-markdown": "^4.9.0",
     "typescript": "^5.9.3"
   }
 }

package/sys/cmd.js

@@ -115,13 +115,6 @@ async function run() {
         config.db['PGSQL'].read.name ??= 'maiyun';
         config.db['PGSQL'].read.user ??= 'root';
         config.db['PGSQL'].read.pwd ??= 'DashAdmin';
-        // --- config - jwt ---
-        config.jwt ??= {};
-        config.jwt.name ??= 'KE_JWT';
-        config.jwt.ttl ??= 172800;
-        config.jwt.ssl ??= false;
-        config.jwt.secret ??= 'MUSTCHANGE';
-        config.jwt.auth ??= false;
         // --- config - dns ---
         config.dns ??= {};
         config.dns['DNSPOD'] ??= {};

package/sys/ctr.d.ts

@@ -33,8 +33,6 @@ export declare class Ctr {
     protected _files: Record<string, kebab.IPostFile | kebab.IPostFile[]>;
     /** --- Cookie 数组 --- */
     protected _cookie: Record<string, string>;
-    /** --- Jwt 数组 --- */
-    protected _jwt: Record<string, any>;
     /** --- Session 数组 --- */
     protected _session: Record<string, any>;
     /** --- Session --- 对象 */

package/sys/ctr.js

@@ -37,8 +37,6 @@ export class Ctr {
         this._files = {};
         /** --- Cookie 数组 --- */
         this._cookie = {};
-        /** --- Jwt 数组 --- */
-        this._jwt = {};
         /** --- Session 数组 --- */
         this._session = {};
         /** --- Session --- 对象 */

package/sys/mod.d.ts

@@ -8,11 +8,11 @@ import * as lDb from '#kebab/lib/db.js';
 import * as sCtr from '#kebab/sys/ctr.js';
 import * as kebab from '#kebab/index.js';
 /** --- 只获取变量 --- */
-type TOnlyProperties<T> = {
+export type TOnlyProperties<T> = {
     [K in keyof T as T[K] extends (...args: any[]) => any ? never : K]: T[K];
 };
 /** --- 条数列表 --- */
-declare class Rows<T extends Mod> implements IRows<T> {
+export declare class Rows<T extends Mod> implements IRows<T> {
     private readonly _items;
     constructor(initialItems?: T[]);
     /** --- 总行数 --- */
@@ -63,7 +63,6 @@ export default class Mod {
     protected _ctr?: sCtr.Ctr;
     /**
      * --- 构造函数 ---
-     * @param ctr Ctr 对象
      * @param opt 选项
      */
     constructor(opt: {
@@ -170,6 +169,18 @@ export default class Mod {
         'by'?: [string | string[], 'DESC' | 'ASC'];
         'limit'?: [number, number?];
     }): lSql.Sql;
+    /**
+     * --- 批量更新数据 ---
+     * @param db 数据库对象
+     * @param data 数据列表
+     * @param key 用于定位的主键或唯一键字段名
+     * @param opt 选项
+     */
+    static updateList(db: lDb.Pool | lDb.Transaction, data: Array<Record<string, any>>, key: string, opt?: {
+        'ctr'?: sCtr.Ctr;
+        'pre'?: string;
+        'index'?: string;
+    }): Promise<boolean | null>;
     /**
      * --- select 自定字段 ---
      * @param db 数据库对象
@@ -217,7 +228,6 @@ export default class Mod {
      * --- 根据主键（或 key 字段）获取对象 ---
      * @param db 数据库对象
      * @param val 主键值
-     * @param lock 是否加锁
      * @param opt 选项
      */
     static find<T extends Mod>(db: lDb.Pool | lDb.Transaction, val: string | number | null, opt?: {
@@ -286,8 +296,14 @@ export default class Mod {
     get(n: string): any;
     /**
      * --- 创建数据 ---
+     * @return true-成功,false-报错,null-唯一键非 _$key 键冲突
+     */
+    create(): Promise<boolean | null>;
+    /**
+     * --- 插入数据，如果存在则更新（UPSERT） ---
+     * @param conflict 冲突字段，不能为 _$key 或 _$primary，应该是你要判断的唯一索引字段
      */
-    create(): Promise<boolean>;
+    upsert(conflict: string | string[]): Promise<boolean>;
     /**
      * --- 刷新当前模型获取最新数据 ---
      * @param lock 是否加锁
@@ -295,8 +311,9 @@ export default class Mod {
     refresh(lock?: boolean): Promise<boolean | null>;
     /**
      * --- 更新 set 的数据到数据库，有未保存数据时才保存 ---
+     * @param where 自定义筛选条件，默认根据主键筛选
      */
-    save(): Promise<boolean>;
+    save(where?: any): Promise<boolean>;
     /**
      * --- 移除本条目 ---
      */
@@ -394,13 +411,11 @@ export default class Mod {
     /**
      * --- 筛选器 ---
      * @param s 筛选条件数组或字符串
-     * @param raw 是否包含已被软删除的数据
      */
     filter(s: kebab.Json): this;
     /**
      * --- 是 filter 的别名 ---
      * @param s 筛选条件数组或字符串
-     * @param raw 是否包含已被软删除的数据
      */
     where(s: kebab.Json): this;
     /**
@@ -487,4 +502,3 @@ export interface IModUnionItem {
     'field': string;
     'where'?: any;
 }
-export {};

package/sys/mod.js

@@ -8,7 +8,7 @@ import * as lDb from '#kebab/lib/db.js';
 import * as lCore from '#kebab/lib/core.js';
 import * as lText from '#kebab/lib/text.js';
 /** --- 条数列表 --- */
-class Rows {
+export class Rows {
     constructor(initialItems = []) {
         this._items = initialItems;
     }
@@ -57,7 +57,6 @@ export default class Mod {
     static { this._$pre = null; }
     /**
      * --- 构造函数 ---
-     * @param ctr Ctr 对象
      * @param opt 选项
      */
     constructor(opt) {
@@ -274,6 +273,78 @@ export default class Mod {
         }
         return sq;
     }
+    /**
+     * --- 批量更新数据 ---
+     * @param db 数据库对象
+     * @param data 数据列表
+     * @param key 用于定位的主键或唯一键字段名
+     * @param opt 选项
+     */
+    static async updateList(db, data, key, opt = {}) {
+        if (!data.length) {
+            return true;
+        }
+        // --- 获取所有涉及的字段（除了 key） ---
+        const columns = new Set();
+        for (const item of data) {
+            for (const k in item) {
+                if (k !== key) {
+                    columns.add(k);
+                }
+            }
+        }
+        if (columns.size === 0) {
+            return true;
+        }
+        const cols = Array.from(columns);
+        // --- 计算分批大小 ---
+        // --- 每个字段需要 2 个占位符 (WHEN ? THEN ?)，加上 WHERE IN (?) 的 1 个 ---
+        // --- Total params per row = cols.length * 2 + 1 ---
+        const paramCountPerRow = cols.length * 2 + 1;
+        const batchSize = Math.floor(60000 / paramCountPerRow);
+        const batches = [];
+        for (let i = 0; i < data.length; i += batchSize) {
+            batches.push(data.slice(i, i + batchSize));
+        }
+        for (const batch of batches) {
+            const sq = lSql.get(opt.pre ?? this._$pre ?? opt.ctr, {
+                'service': db.getService() ?? lDb.ESERVICE.PGSQL,
+            });
+            const updates = {};
+            const keys = [];
+            for (const col of cols) {
+                let caseSql = `(CASE ${sq.field(key)}`;
+                const params = [];
+                let hasUpdate = false;
+                for (const item of batch) {
+                    if (item[col] !== undefined) {
+                        caseSql += ` WHEN ? THEN ?`;
+                        params.push(item[key], item[col]);
+                        hasUpdate = true;
+                    }
+                }
+                if (hasUpdate) {
+                    caseSql += ` ELSE ${sq.field(col)} END)`;
+                    updates[col] = [caseSql, params];
+                }
+            }
+            // --- 收集 keys ---
+            for (const item of batch) {
+                keys.push(item[key]);
+            }
+            if (Object.keys(updates).length === 0) {
+                continue;
+            }
+            sq.update(this._$table + (opt.index ? ('_' + opt.index) : ''), updates)
+                .where({ [key]: keys });
+            const r = await db.execute(sq.getSql(), sq.getData());
+            if (r.packet === null) {
+                lCore.log(opt.ctr ?? {}, '[MOD][updateList] ' + lText.stringifyJson(r.error?.message ?? '').slice(1, -1).replace(/"/g, '""'), '-error');
+                return false;
+            }
+        }
+        return true;
+    }
     /**
      * --- select 自定字段 ---
      * @param db 数据库对象
@@ -326,7 +397,6 @@ export default class Mod {
      * --- 根据主键（或 key 字段）获取对象 ---
      * @param db 数据库对象
      * @param val 主键值
-     * @param lock 是否加锁
      * @param opt 选项
      */
     static async find(db, val, opt = {}) {
@@ -436,7 +506,7 @@ export default class Mod {
         return rtn;
     }
     /**
-     * --- 设置一个/多个属性，值为 underfind 则不会被更新 ---
+     * --- 设置一个/多个属性，值为 undefined 则不会被更新 ---
      * @param n 字符串或键/值
      * @param v 可能是数字
      */
@@ -476,6 +546,7 @@ export default class Mod {
     }
     /**
      * --- 创建数据 ---
+     * @return true-成功,false-报错,null-唯一键非 _$key 键冲突
      */
     async create() {
         const cstr = this.constructor;
@@ -510,6 +581,7 @@ export default class Mod {
                         // --- MYSQL ---
                         const match = /for key '([\w.]+)'/.exec(r.error.message);
                         if (match?.[1].includes(cstr._$index)) {
+                            // --- key 索引重复，继续生成 key ---
                             continue;
                         }
                     }
@@ -517,11 +589,12 @@ export default class Mod {
                         // --- PGSQL ---
                         const match = /constraint "([\w.]+)"/.exec(r.error.message);
                         if (match?.[1].includes(cstr._$index)) {
+                            // --- key 索引重复，继续生成 key ---
                             continue;
                         }
                     }
                     // --- 1062 非 index 冲突，那需要用户自行处理（可能不允许重复的邮箱） ---
-                    return false;
+                    return null;
                 }
                 // --- 未处理的错误 ---
                 const service = this._db.getService();
@@ -538,8 +611,9 @@ export default class Mod {
                 if (r.error.errno !== 1062) {
                     lCore.debug('[MOD][create1][' + cstr._$table + ']', r);
                     lCore.log(this._ctr ?? {}, '[MOD][create1][' + cstr._$table + '] ' + lText.stringifyJson(r.error?.message ?? '').slice(1, -1).replace(/"/g, '""'), '-error');
+                    return false;
                 }
-                return false;
+                return null;
             }
         }
         if (r.packet?.affected) {
@@ -552,6 +626,35 @@ export default class Mod {
             return false;
         }
     }
+    /**
+     * --- 插入数据，如果存在则更新（UPSERT） ---
+     * @param conflict 冲突字段，不能为 _$key 或 _$primary，应该是你要判断的唯一索引字段
+     */
+    async upsert(conflict) {
+        // --- 这里没用 mysql 的 INSERT ... ON DUPLICATE KEY UPDATE 或 pgsql 的 ON CONFLICT DO UPDATE ---
+        // --- 因为还要处理 _$key 的自动生成 ---
+        const res = await this.create();
+        if (res) {
+            // --- 创建成功 ---
+            return true;
+        }
+        if (res === false) {
+            // --- 系统错误 ---
+            return false;
+        }
+        // --- res === null，唯一键冲突，执行更新 ---
+        /** --- 冲突字段列表 --- */
+        const conflicts = typeof conflict === 'string' ? [conflict] : conflict;
+        const where = {};
+        for (const field of conflicts) {
+            if (!this._updates[field]) {
+                return false;
+            }
+            where[field] = this._data[field];
+            delete this._updates[field];
+        }
+        return this.save(where);
+    }
     /**
      * --- 刷新当前模型获取最新数据 ---
      * @param lock 是否加锁
@@ -581,8 +684,9 @@ export default class Mod {
     }
     /**
      * --- 更新 set 的数据到数据库，有未保存数据时才保存 ---
+     * @param where 自定义筛选条件，默认根据主键筛选
      */
-    async save() {
+    async save(where) {
         if (Object.keys(this._updates).length === 0) {
             return true;
         }
@@ -591,9 +695,9 @@ export default class Mod {
         for (const k in this._updates) {
             updates[k] = this._data[k];
         }
-        this._sql.update(cstr._$table + (this._index ? ('_' + this._index[0]) : ''), [updates]).where([{
-                [cstr._$primary]: this._data[cstr._$primary]
-            }]);
+        this._sql.update(cstr._$table + (this._index ? ('_' + this._index[0]) : ''), [updates]).where(where ?? {
+            [cstr._$primary]: this._data[cstr._$primary]
+        });
         const r = await this._db.execute(this._sql.getSql(), this._sql.getData());
         if (r.packet === null) {
             lCore.log(this._ctr ?? {}, '[MOD][save] ' + lText.stringifyJson(r.error?.message ?? '').slice(1, -1).replace(/"/g, '""'), '-error');
@@ -1158,7 +1262,6 @@ export default class Mod {
     /**
      * --- 筛选器 ---
      * @param s 筛选条件数组或字符串
-     * @param raw 是否包含已被软删除的数据
      */
     filter(s) {
         this._sql.where(s);
@@ -1167,7 +1270,6 @@ export default class Mod {
     /**
      * --- 是 filter 的别名 ---
      * @param s 筛选条件数组或字符串
-     * @param raw 是否包含已被软删除的数据
      */
     where(s) {
         return this.filter(s);

package/sys/route.js

@@ -470,7 +470,6 @@ export async function run(data) {
             cctr.setPrototype('_files', middle.getPrototype('_files'));
             cctr.setPrototype('_post', middle.getPrototype('_post'));
             cctr.setPrototype('_cookie', cookies);
-            cctr.setPrototype('_jwt', middle.getPrototype('_jwt'));
             if (!cctr.getPrototype('_sess') && middle.getPrototype('_sess')) {
                 cctr.setPrototype('_session', middle.getPrototype('_session'));
                 cctr.setPrototype('_sess', middle.getPrototype('_sess'));

package/www/example/ctr/test.d.ts

@@ -32,6 +32,8 @@ export default class extends sCtr.Ctr {
     modSplit1(): Promise<void>;
     modSplit2(): Promise<kebab.Json[]>;
     modInsert(): Promise<string>;
+    modUpsert(): Promise<string>;
+    modUpdateList(): Promise<string>;
     captchaFastbuild(): string;
     captchaBase64(): string;
     coreRandom(): string;
@@ -83,8 +85,6 @@ export default class extends sCtr.Ctr {
     scan3(): Promise<kebab.Json>;
     private _scanLink;
     session(): Promise<string | kebab.Json[]>;
-    jwt(): Promise<string | kebab.Json[]>;
-    jwt1(): Promise<[number, kebab.Json]>;
     sql(): string;
     consistentHash(): string;
     consistentDistributed(): string;