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

package/dist/all.d.ts

@@ -1,13 +1,17 @@
+/// <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 { 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
@@ -391,6 +395,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 +424,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 +485,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 +527,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 +651,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 +714,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 +769,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 +796,19 @@ 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 }
+/**
+ * 类型断言工具 - 判断不是 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 +849,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.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(),

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/{plugins → errors}/index.js

@@ -14,5 +14,5 @@ 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("./nanoid"), exports);
+__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

package/dist/interface/type-challenges.utils.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 类型断言工具 - 期望类型为 true
+ *
+ * @public
+ */
+export type Expect<T extends true> = T;
+/**
+ * 类型断言工具 - 期望值为 true
+ *
+ * @public
+ */
+export type ExpectTrue<T extends true> = T;
+/**
+ * 类型断言工具 - 期望值为 false
+ *
+ * @public
+ */
+export type ExpectFalse<T extends false> = T;
+/**
+ * 类型断言工具 - 判断是否为 true
+ *
+ * @public
+ */
+export type IsTrue<T extends true> = T;
+/**
+ * 类型断言工具 - 判断是否为 false
+ *
+ * @public
+ */
+export type IsFalse<T extends false> = T;
+/**
+ * 类型断言工具 - 判断两个类型不相等
+ *
+ * @public
+ */
+export type NotEqual<X, Y> = true extends Equal<X, Y> ? false : true;
+/**
+ * 类型断言工具 - 判断两个类型相等
+ *
+ * @public
+ */
+export type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+/**
+ * 类型断言工具 - 判断是否为 any 类型
+ *
+ * @public
+ */
+export type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+ * 类型断言工具 - 判断不是 any 类型
+ *
+ * @public
+ */
+export type NotAny<T> = true extends IsAny<T> ? false : true;
+/**
+ * 类型调试工具 - 展开类型定义
+ *
+ * @public
+ */
+export type Debug<T> = {
+    [K in keyof T]: T[K];
+};
+/**
+ * 类型合并工具 - 合并嵌套类型
+ *
+ * @public
+ */
+export type MergeInsertions<T> = T extends object ? {
+    [K in keyof T]: MergeInsertions<T[K]>;
+} : T;
+/**
+ * 类型断言工具 - 判断两个类型结构相似
+ *
+ * @public
+ */
+export type Alike<X, Y> = Equal<MergeInsertions<X>, MergeInsertions<Y>>;
+/**
+ * 类型断言工具 - 期望类型扩展自目标类型
+ *
+ * @public
+ */
+export type ExpectExtends<VALUE, EXPECTED> = EXPECTED extends VALUE ? true : false;
+/**
+ * 类型断言工具 - 验证函数参数类型
+ *
+ * @public
+ */
+export type ExpectValidArgs<FUNC extends (...args: any[]) => any, ARGS extends any[]> = ARGS extends Parameters<FUNC> ? true : false;
+/**
+ * 类型转换工具 - 联合类型转交叉类型
+ *
+ * @public
+ */
+export type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;

package/dist/interface/type-challenges.utils.js

@@ -0,0 +1,4 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=type-challenges.utils.js.map

package/dist/test/integration/core/a5-factory.integration.spec.js

@@ -10,10 +10,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 /* eslint-disable @typescript-eslint/consistent-type-definitions */
-const core_1 = require("../../../core");
-const util_1 = require("../../../util");
 const node_console_1 = __importDefault(require("node:console"));
 const common_1 = require("@nestjs/common");
+const core_1 = require("../../../core");
+const util_1 = require("../../../util");
 describe('A5Factory', () => {
     describe('create', () => {
         describe('printLogo', () => {

package/dist/util/a5.util.d.ts

@@ -1,3 +1,6 @@
+/// <reference types="node" />
+import { IncomingHttpHeaders } from 'node:http';
+import { FastifyRequest } from '../interface/http';
 /**
  *
  * @public
@@ -24,4 +27,10 @@ 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;
+    };
 }

package/dist/util/a5.util.js

@@ -36,6 +36,19 @@ class A5Util {
             ? (0, upath_1.normalize)(sourcePath)
             : (0, upath_1.resolve)((0, upath_1.normalize)(basePath), (0, upath_1.normalize)(sourcePath));
     }
+    static getReqIdFromRequest(req) {
+        return req.id;
+    }
+    static getReqHeadersFromRequest(req) {
+        // TODO 支持 HTTP2
+        return req.headers;
+    }
+    static getReqIdAndHeadersFromRequest(req) {
+        return {
+            reqId: req.id,
+            reqHeaders: req.headers,
+        };
+    }
 }
 exports.A5Util = A5Util;
 //# sourceMappingURL=a5.util.js.map

package/dist/util/index.d.ts

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

package/dist/util/index.js

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

package/dist/util/load-package.util.d.ts

@@ -10,13 +10,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 - 包名

package/dist/util/load-package.util.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LoadPackageUtil = void 0;
+const errors_1 = require("../errors");
 const a5_util_1 = require("./a5.util");
 // TODO 当前文件，并未编写单元测试
 /**
@@ -15,7 +16,7 @@ class LoadPackageUtil {
      * @returns 加载的包模块
      * @throws 当包加载失败时抛出错误
      */
-    static async loadPackage(packageName) {
+    static loadPackage(packageName) {
         try {
             // 使用 Dynimic_import 引入模块，仍会显示 ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING_FLAG 报错，
             // 使用 require 进行动态引入；
@@ -25,8 +26,10 @@ class LoadPackageUtil {
             return module;
         }
         catch (error) {
-            // TODO 优化报错显示
-            throw new Error(`Failed to load package "${packageName}": ${error instanceof Error ? error.message : String(error)}`);
+            // 抛出 A5LoadPackageError 错误
+            const cause = error instanceof Error ? error : undefined;
+            const message = error instanceof Error ? error.message : String(error);
+            throw new errors_1.A5LoadPackageError(packageName, `Failed to load package "${packageName}": ${message}`, cause);
         }
     }
     /**
@@ -34,9 +37,9 @@ class LoadPackageUtil {
      * @param packageName - 包名
      * @returns 加载的包模块，如果失败则返回 null
      */
-    static async loadPackageSafe(packageName) {
+    static loadPackageSafe(packageName) {
         try {
-            return await LoadPackageUtil.loadPackage(packageName);
+            return LoadPackageUtil.loadPackage(packageName);
         }
         catch {
             return null;
@@ -54,7 +57,7 @@ class LoadPackageUtil {
         let lastError = null;
         for (let i = 0; i <= retries; i += 1) {
             try {
-                return await LoadPackageUtil.loadPackage(packageName);
+                return LoadPackageUtil.loadPackage(packageName);
             }
             catch (error) {
                 lastError = error instanceof Error ? error : new Error(String(error));
@@ -64,7 +67,8 @@ class LoadPackageUtil {
                 }
             }
         }
-        throw lastError || new Error(`Failed to load package "${packageName}" after ${retries + 1} attempts`);
+        throw (lastError ||
+            new errors_1.A5LoadPackageError(packageName, `Failed to load package "${packageName}" after ${retries + 1} attempts`));
     }
 }
 exports.LoadPackageUtil = LoadPackageUtil;

package/dist/util/random.util.d.ts

@@ -0,0 +1,27 @@
+import { V4Options, V7Options } from 'uuid';
+/**
+ * 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;
+}

package/dist/util/random.util.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A5RandomUtil = void 0;
+const nanoid_1 = require("nanoid");
+const uuid_1 = require("uuid");
+/**
+ * A5 随机工具类
+ *
+ * 提供生成随机值和 UUID 的静态方法
+ *
+ * @public
+ */
+class A5RandomUtil {
+    static nanoid(size) {
+        return (0, nanoid_1.nanoid)(size);
+    }
+    static uuidV4(options) {
+        return (0, uuid_1.v4)(options);
+    }
+    static uuidV7(options) {
+        return (0, uuid_1.v7)(options);
+    }
+    /**
+     * 生成指定位数的随机数字
+     *
+     * @param digits - 位数，默认 6
+     * @returns 随机数字字符串
+     */
+    static randomDigits(digits = 6) {
+        const min = 10 ** (digits - 1);
+        const max = 10 ** digits - 1;
+        const randomNum = Math.floor(Math.random() * (max - min + 1)) + min;
+        return randomNum.toString();
+    }
+    /**
+     * 生成指定长度的随机字符串（a-zA-Z0-9）
+     *
+     * @param length - 长度，默认 8
+     * @returns 随机字符串
+     */
+    static randomString(length = 8, chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789') {
+        return (0, nanoid_1.customAlphabet)(chars)(length);
+    }
+}
+exports.A5RandomUtil = A5RandomUtil;
+//# sourceMappingURL=random.util.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hz-9/a5-core",
-  "version": "0.2.0-alpha.5",
+  "version": "0.2.0-alpha.50",
   "description": "The core library for the `@hz-9/a5-*` series of repositories.",
   "keywords": [
     "nest",
@@ -38,31 +38,28 @@
   ],
   "dependencies": {
     "@nestjs/platform-fastify": "^10.0.0",
-    "fastify": "4.28.1",
     "@types/fs-extra": "~11.0.3",
     "@types/heft-jest": "~1.0.3",
-    "@types/lodash": "~4.17.4",
     "@types/node": "~20.3.1",
     "@types/pug": "~2.0.10",
-    "@types/uuid": "~9.0.8",
-    "@type-challenges/utils": "~0.1.1",
+    "@types/uuid": "^10.0.0",
     "axios": "~1.7.2",
     "body-parser": "~1.20.2",
     "dayjs": "~1.11.10",
+    "fastify": "4.28.1",
     "fs-extra": "~11.1.1",
-    "lodash": "~4.17.21",
     "nanoid": "^3.3.7",
     "pug": "~3.0.3",
     "type-fest": "~4.20.0",
     "upath": "~2.0.1",
-    "ua-parser-js": "~1.0.38"
+    "ua-parser-js": "~1.0.38",
+    "uuid": "^10.0.0"
   },
   "devDependencies": {
     "@hz-9/eslint-config-airbnb-ts": "~0.6.0",
     "@nestjs/cli": "^10.0.0",
     "@nestjs/common": "^10.0.0",
     "@nestjs/core": "^10.0.0",
-    "@nestjs/swagger": "~7.1.14",
     "@nestjs/testing": "^10.0.0",
     "@rushstack/heft": "0.66.1",
     "@types/body-parser": "~1.19.5",

package/dist/plugins/index.d.ts

@@ -1 +0,0 @@
-export * from './nanoid';

package/dist/plugins/nanoid.d.ts

@@ -1 +0,0 @@
-export { nanoid } from 'nanoid';

package/dist/plugins/nanoid.js

@@ -1,6 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.nanoid = void 0;
-var nanoid_1 = require("nanoid");
-Object.defineProperty(exports, "nanoid", { enumerable: true, get: function () { return nanoid_1.nanoid; } });
-//# sourceMappingURL=nanoid.js.map