@aitianyu.cn/types 0.1.2 → 0.1.3

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

@@ -1,22 +1,50 @@
 /**@format */
 import { ObjectDiffMap } from "../../types/Object";
-/** Object Calculation Manager of Tianyu to provide data changes delta calculation and merge */
+/**
+ * Object diff calculation and merge manager.
+ * Provides two static operations:
+ *   1. calculateDiff — compute the field-level delta between two object snapshots.
+ *   2. mergeDiff     — apply one or more diff maps to an object to advance its state.
+ *
+ * 对象差异计算与合并管理器。
+ * 提供两个静态操作：
+ *   1. calculateDiff — 计算两个对象快照之间的字段级差异。
+ *   2. mergeDiff     — 将一个或多个差异映射表应用到对象以推进其状态。
+ */
 export declare class ObjectCalculater {
     /**
-     * Compare two objects and get the delta changes between the two objects
+     * Compute the field-level differences between two object snapshots.
+     * The result is an ObjectDiffMap keyed by the path of each changed field.
      *
-     * @param previous the previous object
-     * @param newest the newest object
-     * @returns return the defferents map
+     * 计算两个对象快照之间的字段级差异。
+     * 结果是以每个变更字段路径为键的 ObjectDiffMap。
+     *
+     * @param previous the previous (old) state / 之前（旧）状态的对象
+     * @param newest the next (new) state / 之后（新）状态的对象
+     * @returns a map of all field differences / 所有字段差异的映射表
      */
     static calculateDiff(previous: any, newest: any): ObjectDiffMap;
     /**
-     * Merge the object value status from one to another one following with the object different maps
+     * Apply an ordered sequence of diff maps to a value, producing the final merged state.
+     * Each diff map is applied in array order (earlier diffs are applied first).
+     *
+     * In strict mode, every merge step is validated:
+     * - Root-level diffs must not coexist with other diffs in the same map.
+     * - The current state must match the `old` value recorded in the diff entry.
+     * - Added fields must not already exist; deleted fields must still exist.
+     *
+     * 将有序的差异映射表序列应用到值上，生成最终合并状态。
+     * 每个差异映射表按数组顺序依次应用（先应用靠前的）。
+     *
+     * 在严格模式下，每步合并都会进行校验：
+     * - 根级差异不能与同一映射表中的其他差异共存。
+     * - 当前状态必须与差异条目中记录的 `old` 值匹配。
+     * - 新增字段不能已经存在；删除字段必须仍然存在。
      *
-     * @param value the raw value(status)
-     * @param diffs the value changed status map array, contains multiply status maps and the status merge will be one by one.
-     * @param strict a boolean value used to whether the program needs a strict status check to avoid some data errors
-     * @returns return a new value status
+     * @param value the base value to apply diffs onto / 要应用差异的基础值
+     * @param diffs an ordered array of diff maps to apply / 要依次应用的差异映射表数组
+     * @param strict when true, validates pre/post state on every change; defaults to false / 为 true 时对每次变更校验前后状态，默认为 false
+     * @returns the resulting value after all diffs have been applied / 应用所有差异后的最终值
      */
     static mergeDiff(value: any, diffs: ObjectDiffMap[], strict?: boolean): any;
 }

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

@@ -1,11 +1,20 @@
 /** @format */
-/** DataView Object Type */
+/**
+ * DataView utility class for creating a globalThis.DataView from typed array buffers.
+ * 用于从类型化数组缓冲区创建 globalThis.DataView 的工具类。
+ */
 export declare class DataView {
     /**
-     * Create a new node:DataView from given data buffer
+     * Create a globalThis.DataView wrapping the given buffer.
+     * Supports ArrayBuffer, Int8Array, Uint8Array, and Uint8ClampedArray as input.
+     * Throws an Error for unsupported input types.
      *
-     * @param data source data buffer
-     * @returns return node:DataView type equals to given data buffer
+     * 创建一个包装给定缓冲区的 globalThis.DataView。
+     * 支持 ArrayBuffer、Int8Array、Uint8Array 和 Uint8ClampedArray 作为输入。
+     * 不支持的输入类型将抛出 Error。
+     *
+     * @param data the source data buffer / 源数据缓冲区
+     * @returns a DataView over the given buffer / 对给定缓冲区的 DataView 视图
      */
     static parse(data: ArrayBuffer | Int8Array | Uint8Array | Uint8ClampedArray): globalThis.DataView;
 }

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

@@ -1,71 +1,92 @@
 /** @format */
-/** Integer Object Type */
+/**
+ * Integer utility class providing random number generation,
+ * byte conversion, and safe bitwise operations.
+ *
+ * 整数工具类，提供随机数生成、字节转换及安全位运算操作。
+ */
 export declare class Integer {
     /**
-     * Get a random integer between min value and max value.
-     * min value should greater than 0, max value should less than 2^48-1 (281474976710655)
+     * Generate a cryptographically random integer in the range [min, max).
+     * min is clamped to 0; max defaults to 2^48-1 (281474976710655).
      *
-     * @param min the min value (0 will be applied when not given)
-     * @param max the max value (281474976710655 will be applied when not given)
-     * @returns return the random value
+     * 在 [min, max) 范围内生成密码学安全的随机整数。
+     * min 最小为 0；max 默认为 2^48-1（281474976710655）。
+     *
+     * @param min lower bound (inclusive), defaults to 0 / 下界（含），默认为 0
+     * @param max upper bound (exclusive), defaults to 281474976710655 / 上界（不含），默认为 281474976710655
+     * @returns the random integer / 随机整数
      */
     static random(min?: number, max?: number): number;
     /**
-     * convert source number to be a 8-byte array
+     * Convert a number to an 8-byte (big-endian) number array.
+     * 将数值转换为 8 字节（大端序）数字数组。
      *
-     * @param srcValue source value
-     * @returns return a 8-byte array
+     * @param srcValue the source number / 源数值
+     * @returns an 8-element array of byte values / 包含 8 个字节值的数组
      */
     static toBytes(srcValue: number): number[];
     /**
-     * number left shift
-     * times will be calculated to get the end 6-bit at the beginning to avoid over-flow
+     * Left-shift `value` by `times` bits.
+     * Only the lowest 6 bits of `times` are used to prevent overflow.
+     *
+     * 将 `value` 左移 `times` 位。
+     * 仅使用 `times` 的低 6 位以防止溢出。
      *
-     * @param value source value
-     * @param times left shift steps
-     * @returns return result value
+     * @param value source value / 源数值
+     * @param times number of bits to shift / 移位位数
+     * @returns shifted result / 移位结果
      */
     static left(value: number, times: number): number;
     /**
-     * number right shift
-     * times will be calculated to get the end 6-bit at the beginning to avoid over-flow
+     * Signed right-shift `value` by `times` bits.
+     * Only the lowest 6 bits of `times` are used to prevent overflow.
      *
-     * @param value source value
-     * @param times right shift steps
-     * @returns return result value
+     * 对 `value` 进行有符号右移 `times` 位。
+     * 仅使用 `times` 的低 6 位以防止溢出。
+     *
+     * @param value source value / 源数值
+     * @param times number of bits to shift / 移位位数
+     * @returns shifted result / 移位结果
      */
     static right(value: number, times: number): number;
     /**
-     * number unsigned right shift
-     * times will be calculated to get the end 6-bit at the beginning to avoid over-flow
+     * Unsigned right-shift `value` by `times` bits.
+     * Only the lowest 6 bits of `times` are used to prevent overflow.
+     *
+     * 对 `value` 进行无符号右移 `times` 位。
+     * 仅使用 `times` 的低 6 位以防止溢出。
      *
-     * @param value source value
-     * @param times right shift steps
-     * @returns return result value
+     * @param value source value / 源数值
+     * @param times number of bits to shift / 移位位数
+     * @returns shifted result / 移位结果
      */
     static rightUnsigned(value: number, times: number): number;
     /**
-     * or
+     * Bitwise OR of value1 and one or more additional values.
+     * 对 value1 与一个或多个附加值进行按位或运算。
      *
-     * @param value1 the first value
-     * @param values the following values array
-     * @returns return calculated value
+     * @param value1 the first operand / 第一个操作数
+     * @param values additional operands / 附加操作数
+     * @returns the bitwise OR result / 按位或结果
      */
     static or(value1: number, ...values: number[]): number;
     /**
-     * and
+     * Bitwise AND of value1 and one or more additional values.
+     * 对 value1 与一个或多个附加值进行按位与运算。
      *
-     * @param value1 the first value
-     * @param values the following values array
-     * @returns return calculated value
+     * @param value1 the first operand / 第一个操作数
+     * @param values additional operands / 附加操作数
+     * @returns the bitwise AND result / 按位与结果
      */
     static and(value1: number, ...values: number[]): number;
     /**
-     * xor
+     * Bitwise XOR of value1 and value2.
+     * 对 value1 和 value2 进行按位异或运算。
      *
-     * @param value1 the first value
-     * @param value2 the second value
-     * @returns return calculated value
+     * @param value1 the first operand / 第一个操作数
+     * @param value2 the second operand / 第二个操作数
+     * @returns the XOR result / 异或结果
      */
     static xor(value1: number, value2: number): number;
 }

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

@@ -1,22 +1,34 @@
 /** @format */
-/** Json Lib */
+/**
+ * JSON utility class providing safe and unsafe JSON parse helpers.
+ * JSON 工具类，提供安全与非安全的 JSON 解析帮助方法。
+ */
 export declare class Json {
     /**
-     * @deprecated
+     * @deprecated Use parseSafe instead.
      *
-     * convert a string to be a javascript object.
-     * This is an unsafe function to convert a string to be object. suggest to use parseSafe to convert string to object.
+     * Parse a JSON string into a JavaScript object.
+     * This is an unsafe operation — it throws a SyntaxError if the string is invalid.
+     * Prefer parseSafe for production use.
      *
-     * @param src source string
-     * @returns target js-object
+     * 将 JSON 字符串解析为 JavaScript 对象。
+     * 这是一个不安全的操作——若字符串无效则抛出 SyntaxError。
+     * 生产环境建议使用 parseSafe。
+     *
+     * @param src the JSON source string / JSON 源字符串
+     * @returns the parsed JavaScript object / 解析后的 JavaScript 对象
      */
     static parse(src: string): any;
     /**
-     * convert a string to be a javascript object safty
+     * Parse a JSON string into a JavaScript object safely.
+     * Returns the specified fallback value (default: null) if parsing fails.
+     *
+     * 安全地将 JSON 字符串解析为 JavaScript 对象。
+     * 解析失败时返回指定的回退值（默认为 null）。
      *
-     * @param src source string
-     * @param failed value returned when converted failed, default is null
-     * @returns target js-object
+     * @param src the JSON source string / JSON 源字符串
+     * @param failed the value to return on parse failure, defaults to null / 解析失败时的返回值，默认为 null
+     * @returns the parsed object, or the fallback value on failure / 解析后的对象，失败时返回回退值
      */
     static parseSafe(src: string, failed?: any): any | null;
 }

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

@@ -1,36 +1,60 @@
 /**@format */
-/** Object Helper of Tianyu to provide data type checking, objects comparing, validation, data clone and other functions */
+/**
+ * Object utility class providing data type checking, deep cloning,
+ * serialization validation, and multi-object comparison.
+ *
+ * 对象工具类，提供数据类型检测、深度克隆、序列化校验和多对象比较功能。
+ */
 export declare class ObjectHelper {
     /**
-     * check whether the specified value does extend from nodejs native type
+     * Check whether the given value is a JavaScript primitive type
+     * (boolean, string, number, symbol, null, or undefined).
      *
-     * @param {any} value supported value type of tianyu store
-     * @returns {boolean} return true if the value is based on type number, string, boolean, function, otherwise false
+     * 检查给定值是否为 JavaScript 原始类型
+     * （boolean、string、number、symbol、null 或 undefined）。
+     *
+     * @param value the value to inspect / 要检查的值
+     * @returns true if the value is a primitive type, false for objects and arrays
+     *          原始类型返回 true，对象和数组返回 false
      */
     static isSimpleDataType(value: any): boolean;
     /**
-     * get a deep copy from source
+     * Create a deep copy of the given value.
+     * Arrays and plain objects are recursively cloned.
+     * Throws ObjectCloneFunctionNotSupportException if the source contains a function.
+     *
+     * 创建给定值的深度副本。
+     * 数组和普通对象将递归克隆。
+     * 若源对象包含函数值，则抛出 ObjectCloneFunctionNotSupportException。
      *
-     * @param {any} sources the specified source value
-     * @returns {any} return a new value that is independent from sources
+     * @param source the value to clone / 要克隆的值
+     * @returns a new deep-copied value independent from the source / 与源对象独立的深度副本
      */
     static clone(source: any): any;
     private static _clone;
     private static _cloneArray;
     private static _cloneRecordType;
     /**
-     * Check the object whether can be stringified
+     * Verify that the given value can be safely passed through JSON.stringify.
+     * Returns false for function types or objects containing function-valued properties.
      *
-     * @param obj be checked object
-     * @returns return true is valid, otherwise false
+     * 验证给定值是否可安全通过 JSON.stringify 序列化。
+     * 函数类型或包含函数属性的对象返回 false。
+     *
+     * @param obj the value to validate / 要校验的值
+     * @returns true if the value is JSON-serializable / 可 JSON 序列化时返回 true
      */
     static validateSerializable(obj: any): boolean;
     /**
-     * Compare two or more objects are the same or different
+     * Compare two or more values for deep equality.
+     * If fewer than two arguments are provided, "same" is returned.
+     *
+     * 对两个或多个值进行深度相等性比较。
+     * 若传入参数少于两个，则返回 "same"。
      *
-     * @param objs the objects which need to be compared
-     * @returns same - if all the objects are same, different - if at least one object is not same to other objects
-     * @description if there are only one parameter or no parameter is provided, same result will be returned
+     * @param objs the values to compare / 要比较的值
+     * @returns "same" if all values are deeply equal, "different" otherwise
+     *          所有值深度相等时返回 "same"，否则返回 "different"
      */
     static compareObjects(...objs: any): "same" | "different";
     private static _compareSimpleType;

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

@@ -1,21 +1,48 @@
 /**@format */
+/**
+ * String utility class providing formatting and safe serialization helpers.
+ * 字符串工具类，提供格式化和安全序列化帮助方法。
+ */
 export declare class StringHelper {
+    /**
+     * Format a string by replacing positional placeholders `{N}` with the corresponding argument.
+     * Works similarly to C#'s String.Format.
+     *
+     * 通过将位置占位符 `{N}` 替换为对应参数来格式化字符串。
+     * 用法类似于 C# 的 String.Format。
+     *
+     * @param source the format template string containing `{0}`, `{1}`, … placeholders / 包含 `{0}`、`{1}` 等占位符的格式模板字符串
+     * @param args a single argument or an array of arguments / 单个参数或参数数组
+     * @returns the formatted string / 格式化后的字符串
+     *
+     * @example
+     * StringHelper.format("Hello, {0}! You have {1} messages.", "Alice", 5);
+     * // => "Hello, Alice! You have 5 messages."
+     */
     static format(source: string, args?: (string | number)[] | string): string;
     /**
-     * @deprecated
+     * @deprecated Use stringifySafe instead.
+     *
+     * Convert a value to a string. Throws an Error if the value is a function type.
+     * For safer usage, prefer stringifySafe which returns "" on failure.
      *
-     * convert an object to be a string.
-     * This is an unsafe function to convert an object to be string. suggest to use stringifySafe to convert object to string.
+     * 将值转换为字符串。若值为函数类型则抛出 Error。
+     * 建议使用更安全的 stringifySafe，失败时返回 ""。
      *
-     * @param src source object
-     * @returns target string
+     * @param data the value to convert / 要转换的值
+     * @returns the string representation / 字符串表示
      */
     static stringify(data: any): string;
     /**
-     * convert an object to be a string safty. empty string will be return when error occurs in converting
+     * Convert a value to a string safely.
+     * Returns an empty string if any error occurs during conversion
+     * (e.g. circular references or function types).
+     *
+     * 安全地将值转换为字符串。
+     * 若转换过程中发生任何错误（如循环引用或函数类型），则返回空字符串。
      *
-     * @param src source object
-     * @returns target string
+     * @param data the value to convert / 要转换的值
+     * @returns the string representation, or "" on failure / 字符串表示，失败时返回 ""
      */
     static stringifySafe(data: any): string;
 }

package/dist/types/index.d.ts

@@ -1,31 +1,75 @@
 /**@format */
+/**
+ * @aitianyu.cn/types — Public API entry point
+ *
+ * This file re-exports every public symbol from the library.
+ * Import from this package directly rather than from sub-paths.
+ *
+ * @aitianyu.cn/types — 公共 API 入口
+ *
+ * 本文件重新导出库中所有公共符号。
+ * 请直接从本包导入，而非从子路径导入。
+ *
+ * @example
+ * import { guid, Log, StringHelper, TOTP } from "@aitianyu.cn/types";
+ */
+/** International area code enum. / 国际区域码枚举。 */
 export { AreaCode } from "./types/AreaCode";
+/** Base exception class for all custom errors. / 所有自定义异常的基类。 */
 export { Exception } from "./types/Exception";
+/** Log level enum and log/performance recorder interfaces. / 日志级别枚举及日志/性能记录器接口。 */
 export { LogLevel, type ILog, type IPerfRecorder } from "./types/Logs";
+/** Object diff info interface and diff map type. / 对象差异信息接口和差异映射类型。 */
 export { type IObjectDiffInfo, type ObjectDiffMap } from "./types/Object";
+/** Abstract path base class. / 抽象路径基类。 */
 export { PathBase } from "./types/PathBase";
+/** Encryption option enum and cipher interface. / 加密选项枚举和密码接口。 */
 export { EncryptOption, type ICipher } from "./types/Security";
+/** Generic comparable-key map. / 支持可比较键的泛型映射表。 */
 export { TMap } from "./types/TMap";
+/** Common generic types and interfaces. / 通用泛型类型与接口。 */
 export { type MapOfBoolean, type MapOfStrings, type MapOfString, type MapOfType, type CallbackAction, type CallbackActionT, type IComparable, type KeyValuePair, } from "./types/Types";
+/** Path-related exception classes. / 路径相关异常类。 */
 export { PathProcessorSourceLostException, PathDirectoryValidationFailException, PathDirAndFileConvertInvaild, } from "./coding/Error";
+/** Path type and Path class. / 路径类型及 Path 类。 */
 export { type PathTargetType, Path } from "./coding/Path";
+/** Core exception classes for argument and object operations. / 参数和对象操作的核心异常类。 */
 export { ArgumentNullOrEmptyException, ObjectCloneFunctionNotSupportException, ObjectMergeStatusCheckFailedException, ObjectDiffApplyInvalidStatusException, ObjectDiffMergeFailedException, } from "./core/Errors";
+/** Area code ↔ string conversion helpers. / 区域码与字符串的转换帮助函数。 */
 export { parseAreaCode, parseAreaString } from "./core/Language";
+/** Global log instance and performance tracker. / 全局日志实例和性能跟踪器。 */
 export { Log, Performance } from "./core/Log";
+/** Type conversion helpers. / 类型转换帮助函数。 */
 export { getBoolean } from "./core/TypeConvertion";
+/** Runtime environment detection. / 运行时环境检测。 */
 export { Environment } from "./core/Environment";
+/** Object diff calculation and merge. / 对象差异计算与合并。 */
 export { ObjectCalculater } from "./core/object/Calculater";
+/** Deep clone, compare, and serialization validation. / 深度克隆、比较和序列化校验。 */
 export { ObjectHelper } from "./core/object/ObjectHelper";
+/** Array merge and deduplication. / 数组合并与去重。 */
 export { ArrayHelper } from "./core/object/ArrayHelper";
+/** String formatting and safe serialization. / 字符串格式化和安全序列化。 */
 export { StringHelper } from "./core/object/StringHelper";
+/** Random byte buffer generation. / 随机字节缓冲区生成。 */
 export { Bytes } from "./core/object/Bytes";
+/** Binary DataView parsing helper. / 二进制 DataView 解析帮助工具。 */
 export { DataView } from "./core/object/DataView";
+/** Bitwise operations and random integer generation. / 位运算和随机整数生成。 */
 export { Integer } from "./core/object/Integer";
+/** Safe JSON parsing helpers. / 安全 JSON 解析帮助工具。 */
 export { Json } from "./core/object/Json";
+/** Base32 encoding/decoding (RFC3548, RFC4648, RFC4648-HEX, Crockford). / Base32 编解码。 */
 export { Base32 } from "./security/Base32";
+/** UUID v4 generation. / UUID v4 生成。 */
 export { guid } from "./security/Guid";
+/** 32-bit string hash code generation. / 32 位字符串哈希码生成。 */
 export { hash } from "./security/Hash";
+/** Async QR code image generation (base64 data URL). / 异步二维码图片生成（base64 data URL）。 */
 export { QRCode } from "./security/QRCode";
+/** RSA key-pair generation and directional encryption/decryption. / RSA 密钥对生成及方向性加密/解密。 */
 export { RSA } from "./security/RSA";
+/** SHA-256 / SHA-512 hashing for data and streams. / 数据和流的 SHA-256 / SHA-512 哈希计算。 */
 export { SHA } from "./security/SHA";
+/** Time-based One-Time Password generation (RFC 6238). / 基于时间的一次性密码生成（RFC 6238）。 */
 export { TOTP } from "./security/TOTP";

package/dist/types/security/Base32.d.ts

@@ -1,40 +1,53 @@
 /** @format */
 /**
- * Base32 Encoding Type
+ * Base32 encoding format type.
+ * Base32 编码格式类型。
  *
- * @field RFC3548
- * @field RFC4648
- * @field RFC4648-HEX
- * @field Crockford
+ * - RFC3548 / RFC4648: Standard alphabet A–Z + 2–7 with "=" padding.
+ * - RFC4648-HEX: Extended hex alphabet 0–9 + A–V.
+ * - Crockford: Human-friendly alphabet; treats O→0, I/L→1; no padding.
+ *
+ * - RFC3548 / RFC4648：标准字母表 A–Z + 2–7，使用 "=" 填充。
+ * - RFC4648-HEX：扩展十六进制字母表 0–9 + A–V。
+ * - Crockford：人类友好字母表；将 O→0、I/L→1；无填充。
  */
 export type EncodingType = "RFC3548" | "RFC4648" | "RFC4648-HEX" | "Crockford";
-/** Base32 Encoding Lib */
+/**
+ * Base32 encoding/decoding utility class.
+ * Supports RFC3548, RFC4648, RFC4648-HEX, and Crockford encoding formats.
+ *
+ * Base32 编解码工具类。
+ * 支持 RFC3548、RFC4648、RFC4648-HEX 和 Crockford 编码格式。
+ */
 export declare class Base32 {
     private static RFC4648_CHS;
     private static RFC4648_HEX_CHS;
     private static CROCKFORD_CHS;
     /**
-     * To encode the buffer to be a Base32 encoded string
+     * Encode a binary buffer to a Base32 string using the specified encoding format.
+     * 使用指定的编码格式将二进制缓冲区编码为 Base32 字符串。
      *
-     * @param data input source buffer
-     * @param encoding encoding type
-     * @returns return the encoded string
+     * @param data the input buffer to encode / 要编码的输入缓冲区
+     * @param encoding the Base32 encoding format to use / 要使用的 Base32 编码格式
+     * @returns the Base32-encoded string / Base32 编码后的字符串
      */
     static encode(data: ArrayBuffer | Int8Array | Uint8Array | Uint8ClampedArray, encoding: EncodingType): string;
     /**
-     * Decode the input string to be an array buffer
+     * Decode a Base32 string back to an ArrayBuffer using the specified encoding format.
+     * 使用指定的编码格式将 Base32 字符串解码还原为 ArrayBuffer。
      *
-     * @param input source string
-     * @param encoding encoding type
-     * @returns return the target array buffer
+     * @param input the Base32-encoded source string / Base32 编码的源字符串
+     * @param encoding the encoding format used to encode the string / 字符串编码时使用的格式
+     * @returns the decoded ArrayBuffer / 解码后的 ArrayBuffer
      */
     static decode(input: string, encoding: EncodingType): ArrayBuffer;
     /**
-     * Get a random string which is encoded by given encoding type
+     * Generate a random Base32-encoded string from cryptographically random bytes.
+     * 从密码学安全随机字节生成随机 Base32 编码字符串。
      *
-     * @param size random bytes size
-     * @param encoding encoding type
-     * @returns return encoded random string
+     * @param size the number of random bytes to generate before encoding / 编码前生成的随机字节数
+     * @param encoding the encoding format to use, defaults to RFC4648 / 要使用的编码格式，默认为 RFC4648
+     * @returns the random Base32-encoded string / 随机 Base32 编码字符串
      */
     static random(size: number, encoding?: EncodingType): string;
     private static getAlphabet;

package/dist/types/security/Guid.d.ts

@@ -1,4 +1,22 @@
 /**@format */
+/** Output format for the generated GUID. / 生成 GUID 的输出格式。 */
 export type GuidType = "none" | "default";
-/** Generate a Guid value string */
+/**
+ * Generate a UUID v4 string.
+ * Uses a combination of the current time and high-resolution performance counter
+ * as a random seed to maximise uniqueness.
+ *
+ * 生成 UUID v4 字符串。
+ * 使用当前时间与高精度性能计数器的组合作为随机种子，以最大化唯一性。
+ *
+ * @param type the output format:
+ *   - "default" (default) — standard hyphenated form "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"
+ *   - "none" — compact form without hyphens
+ *
+ *   输出格式：
+ *   - "default"（默认）—— 标准连字符形式 "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"
+ *   - "none" —— 无连字符的紧凑形式
+ *
+ * @returns the UUID string / UUID 字符串
+ */
 export declare function guid(type?: GuidType): string;

package/dist/types/security/Hash.d.ts

@@ -1,3 +1,12 @@
 /**@format */
-/** Generate a hash code number of the string */
+/**
+ * Generate a 32-bit integer hash code from the given string.
+ * Uses a djb2-style rolling hash algorithm over the character codes.
+ *
+ * 从给定字符串生成 32 位整数哈希码。
+ * 使用基于字符码的 djb2 风格滚动哈希算法。
+ *
+ * @param source the input string / 输入字符串
+ * @returns a 32-bit integer hash code / 32 位整数哈希码
+ */
 export declare function hash(source: string): number;

package/dist/types/security/QRCode.d.ts

@@ -1,11 +1,23 @@
 /** @format */
-/** QR code Lib */
+/**
+ * QR code generation utility class.
+ * Wraps the `qrcode` library to provide an async base64 data-URL API.
+ *
+ * 二维码生成工具类。
+ * 封装 `qrcode` 库，提供异步 base64 data-URL 接口。
+ */
 export declare class QRCode {
     /**
-     * Async getting a base64 URL of given text
+     * Asynchronously generate a base64-encoded PNG data URL for the given text.
+     * The returned data URL can be used directly as an `<img src="...">` attribute.
+     * Returns an empty string if QR code generation fails.
      *
-     * @param text source text
-     * @returns return base64 URL string
+     * 异步为给定文本生成 base64 编码的 PNG data URL。
+     * 返回的 data URL 可直接用作 `<img src="...">` 属性值。
+     * 若二维码生成失败则返回空字符串。
+     *
+     * @param text the text or URL to encode into the QR code / 要编码为二维码的文本或 URL
+     * @returns a Promise that resolves to the base64 data URL, or "" on error / 解析为 base64 data URL 的 Promise，出错时为 ""
      */
     static getURL(text: string): Promise<string>;
 }