@maiyunnet/kebab 2.0.6 → 2.0.8

package/lib/scan.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2022-09-24 15:23:25
+ * Last: 2022-09-24 15:23:25, 2022-9-26 12:37:01, 2022-12-29 00:11:16
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -37,6 +42,20 @@ exports.Scan = void 0;
 exports.get = get;
 exports.scanned = scanned;
 exports.setData = setData;
+/*
+CREATE TABLE IF NOT EXISTS `scan` (
+    `id` bigint NOT NULL AUTO_INCREMENT,
+    `token` char (32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
+    `data` text NOT NULL,
+    `time_update` bigint NOT NULL,
+    `time_add` bigint NOT NULL,
+    `time_exp` bigint NOT NULL,
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `token` (`token`) USING btree
+    KEY `time_update` (`time_update`),
+    KEY `time_exp` (`time_exp`)
+) ENGINE = InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci
+*/
 const lCore = __importStar(require("../lib/core"));
 const lDb = __importStar(require("../lib/db"));
 const lKv = __importStar(require("../lib/kv"));
@@ -46,9 +65,12 @@ const lText = __importStar(require("../lib/text"));
 class Scan {
     constructor(link, token, opt = {}) {
         this._sql = null;
+        /** --- 表名或者 kv 里 key 的前缀 --- */
         this._name = 'scan';
         this._token = null;
+        /** --- 有效期，默认 5 分钟 --- */
         this._ttl = 60 * 5;
+        /** --- 二维码剩余有效时间 --- */
         this._timeLeft = null;
         if (opt.ttl !== undefined) {
             this._ttl = opt.ttl;
@@ -64,26 +86,35 @@ class Scan {
             this._token = token;
         }
     }
+    /**
+     * --- 生成二维码处的轮询，检查是否被扫码、被录入数据 ---
+     * @returns -3 系统错误 -2 token 不存在或已过期 -1 无操作, 0 已扫码, 其他返回为存的数据并结束轮询
+     */
     async poll() {
         if (!this._token) {
             return -3;
         }
         const time = lTime.stamp();
         if (this._link instanceof lDb.Pool) {
+            // --- Db ---
             this._sql.select('*', this._name).where([
                 { 'token': this._token },
                 ['time_exp', '>', time]
             ]);
             const r = await this._link.query(this._sql.getSql(), this._sql.getData());
             if (r.error) {
+                // --- 出错 ---
                 return -3;
             }
             const data = r.rows?.[0];
             if (!data) {
+                // --- 不存在或过期 ---
                 return -2;
             }
+            // --- 存在，判断是否被扫码，以及是否被写入数据 ---
             this._timeLeft = data['time_exp'] - time;
             if (data['data'] !== '') {
+                // --- 已经写入数据了，删除数据库条目并返回写入的数据内容 ---
                 this._sql.delete(this._name).where({
                     'id': data['id']
                 });
@@ -91,15 +122,19 @@ class Scan {
                 return r === false ? -3 : r;
             }
             else if (data['time_update'] > 0) {
+                // --- 已被扫描 ---
                 return 0;
             }
             else {
+                // --- 未扫描 ---
                 return -1;
             }
         }
         else {
+            // --- Kv ---
             const data = await this._link.getJson('scan-' + this._name + '_' + this._token);
             if (data === null) {
+                // --- 不存在或过期 ---
                 return -2;
             }
             const ttl = await this._link.ttl('scan-' + this._name + '_' + this._token);
@@ -108,17 +143,23 @@ class Scan {
             }
             this._timeLeft = ttl;
             if (data['data'] !== null) {
+                // --- 已经写入数据了，删除数据库条目并返回写入的数据内容 ---
                 await this._link.del('scan-' + this._name + '_' + this._token);
                 return data;
             }
             else if (data['time_update'] > 0) {
+                // --- 已被扫描 ---
                 return 0;
             }
             else {
+                // --- 未扫描 ---
                 return -1;
             }
         }
     }
+    /**
+     * --- 创建 token，直接应用到本类 ---
+     */
     async createToken() {
         await this._gc();
         const time = lTime.stamp();
@@ -129,6 +170,7 @@ class Scan {
             }
             this._token = lCore.random(32, lCore.RANDOM_LUN);
             if (this._link instanceof lDb.Pool) {
+                // --- Db ---
                 this._sql.insert(this._name).values({
                     'token': this._token,
                     'data': '',
@@ -147,6 +189,7 @@ class Scan {
                 }
             }
             else {
+                // --- Kv ---
                 if (await this._link.set('scan-' + this._name + '_' + this._token, {
                     'time_update': 0,
                     'data': null
@@ -158,18 +201,34 @@ class Scan {
         }
         return true;
     }
+    /**
+     * --- 获取当前 token ---
+     */
     getToken() {
         return this._token;
     }
+    /**
+     * --- 设置有效期，设置后的新 token 被创建有效 ---
+     * @param ttl
+     */
     setTTL(ttl) {
         this._ttl = ttl;
     }
+    /**
+     * --- 获取设置的有效期 ---
+     */
     getTTL() {
         return this._ttl;
     }
+    /**
+     * --- 获取当前 token 可扫剩余有效期 ---
+     */
     getTimeLeft() {
         return this._timeLeft;
     }
+    /**
+     * --- 根据情况清空 Db 状态下的 scan 表垃圾数据 ---
+     */
     async _gc() {
         if (this._link instanceof lKv.Pool) {
             return;
@@ -184,6 +243,12 @@ class Scan {
     }
 }
 exports.Scan = Scan;
+/**
+ * -- 创建 Scan 对象 ---
+ * @param link
+ * @param token Token
+ * @param opt
+ */
 async function get(link, token, opt = {}) {
     const scan = new Scan(link, token, opt);
     if (!token) {
@@ -191,10 +256,17 @@ async function get(link, token, opt = {}) {
     }
     return scan;
 }
+/**
+ * --- 对 token 执行访问操作，通常用户扫码后展示的网页所调用，代表已扫码 ---
+ * @param link
+ * @patam token 必填
+ * @param opt
+ */
 async function scanned(link, token, opt = {}) {
     const time = lTime.stamp();
     const name = opt.name ?? 'scan';
     if (link instanceof lDb.Pool) {
+        // --- Db ---
         const sql = lSql.get(opt.sqlPre);
         sql.update(name, {
             'time_update': time
@@ -214,11 +286,13 @@ async function scanned(link, token, opt = {}) {
         }
     }
     else {
+        // --- Kv ---
         const ldata = await link.getJson('scan-' + name + '_' + token);
         if (ldata === null) {
             return false;
         }
         if (ldata['time_update'] > 0) {
+            // --- 已经被扫码过了 ---
             return false;
         }
         ldata['time_update'] = time;
@@ -230,6 +304,13 @@ async function scanned(link, token, opt = {}) {
     }
     return false;
 }
+/**
+ * --- 将数据写入 token，通常在客户的逻辑下去写，服务器会 poll 到 ---
+ * @param link
+ * @param token
+ * @param data
+ * @param opt
+ */
 async function setData(link, token, data, opt = {}) {
     if (typeof data === 'number' && Number.isInteger(data)) {
         if (data >= -3 && data <= 1) {
@@ -239,6 +320,7 @@ async function setData(link, token, data, opt = {}) {
     const time = lTime.stamp();
     const name = opt.name ?? 'scan';
     if (link instanceof lDb.Pool) {
+        // --- Db ---
         const sql = lSql.get(opt.sqlPre);
         sql.update(name, {
             'data': lText.stringifyJson(data)
@@ -258,11 +340,13 @@ async function setData(link, token, data, opt = {}) {
         }
     }
     else {
+        // --- Kv ---
         const ldata = await link.getJson('scan-' + name + '_' + token);
         if (ldata === null) {
             return false;
         }
         if (ldata['time_update'] === 0) {
+            // --- 还未被扫码，无法操作 ---
             return false;
         }
         const ttl = await link.ttl('scan-' + name + '_' + token);

package/lib/session.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-6-5 22:01:40
+ * Last: 2020-3-30 00:11:15, 2022-12-29 00:10:28, 2023-5-24 18:59:27
+ */
 import * as db from '../lib/db';
 import * as kv from '../lib/kv';
 import * as ctr from '../sys/ctr';
@@ -8,15 +13,41 @@ export interface IOptions {
     'sqlPre'?: string;
 }
 export declare class Session {
+    /** --- 数据库操作对象 --- */
     private _link;
+    /** --- Sql 对象 ---  */
     private _sql;
+    /** --- session 在前端或 Kv 中储存的名前缀 --- */
     private _name;
+    /** --- 当前 Session 的 token --- */
     private _token;
+    /** --- Session 有效期 --- */
     private _ttl;
+    /** --- ctr 对象 --- */
     private _ctr;
+    /**
+     * --- 初始化函数，相当于 construct ---
+     * @param ctr 模型实例
+     * @param link Kv 或 Db 实例
+     * @param auth 设为 true 则优先从头 Authorization 或 post _auth 值读取 token
+     * @param opt 选项
+     */
     init(ctr: ctr.Ctr, link: db.Pool | kv.Pool, auth?: boolean, opt?: IOptions): Promise<boolean>;
+    /**
+     * --- 获取当前的 token 值 ---
+     */
     getToken(): string;
+    /**
+     * --- 获取当前的 cookie 的 name 值 ---
+     */
     getName(): string;
+    /**
+     * --- 页面整体结束时，要写入到 Kv 或 数据库 ---
+     */
     update(): Promise<void>;
+    /**
+     * --- 根据情况清空 Db 状态下的 session 表垃圾数据 ---
+     * --- 仅能在 Db 模式执行，非 Db 模式则等于没运行 ---
+     */
     private _gc;
 }

package/lib/session.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-6-5 22:01:40
+ * Last: 2020-3-30 00:11:15, 2022-12-29 00:10:28, 2023-5-24 18:59:27
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -34,6 +39,20 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Session = void 0;
+/*
+ * --- Mysql ---
+CREATE TABLE `session` (
+  `id` bigint NOT NULL AUTO_INCREMENT,
+  `token` char(16) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
+  `data` text NOT NULL,
+  `time_update` bigint NOT NULL,
+  `time_add` bigint NOT NULL,
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `token` (`token`),
+  KEY `time_update` (`time_update`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci
+*/
+// --- 库和定义 ---
 const core = __importStar(require("../lib/core"));
 const time = __importStar(require("../lib/time"));
 const db = __importStar(require("../lib/db"));
@@ -42,9 +61,18 @@ const sql = __importStar(require("../lib/sql"));
 const text = __importStar(require("../lib/text"));
 class Session {
     constructor() {
+        /** --- 当前 Session 的 token --- */
         this._token = '';
+        /** --- Session 有效期 --- */
         this._ttl = 0;
     }
+    /**
+     * --- 初始化函数，相当于 construct ---
+     * @param ctr 模型实例
+     * @param link Kv 或 Db 实例
+     * @param auth 设为 true 则优先从头 Authorization 或 post _auth 值读取 token
+     * @param opt 选项
+     */
     async init(ctr, link, auth = false, opt = {}) {
         const config = ctr.getPrototype('_config');
         const ssl = opt.ssl ?? config.session.ssl;
@@ -66,12 +94,16 @@ class Session {
         this._link = link;
         if (link instanceof db.Pool) {
             this._sql = sql.get(pre ? pre : ctr);
-            await this._gc();
+            await this._gc(); // --- 执行 gc ---
         }
+        // --- 初始化 Session 数组 ---
         let session = {};
         let needInsert = false;
+        // --- 有 token 则查看 token 的信息是否存在
         if (this._token !== '') {
+            // --- 如果启用了内存加速则在内存找 ---
             if (this._link instanceof kv.Pool) {
+                // --- Kv ---
                 let data;
                 if ((data = await this._link.getJson(this._name + '_' + this._token)) === null) {
                     needInsert = true;
@@ -81,6 +113,7 @@ class Session {
                 }
             }
             else {
+                // --- 数据库 ---
                 this._sql.select('*', 'session').where([
                     ['time_update', '>=', tim - this._ttl],
                     { 'token': this._token }
@@ -96,8 +129,13 @@ class Session {
             ctr.setPrototype('_session', session);
         }
         else {
+            // --- 全新的机子 ---
             needInsert = true;
         }
+        // --- 本来就该添加个新 Session ---
+        // --- 内存和数据库里没找到的也该添加个新 Session ---
+        // --- 数据库的 Session 已经过期加新 Session ---
+        // --- 如果不存在不允许加新则返回错误 ---
         if (needInsert) {
             if (this._link instanceof kv.Pool) {
                 let count = 0;
@@ -141,12 +179,21 @@ class Session {
         });
         return true;
     }
+    /**
+     * --- 获取当前的 token 值 ---
+     */
     getToken() {
         return this._token;
     }
+    /**
+     * --- 获取当前的 cookie 的 name 值 ---
+     */
     getName() {
         return this._name;
     }
+    /**
+     * --- 页面整体结束时，要写入到 Kv 或 数据库 ---
+     */
     async update() {
         if (this._link instanceof kv.Pool) {
             await this._link.set(this._name + '_' + this._token, this._ctr.getPrototype('_session'), this._ttl);
@@ -161,6 +208,10 @@ class Session {
             await this._link.execute(this._sql.getSql(), this._sql.getData());
         }
     }
+    /**
+     * --- 根据情况清空 Db 状态下的 session 表垃圾数据 ---
+     * --- 仅能在 Db 模式执行，非 Db 模式则等于没运行 ---
+     */
     async _gc() {
         if (!(this._link instanceof db.Pool)) {
             return;

package/lib/sql.d.ts

@@ -1,55 +1,231 @@
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-5-27 20:18:50
+ * Last: 2020-3-29 19:37:25, 2022-07-24 22:38:11, 2023-5-24 18:49:18, 2023-6-13 22:20:21, 2023-12-11 13:58:54, 2023-12-14 13:14:40, 2023-12-21 00:04:40, 2024-4-11 19:29:29, 2024-9-2 17:15:28
+ */
 import * as ctr from '../sys/ctr';
 import * as types from '../types';
 export declare class Sql {
+    /** --- 前置 --- */
     private readonly _pre;
+    /** --- 预拼装 Sql 数组 --- */
     private _sql;
+    /** --- 所有 data 数据 --- */
     private _data;
     constructor(pre?: string, opt?: {
         'data'?: types.DbValue[];
         'sql'?: string[];
     });
+    /**
+     * --- 插入数据前导 ---
+     * @param table 表名
+     */
     insert(table: string): this;
+    /**
+     * --- 替换已经存在的唯一索引数据，不存在则插入 ---
+     * @param table 表名
+     */
     replace(table: string): this;
+    /**
+     * --- 实际插入数据的数据 ---
+     * @param cs [] 数据列或字段列
+     * @param vs [] | [][] 数据
+     */
     values(cs: string[] | Record<string, types.DbValue>, vs?: types.DbValue[] | types.DbValue[][]): this;
+    /**
+     * --- 不存在则插入，衔接在 insert 之后 ---
+     * @param table 表名
+     * @param insert {'xx': 'xx', 'xx': 'xx'}
+     * @param where [{'xx': 'xx', 'xx': 'xx'}], {'xx': 'xx'}
+     */
     notExists(table: string, insert: Record<string, types.DbValue>, where: string | types.Json): this;
+    /**
+     * --- 当不能 insert 时，update（仅能配合 insert 方法用） ---
+     * @param s 更新数据
+     */
     duplicate(s: types.Json): this;
+    /**
+     * --- '*', 'xx' ---
+     * @param c 字段字符串或字段数组
+     * @param f 表，允许多张表
+     */
     select(c: string | Array<string | Array<string | string[]>>, f: string | string[]): this;
+    /**
+     * --- UPDATE SQL 方法 ---
+     * @param f 表名
+     * @param s 设定 update 的值
+     */
     update(f: string, s: types.Json): this;
     private _updateSub;
+    /**
+     * --- 'xx' ---
+     * @param f 表名
+     */
     delete(f: string): this;
+    /**
+     * --- 联查另一个 sql 对象 ---
+     * @param sql sql 对象
+     * @param type 类型
+     */
     union(lsql: Sql, type?: string): this;
+    /**
+     * --- 所有联查另一个 sql 对象 ---
+     * @param sql sql 对象
+     */
     unionAll(lsql: Sql): this;
+    /**
+     * --- join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param type 类型
+     * @param suf 表后缀
+     * @param pre 表前缀，仅在 join 非默认表前缀时填写
+     */
     join(f: string, s?: types.Json, type?: string, suf?: string, pre?: string): this;
+    /**
+     * --- left join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param suf 表后缀
+     * @param pre 表前缀，仅在 join 非默认表前缀时填写
+     */
     leftJoin(f: string, s?: types.Json, suf?: string, pre?: string): this;
+    /**
+     * --- right join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param suf 表后缀
+     * @param pre 表前缀，仅在 join 非默认表前缀时填写
+     */
     rightJoin(f: string, s?: types.Json, suf?: string, pre?: string): this;
+    /**
+     * --- inner join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param suf 表后缀
+     * @param pre 表前缀，仅在 join 非默认表前缀时填写
+     */
     innerJoin(f: string, s?: types.Json, suf?: string, pre?: string): this;
+    /**
+     * --- full join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param suf 表后缀
+     * @param pre 表前缀，仅在 join 非默认表前缀时填写
+     */
     fullJoin(f: string, s?: types.Json, suf?: string, pre?: string): this;
+    /**
+     * --- cross join 方法 ---
+     * @param f 表名
+     * @param s ON 信息
+     * @param suf 表后缀
+     * @param pre 表前缀，仅在 join 非默认表前缀时填写
+     */
     crossJoin(f: string, s?: types.Json, suf?: string, pre?: string): this;
+    /**
+     * --- having 后置筛选器，用法类似 where ---
+     */
     having(s?: string | types.Json): this;
+    /** --- where 的 data 的开始处和结束处 --- */
     private _whereDataPosition;
+    /**
+     * --- 筛选器 ---
+     * --- 1. 'city': 'bj', 'type': '2' ---
+     * --- 2. ['type', '>', '1'] ---
+     * --- 3. ['type', 'in', ['1', '2']] ---
+     * --- 4. 'type': ['1', '2'] ---
+     * --- 5. '$or': [{'city': 'bj'}, {'city': 'sh'}, [['age', '>', '10']]], 'type': '2' ---
+     * --- 6. 'city_in': column('city_out') ---
+     * --- 7. ['JSON_CONTAINS(`uid`, ?)', ['hello']] ---
+     * @param s 筛选数据
+     */
     where(s: string | types.Json): this;
     private _whereSub;
+    /**
+     * --- ORDER BY ---
+     * @param c 字段字符串或数组
+     * @param d 排序规则
+     */
     by(c: string | Array<string | string[]>, d?: 'DESC' | 'ASC'): this;
+    /**
+     * --- GROUP BY ---
+     * @param c 字段字符串或数组
+     */
     group(c: string | string[]): this;
+    /**
+     * --- LIMIT ---
+     * @param a 起始
+     * @param b 长度
+     */
     limit(a: number, b?: number): this;
+    /**
+     * --- 追加消极锁，通常不建议使用 ---
+     */
     lock(): this;
+    /**
+     * --- 创建一个本对象的一个新的 sql 对象拷贝 ---
+     * @param f 可为空，可设置新对象的 table 名变化
+     */
     copy(f?: string | string[], opt?: {
         'where'?: string | types.Json;
     }): Sql;
+    /**
+     * --- 获取 sql 语句 ---
+     */
     getSql(): string;
+    /**
+     * --- 获取全部 data ---
+     */
     getData(): types.DbValue[];
+    /**
+     * --- 获取定义的 pre ---
+     */
     getPre(): string;
+    /**
+     * --- 获取带 data 的 sql 语句 ---
+     * @param sql
+     * @param data
+     */
     format(sql?: string, data?: types.DbValue[]): string;
+    /**
+     * --- 在 sql 最后追加字符串 ---
+     * @param sql
+     */
     append(sql: string): this;
+    /**
+     * --- 对字段进行包裹 ---
+     * @param str
+     * @param pre 表前缀，仅请在 field 表名时倒入前缀
+     * @param suf 表后缀，仅请在 field 表名时倒入后缀，前面加 # 代表要强制 AS
+     */
     field(str: string | number | Array<string | string[]>, pre?: string, suf?: string): string;
+    /**
+     * --- 判断传入值是否是 field，还是别的对象 ---
+     * @param str
+     */
     private _isField;
 }
+/**
+ * --- 创建 sql 对象 ---
+ * @param ctrPre ctr 对象或 pre 表前缀
+ * @param opt 参数
+ */
 export declare function get(ctrPre?: ctr.Ctr | string, opt?: {
     'data'?: types.DbValue[];
     'sql'?: string[];
 }): Sql;
+/**
+ * --- 返回代入后的完整 SQL 字符串 ---
+ * @param sql SQL 字符串
+ * @param data DATA 数据
+ */
 export declare function format(sql: string, data: types.DbValue[]): string;
+/**
+ * --- 将数组兑换为组合的对象（Array/Object mix） ---
+ * @param arr 要转换的数组
+ */
 export declare function aoMix(arr: types.Json): Record<string, string | number | types.Json>;
+/** --- 创建字段对象 --- */
 export declare function column(field: string): {
     'type': 'column';
     'token': string;