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

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

@@ -0,0 +1,27 @@
+/**
+ *
+ * @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;
+}

package/dist/util/a5.util.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A5Util = void 0;
+const upath_1 = require("upath");
+/**
+ *
+ * @public
+ *
+ *  通用工具类
+ *
+ */
+class A5Util {
+    /**
+     *
+     * 睡眠。
+     *
+     * @param t - 时间。单位：毫秒
+     */
+    static async sleep(t) {
+        return new Promise((resolve) => {
+            setTimeout(resolve, t);
+        });
+    }
+    /**
+     * @public
+     *
+     *  如果不是绝对路径，则进行拼接
+     *
+     * @param sourcePath - 资源路径
+     * @param basePath - 基础路径
+     *
+     * @returns 资源路径的绝对路径。
+     */
+    static tryWithAbsolutePath(sourcePath, basePath) {
+        return (0, upath_1.isAbsolute)((0, upath_1.normalize)(sourcePath))
+            ? (0, upath_1.normalize)(sourcePath)
+            : (0, upath_1.resolve)((0, upath_1.normalize)(basePath), (0, upath_1.normalize)(sourcePath));
+    }
+}
+exports.A5Util = A5Util;
+//# sourceMappingURL=a5.util.js.map

package/dist/util/color.util.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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;
+}

package/dist/util/color.util.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ColorUtil = void 0;
+/**
+ * @public
+ */
+class ColorUtil {
+    static get isColorAllowed() {
+        return !('NO_COLOR' in process.env && (!!process.env.NO_COLOR || process.env.NO_COLOR === ''));
+    }
+    static bold(text) {
+        return ColorUtil.isColorAllowed ? `\x1B[1m${text}\x1B[0m` : text;
+    }
+    static red(text) {
+        return ColorUtil.isColorAllowed ? `\x1B[31m${text}\x1B[39m` : text;
+    }
+    static green(text) {
+        return ColorUtil.isColorAllowed ? `\x1B[32m${text}\x1B[39m` : text;
+    }
+    static yellow(text) {
+        return ColorUtil.isColorAllowed ? `\x1B[33m${text}\x1B[39m` : text;
+    }
+    static blue(text) {
+        return ColorUtil.isColorAllowed ? `\x1B[34m${text}\x1B[39m` : text;
+    }
+    static magenta(text) {
+        return ColorUtil.isColorAllowed ? `\x1B[35m${text}\x1B[39m` : text;
+    }
+    static cyan(text) {
+        return ColorUtil.isColorAllowed ? `\x1B[36m${text}\x1B[39m` : text;
+    }
+    static redBright(text) {
+        return ColorUtil.isColorAllowed ? `\x1B[91m${text}\x1B[39m` : text;
+    }
+    static greenBright(text) {
+        return ColorUtil.isColorAllowed ? `\x1B[92m${text}\x1B[39m` : text;
+    }
+    static yellowBright(text) {
+        return ColorUtil.isColorAllowed ? `\x1B[93m${text}\x1B[39m` : text;
+    }
+    static blueBright(text) {
+        return ColorUtil.isColorAllowed ? `\x1B[94m${text}\x1B[39m` : text;
+    }
+    static magentaBright(text) {
+        return ColorUtil.isColorAllowed ? `\x1B[95m${text}\x1B[39m` : text;
+    }
+    static cyanBright(text) {
+        return ColorUtil.isColorAllowed ? `\x1B[96m${text}\x1B[39m` : text;
+    }
+    /**
+     * 移除 ANSI 颜色代码
+     *
+     * @param text - text to clear
+     * @returns cleaned text
+     */
+    static clear(text) {
+        // eslint-disable-next-line no-control-regex
+        return text.replace(/\x1B\[[0-9;]*[A-Za-z]/g, '');
+    }
+}
+exports.ColorUtil = ColorUtil;
+//# sourceMappingURL=color.util.js.map

package/dist/util/index.d.ts

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

package/dist/util/index.js

@@ -0,0 +1,22 @@
+"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.util"), exports);
+__exportStar(require("./color.util"), exports);
+__exportStar(require("./load-package.util"), exports);
+__exportStar(require("./logo.util"), exports);
+__exportStar(require("./run-env.util"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,29 @@
+/**
+ * 包加载工具类
+ * 用于统一处理可选依赖的动态导入
+ * @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>;
+}

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

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoadPackageUtil = void 0;
+const a5_util_1 = require("./a5.util");
+// TODO 当前文件，并未编写单元测试
+/**
+ * 包加载工具类
+ * 用于统一处理可选依赖的动态导入
+ * @public
+ */
+class LoadPackageUtil {
+    /**
+     * 动态加载包
+     * @param packageName - 包名
+     * @returns 加载的包模块
+     * @throws 当包加载失败时抛出错误
+     */
+    static async loadPackage(packageName) {
+        try {
+            // 使用 Dynimic_import 引入模块，仍会显示 ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING_FLAG 报错，
+            // 使用 require 进行动态引入；
+            // const module = await import(packageName)
+            // eslint-disable-next-line global-require, import/no-dynamic-require
+            const module = require(packageName);
+            return module;
+        }
+        catch (error) {
+            // TODO 优化报错显示
+            throw new Error(`Failed to load package "${packageName}": ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * 安全地动态加载包
+     * @param packageName - 包名
+     * @returns 加载的包模块，如果失败则返回 null
+     */
+    static async loadPackageSafe(packageName) {
+        try {
+            return await LoadPackageUtil.loadPackage(packageName);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 带重试的动态加载包
+     * @param packageName - 包名
+     * @param retries - 重试次数，默认为 3
+     * @param retryDelay - 重试间隔（毫秒），默认为 100
+     * @returns 加载的包模块
+     * @throws 当所有重试都失败时抛出错误
+     */
+    static async loadPackageWithRetry(packageName, retries = 3, retryDelay = 100) {
+        let lastError = null;
+        for (let i = 0; i <= retries; i += 1) {
+            try {
+                return await LoadPackageUtil.loadPackage(packageName);
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                if (i < retries) {
+                    // 等待重试间隔
+                    await a5_util_1.A5Util.sleep(retryDelay);
+                }
+            }
+        }
+        throw lastError || new Error(`Failed to load package "${packageName}" after ${retries + 1} attempts`);
+    }
+}
+exports.LoadPackageUtil = LoadPackageUtil;
+//# sourceMappingURL=load-package.util.js.map

package/dist/util/logo.util.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 因 `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;
+}

package/dist/util/logo.util.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogoUtil = void 0;
+const node_console_1 = __importDefault(require("node:console"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const color_util_1 = require("./color.util");
+/**
+ * 因 `logo` 字符串特殊字符过多，不应直接存放当前文件。
+ *
+ * 进行 base64 编码并存放。
+ */
+/**
+ *
+ * @public
+ *
+ *  打印 Logo。
+ *
+ * logo 是在 http://patorjk.com/software/taag/#p=display&f=Big&t=a5 进行制作的。
+ *
+ */
+class LogoUtil {
+    /**
+     * Logo 的文本信息。
+     */
+    static get content() {
+        if (!this._content) {
+            this._content = node_fs_1.default.readFileSync(node_path_1.default.resolve(__dirname, '../../logo'), { encoding: 'utf8' });
+        }
+        return this._content;
+    }
+    /**
+     *
+     * 打印 A5 的 Logo 及版本信息。
+     *
+     * 使用 `console.log` 输出信息，不会写入到日志文件中。
+     *
+     * @param onlyLogo - 仅打印 Logo，不包含版本信息。可选。默认为 false
+     *
+     */
+    static print(onlyLogo = false) {
+        const logoLines = this.content.split('\n');
+        const packageInfo = node_fs_1.default.readFileSync(node_path_1.default.resolve(__dirname, '../../package.json'), { encoding: 'utf8' });
+        const { version } = JSON.parse(packageInfo);
+        if (!onlyLogo) {
+            // logoLines[1] = `${logoLines[1]}`
+            logoLines[logoLines.length - 2] = `${logoLines[logoLines.length - 2]} ${version}`;
+        }
+        node_console_1.default.log('');
+        node_console_1.default.log(color_util_1.ColorUtil.magenta(logoLines.join('\n')));
+        node_console_1.default.log('');
+    }
+}
+exports.LogoUtil = LogoUtil;
+LogoUtil._content = undefined;
+//# sourceMappingURL=logo.util.js.map

package/dist/util/run-env.util.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @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;
+}

package/dist/util/run-env.util.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunEnvUtil = void 0;
+/**
+ * @public
+ *
+ * 当前运行环境。
+ *
+ */
+class RunEnvUtil {
+    /**
+     * 是否处于开发环境.
+     */
+    static get isDev() {
+        /**
+         * 自动修正 NODE_ENV
+         */
+        if (!('NODE_ENV' in process.env))
+            process.env.NODE_ENV = 'development';
+        return process.env.NODE_ENV === 'development' || process.env.NODE_ENV === 'dev';
+    }
+    /**
+     * 是否处于生产环境.
+     */
+    static get isProd() {
+        return process.env.NODE_ENV === 'production' || process.env.NODE_ENV === 'prod';
+    }
+    /**
+     * 是否处于 PKG 打包后的环境。
+     */
+    static get inPKG() {
+        return 'pkg' in process && typeof process.pkg === 'object' && process.pkg !== null;
+    }
+    /**
+     * 是否处于 `VS Code` 的 `Debugger` 模式下。
+     */
+    static get inVSCodeDebugger() {
+        return 'VSCODE_INSPECTOR_OPTIONS' in process.env && process.env.VSCODE_INSPECTOR_OPTIONS !== undefined;
+    }
+    /**
+     * 是否处于 `Jest` 的单元测试环境下。
+     */
+    static get inJest() {
+        return 'JEST_WORKER_ID' in process.env && process.env.JEST_WORKER_ID !== undefined;
+    }
+}
+exports.RunEnvUtil = RunEnvUtil;
+//# sourceMappingURL=run-env.util.js.map

package/logo

@@ -0,0 +1,7 @@
+           _____ 
+     /\   | ____|
+    /  \  | |__  
+   / /\ \ |___ \ 
+  / ____ \ ___) |
+ /_/    \_\____/ 
+                 

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@hz-9/a5-core",
+  "version": "0.2.0-alpha.1",
+  "description": "The core library for the `@hz-9/a5-*` series of repositories.",
+  "keywords": [
+    "nest",
+    "a5",
+    "a5-core"
+  ],
+  "homepage": "https://hz-9.github.io/a5/guide/a5-core",
+  "bugs": {
+    "url": "https://github.com/hz-9/a5/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hz-9/a5.git",
+    "directory": "library/core"
+  },
+  "license": "MIT",
+  "author": "Chen Zhen <heavenzhen999@163.com>",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./*": {
+      "require": "./dist/*.js",
+      "types": "./dist/*.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.{d.ts,js}",
+    "CHANGELOG.md",
+    "public",
+    "logo"
+  ],
+  "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",
+    "axios": "~1.7.2",
+    "body-parser": "~1.20.2",
+    "dayjs": "~1.11.10",
+    "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"
+  },
+  "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",
+    "@types/supertest": "~6.0.2",
+    "@types/ua-parser-js": "~0.7.39",
+    "eslint": "^8.2.0",
+    "reflect-metadata": "^0.1.13",
+    "rxjs": "^7.8.1",
+    "typescript": ">=5.0.0 <5.4.0",
+    "supertest": "~7.0.0",
+    "@hz-9/heft-nest-rig": "0.1.2"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0",
+    "@nestjs/core": "^10.0.0",
+    "reflect-metadata": "^0.1.13",
+    "rxjs": "^7.8.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "heft test-all --clean",
+    "build:sync": "npm run build && node ./.utils/repair.js && node ./.utils/sync-dist.js",
+    "lint": "heft lint",
+    "test": "heft test --clean",
+    "test:watch": "heft test-watch",
+    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
+    "test:e2e": "jest --config ./test/jest-e2e.json"
+  }
+}