@maiyunnet/kebab 2.0.7 → 2.0.8

package/index.d.ts

@@ -1,7 +1,17 @@
-export declare const VER = "2.0.7";
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-3-30 12:46:41
+ * Last: 2020-3-8 21:04:24, 2022-07-22 14:20:34, 2023-5-24 01:34:57, 2025-6-13 14:49:27
+ * --- 本文件用来定义每个目录实体地址的常量 ---
+ * --- npx tsc-alias -w ---
+ */
+/** --- 当前系统版本号 --- */
+export declare const VER = "2.0.8";
+/** --- 框架根目录，以 / 结尾  --- */
 export declare const ROOT_PATH: string;
 export declare const LIB_PATH: string;
 export declare const SYS_PATH: string;
+/** --- 执行根目录，以 / 结尾 --- */
 export declare const ROOT_CWD: string;
 export declare const CONF_CWD: string;
 export declare const CERT_CWD: string;

package/index.js

@@ -1,12 +1,24 @@
 "use strict";
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-3-30 12:46:41
+ * Last: 2020-3-8 21:04:24, 2022-07-22 14:20:34, 2023-5-24 01:34:57, 2025-6-13 14:49:27
+ * --- 本文件用来定义每个目录实体地址的常量 ---
+ * --- npx tsc-alias -w ---
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MOD_CWD = exports.FTMP_CWD = exports.IND_CWD = exports.WWW_CWD = exports.LOG_CWD = exports.LIB_CWD = exports.VHOST_CWD = exports.CERT_CWD = exports.CONF_CWD = exports.ROOT_CWD = exports.SYS_PATH = exports.LIB_PATH = exports.ROOT_PATH = exports.VER = void 0;
-exports.VER = '2.0.7';
+/** --- 当前系统版本号 --- */
+exports.VER = '2.0.8';
+// --- 服务端用的路径 ---
+/** --- /xxx/xxx --- */
 const dirname = __dirname.replace(/\\/g, '/');
+/** --- 框架根目录，以 / 结尾  --- */
 exports.ROOT_PATH = dirname + '/';
 exports.LIB_PATH = exports.ROOT_PATH + 'lib/';
 exports.SYS_PATH = exports.ROOT_PATH + 'sys/';
 const cwd = process.cwd().replace(/\\/g, '/');
+/** --- 执行根目录，以 / 结尾 --- */
 exports.ROOT_CWD = cwd + '/';
 exports.CONF_CWD = exports.ROOT_CWD + 'conf/';
 exports.CERT_CWD = exports.CONF_CWD + 'cert/';

package/lib/buffer.d.ts

@@ -1,25 +1,50 @@
+/** --- 读对象 --- */
 export declare class Reader {
     private readonly _buffer;
+    /** --- 当前读取位置 --- */
     private _offset;
     constructor(buffer: Buffer);
+    /** --- 读取一个无符号8位整数, BYTE --- */
     readUInt8(): number;
+    /** --- 读取一个无符号16位整数（大端模式），WORD --- */
     readUInt16BE(): number;
+    /** --- 读取一个无符号32位整数（大端模式）, DWORD --- */
     readUInt32BE(): number;
+    /** --- 读取一个 BCD 编码的字符串（每个字节表示两个数字）--- */
     readBCDString(length?: number): string;
+    /** --- 读取普通 string --- */
     readString(length?: number, encoding?: BufferEncoding): string;
+    /** --- 读取 Buffer --- */
     readBuffer(length?: number): Buffer;
+    /** --- 获取完整的 buffer 长度 --- */
     length(): number;
 }
+/** --- 写对象 --- */
 export declare class Writer {
     private readonly _buffer;
+    /** --- 当前读取位置 --- */
     private _offset;
     constructor(size: number);
+    /** --- [1 字节] 写入一个无符号 8 位整数 --- */
     writeUInt8(value: number): void;
+    /** --- [2 字节] 写入一个无符号 16 位整数（大端模式） --- */
     writeUInt16BE(value: number): void;
+    /** --- [4 字节] 写入一个无符号 32 位整数（大端模式） --- */
     writeUInt32BE(value: number): void;
+    /** --- [每字节 2 数字] 写入一个 BCD 编码的字符串（仅支持数字） --- */
     writeBCDString(value: string): void;
+    /** --- 写入普通字符串，返回写入的长度 --- */
     writeString(value: string, encoding?: BufferEncoding): number;
+    /** --- 返回 Buffer 对象 --- */
     get(): Buffer;
 }
+/**
+ * --- Buffer Reader 对象 ---
+ * @param buffer 要读取的 buffer
+ */
 export declare function getReader(buffer: Buffer): Reader;
+/**
+ * --- Buffer Writer 对象 ---
+ * @param buffer 要读取的 buffer
+ */
 export declare function getWriter(size: number): Writer;

package/lib/buffer.js

@@ -3,26 +3,32 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Writer = exports.Reader = void 0;
 exports.getReader = getReader;
 exports.getWriter = getWriter;
+/** --- 读对象 --- */
 class Reader {
     constructor(buffer) {
+        /** --- 当前读取位置 --- */
         this._offset = 0;
         this._buffer = buffer;
     }
+    /** --- 读取一个无符号8位整数, BYTE --- */
     readUInt8() {
         const value = this._buffer.readUInt8(this._offset);
         this._offset += 1;
         return value;
     }
+    /** --- 读取一个无符号16位整数（大端模式），WORD --- */
     readUInt16BE() {
         const value = this._buffer.readUInt16BE(this._offset);
         this._offset += 2;
         return value;
     }
+    /** --- 读取一个无符号32位整数（大端模式）, DWORD --- */
     readUInt32BE() {
         const value = this._buffer.readUInt32BE(this._offset);
         this._offset += 4;
         return value;
     }
+    /** --- 读取一个 BCD 编码的字符串（每个字节表示两个数字）--- */
     readBCDString(length) {
         if (length === undefined) {
             length = this._buffer.length - this._offset;
@@ -30,12 +36,13 @@ class Reader {
         let str = '';
         for (let i = 0; i < length; i++) {
             const byte = this._buffer.readUInt8(this._offset + i);
-            str += (byte >> 4).toString(16).toUpperCase();
-            str += (byte & 0x0f).toString(16).toUpperCase();
+            str += (byte >> 4).toString(16).toUpperCase(); // --- 高四位表示第一个数字 ---
+            str += (byte & 0x0f).toString(16).toUpperCase(); // --- 低四位表示第二个数字 ---
         }
         this._offset += length;
         return str;
     }
+    /** --- 读取普通 string --- */
     readString(length, encoding = 'utf8') {
         if (length === undefined) {
             length = this._buffer.length - this._offset;
@@ -51,42 +58,51 @@ class Reader {
         this._offset += length;
         return Buffer.from(buf).toString(encoding);
     }
+    /** --- 读取 Buffer --- */
     readBuffer(length) {
         if (length === undefined) {
             length = this._buffer.length - this._offset;
         }
         return this._buffer.subarray(this._offset, this._offset += length);
     }
+    /** --- 获取完整的 buffer 长度 --- */
     length() {
         return this._buffer.length;
     }
 }
 exports.Reader = Reader;
+/** --- 写对象 --- */
 class Writer {
     constructor(size) {
+        /** --- 当前读取位置 --- */
         this._offset = 0;
         this._buffer = Buffer.alloc(size);
     }
+    /** --- [1 字节] 写入一个无符号 8 位整数 --- */
     writeUInt8(value) {
         this._buffer.writeUInt8(value, this._offset);
         this._offset += 1;
     }
+    /** --- [2 字节] 写入一个无符号 16 位整数（大端模式） --- */
     writeUInt16BE(value) {
         this._buffer.writeUInt16BE(value, this._offset);
         this._offset += 2;
     }
+    /** --- [4 字节] 写入一个无符号 32 位整数（大端模式） --- */
     writeUInt32BE(value) {
         this._buffer.writeUint32BE(value, this._offset);
         this._offset += 4;
     }
+    /** --- [每字节 2 数字] 写入一个 BCD 编码的字符串（仅支持数字） --- */
     writeBCDString(value) {
         for (let i = 0; i < value.length; i += 2) {
-            const high = parseInt(value[i], 10);
-            const low = parseInt(value[i + 1], 10);
-            const byte = (high << 4) | low;
+            const high = parseInt(value[i], 10); // --- 取十位 ---
+            const low = parseInt(value[i + 1], 10); // --- 取个位 ---
+            const byte = (high << 4) | low; // --- 拼接为一个字节 ---
             this.writeUInt8(byte);
         }
     }
+    /** --- 写入普通字符串，返回写入的长度 --- */
     writeString(value, encoding = 'utf8') {
         const bytes = Buffer.from(value, encoding);
         for (const byte of bytes) {
@@ -95,14 +111,23 @@ class Writer {
         this._offset += bytes.length;
         return bytes.length;
     }
+    /** --- 返回 Buffer 对象 --- */
     get() {
         return this._buffer.subarray(0, this._offset);
     }
 }
 exports.Writer = Writer;
+/**
+ * --- Buffer Reader 对象 ---
+ * @param buffer 要读取的 buffer
+ */
 function getReader(buffer) {
     return new Reader(buffer);
 }
+/**
+ * --- Buffer Writer 对象 ---
+ * @param buffer 要读取的 buffer
+ */
 function getWriter(size) {
     return new Writer(size);
 }

package/lib/captcha.d.ts

@@ -5,8 +5,23 @@ export declare class Captcha {
         'height': number;
         'length': number;
     });
+    /**
+     * --- 获取图片 Buffer ---
+     */
     getBuffer(): string;
+    /**
+     * --- 获取 base64 格式图片 ---
+     */
     getBase64(): string;
+    /**
+     * --- 获取当前随机码 ---
+     */
     getPhrase(): string;
 }
+/**
+ * --- 获取验证码对象 ---
+ * @param width 宽度
+ * @param height 高度
+ * @param length 字符个数
+ */
 export declare function get(width: number, height: number, length?: number): Captcha;

package/lib/captcha.js

@@ -35,6 +35,11 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Captcha = void 0;
 exports.get = get;
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-6-7 12:14:31
+ * Last: 2020-3-11 23:33:19, 2022-09-12 10:38:24, 2022-12-29 01:16:26, 2024-4-1 16:40:42, 2025-6-13 19:45:30
+ */
 const svgCaptcha = __importStar(require("svg-captcha"));
 const mime = __importStar(require("@litert/mime"));
 const core = __importStar(require("../lib/core"));
@@ -51,17 +56,32 @@ class Captcha {
             'charPreset': core.RANDOM_V
         });
     }
+    /**
+     * --- 获取图片 Buffer ---
+     */
     getBuffer() {
         return this._link.data.replace('<rect width="100%" height="100%" fill="#fff"/>', '');
     }
+    /**
+     * --- 获取 base64 格式图片 ---
+     */
     getBase64() {
         return `data:${mime.getMime('svg')};base64,` + Buffer.from(this._link.data.replace('<rect width="100%" height="100%" fill="#fff"/>', '')).toString('base64');
     }
+    /**
+     * --- 获取当前随机码 ---
+     */
     getPhrase() {
         return this._link.text;
     }
 }
 exports.Captcha = Captcha;
+/**
+ * --- 获取验证码对象 ---
+ * @param width 宽度
+ * @param height 高度
+ * @param length 字符个数
+ */
 function get(width, height, length = 4) {
     return new Captcha({
         'width': width,

package/lib/consistent.d.ts

@@ -1,20 +1,71 @@
 export declare class Consistent {
+    /** --- 虚拟节点数量 --- */
     private readonly _vcount;
+    /** --- hash 环 --- */
     private readonly _circle;
+    /** --- circle 的 keys --- */
     private _keys;
     constructor(vcount: number);
+    /**
+     * --- 获取当前的虚拟节点数量 ---
+     */
     getVcount(): number;
+    /**
+     * 添加节点
+     * @param node node 节点名一个或多个
+     */
     add(node: string | string[]): void;
+    /**
+     * 移除节点
+     * @param node node 节点名
+     */
     remove(node: string | string[]): void;
+    /**
+     * 获得一个最近的顺时针节点
+     * @param key 为给定键取 Hash，取得顺时针方向上最近的一个虚拟节点对应的实际节点
+     */
     find(key: string | number): string | null;
+    /**
+     * --- 原数据迁移到新地址 ---
+     * @param keys 原始数据 key 集
+     * @param node 新增的节点一个或多个
+     */
     migration(keys: string | number | Array<string | number>, node: string | string[]): Record<string, {
         'old': string;
         'new': string;
     }>;
 }
 export declare function get(vcount?: number): Consistent;
+/**
+ *--- 快速查找一个 key 属于哪个 node ---
+ * @param key 要查找的key
+ * @param nodes node 列表
+ * @param vcount 虚拟节点数量
+ */
 export declare function fast(key: string | number, nodes: string | string[], vcount?: number): string | null;
+/**
+ * --- hash 函数 ---
+ * @param val 要 hash 的值
+ */
 export declare function hash(val: string | number): number;
+/**
+ * --- 获取区间节点系列 ---
+ * @param min 最小值（含）
+ * @param max 最大值（含）
+ * @param pre 前导
+ */
 export declare function getRange(min: number, max: number, pre?: string): string[];
+/**
+ * --- 添加到圆环 ---
+ * @param circle 圆环
+ * @param node node 节点名一个或多个
+ * @param vcount 虚拟节点数量
+ */
 export declare function addToCircle(circle: Record<string, string>, node: string | string[], vcount?: number): void;
+/**
+ * --- 获得一个最近的顺时针节点 ---
+ * @param circle 圆环
+ * @param key 为给定键取 Hash，取得顺时针方向上最近的一个虚拟节点对应的实际节点
+ * @param keys keys，留空则自动从 circle 上取
+ */
 export declare function findInCircle(circle: Record<string, string>, key: string | number, keys?: string[]): string | null;

package/lib/consistent.js

@@ -40,21 +40,40 @@ exports.hash = hash;
 exports.getRange = getRange;
 exports.addToCircle = addToCircle;
 exports.findInCircle = findInCircle;
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2022-09-12 10:51:16
+ * Last: 2022-09-12 10:51:20, 2023-3-17 10:52:04, 2023-11-15 11:45:28
+ */
 const crypto = __importStar(require("../lib/crypto"));
 class Consistent {
     constructor(vcount) {
+        /** --- 虚拟节点数量 --- */
         this._vcount = 300;
+        /** --- hash 环 --- */
         this._circle = {};
+        /** --- circle 的 keys --- */
         this._keys = [];
         this._vcount = vcount;
     }
+    /**
+     * --- 获取当前的虚拟节点数量 ---
+     */
     getVcount() {
         return this._vcount;
     }
+    /**
+     * 添加节点
+     * @param node node 节点名一个或多个
+     */
     add(node) {
         addToCircle(this._circle, node, this._vcount);
         this._keys = [];
     }
+    /**
+     * 移除节点
+     * @param node node 节点名
+     */
     remove(node) {
         if (typeof node === 'string') {
             node = [node];
@@ -66,6 +85,10 @@ class Consistent {
         }
         this._keys = [];
     }
+    /**
+     * 获得一个最近的顺时针节点
+     * @param key 为给定键取 Hash，取得顺时针方向上最近的一个虚拟节点对应的实际节点
+     */
     find(key) {
         if (this._keys.length === 0) {
             this._keys = Object.keys(this._circle);
@@ -75,11 +98,17 @@ class Consistent {
         }
         return findInCircle(this._circle, key, this._keys);
     }
+    /**
+     * --- 原数据迁移到新地址 ---
+     * @param keys 原始数据 key 集
+     * @param node 新增的节点一个或多个
+     */
     migration(keys, node) {
         const rtn = {};
         if (!Array.isArray(keys)) {
             keys = [keys];
         }
+        // --- 获取老的 key 对应的 node ---
         const mapOld = {};
         for (const key of keys) {
             const oldNode = this.find(key);
@@ -89,6 +118,7 @@ class Consistent {
             mapOld[key] = oldNode;
         }
         this.add(node);
+        // --- 再逐一检测老的和新的的 node 是否一致 ---
         for (const key of keys) {
             const newNode = this.find(key);
             if (!newNode) {
@@ -109,11 +139,21 @@ exports.Consistent = Consistent;
 function get(vcount = 300) {
     return new Consistent(vcount);
 }
+/**
+ *--- 快速查找一个 key 属于哪个 node ---
+ * @param key 要查找的key
+ * @param nodes node 列表
+ * @param vcount 虚拟节点数量
+ */
 function fast(key, nodes, vcount = 300) {
     const circle = {};
     addToCircle(circle, nodes, vcount);
     return findInCircle(circle, key);
 }
+/**
+ * --- hash 函数 ---
+ * @param val 要 hash 的值
+ */
 function hash(val) {
     if (typeof val === 'number') {
         val = val.toString();
@@ -125,6 +165,12 @@ function hash(val) {
         (bKey.charCodeAt(0) & 0xFF);
     return res & 0xffffffff;
 }
+/**
+ * --- 获取区间节点系列 ---
+ * @param min 最小值（含）
+ * @param max 最大值（含）
+ * @param pre 前导
+ */
 function getRange(min, max, pre = '') {
     const ls = [];
     for (let i = min; i <= max; ++i) {
@@ -132,6 +178,12 @@ function getRange(min, max, pre = '') {
     }
     return ls;
 }
+/**
+ * --- 添加到圆环 ---
+ * @param circle 圆环
+ * @param node node 节点名一个或多个
+ * @param vcount 虚拟节点数量
+ */
 function addToCircle(circle, node, vcount = 300) {
     if (typeof node === 'string') {
         node = [node];
@@ -142,6 +194,12 @@ function addToCircle(circle, node, vcount = 300) {
         }
     }
 }
+/**
+ * --- 获得一个最近的顺时针节点 ---
+ * @param circle 圆环
+ * @param key 为给定键取 Hash，取得顺时针方向上最近的一个虚拟节点对应的实际节点
+ * @param keys keys，留空则自动从 circle 上取
+ */
 function findInCircle(circle, key, keys = []) {
     let count = keys.length;
     if (keys.length === 0) {
@@ -167,5 +225,6 @@ function findInCircle(circle, key, keys = []) {
         }
         return circle[v];
     }
+    // --- 没找到 ---
     return circle[keys[0]];
 }