@aitianyu.cn/types 0.1.2 → 0.1.3

package/README.md

@@ -0,0 +1,44 @@
+# @aitianyu.cn/types
+
+A comprehensive utility library providing base types, helper functions, and security utilities for the aitianyu ecosystem. Supports both Node.js and browser environments.
+
+为 aitianyu 生态系统提供基础类型、帮助函数和安全工具的综合工具库，同时支持 Node.js 和浏览器运行环境。
+
+---
+
+**[English Documentation](doc/en/README.md)** | **[中文文档](doc/zh/README.md)**
+
+---
+
+## Quick Start / 快速开始
+
+```bash
+npm install @aitianyu.cn/types
+```
+
+```typescript
+import { guid, Log, StringHelper, TOTP, Base32, ObjectHelper } from "@aitianyu.cn/types";
+
+// Generate a UUID / 生成 UUID
+const id = guid();
+
+// Format a string / 格式化字符串
+const msg = StringHelper.format("Hello, {0}!", "world");
+
+// Log a message / 记录日志
+Log.info("Application started");
+
+// Generate a TOTP secret / 生成 TOTP 密钥
+const secret = TOTP.generate();
+```
+
+## Features / 功能特性
+
+- **Core Utilities / 核心工具** — Logging, environment detection, type conversion, error handling / 日志、运行环境检测、类型转换、错误处理
+- **Object Helpers / 对象帮助工具** — Deep clone, compare, string formatting, array and byte operations / 深度克隆、比较、字符串格式化、数组与字节操作
+- **Security / 安全模块** — TOTP, Base32, GUID/UUID, SHA hashing, RSA encryption, QR code generation / TOTP、Base32、GUID/UUID、SHA 哈希、RSA 加密、二维码生成
+- **Type Definitions / 类型定义** — Common interfaces, generic types, area codes, path utilities / 通用接口、泛型类型、区域码、路径工具
+
+## License
+
+ISC © aitianyu.cn

package/dist/lib/coding/Error.js

@@ -4,10 +4,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PathDirAndFileConvertInvaild = exports.PathDirectoryValidationFailException = exports.PathProcessorSourceLostException = void 0;
 const Exception_1 = require("../types/Exception");
 /**
- * Source lost exception of Path Processor.
- * Exception will be thrown if the path is file but the file field is not specified
+ * Thrown when a Path instance is typed as "file" but no file name has been provided.
+ * 当 Path 实例的类型为 "file" 但未指定文件名时抛出此异常。
  */
 class PathProcessorSourceLostException extends Exception_1.Exception {
+    /**
+     * @param msg optional additional message / 可选的附加信息
+     */
     constructor(msg) {
         super(msg);
     }
@@ -17,10 +20,13 @@ class PathProcessorSourceLostException extends Exception_1.Exception {
 }
 exports.PathProcessorSourceLostException = PathProcessorSourceLostException;
 /**
- * Path directory name is not valid.
- * Exception will be thrown if the path name has the invalid char
+ * Thrown when a path segment contains characters that are not valid in a directory name.
+ * 当路径段中包含目录名非法字符时抛出此异常。
  */
 class PathDirectoryValidationFailException extends Exception_1.Exception {
+    /**
+     * @param msg the invalid directory name / 非法的目录名
+     */
     constructor(msg) {
         super(msg);
     }
@@ -30,10 +36,14 @@ class PathDirectoryValidationFailException extends Exception_1.Exception {
 }
 exports.PathDirectoryValidationFailException = PathDirectoryValidationFailException;
 /**
- * Path is file or directory but target type is not.
- * Exception will be thrown if the path is file(directory) but try to convert to directory(file)
+ * Thrown when attempting to treat a file path as a directory path or vice versa.
+ * 当尝试将文件路径当作目录路径（或反之）进行转换时抛出此异常。
  */
 class PathDirAndFileConvertInvaild extends Exception_1.Exception {
+    /**
+     * @param path the path string that caused the conflict / 引发冲突的路径字符串
+     * @param type the actual type of the path / 路径的实际类型
+     */
     constructor(path, type) {
         super(`${path} 为 ${type === "directory" ? "目录" : "文件"}`);
     }

package/dist/lib/coding/Path.js

@@ -94,16 +94,27 @@ function _parsePathFromString(src) {
     }
     return path;
 }
-/** Path */
+/**
+ * Represents a file system path with explicit type (directory or file).
+ * Supports construction from a string, an array of segments, or a combination.
+ * Throws validation exceptions for invalid segment characters or type mismatches.
+ *
+ * 表示具有明确类型（目录或文件）的文件系统路径。
+ * 支持从字符串、目录段数组或两者组合构建实例。
+ * 遇到非法字符或类型不匹配时会抛出校验异常。
+ */
 class Path extends PathBase_1.PathBase {
+    /** Internal path type indicator. / 内部路径类型标识。 */
     _type;
+    /** The file name component, present only when type is "file". / 文件名组件，仅在类型为 "file" 时存在。 */
     _file;
     /**
-     * Create a new Path instance
+     * Create a new Path instance.
+     * 创建一个新的 Path 实例。
      *
-     * @param dirs the directory names
-     * @param type indicate which type the Path is
-     * @param file the file name if the type is file
+     * @param dirs directory segments as an array or a full path string / 目录段数组或完整路径字符串
+     * @param type explicit target type; inferred from string if omitted / 显式目标类型，省略时从字符串推断
+     * @param file explicit file name when type is "file" / 类型为 "file" 时指定文件名
      */
     constructor(dirs, type, file) {
         super();
@@ -125,9 +136,13 @@ class Path extends PathBase_1.PathBase {
         this._file = actFile;
     }
     /**
-     * Convert the path to a string
+     * Convert this path to its string representation.
+     * Throws PathProcessorSourceLostException if type is "file" but no file name is set.
      *
-     * @returns return the string
+     * 将路径转换为字符串表示形式。
+     * 若类型为 "file" 但未设置文件名，则抛出 PathProcessorSourceLostException。
+     *
+     * @returns the formatted path string / 格式化后的路径字符串
      */
     toString() {
         if (this.getType() === "file" && !!!this.getFile()) {
@@ -156,26 +171,29 @@ class Path extends PathBase_1.PathBase {
         return dirs.join("/");
     }
     /**
-     * Set the target type
+     * Set the target type of this path instance.
+     * 设置当前路径实例的目标类型。
      *
-     * @param type new type
+     * @param type the new path type / 新路径类型
      */
     setType(type) {
         this._type = type;
     }
     /**
-     * Get the path type of current instance
+     * Get the target type of this path instance.
+     * 获取当前路径实例的目标类型。
      *
-     * @returns return the path type
+     * @returns the path type / 路径类型
      */
     getType() {
         return this._type;
     }
     /**
-     * Set the path file name
+     * Set a new file name for this path.
+     * 设置当前路径的新文件名。
      *
-     * @param file the new file name
-     * @returns return the old file name
+     * @param file the new file name / 新文件名
+     * @returns the previous file name, or undefined if none was set / 之前的文件名，未设置时返回 undefined
      */
     setFile(file) {
         const oldFile = this._file;
@@ -183,25 +201,28 @@ class Path extends PathBase_1.PathBase {
         return oldFile;
     }
     /**
-     * Get the file name of current instance
+     * Get the file name component of this path.
+     * 获取当前路径的文件名组件。
      *
-     * @returns return the file name
+     * @returns the file name, or undefined if this is a directory path / 文件名，若为目录路径则返回 undefined
      */
     getFile() {
         return this._file;
     }
     /**
-     * IComparable impl to get a string what equals to current instance
+     * IComparable implementation — returns the string form for equality comparison.
+     * IComparable 实现——返回用于相等性比较的字符串形式。
      *
-     * @returns return the string
+     * @returns the comparable string / 可比较字符串
      */
     getString() {
         return this.toString();
     }
     /**
-     * Get a hash code of current instance
+     * IComparable implementation — returns 0 as the hash code.
+     * IComparable 实现——返回 0 作为哈希码。
      *
-     * @returns always return 0
+     * @returns always 0 / 始终返回 0
      */
     getHashCode() {
         return 0;

package/dist/lib/core/Environment.js

@@ -2,7 +2,21 @@
 /** @format */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Environment = void 0;
+/**
+ * Runtime environment detection utility.
+ * Identifies whether the current execution context is Node.js or a browser.
+ *
+ * 运行时环境检测工具类。
+ * 用于识别当前执行上下文是 Node.js 还是浏览器环境。
+ */
 class Environment {
+    /**
+     * Detect the current runtime environment.
+     * 检测当前运行时环境。
+     *
+     * @returns "node" when running in Node.js, "browser" otherwise
+     *          在 Node.js 中运行时返回 "node"，否则返回 "browser"
+     */
     static runtimeEnv() {
         const isNode = !!(typeof process !== "undefined" && process.versions && process.versions.node);
         return isNode ? "node" : "browser";

package/dist/lib/core/Errors.js

@@ -3,8 +3,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ObjectDiffMergeFailedException = exports.ObjectDiffApplyInvalidStatusException = exports.ObjectMergeStatusCheckFailedException = exports.ObjectCloneFunctionNotSupportException = exports.ArgumentNullOrEmptyException = void 0;
 const Exception_1 = require("../types/Exception");
-/** Argument null exception */
+/**
+ * Thrown when a required argument is null or an empty string.
+ * 当必填参数为 null 或空字符串时抛出。
+ */
 class ArgumentNullOrEmptyException extends Exception_1.Exception {
+    /**
+     * @param msg the name of the offending argument / 出错的参数名称
+     */
     constructor(msg) {
         super(msg);
     }
@@ -14,9 +20,11 @@ class ArgumentNullOrEmptyException extends Exception_1.Exception {
 }
 exports.ArgumentNullOrEmptyException = ArgumentNullOrEmptyException;
 /**
- * Object Clone:
- * Function type is not supported.
- * Exception will be thrown if try to clone a function type object
+ * Thrown when attempting to deep-clone an object that contains a function value.
+ * Function types are not supported by the clone utility.
+ *
+ * 当尝试深度克隆包含函数值的对象时抛出。
+ * 克隆工具不支持 function 类型。
  */
 class ObjectCloneFunctionNotSupportException extends Exception_1.Exception {
     constructor() {
@@ -28,13 +36,18 @@ class ObjectCloneFunctionNotSupportException extends Exception_1.Exception {
 }
 exports.ObjectCloneFunctionNotSupportException = ObjectCloneFunctionNotSupportException;
 /**
- * Object Clone:
- * Object different status could not be matched.
- * Exception will be thrown if the object diff could not to be merged
+ * Thrown when the expected state of an object diff entry does not match
+ * the actual current state during a merge operation.
+ *
+ * 在合并操作中，对象差异条目的预期状态与当前实际状态不匹配时抛出。
  */
 class ObjectMergeStatusCheckFailedException extends Exception_1.Exception {
     status;
     path;
+    /**
+     * @param path the diff path where the mismatch occurred / 发生不匹配的差异路径
+     * @param status the type of change that failed verification / 校验失败的变更类型
+     */
     constructor(path, status) {
         super();
         this.path = path;
@@ -46,12 +59,16 @@ class ObjectMergeStatusCheckFailedException extends Exception_1.Exception {
 }
 exports.ObjectMergeStatusCheckFailedException = ObjectMergeStatusCheckFailedException;
 /**
- * Object Clone:
- * Object different status could not be applied.
- * Exception will be thrown if the object diff could not to be applied
+ * Thrown when a diff entry cannot be applied because the current value
+ * is in an unexpected state (e.g., a value that should not exist already does).
+ *
+ * 当差异条目因当前值处于意外状态（如不应存在的值已存在）而无法应用时抛出。
  */
 class ObjectDiffApplyInvalidStatusException extends Exception_1.Exception {
     value;
+    /**
+     * @param value the value that is in an invalid state / 处于无效状态的值
+     */
     constructor(value) {
         super();
         this.value = value;
@@ -69,12 +86,16 @@ class ObjectDiffApplyInvalidStatusException extends Exception_1.Exception {
 }
 exports.ObjectDiffApplyInvalidStatusException = ObjectDiffApplyInvalidStatusException;
 /**
- * Object Clone:
- * Object different merge failed.
- * Exception will be thrown if the object element could not be accessed
+ * Thrown when a nested object at a specific path cannot be accessed during a diff merge,
+ * typically because an intermediate parent object is missing.
+ *
+ * 在差异合并期间，因中间父对象缺失等原因导致特定路径处的嵌套对象无法访问时抛出。
  */
 class ObjectDiffMergeFailedException extends Exception_1.Exception {
     path;
+    /**
+     * @param path the path where the inaccessible object was encountered / 遇到无法访问对象的路径
+     */
     constructor(path) {
         super();
         this.path = path;

package/dist/lib/core/Language.js

@@ -3,6 +3,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseAreaString = exports.parseAreaCode = void 0;
 const AreaCode_1 = require("../types/AreaCode");
+/**
+ * Internal implementation: convert a locale string to its corresponding AreaCode enum value.
+ * The input is normalised to lower-case before matching.
+ * When no match is found, the fallback depends on `forceArea`:
+ *   - false / omitted → AreaCode.zh_CN
+ *   - true            → AreaCode.unknown
+ *
+ * 内部实现：将语言环境字符串转换为对应的 AreaCode 枚举值。
+ * 输入会先转换为小写再进行匹配。
+ * 未匹配时的回退值取决于 `forceArea`：
+ *   - false / 省略 → AreaCode.zh_CN
+ *   - true         → AreaCode.unknown
+ *
+ * @param areaStr the locale string to parse, e.g. "zh_CN" / 要解析的语言环境字符串，如 "zh_CN"
+ * @param forceArea when true, returns AreaCode.unknown for unrecognised strings / 为 true 时，无法识别的字符串返回 AreaCode.unknown
+ * @returns the matching AreaCode enum value / 对应的 AreaCode 枚举值
+ */
 // eslint-disable-next-line complexity
 function _parseAreaString(areaStr, forceArea) {
     const lowCase = areaStr?.toLowerCase() || "zh_cn";
@@ -271,6 +288,16 @@ function _parseAreaString(areaStr, forceArea) {
             return forceArea ? AreaCode_1.AreaCode.unknown : AreaCode_1.AreaCode.zh_CN;
     }
 }
+/**
+ * Internal implementation: convert an AreaCode enum value to its canonical locale string.
+ * Falls back to "zh_CN" for AreaCode.unknown and any unrecognised value.
+ *
+ * 内部实现：将 AreaCode 枚举值转换为其标准语言环境字符串。
+ * AreaCode.unknown 及任何无法识别的值均回退为 "zh_CN"。
+ *
+ * @param eArea the AreaCode enum value to convert / 要转换的 AreaCode 枚举值
+ * @returns the canonical locale string, e.g. "zh_CN" / 标准语言环境字符串，如 "zh_CN"
+ */
 // eslint-disable-next-line complexity
 function _areaCodeToString(eArea) {
     switch (eArea) {
@@ -539,21 +566,47 @@ function _areaCodeToString(eArea) {
     }
 }
 /**
- * Parse area code to general string
+ * Convert an AreaCode enum value to its canonical locale string (e.g. "zh_CN", "en_US").
+ * Falls back to "zh_CN" for AreaCode.unknown.
+ *
+ * 将 AreaCode 枚举值转换为其标准语言环境字符串（如 "zh_CN"、"en_US"）。
+ * AreaCode.unknown 回退为 "zh_CN"。
  *
- * @param eArea the area code
- * @returns return the general string of specified area code
+ * @param eArea the AreaCode enum value / AreaCode 枚举值
+ * @returns the locale string for the given area code / 给定区域码对应的语言环境字符串
+ *
+ * @example
+ * parseAreaCode(AreaCode.zh_CN); // "zh_CN"
+ * parseAreaCode(AreaCode.en_US); // "en_US"
  */
 function parseAreaCode(eArea) {
     return _areaCodeToString(eArea);
 }
 exports.parseAreaCode = parseAreaCode;
 /**
- * Convert the string to area code
+ * Parse a locale string into its corresponding AreaCode enum value.
+ * The input is matched case-insensitively (e.g. "ZH_CN", "zh_cn", and "zh_CN" all resolve to AreaCode.zh_CN).
+ *
+ * When the string cannot be matched:
+ *   - `forceArea` omitted or false → returns AreaCode.zh_CN (lenient default)
+ *   - `forceArea` true             → returns AreaCode.unknown (strict mode)
+ *
+ * 将语言环境字符串解析为对应的 AreaCode 枚举值。
+ * 输入不区分大小写（如 "ZH_CN"、"zh_cn"、"zh_CN" 均解析为 AreaCode.zh_CN）。
+ *
+ * 字符串无法匹配时：
+ *   - `forceArea` 省略或为 false → 返回 AreaCode.zh_CN（宽松默认值）
+ *   - `forceArea` 为 true        → 返回 AreaCode.unknown（严格模式）
+ *
+ * @param areaStr the locale string to parse; defaults to "zh_CN" if omitted / 要解析的语言环境字符串，省略时默认为 "zh_CN"
+ * @param forceArea when true, returns AreaCode.unknown for unrecognised strings / 为 true 时，无法识别的字符串返回 AreaCode.unknown
+ * @returns the matching AreaCode enum value / 对应的 AreaCode 枚举值
  *
- * @param areaStr the source string
- * @param forceArea a boolean value indicates whether needs to have a strict check for the source string. (That means if in strict mode and the string could not be converted, an unkonwn will be returned.)
- * @returns return the area code
+ * @example
+ * parseAreaString("zh_CN");          // AreaCode.zh_CN
+ * parseAreaString("en_US");          // AreaCode.en_US
+ * parseAreaString("invalid", true);  // AreaCode.unknown
+ * parseAreaString("invalid");        // AreaCode.zh_CN
  */
 function parseAreaString(areaStr, forceArea) {
     return _parseAreaString(areaStr, forceArea);

package/dist/lib/core/Log.js

@@ -103,10 +103,42 @@ function _endPerf(recorder, console) {
     }
     return perfTime;
 }
-/** Tianyu Log Instance */
+/**
+ * The global Tianyu log instance.
+ * Provides leveled console logging with optional timestamp support.
+ *
+ * 全局 Tianyu 日志实例。
+ * 提供带可选时间戳的分级控制台日志功能。
+ */
 exports.Log = _log;
-/** Tianyu Performance Instance */
+/**
+ * The global Tianyu performance tracking instance.
+ * Use startPerf / endPerf to measure elapsed time for any named operation.
+ *
+ * 全局 Tianyu 性能跟踪实例。
+ * 使用 startPerf / endPerf 测量任意命名操作的耗时。
+ *
+ * @example
+ * const rec = Performance.startPerf("db-query");
+ * // ... do work ...
+ * const ms = Performance.endPerf(rec, true); // logs and returns elapsed ms
+ */
 exports.Performance = {
+    /**
+     * Start a performance recording session.
+     * 开始一次性能记录会话。
+     *
+     * @param id optional session name / 可选的会话名称
+     * @returns a recorder object holding the start timestamp / 包含开始时间戳的记录器对象
+     */
     startPerf: _startPerf,
+    /**
+     * End a performance recording session and return elapsed milliseconds.
+     * 结束性能记录会话并返回经过的毫秒数。
+     *
+     * @param recorder the recorder returned by startPerf / startPerf 返回的记录器
+     * @param console whether to print the elapsed time to the console / 是否将耗时输出到控制台
+     * @returns elapsed time in milliseconds / 经过的毫秒数
+     */
     endPerf: _endPerf,
 };

package/dist/lib/core/TypeConvertion.js

@@ -2,6 +2,26 @@
 /**@format */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getBoolean = void 0;
+/**
+ * Convert a value of any type to a boolean.
+ * Conversion rules:
+ *   - null / undefined → false
+ *   - number: 0 → false, any other number → true
+ *   - string: "" or "false" (case-insensitive) → false, any other non-empty string → true
+ *   - boolean: returned as-is
+ *   - any other type → true
+ *
+ * 将任意类型的值转换为布尔值。
+ * 转换规则：
+ *   - null / undefined → false
+ *   - number：0 → false，其他数值 → true
+ *   - string：空字符串或 "false"（大小写不敏感）→ false，其他非空字符串 → true
+ *   - boolean：直接返回原值
+ *   - 其他类型 → true
+ *
+ * @param value the value to convert / 要转换的值
+ * @returns the boolean result / 转换后的布尔值
+ */
 function getBoolean(value) {
     if (value === null) {
         return false;

package/dist/lib/core/object/ArrayHelper.js

@@ -2,13 +2,24 @@
 /**@format */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArrayHelper = void 0;
-/** Array type related tools */
+/**
+ * Array utility class providing merge and deduplication helpers.
+ * 数组工具类，提供合并与去重帮助方法。
+ */
 class ArrayHelper {
     /**
-     * To merge multiple arrays into a new array and remove duplicated elements.
+     * Merge multiple arrays (or individual values) into a single new array,
+     * removing duplicate elements. Non-array arguments are treated as single-item arrays.
      *
-     * @param {any[]} array arrays
-     * @returns return a new array
+     * 将多个数组（或单个值）合并为一个新数组，并移除重复元素。
+     * 非数组参数被视为单元素数组处理。
+     *
+     * @param array any number of arrays or individual values / 任意数量的数组或单个值
+     * @returns a new deduplicated array / 去重后的新数组
+     *
+     * @example
+     * ArrayHelper.merge([1, 2], [2, 3], 4);
+     * // => [1, 2, 3, 4]
      */
     static merge(...array) {
         if (array.length === 0) {

package/dist/lib/core/object/Bytes.js

@@ -6,13 +6,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Bytes = void 0;
 const crypto_1 = __importDefault(require("crypto"));
-/** Bytes Object type */
+/**
+ * Byte buffer utility class.
+ * 字节缓冲区工具类。
+ */
 class Bytes {
     /**
-     * Get a bytes buffer filled with random data
+     * Generate a Buffer of the specified size filled with cryptographically random bytes.
+     * 生成指定大小、由密码学安全随机字节填充的 Buffer。
      *
-     * @param size the length of bytes buffer
-     * @returns buffer
+     * @param size the number of random bytes to generate / 要生成的随机字节数
+     * @returns a Buffer containing random data / 包含随机数据的 Buffer
      */
     static random(size) {
         return crypto_1.default.randomBytes(size);