@hz-9/a5-core 0.2.0-alpha.6 → 0.2.0-alpha.60

package/dist/all.d.ts

@@ -1,13 +1,18 @@
+/// <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 { nanoid } from 'nanoid';
+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
@@ -118,7 +123,7 @@ export declare class A5Application {
      *  在正常获取 IP 与端口后，可通过此函数输出日志信息。
      *
      */
-    printAddress(): Promise<void>;
+    printAddress(options?: A5AppPrintAddressOptions): Promise<void>;
     /**
      *
      * @public
@@ -193,6 +198,27 @@ export declare interface A5AppListenOptions {
  */
 export declare type A5AppOptions = Required<A5AppConstructorOptions>;
 
+/**
+ * @public
+ *
+ *  A5App 打印地址项
+ *
+ */
+export declare interface A5AppPrintAddressItem {
+    name: string;
+    path: string;
+}
+
+/**
+ * @public
+ *
+ *  A5App 打印地址选项
+ *
+ */
+export declare interface A5AppPrintAddressOptions {
+    address?: A5AppPrintAddressItem[];
+}
+
 /**
  * @public
  */
@@ -391,6 +417,27 @@ declare interface A5FormatMessageOptions {
  */
 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
  *
@@ -399,6 +446,33 @@ export declare type A5GlobalProvideToken = `Global.A5.${string}`;
  */
 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
  *
@@ -433,8 +507,21 @@ export declare class A5Util {
      * @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
  */
@@ -462,16 +549,67 @@ export declare class ColorUtil {
     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
  */
@@ -535,6 +673,57 @@ export declare abstract class IA5ConfigModule {
 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;
+
 /**
  * 包加载工具类
  * 用于统一处理可选依赖的动态导入
@@ -547,13 +736,13 @@ export declare class LoadPackageUtil {
      * @returns 加载的包模块
      * @throws 当包加载失败时抛出错误
      */
-    static loadPackage<T = unknown>(packageName: string): Promise<T>;
+    static loadPackage<T = unknown>(packageName: string): T;
     /**
      * 安全地动态加载包
      * @param packageName - 包名
      * @returns 加载的包模块，如果失败则返回 null
      */
-    static loadPackageSafe<T = unknown>(packageName: string): Promise<T | null>;
+    static loadPackageSafe<T = unknown>(packageName: string): T | null;
     /**
      * 带重试的动态加载包
      * @param packageName - 包名
@@ -602,6 +791,15 @@ export declare class LogoUtil {
  */
 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
@@ -620,7 +818,67 @@ export declare const MODULE_CONFIG_PATH_A5_CONFIG: <T extends string>(str: T) =>
  */
 export declare const MODULE_CONFIG_PATH_A5_LOG: <T extends string>(str: T) => `A5.log.${T}`;
 
-export { nanoid }
+/**
+ * @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
@@ -661,6 +919,13 @@ export declare class RunEnvUtil {
     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
  */

package/dist/core/a5-application.d.ts

@@ -63,6 +63,25 @@ export interface A5AppListenOptions {
      */
     readonly tryTimes?: number;
 }
+/**
+ * @public
+ *
+ *  A5App 打印地址项
+ *
+ */
+export interface A5AppPrintAddressItem {
+    name: string;
+    path: string;
+}
+/**
+ * @public
+ *
+ *  A5App 打印地址选项
+ *
+ */
+export interface A5AppPrintAddressOptions {
+    address?: A5AppPrintAddressItem[];
+}
 /**
  * @public
  *
@@ -126,7 +145,7 @@ export declare class A5Application {
      *  在正常获取 IP 与端口后，可通过此函数输出日志信息。
      *
      */
-    printAddress(): Promise<void>;
+    printAddress(options?: A5AppPrintAddressOptions): Promise<void>;
     /**
      *
      * @public

package/dist/core/a5-application.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.A5Application = void 0;
 const common_1 = require("@nestjs/common");
 const core_1 = require("@nestjs/core");
-const nanoid_1 = require("nanoid");
 const index_1 = require("../const/index");
 const log_1 = require("../module/log");
 const util_1 = require("../util");
@@ -75,7 +74,7 @@ class A5Application {
          * setExtraUrl 及 getUrls 函数用于保存数据的数组
          */
         this.extraUrls = [];
-        this.instanceId = (0, nanoid_1.nanoid)();
+        this.instanceId = util_1.A5RandomUtil.nanoid();
         this.nestApp = nestApp;
         this.options = {
             logger: options.logger ?? this._getA5LoggerService(),
@@ -195,7 +194,7 @@ class A5Application {
      *  在正常获取 IP 与端口后，可通过此函数输出日志信息。
      *
      */
-    async printAddress() {
+    async printAddress(options) {
         const urls = await this.getUrls();
         const timeDiffWithColor = util_1.ColorUtil.yellowBright(`${Date.now() - +process.env.A5_INIT_TIME} ms`);
         const urlMaxLength = Math.max(...urls.map((i) => i.length));
@@ -208,6 +207,12 @@ class A5Application {
                 this.logger.log(`                      ${urlWithColor}`);
             }
         });
+        if (Array.isArray(options?.address)) {
+            options?.address.forEach((address) => {
+                const urlWithColor = util_1.ColorUtil.cyan(`${urls[0] ?? ''}${address.path}`);
+                this.logger.log(`${address.name.padEnd(21, ' ')} ${urlWithColor}`);
+            });
+        }
     }
     /**
      *

package/dist/core/a5-console-logger.js

@@ -11,6 +11,9 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 var A5ConsoleLogger_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.A5ConsoleLogger = exports.DEFAULT_LOG_LEVELS = void 0;
@@ -20,19 +23,11 @@ const optional_decorator_1 = require("@nestjs/common/decorators/core/optional.de
 const is_log_level_enabled_util_1 = require("@nestjs/common/services/utils/is-log-level-enabled.util");
 const cli_colors_util_1 = require("@nestjs/common/utils/cli-colors.util");
 const shared_utils_1 = require("@nestjs/common/utils/shared.utils");
+const dayjs_1 = __importDefault(require("dayjs"));
 /**
  * @public
  */
 exports.DEFAULT_LOG_LEVELS = ['log', 'error', 'warn', 'debug', 'verbose', 'fatal'];
-const dateTimeFormatter = new Intl.DateTimeFormat(undefined, {
-    year: 'numeric',
-    month: '2-digit',
-    day: '2-digit',
-    hour: 'numeric',
-    minute: 'numeric',
-    second: 'numeric',
-    fractionalSecondDigits: 3,
-});
 /**
  * @public
  */
@@ -185,7 +180,7 @@ let A5ConsoleLogger = A5ConsoleLogger_1 = class A5ConsoleLogger {
         return logLevel.toUpperCase().padStart(7, ' ');
     }
     formatTimestamp(dateMilliseconds) {
-        return dateTimeFormatter.format(dateMilliseconds).replace(/ /g, 'T').replace(/\//g, '-');
+        return (0, dayjs_1.default)(dateMilliseconds).format('YYYY-MM-DDTHH:mm:ss.SSS');
     }
     formatContext(context) {
         if (context.length === 0)

package/dist/core/a5-factory.js

@@ -35,7 +35,10 @@ class A5FactoryStatic {
         const nestOptions = {
             bufferLogs: true,
         };
-        const nestApplication = await this.nestFactoryStatic.create(module, new platform_fastify_1.FastifyAdapter(), nestOptions);
+        const nestApplication = await this.nestFactoryStatic.create(module, new platform_fastify_1.FastifyAdapter({
+            // 生成 Req Id
+            genReqId: (req) => util_1.A5RandomUtil.uuidV7(),
+        }), nestOptions);
         // this.initBodyParser(nestApplication, options)
         const app = new a5_application_1.A5Application(nestApplication);
         await app.init();

package/dist/errors/a5-load-package.error.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A5 加载包错误
+ * 当动态加载可选依赖包失败时抛出此错误
+ * @public
+ */
+export declare class A5LoadPackageError extends Error {
+    /**
+     * 错误名称
+     */
+    readonly name: string;
+    /**
+     * 尝试加载的包名
+     */
+    readonly packageName: string;
+    /**
+     * 原始错误（如果有）
+     */
+    readonly cause?: Error;
+    constructor(packageName: string, message?: string, cause?: Error);
+}

package/dist/errors/a5-load-package.error.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A5LoadPackageError = void 0;
+/**
+ * A5 加载包错误
+ * 当动态加载可选依赖包失败时抛出此错误
+ * @public
+ */
+class A5LoadPackageError extends Error {
+    constructor(packageName, message, cause) {
+        super(message || `Failed to load package: ${packageName}`);
+        /**
+         * 错误名称
+         */
+        this.name = 'A5LoadPackageError';
+        this.packageName = packageName;
+        this.cause = cause;
+        // 设置原型链，确保 instanceof 正常工作
+        Object.setPrototypeOf(this, A5LoadPackageError.prototype);
+    }
+}
+exports.A5LoadPackageError = A5LoadPackageError;
+//# sourceMappingURL=a5-load-package.error.js.map

package/dist/errors/index.d.ts

@@ -0,0 +1 @@
+export * from './a5-load-package.error';

package/dist/errors/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./a5-load-package.error"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export * from './const';
 export * from './core';
+export * from './errors';
 export * from './interface';
 export * from './module';
 export * from './middleware';
-export * from './plugins';
 export * from './util';

package/dist/index.js

@@ -16,9 +16,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./const"), exports);
 __exportStar(require("./core"), exports);
+__exportStar(require("./errors"), exports);
 __exportStar(require("./interface"), exports);
 __exportStar(require("./module"), exports);
 __exportStar(require("./middleware"), exports);
-__exportStar(require("./plugins"), exports);
 __exportStar(require("./util"), exports);
 //# sourceMappingURL=index.js.map

package/dist/interface/index.d.ts

@@ -1,3 +1,5 @@
 export * from './base';
 export * from './http';
+export * from './json';
 export * from './provide-token';
+export * from './type-challenges.utils';

package/dist/interface/index.js

@@ -16,5 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./base"), exports);
 __exportStar(require("./http"), exports);
+__exportStar(require("./json"), exports);
 __exportStar(require("./provide-token"), exports);
+__exportStar(require("./type-challenges.utils"), exports);
 //# sourceMappingURL=index.js.map

package/dist/interface/json.d.ts

@@ -0,0 +1,27 @@
+/**
+ * JSON 值类型
+ *
+ * 表示所有合法的 JSON 值类型，包括基础类型、对象和数组
+ *
+ * @public
+ */
+export type JsonValue = string | number | boolean | null | JsonObject | JsonArray;
+/**
+ * JSON 对象类型
+ *
+ * 表示 JSON 对象结构，键为字符串，值为任意 JSON 值
+ *
+ * @public
+ */
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+/**
+ * JSON 数组类型
+ *
+ * 表示 JSON 数组结构，元素为任意 JSON 值
+ *
+ * @public
+ */
+export interface JsonArray extends Array<JsonValue> {
+}

package/dist/interface/json.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=json.js.map