@aitianyu.cn/types 0.1.2 → 0.1.3

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

@@ -2,7 +2,26 @@
 /**@format */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StringHelper = void 0;
+/**
+ * String utility class providing formatting and safe serialization helpers.
+ * 字符串工具类，提供格式化和安全序列化帮助方法。
+ */
 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, args) {
         if (!args) {
             return source;
@@ -19,13 +38,16 @@ class StringHelper {
         });
     }
     /**
-     * @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) {
         const type = typeof data;
@@ -44,10 +66,15 @@ class StringHelper {
         return JSON.stringify(data);
     }
     /**
-     * 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) {
         try {

package/dist/lib/index.js

@@ -2,73 +2,114 @@
 /**@format */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TOTP = exports.SHA = exports.RSA = exports.QRCode = exports.hash = exports.guid = exports.Base32 = exports.Json = exports.Integer = exports.DataView = exports.Bytes = exports.StringHelper = exports.ArrayHelper = exports.ObjectHelper = exports.ObjectCalculater = exports.Environment = exports.getBoolean = exports.Performance = exports.Log = exports.parseAreaString = exports.parseAreaCode = exports.ObjectDiffMergeFailedException = exports.ObjectDiffApplyInvalidStatusException = exports.ObjectMergeStatusCheckFailedException = exports.ObjectCloneFunctionNotSupportException = exports.ArgumentNullOrEmptyException = exports.Path = exports.PathDirAndFileConvertInvaild = exports.PathDirectoryValidationFailException = exports.PathProcessorSourceLostException = exports.TMap = exports.EncryptOption = exports.PathBase = exports.LogLevel = exports.Exception = exports.AreaCode = void 0;
-// src/types
+/**
+ * @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";
+ */
+// ─── Type definitions / 类型定义 ────────────────────────────────────────────
+/** International area code enum. / 国际区域码枚举。 */
 var AreaCode_1 = require("./types/AreaCode");
 Object.defineProperty(exports, "AreaCode", { enumerable: true, get: function () { return AreaCode_1.AreaCode; } });
+/** Base exception class for all custom errors. / 所有自定义异常的基类。 */
 var Exception_1 = require("./types/Exception");
 Object.defineProperty(exports, "Exception", { enumerable: true, get: function () { return Exception_1.Exception; } });
+/** Log level enum and log/performance recorder interfaces. / 日志级别枚举及日志/性能记录器接口。 */
 var Logs_1 = require("./types/Logs");
 Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return Logs_1.LogLevel; } });
+/** Abstract path base class. / 抽象路径基类。 */
 var PathBase_1 = require("./types/PathBase");
 Object.defineProperty(exports, "PathBase", { enumerable: true, get: function () { return PathBase_1.PathBase; } });
+/** Encryption option enum and cipher interface. / 加密选项枚举和密码接口。 */
 var Security_1 = require("./types/Security");
 Object.defineProperty(exports, "EncryptOption", { enumerable: true, get: function () { return Security_1.EncryptOption; } });
+/** Generic comparable-key map. / 支持可比较键的泛型映射表。 */
 var TMap_1 = require("./types/TMap");
 Object.defineProperty(exports, "TMap", { enumerable: true, get: function () { return TMap_1.TMap; } });
-// utilities
-// coding
+// ─── Coding utilities / 编码工具 ─────────────────────────────────────────────
+/** Path-related exception classes. / 路径相关异常类。 */
 var Error_1 = require("./coding/Error");
 Object.defineProperty(exports, "PathProcessorSourceLostException", { enumerable: true, get: function () { return Error_1.PathProcessorSourceLostException; } });
 Object.defineProperty(exports, "PathDirectoryValidationFailException", { enumerable: true, get: function () { return Error_1.PathDirectoryValidationFailException; } });
 Object.defineProperty(exports, "PathDirAndFileConvertInvaild", { enumerable: true, get: function () { return Error_1.PathDirAndFileConvertInvaild; } });
+/** Path type and Path class. / 路径类型及 Path 类。 */
 var Path_1 = require("./coding/Path");
 Object.defineProperty(exports, "Path", { enumerable: true, get: function () { return Path_1.Path; } });
-// core
+// ─── Core utilities / 核心工具 ───────────────────────────────────────────────
+/** Core exception classes for argument and object operations. / 参数和对象操作的核心异常类。 */
 var Errors_1 = require("./core/Errors");
 Object.defineProperty(exports, "ArgumentNullOrEmptyException", { enumerable: true, get: function () { return Errors_1.ArgumentNullOrEmptyException; } });
 Object.defineProperty(exports, "ObjectCloneFunctionNotSupportException", { enumerable: true, get: function () { return Errors_1.ObjectCloneFunctionNotSupportException; } });
 Object.defineProperty(exports, "ObjectMergeStatusCheckFailedException", { enumerable: true, get: function () { return Errors_1.ObjectMergeStatusCheckFailedException; } });
 Object.defineProperty(exports, "ObjectDiffApplyInvalidStatusException", { enumerable: true, get: function () { return Errors_1.ObjectDiffApplyInvalidStatusException; } });
 Object.defineProperty(exports, "ObjectDiffMergeFailedException", { enumerable: true, get: function () { return Errors_1.ObjectDiffMergeFailedException; } });
+/** Area code ↔ string conversion helpers. / 区域码与字符串的转换帮助函数。 */
 var Language_1 = require("./core/Language");
 Object.defineProperty(exports, "parseAreaCode", { enumerable: true, get: function () { return Language_1.parseAreaCode; } });
 Object.defineProperty(exports, "parseAreaString", { enumerable: true, get: function () { return Language_1.parseAreaString; } });
+/** Global log instance and performance tracker. / 全局日志实例和性能跟踪器。 */
 var Log_1 = require("./core/Log");
 Object.defineProperty(exports, "Log", { enumerable: true, get: function () { return Log_1.Log; } });
 Object.defineProperty(exports, "Performance", { enumerable: true, get: function () { return Log_1.Performance; } });
+/** Type conversion helpers. / 类型转换帮助函数。 */
 var TypeConvertion_1 = require("./core/TypeConvertion");
 Object.defineProperty(exports, "getBoolean", { enumerable: true, get: function () { return TypeConvertion_1.getBoolean; } });
+/** Runtime environment detection. / 运行时环境检测。 */
 var Environment_1 = require("./core/Environment");
 Object.defineProperty(exports, "Environment", { enumerable: true, get: function () { return Environment_1.Environment; } });
-//// object
+// ─── Object helpers / 对象帮助工具 ───────────────────────────────────────────
+/** Object diff calculation and merge. / 对象差异计算与合并。 */
 var Calculater_1 = require("./core/object/Calculater");
 Object.defineProperty(exports, "ObjectCalculater", { enumerable: true, get: function () { return Calculater_1.ObjectCalculater; } });
+/** Deep clone, compare, and serialization validation. / 深度克隆、比较和序列化校验。 */
 var ObjectHelper_1 = require("./core/object/ObjectHelper");
 Object.defineProperty(exports, "ObjectHelper", { enumerable: true, get: function () { return ObjectHelper_1.ObjectHelper; } });
+/** Array merge and deduplication. / 数组合并与去重。 */
 var ArrayHelper_1 = require("./core/object/ArrayHelper");
 Object.defineProperty(exports, "ArrayHelper", { enumerable: true, get: function () { return ArrayHelper_1.ArrayHelper; } });
+/** String formatting and safe serialization. / 字符串格式化和安全序列化。 */
 var StringHelper_1 = require("./core/object/StringHelper");
 Object.defineProperty(exports, "StringHelper", { enumerable: true, get: function () { return StringHelper_1.StringHelper; } });
+/** Random byte buffer generation. / 随机字节缓冲区生成。 */
 var Bytes_1 = require("./core/object/Bytes");
 Object.defineProperty(exports, "Bytes", { enumerable: true, get: function () { return Bytes_1.Bytes; } });
+/** Binary DataView parsing helper. / 二进制 DataView 解析帮助工具。 */
 var DataView_1 = require("./core/object/DataView");
 Object.defineProperty(exports, "DataView", { enumerable: true, get: function () { return DataView_1.DataView; } });
+/** Bitwise operations and random integer generation. / 位运算和随机整数生成。 */
 var Integer_1 = require("./core/object/Integer");
 Object.defineProperty(exports, "Integer", { enumerable: true, get: function () { return Integer_1.Integer; } });
+/** Safe JSON parsing helpers. / 安全 JSON 解析帮助工具。 */
 var Json_1 = require("./core/object/Json");
 Object.defineProperty(exports, "Json", { enumerable: true, get: function () { return Json_1.Json; } });
-// security
+// ─── Security utilities / 安全工具 ──────────────────────────────────────────
+/** Base32 encoding/decoding (RFC3548, RFC4648, RFC4648-HEX, Crockford). / Base32 编解码。 */
 var Base32_1 = require("./security/Base32");
 Object.defineProperty(exports, "Base32", { enumerable: true, get: function () { return Base32_1.Base32; } });
+/** UUID v4 generation. / UUID v4 生成。 */
 var Guid_1 = require("./security/Guid");
 Object.defineProperty(exports, "guid", { enumerable: true, get: function () { return Guid_1.guid; } });
+/** 32-bit string hash code generation. / 32 位字符串哈希码生成。 */
 var Hash_1 = require("./security/Hash");
 Object.defineProperty(exports, "hash", { enumerable: true, get: function () { return Hash_1.hash; } });
+/** Async QR code image generation (base64 data URL). / 异步二维码图片生成（base64 data URL）。 */
 var QRCode_1 = require("./security/QRCode");
 Object.defineProperty(exports, "QRCode", { enumerable: true, get: function () { return QRCode_1.QRCode; } });
+/** RSA key-pair generation and directional encryption/decryption. / RSA 密钥对生成及方向性加密/解密。 */
 var RSA_1 = require("./security/RSA");
 Object.defineProperty(exports, "RSA", { enumerable: true, get: function () { return RSA_1.RSA; } });
+/** SHA-256 / SHA-512 hashing for data and streams. / 数据和流的 SHA-256 / SHA-512 哈希计算。 */
 var SHA_1 = require("./security/SHA");
 Object.defineProperty(exports, "SHA", { enumerable: true, get: function () { return SHA_1.SHA; } });
+/** Time-based One-Time Password generation (RFC 6238). / 基于时间的一次性密码生成（RFC 6238）。 */
 var TOTP_1 = require("./security/TOTP");
 Object.defineProperty(exports, "TOTP", { enumerable: true, get: function () { return TOTP_1.TOTP; } });

package/dist/lib/security/Base32.js

@@ -6,17 +6,24 @@ const Bytes_1 = require("../core/object/Bytes");
 const DataView_1 = require("../core/object/DataView");
 const Integer_1 = require("../core/object/Integer");
 const StringHelper_1 = require("../core/object/StringHelper");
-/** Base32 Encoding Lib */
+/**
+ * Base32 encoding/decoding utility class.
+ * Supports RFC3548, RFC4648, RFC4648-HEX, and Crockford encoding formats.
+ *
+ * Base32 编解码工具类。
+ * 支持 RFC3548、RFC4648、RFC4648-HEX 和 Crockford 编码格式。
+ */
 class Base32 {
     static RFC4648_CHS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
     static RFC4648_HEX_CHS = "0123456789ABCDEFGHIJKLMNOPQRSTUV";
     static CROCKFORD_CHS = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
     /**
-     * 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, encoding) {
         const alphabet = Base32.getAlphabet(encoding);
@@ -48,11 +55,12 @@ class Base32 {
         return output;
     }
     /**
-     * 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, encoding) {
         const alphabet = Base32.getAlphabet(encoding);
@@ -73,11 +81,12 @@ class Base32 {
         return output.buffer;
     }
     /**
-     * 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, encoding = "RFC4648") {
         const bytes = Bytes_1.Bytes.random(size);

package/dist/lib/security/Guid.js

@@ -7,7 +7,24 @@ const UUID_TEMPLATE = {
     none: "xxxxxxxxxxxx4xxxyxxxxxxxxxxxxxxx",
     default: "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx",
 };
-/** 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 字符串
+ */
 function guid(type = "default") {
     let d = new Date().getTime();
     if (typeof performance === "undefined") {

package/dist/lib/security/Hash.js

@@ -3,7 +3,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hash = void 0;
 const Integer_1 = require("../core/object/Integer");
-/** 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 位整数哈希码
+ */
 function hash(source) {
     let length = source.length;
     let hashCode = 0;

package/dist/lib/security/QRCode.js

@@ -26,13 +26,25 @@ var __importStar = (this && this.__importStar) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QRCode = void 0;
 const qrcode = __importStar(require("qrcode"));
-/** QR code Lib */
+/**
+ * QR code generation utility class.
+ * Wraps the `qrcode` library to provide an async base64 data-URL API.
+ *
+ * 二维码生成工具类。
+ * 封装 `qrcode` 库，提供异步 base64 data-URL 接口。
+ */
 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 async getURL(text) {
         return new Promise((resolve) => {

package/dist/lib/security/RSA.js

@@ -3,13 +3,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RSA = void 0;
 const crypto_1 = require("crypto");
-/** RSA Lib */
+/**
+ * RSA encryption/decryption utility class.
+ * Provides key-pair generation and four directional encryption operations
+ * (public→private, private→public, and their reverses).
+ *
+ * RSA 加密/解密工具类。
+ * 提供密钥对生成及四种方向的加密操作
+ * （公钥→私钥、私钥→公钥，及各自的反向解密）。
+ */
 class RSA {
     /**
-     * To get a new RSA public key and private key
+     * Generate a new RSA public/private key pair.
+     * 生成新的 RSA 公私密钥对。
      *
-     * @param options RSA key generation option
-     * @returns return new RSA key
+     * @param options RSA key generation options (modulus length, format, etc.) / RSA 密钥生成选项（模数长度、格式等）
+     * @returns an object containing the generated private and public keys / 包含生成的私钥和公钥的对象
      */
     static new(options) {
         const { publicKey, privateKey } = (0, crypto_1.generateKeyPairSync)("rsa", options);
@@ -19,41 +28,45 @@ class RSA {
         };
     }
     /**
-     * To encode a value with public key, the encoded data can be decoded by private key
+     * Encrypt data using the public key (decryptable with the private key).
+     * 使用公钥加密数据（可用私钥解密）。
      *
-     * @param data input data
-     * @param publicKey encoding public key
-     * @returns return encoded buffer
+     * @param data the plaintext data to encrypt / 要加密的明文数据
+     * @param publicKey the RSA public key / RSA 公钥
+     * @returns the encrypted Buffer / 加密后的 Buffer
      */
     static encodepub(data, publicKey) {
         return (0, crypto_1.publicEncrypt)(publicKey, data);
     }
     /**
-     * To encode a value with private key, the encoded data can be decoded by public key
+     * Encrypt data using the private key (decryptable with the public key).
+     * 使用私钥加密数据（可用公钥解密）。
      *
-     * @param data input data
-     * @param publicKey encoding private key
-     * @returns return encoded buffer
+     * @param data the plaintext data to encrypt / 要加密的明文数据
+     * @param privateKey the RSA private key / RSA 私钥
+     * @returns the encrypted Buffer / 加密后的 Buffer
      */
     static encodepri(data, privateKey) {
         return (0, crypto_1.privateEncrypt)(privateKey, data);
     }
     /**
-     * To decode a value with public key, the value is encoded by private key
+     * Decrypt data using the public key (data was encrypted with the private key).
+     * 使用公钥解密数据（数据由私钥加密）。
      *
-     * @param data input data
-     * @param publicKey decoding public key
-     * @returns return decoded buffer
+     * @param data the encrypted data / 加密后的数据
+     * @param publicKey the RSA public key / RSA 公钥
+     * @returns the decrypted Buffer / 解密后的 Buffer
      */
     static decodepub(data, publicKey) {
         return (0, crypto_1.publicDecrypt)(publicKey, data);
     }
     /**
-     * To decode a value with private key, the value is encoded by public key
+     * Decrypt data using the private key (data was encrypted with the public key).
+     * 使用私钥解密数据（数据由公钥加密）。
      *
-     * @param data input data
-     * @param privateKey decoding private key
-     * @returns return decoded buffer
+     * @param data the encrypted data / 加密后的数据
+     * @param privateKey the RSA private key / RSA 私钥
+     * @returns the decrypted Buffer / 解密后的 Buffer
      */
     static decodepri(data, privateKey) {
         return (0, crypto_1.privateDecrypt)(privateKey, data);

package/dist/lib/security/SHA.js

@@ -6,24 +6,32 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SHA = void 0;
 const crypto_1 = __importDefault(require("crypto"));
-/** SHA Lib */
+/**
+ * SHA hash utility class.
+ * Provides SHA-256 and SHA-512 hashing for both buffer/string data and Node.js streams.
+ *
+ * SHA 哈希工具类。
+ * 为缓冲区/字符串数据和 Node.js 流提供 SHA-256 和 SHA-512 哈希计算。
+ */
 class SHA {
     /**
-     * Calculate SHA256 code of data based on specified string encoding.
+     * Calculate the SHA-256 hash of string or Buffer data.
+     * 计算字符串或 Buffer 数据的 SHA-256 哈希值。
      *
-     * @param data source data
-     * @param encoding string encoding type, default encoding type is 'utf-8', only used when data type is string
-     * @returns return the SHA256 code buffer
+     * @param data the source data / 源数据
+     * @param encoding string encoding used when `data` is a string; defaults to "utf-8" / 当 `data` 为字符串时使用的字符串编码，默认为 "utf-8"
+     * @returns the SHA-256 digest as a Buffer / SHA-256 摘要 Buffer
      */
     static sha256(data, encoding = "utf-8") {
         return SHA.sha("sha256", data, encoding);
     }
     /**
-     * Calculate SHA512 code of data based on specified string encoding.
+     * Calculate the SHA-512 hash of string or Buffer data.
+     * 计算字符串或 Buffer 数据的 SHA-512 哈希值。
      *
-     * @param data source data
-     * @param encoding string encoding type, default encoding type is 'utf-8', only used when data type is string
-     * @returns return the SHA256 code buffer
+     * @param data the source data / 源数据
+     * @param encoding string encoding used when `data` is a string; defaults to "utf-8" / 当 `data` 为字符串时使用的字符串编码，默认为 "utf-8"
+     * @returns the SHA-512 digest as a Buffer / SHA-512 摘要 Buffer
      */
     static sha512(data, encoding = "utf-8") {
         return SHA.sha("sha512", data, encoding);
@@ -35,19 +43,21 @@ class SHA {
         return hash.digest();
     }
     /**
-     * Calculate SHA256 code of data based on a stream
+     * Calculate the SHA-256 hash of data provided via a Node.js readable stream.
+     * 通过 Node.js 可读流提供的数据计算 SHA-256 哈希值。
      *
-     * @param stream data stream
-     * @returns return the encoded buffer
+     * @param stream the readable data stream / 可读数据流
+     * @returns a Promise that resolves to the SHA-256 digest Buffer / 解析为 SHA-256 摘要 Buffer 的 Promise
      */
     static async stream256(stream) {
         return SHA.streamSHA("sha256", stream);
     }
     /**
-     * Calculate SHA512 code of data based on a stream
+     * Calculate the SHA-512 hash of data provided via a Node.js readable stream.
+     * 通过 Node.js 可读流提供的数据计算 SHA-512 哈希值。
      *
-     * @param stream data stream
-     * @returns return the encoded buffer
+     * @param stream the readable data stream / 可读数据流
+     * @returns a Promise that resolves to the SHA-512 digest Buffer / 解析为 SHA-512 摘要 Buffer 的 Promise
      */
     static async stream512(stream) {
         return SHA.streamSHA("sha512", stream);

package/dist/lib/security/TOTP.js

@@ -9,21 +9,38 @@ const crypto_1 = __importDefault(require("crypto"));
 const Integer_1 = require("../core/object/Integer");
 const DataView_1 = require("../core/object/DataView");
 const Base32_1 = require("./Base32");
-/** TOTP Lib */
+/**
+ * Time-based One-Time Password (TOTP) utility class.
+ * Implements the TOTP algorithm as defined in RFC 6238.
+ * Compatible with standard authenticator apps (Google Authenticator, Authy, etc.).
+ *
+ * 基于时间的一次性密码（TOTP）工具类。
+ * 实现 RFC 6238 定义的 TOTP 算法。
+ * 与标准认证器应用（Google Authenticator、Authy 等）兼容。
+ */
 class TOTP {
     /**
-     * To generate a new TOTP secret key
+     * Generate a new TOTP secret key encoded in Base32 (RFC4648).
+     * The returned key should be stored securely and associated with a user account.
      *
-     * @returns TOTP secret key
+     * 生成一个以 Base32（RFC4648）编码的新 TOTP 密钥。
+     * 返回的密钥应安全存储并与用户账户关联。
+     *
+     * @returns a Base32-encoded secret key string / Base32 编码的密钥字符串
      */
     static generate() {
         return Base32_1.Base32.random(20);
     }
     /**
-     * Generate TOTP random code
+     * Generate the 6-digit TOTP code for the given secret key and time window.
+     * The default time window is the current 30-second interval (standard TOTP).
+     *
+     * 为给定密钥和时间窗口生成 6 位 TOTP 验证码。
+     * 默认时间窗口为当前的 30 秒间隔（标准 TOTP）。
      *
-     * @param key TOTP secret key
-     * @returns return TOTP random code
+     * @param key the Base32-encoded secret key / Base32 编码的密钥
+     * @param time optional Unix timestamp in milliseconds; defaults to Date.now() / 可选的 Unix 时间戳（毫秒），默认为 Date.now()
+     * @returns a 6-digit OTP string / 6 位一次性密码字符串
      */
     static code(key, time) {
         const K = Base32_1.Base32.decode(key.toUpperCase(), "RFC4648");
@@ -41,10 +58,15 @@ class TOTP {
         return code;
     }
     /**
-     * Generate a key and TOTP register URL from given user
+     * Generate a new TOTP secret and the corresponding otpauth:// URI for QR code scanning.
+     * The URI can be rendered as a QR code so users can add the account to an authenticator app.
+     *
+     * 生成新的 TOTP 密钥及对应的 otpauth:// URI，用于二维码扫描。
+     * 该 URI 可渲染为二维码，方便用户将账户添加到认证器应用。
      *
-     * @param user user name
-     * @returns return the secret key and url
+     * @param user the account username or email / 账户用户名或邮箱
+     * @param project the issuer / service name shown in the authenticator app / 显示在认证器应用中的发行方/服务名称
+     * @returns an object containing the secret key and the otpauth:// URL / 包含密钥和 otpauth:// URL 的对象
      */
     static getUrl(user, project = "tianyu-template-project") {
         const key = TOTP.generate();