@maiyunnet/kebab 2.0.7 → 2.0.9

package/lib/time.js

@@ -38,20 +38,35 @@ exports.get = get;
 exports.stamp = stamp;
 exports.isMs = isMs;
 exports.format = format;
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-6-6 12:04:15
+ * Last: 2020-3-29 23:41:21, 2024-1-18 17:16:50, 2024-8-5 10:55:21
+ */
 const sCtr = __importStar(require("../sys/ctr"));
+/** --- 一小时的秒数 --- */
 exports.HOUR = 3600;
+/** --- 一天的秒数 --- */
 exports.DAY = 86400;
+/** --- 一年（365 天） */
 exports.YEAR = 31536000;
+/** --- 星期名 --- */
 const dayNames = [
     ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
     ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
 ];
+/** --- 月份名 --- */
 const monthNames = [
     ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
     ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
 ];
 class Time {
+    /**
+     * --- 构造函数 ---
+     * @param opt
+     */
     constructor(ctr, opt) {
+        /** --- 当前时区 --- */
         this._zone = 0;
         this._zone = opt.zone ?? ctr.getPrototype('_config').set.timezone ?? 0;
         if (opt.data) {
@@ -65,6 +80,7 @@ class Time {
             }
             else if (typeof opt.data === 'string') {
                 this._date = new Date(opt.data);
+                /** --- 与当前设定时区的差小时 --- */
                 const offset = this._date.getTimezoneOffset() / 60 + this._zone;
                 if (offset !== 0) {
                     this._date.setUTCHours(this._date.getUTCHours() - offset);
@@ -75,26 +91,53 @@ class Time {
             this._date = new Date();
         }
     }
+    /**
+     * --- 设置时区 ---
+     * @param zone 北京时间如 8
+     */
     setZone(zone) {
         this._zone = zone;
     }
+    /**
+     * --- 获取时区 ---
+     */
     getZone() {
         return this._zone;
     }
+    /**
+     * --- 获取 UTC 字符串 ---
+     */
     toUTCString() {
         return this._date.toUTCString();
     }
+    /**
+     * --- 获取格式化的字符串 ---
+     * @param f 格式化字符串
+     * @param zone 时区小时，如 8
+     */
     format(f, zone) {
         return format(zone ?? 0, f, this._date);
     }
+    /**
+     * --- 获取秒级时间戳 ---
+     */
     stamp() {
         return stamp(this._date);
     }
 }
 exports.Time = Time;
+/**
+ * --- 创建获取一个时间对象 ---
+ * @param opt
+ */
 function get(ctr, opt = {}) {
     return new Time(ctr, opt);
 }
+/**
+ * --- 获取秒级时间戳 ---
+ * @param date Date 对象可选
+ * @param zone 时区小时或 ctr 对象，如 8，设置 null 则以系统时区为准
+ */
 function stamp(date, zone) {
     if (date) {
         if (date instanceof Date) {
@@ -109,7 +152,9 @@ function stamp(date, zone) {
         else {
             zone *= 60;
         }
+        /** --- 时区是否是负数 --- */
         const negative = zone < 0;
+        /** --- 时区绝对值 --- */
         const zoneabs = Math.abs(zone);
         return Math.floor((new Date(`${date} ${negative ? '-' : '+'}${Math.floor(zoneabs / 60)}:${zoneabs % 60}`)).getTime() / 1000);
     }
@@ -117,9 +162,19 @@ function stamp(date, zone) {
         return Math.floor(Date.now() / 1000);
     }
 }
+/**
+ * --- 是否是毫秒 ---
+ * @param time 要判断的时间戳
+ */
 function isMs(time) {
     return time > 1000000000000 ? true : false;
 }
+/**
+ * --- 将时间对象转换为时间字符串 ---
+ * @param zone 时区小时或 ctr 对象，如 8，设置 null 则以系统时区为准
+ * @param f 转换格式
+ * @param date 时间对象或秒/毫秒级数字，如果是秒请乘以 1000
+ */
 function format(zone, f, date) {
     const over = [];
     if (date === undefined) {

package/lib/ws.d.ts

@@ -1,12 +1,19 @@
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-6-2 20:42
+ * Last: 2020-4-9 22:33:11, 2022-09-13 13:32:01, 2022-12-30 19:13:07, 2024-2-6 23:53:45, 2024-12-23 01:33:16, 2025-1-28 21:05:51
+ */
 import * as http from 'http';
 import * as net from 'net';
 import * as types from '../types';
 import * as sCtr from '../sys/ctr';
+/** --- 一般用 SIMPLE --- */
 export declare enum EFrameReceiveMode {
     STANDARD = 0,
     LITE = 1,
     SIMPLE = 2
 }
+/** --- OPCODE --- */
 export declare enum EOpcode {
     CONTINUATION = 0,
     TEXT = 1,
@@ -15,51 +22,78 @@ export declare enum EOpcode {
     PING = 9,
     PONG = 10
 }
+/** --- 请求的传入参数选项 --- */
 export interface IConnectOptions {
+    /** --- 秒数 --- */
     'timeout'?: number;
     'hosts'?: Record<string, string>;
     'local'?: string;
     'headers'?: types.THttpHeaders;
+    /** --- cookie 托管对象 --- */
     'cookie'?: Record<string, types.ICookie>;
+    /** --- 小帧模式，默认 false --- */
     'mode'?: EFrameReceiveMode;
+    /** --- 加密模式，默认 true --- */
     'masking'?: boolean;
+    /** --- 正向 mproxy 代理，url 如 wss://xxx/abc --- */
     'mproxy'?: {
         'url': string;
         'auth': string;
     };
 }
+/** --- 正向代理请求的传入参数选项 --- */
 export interface IMproxyOptions {
+    /** --- 秒数 --- */
     'timeout'?: number;
     'hosts'?: Record<string, string>;
     'local'?: string;
     'headers'?: types.THttpHeaders;
+    /** --- 小帧模式，默认 false --- */
     'mode'?: EFrameReceiveMode;
+    /** --- 加密模式，默认 true --- */
     'masking'?: boolean;
 }
+/** --- 反向代理请求的传入参数选项 --- */
 export interface IRproxyOptions {
+    /** --- 秒数 --- */
     'timeout'?: number;
     'hosts'?: Record<string, string>;
     'local'?: string;
     'headers'?: types.THttpHeaders;
+    /** --- 小帧模式，默认 false --- */
     'mode'?: EFrameReceiveMode;
+    /** --- 加密模式，默认 true --- */
     'masking'?: boolean;
+    /** --- 正向 mproxy 代理，url 如 wss://xxx/abc --- */
     'mproxy'?: {
         'url': string;
         'auth': string;
     };
 }
 export declare class Socket {
+    /** --- 当前的 ws 对象 --- */
     private _ws;
     constructor(request?: http.IncomingMessage, socket?: net.Socket, options?: {
         'headers'?: http.OutgoingHttpHeaders;
         'timeout'?: number;
     });
+    /**
+     * --- 以客户端形式发起链接 ---
+     * @param u 以 ws, wss 开头的地址
+     * @param opt 参数
+     */
     connect(u: string, opt?: IConnectOptions): Promise<this | null>;
+    /** --- 创建成功后第一时间绑定事件 --- */
     private _bindEvent;
+    /** --- 还未开启监听时来的数据将存在这里 --- */
     private readonly _waitMsg;
+    /** --- 还未开启 error 监听时产生的 error 错误对象 --- */
     private _error;
+    /** --- 还未开启 close 监听时是不是就已经 close --- */
     private _close;
+    /** --- 未绑定自定义监听事件的默认执行函数 --- */
     private _on;
+    /** --- 绑定监听 --- */
     on(event: 'message', cb: (msg: {
         'opcode': EOpcode;
         'data': Buffer | string;
@@ -68,20 +102,54 @@ export declare class Socket {
     on(event: 'drain' | 'close' | 'end', cb: () => void | Promise<void>): this;
     end(): void;
     destroy(): void;
+    /** --- 发送文本 --- */
     writeText(data: string): boolean;
+    /** --- 发送结果对象字符串 --- */
     writeResult(data: types.Json): boolean;
+    /** --- 发送二进制 --- */
     writeBinary(data: string | Buffer | Array<string | Buffer>): boolean;
+    /** --- 当前是否是可写状态 --- */
     get writable(): boolean;
+    /** --- 当前是否已经结束读取，并且无法继续读取 --- */
     get ended(): boolean;
+    /** --- 当前是否已经结束写入，并且无法继续写入 --- */
     get finished(): boolean;
+    /**
+     * --- 当前连接是不是服务器连接 ---
+     */
     get isServer(): boolean;
+    /** --- 发送 ping --- */
     ping(data?: Buffer | string): boolean;
+    /** --- 发送 ping --- */
     pong(data?: Buffer | string): boolean;
 }
+/**
+ * --- 创建一个 ws 客户端发起 ws 请求 ---
+ * @param u 以 ws, wss 开头的地址
+ * @param opt 参数
+ */
 export declare function connect(u: string, opt?: IConnectOptions): Promise<Socket | null>;
+/**
+ * --- 创建一个 ws 服务器接收处理器 ---
+ * @param request Http 请求端
+ * @param socket 响应双向 socket
+ */
 export declare function createServer(request: http.IncomingMessage, socket: net.Socket, options?: {
     'headers'?: http.OutgoingHttpHeaders;
     'timeout'?: number;
 }): Socket;
+/**
+ * --- 正向 mproxy 代理，读取 get 的 url 为实际请求地址 ---
+ * --- get: url, auth ---
+ * @param ctr 当前控制器
+ * @param auth 校验字符串，读取 get 的 auth 和本参数做比对
+ * @param opt 参数
+ */
 export declare function mproxy(ctr: sCtr.Ctr, auth: string, opt?: IMproxyOptions): Promise<number>;
+/**
+ * --- 反向代理，将本 socket 连接反代到其他网址，在 ws 的 onLoad 事件中使用 ---
+ * @param ctr 当前控制器
+ * @param url 反代真实请求地址，如有 get 需要自行添加
+ * @param opt 参数
+ */
 export declare function rproxy(ctr: sCtr.Ctr, url: string, opt?: IRproxyOptions): Promise<boolean>;

package/lib/ws.js

@@ -38,15 +38,19 @@ exports.connect = connect;
 exports.createServer = createServer;
 exports.mproxy = mproxy;
 exports.rproxy = rproxy;
+// --- 第三方 ---
 const liws = __importStar(require("@litert/websocket"));
+// --- 库 ---
 const lText = __importStar(require("../lib/text"));
 const lNet = __importStar(require("../lib/net"));
+/** --- 一般用 SIMPLE --- */
 var EFrameReceiveMode;
 (function (EFrameReceiveMode) {
     EFrameReceiveMode[EFrameReceiveMode["STANDARD"] = 0] = "STANDARD";
     EFrameReceiveMode[EFrameReceiveMode["LITE"] = 1] = "LITE";
     EFrameReceiveMode[EFrameReceiveMode["SIMPLE"] = 2] = "SIMPLE";
 })(EFrameReceiveMode || (exports.EFrameReceiveMode = EFrameReceiveMode = {}));
+/** --- OPCODE --- */
 var EOpcode;
 (function (EOpcode) {
     EOpcode[EOpcode["CONTINUATION"] = 0] = "CONTINUATION";
@@ -59,14 +63,19 @@ var EOpcode;
 const liwsServer = liws.createServer();
 class Socket {
     constructor(request, socket, options = {}) {
+        /** --- 还未开启监听时来的数据将存在这里 --- */
         this._waitMsg = [];
+        /** --- 还未开启 error 监听时产生的 error 错误对象 --- */
         this._error = null;
+        /** --- 还未开启 close 监听时是不是就已经 close --- */
         this._close = false;
+        /** --- 未绑定自定义监听事件的默认执行函数 --- */
         this._on = {
             message: (msg) => {
                 this._waitMsg.push(msg);
             },
             drain: () => {
+                // --- nothing ---
             },
             error: (e) => {
                 this._error = e;
@@ -75,11 +84,13 @@ class Socket {
                 this._close = true;
             },
             end: () => {
+                // --- nothing ---
             }
         };
         if (!request || !socket) {
             return;
         }
+        // --- 一定是 server 模式 ---
         this._ws = liwsServer.accept({
             'request': request,
             'socket': socket,
@@ -88,11 +99,17 @@ class Socket {
         });
         this._bindEvent();
     }
+    /**
+     * --- 以客户端形式发起链接 ---
+     * @param u 以 ws, wss 开头的地址
+     * @param opt 参数
+     */
     async connect(u, opt = {}) {
         const uri = lText.parseUrl(u);
         if (!uri.hostname) {
             return null;
         }
+        /** --- 正向代理的地址 --- */
         const puri = opt.mproxy ? lText.parseUrl(opt.mproxy.url) : null;
         const timeout = opt.timeout ?? 10;
         const hosts = opt.hosts ?? {};
@@ -106,16 +123,20 @@ class Socket {
             }
         }
         headers['user-agent'] ??= 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.86 Safari/537.36';
+        // --- cookie 托管 ---
         if (opt.cookie) {
             headers['cookie'] = lNet.buildCookieQuery(opt.cookie, uri);
         }
+        // --- ssl ---
         const ca = puri ?
             puri.protocol === 'wss:' ? await lNet.getCa() : null :
             uri.protocol === 'wss:' ? await lNet.getCa() : null;
         if (!ca && hosts[uri.hostname]) {
+            // --- 没有 ca，但是要设置 额外的 host ---
             headers['host'] = uri.hostname + (uri.port ? ':' + uri.port : '');
         }
         try {
+            // --- 重定义 IP ---
             const host = puri?.hostname ?? uri.hostname ?? '';
             const port = (puri ? puri.port : uri.port) ?? 443;
             const path = puri ? puri.path + (puri.path?.includes('?') ? '&' : '?') + lText.queryStringify({
@@ -152,6 +173,7 @@ class Socket {
             return null;
         }
     }
+    /** --- 创建成功后第一时间绑定事件 --- */
     _bindEvent() {
         this._ws.on('message', (msg) => {
             (async () => {
@@ -173,6 +195,7 @@ class Socket {
                     'data': data
                 });
             })().catch(() => {
+                // --- nothing ---
             });
         }).on('drain', () => {
             this._on.drain();
@@ -205,6 +228,7 @@ class Socket {
                 break;
             }
             default: {
+                // --- close ---
                 if (!this._close) {
                     break;
                 }
@@ -219,36 +243,46 @@ class Socket {
     destroy() {
         this._ws.destroy();
     }
+    /** --- 发送文本 --- */
     writeText(data) {
         if (!this._ws.writable) {
             return false;
         }
         return this._ws.writeText(data);
     }
+    /** --- 发送结果对象字符串 --- */
     writeResult(data) {
         if (!this._ws.writable) {
             return false;
         }
         return this._ws.writeText(lText.stringifyResult(data));
     }
+    /** --- 发送二进制 --- */
     writeBinary(data) {
         if (!this._ws.writable) {
             return false;
         }
         return this._ws.writeBinary(data);
     }
+    /** --- 当前是否是可写状态 --- */
     get writable() {
         return this._ws.writable;
     }
+    /** --- 当前是否已经结束读取，并且无法继续读取 --- */
     get ended() {
         return this._ws.ended;
     }
+    /** --- 当前是否已经结束写入，并且无法继续写入 --- */
     get finished() {
         return this._ws.finished;
     }
+    /**
+     * --- 当前连接是不是服务器连接 ---
+     */
     get isServer() {
         return this._ws.isServer;
     }
+    /** --- 发送 ping --- */
     ping(data) {
         try {
             this._ws.ping(data);
@@ -258,6 +292,7 @@ class Socket {
             return false;
         }
     }
+    /** --- 发送 ping --- */
     pong(data) {
         try {
             this._ws.pong(data);
@@ -269,15 +304,31 @@ class Socket {
     }
 }
 exports.Socket = Socket;
+/**
+ * --- 创建一个 ws 客户端发起 ws 请求 ---
+ * @param u 以 ws, wss 开头的地址
+ * @param opt 参数
+ */
 function connect(u, opt = {}) {
     const s = new Socket();
     return s.connect(u, opt);
 }
+/**
+ * --- 创建一个 ws 服务器接收处理器 ---
+ * @param request Http 请求端
+ * @param socket 响应双向 socket
+ */
 function createServer(request, socket, options = {}) {
     return new Socket(request, socket, options);
 }
+/**
+ * --- 绑定 socket 管道 ---
+ * @param s1 第一个 socket
+ * @param s2 第二个 socket
+ */
 function bindPipe(s1, s2) {
     return new Promise((resolve) => {
+        // --- 监听发送端的 ---
         s1.on('message', (msg) => {
             switch (msg.opcode) {
                 case EOpcode.TEXT:
@@ -303,11 +354,13 @@ function bindPipe(s1, s2) {
                     break;
                 }
                 default: {
+                    // --- EOpcode.CONTINUATION ---
                 }
             }
         }).on('close', () => {
             resolve();
         });
+        // --- 监听远程端的 ---
         s2.on('message', (msg) => {
             switch (msg.opcode) {
                 case EOpcode.TEXT:
@@ -333,6 +386,7 @@ function bindPipe(s1, s2) {
                     break;
                 }
                 default: {
+                    // --- EOpcode.CONTINUATION ---
                 }
             }
         }).on('close', () => {
@@ -340,9 +394,18 @@ function bindPipe(s1, s2) {
         });
     });
 }
+/**
+ * --- 正向 mproxy 代理，读取 get 的 url 为实际请求地址 ---
+ * --- get: url, auth ---
+ * @param ctr 当前控制器
+ * @param auth 校验字符串，读取 get 的 auth 和本参数做比对
+ * @param opt 参数
+ */
 async function mproxy(ctr, auth, opt = {}) {
     const req = ctr.getPrototype('_req');
+    /** --- 请求端产生的双向 socket --- */
     const socket = ctr.getPrototype('_socket');
+    /** --- 客户端请求中的 get 的数据 --- */
     const get = ctr.getPrototype('_get');
     if (get['auth'] !== auth) {
         return 0;
@@ -352,6 +415,8 @@ async function mproxy(ctr, auth, opt = {}) {
     }
     opt.headers ??= {};
     Object.assign(opt.headers, lNet.filterProxyHeaders(req.headers));
+    // --- 发起请求 ---
+    /** --- 远程端的双向 socket --- */
     const rsocket = await connect(get['url'], opt);
     if (!rsocket) {
         return -2;
@@ -359,11 +424,20 @@ async function mproxy(ctr, auth, opt = {}) {
     await bindPipe(socket, rsocket);
     return 1;
 }
+/**
+ * --- 反向代理，将本 socket 连接反代到其他网址，在 ws 的 onLoad 事件中使用 ---
+ * @param ctr 当前控制器
+ * @param url 反代真实请求地址，如有 get 需要自行添加
+ * @param opt 参数
+ */
 async function rproxy(ctr, url, opt = {}) {
     const req = ctr.getPrototype('_req');
+    /** --- 请求端产生的双向 socket --- */
     const socket = ctr.getPrototype('_socket');
     opt.headers ??= {};
     Object.assign(opt.headers, lNet.filterProxyHeaders(req.headers));
+    // --- 发起请求 ---
+    /** --- 远程端的双向 socket --- */
     const rsocket = await connect(url, opt);
     if (!rsocket) {
         return false;

package/lib/zip.d.ts

@@ -1,20 +1,49 @@
 import jszip from 'jszip';
 import * as types from '../types';
+/**
+ * --- 本库主要用于读取 zip，请尽量不要用来写入 zip，尤其是大文件 zip ---
+ */
 export declare class Zip {
+    /** --- zip 对象 --- */
     private readonly _zip;
+    /** --- 当前路径，以 / 开头以 / 结尾 --- */
     private _path;
     constructor(zip: jszip);
     getContent(path: string): Promise<string | null>;
     getContent<T extends types.TZipOutputType>(path: string, type: T): Promise<types.IZipOutputByType[T] | null>;
+    /**
+     * --- 写入文件内容 ---
+     * @param path 文件路径
+     * @param data 要写入的内容
+     * @param options 选项
+     */
     putContent<T extends types.TZipInputType>(path: string, data: types.IZipInputByType[T], options?: {
         'base64'?: boolean;
         'binary'?: boolean;
         'date'?: Date;
     }): void;
+    /**
+     * --- 删除一个文件/文件夹（深度删除） ---
+     * @param path 要删除的文件路径
+     */
     unlink(path: string): void;
+    /**
+     * --- 获取对象是否存在，存在则返回 stats 对象，否则返回 null ---
+     * @param path 对象路径
+     * @param options 选项
+     */
     stats(path: string): types.IZipStats | null;
+    /**
+     * --- 判断是否是目录或目录是否存在，是的话返回 stats ---
+     * @param path 判断路径
+     */
     isDir(path: string): types.IZipStats | false;
+    /**
+     * --- 判断是否是文件或文件是否存在，是的话返回 stats ---
+     * @param path 判断路径
+     */
     isFile(path: string): types.IZipStats | false;
+    /** --- 读取目录，hasChildren: false, hasDir: true, pathAsKey: false --- */
     readDir(path?: string, opt?: {
         'hasChildren'?: boolean;
         'hasDir'?: boolean;
@@ -26,15 +55,39 @@ export declare class Zip {
         'pathAsKey': true;
     }): Record<string, types.IZipItem>;
     private _readDir;
+    /** --- 目录列表缓存 --- */
     private _list;
+    /**
+     * --- 重建目录列表缓存 ---
+     */
     private _refreshList;
+    /**
+     * --- 获取当前目录，末尾不带 / ---
+     * @return string
+     */
     pwd(): string;
+    /**
+     * --- 进入一个目录（不存在也能进入，需要自行判断） ---
+     * --- 返回进入后的路径值 ---
+     * @param dir 相对路径或绝对路径
+     */
     cd(dir: string): string;
+    /**
+     * --- 打包 zip ---
+     * @param options 选项
+     */
     generate<T extends types.TZipOutputType>(options?: {
         'type'?: T;
         'level'?: number;
         'onUpdate'?: (percent: number, currentFile: string | null) => void;
     }): Promise<types.IZipOutputByType[T]>;
+    /**
+     * --- 获取 path 和 string/Buffer 对应的文件列表 ---
+     */
     getList(): Promise<Record<string, Buffer | string>>;
 }
+/**
+ * --- 获取 zip 对象 ---
+ * @param data 对象数据
+ */
 export declare function get(data?: types.TZipInputFileFormat): Promise<Zip | null>;