@nsnanocat/util 2.0.0 → 2.1.1

package/polyfill/Lodash.mjs

@@ -1,5 +1,28 @@
 /* https://www.lodashjs.com */
+/**
+ * 轻量 Lodash 工具集。
+ * Lightweight Lodash-like utilities.
+ *
+ * 说明:
+ * Notes:
+ * - 这是 Lodash 的“部分方法”简化实现，不等价于完整 Lodash
+ * - This is a simplified subset, not a full Lodash implementation
+ * - 各方法语义可参考 Lodash 官方文档
+ * - Method semantics can be referenced from official Lodash docs
+ *
+ * 参考:
+ * Reference:
+ * - https://www.lodashjs.com
+ * - https://lodash.com
+ */
 export class Lodash {
+	/**
+	 * HTML 特殊字符转义。
+	 * Escape HTML special characters.
+	 *
+	 * @param {string} string 输入文本 / Input text.
+	 * @returns {string}
+	 */
 	static escape(string) {
 		const map = {
 			"&": "&",
@@ -11,6 +34,15 @@ export class Lodash {
 		return string.replace(/[&<>"']/g, m => map[m]);
 	}
 
+	/**
+	 * 按路径读取对象值。
+	 * Get object value by path.
+	 *
+	 * @param {object} [object={}] 目标对象 / Target object.
+	 * @param {string|string[]} [path=""] 路径 / Path.
+	 * @param {*} [defaultValue=undefined] 默认值 / Default value.
+	 * @returns {*}
+	 */
 	static get(object = {}, path = "", defaultValue = undefined) {
 		// translate array case to dot case, then split with .
 		// a[0].b -> a.0.b -> ['a', '0', 'b']
@@ -24,7 +56,9 @@ export class Lodash {
 
 	/**
 	 * 递归合并源对象的自身可枚举属性到目标对象
+	 * Recursively merge source enumerable properties into target object.
 	 * @description 简化版 lodash.merge，用于合并配置对象
+	 * @description A simplified lodash.merge for config merging.
 	 *
 	 * 适用情况:
 	 * - 合并嵌套的配置/设置对象
@@ -41,8 +75,11 @@ export class Lodash {
 	 * - 会修改原始目标对象 (mutates target)
 	 *
 	 * @param {object} object - 目标对象
+	 * @param {object} object - Target object.
 	 * @param {...object} sources - 源对象(可多个)
+	 * @param {...object} sources - Source objects.
 	 * @returns {object} 返回合并后的目标对象
+	 * @returns {object} Merged target object.
 	 * @example
 	 * const target = { a: { b: 1 }, c: 2 };
 	 * const source = { a: { d: 3 }, e: 4 };
@@ -99,8 +136,11 @@ export class Lodash {
 
 	/**
 	 * 判断值是否为普通对象 (Plain Object)
+	 * Check whether a value is a plain object.
 	 * @param {*} value - 要检查的值
+	 * @param {*} value - Value to check.
 	 * @returns {boolean} 如果是普通对象返回 true
+	 * @returns {boolean} Returns true when value is a plain object.
 	 */
 	static #isPlainObject(value) {
 		if (value === null || typeof value !== "object") return false;
@@ -108,24 +148,56 @@ export class Lodash {
 		return proto === null || proto === Object.prototype;
 	}
 
+	/**
+	 * 删除对象指定路径并返回对象。
+	 * Omit paths from object and return the same object.
+	 *
+	 * @param {object} [object={}] 目标对象 / Target object.
+	 * @param {string|string[]} [paths=[]] 要删除的路径 / Paths to remove.
+	 * @returns {object}
+	 */
 	static omit(object = {}, paths = []) {
 		if (!Array.isArray(paths)) paths = [paths.toString()];
 		paths.forEach(path => Lodash.unset(object, path));
 		return object;
 	}
 
+	/**
+	 * 仅保留对象指定键（第一层）。
+	 * Pick selected keys from object (top level only).
+	 *
+	 * @param {object} [object={}] 目标对象 / Target object.
+	 * @param {string|string[]} [paths=[]] 需要保留的键 / Keys to keep.
+	 * @returns {object}
+	 */
 	static pick(object = {}, paths = []) {
 		if (!Array.isArray(paths)) paths = [paths.toString()];
 		const filteredEntries = Object.entries(object).filter(([key, value]) => paths.includes(key));
 		return Object.fromEntries(filteredEntries);
 	}
 
+	/**
+	 * 按路径写入对象值。
+	 * Set object value by path.
+	 *
+	 * @param {object} object 目标对象 / Target object.
+	 * @param {string|string[]} path 路径 / Path.
+	 * @param {*} value 写入值 / Value.
+	 * @returns {object}
+	 */
 	static set(object, path, value) {
 		if (!Array.isArray(path)) path = Lodash.toPath(path);
 		path.slice(0, -1).reduce((previousValue, currentValue, currentIndex) => (Object(previousValue[currentValue]) === previousValue[currentValue] ? previousValue[currentValue] : (previousValue[currentValue] = /^\d+$/.test(path[currentIndex + 1]) ? [] : {})), object)[path[path.length - 1]] = value;
 		return object;
 	}
 
+	/**
+	 * 将点路径或数组下标路径转换为数组。
+	 * Convert dot/array-index path string into path segments.
+	 *
+	 * @param {string} value 路径字符串 / Path string.
+	 * @returns {string[]}
+	 */
 	static toPath(value) {
 		return value
 			.replace(/\[(\d+)\]/g, ".$1")
@@ -133,6 +205,13 @@ export class Lodash {
 			.filter(Boolean);
 	}
 
+	/**
+	 * HTML 实体反转义。
+	 * Unescape HTML entities.
+	 *
+	 * @param {string} string 输入文本 / Input text.
+	 * @returns {string}
+	 */
 	static unescape(string) {
 		const map = {
 			"&amp;": "&",
@@ -144,6 +223,14 @@ export class Lodash {
 		return string.replace(/&amp;|&lt;|&gt;|&quot;|&#39;/g, m => map[m]);
 	}
 
+	/**
+	 * 删除对象路径对应的值。
+	 * Remove value by object path.
+	 *
+	 * @param {object} [object={}] 目标对象 / Target object.
+	 * @param {string|string[]} [path=""] 路径 / Path.
+	 * @returns {boolean}
+	 */
 	static unset(object = {}, path = "") {
 		if (!Array.isArray(path)) path = Lodash.toPath(path);
 		const result = path.reduce((previousValue, currentValue, currentIndex) => {

package/polyfill/StatusTexts.mjs

@@ -1,3 +1,20 @@
+/**
+ * HTTP 状态码文本映射表。
+ * HTTP status code to status text map.
+ *
+ * 主要用途:
+ * Primary usage:
+ * - 为 Quantumult X 的 `$done` 状态行拼接提供状态文本
+ * - Provide status text for Quantumult X `$done` status-line composition
+ * - QX 在部分场景要求 `status` 为完整状态行（如 `HTTP/1.1 200 OK`）
+ * - QX may require full status line (e.g. `HTTP/1.1 200 OK`) in some cases
+ *
+ * 参考:
+ * Reference:
+ * - https://github.com/crossutility/Quantumult-X/raw/refs/heads/master/sample-rewrite-response-header.js
+ *
+ * @type {Record<number, string>}
+ */
 export const StatusTexts = {
 	100: "Continue",
 	101: "Switching Protocols",

package/polyfill/Storage.mjs

@@ -2,36 +2,70 @@ import { $app } from "../lib/app.mjs";
 import { Lodash as _ } from "./Lodash.mjs";
 
 /**
- * Storage
+ * 跨平台持久化存储适配器。
+ * Cross-platform persistent storage adapter.
  *
- * @link https://developer.mozilla.org/zh-CN/docs/Web/API/Storage/setItem
- * @export
- * @class Storage
- * @typedef {Storage}
+ * 设计目标:
+ * Design goal:
+ * - 仿照 Web Storage (`Storage`) 接口设计
+ * - Modeled after Web Storage (`Storage`) interface
+ * - 统一 VPN App 脚本环境中的持久化读写接口
+ * - Unify persistence APIs across VPN app script environments
+ *
+ * 支持后端:
+ * Supported backends:
+ * - Surge/Loon/Stash/Egern/Shadowrocket: `$persistentStore`
+ * - Quantumult X: `$prefs`
+ * - Node.js: 本地 `box.dat`
+ * - Node.js: local `box.dat`
+ *
+ * 支持路径键:
+ * Supports path key:
+ * - `@root.path.to.value`
+ *
+ * 与 Web Storage 的已知差异:
+ * Known differences from Web Storage:
+ * - 支持 `@key.path` 深路径读写（Web Storage 原生不支持）
+ * - Supports `@key.path` deep-path access (not native in Web Storage)
+ * - `removeItem/clear` 并非所有平台都可用
+ * - `removeItem/clear` are not available on every platform
+ * - 读取时会尝试 `JSON.parse`，写入对象会 `JSON.stringify`
+ * - Reads try `JSON.parse`, writes stringify objects
+ *
+ * @link https://developer.mozilla.org/en-US/docs/Web/API/Storage
+ * @link https://developer.mozilla.org/zh-CN/docs/Web/API/Storage
  */
 export class Storage {
 	/**
-	 * data
+	 * Node.js 环境下的内存数据缓存。
+	 * In-memory data cache for Node.js runtime.
 	 *
-	 * @static
-	 * @type {file}
+	 * @type {Record<string, any>|null}
 	 */
 	static data = null;
+
+	/**
+	 * Node.js 持久化文件名。
+	 * Data file name used in Node.js.
+	 *
+	 * @type {string}
+	 */
 	static dataFile = "box.dat";
+
 	/**
-	 * nameRegex
+	 * `@key.path` 解析正则。
+	 * Regex for `@key.path` parsing.
 	 *
-	 * @static
-	 * @type {regexp}
+	 * @type {RegExp}
 	 */
 	static #nameRegex = /^@(?<key>[^.]+)(?:\.(?<path>.*))?$/;
 
 	/**
-	 * getItem
+	 * 读取存储值。
+	 * Read value from persistent storage.
 	 *
-	 * @static
-	 * @param {string} keyName
-	 * @param {*} [defaultValue]
+	 * @param {string} keyName 键名或路径键 / Key or path key.
+	 * @param {*} [defaultValue=null] 默认值 / Default value when key is missing.
 	 * @returns {*}
 	 */
 	static getItem(keyName, defaultValue = null) {
@@ -80,11 +114,11 @@ export class Storage {
 	}
 
 	/**
-	 * setItem
+	 * 写入存储值。
+	 * Write value into persistent storage.
 	 *
-	 * @static
-	 * @param {string} keyName
-	 * @param {*} keyValue
+	 * @param {string} keyName 键名或路径键 / Key or path key.
+	 * @param {*} keyValue 写入值 / Value to store.
 	 * @returns {boolean}
 	 */
 	static setItem(keyName = new String(), keyValue = new String()) {
@@ -135,10 +169,10 @@ export class Storage {
 	}
 
 	/**
-	 * removeItem
+	 * 删除存储值。
+	 * Remove value from persistent storage.
 	 *
-	 * @static
-	 * @param {string} keyName
+	 * @param {string} keyName 键名或路径键 / Key or path key.
 	 * @returns {boolean}
 	 */
 	static removeItem(keyName) {
@@ -178,9 +212,9 @@ export class Storage {
 	}
 
 	/**
-	 * clear
+	 * 清空存储（仅 Quantumult X 支持）。
+	 * Clear storage (supported by Quantumult X only).
 	 *
-	 * @static
 	 * @returns {boolean}
 	 */
 	static clear() {
@@ -207,10 +241,12 @@ export class Storage {
 	}
 
 	/**
-	 * #loaddata
+	 * 从 Node.js 数据文件加载 JSON。
+	 * Load JSON data from Node.js data file.
 	 *
-	 * @param {string} dataFile
-	 * @returns {*}
+	 * @private
+	 * @param {string} dataFile 数据文件名 / Data file name.
+	 * @returns {Record<string, any>}
 	 */
 	static #loaddata = dataFile => {
 		if ($app === "Node.js") {
@@ -232,9 +268,12 @@ export class Storage {
 	};
 
 	/**
-	 * #writedata
+	 * 将内存数据写入 Node.js 数据文件。
+	 * Persist in-memory data to Node.js data file.
 	 *
-	 * @param {string} [dataFile=this.dataFile]
+	 * @private
+	 * @param {string} [dataFile=this.dataFile] 数据文件名 / Data file name.
+	 * @returns {void}
 	 */
 	static #writedata = (dataFile = this.dataFile) => {
 		if ($app === "Node.js") {

package/polyfill/fetch.mjs

@@ -4,14 +4,69 @@ import { Lodash as _ } from "./Lodash.mjs";
 import { StatusTexts } from "./StatusTexts.mjs";
 
 /**
- * fetch
+ * 统一请求参数。
+ * Unified request payload.
  *
- * @link https://developer.mozilla.org/zh-CN/docs/Web/API/Fetch_API
- * @export
+ * @typedef {object} FetchRequest
+ * @property {string} url 请求地址 / Request URL.
+ * @property {string} [method] 请求方法 / HTTP method.
+ * @property {Record<string, any>} [headers] 请求头 / Request headers.
+ * @property {string|ArrayBuffer|ArrayBufferView|object} [body] 请求体 / Request body.
+ * @property {ArrayBuffer} [bodyBytes] 二进制请求体 / Binary request body.
+ * @property {number|string} [timeout] 超时（秒或毫秒）/ Timeout (seconds or milliseconds).
+ * @property {string} [policy] 指定策略 / Preferred policy.
+ * @property {boolean} [redirection] 是否跟随重定向 / Whether to follow redirects.
+ * @property {boolean} ["auto-redirect"] 平台重定向字段 / Platform redirect flag.
+ * @property {Record<string, any>} [opts] 平台扩展字段 / Platform extension fields.
+ */
+
+/**
+ * 统一响应结构。
+ * Unified response payload.
+ *
+ * @typedef {object} FetchResponse
+ * @property {boolean} ok 请求是否成功 / Whether request is successful.
+ * @property {number} status 状态码 / HTTP status code.
+ * @property {number} [statusCode] 状态码别名 / Status code alias.
+ * @property {string} [statusText] 状态文本 / HTTP status text.
+ * @property {Record<string, any>} [headers] 响应头 / Response headers.
+ * @property {string|ArrayBuffer} [body] 响应体 / Response body.
+ * @property {ArrayBuffer} [bodyBytes] 二进制响应体 / Binary response body.
+ */
+
+/**
+ * 跨平台 `fetch` 适配层。
+ * Cross-platform `fetch` adapter.
+ *
+ * 设计目标:
+ * Design goal:
+ * - 仿照 Web API `fetch`（`Window.fetch`）接口设计
+ * - Modeled after Web API `fetch` (`Window.fetch`)
+ * - 统一 VPN App 与 Node.js 环境中的请求调用
+ * - Unify request calls across VPN apps and Node.js
+ *
+ * 功能:
+ * Features:
+ * - 统一 Quantumult X / Loon / Surge / Stash / Egern / Shadowrocket / Node.js 请求接口
+ * - Normalize request APIs across Quantumult X / Loon / Surge / Stash / Egern / Shadowrocket / Node.js
+ * - 统一返回体字段（`ok/status/statusText/body/bodyBytes`）
+ * - Normalize response fields (`ok/status/statusText/body/bodyBytes`)
+ *
+ * 与 Web `fetch` 的已知差异:
+ * Known differences from Web `fetch`:
+ * - 支持 `policy`、`auto-redirect` 等平台扩展字段
+ * - Supports platform extension fields like `policy` and `auto-redirect`
+ * - 非浏览器平台通过 `$httpClient/$task` 实现，不是原生 Fetch 实现
+ * - Non-browser platforms use `$httpClient/$task` instead of native Fetch engine
+ * - 返回结构包含 `statusCode/bodyBytes` 等兼容字段
+ * - Response includes compatibility fields like `statusCode/bodyBytes`
+ *
+ * @link https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch
+ * @link https://developer.mozilla.org/zh-CN/docs/Web/API/Window/fetch
  * @async
- * @param {object|string} resource
- * @param {object} [options]
- * @returns {Promise<object>}
+ * @param {FetchRequest|string} resource 请求对象或 URL / Request object or URL string.
+ * @param {Partial<FetchRequest>} [options={}] 追加参数 / Extra options.
+ * @returns {Promise<FetchResponse>}
  */
 export async function fetch(resource, options = {}) {
 	// 初始化参数