@maiyunnet/kebab 2.0.6 → 2.0.8

package/lib/kv.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-5-30 19:25:22
+ * Last: 2020-3-28 18:54:04, 2022-09-12 23:24:45, 2022-09-22 01:06:22, 2024-2-21 13:32:56, 2024-8-21 16:59:57
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -36,22 +41,33 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Connection = exports.Pool = void 0;
 exports.get = get;
 exports.getConnectionList = getConnectionList;
+// --- Pool 是使用时必须要一个用户创建一份的，Connection 是池子里获取的 ---
+// --- 为啥 Pool 要独立，因为有些配置项目不能存在 Connection 是用户单独使用的，例如 pre ---
+// --- 第三方 ---
 const redis = __importStar(require("@litert/redis"));
+// --- 库和定义 ---
 const time = __importStar(require("../lib/time"));
 const text = __importStar(require("../lib/text"));
+/** --- 连接列表（同一个 host、port、index、auth 只有一个连接） --- */
 const connections = [];
+/**
+ * --- 计划任务 30 秒一次，关闭超过 3 分钟不活动的连接 ---
+ */
 async function checkConnection() {
     const now = time.stamp();
     for (let i = 0; i < connections.length; ++i) {
         const connection = connections[i];
         if (connection.isLost()) {
+            // --- 连接已经丢失，移除 ---
             await connection.end();
             connections.splice(i, 1);
             --i;
             continue;
         }
         if (connection.isUsing()) {
+            // --- 连接正在被使用，看看是否使用超过 3 分钟，超过则不是正常状态 ---
             if (connection.getLast() <= now - 180) {
+                // --- 10 分钟之前开始的 ---
                 console.log(`[kv] [error] There is a transactional connection[${i}] that is not closed.`);
                 await connection.end();
                 connections.splice(i, 1);
@@ -59,9 +75,12 @@ async function checkConnection() {
             }
             continue;
         }
+        // --- 检测 3 分钟内是否使用过 ---
         if (connection.getLast() > now - 180) {
+            // --- 3 分钟内使用过，不管 ---
             continue;
         }
+        // --- 超 3 分钟未被使用，则关闭 ---
         await connection.end();
         connections.splice(i, 1);
         --i;
@@ -83,6 +102,13 @@ class Pool {
             this._etc = ctr.getPrototype('_config').kv;
         }
     }
+    /**
+     * --- 设定一个值 ---
+     * @param key
+     * @param val
+     * @param ttl 秒，0 为不限制
+     * @param mod 设置模式: 空,nx（key不存在才建立）,xx（key存在才修改）
+     */
     async set(key, val, ttl = 0, mod = '') {
         const conn = await this._getConnection();
         if (!conn) {
@@ -92,6 +118,12 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 添加一个值，存在则不变 ---
+     * @param key
+     * @param val
+     * @param ttl 秒，0 为不限制
+     */
     async add(key, val, ttl = 0) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -101,6 +133,12 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 替换一个存在的值 ---
+     * @param key
+     * @param val
+     * @param ttl 秒，0 为不限制
+     */
     async replace(key, val, ttl = 0) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -110,6 +148,11 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 向已存在的值后追加数据 ---
+     * @param key
+     * @param val
+     */
     async append(key, val) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -119,6 +162,11 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 向已存在的值之前追加数据 ---
+     * @param key
+     * @param val
+     */
     async prepend(key, val) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -128,6 +176,10 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 检测 key 是否存在 ---
+     * @param keys
+     */
     async exists(keys) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -137,6 +189,10 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 获取字符串 ---
+     * @param key
+     */
     async get(key) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -146,6 +202,10 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 获取相应的剩余有效期秒数 ---
+     * @param key
+     */
     async ttl(key) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -155,6 +215,10 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 获取相应的剩余有效期毫秒数 ---
+     * @param key
+     */
     async pttl(key) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -164,6 +228,10 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 批量获取值 ---
+     * @param keys key 序列
+     */
     async mSet(rows) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -173,6 +241,10 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 批量获取值 ---
+     * @param keys key 序列
+     */
     async mGet(keys) {
         const conn = await this._getConnection();
         if (conn) {
@@ -188,6 +260,10 @@ class Pool {
             return rtn;
         }
     }
+    /**
+     * --- 获取 json 对象 ---
+     * @param key
+     */
     async getJson(key) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -197,6 +273,10 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 删除已存在的值 ---
+     * @param keys
+     */
     async del(keys) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -206,6 +286,11 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 自增 ---
+     * @param key
+     * @param num 整数或浮点正数
+     */
     async incr(key, num = 1) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -215,6 +300,11 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 自减 ---
+     * @param key
+     * @param num 整数或浮点正数
+     */
     async decr(key, num = 1) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -224,6 +314,11 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 仅修改过期时间不修改值 ---
+     * @param key
+     * @param ttl
+     */
     async expire(key, ttl) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -233,6 +328,10 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 获取服务器上的所有 key 列表 ---
+     * @param pattern
+     */
     async keys(pattern) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -242,6 +341,12 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 根据条件获取服务器上的 keys ---
+     * @param cursor
+     * @param pattern 例如 *
+     * @param count 获取的条数
+     */
     async scan(cursor = 0, pattern = '*', count = 10) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -251,6 +356,9 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 清除当前所选数据库的所有内容 ---
+     */
     async flushDb() {
         const conn = await this._getConnection();
         if (!conn) {
@@ -260,6 +368,9 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 发送 ping ---
+     */
     async ping() {
         const conn = await this._getConnection();
         if (!conn) {
@@ -269,6 +380,13 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 设置哈希表值 ---
+     * @param key key 名
+     * @param field 字段名
+     * @param val 值
+     * @param mod 空,nx(key不存在才建立)
+     */
     async hSet(key, field, val, mod = '') {
         const conn = await this._getConnection();
         if (!conn) {
@@ -278,6 +396,11 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 批量设置哈希值 ---
+     * @param key key 名
+     * @param rows key / val 数组
+     */
     async hMSet(key, rows) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -287,6 +410,11 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 获取哈希值 ---
+     * @param key
+     * @param field
+     */
     async hGet(key, field) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -296,6 +424,11 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 获取哈希 json 对象 ---
+     * @param key
+     * @param field
+     */
     async hGetJson(key, field) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -305,6 +438,11 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 批量获取哈希值 ---
+     * @param key
+     * @param fields
+     */
     async hMGet(key, fields) {
         const conn = await this._getConnection();
         if (conn) {
@@ -320,6 +458,10 @@ class Pool {
             return rtn;
         }
     }
+    /**
+     * --- 批量获取哈希键值对 ---
+     * @param key
+     */
     async hGetAll(key) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -329,6 +471,11 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 删除哈希键 ---
+     * @param key
+     * @param fields 值序列
+     */
     async hDel(key, fields) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -338,6 +485,11 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 判断哈希字段是否存在 ---
+     * @param key
+     * @param field
+     */
     async hExists(key, field) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -347,6 +499,12 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 设置哈希自增自减 ---
+     * @param key key
+     * @param field 字段
+     * @param increment 正数或负数，整数或浮点
+     */
     async hIncr(key, field, increment) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -356,6 +514,10 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 获取哈希所有字段 ---
+     * @param key
+     */
     async hKeys(key) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -437,6 +599,9 @@ class Pool {
         conn.used();
         return r;
     }
+    /**
+     * --- 从连接池获取一个连接，会被自动设置为使用中，需要在执行命令后解除占用 ---
+     */
     async _getConnection() {
         let conn;
         for (const connection of connections) {
@@ -446,6 +611,7 @@ class Pool {
                 (etc.host !== this._etc.host) ||
                 (etc.port !== this._etc.port) ||
                 (etc.index !== this._etc.index)) {
+                // --- 配置项连接项不匹配 ---
                 continue;
             }
             connection.refreshLast();
@@ -454,16 +620,19 @@ class Pool {
             break;
         }
         if (!conn) {
+            // --- 没有找到合适的连接，创建一个 ---
             const link = redis.createCommandClient({
                 'host': this._etc.host,
                 'port': this._etc.port
             });
+            // --- 开始连接 ---
             try {
                 await link.connect();
             }
             catch {
                 return null;
             }
+            // --- 认证 ---
             if (this._etc.user || this._etc.pwd) {
                 try {
                     await link.auth(this._etc.user + this._etc.pwd);
@@ -478,6 +647,7 @@ class Pool {
             conn.setUsing();
             link.on('error', function (err) {
                 conn.setLost();
+                // console.log(`--- redis [${conn._etc.host}:${conn._etc.port}] error ---`);
                 console.log('[KV] [ERROR]', err);
             }).on('close', () => {
                 conn.setLost();
@@ -490,37 +660,67 @@ class Pool {
 exports.Pool = Pool;
 class Connection {
     constructor(etc, link) {
+        /** --- 本连接最后一次使用时间 --- */
         this._last = 0;
+        /** --- 当前连接是否正在被独占使用 --- */
         this._using = false;
+        /** --- 当发生断开，则需从连接池移除连接 --- */
         this._lost = false;
         this._etc = etc;
         this._link = link;
         this.refreshLast();
     }
+    /**
+     * --- 获取连接 etc 信息 ---
+     */
     getEtc() {
         return this._etc;
     }
+    /**
+     * --- 获取最后一次获取连接的时间 ---
+     */
     getLast() {
         return this._last;
     }
+    /**
+     * --- 将本条连接设置为不可用 ---
+     */
     setLost() {
         this._lost = true;
     }
+    /**
+     * --- 是否已经丢失 ---
+     */
     isLost() {
         return this._lost;
     }
+    /**
+     * --- 将本条连接设置占用中 ---
+     */
     setUsing() {
         this._using = true;
     }
+    /**
+     * --- 获取当前状态是否正在被使用中 ---
+     */
     isUsing() {
         return this._using;
     }
+    /**
+     * --- 取消占用 ---
+     */
     used() {
         this._using = false;
     }
+    /**
+     * --- 设定最后使用时间 ---
+     */
     refreshLast() {
         this._last = time.stamp();
     }
+    /**
+     * --- 断开此连接，一般情况下不使用 ---
+     */
     async end() {
         try {
             await this._link.close();
@@ -529,6 +729,14 @@ class Connection {
             return;
         }
     }
+    /**
+     * --- 设定一个值 ---
+     * @param key
+     * @param val
+     * @param ttl 秒，0 为不限制
+     * @param mod 设置模式: 空,nx（key不存在才建立）,xx（key存在才修改）
+     * @param etc 配置项，主要用 etc.pre
+     */
     async set(key, val, ttl, mod, etc) {
         this.refreshLast();
         if (typeof val !== 'string') {
@@ -551,12 +759,32 @@ class Connection {
             return false;
         }
     }
+    /**
+     * --- 添加一个值，存在则不变 ---
+     * @param key
+     * @param val
+     * @param ttl 秒，0 为不限制
+     * @param etc
+     */
     async add(key, val, ttl, etc) {
         return this.set(key, val, ttl, 'nx', etc);
     }
+    /**
+     * --- 替换一个存在的值 ---
+     * @param key
+     * @param val
+     * @param ttl 秒，0 为不限制
+     * @param etc
+     */
     async replace(key, val, ttl, etc) {
         return this.set(key, val, ttl, 'xx', etc);
     }
+    /**
+     * --- 向已存在的值后追加数据 ---
+     * @param key
+     * @param val
+     * @param etc
+     */
     async append(key, val, etc) {
         this.refreshLast();
         try {
@@ -566,6 +794,11 @@ class Connection {
             return false;
         }
     }
+    /**
+     * --- 向已存在的值之前追加数据 ---
+     * @param key
+     * @param val
+     */
     async prepend(key, val, etc) {
         this.refreshLast();
         try {
@@ -592,6 +825,11 @@ end`;
             return false;
         }
     }
+    /**
+     * --- 检测 key 是否存在 ---
+     * @param keys 单个或序列
+     * @param etc
+     */
     async exists(keys, etc) {
         this.refreshLast();
         try {
@@ -607,6 +845,11 @@ end`;
             return 0;
         }
     }
+    /**
+     * --- 获取字符串 ---
+     * @param key
+     * @param etc
+     */
     async get(key, etc) {
         this.refreshLast();
         try {
@@ -616,6 +859,11 @@ end`;
             return null;
         }
     }
+    /**
+     * --- 获取相应的剩余有效期秒数 ---
+     * @param key
+     * @param etc
+     */
     async ttl(key, etc) {
         this.refreshLast();
         try {
@@ -625,6 +873,11 @@ end`;
             return null;
         }
     }
+    /**
+     * --- 获取相应的剩余有效期毫秒数 ---
+     * @param key
+     * @param etc
+     */
     async pttl(key, etc) {
         this.refreshLast();
         try {
@@ -634,6 +887,11 @@ end`;
             return null;
         }
     }
+    /**
+     * --- 批量获取值 ---
+     * @param keys key 序列
+     * @param etc 顺序数组
+     */
     async mGet(keys, etc) {
         this.refreshLast();
         for (let k = 0; k < keys.length; ++k) {
@@ -657,6 +915,12 @@ end`;
         }
         return rtn;
     }
+    /**
+     * --- 批量设置哈希值 ---
+     * @param key key 名
+     * @param rows key / val 数组
+     * @param etc
+     */
     async mSet(rows, etc) {
         this.refreshLast();
         try {
@@ -671,6 +935,11 @@ end`;
             return false;
         }
     }
+    /**
+     * --- 获取 json 对象 ---
+     * @param key
+     * @param etc
+     */
     async getJson(key, etc) {
         const v = await this.get(key, etc);
         if (v === null) {
@@ -679,6 +948,11 @@ end`;
         const r = text.parseJson(v);
         return r === false ? null : r;
     }
+    /**
+     * --- 删除已存在的值 ---
+     * @param keys
+     * @param etc
+     */
     async del(keys, etc) {
         this.refreshLast();
         if (typeof keys === 'string') {
@@ -694,6 +968,12 @@ end`;
             return false;
         }
     }
+    /**
+     * --- 自增 ---
+     * @param key
+     * @param num 整数或浮点正数
+     * @param etc
+     */
     async incr(key, num, etc) {
         this.refreshLast();
         try {
@@ -713,6 +993,12 @@ end`;
             return false;
         }
     }
+    /**
+     * --- 自减 ---
+     * @param key
+     * @param num 整数或浮点正数
+     * @param etc
+     */
     async decr(key, num, etc) {
         this.refreshLast();
         try {
@@ -732,6 +1018,12 @@ end`;
             return false;
         }
     }
+    /**
+     * --- 仅修改过期时间不修改值 ---
+     * @param key
+     * @param ttl
+     * @param etc
+     */
     async expire(key, ttl, etc) {
         this.refreshLast();
         try {
@@ -741,6 +1033,10 @@ end`;
             return false;
         }
     }
+    /**
+     * --- 获取服务器上的所有 key 列表 ---
+     * @param pattern
+     */
     async keys(pattern, etc) {
         this.refreshLast();
         try {
@@ -757,6 +1053,13 @@ end`;
             return false;
         }
     }
+    /**
+     * --- 根据条件获取服务器上的 keys ---
+     * @param cursor
+     * @param pattern 例如 *
+     * @param count 获取的条数
+     * @param etc
+     */
     async scan(cursor, pattern, count, etc) {
         this.refreshLast();
         try {
@@ -770,6 +1073,9 @@ end`;
             return false;
         }
     }
+    /**
+     * --- 清除当前所选数据库的所有内容 ---
+     */
     async flushDb() {
         this.refreshLast();
         try {
@@ -780,6 +1086,9 @@ end`;
             return false;
         }
     }
+    /**
+     * --- 发送 ping ---
+     */
     async ping() {
         this.refreshLast();
         try {
@@ -789,6 +1098,14 @@ end`;
             return false;
         }
     }
+    /**
+     * --- 设置哈希表值 ---
+     * @param key key 名
+     * @param field 字段名
+     * @param val 值
+     * @param mod 空,nx(key不存在才建立)
+     * @param etc
+     */
     async hSet(key, field, val, mod, etc) {
         this.refreshLast();
         try {
@@ -806,6 +1123,12 @@ end`;
             return false;
         }
     }
+    /**
+     * --- 批量设置哈希值 ---
+     * @param key key 名
+     * @param rows key / val 数组
+     * @param etc
+     */
     async hMSet(key, rows, etc) {
         this.refreshLast();
         try {
@@ -822,6 +1145,12 @@ end`;
             return false;
         }
     }
+    /**
+     * --- 获取哈希值 ---
+     * @param key
+     * @param field
+     * @param etc
+     */
     async hGet(key, field, etc) {
         this.refreshLast();
         try {
@@ -831,6 +1160,12 @@ end`;
             return null;
         }
     }
+    /**
+     * --- 获取哈希 json 对象 ---
+     * @param key
+     * @param field
+     * @param etc
+     */
     async hGetJson(key, field, etc) {
         const v = await this.hGet(key, field, etc);
         if (v === null) {
@@ -839,6 +1174,12 @@ end`;
         const r = text.parseJson(v);
         return r === false ? null : v;
     }
+    /**
+     * --- 批量获取哈希值 ---
+     * @param key
+     * @param fields
+     * @param etc
+     */
     async hMGet(key, fields, etc) {
         this.refreshLast();
         try {
@@ -852,6 +1193,11 @@ end`;
             return rtn;
         }
     }
+    /**
+     * --- 批量获取哈希键值对 ---
+     * @param key
+     * @param etc
+     */
     async hGetAll(key, etc) {
         this.refreshLast();
         try {
@@ -861,6 +1207,12 @@ end`;
             return null;
         }
     }
+    /**
+     * --- 删除哈希键 ---
+     * @param key
+     * @param fields 值序列
+     * @param etc
+     */
     async hDel(key, fields, etc) {
         this.refreshLast();
         try {
@@ -870,6 +1222,12 @@ end`;
             return 0;
         }
     }
+    /**
+     * --- 判断哈希字段是否存在 ---
+     * @param key
+     * @param field
+     * @param etc
+     */
     async hExists(key, field, etc) {
         this.refreshLast();
         try {
@@ -879,6 +1237,13 @@ end`;
             return false;
         }
     }
+    /**
+     * --- 设置哈希自增自减 ---
+     * @param key key
+     * @param field 字段
+     * @param increment 正数或负数，整数或浮点
+     * @param etc
+     */
     async hIncr(key, field, increment, etc) {
         this.refreshLast();
         try {
@@ -893,6 +1258,11 @@ end`;
             return 0;
         }
     }
+    /**
+     * --- 获取哈希所有字段 ---
+     * @param key
+     * @param etc
+     */
     async hKeys(key, etc) {
         this.refreshLast();
         try {
@@ -979,12 +1349,19 @@ end`;
     }
 }
 exports.Connection = Connection;
+/**
+ * --- 获取 Kv Pool 对象 ---
+ * @param etc 配置信息可留空
+ */
 function get(ctr, etc) {
     if (!etc) {
         etc = ctr.getPrototype('_config').kv;
     }
     return new Pool(ctr, etc);
 }
+/**
+ * --- 获取当前连接池中所有连接的信息 ---
+ */
 function getConnectionList() {
     const list = [];
     for (let i = 0; i < connections.length; ++i) {