@maiyunnet/kebab 5.3.0 → 6.0.0

package/lib/dns.d.ts

@@ -1,9 +1,9 @@
 /**
  * Project: Kebab, User: JianSuoQiYue
  * Date: 2019-6-19
- * Last: 2022-09-12 20:58:07, 2024-2-21 17:55:54, 2025-6-13 19:08:56
+ * Last: 2022-09-12 20:58:07, 2024-2-21 17:55:54, 2025-6-13 19:08:56, 2025-11-19 00:17:56
  */
-import * as ctr from '#kebab/sys/ctr.js';
+import * as sCtr from '#kebab/sys/ctr.js';
 /**
  * 0.DNSPod：https://www.dnspod.cn/docs/index.html（腾讯云也请使用 DNSPod 的 API）
  * 1.阿里云：https://help.aliyun.com/document_detail/29745.html
@@ -44,19 +44,19 @@ export interface IAddDomainRecord {
 /**
  * --- 记录值类型 ---
  */
-export declare const RECORD_TYPE: {
-    A: string;
-    NS: string;
-    MX: string;
-    TXT: string;
-    CNAME: string;
-    SRV: string;
-    AAAA: string;
-};
+export declare enum ERECORDTYPE {
+    'A' = 0,
+    'NS' = 1,
+    'MX' = 2,
+    'TXT' = 3,
+    'CNAME' = 4,
+    'SRV' = 5,
+    'AAAA' = 6
+}
 /**
  * --- 记录值线路 ---
  */
-export declare enum ERecordLine {
+export declare enum ERECORDLINE {
     'DEFAULT' = 0,
     'TELECOM' = 1,
     'UNICOM' = 2,
@@ -67,7 +67,7 @@ export declare enum ERecordLine {
 export declare class Dns {
     /** --- 当前选项 --- */
     private readonly _opt;
-    constructor(ctr: ctr.Ctr, opt: IOptions);
+    constructor(ctr: sCtr.Ctr, opt: IOptions);
     /**
      * --- 最终发送 ---
      * @param obj 要发送的信息
@@ -90,7 +90,7 @@ export declare class Dns {
         'sub': string;
         'type': string;
         'value': string;
-        'line'?: number;
+        'line'?: ERECORDLINE;
         'ttl'?: number;
         'mx'?: number;
     }): Promise<IAddDomainRecord | null>;
@@ -104,7 +104,7 @@ export declare class Dns {
         'sub': string;
         'type': string;
         'value': string;
-        'line'?: number;
+        'line'?: ERECORDLINE;
         'ttl'?: number;
         'mx'?: number;
     }): Promise<IAddDomainRecord | null>;
@@ -120,7 +120,7 @@ export declare class Dns {
     } | null>;
 }
 /**
- * --- 创建一个第三方 Dns 对象 ---
+ * --- 创建一个 Dns 对象 ---
  * @param opt 选项
  */
-export declare function get(ctr: ctr.Ctr, opt: IOptions): Dns;
+export declare function get(ctr: sCtr.Ctr, opt: IOptions): Dns;

package/lib/dns.js

@@ -1,14 +1,14 @@
 /**
  * Project: Kebab, User: JianSuoQiYue
  * Date: 2019-6-19
- * Last: 2022-09-12 20:58:07, 2024-2-21 17:55:54, 2025-6-13 19:08:56
+ * Last: 2022-09-12 20:58:07, 2024-2-21 17:55:54, 2025-6-13 19:08:56, 2025-11-19 00:17:56
  */
 // --- 库和定义 ---
-import * as net from '#kebab/lib/net.js';
-import * as core from '#kebab/lib/core.js';
-import * as text from '#kebab/lib/text.js';
-import * as crypto from '#kebab/lib/crypto.js';
-import * as response from '#kebab/lib/net/response.js';
+import * as lNet from '#kebab/lib/net.js';
+import * as lCore from '#kebab/lib/core.js';
+import * as lText from '#kebab/lib/text.js';
+import * as lCrypto from '#kebab/lib/crypto.js';
+import * as lResponse from '#kebab/lib/net/response.js';
 /**
  * 0.DNSPod：https://www.dnspod.cn/docs/index.html（腾讯云也请使用 DNSPod 的 API）
  * 1.阿里云：https://help.aliyun.com/document_detail/29745.html
@@ -22,27 +22,28 @@ export var ESERVICE;
 /**
  * --- 记录值类型 ---
  */
-export const RECORD_TYPE = {
-    'A': 'A',
-    'NS': 'NS',
-    'MX': 'MX',
-    'TXT': 'TXT',
-    'CNAME': 'CNAME',
-    'SRV': 'SRV',
-    'AAAA': 'AAAA'
-};
+export var ERECORDTYPE;
+(function (ERECORDTYPE) {
+    ERECORDTYPE[ERECORDTYPE["A"] = 0] = "A";
+    ERECORDTYPE[ERECORDTYPE["NS"] = 1] = "NS";
+    ERECORDTYPE[ERECORDTYPE["MX"] = 2] = "MX";
+    ERECORDTYPE[ERECORDTYPE["TXT"] = 3] = "TXT";
+    ERECORDTYPE[ERECORDTYPE["CNAME"] = 4] = "CNAME";
+    ERECORDTYPE[ERECORDTYPE["SRV"] = 5] = "SRV";
+    ERECORDTYPE[ERECORDTYPE["AAAA"] = 6] = "AAAA";
+})(ERECORDTYPE || (ERECORDTYPE = {}));
 /**
  * --- 记录值线路 ---
  */
-export var ERecordLine;
-(function (ERecordLine) {
-    ERecordLine[ERecordLine["DEFAULT"] = 0] = "DEFAULT";
-    ERecordLine[ERecordLine["TELECOM"] = 1] = "TELECOM";
-    ERecordLine[ERecordLine["UNICOM"] = 2] = "UNICOM";
-    ERecordLine[ERecordLine["MOBILE"] = 3] = "MOBILE";
-    ERecordLine[ERecordLine["EDU"] = 4] = "EDU";
-    ERecordLine[ERecordLine["OVERSEA"] = 5] = "OVERSEA";
-})(ERecordLine || (ERecordLine = {}));
+export var ERECORDLINE;
+(function (ERECORDLINE) {
+    ERECORDLINE[ERECORDLINE["DEFAULT"] = 0] = "DEFAULT";
+    ERECORDLINE[ERECORDLINE["TELECOM"] = 1] = "TELECOM";
+    ERECORDLINE[ERECORDLINE["UNICOM"] = 2] = "UNICOM";
+    ERECORDLINE[ERECORDLINE["MOBILE"] = 3] = "MOBILE";
+    ERECORDLINE[ERECORDLINE["EDU"] = 4] = "EDU";
+    ERECORDLINE[ERECORDLINE["OVERSEA"] = 5] = "OVERSEA";
+})(ERECORDLINE || (ERECORDLINE = {}));
 const recordLine = {
     [ESERVICE.DNSPOD]: [
         '默认',
@@ -87,25 +88,26 @@ export class Dns {
                 }, obj);
                 const path = data['_path'];
                 delete data['_path'];
-                return await net.post('https://dnsapi.cn/' + path, data); // 境外 api 会自动调度到香港服务器
+                // --- 境外服务器请求的话 api 会自动解析到香港服务器 ---
+                return lNet.post('https://dnsapi.cn/' + path, data);
             }
             // --- 阿里云 ---
             case ESERVICE.ALIBABA: {
-                const getData = core.objectSort(Object.assign({
+                const getData = lCore.objectSort(Object.assign({
                     'Format': 'JSON',
                     'Version': '2015-01-09',
                     'AccessKeyId': this._opt.secretId,
                     'SignatureMethod': 'HMAC-SHA1',
                     'Timestamp': (new Date()).toISOString(),
                     'SignatureVersion': '1.0',
-                    'SignatureNonce': core.rand(1000000000, 9999999999)
+                    'SignatureNonce': lCore.rand(1000000000, 9999999999)
                 }, obj));
-                const urlRight = text.queryStringify(getData);
-                const signature = crypto.hashHmac('sha1', `GET&${encodeURIComponent('/')}&${encodeURIComponent(urlRight)}`, (this._opt.secretKey ?? '') + '&', 'base64');
-                return await net.get(`https://alidns.aliyuncs.com/?${urlRight}&Signature=${encodeURIComponent(signature)}`); // 境外 api 会自动调度到新加坡服务器
+                const urlRight = lText.queryStringify(getData);
+                const signature = lCrypto.hashHmac('sha1', `GET&${encodeURIComponent('/')}&${encodeURIComponent(urlRight)}`, (this._opt.secretKey ?? '') + '&', 'base64');
+                return lNet.get(`https://alidns.aliyuncs.com/?${urlRight}&Signature=${encodeURIComponent(signature)}`); // 境外 api 会自动调度到新加坡服务器
             }
         }
-        return new response.Response(null);
+        return new lResponse.Response(null);
     }
     /**
      * --- 获取域名列表 ---
@@ -124,7 +126,7 @@ export class Dns {
                 if (!res) {
                     return res;
                 }
-                const json = text.parseJson(res.toString());
+                const json = lText.parseJson(res.toString());
                 const r = {
                     'total': json.info.domain_total,
                     'list': []
@@ -151,7 +153,7 @@ export class Dns {
                 if (!res) {
                     return res;
                 }
-                const json = text.parseJson(res.toString());
+                const json = lText.parseJson(res.toString());
                 const r = {
                     'total': json.TotalCount,
                     'list': []
@@ -174,7 +176,7 @@ export class Dns {
      * @param opt 参数
      */
     async addDomainRecord(opt) {
-        const line = opt.line ?? ERecordLine.DEFAULT;
+        const line = opt.line ?? ERECORDLINE.DEFAULT;
         const ttl = opt.ttl ?? 600;
         switch (this._opt.service) {
             // --- DNSPod ---
@@ -193,7 +195,7 @@ export class Dns {
                 if (!res) {
                     return res;
                 }
-                const json = text.parseJson(res.toString());
+                const json = lText.parseJson(res.toString());
                 const r = {
                     'success': json.record?.id ? true : false,
                     'id': json.record?.id ?? ''
@@ -216,7 +218,7 @@ export class Dns {
                 if (!res) {
                     return res;
                 }
-                const json = text.parseJson(res.toString());
+                const json = lText.parseJson(res.toString());
                 const r = {
                     'success': json.RecordId !== undefined ? true : false,
                     'id': json.RecordId ?? ''
@@ -231,7 +233,7 @@ export class Dns {
      * @param opt 参数
      */
     async updateDomainRecord(opt) {
-        const line = opt.line ?? ERecordLine.DEFAULT;
+        const line = opt.line ?? ERECORDLINE.DEFAULT;
         const ttl = opt.ttl ?? 600;
         switch (this._opt.service) {
             // --- DNSPod ---
@@ -252,7 +254,7 @@ export class Dns {
                 if (!res) {
                     return res;
                 }
-                const json = text.parseJson(res.toString());
+                const json = lText.parseJson(res.toString());
                 const r = {
                     'success': json.record?.id ? true : false,
                     'id': json.record?.id ?? ''
@@ -275,7 +277,7 @@ export class Dns {
                 if (!res) {
                     return res;
                 }
-                const json = text.parseJson(res.toString());
+                const json = lText.parseJson(res.toString());
                 const r = {
                     'success': json.RecordId !== undefined ? true : false,
                     'id': json.RecordId ?? ''
@@ -302,7 +304,7 @@ export class Dns {
                 if (!res) {
                     return res;
                 }
-                const json = text.parseJson(res.toString());
+                const json = lText.parseJson(res.toString());
                 return {
                     'success': json.status.code === '1' ? true : false
                 };
@@ -317,7 +319,7 @@ export class Dns {
                 if (!res) {
                     return res;
                 }
-                const json = text.parseJson(res.toString());
+                const json = lText.parseJson(res.toString());
                 return {
                     'success': json.Code === undefined ? true : false
                 };
@@ -327,7 +329,7 @@ export class Dns {
     }
 }
 /**
- * --- 创建一个第三方 Dns 对象 ---
+ * --- 创建一个 Dns 对象 ---
  * @param opt 选项
  */
 export function get(ctr, opt) {

package/lib/fs.d.ts

@@ -72,7 +72,7 @@ export declare function mkdir(path: string, mode?: number): Promise<boolean>;
 export declare function rmdir(path: string): Promise<boolean>;
 /**
  * --- Danger 危险：危险函数，尽量不要使用 ---
- * --- This f**king is a danger function, please don't use it ---
+ * --- This is a danger function, please don't use it ---
  * --- 删除一个非空目录 ---
  */
 export declare function rmdirDeep(path: string): Promise<boolean>;
@@ -83,7 +83,7 @@ export declare function rmdirDeep(path: string): Promise<boolean>;
  */
 export declare function chmod(path: string, mod: string | number): Promise<boolean>;
 /**
- * --- 重命名/移动 文件文件夹 ---
+ * --- 重命名/移动文件文件夹 ---
  * @param oldPath 老名
  * @param newPath 新名
  */

package/lib/fs.js

@@ -208,7 +208,7 @@ export async function rmdir(path) {
 }
 /**
  * --- Danger 危险：危险函数，尽量不要使用 ---
- * --- This f**king is a danger function, please don't use it ---
+ * --- This is a danger function, please don't use it ---
  * --- 删除一个非空目录 ---
  */
 export async function rmdirDeep(path) {
@@ -252,7 +252,7 @@ export async function chmod(path, mod) {
     }
 }
 /**
- * --- 重命名/移动 文件文件夹 ---
+ * --- 重命名/移动文件文件夹 ---
  * @param oldPath 老名
  * @param newPath 新名
  */

package/lib/kv.d.ts

@@ -6,10 +6,27 @@
 import * as redis from '@litert/redis';
 import * as kebab from '#kebab/index.js';
 import * as sCtr from '#kebab/sys/ctr.js';
+/**
+ * --- 键值存储操作类 ---
+ *
+ * @example
+ * ```ts
+ * import * as lKv from '@maiyunnet/kebab/lib/kv.js';
+ * const kv = lKv.get(this);
+ * await kv.ping();
+ * const v = await kv.get('test');
+ * const res = await kv.replace('test', 111);
+ * ```
+ */
 export declare class Kv {
     /** --- 当前的 kv 连接信息 --- */
     private readonly _etc;
     constructor(etc: kebab.IConfigKv);
+    /**
+     * --- 获取一个 pipeline 操作对象 ---
+     * @returns 失败则返回 false
+     */
+    pipeline(): Promise<redis.IPipelineClient | false>;
     /**
      * --- 设定一个值 ---
      * @param key
@@ -27,16 +44,15 @@ export declare class Kv {
     add(key: string, val: object | string | number, ttl?: number): Promise<boolean>;
     /**
      * --- 替换一个存在的值 ---
-     * @param key
-     * @param val
+     * @param key 键
+     * @param val 值
      * @param ttl 秒，0 为不限制
-     * @param etc
      */
     replace(key: string, val: object | string | number, ttl?: number): Promise<boolean>;
     /**
      * --- 向已存在的值后追加数据 ---
-     * @param key
-     * @param val
+     * @param key 键
+     * @param val 值
      */
     append(key: string, val: string): Promise<boolean>;
     /**
@@ -122,7 +138,6 @@ export declare class Kv {
     flushDb(): Promise<boolean>;
     /**
      * --- 发送 ping ---
-     * @param last 是否刷新最后使用时间（默认刷新）
      */
     ping(): Promise<false | string>;
     /**
@@ -201,7 +216,7 @@ export declare class Kv {
 }
 /**
  * --- 获取 Kv 对象 ---
- * @param etc 配置信息可留空
+ * @param ctrEtc 控制器或配置信息
  */
 export declare function get(ctrEtc: sCtr.Ctr | kebab.IConfigKv): Kv;
 /** --- 连接信息 --- */

package/lib/kv.js

@@ -10,10 +10,33 @@ import * as lCore from '#kebab/lib/core.js';
 import * as sCtr from '#kebab/sys/ctr.js';
 /** --- 连接列表（同一个 host、port、index 只有一个连接） --- */
 const connections = [];
+/**
+ * --- 键值存储操作类 ---
+ *
+ * @example
+ * ```ts
+ * import * as lKv from '@maiyunnet/kebab/lib/kv.js';
+ * const kv = lKv.get(this);
+ * await kv.ping();
+ * const v = await kv.get('test');
+ * const res = await kv.replace('test', 111);
+ * ```
+ */
 export class Kv {
     constructor(etc) {
         this._etc = etc;
     }
+    /**
+     * --- 获取一个 pipeline 操作对象 ---
+     * @returns 失败则返回 false
+     */
+    async pipeline() {
+        const conn = await this._getConnection();
+        if (!conn) {
+            return false;
+        }
+        return conn.pipeline();
+    }
     /**
      * --- 设定一个值 ---
      * @param key
@@ -57,18 +80,17 @@ export class Kv {
     }
     /**
      * --- 替换一个存在的值 ---
-     * @param key
-     * @param val
+     * @param key 键
+     * @param val 值
      * @param ttl 秒，0 为不限制
-     * @param etc
      */
     async replace(key, val, ttl = 0) {
         return this.set(key, val, ttl, 'xx');
     }
     /**
      * --- 向已存在的值后追加数据 ---
-     * @param key
-     * @param val
+     * @param key 键
+     * @param val 值
      */
     async append(key, val) {
         const conn = await this._getConnection();
@@ -404,7 +426,6 @@ end`;
     }
     /**
      * --- 发送 ping ---
-     * @param last 是否刷新最后使用时间（默认刷新）
      */
     async ping() {
         const conn = await this._getConnection();
@@ -748,7 +769,7 @@ end`;
 }
 /**
  * --- 获取 Kv 对象 ---
- * @param etc 配置信息可留空
+ * @param ctrEtc 控制器或配置信息
  */
 export function get(ctrEtc) {
     const etc = ctrEtc instanceof sCtr.Ctr ? ctrEtc.getPrototype('_config').kv : ctrEtc;

package/lib/net/request.d.ts

@@ -55,7 +55,7 @@ export declare class Request {
      * --- 设置域名 -> ip的对应键值，就像电脑里的 hosts 一样 ---
      * @param hosts
      */
-    hosts(hosts: Record<string, string>): this;
+    hosts(hosts: Record<string, string> | string): this;
     /**
      * --- 设置后将直接保存到本地文件，不会返回，save 为本地实体路径 ---
      * @param save

package/lib/net.d.ts

@@ -36,17 +36,17 @@ export declare function post(u: string, data: Record<string, kebab.Json> | Buffe
  * --- 发起 JSON 请求 ---
  * @param u 网址
  * @param data 数据
- * @param opt选项
+ * @param opt 选项
  */
-export declare function postJson(u: string, data: kebab.Json[] | Record<string, kebab.Json>, opt?: IRequestOptions): Promise<lResponse.Response>;
+export declare function postJson(u: string, data: any[] | Record<string, kebab.Json>, opt?: IRequestOptions): Promise<lResponse.Response>;
 /**
  * --- 发起 JSON 请求并解析 JSON 响应 ---
- * @param url 网址
+ * @param u 网址
  * @param data 数据
- * @param init 选项
+ * @param opt 选项
  * @returns JSON 数据，失败时返回 null
  */
-export declare function postJsonResponseJson(u: string, data: kebab.Json[] | Record<string, kebab.Json>, opt?: IRequestOptions): Promise<any | null>;
+export declare function postJsonResponseJson(u: string, data: any[] | Record<string, kebab.Json>, opt?: IRequestOptions): Promise<any | null>;
 /**
  * --- 发起一个原生 fetch 请求，增加了一些框架选项，注意：会抛出错误 ---
  * @param input 请求的 URL 或 Request 对象
@@ -64,7 +64,7 @@ export declare function fetch(input: string | URL | Request, init?: RequestInit
  * --- 发起一个请求 ---
  * @param opt 配置项
  */
-export declare function request(u: string, data?: Record<string, kebab.Json> | Buffer | string | stream.Readable, opt?: IRequestOptions): Promise<lResponse.Response>;
+export declare function request(u: string, data?: Record<string, any> | Buffer | string | stream.Readable, opt?: IRequestOptions): Promise<lResponse.Response>;
 /**
  * --- 对 cookie 对象进行操作 ---
  * @param cookie 要操作的对象

package/lib/net.js

@@ -60,7 +60,7 @@ export async function post(u, data, opt = {}) {
  * --- 发起 JSON 请求 ---
  * @param u 网址
  * @param data 数据
- * @param opt选项
+ * @param opt 选项
  */
 export async function postJson(u, data, opt = {}) {
     opt.method = 'POST';
@@ -69,9 +69,9 @@ export async function postJson(u, data, opt = {}) {
 }
 /**
  * --- 发起 JSON 请求并解析 JSON 响应 ---
- * @param url 网址
+ * @param u 网址
  * @param data 数据
- * @param init 选项
+ * @param opt 选项
  * @returns JSON 数据，失败时返回 null
  */
 export async function postJsonResponseJson(u, data, opt = {}) {

package/lib/scan.d.ts

@@ -68,9 +68,9 @@ export declare class Scan {
 export declare function get(link: lDb.Pool | lKv.Kv, token?: string, opt?: IOptions): Promise<Scan>;
 /**
  * --- 对 token 执行访问操作，通常用户扫码后展示的网页所调用，代表已扫码 ---
- * @param link
- * @patam token 必填
- * @param opt
+ * @param link Db 或 Kv
+ * @param token 必填
+ * @param opt 参数
  */
 export declare function scanned(link: lDb.Pool | lKv.Kv, token: string, opt?: IStaticOptions): Promise<boolean>;
 /**

package/lib/scan.js

@@ -218,9 +218,9 @@ export async function get(link, token, opt = {}) {
 }
 /**
  * --- 对 token 执行访问操作，通常用户扫码后展示的网页所调用，代表已扫码 ---
- * @param link
- * @patam token 必填
- * @param opt
+ * @param link Db 或 Kv
+ * @param token 必填
+ * @param opt 参数
  */
 export async function scanned(link, token, opt = {}) {
     const time = lTime.stamp();

package/lib/sql.d.ts

@@ -22,7 +22,7 @@ export declare class Sql {
     /** --- 表别名列表 --- */
     private readonly _alias;
     /** --- PostgreSQL 占位符计数器 --- */
-    private _placeholder;
+    private _placeholderCounter;
     constructor(pre?: string, opt?: {
         'data'?: kebab.DbValue[];
         'sql'?: string[];
@@ -39,6 +39,12 @@ export declare class Sql {
      * @param vs [] | [][] 数据
      */
     values(cs: string[] | Record<string, kebab.DbValue>, vs?: kebab.DbValue[] | kebab.DbValue[][]): this;
+    /**
+     * --- 如果存在则更新不存在则插入（UPSERT）---
+     * @param data 更新的数据
+     * @param conflict 冲突字段，PostgreSQL 用于指定 ON CONFLICT 字段；MySQL 时忽略，因为会对所有唯一键冲突执行更新
+     */
+    upsert(data: kebab.Json, conflict?: string | string[]): this;
     /**
      * --- '*', 'xx' ---
      * @param c 字段字符串或字段数组
@@ -59,13 +65,13 @@ export declare class Sql {
     delete(f: string): this;
     /**
      * --- 联查另一个 sql 对象 ---
-     * @param sql sql 对象
+     * @param lsql sql 对象
      * @param type 类型
      */
     union(lsql: Sql, type?: string): this;
     /**
      * --- 所有联查另一个 sql 对象 ---
-     * @param sql sql 对象
+     * @param lsql sql 对象
      */
     unionAll(lsql: Sql): this;
     /**
@@ -187,8 +193,6 @@ export declare class Sql {
      * @param sql
      */
     append(sql: string): this;
-    /** --- 获取占位符 --- */
-    placeholder(): string;
     /**
      * --- 对字段进行包裹 ---
      * @param str
@@ -201,6 +205,13 @@ export declare class Sql {
      * @param str
      */
     private _isField;
+    /** --- 获取占位符 --- */
+    private _placeholder;
+    /**
+     * --- 处理单个值,检测数据类型并返回 SQL 和 data ---
+     * @param v 要处理的值
+     */
+    private _processValue;
 }
 /**
  * --- 创建 sql 对象 ---