@hz-9/a5-core 0.2.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Chen Zhen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @hz-9/a5-core
+
+The core library for the `@hz-9/a5-*` series of repositories. It is used to bootstrap application services, encapsulate `NestApplication` and `NestFactory`, and create common classes for `@hz-9/a5-*`.
+
+![NPM Version][npm-version-url] ![NPM License][npm-license-url] ![NPM Downloads][npm-downloads-url] ![Types][types-url]
+<br /> ![Node Version][node-version-url] ![Last Commit][last-commit-url]
+
+[npm-version-url]: https://badgen.net/npm/v/@hz-9/a5-core
+[npm-license-url]: https://badgen.net/npm/license/@hz-9/a5-core
+[npm-downloads-url]: https://badgen.net/npm/dt/@hz-9/a5-core
+[types-url]: https://badgen.net/npm/types/@hz-9/a5-core
+[node-version-url]: https://badgen.net/npm/node/@hz-9/a5-core
+[last-commit-url]: https://badgen.net/github/last-commit/hz-9/a5
+
+[Document](https://hz-9.github.io/a5/guide/a5-core/) | [文档](https://hz-9.github.io/a5/zh-CN/guide/a5-core/)

package/dist/all.d.ts

@@ -0,0 +1,676 @@
+import { FastifyReply as FastifyReply_2 } from 'fastify';
+import { FastifyRequest as FastifyRequest_2 } from 'fastify';
+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 { nanoid } from 'nanoid';
+import { NestFactoryStatic } from '@nestjs/core/nest-factory';
+import { NestFastifyApplication } from '@nestjs/platform-fastify';
+import { NestMiddleware } from '@nestjs/common';
+
+/**
+ * @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}`;
+
+/**
+ * @public
+ *
+ * `A5` 配置项路径。
+ *
+ */
+export declare type A5ModuleConfigPath = `A5.${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;
+}
+
+/**
+ * @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 const DEFAULT_LOG_LEVELS: LogLevel[];
+
+/**
+ * @public
+ */
+export declare const ERROR_WELCOME_MSG: string;
+
+/**
+ * @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 {
+}
+
+/**
+ * 包加载工具类
+ * 用于统一处理可选依赖的动态导入
+ * @public
+ */
+export declare class LoadPackageUtil {
+    /**
+     * 动态加载包
+     * @param packageName - 包名
+     * @returns 加载的包模块
+     * @throws 当包加载失败时抛出错误
+     */
+    static loadPackage<T = unknown>(packageName: string): Promise<T>;
+    /**
+     * 安全地动态加载包
+     * @param packageName - 包名
+     * @returns 加载的包模块，如果失败则返回 null
+     */
+    static loadPackageSafe<T = unknown>(packageName: string): Promise<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
+ *
+ *   `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}`;
+
+export { nanoid }
+
+/**
+ * @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 Writable<T> = {
+    -readonly [P in keyof T]: T[P];
+};
+
+/**
+ * @public
+ */
+export declare type WritableRequired<T> = Writable<Required<T>>;
+
+export { }