@hz-9/a5-core 0.2.0-alpha.52 → 0.2.0-alpha.53

package/dist/all.d.ts

@@ -0,0 +1,871 @@
+/// <reference types="node" />
+
+import { FastifyReply as FastifyReply_2 } from 'fastify';
+import { FastifyRequest as FastifyRequest_2 } from 'fastify';
+import { IncomingHttpHeaders } from 'node:http';
+import { Logger } from '@nestjs/common';
+import { LoggerService } from '@nestjs/common/services/logger.service';
+import { LoggerService as LoggerService_2 } from '@nestjs/common';
+import { LogLevel } from '@nestjs/common/services/logger.service';
+import { NestFactoryStatic } from '@nestjs/core/nest-factory';
+import { NestFastifyApplication } from '@nestjs/platform-fastify';
+import { NestMiddleware } from '@nestjs/common';
+import { V4Options } from 'uuid';
+import { V7Options } from 'uuid';
+
+/**
+ * @public
+ *
+ *  `A5App.prototype.listen` 参数默认值。
+ *
+ */
+export declare const A5_APP_LISTEN_OPTIONS_DEFAULT: {
+    /**
+     * 是否自动退出。
+     */
+    readonly AUTO_EXIT: true;
+    /**
+     * 重试间隔。
+     */
+    readonly TRY_INTERVAL: 300;
+    /**
+     * 最大重试次数。
+     */
+    readonly TRY_TIMES: 20;
+};
+
+/**
+ * @public
+ *
+ * 默认监听端口。
+ */
+export declare const A5_APP_LISTEN_PORT_DEFAULT: 16100;
+
+/**
+ * @public
+ *
+ *  A5App Constructor Options
+ *
+ */
+export declare interface A5AppConstructorOptions {
+    /**
+     * Logger 对象。
+     *
+     * 显性设置 Logger 对象。默认情况下，将会加载 A5LoggerModule 的 Logger 实例。
+     *
+     * 如果加载失败，将会使用 A5ConsoleLogger 的实例。
+     *
+     */
+    readonly logger?: LoggerService_2;
+}
+
+/**
+ * @public
+ *
+ *  `A5` for `NestApplication`。服务应用类。
+ *
+ */
+export declare class A5Application {
+    protected readonly initTime: Date;
+    protected readonly logger: Logger;
+    /**
+     * setExtraUrl 及 getUrls 函数用于保存数据的数组
+     */
+    protected readonly extraUrls: string[];
+    /**
+     *
+     * 由 [nanoid](https://github.com/ai/nanoid) 生成的实例 ID。21 位长的字符串。
+     *
+     */
+    readonly instanceId: string;
+    readonly nestApp: NestFastifyApplication;
+    readonly options: A5AppOptions;
+    constructor(nestApp: NestFastifyApplication, options?: A5AppConstructorOptions);
+    init(): Promise<void>;
+    /**
+     *
+     * @public
+     *
+     *  `A5` 应用，对网络进行监听。
+     *
+     *  `A5` 增加了对端口获取失败的多次尝试。
+     *
+     *  如果想关闭自动重试，请传入 `listen({ tryTimes: 0 })`
+     *
+     *  TODO 未考虑采用哪种方案，进行多次尝试。
+     *
+     */
+    listen(options?: A5AppListenOptions): Promise<void>;
+    listen(port: number | string, options?: A5AppListenOptions): Promise<void>;
+    /**
+     *
+     * @public
+     *
+     *  添加额外的 urls, 便于 printAddress 进行输出
+     *
+     */
+    setExtraUrl(urlOrUrls: string | string[]): Promise<void>;
+    /**
+     *
+     * @public
+     *
+     *  输出可以访问当前服务的地址。
+     *
+     * TODO 需要精准判断 IPv4 和 IPv6 等各项情况。
+     *
+     */
+    getUrls(): Promise<string[]>;
+    /**
+     *
+     * @public
+     *
+     *  在正常获取 IP 与端口后，可通过此函数输出日志信息。
+     *
+     */
+    printAddress(): Promise<void>;
+    /**
+     *
+     * @public
+     *
+     *  关闭应用。
+     *  是 `NestApplication.prototype.close()` 的语法糖。
+     *
+     */
+    close(): Promise<void>;
+    /**
+     *
+     * @public
+     *
+     *  应用是否处于关闭状态
+     *
+     */
+    isClose(): boolean;
+    /**
+     * @internal
+     *
+     *  将会优先尝试 A5 内部的日志模块。如果没有的话，才会使用 A5ConsoleLogger
+     *
+     */
+    private _getA5LoggerService;
+}
+
+/**
+ *
+ * @public
+ *
+ *  `A5App.prototype.listen` 参数
+ *
+ */
+export declare interface A5AppListenOptions {
+    /**
+     *
+     * 若多次尝试失败，是否退出 NestApplication。
+     *
+     * 可选。默认值为 @see A5_APP_LISTEN_OPTIONS_DEFAULT.AUTO_EXIT
+     *
+     */
+    readonly autoExit?: boolean;
+    /**
+     *
+     * 若端口被占用，则重新获取端口的时间间隔。(单位 ms)
+     *
+     * 数值是正整数。
+     *
+     * 可选。默认值为 @see A5_APP_LISTEN_OPTIONS_DEFAULT.TRY_INTERVAL
+     *
+     * TODO 后续可以添加合适的时间范围。
+     *
+     */
+    readonly tryInterval?: number;
+    /**
+     *
+     * 若端口被占用，则重新获取端口的最大尝试次数。
+     *
+     * 数值是正整数。
+     *
+     * 可选。默认值为 @see A5_APP_LISTEN_OPTIONS_DEFAULT.TRY_TIMES
+     *
+     */
+    readonly tryTimes?: number;
+}
+
+/**
+ * @public
+ *
+ *  A5App Options
+ *
+ */
+export declare type A5AppOptions = Required<A5AppConstructorOptions>;
+
+/**
+ * @public
+ */
+export declare class A5ConsoleLogger implements LoggerService {
+    protected static lastTimestampAt?: number;
+    protected readonly originalContext: string;
+    protected context: string;
+    protected options: A5ConsoleLoggerOptions;
+    constructor(options?: A5ConsoleLoggerConstructorOptions);
+    /**
+     * Write a 'log' level log, if the configured level allows for it.
+     * Prints to `stdout` with newline.
+     */
+    log(message: unknown, context?: string): void;
+    log(message: unknown, ...optionalParams: [...unknown[], string | unknown]): void;
+    /**
+     * Write an 'error' level log, if the configured level allows for it.
+     * Prints to `stderr` with newline.
+     */
+    error(message: unknown, stackOrContext?: string): void;
+    error(message: unknown, stack?: string, context?: string): void;
+    error(message: unknown, ...optionalParams: [...unknown[], string | unknown, string | unknown]): void;
+    /**
+     * Write a 'warn' level log, if the configured level allows for it.
+     * Prints to `stdout` with newline.
+     */
+    warn(message: unknown, context?: string): void;
+    warn(message: unknown, ...optionalParams: [...unknown[], string | unknown]): void;
+    /**
+     * Write a 'debug' level log, if the configured level allows for it.
+     * Prints to `stdout` with newline.
+     */
+    debug(message: unknown, context?: string): void;
+    debug(message: unknown, ...optionalParams: [...unknown[], string | unknown]): void;
+    /**
+     * Write a 'verbose' level log, if the configured level allows for it.
+     * Prints to `stdout` with newline.
+     */
+    verbose(message: unknown, context?: string): void;
+    verbose(message: unknown, ...optionalParams: [...unknown[], string | unknown]): void;
+    /**
+     * TODO 需要思考，是否需要让 fatal 与 error 保持一致！！！
+     */
+    /**
+     * Write a 'fatal' level log, if the configured level allows for it.
+     * Prints to `stdout` with newline.
+     */
+    fatal(message: unknown, context?: string): void;
+    fatal(message: unknown, ...optionalParams: [...unknown[], string | unknown]): void;
+    /**
+     * Set log levels
+     * @param levels - log levels
+     */
+    setLogLevels(levels: LogLevel[]): void;
+    /**
+     * Set logger context
+     * @param context - context
+     */
+    setContext(context: string): void;
+    /**
+     * Get logger context
+     * @param context - context
+     */
+    getContext(): string;
+    /**
+     * Resets the logger context to the value that was passed in the constructor.
+     */
+    resetContext(): void;
+    isLevelEnabled(level: LogLevel): boolean;
+    protected printMessages(messages: unknown[], context_: string, logLevel?: LogLevel, writeStreamType?: 'stdout' | 'stderr'): void;
+    protected formatMessage(options: A5FormatMessageOptions): string;
+    protected formatMessageStructure(options: A5FormatMessageOptions): A5FormatMessageInfo;
+    protected formatPrefix(): string;
+    protected formatPid(): string;
+    protected formatLogLevel(logLevel: LogLevel): string;
+    protected formatTimestamp(dateMilliseconds: number): string;
+    protected formatContext(context: string): string;
+    protected stringifyMessage(message: unknown, logLevel: LogLevel): string;
+    protected colorize(message: string, logLevel: LogLevel): string;
+    protected printStackTrace(stack: string | undefined): void;
+    protected updateAndGetTimestampDiff(): number | null;
+    protected formatTimestampDiff(timestampDiff: number | null): string;
+    protected getContextAndMessagesToPrint(args: unknown[]): {
+        context: string;
+        messages: unknown[];
+    };
+    protected getContextAndStackAndMessagesToPrint(args: unknown[]): {
+        messages: unknown[];
+        context: string;
+        stack?: string;
+    };
+    protected isStackFormat(stack: unknown): stack is string;
+    /**
+     * 移除最后 多个 undefined
+     */
+    protected removeLastUndefined(args: unknown[]): unknown[];
+    protected getColorByLogLevel(level: LogLevel): (text: string) => string;
+    /**
+     * 保证日志数据的统一格式，对 Nest 默认的日志输出进行格式化。
+     */
+    protected _contextNeedApologeticReplace(context: string): context is 'NestFactory' | 'NestApplication';
+    /**
+     * 保证日志数据的统一格式，对 Nest 默认的日志输出进行格式化。
+     */
+    protected _contextApologeticReplace(context: 'NestFactory' | 'NestApplication'): string;
+    /**
+     * 保证日志数据的统一格式，对 Nest 默认的日志输出进行格式化。
+     */
+    protected _messageApologeticReplace(message: unknown): unknown;
+}
+
+/**
+ * @public
+ */
+export declare interface A5ConsoleLoggerConstructorOptions {
+    /**
+     * Context name for logs
+     *
+     * Default is ''
+     */
+    context?: string;
+    /**
+     * Enabled log levels.
+     *
+     * Default is @see DEFAULT_LOG_LEVELS
+     */
+    logLevels?: LogLevel[];
+    /**
+     * If enabled, will print timestamp (time difference) between current and previous log message.
+     *
+     * Default is `false`
+     */
+    timestamp?: boolean;
+}
+
+/**
+ * @public
+ */
+export declare class A5ConsoleLoggerMiddleware implements NestMiddleware {
+    protected logger: Logger;
+    use(req: FastifyRequestRaw, res: FastifyReplyRaw, next: () => void): void;
+}
+
+/**
+ * @public
+ */
+export declare type A5ConsoleLoggerOptions = Omit<Required<A5ConsoleLoggerConstructorOptions>, 'context'>;
+
+/**
+ * @public
+ */
+export declare const A5Factory: A5FactoryStatic;
+
+/**
+ * @public
+ */
+export declare interface A5FactoryCreateOptions {
+    /**
+     * 是否输出日志信息。可选。默认为 true
+     */
+    readonly printLogo?: boolean;
+}
+
+declare class A5FactoryStatic {
+    protected nestFactoryStatic: NestFactoryStatic;
+    constructor();
+    create(module: unknown, options?: A5FactoryCreateOptions): Promise<A5Application>;
+}
+
+/**
+ * @public
+ */
+export declare interface A5FormatMessageInfo {
+    prefix: string;
+    pid: string;
+    timestamp: number;
+    timestampStr: string;
+    logLevel: string;
+    context: string;
+    output: string;
+    timestampDiff: number | null;
+    timestampDiffStr: string;
+}
+
+declare interface A5FormatMessageOptions {
+    logLevel: LogLevel;
+    context: string;
+    message: unknown;
+}
+
+/**
+ * @public
+ *
+ *  `A5` 全局提供者 Token。
+ *
+ */
+export declare type A5GlobalProvideToken = `Global.A5.${string}`;
+
+/**
+ * A5 加载包错误
+ * 当动态加载可选依赖包失败时抛出此错误
+ * @public
+ */
+export declare class A5LoadPackageError extends Error {
+    /**
+     * 错误名称
+     */
+    readonly name: string;
+    /**
+     * 尝试加载的包名
+     */
+    readonly packageName: string;
+    /**
+     * 原始错误（如果有）
+     */
+    readonly cause?: Error;
+    constructor(packageName: string, message?: string, cause?: Error);
+}
+
+/**
+ * @public
+ *
+ * `A5` 配置项路径。
+ *
+ */
+export declare type A5ModuleConfigPath = `A5.${string}`;
+
+/**
+ * A5 随机工具类
+ *
+ * 提供生成随机值和 UUID 的静态方法
+ *
+ * @public
+ */
+export declare class A5RandomUtil {
+    static nanoid(size?: number): string;
+    static uuidV4(options?: V4Options): string;
+    static uuidV7(options?: V7Options): string;
+    /**
+     * 生成指定位数的随机数字
+     *
+     * @param digits - 位数，默认 6
+     * @returns 随机数字字符串
+     */
+    static randomDigits(digits?: number): string;
+    /**
+     * 生成指定长度的随机字符串（a-zA-Z0-9）
+     *
+     * @param length - 长度，默认 8
+     * @returns 随机字符串
+     */
+    static randomString(length?: number, chars?: string): string;
+}
+
+/**
+ * @public
+ *
+ * `A5` 作用域提供者 Token。
+ *
+ */
+export declare type A5ScopeProvideToken = `Scope.A5.${string}`;
+
+/**
+ *
+ * @public
+ *
+ *  通用工具类
+ *
+ */
+export declare class A5Util {
+    /**
+     *
+     * 睡眠。
+     *
+     * @param t - 时间。单位：毫秒
+     */
+    static sleep(t: number): Promise<void>;
+    /**
+     * @public
+     *
+     *  如果不是绝对路径，则进行拼接
+     *
+     * @param sourcePath - 资源路径
+     * @param basePath - 基础路径
+     *
+     * @returns 资源路径的绝对路径。
+     */
+    static tryWithAbsolutePath(sourcePath: string, basePath: string): string;
+    static getReqIdFromRequest(req: FastifyRequest): string;
+    static getReqHeadersFromRequest(req: FastifyRequest): IncomingHttpHeaders;
+    static getReqIdAndHeadersFromRequest(req: FastifyRequest): {
+        reqId: string;
+        reqHeaders: IncomingHttpHeaders;
+    };
+}
+
+/**
+ * 类型断言工具 - 判断两个类型结构相似
+ *
+ * @public
+ */
+export declare type Alike<X, Y> = Equal<MergeInsertions<X>, MergeInsertions<Y>>;
+
+/**
+ * @public
+ */
+export declare class ColorUtil {
+    static get isColorAllowed(): boolean;
+    static bold(text: string): string;
+    static red(text: string): string;
+    static green(text: string): string;
+    static yellow(text: string): string;
+    static blue(text: string): string;
+    static magenta(text: string): string;
+    static cyan(text: string): string;
+    static redBright(text: string): string;
+    static greenBright(text: string): string;
+    static yellowBright(text: string): string;
+    static blueBright(text: string): string;
+    static magentaBright(text: string): string;
+    static cyanBright(text: string): string;
+    /**
+     * 移除 ANSI 颜色代码
+     *
+     * @param text - text to clear
+     * @returns cleaned text
+     */
+    static clear(text: string): string;
+}
+
+/**
+ * 类型调试工具 - 展开类型定义
+ *
+ * @public
+ */
+export declare type Debug<T> = {
+    [K in keyof T]: T[K];
+};
+
+/**
+ * @public
+ */
+export declare const DEFAULT_LOG_LEVELS: LogLevel[];
+
+/**
+ * 类型断言工具 - 判断两个类型相等
+ *
+ * @public
+ */
+export declare type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+
+/**
+ * @public
+ */
+export declare const ERROR_WELCOME_MSG: string;
+
+/**
+ * 类型断言工具 - 期望类型为 true
+ *
+ * @public
+ */
+export declare type Expect<T extends true> = T;
+
+/**
+ * 类型断言工具 - 期望类型扩展自目标类型
+ *
+ * @public
+ */
+export declare type ExpectExtends<VALUE, EXPECTED> = EXPECTED extends VALUE ? true : false;
+
+/**
+ * 类型断言工具 - 期望值为 false
+ *
+ * @public
+ */
+export declare type ExpectFalse<T extends false> = T;
+
+/**
+ * 类型断言工具 - 期望值为 true
+ *
+ * @public
+ */
+export declare type ExpectTrue<T extends true> = T;
+
+/**
+ * 类型断言工具 - 验证函数参数类型
+ *
+ * @public
+ */
+export declare type ExpectValidArgs<FUNC extends (...args: any[]) => any, ARGS extends any[]> = ARGS extends Parameters<FUNC> ? true : false;
+
+/**
+ * @public
+ */
+export declare type FastifyReply = FastifyReply_2;
+
+/**
+ * @public
+ */
+export declare type FastifyReplyRaw = FastifyReply_2['raw'];
+
+/**
+ * @public
+ */
+export declare type FastifyRequest = FastifyRequest_2;
+
+/**
+ * @public
+ */
+export declare type FastifyRequestRaw = FastifyRequest_2['raw'];
+
+/**
+ *
+ * @public
+ *
+ *   `A5 Log Module` Global Provide Token
+ *
+ */
+export declare const GLOBAL_PROVIDE_TOKEN_A5_CONFIG: A5GlobalProvideToken;
+
+/**
+ *
+ * @public
+ *
+ *   `A5 Log Module` Global Provide Token
+ *
+ */
+export declare const GLOBAL_PROVIDE_TOKEN_A5_LOG_LOGGER: A5GlobalProvideToken;
+
+/**
+ * @public
+ */
+export declare const HOME_STATIC_PATH: string;
+
+/**
+ *
+ * @public
+ *
+ *  `A5 Config Module` 抽象类。
+ *
+ */
+export declare abstract class IA5ConfigModule {
+}
+
+/**
+ *
+ * @public
+ *
+ *  `A5 Log Module` 抽象类。
+ *
+ */
+export declare abstract class IA5LogModule {
+}
+
+/**
+ * 类型断言工具 - 判断是否为 any 类型
+ *
+ * @public
+ */
+export declare type IsAny<T> = 0 extends 1 & T ? true : false;
+
+/**
+ * 类型断言工具 - 判断是否为 false
+ *
+ * @public
+ */
+export declare type IsFalse<T extends false> = T;
+
+/**
+ * 类型断言工具 - 判断是否为 true
+ *
+ * @public
+ */
+export declare type IsTrue<T extends true> = T;
+
+/**
+ * JSON 数组类型
+ *
+ * 表示 JSON 数组结构，元素为任意 JSON 值
+ *
+ * @public
+ */
+export declare interface JsonArray extends Array<JsonValue> {
+}
+
+/**
+ * JSON 对象类型
+ *
+ * 表示 JSON 对象结构，键为字符串，值为任意 JSON 值
+ *
+ * @public
+ */
+export declare interface JsonObject {
+    [key: string]: JsonValue;
+}
+
+/**
+ * JSON 值类型
+ *
+ * 表示所有合法的 JSON 值类型，包括基础类型、对象和数组
+ *
+ * @public
+ */
+export declare type JsonValue = string | number | boolean | null | JsonObject | JsonArray;
+
+/**
+ * 包加载工具类
+ * 用于统一处理可选依赖的动态导入
+ * @public
+ */
+export declare class LoadPackageUtil {
+    /**
+     * 动态加载包
+     * @param packageName - 包名
+     * @returns 加载的包模块
+     * @throws 当包加载失败时抛出错误
+     */
+    static loadPackage<T = unknown>(packageName: string): T;
+    /**
+     * 安全地动态加载包
+     * @param packageName - 包名
+     * @returns 加载的包模块，如果失败则返回 null
+     */
+    static loadPackageSafe<T = unknown>(packageName: string): T | null;
+    /**
+     * 带重试的动态加载包
+     * @param packageName - 包名
+     * @param retries - 重试次数，默认为 3
+     * @param retryDelay - 重试间隔（毫秒），默认为 100
+     * @returns 加载的包模块
+     * @throws 当所有重试都失败时抛出错误
+     */
+    static loadPackageWithRetry<T = unknown>(packageName: string, retries?: number, retryDelay?: number): Promise<T>;
+}
+
+/**
+ * 因 `logo` 字符串特殊字符过多，不应直接存放当前文件。
+ *
+ * 进行 base64 编码并存放。
+ */
+/**
+ *
+ * @public
+ *
+ *  打印 Logo。
+ *
+ * logo 是在 http://patorjk.com/software/taag/#p=display&f=Big&t=a5 进行制作的。
+ *
+ */
+export declare class LogoUtil {
+    private static _content;
+    /**
+     * Logo 的文本信息。
+     */
+    static get content(): string;
+    /**
+     *
+     * 打印 A5 的 Logo 及版本信息。
+     *
+     * 使用 `console.log` 输出信息，不会写入到日志文件中。
+     *
+     * @param onlyLogo - 仅打印 Logo，不包含版本信息。可选。默认为 false
+     *
+     */
+    static print(onlyLogo?: boolean): void;
+}
+
+/**
+ * @public
+ */
+export declare const MAIN_STATIC_PATH: string;
+
+/**
+ * 类型合并工具 - 合并嵌套类型
+ *
+ * @public
+ */
+export declare type MergeInsertions<T> = T extends object ? {
+    [K in keyof T]: MergeInsertions<T[K]>;
+} : T;
+
+/**
+ *
+ * @public
+ *
+ *   `A5 Config Module` Config Path
+ *
+ */
+export declare const MODULE_CONFIG_PATH_A5_CONFIG: <T extends string>(str: T) => `A5.config.${T}`;
+
+/**
+ *
+ * @public
+ *
+ *   `A5 Log Module` Config Path
+ *
+ */
+export declare const MODULE_CONFIG_PATH_A5_LOG: <T extends string>(str: T) => `A5.log.${T}`;
+
+/**
+ * 类型断言工具 - 判断不是 any 类型
+ *
+ * @public
+ */
+export declare type NotAny<T> = true extends IsAny<T> ? false : true;
+
+/**
+ * 类型断言工具 - 判断两个类型不相等
+ *
+ * @public
+ */
+export declare type NotEqual<X, Y> = true extends Equal<X, Y> ? false : true;
+
+/**
+ * @public
+ */
+export declare type RequiredButOmit<T, K extends keyof T> = Required<Pick<T, K>> & Omit<T, K>;
+
+/**
+ * @public
+ */
+export declare type RequiredButPick<T, K extends keyof T> = Required<Omit<T, K>> & Pick<T, K>;
+
+/**
+ * @public
+ *
+ * 当前运行环境。
+ *
+ */
+export declare class RunEnvUtil {
+    /**
+     * 是否处于开发环境.
+     */
+    static get isDev(): boolean;
+    /**
+     * 是否处于生产环境.
+     */
+    static get isProd(): boolean;
+    /**
+     * 是否处于 PKG 打包后的环境。
+     */
+    static get inPKG(): boolean;
+    /**
+     * 是否处于 `VS Code` 的 `Debugger` 模式下。
+     */
+    static get inVSCodeDebugger(): boolean;
+    /**
+     * 是否处于 `Jest` 的单元测试环境下。
+     */
+    static get inJest(): boolean;
+}
+
+/**
+ * 类型转换工具 - 联合类型转交叉类型
+ *
+ * @public
+ */
+export declare type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+
+/**
+ * @public
+ */
+export declare type Writable<T> = {
+    -readonly [P in keyof T]: T[P];
+};
+
+/**
+ * @public
+ */
+export declare type WritableRequired<T> = Writable<Required<T>>;
+
+export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hz-9/a5-core",
-  "version": "0.2.0-alpha.52",
+  "version": "0.2.0-alpha.53",
   "description": "The core library for the `@hz-9/a5-*` series of repositories.",
   "keywords": [
     "nest",