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

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/plugins/axios.d.ts

@@ -0,0 +1,2 @@
+import axios from 'axios';
+export = axios;

package/dist/plugins/axios.js

@@ -0,0 +1,7 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const axios_1 = __importDefault(require("axios"));
+module.exports = axios_1.default;
+//# sourceMappingURL=axios.js.map

package/dist/plugins/dayjs.d.ts

@@ -0,0 +1,2 @@
+import dayjs from 'dayjs';
+export = dayjs;

package/dist/plugins/dayjs.js

@@ -0,0 +1,7 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const dayjs_1 = __importDefault(require("dayjs"));
+module.exports = dayjs_1.default;
+//# sourceMappingURL=dayjs.js.map

package/dist/plugins/fs-extra.d.ts

@@ -0,0 +1,2 @@
+import fse from 'fs-extra';
+export = fse;

package/dist/plugins/fs-extra.js

@@ -0,0 +1,7 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const fs_extra_1 = __importDefault(require("fs-extra"));
+module.exports = fs_extra_1.default;
+//# sourceMappingURL=fs-extra.js.map

package/dist/plugins/ms.d.ts

@@ -0,0 +1,2 @@
+import ms from 'ms';
+export = ms;

package/dist/plugins/ms.js

@@ -0,0 +1,7 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const ms_1 = __importDefault(require("ms"));
+module.exports = ms_1.default;
+//# sourceMappingURL=ms.js.map

package/dist/plugins/nanoid.d.ts

@@ -1 +1,2 @@
-export { nanoid } from 'nanoid';
+import { nanoid } from 'nanoid';
+export = nanoid;

package/dist/plugins/nanoid.js

@@ -1,6 +1,4 @@
 "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; } });
+const nanoid_1 = require("nanoid");
+module.exports = nanoid_1.nanoid;
 //# sourceMappingURL=nanoid.js.map

package/dist/plugins/pug.d.ts

@@ -0,0 +1,2 @@
+import pug from 'pug';
+export = pug;

package/dist/plugins/pug.js

@@ -0,0 +1,7 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const pug_1 = __importDefault(require("pug"));
+module.exports = pug_1.default;
+//# sourceMappingURL=pug.js.map

package/dist/plugins/type-fest.d.ts

@@ -0,0 +1 @@
+export * from 'type-fest';

package/dist/plugins/{index.js → type-fest.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);
-//# sourceMappingURL=index.js.map
+__exportStar(require("type-fest"), exports);
+//# sourceMappingURL=type-fest.js.map

package/dist/plugins/ua-parser-js.d.ts

@@ -0,0 +1,2 @@
+import UAParser from 'ua-parser-js';
+export = UAParser;

package/dist/plugins/ua-parser-js.js

@@ -0,0 +1,7 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const ua_parser_js_1 = __importDefault(require("ua-parser-js"));
+module.exports = ua_parser_js_1.default;
+//# sourceMappingURL=ua-parser-js.js.map

package/dist/plugins/upath.d.ts

@@ -0,0 +1,2 @@
+import upath from 'upath';
+export = upath;

package/dist/plugins/upath.js

@@ -0,0 +1,7 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const upath_1 = __importDefault(require("upath"));
+module.exports = upath_1.default;
+//# sourceMappingURL=upath.js.map

package/dist/plugins/uuid.d.ts

@@ -0,0 +1,2 @@
+import * as uuid from 'uuid';
+export = uuid;

package/dist/plugins/uuid.js

@@ -0,0 +1,27 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+const uuid = __importStar(require("uuid"));
+module.exports = uuid;
+//# sourceMappingURL=uuid.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,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,5 +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/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/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/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