@maiyunnet/kebab 9.13.8 → 9.14.0

package/doc/kebab-rag.md

@@ -1360,7 +1360,7 @@ index/variables/VER.md
 
 # Variable: VER
 
-> `const` **VER**: `"9.13.8"` = `'9.13.8'`
+> `const` **VER**: `"9.14.0"` = `'9.14.0'`
 
 Defined in: [index.ts:10](https://github.com/maiyunnet/kebab/blob/master/index.ts#L10)
 
@@ -5420,7 +5420,7 @@ AES 解密
 
 #### key
 
-`CipherKey`
+`KeyLike`
 
 密钥 32 个英文字母和数字
 
@@ -5462,7 +5462,7 @@ AES 解密
 
 #### key
 
-`CipherKey`
+`KeyLike`
 
 密钥 32 个英文字母和数字
 
@@ -5515,7 +5515,7 @@ AES 加密
 
 #### key
 
-`CipherKey`
+`KeyLike`
 
 密钥尽量 32 个英文字母和数字，不是 32 个系统会自动处理
 
@@ -5559,7 +5559,7 @@ AES 加密
 
 #### key
 
-`CipherKey`
+`KeyLike`
 
 密钥尽量 32 个英文字母和数字，不是 32 个系统会自动处理
 
@@ -5704,7 +5704,7 @@ cipher 解密
 
 ### key
 
-`CipherKey`
+`KeyLike`
 
 密钥 32 个英文字母和数字
 
@@ -5757,7 +5757,7 @@ cipher 加密，强烈不建议使用 AES_256_ECB
 
 ### key
 
-`CipherKey`
+`KeyLike`
 
 密钥 32 个英文字母和数字
 
@@ -5812,7 +5812,7 @@ AES 解密
 
 #### key
 
-`CipherKey`
+`KeyLike`
 
 密钥 32 个英文字母和数字
 
@@ -5844,7 +5844,7 @@ AES 解密
 
 #### key
 
-`CipherKey`
+`KeyLike`
 
 密钥 32 个英文字母和数字
 
@@ -5887,7 +5887,7 @@ AES GCM 托管加密
 
 #### key
 
-`CipherKey`
+`KeyLike`
 
 密钥尽量 32 个英文字母和数字，不是 32 个系统会自动处理
 
@@ -5919,7 +5919,7 @@ AES GCM 托管加密
 
 #### key
 
-`CipherKey`
+`KeyLike`
 
 密钥尽量 32 个英文字母和数字，不是 32 个系统会自动处理
 
@@ -6033,7 +6033,7 @@ hash 或 hmac 加密文件
 
 #### key?
 
-`CipherKey`
+`KeyLike`
 
 设置则采用 hmac 加密
 
@@ -6069,7 +6069,7 @@ hash 或 hmac 加密文件
 
 #### key
 
-`CipherKey`
+`KeyLike`
 
 设置则采用 hmac 加密
 
@@ -6116,7 +6116,7 @@ hash 或 hmac 加密
 
 #### key?
 
-`CipherKey`
+`KeyLike`
 
 设置则采用 hmac 加密
 
@@ -6152,7 +6152,7 @@ hash 或 hmac 加密
 
 #### key
 
-`CipherKey` \| `undefined`
+`KeyLike` \| `undefined`
 
 设置则采用 hmac 加密
 
@@ -6185,7 +6185,7 @@ Defined in: [lib/crypto.ts:136](https://github.com/maiyunnet/kebab/blob/master/l
 
 ### key
 
-`KeyLike` \| `RsaPrivateKey`
+`KeyLike` \| `PrivateKeyInput`
 
 私钥
 
@@ -6220,7 +6220,7 @@ Defined in: [lib/crypto.ts:114](https://github.com/maiyunnet/kebab/blob/master/l
 
 ### key
 
-`KeyLike` \| `RsaPrivateKey`
+`KeyLike` \| `PrivateKeyInput`
 
 私钥
 
@@ -6255,7 +6255,7 @@ Defined in: [lib/crypto.ts:125](https://github.com/maiyunnet/kebab/blob/master/l
 
 ### key
 
-`KeyLike` \| `RsaPublicKey` \| `RsaPrivateKey`
+`KeyLike` \| `PrivateKeyInput` \| `PublicKeyInput`
 
 公钥
 
@@ -6290,7 +6290,7 @@ Defined in: [lib/crypto.ts:103](https://github.com/maiyunnet/kebab/blob/master/l
 
 ### key
 
-`KeyLike` \| `RsaPublicKey` \| `RsaPrivateKey`
+`KeyLike` \| `PrivateKeyInput` \| `PublicKeyInput`
 
 公钥
 
@@ -6327,7 +6327,7 @@ Defined in: [lib/crypto.ts:69](https://github.com/maiyunnet/kebab/blob/master/li
 
 #### data
 
-`BinaryLike`
+`string` \| `ArrayBufferView`\<`ArrayBufferLike`\>
 
 数据
 
@@ -6365,7 +6365,7 @@ Defined in: [lib/crypto.ts:72](https://github.com/maiyunnet/kebab/blob/master/li
 
 #### data
 
-`BinaryLike`
+`string` \| `ArrayBufferView`\<`ArrayBufferLike`\>
 
 数据
 
@@ -6420,7 +6420,7 @@ SM4 解密
 
 #### key
 
-`CipherKey`
+`KeyLike`
 
 密钥 32 个英文字母和数字
 
@@ -6462,7 +6462,7 @@ SM4 解密
 
 #### key
 
-`CipherKey`
+`KeyLike`
 
 密钥 32 个英文字母和数字
 
@@ -6515,7 +6515,7 @@ SM4 加密
 
 #### key
 
-`CipherKey`
+`KeyLike`
 
 密钥 32 个英文字母和数字
 
@@ -6557,7 +6557,7 @@ SM4 加密
 
 #### key
 
-`CipherKey`
+`KeyLike`
 
 密钥 32 个英文字母和数字
 
@@ -6631,7 +6631,7 @@ Defined in: [lib/crypto.ts:90](https://github.com/maiyunnet/kebab/blob/master/li
 
 ### data
 
-`BinaryLike`
+`string` \| `ArrayBufferView`\<`ArrayBufferLike`\>
 
 数据
 
@@ -8623,10 +8623,14 @@ lib/fs/functions/getContent.md
 
 ## Param
 
+**path**
+
 文件路径
 
 ## Param
 
+**options**
+
 编码或选项
 
 ## Call Signature
@@ -10720,7 +10724,7 @@ Defined in: [lib/net/formdata.ts:37](https://github.com/maiyunnet/kebab/blob/mas
 
 > **new FormData**(`options?`): `FormData`
 
-Defined in: node\_modules/@types/node/stream.d.ts:80
+Defined in: node\_modules/@types/node/stream.d.ts:81
 
 #### Parameters
 
@@ -15063,23 +15067,29 @@ lib/sql/functions/json.md
 
 # Function: json()
 
-> **json**(`obj`): `any`
+> **json**\<`T`\>(`obj`): `T`
 
 Defined in: [lib/sql.ts:1461](https://github.com/maiyunnet/kebab/blob/master/lib/sql.ts#L1461)
 
 将对象转换为 JSON 字符串并避开类型检查，用于适配 PostgreSQL 的 jsonb 字段
 
+## Type Parameters
+
+### T
+
+`T`
+
 ## Parameters
 
 ### obj
 
-`any`
+`T`
 
 要转换的 JSON 对象
 
 ## Returns
 
-`any`
+`T`
 
 lib/sql/functions/value.md
 ---
@@ -15562,10 +15572,14 @@ Defined in: [lib/ssh/sftp.ts:442](https://github.com/maiyunnet/kebab/blob/master
 
 #### Param
 
+**path**
+
 文件路径
 
 #### Param
 
+**options**
+
 编码或选项
 
 #### Call Signature
@@ -18027,7 +18041,7 @@ Defined in: [lib/undici/formdata.ts:37](https://github.com/maiyunnet/kebab/blob/
 
 > **new FormData**(`options?`): `FormData`
 
-Defined in: node\_modules/@types/node/stream.d.ts:80
+Defined in: node\_modules/@types/node/stream.d.ts:81
 
 #### Parameters
 
@@ -21155,10 +21169,14 @@ Defined in: [lib/zip.ts:350](https://github.com/maiyunnet/kebab/blob/master/lib/
 
 #### Param
 
+**path**
+
 文件路径
 
 #### Param
 
+**type**
+
 返回类型
 
 #### Call Signature
@@ -21335,10 +21353,14 @@ string
 
 #### Param
 
+**path**
+
 文件夹路径
 
 #### Param
 
+**opt**
+
 选项
 
 #### Call Signature
@@ -24152,6 +24174,8 @@ Defined in: [sys/mod.ts:1797](https://github.com/maiyunnet/kebab/blob/master/sys
 
 #### Param
 
+**key**
+
 是否以某个字段为主键
 
 #### Call Signature
@@ -24188,6 +24212,8 @@ Defined in: [sys/mod.ts:1140](https://github.com/maiyunnet/kebab/blob/master/sys
 
 #### Param
 
+**key**
+
 是否以某个字段为主键
 
 #### Call Signature
@@ -24384,6 +24410,8 @@ ON 信息
 
 #### Param
 
+**all**
+
 是否获取完全的情况，默认不获取，只返回扫描情况
 
 #### Call Signature
@@ -24448,10 +24476,14 @@ Defined in: [sys/mod.ts:1640](https://github.com/maiyunnet/kebab/blob/master/sys
 
 #### Param
 
+**lock**
+
 是否加锁
 
 #### Param
 
+**array**
+
 是否返回原生对象
 
 #### Call Signature
@@ -24992,10 +25024,14 @@ Defined in: [sys/mod.ts:973](https://github.com/maiyunnet/kebab/blob/master/sys/
 
 #### Param
 
+**n**
+
 字符串或键/值
 
 #### Param
 
+**v**
+
 可能是数字
 
 #### Call Signature
@@ -25464,21 +25500,27 @@ Defined in: [sys/mod.ts:264](https://github.com/maiyunnet/kebab/blob/master/sys/
 
 ### json()
 
-> `static` **json**(`obj`): `any`
+> `static` **json**\<`T`\>(`obj`): `T`
 
 Defined in: [sys/mod.ts:193](https://github.com/maiyunnet/kebab/blob/master/sys/mod.ts#L193)
 
 创建 JSON 字符串对象，用于 PGSQL 的 jsonb 字段
 
+#### Type Parameters
+
+##### T
+
+`T`
+
 #### Parameters
 
 ##### obj
 
-`any`
+`T`
 
 #### Returns
 
-`any`
+`T`
 
 ***
 
@@ -25488,14 +25530,20 @@ Defined in: [sys/mod.ts:193](https://github.com/maiyunnet/kebab/blob/master/sys/
 
 #### Param
 
+**db**
+
 数据库对象
 
 #### Param
 
+**s**
+
 筛选条件数组或字符串
 
 #### Param
 
+**opt**
+
 选项（opt.pre: MySQL 表前缀/PostgreSQL Schema 名；lock 需确保 where 条件命中索引，否则可能退化为表锁）
 
 #### Call Signature

package/index.d.ts

@@ -5,7 +5,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export declare const VER = "9.13.8";
+export declare const VER = "9.14.0";
 /** --- 框架根目录，以 / 结尾  --- */
 export declare const ROOT_PATH: string;
 /** --- 框架的 LIB，以 / 结尾 --- */

package/index.js

@@ -6,7 +6,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export const VER = '9.13.8';
+export const VER = '9.14.0';
 // --- 服务端用的路径 ---
 const imu = decodeURIComponent(import.meta.url).replace('file://', '').replace(/^\/(\w:)/, '$1');
 /** --- /xxx/xxx --- */

package/lib/crypto.d.ts

@@ -1,7 +1,7 @@
 /**
  * Project: Kebab, User: JianSuoQiYue
  * Date: 2019-4-2 14:01:06
- * Last: 2020-3-12 14:05:24, 2022-09-12 11:52:35, 2024-9-8 17:09:39, 2024-11-11 00:21:58, 2025-6-18 20:27:47
+ * Last: 2020-3-12 14:05:24, 2022-09-12 11:52:35, 2024-9-8 17:09:39, 2024-11-11 00:21:58, 2025-6-18 20:27:47, 2026-07-29 11:51
  */
 import * as crypto from 'crypto';
 /**
@@ -31,8 +31,8 @@ export declare function generateKeyPair(type: string, options?: {
  * @param format 输出格式
  * @param algorithm 哈希方式
  */
-export declare function sign(data: crypto.BinaryLike, privateKey: crypto.KeyLike | crypto.SignKeyObjectInput | crypto.SignPrivateKeyInput | crypto.SignJsonWebKeyInput, format: 'hex' | 'base64' | 'binary', algorithm?: string): string;
-export declare function sign(data: crypto.BinaryLike, privateKey: crypto.KeyLike | crypto.SignKeyObjectInput | crypto.SignPrivateKeyInput | crypto.SignJsonWebKeyInput, format?: 'buffer', algorithm?: string): Buffer;
+export declare function sign(data: string | NodeJS.ArrayBufferView, privateKey: crypto.KeyLike | crypto.SignKeyObjectInput | crypto.SignPrivateKeyInput | crypto.SignJsonWebKeyInput, format: 'hex' | 'base64' | 'binary', algorithm?: string): string;
+export declare function sign(data: string | NodeJS.ArrayBufferView, privateKey: crypto.KeyLike | crypto.SignKeyObjectInput | crypto.SignPrivateKeyInput | crypto.SignJsonWebKeyInput, format?: 'buffer', algorithm?: string): Buffer;
 /**
  * --- 非对称验签 ---
  * @param data 数据
@@ -40,31 +40,31 @@ export declare function sign(data: crypto.BinaryLike, privateKey: crypto.KeyLike
  * @param signature 签名
  * @param algorithm 哈希方式
  */
-export declare function verify(data: crypto.BinaryLike, object: crypto.KeyLike | crypto.VerifyKeyObjectInput | crypto.VerifyPublicKeyInput | crypto.VerifyJsonWebKeyInput, signature: NodeJS.ArrayBufferView, algorithm?: string): boolean;
+export declare function verify(data: string | NodeJS.ArrayBufferView, object: crypto.KeyLike | crypto.VerifyKeyObjectInput | crypto.VerifyPublicKeyInput | crypto.VerifyJsonWebKeyInput, signature: NodeJS.ArrayBufferView, algorithm?: string): boolean;
 /**
  * --- 非对称公钥加密 ---
  * @param key 公钥
  * @param buffer 数据
  */
-export declare function publicEncrypt(key: crypto.RsaPublicKey | crypto.RsaPrivateKey | crypto.KeyLike, buffer: NodeJS.ArrayBufferView | string): Buffer;
+export declare function publicEncrypt(key: crypto.KeyLike | crypto.PublicKeyInput | crypto.PrivateKeyInput, buffer: NodeJS.ArrayBufferView | string): Buffer;
 /**
  * --- 非对称私钥加密 ---
  * @param key 私钥
  * @param buffer 数据
  */
-export declare function privateEncrypt(key: crypto.RsaPrivateKey | crypto.KeyLike, buffer: NodeJS.ArrayBufferView | string): Buffer;
+export declare function privateEncrypt(key: crypto.KeyLike | crypto.PrivateKeyInput, buffer: NodeJS.ArrayBufferView | string): Buffer;
 /**
  * --- 非对称公钥解密 ---
  * @param key 公钥
  * @param buffer 数据
  */
-export declare function publicDecrypt(key: crypto.RsaPublicKey | crypto.RsaPrivateKey | crypto.KeyLike, buffer: NodeJS.ArrayBufferView | string): Buffer;
+export declare function publicDecrypt(key: crypto.KeyLike | crypto.PublicKeyInput | crypto.PrivateKeyInput, buffer: NodeJS.ArrayBufferView | string): Buffer;
 /**
  * --- 非对称私钥解密 ---
  * @param key 私钥
  * @param buffer 数据
  */
-export declare function privateDecrypt(key: crypto.RsaPrivateKey | crypto.KeyLike, buffer: NodeJS.ArrayBufferView | string): Buffer;
+export declare function privateDecrypt(key: crypto.KeyLike | crypto.PrivateKeyInput, buffer: NodeJS.ArrayBufferView | string): Buffer;
 /** --- 勿使用，无 iv 默认，但勿使用 --- */
 export declare const AES_256_ECB = "aes-256-ecb";
 /** --- 一般不用，兼容性场景下用 --- */
@@ -86,7 +86,7 @@ export declare const SM4_CFB = "sm4-cfb";
  * @param method 加密方法
  * @param output 输出类型
  */
-export declare function cipherEncrypt(original: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'base64' | 'buffer'): string | Buffer | false;
+export declare function cipherEncrypt(original: string | Buffer, key: crypto.KeyLike, iv?: string, method?: string, output?: 'base64' | 'buffer'): string | Buffer | false;
 /**
  * --- AES 加密 ---
  * @param original 原始字符串
@@ -95,16 +95,16 @@ export declare function cipherEncrypt(original: string | Buffer, key: crypto.Cip
  * @param method 加密方法
  * @param output 输出类型
  */
-export declare function aesEncrypt(original: string | Buffer, key: crypto.CipherKey, iv: string, method: string, output: 'buffer'): Buffer | false;
-export declare function aesEncrypt(original: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'base64'): string | false;
+export declare function aesEncrypt(original: string | Buffer, key: crypto.KeyLike, iv: string, method: string, output: 'buffer'): Buffer | false;
+export declare function aesEncrypt(original: string | Buffer, key: crypto.KeyLike, iv?: string, method?: string, output?: 'base64'): string | false;
 /**
  * --- AES GCM 托管加密 ---
  * @param original 原始字符串
  * @param key 密钥尽量 32 个英文字母和数字，不是 32 个系统会自动处理
  * @param output 输出类型
  */
-export declare function gcmEncrypt(original: string | Buffer, key: crypto.CipherKey, output: 'buffer'): Buffer | false;
-export declare function gcmEncrypt(original: string | Buffer, key: crypto.CipherKey, output?: 'base64'): string | false;
+export declare function gcmEncrypt(original: string | Buffer, key: crypto.KeyLike, output: 'buffer'): Buffer | false;
+export declare function gcmEncrypt(original: string | Buffer, key: crypto.KeyLike, output?: 'base64'): string | false;
 /**
  * --- SM4 加密 ---
  * @param original 原始字符串
@@ -112,8 +112,8 @@ export declare function gcmEncrypt(original: string | Buffer, key: crypto.Cipher
  * @param iv 向量 16 个英文字母和数字
  * @param method 加密方法
  */
-export declare function sm4Encrypt(original: string | Buffer, key: crypto.CipherKey, iv: string, method: string, output: 'buffer'): Buffer | false;
-export declare function sm4Encrypt(original: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'base64'): string | false;
+export declare function sm4Encrypt(original: string | Buffer, key: crypto.KeyLike, iv: string, method: string, output: 'buffer'): Buffer | false;
+export declare function sm4Encrypt(original: string | Buffer, key: crypto.KeyLike, iv?: string, method?: string, output?: 'base64'): string | false;
 /**
  * --- cipher 解密 ---
  * @param encrypt 需解密的字符串
@@ -122,7 +122,7 @@ export declare function sm4Encrypt(original: string | Buffer, key: crypto.Cipher
  * @param method 加密方法
  * @param output 输出类型
  */
-export declare function cipherDecrypt(encrypt: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'binary' | 'buffer'): string | Buffer | false;
+export declare function cipherDecrypt(encrypt: string | Buffer, key: crypto.KeyLike, iv?: string, method?: string, output?: 'binary' | 'buffer'): string | Buffer | false;
 /**
  * --- AES 解密 ---
  * @param encrypt 需解密的字符串
@@ -130,16 +130,16 @@ export declare function cipherDecrypt(encrypt: string | Buffer, key: crypto.Ciph
  * @param iv 向量 16(CTR) 或 12(GCM) 个英文字母和数字
  * @param method 加密方法
  */
-export declare function aesDecrypt(encrypt: string | Buffer, key: crypto.CipherKey, iv: string, method: string, output: 'buffer'): Buffer | false;
-export declare function aesDecrypt(encrypt: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'binary'): string | false;
+export declare function aesDecrypt(encrypt: string | Buffer, key: crypto.KeyLike, iv: string, method: string, output: 'buffer'): Buffer | false;
+export declare function aesDecrypt(encrypt: string | Buffer, key: crypto.KeyLike, iv?: string, method?: string, output?: 'binary'): string | false;
 /**
  * --- AES 解密 ---
  * @param encrypt 需解密的字符串
  * @param key 密钥 32 个英文字母和数字
  * @param output 输出类型
  */
-export declare function gcmDecrypt(encrypt: string | Buffer, key: crypto.CipherKey, output: 'buffer'): Buffer | false;
-export declare function gcmDecrypt(encrypt: string | Buffer, key: crypto.CipherKey, output?: 'binary'): string | false;
+export declare function gcmDecrypt(encrypt: string | Buffer, key: crypto.KeyLike, output: 'buffer'): Buffer | false;
+export declare function gcmDecrypt(encrypt: string | Buffer, key: crypto.KeyLike, output?: 'binary'): string | false;
 /**
  * --- SM4 解密 ---
  * @param encrypt 需解密的字符串
@@ -147,24 +147,24 @@ export declare function gcmDecrypt(encrypt: string | Buffer, key: crypto.CipherK
  * @param iv 向量 16 个英文字母和数字
  * @param method 加密方法
  */
-export declare function sm4Decrypt(encrypt: string | Buffer, key: crypto.CipherKey, iv: string, method: string, output: 'buffer'): Buffer | false;
-export declare function sm4Decrypt(encrypt: string | Buffer, key: crypto.CipherKey, iv?: string, method?: string, output?: 'binary'): string | false;
+export declare function sm4Decrypt(encrypt: string | Buffer, key: crypto.KeyLike, iv: string, method: string, output: 'buffer'): Buffer | false;
+export declare function sm4Decrypt(encrypt: string | Buffer, key: crypto.KeyLike, iv?: string, method?: string, output?: 'binary'): string | false;
 /**
  * --- hash 或 hmac 加密 ---
  * @param algorithm 哈希方式
  * @param data 源数据
  * @param key 设置则采用 hmac 加密
  */
-export declare function hashHmac(algorithm: string, data: Buffer | string, key?: crypto.CipherKey, format?: 'hex' | 'base64'): string;
-export declare function hashHmac(algorithm: string, data: Buffer | string, key: crypto.CipherKey | undefined, format: 'buffer'): Buffer;
+export declare function hashHmac(algorithm: string, data: Buffer | string, key?: crypto.KeyLike, format?: 'hex' | 'base64'): string;
+export declare function hashHmac(algorithm: string, data: Buffer | string, key: crypto.KeyLike | undefined, format: 'buffer'): Buffer;
 /**
  * --- hash 或 hmac 加密文件 ---
  * @param algorithm 加密方式，如 md5、sha256、sm3 等
  * @param path 文件路径
  * @param key 设置则采用 hmac 加密
  */
-export declare function hashHmacFile(algorithm: string, path: string, key?: crypto.CipherKey, encoding?: 'hex' | 'base64' | 'base64url'): Promise<string | false>;
-export declare function hashHmacFile(algorithm: string, path: string, key: crypto.CipherKey, encoding: 'buffer'): Promise<Buffer | false>;
+export declare function hashHmacFile(algorithm: string, path: string, key?: crypto.KeyLike, encoding?: 'hex' | 'base64' | 'base64url'): Promise<string | false>;
+export declare function hashHmacFile(algorithm: string, path: string, key: crypto.KeyLike, encoding: 'buffer'): Promise<Buffer | false>;
 /**
  * --- base64 编码 ---
  * @param data 字符串或 Buffer

package/lib/crypto.js

@@ -1,7 +1,7 @@
 /**
  * Project: Kebab, User: JianSuoQiYue
  * Date: 2019-4-2 14:01:06
- * Last: 2020-3-12 14:05:24, 2022-09-12 11:52:35, 2024-9-8 17:09:39, 2024-11-11 00:21:58, 2025-6-18 20:27:47
+ * Last: 2020-3-12 14:05:24, 2022-09-12 11:52:35, 2024-9-8 17:09:39, 2024-11-11 00:21:58, 2025-6-18 20:27:47, 2026-07-29 11:51
  */
 import * as crypto from 'crypto';
 // --- 库和定义 ---

package/lib/sql.d.ts

@@ -303,4 +303,4 @@ export declare function value(val: kebab.DbValue): {
  * --- 将对象转换为 JSON 字符串并避开类型检查，用于适配 PostgreSQL 的 jsonb 字段 ---
  * @param obj 要转换的 JSON 对象
  */
-export declare function json(obj: kebab.Json): any;
+export declare function json<T>(obj: T): T;

package/lib/undici/response.d.ts

@@ -31,7 +31,7 @@ export declare class Response {
     /**
      * --- 获取响应读取流对象 ---
      */
-    getStream(): zlib.BrotliDecompress | zlib.Gunzip | zlib.Inflate | (import("undici/types/readable").default & undici.Dispatcher.BodyMixin) | null;
+    getStream(): (import("undici/types/readable").default & undici.Dispatcher.BodyMixin) | zlib.Gunzip | zlib.Inflate | zlib.BrotliDecompress | null;
     /**
      * --- 获取原生响应读取流对象 ---
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maiyunnet/kebab",
-  "version": "9.13.8",
+  "version": "9.14.0",
   "description": "Simple, easy-to-use, and fully-featured Node.js framework that is ready-to-use out of the box.",
   "type": "module",
   "keywords": [
@@ -22,47 +22,47 @@
     "#kebab/*": "./*"
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.1047.0",
-    "@aws-sdk/lib-storage": "^3.1047.0",
+    "@aws-sdk/client-s3": "^3.1096.0",
+    "@aws-sdk/lib-storage": "^3.1096.0",
     "@litert/http-client": "^1.1.2",
     "@litert/mime": "^0.1.3",
     "@litert/redis": "^3.2.1",
     "@litert/websocket": "^0.2.8",
-    "@radix-ui/react-checkbox": "^1.3.3",
-    "@radix-ui/react-label": "^2.1.8",
-    "@radix-ui/react-slot": "^1.2.4",
-    "@radix-ui/react-switch": "^1.2.6",
-    "@tailwindcss/cli": "^4.3.0",
+    "@radix-ui/react-checkbox": "^1.3.11",
+    "@radix-ui/react-label": "^2.1.15",
+    "@radix-ui/react-slot": "^1.3.3",
+    "@radix-ui/react-switch": "^1.3.7",
+    "@tailwindcss/cli": "^4.3.3",
     "@types/ssh2": "^1.15.5",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "ejs": "^5.0.2",
-    "esbuild": "^0.28.0",
+    "ejs": "^6.0.1",
+    "esbuild": "^0.28.1",
     "jszip": "^3.10.1",
-    "mysql2": "^3.22.3",
-    "node-cron": "^4.2.1",
-    "openai": "^6.37.0",
-    "pg": "^8.20.0",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "react-router-dom": "^7.15.1",
+    "mysql2": "^3.23.2",
+    "node-cron": "^4.6.0",
+    "openai": "^7.0.0",
+    "pg": "^8.22.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-router-dom": "^7.18.1",
     "ssh2": "^1.17.0",
     "svg-captcha": "^1.4.0",
     "tailwind-merge": "^3.6.0",
-    "tencentcloud-sdk-nodejs": "^4.1.232",
-    "undici": "^8.3.0"
+    "tencentcloud-sdk-nodejs": "^4.1.277",
+    "undici": "^8.9.0"
   },
   "devDependencies": {
     "@litert/eslint-plugin-rules": "^0.3.1",
     "@types/ejs": "^3.1.5",
-    "@types/node": "^25.8.0",
+    "@types/node": "^26.1.2",
     "@types/pg": "^8.20.0",
-    "@types/react": "^19.2.14",
+    "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "typedoc": "^0.28.19",
-    "typedoc-plugin-markdown": "^4.11.0",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "^4.12.0",
     "typescript": "^6.0.3"
   }
 }

package/sys/child.js

@@ -47,6 +47,8 @@ let http2Server;
 const linkCount = {};
 /** --- 是否正在停止，停止时对 HTTP/1.1 响应追加 Connection: close，避免请求完成后连接回到保活池 --- */
 let stopping = false;
+/** --- 当前活跃的 HTTP/2 会话集合，用于 graceful shutdown 时发送 GOAWAY 帧 --- */
+const http2Sessions = new Set();
 /**
  * --- 包装请求处理函数，统一管理 linkCount 计数和错误处理 ---
  * @param key 连接标识
@@ -144,6 +146,12 @@ async function run() {
         }
         wrapWithLinkCount(host + (req.url ?? ''), () => upgradeHandler(req, socket, true, head), '[CHILD][http2][upgrade]', 'UPGRADE');
     }).listen(lCore.globalConfig.httpsPort);
+    // --- 追踪 HTTP/2 会话，用于 graceful shutdown 时发送 GOAWAY 帧通知 CDN 切换连接 ---
+    http2Server.on('session', (session) => {
+        http2Sessions.add(session);
+        session.on('close', () => { http2Sessions.delete(session); });
+        session.on('error', () => { http2Sessions.delete(session); });
+    });
     // --- 增大 HTTP/2 超时，防止 CDN 预建连接被 Node.js 过早关闭 ---
     http2Server.setTimeout(120_000);
     httpServer = http.createServer(function (req, res) {
@@ -562,6 +570,13 @@ process.on('message', function (msg) {
             case 'stop': {
                 // --- 需要停止监听，等待已有连接全部断开，然后关闭线程 ---
                 stopping = true;
+                // --- 向所有 HTTP/2 会话发送 GOAWAY 帧，通知 CDN 客户端停止在该连接上发送新请求并切换到新连接 ---
+                for (const session of http2Sessions) {
+                    try {
+                        session.goaway(http2.constants.NGHTTP2_NO_ERROR);
+                    }
+                    catch { }
+                }
                 httpServer?.close();
                 http2Server?.close();
                 // --- 立即关闭空闲保活连接（无活跃请求的 keep-alive socket），避免进程长时间等待 ---

package/sys/master.js

@@ -18,6 +18,29 @@ import * as lTime from '#kebab/lib/time.js';
 import * as lZip from '#kebab/lib/zip.js';
 /** --- 当前运行中的子进程列表 --- */
 const workerList = {};
+/**
+ * --- 等待指定 worker 开始监听端口就绪 ---
+ * @param worker 要等待的 worker 对象
+ * @param timeout 超时时间（毫秒），默认 30 秒
+ */
+function waitForWorkerListening(worker, timeout = 30_000) {
+    return new Promise((resolve) => {
+        let timer;
+        const onListening = (w) => {
+            if (w.id === worker.id) {
+                clearTimeout(timer);
+                cluster.removeListener('listening', onListening);
+                resolve();
+            }
+        };
+        timer = setTimeout(() => {
+            lCore.display(`[master] Worker ${worker.process.pid ?? 'undefined'} timed out waiting for listening, proceeding anyway.`);
+            cluster.removeListener('listening', onListening);
+            resolve();
+        }, timeout);
+        cluster.on('listening', onListening);
+    });
+}
 /**
  * --- 最终调用执行的函数块 ---
  */
@@ -124,16 +147,7 @@ function createRpcListener() {
                     break;
                 }
                 case 'restart': {
-                    // --- 为所有子线程发送 stop 信息 ---
-                    for (const pid in workerList) {
-                        workerList[pid].worker.send({
-                            'action': 'stop'
-                        });
-                        // --- 开启新线程 ---
-                        await createChildProcess(workerList[pid].cpu);
-                        // --- 删除记录 ---
-                        delete workerList[pid];
-                    }
+                    await restartWorkers();
                     break;
                 }
                 case 'global': {
@@ -768,6 +782,34 @@ function createRpcListener() {
         });
     }).listen(lCore.globalConfig.rpcPort);
 }
+/**
+ * --- 零宕机重启所有 worker 进程：先创建新进程并等待监听就绪，再停止旧进程 ---
+ */
+async function restartWorkers() {
+    // --- 收集旧进程信息（先快照，避免迭代过程中修改 workerList） ---
+    const oldEntries = [];
+    for (const pid in workerList) {
+        oldEntries.push({
+            'pid': pid,
+            'cpu': workerList[pid].cpu,
+            'worker': workerList[pid].worker
+        });
+    }
+    // --- 阶段 1：创建新进程并等待其监听端口就绪 ---
+    for (const entry of oldEntries) {
+        const newWorker = await createChildProcess(entry.cpu);
+        if (newWorker) {
+            await waitForWorkerListening(newWorker);
+        }
+    }
+    // --- 阶段 2：停止旧进程 ---
+    for (const entry of oldEntries) {
+        entry.worker.send({
+            'action': 'stop'
+        });
+        delete workerList[entry.pid];
+    }
+}
 /**
  * --- 检测是否有死掉丢失的子进程，复活之 ---
  */
@@ -795,7 +837,7 @@ async function checkWorkerLost() {
 async function createChildProcess(cpu) {
     const worker = cluster.fork();
     if (!worker.process.pid) {
-        return;
+        return null;
     }
     workerList[worker.process.pid] = {
         'worker': worker,
@@ -823,16 +865,7 @@ async function createChildProcess(cpu) {
                     break;
                 }
                 case 'restart': {
-                    // --- 为所有子进程发送 restart 信息 ---
-                    for (const pid in workerList) {
-                        workerList[pid].worker.send({
-                            'action': 'stop'
-                        });
-                        // --- 开启新线程 ---
-                        await createChildProcess(workerList[pid].cpu);
-                        // --- 删除记录 ---
-                        delete workerList[pid];
-                    }
+                    await restartWorkers();
                     break;
                 }
                 case 'global': {
@@ -889,6 +922,7 @@ async function createChildProcess(cpu) {
             'data': lCore.global
         });
     }
+    return worker;
 }
 /**
  * --- 开发模式下的文件监听自动重载（HMR），仅在 debug: true 时启用 ---
@@ -919,18 +953,10 @@ function startFileWatcher() {
             }
             restarting = true;
             lCore.display(`[HMR] File changed: ${formatName}, reloading workers...`);
-            (async () => {
-                // --- 为所有子进程发送 stop 信息并重启 ---
-                for (const pid in workerList) {
-                    workerList[pid].worker.send({
-                        'action': 'stop'
-                    });
-                    await createChildProcess(workerList[pid].cpu);
-                    delete workerList[pid];
-                }
+            restartWorkers().then(() => {
                 restarting = false;
                 lCore.display('[HMR] All workers reloaded.');
-            })().catch((e) => {
+            }).catch((e) => {
                 restarting = false;
                 lCore.display('[HMR] Reload error:', e);
             });

package/sys/mod.d.ts

@@ -96,7 +96,7 @@ export default class Mod {
         'value': kebab.DbValue;
     };
     /** --- 创建 JSON 字符串对象，用于 PGSQL 的 jsonb 字段 --- */
-    static json(obj: kebab.Json): any;
+    static json<T>(obj: T): T;
     /**
      * --- 添加一个序列（允许超过 65536 的占位符会被拆分多次执行） ---
      * @param db 数据库对象

package/www/example/stc/lib/ui/checkbox.d.ts

@@ -5,5 +5,5 @@
  */
 import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
 type CheckboxProps = React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>;
-export declare function Checkbox({ className, ...props }: CheckboxProps): import("react/jsx-runtime").JSX.Element;
+export declare function Checkbox({ className, ...props }: CheckboxProps): import("react").JSX.Element;
 export {};

package/www/example/stc/lib/ui/input.d.ts

@@ -1,3 +1,3 @@
 type InputProps = React.InputHTMLAttributes<HTMLInputElement>;
-export declare function Input({ className, ...props }: InputProps): import("react/jsx-runtime").JSX.Element;
+export declare function Input({ className, ...props }: InputProps): import("react").JSX.Element;
 export {};

package/www/example/stc/lib/ui/label.d.ts

@@ -7,5 +7,5 @@ import * as LabelPrimitive from '@radix-ui/react-label';
 import { type VariantProps } from 'class-variance-authority';
 declare const labelVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
 type LabelProps = React.ComponentPropsWithoutRef<typeof LabelPrimitive.Root> & VariantProps<typeof labelVariants>;
-export declare function Label({ className, ...props }: LabelProps): import("react/jsx-runtime").JSX.Element;
+export declare function Label({ className, ...props }: LabelProps): import("react").JSX.Element;
 export {};

package/www/example/stc/lib/ui/switch.d.ts

@@ -5,5 +5,5 @@
  */
 import * as SwitchPrimitive from '@radix-ui/react-switch';
 type SwitchProps = React.ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>;
-export declare function Switch({ className, ...props }: SwitchProps): import("react/jsx-runtime").JSX.Element;
+export declare function Switch({ className, ...props }: SwitchProps): import("react").JSX.Element;
 export {};

package/www/example/stc/view/react-router.page.d.ts

@@ -48,5 +48,5 @@ interface IProps {
  * 框架负责用 StaticRouter（服务端）/ BrowserRouter（客户端）包裹本组件，
  * 组件内部只需使用 Routes/Route/Link 等，无需自行包裹 Router。
  */
-export default function ReactRouterPage({ title, serverTime, node, users, user, _urlBase, _urlStc, _staticVer, }: IProps): import("react/jsx-runtime").JSX.Element;
+export default function ReactRouterPage({ title, serverTime, node, users, user, _urlBase, _urlStc, _staticVer, }: IProps): import("react").JSX.Element;
 export {};

package/www/example/stc/view/react.page.d.ts

@@ -44,5 +44,5 @@ interface IProps {
     '_staticVer': string;
 }
 /** --- Kebab React 全页面演示 --- */
-export default function ReactPage({ title, serverTime, node, _urlBase, _urlStc, _staticVer }: IProps): import("react/jsx-runtime").JSX.Element;
+export default function ReactPage({ title, serverTime, node, _urlBase, _urlStc, _staticVer }: IProps): import("react").JSX.Element;
 export {};