@aitianyu.cn/types 0.1.2 → 0.1.3

package/dist/types/types/Logs.d.ts

@@ -1,64 +1,93 @@
 /**@format */
-/** Tianyu Log Level */
+/**
+ * Tianyu Log Level Enum.
+ * Defines the severity levels for log messages.
+ *
+ * Tianyu 日志级别枚举。
+ * 定义日志消息的严重程度级别。
+ */
 export declare enum LogLevel {
-    /** Debug mode log */
+    /** Debug level — for development/diagnostic messages. / 调试级别——用于开发或诊断信息。 */
     DEBUG = 0,
-    /** error msg */
+    /** Error level — for recoverable error messages. / 错误级别——用于可恢复的错误信息。 */
     ERROR = 1,
-    /** fatal error msg */
+    /** Fatal level — for critical, unrecoverable errors. / 致命级别——用于严重且无法恢复的错误。 */
     FATAL = 2,
-    /** info log */
+    /** Info level — for general informational messages. / 信息级别——用于一般性通知信息。 */
     INFO = 3,
-    /** warning log */
+    /** Warning level — for potentially problematic situations. / 警告级别——用于潜在问题的提示信息。 */
     WARNING = 4,
-    /** default log */
+    /** Default log level — for plain output with no special classification. / 默认日志级别——无特殊分类的普通输出。 */
     LOG = 5
 }
-/** Tianyu Log Interface */
+/**
+ * Tianyu Log Interface.
+ * Defines the contract for the logging instance.
+ *
+ * Tianyu 日志接口。
+ * 定义日志实例的方法契约。
+ */
 export interface ILog {
     /**
-     * Write a console log with specified log level
+     * Write a console log with a specified log level.
+     * 以指定日志级别写入一条控制台日志。
      *
-     * @param msg the message body
-     * @param level the console log level, if not be specified, to print as default log
-     * @param timer a boolean value indicates whether needs to add a timestamp for the log
+     * @param msg the message body / 日志内容
+     * @param level the console log level; defaults to INFO if not specified / 日志级别，未指定时默认为 INFO
+     * @param timer whether to prepend a timestamp to the log / 是否在日志前添加时间戳
      */
     log(msg: string, level?: LogLevel, timer?: boolean): void;
     /**
-     * Write a console info log
-     * @param msg the message body
-     * @param timer a boolean value indicates whether needs to add a timestamp for the log
+     * Write a console info log.
+     * 写入一条 INFO 级别的控制台日志。
+     *
+     * @param msg the message body / 日志内容
+     * @param timer whether to prepend a timestamp / 是否添加时间戳
      */
     info(msg: string, timer?: boolean): void;
     /**
-     * Write a console warning log
-     * @param msg the message body
-     * @param timer a boolean value indicates whether needs to add a timestamp for the log
+     * Write a console warning log.
+     * 写入一条 WARNING 级别的控制台日志。
+     *
+     * @param msg the message body / 日志内容
+     * @param timer whether to prepend a timestamp / 是否添加时间戳
      */
     warn(msg: string, timer?: boolean): void;
     /**
-     * Write a console debug log
-     * @param msg the message body
-     * @param timer a boolean value indicates whether needs to add a timestamp for the log
+     * Write a console debug log.
+     * 写入一条 DEBUG 级别的控制台日志。
+     *
+     * @param msg the message body / 日志内容
+     * @param timer whether to prepend a timestamp / 是否添加时间戳
      */
     debug(msg: string, timer?: boolean): void;
     /**
-     * Write a console error message
-     * @param msg the message body
-     * @param timer a boolean value indicates whether needs to add a timestamp for the log
+     * Write a console error message.
+     * 写入一条 ERROR 级别的控制台日志。
+     *
+     * @param msg the message body / 日志内容
+     * @param timer whether to prepend a timestamp / 是否添加时间戳
      */
     error(msg: string, timer?: boolean): void;
     /**
-     * Write a console fatal message
-     * @param msg the message body
-     * @param timer a boolean value indicates whether needs to add a timestamp for the log
+     * Write a console fatal message.
+     * 写入一条 FATAL 级别的控制台日志。
+     *
+     * @param msg the message body / 日志内容
+     * @param timer whether to prepend a timestamp / 是否添加时间戳
      */
     fatal(msg: string, timer?: boolean): void;
 }
-/** Tianyu Performance recorder */
+/**
+ * Tianyu Performance Recorder.
+ * Holds the start information for a performance measurement session.
+ *
+ * Tianyu 性能记录器。
+ * 保存一次性能测量会话的起始信息。
+ */
 export interface IPerfRecorder {
-    /** the recording id */
+    /** Unique identifier for this performance recording session. / 本次性能记录会话的唯一标识符。 */
     id: string;
-    /** the start time number */
+    /** The timestamp (ms since epoch) when the recording started. / 记录开始时的时间戳（毫秒）。 */
     start: number;
 }

package/dist/types/types/Object.d.ts

@@ -1,18 +1,27 @@
 /**@format */
 import { TMap } from "./TMap";
 import { PathBase } from "./PathBase";
-/** Tianyu Object calculated different item */
+/**
+ * Describes a single field-level difference between two object snapshots.
+ * 描述两个对象快照之间某个字段级别的差异信息。
+ */
 export interface IObjectDiffInfo {
-    /** different item path */
+    /** The path string that locates the changed field within the object. / 定位对象中变更字段的路径字符串。 */
     path: string;
-    /** the old value of this path */
+    /** The previous value at this path before the change. / 变更前此路径处的旧值。 */
     old: any;
-    /** the new value of this path */
+    /** The new value at this path after the change. / 变更后此路径处的新值。 */
     new: any;
-    /** does the change be deletion */
+    /** Present and true when this change represents a field deletion. / 当此变更表示字段删除时，该属性存在且为 true。 */
     deleted?: true;
-    /** does the change be adding */
+    /** Present and true when this change represents a new field addition. / 当此变更表示字段新增时，该属性存在且为 true。 */
     added?: true;
 }
-/** Different items map */
+/**
+ * A map of all field-level differences keyed by their path.
+ * Used as the return type of ObjectCalculater.calculateDiff().
+ *
+ * 以路径为键存储所有字段级差异的映射表。
+ * 作为 ObjectCalculater.calculateDiff() 的返回类型使用。
+ */
 export type ObjectDiffMap = TMap<PathBase, IObjectDiffInfo>;

package/dist/types/types/PathBase.d.ts

@@ -1,24 +1,36 @@
 /**@format */
 import { IComparable } from "./Types";
-/** Path base class */
+/**
+ * Abstract base class for path representations.
+ * Stores an ordered list of directory segments and provides path manipulation utilities.
+ * Implements IComparable so instances can be used as TMap keys.
+ *
+ * 路径表示的抽象基类。
+ * 以有序列表存储目录段，并提供路径操作工具方法。
+ * 实现 IComparable 接口，使实例可用作 TMap 的键。
+ */
 export declare class PathBase implements IComparable {
+    /** Internal array of directory segment strings. / 内部存储目录段字符串的数组。 */
     protected _dirs: string[];
     /**
-     * Create a Path instance by specified dirs
+     * Create a PathBase instance from an optional array of directory segments.
+     * 通过可选的目录段数组创建 PathBase 实例。
      *
-     * @param dirs the specified directories
+     * @param dirs the directory segments to initialize with / 用于初始化的目录段数组
      */
     constructor(dirs?: string[]);
     /**
-     * Convert the path instance to string
+     * Convert the path to a forward-slash-separated string.
+     * 将路径转换为以正斜杠分隔的字符串。
      *
-     * @returns return the fromatted string
+     * @returns the formatted path string, or "" if empty / 格式化后的路径字符串，为空时返回 ""
      */
     toString(): string;
     /**
-     * Iterator of path directories
+     * Return an iterator over the directory segments in order.
+     * 按顺序返回目录段的迭代器。
      *
-     * @returns return an iterator
+     * @returns an iterator object / 迭代器对象
      */
     [Symbol.iterator](): {
         next: () => {
@@ -27,50 +39,58 @@ export declare class PathBase implements IComparable {
         };
     };
     /**
-     * Get a directories array deep copy
+     * Get a shallow copy of the internal directory segments array.
+     * 获取内部目录段数组的浅拷贝。
      *
-     * @returns return directories
+     * @returns a copy of the directories array / 目录数组的副本
      */
     getDirs(): string[];
     /**
-     * Get a number that indicates the directories count
+     * Get the number of directory segments in this path.
+     * 获取当前路径中目录段的数量。
      *
-     * @returns return the directories count
+     * @returns the segment count / 目录段数量
      */
     length(): number;
     /**
-     * Append a new directory to the end of path
+     * Append a new directory segment to the end of the path.
+     * 在路径末尾追加一个新的目录段。
      *
-     * @param dir the new directory name
-     * @returns return the new directories count
+     * @param dir the directory name to append / 要追加的目录名
+     * @returns the new total segment count / 新的目录段总数
      */
     append(dir: string): number;
     /**
-     * Clean all the pathes
+     * Remove all directory segments, resetting the path to empty.
+     * 清除所有目录段，将路径重置为空。
      */
     clear(): void;
     /**
-     * Remove the end directory of the path instance and return it
+     * Remove and return the last directory segment.
+     * 移除并返回最后一个目录段。
      *
-     * @returns return the end of directory
+     * @returns the last directory segment, or undefined if empty / 最后一个目录段，为空时返回 undefined
      */
     pop(): string | undefined;
     /**
-     * Remove the first directory of the path instance and return it
+     * Remove and return the first directory segment.
+     * 移除并返回第一个目录段。
      *
-     * @returns return the first directory
+     * @returns the first directory segment, or undefined if empty / 第一个目录段，为空时返回 undefined
      */
     shift(): string | undefined;
     /**
-     * Convert the path instance to string for object comparing
+     * IComparable implementation — returns the string form for object comparison.
+     * IComparable 实现——返回用于对象比较的字符串形式。
      *
-     * @returns return the comparable string
+     * @returns the comparable string / 可比较字符串
      */
     getString(): string;
     /**
-     * Get the hashcode of current path
+     * IComparable implementation — returns 0 as the hash code for this path.
+     * IComparable 实现——返回 0 作为此路径的哈希码。
      *
-     * @returns always return 0
+     * @returns always 0 / 始终返回 0
      */
     getHashCode(): number;
 }

package/dist/types/types/Security.d.ts

@@ -1,23 +1,36 @@
 /**@format */
-/** Encrypt Option Type */
+/**
+ * Encryption operation direction.
+ * 加密操作方向枚举。
+ */
 export declare enum EncryptOption {
+    /** Encryption direction — encode plaintext into ciphertext. / 加密方向——将明文编码为密文。 */
     Encryption = 0,
+    /** Decryption direction — decode ciphertext back to plaintext. / 解密方向——将密文还原为明文。 */
     Decryption = 1
 }
-/** An Interface of the Cipher */
+/**
+ * Cipher algorithm interface.
+ * Any class that implements a symmetric encryption algorithm should implement this interface.
+ *
+ * 密码算法接口。
+ * 实现对称加密算法的类应实现此接口。
+ */
 export interface ICipher {
     /**
-     * To encode the source value
+     * Encode the source byte array into an encrypted byte array.
+     * 将源字节数组编码为加密后的字节数组。
      *
-     * @param source the source value
-     * @returns return the encoded value
+     * @param source the plaintext source value as a number array / 明文源数据（数字数组形式）
+     * @returns the encrypted byte array / 加密后的字节数组
      */
     encryption(source: number[]): number[];
     /**
-     * To decode the encoded value
+     * Decode the encrypted byte array back to the original plaintext byte array.
+     * 将加密字节数组解码还原为原始明文字节数组。
      *
-     * @param source the encoded value
-     * @returns return the decoded value
+     * @param source the encrypted value as a number array / 加密数据（数字数组形式）
+     * @returns the decrypted byte array / 解密后的字节数组
      */
     decryption(source: number[]): number[];
 }

package/dist/types/types/TMap.d.ts

@@ -1,80 +1,98 @@
 /**@format */
 import { IComparable } from "./Types";
 /**
- * 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() 返回值作为实际映射键。
  */
 export declare class TMap<K extends IComparable, V> {
+    /** Internal value store keyed by the string form of K. / 以 K 的字符串形式为键的内部值存储。 */
     private _map;
+    /** Internal key object store for retrieving the original K instance. / 存储原始 K 实例的内部键对象映射。 */
     private _kMap;
     /**
-     * Create an empty Tianyu Map Instance
+     * Create an empty TMap instance.
+     * 创建一个空的 TMap 实例。
      */
     constructor();
     /**
-     * Clean the Map instance
+     * Remove all key-value pairs from the map.
+     * 清除映射表中的所有键值对。
      */
     clear(): void;
     /**
-     * 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: K): boolean;
     /**
-     * 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: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void;
     /**
-     * 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: K): V | undefined;
     /**
-     * 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: K): boolean;
     /**
-     * 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: K, value: V): 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(): number;
     /**
-     * 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(): IterableIterator<K>;
     /**
-     * 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(): IterableIterator<V>;
     /**
-     * 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](): Iterator<[K | undefined, V | undefined]>;
 }

package/dist/types/types/Types.d.ts

@@ -1,25 +1,57 @@
 /**@format */
-/**A record object type of boolean */
+/**
+ * A record object type with string keys and boolean values.
+ * 键为字符串、值为布尔类型的记录对象类型。
+ */
 export type MapOfBoolean = Record<string, boolean>;
-/**A record object type of string array */
+/**
+ * A record object type with string keys and string array values.
+ * 键为字符串、值为字符串数组的记录对象类型。
+ */
 export type MapOfStrings = Record<string, string[]>;
-/**A record object type of string */
+/**
+ * A record object type with string keys and string values.
+ * 键为字符串、值为字符串的记录对象类型。
+ */
 export type MapOfString = Record<string, string>;
-/**A record object type of customized */
+/**
+ * A record object type with string keys and customized value type.
+ * 键为字符串、值为自定义类型的记录对象类型。
+ */
 export type MapOfType<T> = Record<string, T>;
-/** no parameter call back function */
+/**
+ * A callback function type with no parameters and no return value.
+ * 无参数、无返回值的回调函数类型。
+ */
 export type CallbackAction = () => void;
-/** call back function with customized type parameter */
+/**
+ * A callback function type with a single typed parameter and no return value.
+ * 带单个泛型参数、无返回值的回调函数类型。
+ */
 export type CallbackActionT<T> = (value: T) => void;
-/** A key value pair to include a key and a value */
+/**
+ * A key-value pair interface that holds a key and its associated value.
+ * 包含键和对应值的键值对接口。
+ */
 export interface KeyValuePair<K, V> {
+    /** The key of the pair. / 键值对的键。 */
     key: K;
+    /** The value associated with the key. / 与键对应的值。 */
     value: V;
 }
-/** Tianyu Comparable Interface */
+/**
+ * Tianyu Comparable Interface.
+ * Tianyu 可比较接口，要求实现对象标识字符串和哈希码方法。
+ */
 export interface IComparable {
-    /** Get a string what can indicate the object unified */
+    /**
+     * Get a string that uniquely identifies the object instance.
+     * 获取能唯一标识当前对象实例的字符串。
+     */
     getString(): string;
-    /** Get a number which is the hash value of the object instance */
+    /**
+     * Get the hash code number of the object instance.
+     * 获取当前对象实例的哈希码数值。
+     */
     getHashCode(): number;
 }