@maiyunnet/kebab 2.0.6 → 2.0.8

package/lib/jwt.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2023-1-31 20:34:47
+ * Last: 2023-1-31 20:34:47, 2023-12-8 13:55:09
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -38,11 +43,19 @@ exports.getOrigin = getOrigin;
 exports.decode = decode;
 exports.block = block;
 exports.get = get;
+// --- 库和定义 ---
 const lCore = __importStar(require("../lib/core"));
 const lTime = __importStar(require("../lib/time"));
 const lText = __importStar(require("../lib/text"));
 const lCrypto = __importStar(require("../lib/crypto"));
 class Jwt {
+    /**
+     * --- 初始化函数，相当于 construct ---
+     * @param ctr 模型实例
+     * @param link Kv 或 Db 实例
+     * @param auth 设为 true 则优先从头 Authorization 或 post _auth 值读取 token
+     * @param opt 选项
+     */
     async init(ctr, opt = {}, link) {
         const config = ctr.getPrototype('_config');
         this._ctr = ctr;
@@ -69,6 +82,7 @@ class Jwt {
         }
         const data = await decode(this._ctr, jwt, this._link, this._name, this._secret);
         if (!data) {
+            // --- 清除 cookie ---
             const cookie = this._ctr.getPrototype('_cookie');
             if (cookie[this._name]) {
                 delete cookie[this._name];
@@ -78,12 +92,16 @@ class Jwt {
         this._ctr.setPrototype('_jwt', data);
         return true;
     }
+    /**
+     * --- 将 _jwt 数据封装并返回（创建新的或者续期老的 token），默认会同时设置一个 cookie（data 值会自动设置 token、exp） ---
+     */
     renew() {
         const time = lTime.stamp();
         const data = this._ctr.getPrototype('_jwt');
         const token = data['token'] ? data['token'] : lCore.random(16, lCore.RANDOM_LUN);
         data['exp'] = time + this._ttl;
         data['token'] = token;
+        // --- 拼装 ---
         const header = lCrypto.base64Encode(lText.stringifyJson({
             'alg': 'HS256',
             'typ': 'JWT'
@@ -99,6 +117,9 @@ class Jwt {
         }
         return jwt;
     }
+    /**
+     * --- 清除 cookie，仅仅清除 cookie，jwt 并不会失效 ---
+     */
     clearCookie() {
         if (this._auth) {
             return;
@@ -108,6 +129,9 @@ class Jwt {
             'ssl': this._ssl
         });
     }
+    /**
+     * --- 销毁 jwt，其实就是将 token block 信息写入 redis，如果没有 redis 则不能销毁，返回数组代表销毁成功的 token 和原 exp，否则失败返回 false ---
+     */
     async destory() {
         if (!this._link) {
             return false;
@@ -136,6 +160,9 @@ class Jwt {
     }
 }
 exports.Jwt = Jwt;
+/**
+ * --- 获取 jwt 原始字符串，不保证有效 ---
+ */
 function getOrigin(ctr, name = '', auth = false) {
     if (!name) {
         name = ctr.getPrototype('_config').jwt.name;
@@ -157,6 +184,10 @@ function getOrigin(ctr, name = '', auth = false) {
     }
     return jwt;
 }
+/**
+ * --- decode ---
+ * 不传入 link 的话，将不做 block 有效校验，只做本身的 exp 有效校验
+ */
 async function decode(ctr, val, link, name = '', secret = '') {
     if (!val) {
         return false;
@@ -172,6 +203,8 @@ async function decode(ctr, val, link, name = '', secret = '') {
     if (!jwtArray[2]) {
         return false;
     }
+    // jwtArray[1]: payload, jwtArray[2]: signature
+    // --- 判断是否合法 ---
     const nsignature = lCrypto.hashHmac('sha256', jwtArray[0] + '.' + jwtArray[1], secret, 'base64');
     if (nsignature !== jwtArray[2]) {
         return false;
@@ -185,16 +218,20 @@ async function decode(ctr, val, link, name = '', secret = '') {
         if (!data) {
             return false;
         }
+        // --- 检测 token ---
         if (!data['token']) {
             return false;
         }
+        // --- 检测 exp ---
         if (!data['exp']) {
             return false;
         }
         const time = lTime.stamp();
         if (data['exp'] < time) {
+            // --- 过期 ---
             return false;
         }
+        // --- 检测 token 是否有效 ---
         if (!link || !await link.get(name + '_block_' + data['token'])) {
             return data;
         }
@@ -204,6 +241,9 @@ async function decode(ctr, val, link, name = '', secret = '') {
         return false;
     }
 }
+/**
+ * --- 仅往 redis 写禁止相关 token 的数据，一般用于异步通知时在异处的服务器来调用的 ---
+ */
 async function block(ctr, token, exp, link, name = '') {
     const time = lTime.stamp();
     if (!name) {
@@ -216,6 +256,11 @@ async function block(ctr, token, exp, link, name = '') {
     await link.set(name + '_block_' + token, '1', ttl + 1);
     return true;
 }
+/**
+ * @param ctr 模型实例
+ * @param opt name, ttl, ssl, secret, auth: false, true 则优先从头 Authorization 或 post _auth 值读取 token
+ * @param link 实例
+ */
 async function get(ctr, opt = {}, link) {
     const jwt = new Jwt();
     await jwt.init(ctr, opt, link);

package/lib/kv.d.ts

@@ -1,6 +1,12 @@
+/**
+ * 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
+ */
 import * as redis from '@litert/redis';
 import * as ctr from '../sys/ctr';
 import * as types from '../types';
+/** --- 连接信息 --- */
 export interface IConnectionInfo {
     'id': number;
     'last': number;
@@ -10,37 +16,181 @@ export interface IConnectionInfo {
     'lost': boolean;
 }
 export declare class Pool {
+    /** --- 当前 Pool 对象的 kv 连接信息 --- */
     private readonly _etc;
     constructor(ctr: ctr.Ctr, etc?: types.IConfigKv);
+    /**
+     * --- 设定一个值 ---
+     * @param key
+     * @param val
+     * @param ttl 秒，0 为不限制
+     * @param mod 设置模式: 空,nx（key不存在才建立）,xx（key存在才修改）
+     */
     set(key: string, val: object | string | number, ttl?: number, mod?: '' | 'nx' | 'xx'): Promise<boolean>;
+    /**
+     * --- 添加一个值，存在则不变 ---
+     * @param key
+     * @param val
+     * @param ttl 秒，0 为不限制
+     */
     add(key: string, val: object | string | number, ttl?: number): Promise<boolean>;
+    /**
+     * --- 替换一个存在的值 ---
+     * @param key
+     * @param val
+     * @param ttl 秒，0 为不限制
+     */
     replace(key: string, val: object | string | number, ttl?: number): Promise<boolean>;
+    /**
+     * --- 向已存在的值后追加数据 ---
+     * @param key
+     * @param val
+     */
     append(key: string, val: string): Promise<boolean>;
+    /**
+     * --- 向已存在的值之前追加数据 ---
+     * @param key
+     * @param val
+     */
     prepend(key: string, val: string): Promise<boolean>;
+    /**
+     * --- 检测 key 是否存在 ---
+     * @param keys
+     */
     exists(keys: string | string[]): Promise<number>;
+    /**
+     * --- 获取字符串 ---
+     * @param key
+     */
     get(key: string): Promise<string | null>;
+    /**
+     * --- 获取相应的剩余有效期秒数 ---
+     * @param key
+     */
     ttl(key: string): Promise<number | null>;
+    /**
+     * --- 获取相应的剩余有效期毫秒数 ---
+     * @param key
+     */
     pttl(key: string): Promise<number | null>;
+    /**
+     * --- 批量获取值 ---
+     * @param keys key 序列
+     */
     mSet(rows: Record<string, string | Buffer>): Promise<boolean>;
+    /**
+     * --- 批量获取值 ---
+     * @param keys key 序列
+     */
     mGet(keys: string[]): Promise<Record<string, string | null>>;
+    /**
+     * --- 获取 json 对象 ---
+     * @param key
+     */
     getJson(key: string): Promise<any | null>;
+    /**
+     * --- 删除已存在的值 ---
+     * @param keys
+     */
     del(keys: string | string[]): Promise<boolean>;
+    /**
+     * --- 自增 ---
+     * @param key
+     * @param num 整数或浮点正数
+     */
     incr(key: string, num?: number): Promise<number | false>;
+    /**
+     * --- 自减 ---
+     * @param key
+     * @param num 整数或浮点正数
+     */
     decr(key: string, num?: number): Promise<number | false>;
+    /**
+     * --- 仅修改过期时间不修改值 ---
+     * @param key
+     * @param ttl
+     */
     expire(key: string, ttl: number): Promise<boolean>;
+    /**
+     * --- 获取服务器上的所有 key 列表 ---
+     * @param pattern
+     */
     keys(pattern: string): Promise<string[] | false>;
+    /**
+     * --- 根据条件获取服务器上的 keys ---
+     * @param cursor
+     * @param pattern 例如 *
+     * @param count 获取的条数
+     */
     scan(cursor?: number, pattern?: string, count?: number): Promise<redis.IScanResult<string> | false>;
+    /**
+     * --- 清除当前所选数据库的所有内容 ---
+     */
     flushDb(): Promise<boolean>;
+    /**
+     * --- 发送 ping ---
+     */
     ping(): Promise<string | false>;
+    /**
+     * --- 设置哈希表值 ---
+     * @param key key 名
+     * @param field 字段名
+     * @param val 值
+     * @param mod 空,nx(key不存在才建立)
+     */
     hSet(key: string, field: string, val: object | string | number, mod?: '' | 'nx'): Promise<boolean>;
+    /**
+     * --- 批量设置哈希值 ---
+     * @param key key 名
+     * @param rows key / val 数组
+     */
     hMSet(key: string, rows: Record<string, object | string | number>): Promise<boolean>;
+    /**
+     * --- 获取哈希值 ---
+     * @param key
+     * @param field
+     */
     hGet(key: string, field: string): Promise<string | null>;
+    /**
+     * --- 获取哈希 json 对象 ---
+     * @param key
+     * @param field
+     */
     hGetJson(key: string, field: string): Promise<any | null>;
+    /**
+     * --- 批量获取哈希值 ---
+     * @param key
+     * @param fields
+     */
     hMGet(key: string, fields: string[]): Promise<Record<string, string | null>>;
+    /**
+     * --- 批量获取哈希键值对 ---
+     * @param key
+     */
     hGetAll(key: string): Promise<Record<string, string | null> | null>;
+    /**
+     * --- 删除哈希键 ---
+     * @param key
+     * @param fields 值序列
+     */
     hDel(key: string, fields: string | string[]): Promise<number>;
+    /**
+     * --- 判断哈希字段是否存在 ---
+     * @param key
+     * @param field
+     */
     hExists(key: string, field: string): Promise<boolean>;
+    /**
+     * --- 设置哈希自增自减 ---
+     * @param key key
+     * @param field 字段
+     * @param increment 正数或负数，整数或浮点
+     */
     hIncr(key: string, field: string, increment: number): Promise<number>;
+    /**
+     * --- 获取哈希所有字段 ---
+     * @param key
+     */
     hKeys(key: string): Promise<string[]>;
     lPush(key: string, values: Array<string | Buffer>): Promise<number>;
     rPush(key: string, values: Array<string | Buffer>): Promise<number>;
@@ -50,53 +200,258 @@ export declare class Pool {
     bRPop(key: string | string[], timeout: number): Promise<Record<string, string>>;
     lRange(key: string, start: number, stop: number): Promise<string[]>;
     lLen(key: string): Promise<number>;
+    /**
+     * --- 从连接池获取一个连接，会被自动设置为使用中，需要在执行命令后解除占用 ---
+     */
     private _getConnection;
 }
 export declare class Connection {
+    /** --- 本连接最后一次使用时间 --- */
     private _last;
+    /** --- kv 缓存连接对象 --- */
     private readonly _link;
+    /** --- 当前连接是否正在被独占使用 --- */
     private _using;
+    /** --- 当发生断开，则需从连接池移除连接 --- */
     private _lost;
+    /** --- 当前的连接配置信息 --- */
     private readonly _etc;
     constructor(etc: types.IConfigKv, link: redis.ICommandClient);
+    /**
+     * --- 获取连接 etc 信息 ---
+     */
     getEtc(): types.IConfigKv;
+    /**
+     * --- 获取最后一次获取连接的时间 ---
+     */
     getLast(): number;
+    /**
+     * --- 将本条连接设置为不可用 ---
+     */
     setLost(): void;
+    /**
+     * --- 是否已经丢失 ---
+     */
     isLost(): boolean;
+    /**
+     * --- 将本条连接设置占用中 ---
+     */
     setUsing(): void;
+    /**
+     * --- 获取当前状态是否正在被使用中 ---
+     */
     isUsing(): boolean;
+    /**
+     * --- 取消占用 ---
+     */
     used(): void;
+    /**
+     * --- 设定最后使用时间 ---
+     */
     refreshLast(): void;
+    /**
+     * --- 断开此连接，一般情况下不使用 ---
+     */
     end(): Promise<void>;
+    /**
+     * --- 设定一个值 ---
+     * @param key
+     * @param val
+     * @param ttl 秒，0 为不限制
+     * @param mod 设置模式: 空,nx（key不存在才建立）,xx（key存在才修改）
+     * @param etc 配置项，主要用 etc.pre
+     */
     set(key: string, val: object | string | number, ttl: number, mod: '' | 'nx' | 'xx', etc: types.IConfigKv): Promise<boolean>;
+    /**
+     * --- 添加一个值，存在则不变 ---
+     * @param key
+     * @param val
+     * @param ttl 秒，0 为不限制
+     * @param etc
+     */
     add(key: string, val: object | string | number, ttl: number, etc: types.IConfigKv): Promise<boolean>;
+    /**
+     * --- 替换一个存在的值 ---
+     * @param key
+     * @param val
+     * @param ttl 秒，0 为不限制
+     * @param etc
+     */
     replace(key: string, val: object | string | number, ttl: number, etc: types.IConfigKv): Promise<boolean>;
+    /**
+     * --- 向已存在的值后追加数据 ---
+     * @param key
+     * @param val
+     * @param etc
+     */
     append(key: string, val: string, etc: types.IConfigKv): Promise<boolean>;
+    /**
+     * --- 向已存在的值之前追加数据 ---
+     * @param key
+     * @param val
+     */
     prepend(key: string, val: string, etc: types.IConfigKv): Promise<boolean>;
+    /**
+     * --- 检测 key 是否存在 ---
+     * @param keys 单个或序列
+     * @param etc
+     */
     exists(keys: string | string[], etc: types.IConfigKv): Promise<number>;
+    /**
+     * --- 获取字符串 ---
+     * @param key
+     * @param etc
+     */
     get(key: string, etc: types.IConfigKv): Promise<string | null>;
+    /**
+     * --- 获取相应的剩余有效期秒数 ---
+     * @param key
+     * @param etc
+     */
     ttl(key: string, etc: types.IConfigKv): Promise<number | null>;
+    /**
+     * --- 获取相应的剩余有效期毫秒数 ---
+     * @param key
+     * @param etc
+     */
     pttl(key: string, etc: types.IConfigKv): Promise<number | null>;
+    /**
+     * --- 批量获取值 ---
+     * @param keys key 序列
+     * @param etc 顺序数组
+     */
     mGet(keys: string[], etc: types.IConfigKv): Promise<Record<string, string | null>>;
+    /**
+     * --- 批量设置哈希值 ---
+     * @param key key 名
+     * @param rows key / val 数组
+     * @param etc
+     */
     mSet(rows: Record<string, string | Buffer>, etc: types.IConfigKv): Promise<boolean>;
+    /**
+     * --- 获取 json 对象 ---
+     * @param key
+     * @param etc
+     */
     getJson(key: string, etc: types.IConfigKv): Promise<any | null>;
+    /**
+     * --- 删除已存在的值 ---
+     * @param keys
+     * @param etc
+     */
     del(keys: string | string[], etc: types.IConfigKv): Promise<boolean>;
+    /**
+     * --- 自增 ---
+     * @param key
+     * @param num 整数或浮点正数
+     * @param etc
+     */
     incr(key: string, num: number, etc: types.IConfigKv): Promise<number | false>;
+    /**
+     * --- 自减 ---
+     * @param key
+     * @param num 整数或浮点正数
+     * @param etc
+     */
     decr(key: string, num: number, etc: types.IConfigKv): Promise<number | false>;
+    /**
+     * --- 仅修改过期时间不修改值 ---
+     * @param key
+     * @param ttl
+     * @param etc
+     */
     expire(key: string, ttl: number, etc: types.IConfigKv): Promise<boolean>;
+    /**
+     * --- 获取服务器上的所有 key 列表 ---
+     * @param pattern
+     */
     keys(pattern: string, etc: types.IConfigKv): Promise<string[] | false>;
+    /**
+     * --- 根据条件获取服务器上的 keys ---
+     * @param cursor
+     * @param pattern 例如 *
+     * @param count 获取的条数
+     * @param etc
+     */
     scan(cursor: number, pattern: string, count: number, etc: types.IConfigKv): Promise<redis.IScanResult<string> | false>;
+    /**
+     * --- 清除当前所选数据库的所有内容 ---
+     */
     flushDb(): Promise<boolean>;
+    /**
+     * --- 发送 ping ---
+     */
     ping(): Promise<false | string>;
+    /**
+     * --- 设置哈希表值 ---
+     * @param key key 名
+     * @param field 字段名
+     * @param val 值
+     * @param mod 空,nx(key不存在才建立)
+     * @param etc
+     */
     hSet(key: string, field: string, val: object | string | number, mod: '' | 'nx', etc: types.IConfigKv): Promise<boolean>;
+    /**
+     * --- 批量设置哈希值 ---
+     * @param key key 名
+     * @param rows key / val 数组
+     * @param etc
+     */
     hMSet(key: string, rows: Record<string, object | string | number>, etc: types.IConfigKv): Promise<boolean>;
+    /**
+     * --- 获取哈希值 ---
+     * @param key
+     * @param field
+     * @param etc
+     */
     hGet(key: string, field: string, etc: types.IConfigKv): Promise<string | null>;
+    /**
+     * --- 获取哈希 json 对象 ---
+     * @param key
+     * @param field
+     * @param etc
+     */
     hGetJson(key: string, field: string, etc: types.IConfigKv): Promise<any | null>;
+    /**
+     * --- 批量获取哈希值 ---
+     * @param key
+     * @param fields
+     * @param etc
+     */
     hMGet(key: string, fields: string[], etc: types.IConfigKv): Promise<Record<string, string | null>>;
+    /**
+     * --- 批量获取哈希键值对 ---
+     * @param key
+     * @param etc
+     */
     hGetAll(key: string, etc: types.IConfigKv): Promise<Record<string, string | null> | null>;
+    /**
+     * --- 删除哈希键 ---
+     * @param key
+     * @param fields 值序列
+     * @param etc
+     */
     hDel(key: string, fields: string | string[], etc: types.IConfigKv): Promise<number>;
+    /**
+     * --- 判断哈希字段是否存在 ---
+     * @param key
+     * @param field
+     * @param etc
+     */
     hExists(key: string, field: string, etc: types.IConfigKv): Promise<boolean>;
+    /**
+     * --- 设置哈希自增自减 ---
+     * @param key key
+     * @param field 字段
+     * @param increment 正数或负数，整数或浮点
+     * @param etc
+     */
     hIncr(key: string, field: string, increment: number, etc: types.IConfigKv): Promise<number>;
+    /**
+     * --- 获取哈希所有字段 ---
+     * @param key
+     * @param etc
+     */
     hKeys(key: string, etc: types.IConfigKv): Promise<string[]>;
     lPush(key: string, values: Array<string | Buffer>, etc: types.IConfigKv): Promise<number>;
     rPush(key: string, values: Array<string | Buffer>, etc: types.IConfigKv): Promise<number>;
@@ -107,5 +462,12 @@ export declare class Connection {
     lRange(key: string, start: number, stop: number, etc: types.IConfigKv): Promise<string[]>;
     lLen(key: string, etc: types.IConfigKv): Promise<number>;
 }
+/**
+ * --- 获取 Kv Pool 对象 ---
+ * @param etc 配置信息可留空
+ */
 export declare function get(ctr: ctr.Ctr, etc?: types.IConfigKv): Pool;
+/**
+ * --- 获取当前连接池中所有连接的信息 ---
+ */
 export declare function getConnectionList(): IConnectionInfo[];