@aitianyu.cn/types 0.1.2 → 0.1.3

package/dist/lib/types/TMap.js

@@ -3,41 +3,50 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TMap = void 0;
 /**
- * Tianyu Map
- * Support Customized Object type
+ * Tianyu Map — a generic Map implementation that supports customized object types as keys.
+ * Keys must implement IComparable; the getString() value is used internally as the actual map key.
+ *
+ * Tianyu 映射表——支持自定义对象类型作为键的泛型 Map 实现。
+ * 键必须实现 IComparable 接口；内部使用 getString() 返回值作为实际映射键。
  */
 class TMap {
+    /** Internal value store keyed by the string form of K. / 以 K 的字符串形式为键的内部值存储。 */
     _map;
+    /** Internal key object store for retrieving the original K instance. / 存储原始 K 实例的内部键对象映射。 */
     _kMap;
     /**
-     * Create an empty Tianyu Map Instance
+     * Create an empty TMap instance.
+     * 创建一个空的 TMap 实例。
      */
     constructor() {
         this._map = new Map();
         this._kMap = new Map();
     }
     /**
-     * Clean the Map instance
+     * Remove all key-value pairs from the map.
+     * 清除映射表中的所有键值对。
      */
     clear() {
         this._map.clear();
         this._kMap.clear();
     }
     /**
-     * Delete a specified item from the instance
+     * Delete the element with the specified key from the map.
+     * 从映射表中删除指定键对应的元素。
      *
-     * @param key The key of the item
-     * @returns return true if deleted successful and return false if failed
+     * @param key the key of the element to delete / 要删除的元素的键
+     * @returns true if the element was found and deleted, false otherwise / 删除成功返回 true，否则返回 false
      */
     delete(key) {
         const keyString = key.getString();
         return this._map.delete(keyString) && this._kMap.delete(keyString);
     }
     /**
-     * Executes a provided function once per each key/value pair in the Map, in insertion order.
+     * Execute a callback once for each key-value pair in insertion order.
+     * 按插入顺序对每个键值对执行一次回调函数。
      *
-     * @param callbackfn provided execution function
-     * @param thisArg additional args
+     * @param callbackfn the function to execute per entry / 每条记录执行的回调函数
+     * @param thisArg optional value to use as `this` in the callback / 回调中可选的 this 绑定值
      */
     forEach(callbackfn, thisArg) {
         const runMap = new Map();
@@ -52,33 +61,38 @@ class TMap {
         }, thisArg);
     }
     /**
-     * Returns a specified element from the Map object. If the value that is associated to the provided key is an object,
-     * then you will get a reference to that object and any change made to that object will effectively modify it inside the Map.
+     * Return the value associated with the specified key.
+     * If the key is associated with an object, a reference to that object is returned —
+     * any mutation will affect the stored value.
      *
-     * @param key The key of the value
-     * @returns Returns the element associated with the specified key.
-     *          If no element is associated with the specified key, undefined is returned.
+     * 返回与指定键关联的值。
+     * 若键对应的值为对象，则返回其引用——对该对象的修改会影响映射表中存储的值。
+     *
+     * @param key the key to look up / 要查找的键
+     * @returns the associated value, or undefined if not found / 关联的值，未找到时返回 undefined
      */
     get(key) {
         const keyString = key.getString();
         return this._map.get(keyString);
     }
     /**
-     * Get a boolean value indicates whether an element with the specified key exists or not.
+     * Check whether an element with the specified key exists in the map.
+     * 检查映射表中是否存在指定键对应的元素。
      *
-     * @param key The key what wants to search
-     * @returns return true if the value is found
+     * @param key the key to search for / 要查找的键
+     * @returns true if the key exists / 键存在时返回 true
      */
     has(key) {
         const keyString = key.getString();
         return this._kMap.has(keyString);
     }
     /**
-     * Adds a new element with a specified key and value to the Map. If an element with the same key already exists, the element will be updated.
+     * Add or update the element with the specified key and value.
+     * 添加或更新具有指定键和值的元素。
      *
-     * @param key The key of new element
-     * @param value The value of new element
-     * @returns return the instance that is current instance
+     * @param key the key of the new or existing element / 新增或已有元素的键
+     * @param value the value to associate with the key / 要与键关联的值
+     * @returns the current TMap instance (for chaining) / 当前 TMap 实例（支持链式调用）
      */
     set(key, value) {
         const keyString = key.getString();
@@ -87,33 +101,37 @@ class TMap {
         return this;
     }
     /**
-     * Get a number of elements in the Map
+     * Get the number of elements stored in the map.
+     * 获取映射表中存储的元素数量。
      *
-     * @returns return the count of elements
+     * @returns the element count / 元素数量
      */
     size() {
         return this._kMap.size;
     }
     /**
-     * Get all keys of the Map
+     * Return an iterator over all keys (as original K instances) in the map.
+     * 返回映射表中所有键（原始 K 实例）的迭代器。
      *
-     * @returns return a keys iterator
+     * @returns a keys iterator / 键迭代器
      */
     keys() {
         return this._kMap.values();
     }
     /**
-     * Get all values of the Map
+     * Return an iterator over all values in the map.
+     * 返回映射表中所有值的迭代器。
      *
-     * @returns return a values iterator
+     * @returns a values iterator / 值迭代器
      */
     values() {
         return this._map.values();
     }
     /**
-     * Get an Iterator of the Map
+     * Return an iterator that yields [K, V] tuple pairs in insertion order.
+     * 返回按插入顺序产出 [K, V] 元组对的迭代器。
      *
-     * @returns return an iterator object
+     * @returns an iterator object / 迭代器对象
      */
     [Symbol.iterator]() {
         const keys = this._map.entries();

package/dist/types/coding/Error.d.ts

@@ -2,26 +2,36 @@
 import { Exception } from "../types/Exception";
 import { PathTargetType } from "./Path";
 /**
- * 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" 但未指定文件名时抛出此异常。
  */
 export declare class PathProcessorSourceLostException extends Exception {
+    /**
+     * @param msg optional additional message / 可选的附加信息
+     */
     constructor(msg?: string);
     toString(): string;
 }
 /**
- * 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.
+ * 当路径段中包含目录名非法字符时抛出此异常。
  */
 export declare class PathDirectoryValidationFailException extends Exception {
+    /**
+     * @param msg the invalid directory name / 非法的目录名
+     */
     constructor(msg?: string);
     toString(): string;
 }
 /**
- * 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.
+ * 当尝试将文件路径当作目录路径（或反之）进行转换时抛出此异常。
  */
 export declare class PathDirAndFileConvertInvaild extends Exception {
+    /**
+     * @param path the path string that caused the conflict / 引发冲突的路径字符串
+     * @param type the actual type of the path / 路径的实际类型
+     */
     constructor(path: string, type: PathTargetType);
     toString(): string;
 }

package/dist/types/coding/Path.d.ts

@@ -1,61 +1,85 @@
 /**@format */
 import { PathBase } from "../types/PathBase";
 import { IComparable } from "../types/Types";
-/** The target path type */
+/**
+ * The target type of a Path — either a directory or a file.
+ * Path 的目标类型——目录或文件。
+ */
 export type PathTargetType = "directory" | "file";
-/** 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.
+ *
+ * 表示具有明确类型（目录或文件）的文件系统路径。
+ * 支持从字符串、目录段数组或两者组合构建实例。
+ * 遇到非法字符或类型不匹配时会抛出校验异常。
+ */
 export declare class Path extends PathBase implements IComparable {
+    /** Internal path type indicator. / 内部路径类型标识。 */
     private _type;
+    /** The file name component, present only when type is "file". / 文件名组件，仅在类型为 "file" 时存在。 */
     private _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?: string[] | string, type?: PathTargetType, file?: string);
     /**
-     * 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(): string;
     /**
-     * Set the target type
+     * Set the target type of this path instance.
+     * 设置当前路径实例的目标类型。
      *
-     * @param type new type
+     * @param type the new path type / 新路径类型
      */
     setType(type: PathTargetType): void;
     /**
-     * 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(): PathTargetType;
     /**
-     * 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: string): string | undefined;
     /**
-     * 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(): string | undefined;
     /**
-     * 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(): string;
     /**
-     * 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(): number;
 }

package/dist/types/core/Environment.d.ts

@@ -1,4 +1,18 @@
 /** @format */
+/**
+ * Runtime environment detection utility.
+ * Identifies whether the current execution context is Node.js or a browser.
+ *
+ * 运行时环境检测工具类。
+ * 用于识别当前执行上下文是 Node.js 还是浏览器环境。
+ */
 export declare class Environment {
+    /**
+     * Detect the current runtime environment.
+     * 检测当前运行时环境。
+     *
+     * @returns "node" when running in Node.js, "browser" otherwise
+     *          在 Node.js 中运行时返回 "node"，否则返回 "browser"
+     */
     static runtimeEnv(): "node" | "browser";
 }

package/dist/types/core/Errors.d.ts

@@ -1,47 +1,68 @@
 /**@format */
 import { Exception } from "../types/Exception";
-/** Argument null exception */
+/**
+ * Thrown when a required argument is null or an empty string.
+ * 当必填参数为 null 或空字符串时抛出。
+ */
 export declare class ArgumentNullOrEmptyException extends Exception {
+    /**
+     * @param msg the name of the offending argument / 出错的参数名称
+     */
     constructor(msg: string);
     toString(): string;
 }
 /**
- * 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 类型。
  */
 export declare class ObjectCloneFunctionNotSupportException extends Exception {
     constructor();
     toString(): string;
 }
 /**
- * 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.
+ *
+ * 在合并操作中，对象差异条目的预期状态与当前实际状态不匹配时抛出。
  */
 export declare class ObjectMergeStatusCheckFailedException extends Exception {
     private status;
     private path;
+    /**
+     * @param path the diff path where the mismatch occurred / 发生不匹配的差异路径
+     * @param status the type of change that failed verification / 校验失败的变更类型
+     */
     constructor(path: string, status: "add" | "modify" | "del");
     toString(): string;
 }
 /**
- * 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).
+ *
+ * 当差异条目因当前值处于意外状态（如不应存在的值已存在）而无法应用时抛出。
  */
 export declare class ObjectDiffApplyInvalidStatusException extends Exception {
     private value;
+    /**
+     * @param value the value that is in an invalid state / 处于无效状态的值
+     */
     constructor(value: any);
     toString(): string;
 }
 /**
- * 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.
+ *
+ * 在差异合并期间，因中间父对象缺失等原因导致特定路径处的嵌套对象无法访问时抛出。
  */
 export declare class ObjectDiffMergeFailedException extends Exception {
     private path;
+    /**
+     * @param path the path where the inaccessible object was encountered / 遇到无法访问对象的路径
+     */
     constructor(path: string);
     toString(): string;
 }

package/dist/types/core/Language.d.ts

@@ -1,17 +1,43 @@
 /**@format */
 import { AreaCode } from "../types/AreaCode";
 /**
- * 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.
  *
- * @param eArea the area code
- * @returns return the general string of specified area code
+ * 将 AreaCode 枚举值转换为其标准语言环境字符串（如 "zh_CN"、"en_US"）。
+ * AreaCode.unknown 回退为 "zh_CN"。
+ *
+ * @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"
  */
 export declare function parseAreaCode(eArea: AreaCode): string;
 /**
- * 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
  */
 export declare function parseAreaString(areaStr?: string, forceArea?: boolean): AreaCode;

package/dist/types/core/Log.d.ts

@@ -2,11 +2,43 @@
 import { ILog, IPerfRecorder } from "../types/Logs";
 declare function _startPerf(id?: string): IPerfRecorder;
 declare function _endPerf(recorder: IPerfRecorder, console?: boolean): number;
-/** Tianyu Log Instance */
+/**
+ * The global Tianyu log instance.
+ * Provides leveled console logging with optional timestamp support.
+ *
+ * 全局 Tianyu 日志实例。
+ * 提供带可选时间戳的分级控制台日志功能。
+ */
 export declare const Log: ILog;
-/** 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
+ */
 export declare const Performance: {
+    /**
+     * Start a performance recording session.
+     * 开始一次性能记录会话。
+     *
+     * @param id optional session name / 可选的会话名称
+     * @returns a recorder object holding the start timestamp / 包含开始时间戳的记录器对象
+     */
     startPerf: typeof _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: typeof _endPerf;
 };
 export {};

package/dist/types/core/TypeConvertion.d.ts

@@ -1,2 +1,22 @@
 /**@format */
+/**
+ * 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 / 转换后的布尔值
+ */
 export declare function getBoolean(value: any): boolean;

package/dist/types/core/interface/ITJSON.d.ts

@@ -1,5 +1,16 @@
 /** @format */
 import { IComparable } from "../../../src/types/Types";
+/**
+ * Base interface for aitianyu JSON-representable types.
+ * Extends IComparable and requires a toString() method.
+ *
+ * aitianyu 可 JSON 表示类型的基础接口。
+ * 继承 IComparable 并要求实现 toString() 方法。
+ */
 export interface ITianyuJSON extends IComparable {
+    /**
+     * Serialize this object to a JSON string.
+     * 将当前对象序列化为 JSON 字符串。
+     */
     toString(): string;
 }

package/dist/types/core/interface/ITianyuType.d.ts

@@ -1,5 +1,16 @@
 /** @format */
 import { IComparable } from "../../../src/types/Types";
+/**
+ * Base interface for all aitianyu typed wrapper objects.
+ * Extends IComparable and requires a toString() method for serialization.
+ *
+ * 所有 aitianyu 类型包装对象的基础接口。
+ * 继承 IComparable 并要求实现 toString() 方法以支持序列化。
+ */
 export interface ITianyuType extends IComparable {
+    /**
+     * Convert this object to its string representation.
+     * 将当前对象转换为字符串表示形式。
+     */
     toString(): string;
 }

package/dist/types/core/object/ArrayHelper.d.ts

@@ -1,11 +1,22 @@
 /**@format */
-/** Array type related tools */
+/**
+ * Array utility class providing merge and deduplication helpers.
+ * 数组工具类，提供合并与去重帮助方法。
+ */
 export declare 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: any[]): any[];
 }

package/dist/types/core/object/Bytes.d.ts

@@ -1,13 +1,17 @@
 /** @format */
 /// <reference types="node" />
 /// <reference types="node" />
-/** Bytes Object type */
+/**
+ * Byte buffer utility class.
+ * 字节缓冲区工具类。
+ */
 export declare 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: number): Buffer;
 }