@hz-9/a5-core 0.2.0-alpha.3 → 0.2.0-alpha.31

package/dist/all.d.ts

@@ -391,6 +391,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
  *
@@ -435,6 +456,13 @@ export declare class A5Util {
     static tryWithAbsolutePath(sourcePath: string, basePath: string): string;
 }
 
+/**
+ * 类型断言工具 - 判断两个类型结构相似
+ *
+ * @public
+ */
+export declare type Alike<X, Y> = Equal<MergeInsertions<X>, MergeInsertions<Y>>;
+
 /**
  * @public
  */
@@ -462,16 +490,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 +614,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 +677,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 +732,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
@@ -622,6 +761,20 @@ export declare const MODULE_CONFIG_PATH_A5_LOG: <T extends string>(str: T) => `A
 
 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 +814,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/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,5 +1,6 @@
 export * from './const';
 export * from './core';
+export * from './errors';
 export * from './interface';
 export * from './module';
 export * from './middleware';

package/dist/index.js

@@ -16,6 +16,7 @@ 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);

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hz-9/a5-core",
-  "version": "0.2.0-alpha.3",
+  "version": "0.2.0-alpha.31",
   "description": "The core library for the `@hz-9/a5-*` series of repositories.",
   "keywords": [
     "nest",
@@ -45,7 +45,6 @@
     "@types/node": "~20.3.1",
     "@types/pug": "~2.0.10",
     "@types/uuid": "~9.0.8",
-    "@type-challenges/utils": "~0.1.1",
     "axios": "~1.7.2",
     "body-parser": "~1.20.2",
     "dayjs": "~1.11.10",
@@ -62,7 +61,6 @@
     "@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",