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

package/package.json

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

package/dist/all.d.ts

@@ -1,871 +0,0 @@
-/// <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 { }