@maiyunnet/kebab 2.0.7 → 2.0.9

package/sys/ctr.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2020-3-14 17:24:38
+ * Last: 2020-3-30 15:31:40, 2022-07-22 16:59:00, 2022-09-12 23:51:56, 2022-09-23 15:53:58, 2022-12-29 01:18:08, 2023-2-28 20:07:57, 2023-12-27 18:39:35, 2024-3-1 19:38:53, 2024-4-9 16:03:58, 2025-2-12 18:55:44, 2025-6-12 16:56:08
+ */
 import * as http from 'http';
 import * as http2 from 'http2';
 import * as session from '../lib/session';
@@ -5,41 +10,75 @@ import * as db from '../lib/db';
 import * as kv from '../lib/kv';
 import * as lWs from '../lib/ws';
 import * as types from '../types';
+/**
+ * --- 清除已经加载的 data 与语言包文件缓存 ---
+ */
 export declare function clearLocaleData(): void;
 export declare class Ctr {
+    /** --- 路由参数序列数组 --- */
     protected _param: string[];
+    /** --- 当前的 action 名 --- */
     protected _action: string;
+    /** --- 请求的 header 列表，key 均为小写 --- */
     protected _headers: http.IncomingHttpHeaders;
+    /** --- GET 数据 --- */
     protected _get: Record<string, string>;
+    /** --- 原始 POST 数据 --- */
     protected _rawPost: Record<string, types.Json>;
+    /** --- POST 数据 --- */
     protected _post: Record<string, types.Json>;
+    /** --- 原始 input 字符串 */
     protected _input: string;
+    /** --- 上传的文件列表 --- */
     protected _files: Record<string, types.IPostFile | types.IPostFile[]>;
+    /** --- Cookie 数组 --- */
     protected _cookie: Record<string, string>;
+    /** --- Jwt 数组 --- */
     protected _jwt: Record<string, types.Json>;
+    /** --- Session 数组 --- */
     protected _session: Record<string, types.Json>;
+    /** --- Session --- 对象 */
     protected _sess: session.Session | null;
+    /** --- 页面浏览器客户端缓存 --- */
     protected _cacheTTL: number;
+    /** --- XSRF TOKEN 值 --- */
     protected _xsrf: string;
+    /** --- 自定义 http code --- */
     protected _httpCode: number;
+    /** --- 当前语言名 --- */
     protected _locale: string;
+    /** --- vhost 的 kebab.json 以及全局常量 --- */
     protected readonly _config: types.IConfig;
     protected readonly _req: http2.Http2ServerRequest | http.IncomingMessage;
     protected readonly _res: http2.Http2ServerResponse | http.ServerResponse;
     protected readonly _socket: lWs.Socket;
+    /** --- 本 ctr 已加载的语言文件列表 --- */
     protected _localeFiles: string[];
+    /** --- 本 ctr 的 locale data --- */
     protected _localeData: Record<string, Record<string, string>>;
     constructor(config: types.IConfig, req: http2.Http2ServerRequest | http.IncomingMessage, res?: http2.Http2ServerResponse | http.ServerResponse);
+    /** --- 当前用户连接是否还在连接中 --- */
     get isAvail(): boolean;
+    /** --- timeout 的 timer --- */
     protected _timer?: {
         'timer': NodeJS.Timeout;
         'timeout': number;
         'callback': () => void;
     };
+    /** --- 获取当前过期时间 --- */
     get timeout(): number;
+    /**
+     * --- 设置当前过期时间 ---
+     */
     set timeout(num: number);
+    /** --- 一些需要等待的事项的记录（异步任务、事务） --- */
     private readonly _waitInfo;
+    /**
+     * --- 执行一段跳出堆栈的异步代码，代码执行完成前，热更新不会杀死当面进程 且 ftmp 临时文件不会被清除 ---
+     * @param func 异步代码
+     */
     protected _asyncTask(func: () => void | Promise<void>): void;
+    /** --- 获取类内部的 prototype --- */
     getPrototype(name: '_config'): types.IConfig;
     getPrototype(name: '_sess'): session.Session | null;
     getPrototype(name: '_headers'): http.IncomingHttpHeaders;
@@ -49,45 +88,172 @@ export declare class Ctr {
     getPrototype(name: '_rawPost' | '_post' | '_get' | '_session'): Record<string, types.Json>;
     getPrototype(name: '_input'): string;
     getPrototype(name: string): types.Json;
+    /** --- 设置类内部的 prototype --- */
     setPrototype(name: string, val: string | string[] | http.IncomingHttpHeaders | Record<string, types.Json> | session.Session | lWs.Socket | null): void;
+    /**
+     * --- 实例化后会执行的方法，可重写此方法 ---
+     */
     onLoad(): boolean | string | types.DbValue[] | Promise<boolean | string | types.DbValue[]>;
+    /**
+     * --- 整个结束前会执行本方法，可重写此方法对输出结果再处理一次（Websocket 模式无效） ---
+     * @param rtn 之前用户的输出结果
+     */
     onUnload(rtn: boolean | string | types.DbValue[]): boolean | string | types.DbValue[] | Promise<boolean | string | types.DbValue[]>;
+    /**
+     * --- WebSocket 下在建立 Server 连接之前可对 WebSocket 的信息进行配置 ---
+     */
     onUpgrade(): {
         'headers'?: http.OutgoingHttpHeaders;
         'timeout'?: number;
     };
+    /**
+     * --- WebSocket 下当收到数据时会自动被调用的事件，即只文本和二进制数据，返回内容会被发送给 socket，但返回 false 连接会被中断 ---
+     */
     onData(data: Buffer | string, opcode: lWs.EOpcode): types.Json;
+    /**
+     * --- 包含所有 opcode 的消息，若要发送数据需自行调用 write 方法，返回 false 则不会执行默认方法 ---
+     * @param data 数据
+     * @param opcode opcode
+     */
     onMessage(data: Buffer | string, opcode: lWs.EOpcode): undefined | boolean | Promise<undefined | boolean>;
+    /**
+     * --- WebSocket 下连接恢复可写入状态后会调用此事件，可重写此方法 ---
+     */
     onDrain(): void | Promise<void>;
+    /**
+     * --- WebSocket 下连接被终止后会自动被调用的事件，可重写此方法 ---
+     */
     onClose(): void | Promise<void>;
+    /**
+     * --- 获取截止当前时间的总运行时间 ---
+     * @param ms 为 true 为毫秒，否则为秒
+     */
     protected _getRunTime(ms?: boolean): number;
+    /**
+     * --- 获取截止当前内存的使用情况 ---
+     */
     protected _getMemoryUsage(): number;
+    /**
+     * --- 加载视图 ---
+     * @param path
+     * @param data
+     */
     protected _loadView(path: string, data?: types.Json): Promise<string>;
+    /**
+     * --- 检测提交的数据类型 ---
+     * @param input 要校验的输入项
+     * @param rule 规则
+     * @param rtn 返回值
+     */
     protected _checkInput(input: Record<string, types.Json>, rule: Record<string, types.Json[]>, rtn: types.Json[]): boolean;
+    /**
+     * --- 检测提交的数据类型（会检测 XSRF） ---
+     * @param input 要校验的输入项
+     * @param rule 规则
+     * @param rtn 返回值
+     */
     protected _checkXInput(input: Record<string, types.Json>, rule: Record<string, types.Json[]>, rtn: types.Json[]): boolean;
+    /**
+     * --- 当前页面开启 XSRF 支持（主要检测 cookie 是否存在） ---
+     * --- 如果当前页面有 CDN，请不要使用 ---
+     */
     protected _enabledXsrf(): void;
+    /**
+     * --- 获取 Auth 字符串，用于客户端提交 ---
+     * @param user 用户名
+     * @param pwd 密码
+     */
     protected _getBasicAuth(user: string, pwd: string): string;
+    /**
+     * --- 根据用户 ua 获取当前用户的设备类型 ---
+     */
     protected _device(): 'android' | 'windows' | 'linux' | 'macintosh' | 'ipad' | 'unknown';
+    /** --- auth 对象，user, pwd --- */
     private _authorization;
+    /**
+     * --- 通过 header 或 _auth 获取鉴权信息或 JWT 信息（不解析） ---
+     */
     getAuthorization(): {
         'user': string;
         'pwd': string;
     } | false | string;
+    /**
+     * --- 获取 data 数据 ---
+     * @param path 文件路径（不含扩展名）
+     */
     protected _loadData(path: string): Promise<Record<string, string> | null>;
+    /**
+     * --- 跳转（302临时跳转），支持相对本项目根路径的路径或绝对路径 ---
+     * @param location 相对或绝对网址
+     */
     protected _location(location: string): false;
+    /**
+     * --- 开启 Session ---
+     * @param link Kv 或 Db 实例
+     * @param auth 设为 true 则从头 Authorization 或 post _auth 值读取 token
+     * @param opt name, ttl, ssl, sqlPre
+     */
     protected _startSession(link: db.Pool | kv.Pool, auth?: boolean, opt?: session.IOptions): Promise<void>;
+    /**
+     * --- 设定语言并加载语言包 ---
+     * @param loc 要加载的目标语言
+     * @param pkg 包名，为空自动填充为 default
+     */
     protected _loadLocale(loc: string, pkg?: string): Promise<boolean>;
     private _loadLocaleDeep;
+    /**
+     * --- 根据当前后台语言包设置情况获取 JSON 字符串传输到前台 ---
+     * @return string
+     */
     protected _getLocaleJsonString(): string;
+    /**
+     * --- 获取当前语言名 ---
+     */
     protected _getLocale(): string;
+    /**
+     * --- 开启跨域请求 ---
+     * 返回 true 接续执行，返回 false 需要中断用户本次访问（options请求）
+     */
     protected _cross(): boolean;
+    /**
+     * --- 获取语言包值 ---
+     * @param key
+     * @param data 要替换的数据
+     */
     _l(key: string, data?: string[]): string;
+    /**
+     * --- 发送 socket 文本 ---
+     * @param data 要发送的信息
+     */
     protected _writeText(data: string): boolean;
+    /**
+     * --- 发送结果对象文本 ---
+     * @param data 要发送的结果对象，如 [0, 'Failed.']
+     */
     protected _writeResult(data: types.Json): boolean;
+    /**
+     * --- 发送 socket 二进制 ---
+     * @param data 要发送的信息
+     */
     protected _writeBinary(data: Buffer | string | Array<Buffer | string>): boolean;
+    /**
+     * --- 发送 socket ping ---
+     * @param data 要发送的信息
+     */
     protected _ping(): boolean;
+    /**
+     * --- 发送 socket pong ---
+     * @param data 要发送的信息
+     */
     protected _pong(): boolean;
+    /**
+     * --- 主动关闭当前 socket 连接 ---
+     */
     protected _end(): void;
+    /**
+     * --- 获取 formdata 的信息 ---
+     * @param events 文件处理情况
+     */
     protected _handleFormData(events?: {
         onfilestart?: (name: string) => boolean | undefined;
         onfiledata?: (chunk: Buffer) => void;