@maiyunnet/kebab 2.0.6 → 2.0.8

package/lib/db.d.ts

@@ -1,6 +1,12 @@
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-4-15 13:40
+ * Last: 2020-4-13 15:34:45, 2022-09-12 13:10:34, 2023-5-24 18:29:38, 2024-7-11 14:37:54, 2024-8-25 00:32:53, 2024-9-22 17:30:47
+ */
 import * as mysql2 from 'mysql2/promise';
 import * as ctr from '../sys/ctr';
 import * as types from '../types';
+/** --- query 返回的数据 --- */
 export interface IData {
     'rows': any[] | null;
     'fields': mysql2.FieldPacket[];
@@ -10,6 +16,7 @@ export interface IData {
         [key: string]: any;
     } | null;
 }
+/** --- exec 返回对象 --- */
 export interface IPacket {
     'packet': mysql2.ResultSetHeader | null;
     'fields': mysql2.FieldPacket[];
@@ -19,6 +26,7 @@ export interface IPacket {
         [key: string]: any;
     } | null;
 }
+/** --- 连接信息 --- */
 export interface IConnectionInfo {
     'id': number;
     'last': number;
@@ -30,18 +38,43 @@ export interface IConnectionInfo {
     'using': boolean;
     'transaction': boolean;
 }
+/** --- 数据库连接池对象 --- */
 export declare class Pool {
+    /** --- SQL 执行次数 --- */
     private _queries;
+    /** --- 当前 Pool 对象的数据库连接信息 --- */
     private readonly _etc;
     constructor(etc: types.IConfigDb);
+    /**
+     * --- 执行一条 SQL，无视顺序和相同连接，随用随取 ---
+     * @param sql 执行的 SQL 字符串
+     * @param values 要替换的 data 数据
+     */
     query(sql: string, values?: types.DbValue[]): Promise<IData>;
+    /**
+     * --- 执行一条 SQL 并获得影响行数对象 packet，连接失败抛出错误 ---
+     * @param sql 执行的 SQL 字符串
+     * @param values 要替换的 data 数据
+     */
     execute(sql: string, values?: types.DbValue[]): Promise<IPacket>;
+    /**
+     * --- 开启事务，返回事务对象并锁定连接，别人任何人不可用，有 ctr 的话必传 this，独立执行时可传 null ---
+     */
     beginTransaction(ctr: ctr.Ctr | null): Promise<Transaction | null>;
+    /**
+     * --- 获取一个连接，自动变为 using 状态，；连接失败会返回 null ---
+     */
     private _getConnection;
+    /**
+     * --- 获取 SQL 执行次数 ---
+     */
     getQueries(): number;
 }
+/** --- 事务连接对象，commit 和 rollback 后将无法使用 --- */
 export declare class Transaction {
+    /** --- SQL 执行次数 --- */
     private _queries;
+    /** --- 连接对象 --- */
     private _conn;
     private readonly _ctr;
     private readonly _timer;
@@ -49,40 +82,111 @@ export declare class Transaction {
         'warning'?: number;
         'danger'?: number;
     });
+    /**
+     * --- 在事务连接中执行一条 SQL ---
+     * @param sql 执行的 SQL 字符串
+     * @param values 要替换的 data 数据
+     */
     query(sql: string, values?: types.DbValue[]): Promise<IData>;
+    /**
+     * --- 执行一条 SQL 并获得影响行数对象 packet，连接失败抛出错误 ---
+     * @param sql 执行的 SQL 字符串
+     * @param values 要替换的 data 数据
+     */
     execute(sql: string, values?: types.DbValue[]): Promise<IPacket>;
     commit(): Promise<boolean>;
     rollback(): Promise<boolean>;
 }
+/** --- 数据库连接对象 --- */
 export declare class Connection {
+    /** --- 本连接最后一次使用时间 --- */
     private _last;
+    /** --- 最后两次执行的 sql 完整串 --- */
     private readonly _lastSql;
+    /** --- 数据库连接对象 --- */
     private readonly _link;
+    /** --- 当前连接是否正在被独占使用 --- */
     private _using;
+    /** --- 当发生断开，则需从连接池移除连接 --- */
     private _lost;
+    /** --- 当前正在处理事务 --- */
     private _transaction;
+    /** --- 当前的连接配置信息 --- */
     private readonly _etc;
     constructor(etc: types.IConfigDb, link: mysql2.Connection);
+    /**
+     * --- 获取连接 etc 信息 ---
+     */
     getEtc(): types.IConfigDb;
+    /**
+     * --- 获取最后一次获取连接的时间 ---
+     */
     getLast(): number;
+    /**
+     * --- 获取最后两次执行的 sql 字符串 ---
+     */
     getLastSql(): Array<{
         'sql': string;
         'values'?: types.DbValue[];
     }>;
+    /**
+     * --- 将本条连接设置为不可用 ---
+     */
     setLost(): void;
+    /**
+     * --- 是否已经丢失 ---
+     */
     isLost(): boolean;
+    /**
+     * --- 是否是开启事务状态 ---
+     */
     isTransaction(): boolean;
+    /**
+     * --- 获取当前状态是否正在被使用中 ---
+     */
     isUsing(): boolean;
+    /**
+     * --- 判断是否可用（丢失的也算不可用），返回 true 代表获取成功并自动刷新最后时间 ---
+     */
     using(): boolean;
+    /**
+     * --- 取消占用 ---
+     */
     used(): void;
+    /**
+     * --- 设定最后使用时间 ---
+     */
     refreshLast(): void;
+    /**
+     * --- 通过执行一条语句判断当前连接是否可用 ---
+     */
     isAvailable(): Promise<boolean>;
+    /**
+     * --- 执行一条 SQL 并获得返回数据 ---
+     * @param sql 执行的 SQL 字符串
+     * @param values 要替换的 data 数据
+     */
     query(sql: string, values?: types.DbValue[]): Promise<IData>;
+    /**
+     * --- 执行一条 SQL 并获得影响行数对象 packet ---
+     * @param sql 执行的 SQL 字符串
+     * @param values 要替换的 data 数据
+     */
     execute(sql: string, values?: types.DbValue[]): Promise<IPacket>;
+    /**
+     * --- 关闭连接，一般情况下不使用 ---
+     */
     end(): Promise<boolean>;
     beginTransaction(): Promise<boolean>;
     commit(): Promise<boolean>;
     rollback(): Promise<boolean>;
 }
+/**
+ * --- 获取 Db Pool 对象 ---
+ * @param etc 配置信息可留空
+ */
 export declare function get(ctrEtc: ctr.Ctr | types.IConfigDb): Pool;
+/**
+ * --- 获取当前连接池中所有连接的信息 ---
+ */
 export declare function getConnectionList(): IConnectionInfo[];

package/lib/db.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-4-15 13:40
+ * Last: 2020-4-13 15:34:45, 2022-09-12 13:10:34, 2023-5-24 18:29:38, 2024-7-11 14:37:54, 2024-8-25 00:32:53, 2024-9-22 17:30:47
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -36,25 +41,35 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Connection = exports.Transaction = exports.Pool = void 0;
 exports.get = get;
 exports.getConnectionList = getConnectionList;
+// --- Pool 是使用时必须要一个用户创建一份的，Connection 是池子里获取的 ---
+// --- 第三方 ---
 const mysql2 = __importStar(require("mysql2/promise"));
+// --- 库和定义 ---
 const time = __importStar(require("../lib/time"));
 const lSql = __importStar(require("../lib/sql"));
 const core = __importStar(require("../lib/core"));
 const text = __importStar(require("../lib/text"));
 const ctr = __importStar(require("../sys/ctr"));
+/** --- 连接列表池 --- */
 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()) {
+            // --- 连接正在被使用，看看是否空闲了超过 1 分钟，超过则不是正常状态 ---
             if (connection.getLast() <= now - 60) {
+                // --- 1 分钟之前开始的 ---
                 const ls = connection.getLastSql();
                 const sql = ls[1] ?? ls[0];
                 console.log(`[child] [db] [error] There is a transactional connection[${i}] that is not closed, last sql: ${sql?.sql ?? 'undefined'}.`);
@@ -77,9 +92,12 @@ async function checkConnection() {
             }
             continue;
         }
+        // --- 目前未被使用中的连接 ---
         if (connection.getLast() > now - 180) {
+            // --- 3 分钟内使用过，不管 ---
             continue;
         }
+        // --- 超 3 分钟未被使用，则关闭 ---
         await connection.end();
         connections.splice(i, 1);
         --i;
@@ -91,13 +109,21 @@ async function checkConnection() {
 setTimeout(function () {
     checkConnection().catch(e => { console.log('[DB]', e); });
 }, 30000);
+/** --- 数据库连接池对象 --- */
 class Pool {
     constructor(etc) {
+        /** --- SQL 执行次数 --- */
         this._queries = 0;
         this._etc = etc;
     }
+    /**
+     * --- 执行一条 SQL，无视顺序和相同连接，随用随取 ---
+     * @param sql 执行的 SQL 字符串
+     * @param values 要替换的 data 数据
+     */
     async query(sql, values) {
         ++this._queries;
+        // --- 获取并自动 using  ---
         const conn = await this._getConnection();
         if (!conn) {
             return {
@@ -109,8 +135,14 @@ class Pool {
                 }
             };
         }
+        // --- 执行一次后自动解除 using ---
         return conn.query(sql, values);
     }
+    /**
+     * --- 执行一条 SQL 并获得影响行数对象 packet，连接失败抛出错误 ---
+     * @param sql 执行的 SQL 字符串
+     * @param values 要替换的 data 数据
+     */
     async execute(sql, values) {
         ++this._queries;
         const conn = await this._getConnection();
@@ -126,6 +158,9 @@ class Pool {
         }
         return conn.execute(sql, values);
     }
+    /**
+     * --- 开启事务，返回事务对象并锁定连接，别人任何人不可用，有 ctr 的话必传 this，独立执行时可传 null ---
+     */
     async beginTransaction(ctr) {
         const conn = await this._getConnection();
         if (!conn) {
@@ -136,6 +171,9 @@ class Pool {
         }
         return new Transaction(ctr, conn);
     }
+    /**
+     * --- 获取一个连接，自动变为 using 状态，；连接失败会返回 null ---
+     */
     async _getConnection() {
         let conn = null;
         for (const connection of connections) {
@@ -144,15 +182,19 @@ class Pool {
                 (etc.port !== this._etc.port) ||
                 (etc.name !== this._etc.name) ||
                 (etc.user !== this._etc.user)) {
+                // --- 配置项连接项不匹配 ---
                 continue;
             }
             if (!connection.using()) {
+                // --- 正在被使用，或者已经 lost ---
                 continue;
             }
+            // --- 匹配且可用 ---
             conn = connection;
             break;
         }
         if (!conn) {
+            // --- 没有找到合适的连接，创建一个 ---
             try {
                 const link = await mysql2.createConnection({
                     'host': this._etc.host,
@@ -190,23 +232,31 @@ class Pool {
         }
         return conn;
     }
+    /**
+     * --- 获取 SQL 执行次数 ---
+     */
     getQueries() {
         return this._queries;
     }
 }
 exports.Pool = Pool;
+/** --- 事务连接对象，commit 和 rollback 后将无法使用 --- */
 class Transaction {
     constructor(ctr, conn, opts = {}) {
+        /** --- SQL 执行次数 --- */
         this._queries = 0;
+        // --- 事务时长监听 timer ---
         this._timer = {
             'warning': undefined,
             'danger': undefined
         };
+        // --- 进来的连接对象直接是事务独占模式 ---
         this._ctr = ctr;
         if (ctr) {
             ++ctr.getPrototype('_waitInfo').transaction;
         }
         this._conn = conn;
+        // --- 事务时长监听 ---
         const warning = opts.warning ?? 1_500;
         this._timer.warning = setTimeout(() => {
             this._timer.warning = undefined;
@@ -218,8 +268,14 @@ class Transaction {
             console.log('[DANGER][DB][Transaction] time too long, ms:', danger, this._ctr?.getPrototype('_config').const.path ?? 'no ctr');
         }, danger);
     }
+    /**
+     * --- 在事务连接中执行一条 SQL ---
+     * @param sql 执行的 SQL 字符串
+     * @param values 要替换的 data 数据
+     */
     async query(sql, values) {
         if (!this._conn) {
+            // --- 当前连接已不可用 ---
             console.log('[ERROR][DB][Transaction.query] has been closed.', this._ctr?.getPrototype('_config').const.path ?? 'no ctr', sql);
             await core.log({
                 'path': '',
@@ -242,8 +298,14 @@ class Transaction {
         ++this._queries;
         return this._conn.query(sql, values);
     }
+    /**
+     * --- 执行一条 SQL 并获得影响行数对象 packet，连接失败抛出错误 ---
+     * @param sql 执行的 SQL 字符串
+     * @param values 要替换的 data 数据
+     */
     async execute(sql, values) {
         if (!this._conn) {
+            // --- 当前连接已不可用 ---
             console.log('[ERROR][DB][Transaction.execute] has been closed.', this._ctr?.getPrototype('_config').const.path ?? 'no ctr', sql);
             await core.log({
                 'path': '',
@@ -268,6 +330,7 @@ class Transaction {
     }
     async commit() {
         if (!this._conn) {
+            // --- 当前连接已不可用 ---
             console.log('[ERROR][DB][Transaction.commit] has been closed.', this._ctr?.getPrototype('_config').const.path ?? 'no ctr');
             await core.log({
                 'path': '',
@@ -296,6 +359,7 @@ class Transaction {
     }
     async rollback() {
         if (!this._conn) {
+            // --- 当前连接已不可用 ---
             console.log('[ERROR][DB][Transaction.rollback] has been closed.', this._ctr?.getPrototype('_config').const.path ?? 'no ctr');
             await core.log({
                 'path': '',
@@ -324,38 +388,68 @@ class Transaction {
     }
 }
 exports.Transaction = Transaction;
+/** --- 数据库连接对象 --- */
 class Connection {
     constructor(etc, link) {
+        /** --- 本连接最后一次使用时间 --- */
         this._last = 0;
+        /** --- 最后两次执行的 sql 完整串 --- */
         this._lastSql = [];
+        /** --- 当前连接是否正在被独占使用 --- */
         this._using = false;
+        /** --- 当发生断开，则需从连接池移除连接 --- */
         this._lost = false;
+        /** --- 当前正在处理事务 --- */
         this._transaction = false;
         this._etc = etc;
         this._link = link;
         this.refreshLast();
     }
+    /**
+     * --- 获取连接 etc 信息 ---
+     */
     getEtc() {
         return this._etc;
     }
+    /**
+     * --- 获取最后一次获取连接的时间 ---
+     */
     getLast() {
         return this._last;
     }
+    /**
+     * --- 获取最后两次执行的 sql 字符串 ---
+     */
     getLastSql() {
         return this._lastSql;
     }
+    /**
+     * --- 将本条连接设置为不可用 ---
+     */
     setLost() {
         this._lost = true;
     }
+    /**
+     * --- 是否已经丢失 ---
+     */
     isLost() {
         return this._lost;
     }
+    /**
+     * --- 是否是开启事务状态 ---
+     */
     isTransaction() {
         return this._transaction;
     }
+    /**
+     * --- 获取当前状态是否正在被使用中 ---
+     */
     isUsing() {
         return this._using;
     }
+    /**
+     * --- 判断是否可用（丢失的也算不可用），返回 true 代表获取成功并自动刷新最后时间 ---
+     */
     using() {
         if (this._lost || this._using) {
             return false;
@@ -366,12 +460,21 @@ class Connection {
             return true;
         }
     }
+    /**
+     * --- 取消占用 ---
+     */
     used() {
         this._using = false;
     }
+    /**
+     * --- 设定最后使用时间 ---
+     */
     refreshLast() {
         this._last = time.stamp();
     }
+    /**
+     * --- 通过执行一条语句判断当前连接是否可用 ---
+     */
     async isAvailable() {
         this.refreshLast();
         try {
@@ -382,6 +485,11 @@ class Connection {
             return false;
         }
     }
+    /**
+     * --- 执行一条 SQL 并获得返回数据 ---
+     * @param sql 执行的 SQL 字符串
+     * @param values 要替换的 data 数据
+     */
     async query(sql, values) {
         let res;
         try {
@@ -408,12 +516,18 @@ class Connection {
         if (!this._transaction) {
             this._using = false;
         }
+        // --- 返回数据 ---
         return {
             'rows': res[0],
             'fields': res[1],
             'error': null
         };
     }
+    /**
+     * --- 执行一条 SQL 并获得影响行数对象 packet ---
+     * @param sql 执行的 SQL 字符串
+     * @param values 要替换的 data 数据
+     */
     async execute(sql, values) {
         let res;
         try {
@@ -431,6 +545,7 @@ class Connection {
             if (!this._transaction) {
                 this._using = false;
             }
+            // --- e.errno 可能为 1062 ---
             return {
                 'packet': null,
                 'fields': [],
@@ -446,6 +561,9 @@ class Connection {
             'error': null
         };
     }
+    /**
+     * --- 关闭连接，一般情况下不使用 ---
+     */
     async end() {
         try {
             await this._link.end();
@@ -455,6 +573,7 @@ class Connection {
             return false;
         }
     }
+    // --- 事务，只能在独占连接中使用，pool 创建事务返回独占连接，commit 或 rollback 释放连接回池 ---
     async beginTransaction() {
         if (this._using) {
             try {
@@ -496,10 +615,17 @@ class Connection {
     }
 }
 exports.Connection = Connection;
+/**
+ * --- 获取 Db Pool 对象 ---
+ * @param etc 配置信息可留空
+ */
 function get(ctrEtc) {
     const etc = ctrEtc instanceof ctr.Ctr ? ctrEtc.getPrototype('_config').db : ctrEtc;
     return new Pool(etc);
 }
+/**
+ * --- 获取当前连接池中所有连接的信息 ---
+ */
 function getConnectionList() {
     const list = [];
     for (let i = 0; i < connections.length; ++i) {

package/lib/dns.d.ts

@@ -1,13 +1,30 @@
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-6-19
+ * Last: 2022-09-12 20:58:07, 2024-2-21 17:55:54, 2025-6-13 19:08:56
+ */
 import * as ctr from '../sys/ctr';
+/**
+ * 0.DNSPod：https://www.dnspod.cn/docs/index.html（腾讯云也请使用 DNSPod 的 API）
+ * 1.阿里云：https://help.aliyun.com/document_detail/29745.html
+ */
+/** --- 服务商定义 --- */
 export declare enum ESERVICE {
     'DNSPOD' = 0,
     'ALIBABA' = 1
 }
+/** --- 选项 --- */
 export interface IOptions {
+    /** --- 服务商 ---- */
     'service': ESERVICE;
+    /** --- 密钥键 --- */
     'secretId'?: string;
+    /** --- 密钥值 --- */
     'secretKey'?: string;
 }
+/**
+ * --- 获取域名列表的返回对象 ---
+ */
 export interface IDomainList {
     'total': number;
     'list': Array<{
@@ -17,10 +34,16 @@ export interface IDomainList {
         'punyCode': string;
     }>;
 }
+/**
+ * --- 添加记录的返回对象 ---
+ */
 export interface IAddDomainRecord {
     'success': boolean;
     'id': string;
 }
+/**
+ * --- 记录值类型 ---
+ */
 export declare const RECORD_TYPE: {
     A: string;
     NS: string;
@@ -30,6 +53,9 @@ export declare const RECORD_TYPE: {
     SRV: string;
     AAAA: string;
 };
+/**
+ * --- 记录值线路 ---
+ */
 export declare enum ERecordLine {
     'DEFAULT' = 0,
     'TELECOM' = 1,
@@ -39,13 +65,26 @@ export declare enum ERecordLine {
     'OVERSEA' = 5
 }
 export declare class Dns {
+    /** --- 当前选项 --- */
     private readonly _opt;
     constructor(ctr: ctr.Ctr, opt: IOptions);
+    /**
+     * --- 最终发送 ---
+     * @param obj 要发送的信息
+     */
     private _send;
+    /**
+     * --- 获取域名列表 ---
+     * @param opt 参数
+     */
     getDomainList(opt: {
         'offset'?: number;
         'length'?: number;
     }): Promise<IDomainList | null>;
+    /**
+     * --- 添加记录 ---
+     * @param opt 参数
+     */
     addDomainRecord(opt: {
         'domain': string;
         'sub': string;
@@ -55,6 +94,10 @@ export declare class Dns {
         'ttl'?: number;
         'mx'?: number;
     }): Promise<IAddDomainRecord | null>;
+    /**
+     * --- 修改记录 ---
+     * @param opt 参数
+     */
     updateDomainRecord(opt: {
         'domain': string;
         'record': string;
@@ -65,6 +108,10 @@ export declare class Dns {
         'ttl'?: number;
         'mx'?: number;
     }): Promise<IAddDomainRecord | null>;
+    /**
+     * --- 删除记录 ---
+     * @param opt 参数
+     */
     deleteDomainRecord(opt: {
         'domain': string;
         'id': string;
@@ -72,4 +119,8 @@ export declare class Dns {
         'success': boolean;
     } | null>;
 }
+/**
+ * --- 创建一个第三方 Dns 对象 ---
+ * @param opt 选项
+ */
 export declare function get(ctr: ctr.Ctr, opt: IOptions): Dns;