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

package/dist/all.d.ts

@@ -0,0 +1,920 @@
+/// <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 ms from 'ms';
+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}`;
+
+/**
+ * @public
+ */
+export declare type MSStringValue = ms.StringValue;
+
+/**
+ * @public
+ */
+export declare class MSUtil {
+    /**
+     * 将 ms 时间字符串转换为毫秒数
+     *
+     * @param value - ms 时间字符串
+     * @returns 毫秒数
+     *
+     * @example
+     * ```typescript
+     * MSUtil.ms('123') // 123
+     * MSUtil.ms('2h') // 7200000
+     * MSUtil.ms('30s') // 30000
+     * MSUtil.ms('123 ms') // 123
+     * ```
+     */
+    static ms(value: ms.StringValue): number;
+    /**
+     * 判断字符串是否是有效的 ms 时间字符串格式
+     * 可以作为类型守卫使用，在运行时验证并断言为 ms.StringValue 类型
+     *
+     * @param value - 要检查的字符串值
+     * @returns 如果是有效的 ms 字符串返回 true，否则返回 false
+     *
+     * @example
+     * ```typescript
+     * // 有效格式
+     * MSUtil.isMsStringValue('123') // true
+     * MSUtil.isMsStringValue('2h') // true
+     * MSUtil.isMsStringValue('30s') // true
+     * MSUtil.isMsStringValue('123 ms') // true
+     *
+     * // 无效格式
+     * MSUtil.isMsStringValue('abc') // false
+     * MSUtil.isMsStringValue('') // false
+     * MSUtil.isMsStringValue('123xx') // false
+     * ```
+     */
+    static isMsStringValue(value: string): value is ms.StringValue;
+}
+
+/**
+ * 类型断言工具 - 判断不是 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/dist/util/index.d.ts

@@ -2,5 +2,6 @@ export * from './a5.util';
 export * from './color.util';
 export * from './load-package.util';
 export * from './logo.util';
+export * from './ms.util';
 export * from './random.util';
 export * from './run-env.util';

package/dist/util/index.js

@@ -18,6 +18,7 @@ __exportStar(require("./a5.util"), exports);
 __exportStar(require("./color.util"), exports);
 __exportStar(require("./load-package.util"), exports);
 __exportStar(require("./logo.util"), exports);
+__exportStar(require("./ms.util"), exports);
 __exportStar(require("./random.util"), exports);
 __exportStar(require("./run-env.util"), exports);
 //# sourceMappingURL=index.js.map

package/dist/util/ms.util.d.ts

@@ -0,0 +1,47 @@
+import ms from 'ms';
+/**
+ * @public
+ */
+export type MSStringValue = ms.StringValue;
+/**
+ * @public
+ */
+export declare class MSUtil {
+    /**
+     * 将 ms 时间字符串转换为毫秒数
+     *
+     * @param value - ms 时间字符串
+     * @returns 毫秒数
+     *
+     * @example
+     * ```typescript
+     * MSUtil.ms('123') // 123
+     * MSUtil.ms('2h') // 7200000
+     * MSUtil.ms('30s') // 30000
+     * MSUtil.ms('123 ms') // 123
+     * ```
+     */
+    static ms(value: ms.StringValue): number;
+    /**
+     * 判断字符串是否是有效的 ms 时间字符串格式
+     * 可以作为类型守卫使用，在运行时验证并断言为 ms.StringValue 类型
+     *
+     * @param value - 要检查的字符串值
+     * @returns 如果是有效的 ms 字符串返回 true，否则返回 false
+     *
+     * @example
+     * ```typescript
+     * // 有效格式
+     * MSUtil.isMsStringValue('123') // true
+     * MSUtil.isMsStringValue('2h') // true
+     * MSUtil.isMsStringValue('30s') // true
+     * MSUtil.isMsStringValue('123 ms') // true
+     *
+     * // 无效格式
+     * MSUtil.isMsStringValue('abc') // false
+     * MSUtil.isMsStringValue('') // false
+     * MSUtil.isMsStringValue('123xx') // false
+     * ```
+     */
+    static isMsStringValue(value: string): value is ms.StringValue;
+}

package/dist/util/ms.util.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MSUtil = void 0;
+const ms_1 = __importDefault(require("ms"));
+/**
+ * @public
+ */
+class MSUtil {
+    /**
+     * 将 ms 时间字符串转换为毫秒数
+     *
+     * @param value - ms 时间字符串
+     * @returns 毫秒数
+     *
+     * @example
+     * ```typescript
+     * MSUtil.ms('123') // 123
+     * MSUtil.ms('2h') // 7200000
+     * MSUtil.ms('30s') // 30000
+     * MSUtil.ms('123 ms') // 123
+     * ```
+     */
+    static ms(value) {
+        return (0, ms_1.default)(value);
+    }
+    /**
+     * 判断字符串是否是有效的 ms 时间字符串格式
+     * 可以作为类型守卫使用，在运行时验证并断言为 ms.StringValue 类型
+     *
+     * @param value - 要检查的字符串值
+     * @returns 如果是有效的 ms 字符串返回 true，否则返回 false
+     *
+     * @example
+     * ```typescript
+     * // 有效格式
+     * MSUtil.isMsStringValue('123') // true
+     * MSUtil.isMsStringValue('2h') // true
+     * MSUtil.isMsStringValue('30s') // true
+     * MSUtil.isMsStringValue('123 ms') // true
+     *
+     * // 无效格式
+     * MSUtil.isMsStringValue('abc') // false
+     * MSUtil.isMsStringValue('') // false
+     * MSUtil.isMsStringValue('123xx') // false
+     * ```
+     */
+    static isMsStringValue(value) {
+        if (typeof value !== 'string' || value.length === 0) {
+            return false;
+        }
+        try {
+            // 尝试转换，如果 ms() 函数能成功解析则说明格式正确
+            // 使用类型断言因为我们正在验证这个值
+            const result = (0, ms_1.default)(value);
+            return typeof result === 'number' && Number.isNaN(result) === false;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+}
+exports.MSUtil = MSUtil;
+//# sourceMappingURL=ms.util.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hz-9/a5-core",
-  "version": "0.2.0-alpha.52",
+  "version": "0.2.0-alpha.54",
   "description": "The core library for the `@hz-9/a5-*` series of repositories.",
   "keywords": [
     "nest",
@@ -53,7 +53,9 @@
     "type-fest": "~4.20.0",
     "upath": "~2.0.1",
     "ua-parser-js": "~1.0.38",
-    "uuid": "^10.0.0"
+    "uuid": "^10.0.0",
+    "ms": "~2.1.3",
+    "@types/ms": "~2.1.0"
   },
   "devDependencies": {
     "@hz-9/eslint-config-airbnb-ts": "~0.6.0",