@nsnanocat/util 2.1.0 → 2.1.1

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 = {}) {
 	// 初始化参数