@nsnanocat/util 2.6.2 → 2.6.4

package/README.md

@@ -90,6 +90,7 @@ import {
 - `lib/environment.mjs`
 - `lib/runScript.mjs`
 - `getStorage.mjs`（薯条项目自用，仅当你的存储结构与薯条项目一致时再使用；请通过子路径 `@nsnanocat/util/getStorage.mjs` 导入）
+- `polyfill/Storage.cjs`（Node.js / Worker CJS 入口；请通过子路径 `@nsnanocat/util/polyfill/Storage` 导入）
 
 ## 模块依赖关系
 
@@ -108,7 +109,7 @@ import {
 | `getStorage.mjs` | `lib/argument.mjs`, `polyfill/Console.mjs`, `polyfill/Lodash.mjs`, `polyfill/Storage.mjs` | `Console.debug`, `Console.logLevel`, `Lodash.merge`, `Storage.getItem` | 先标准化 `$argument`，再合并默认配置/持久化配置/运行参数 |
 | `polyfill/Console.mjs` | `lib/app.mjs` | `$app` | 日志在 Worker / Node.js 与 iOS 脚本环境使用不同错误输出策略 |
 | `polyfill/fetch.mjs` | `lib/app.mjs`, `polyfill/Lodash.mjs`, `polyfill/StatusTexts.mjs`, `polyfill/Console.mjs` | `$app`, `Lodash.set`, `StatusTexts`（`Console` 当前版本未实际调用） | 按平台选请求引擎并做参数映射、响应结构统一 |
-| `polyfill/Storage.mjs` | `lib/app.mjs`, `polyfill/Lodash.mjs` | `$app`, `Lodash.get`, `Lodash.set`, `Lodash.unset` | 按平台选持久化后端并支持 `@key.path` 读写 |
+| `polyfill/Storage.mjs` | `lib/app.mjs`, `polyfill/Lodash.mjs` | `$app`, `Lodash.get`, `Lodash.set`, `Lodash.unset` | ESM 路径下按平台选持久化后端并支持 `@key.path` 读写（Node.js 请走 `Storage.cjs`） |
 | `polyfill/Lodash.mjs` | 无 | 无 | 提供路径/合并等基础能力，被多个模块复用 |
 | `polyfill/qs.mjs` | `polyfill/Lodash.mjs` | `Lodash.get`, `Lodash.set`, `Lodash.toPath` | 提供查询字符串与对象之间的解析/序列化能力 |
 | `polyfill/StatusTexts.mjs` | 无 | 无 | 提供 HTTP 状态文案，供 `fetch/done` 使用 |
@@ -369,7 +370,11 @@ const store = getStorage("@my_box", ["YouTube", "Global"], database);
 
 ### `polyfill/fetch.mjs`
 
-`fetch` 是仿照 Web API `Window.fetch` 设计的跨平台适配实现：
+`fetch` 现已拆分为 ESM / CJS 两条运行路径：
+- `polyfill/fetch.mjs`：仅用于 iOS 脚本平台（Quantumult X / Loon / Surge / Stash / Egern / Shadowrocket）
+- `polyfill/fetch.cjs`：用于 Worker / Node.js
+
+`polyfill/fetch.mjs` 仍仿照 Web API `Window.fetch` 设计：
 - 参考文档：https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch
 - 中文文档：https://developer.mozilla.org/zh-CN/docs/Web/API/Window/fetch
 - 目标：尽量保持 Web `fetch` 调用习惯，同时补齐各平台扩展参数映射
@@ -394,7 +399,7 @@ const store = getStorage("@my_box", ["YouTube", "Global"], database);
 - `timeout`
 - `policy`
 - `redirection` / `auto-redirect`
-- `auto-cookie`（Worker / Node.js 共享分支识别；默认启用，传入 `false` / `0` / `-1` 可关闭）
+- `auto-cookie`（仅 CJS 的 Worker / Node.js 分支识别；默认启用，传入 `false` / `0` / `-1` 可关闭）
 
 说明：下表是各 App 原生 HTTP 接口的差异补充，以及本库 `fetch` 的内部映射方式。调用方使用统一入参即可。
 
@@ -408,8 +413,6 @@ const store = getStorage("@my_box", ["YouTube", "Global"], database);
 | Egern | `$httpClient[method]` | 秒 | 无专门映射 | `auto-redirect` | 同上 |
 | Shadowrocket | `$httpClient[method]` | 秒 | `headers.X-Surge-Proxy` | `auto-redirect` | 同上 |
 | Quantumult X | `$task.fetch` | 毫秒（内部乘 1000） | `opts.policy` | `opts.redirection` | `body(ArrayBuffer/TypedArray)` 转 `bodyBytes`；响应按 `Content-Type` 恢复到 `body` |
-| Worker | `globalThis.fetch`（不存在时回退 `node-fetch`）；共享 `auto-cookie` 处理 | 毫秒（内部乘 1000） | 无 | `redirect: follow/manual` | 返回 `body`(UTF-8 string) + `bodyBytes`(ArrayBuffer) |
-| Node.js | `globalThis.fetch`（不存在时回退 `node-fetch`）；默认按需包裹 `fetch-cookie` | 毫秒（内部乘 1000） | 无 | `redirect: follow/manual` | 返回 `body`(UTF-8 string) + `bodyBytes`(ArrayBuffer) |
 
 返回对象（统一后）常见字段：
 - `ok`
@@ -421,15 +424,22 @@ const store = getStorage("@my_box", ["YouTube", "Global"], database);
 - `bodyBytes`
 
 不可用/差异点：
-- `policy` 在 Surge / Egern / Worker / Node.js 分支没有额外适配逻辑。
+- `policy` 在 Surge / Egern 分支没有额外适配逻辑。
 - `redirection` 在部分平台会映射为 `auto-redirect` 或 `opts.redirection`。
-- Worker / Node.js 共享基于 `fetch` 的请求分支；若 `globalThis.fetch` 不存在则回退到 `node-fetch`，并在 `auto-cookie` 未关闭时按需包裹 `fetch-cookie`。
 - 传入 `timeout` 时，`5` 和 `5000` 都会被接受；库会先将用户输入归一化，再按平台要求转换为秒或毫秒。
 - 返回结构是统一兼容结构，不等同于浏览器 `Response` 对象。
 
+Worker / Node.js 使用说明：
+- 请通过 CJS 入口调用：`require("@nsnanocat/util").fetch` 或 `require("@nsnanocat/util/polyfill/fetch").fetch`
+- CJS 分支会处理 `auto-cookie`，并将响应归一化为 `ok/status/statusText/body/bodyBytes`
+
 ### `polyfill/Storage.mjs`
 
-`Storage` 是仿照 Web Storage 接口（`Storage`）设计的跨平台持久化适配器：
+`Storage` 已拆分为 ESM / CJS 两条运行路径：
+- `polyfill/Storage.mjs`：用于 iOS 脚本平台 + Worker
+- `polyfill/Storage.cjs`：用于 Worker / Node.js（含 `box.dat` 文件读写）
+
+`polyfill/Storage.mjs` 仍仿照 Web Storage 接口（`Storage`）设计：
 - 参考文档：https://developer.mozilla.org/en-US/docs/Web/API/Storage
 - 中文文档：https://developer.mozilla.org/zh-CN/docs/Web/API/Storage
 - 目标：统一 VPN App 脚本环境中的持久化读写接口，并尽量贴近 Web Storage 行为
@@ -447,23 +457,31 @@ const store = getStorage("@my_box", ["YouTube", "Global"], database);
 - Quantumult X：可用（`$prefs.removeValueForKey`）。
 - Surge：通过 `$persistentStore.write(null, keyName)` 删除。
 - Worker：可用（仅删除内存缓存中的对应 key，不持久化）。
-- Node.js：可用（删除 `box.dat` 中对应 key 并落盘）。
+- Node.js：ESM 路径不支持，会提示改用 CJS 入口。
 - Loon / Stash / Egern / Shadowrocket：返回 `false`。
 
 #### `Storage.clear()`
 - Quantumult X：可用（`$prefs.removeAllValues`）。
 - Worker：可用（仅清空内存缓存，不持久化）。
-- Node.js：可用（清空 `box.dat` 并落盘）。
+- Node.js：ESM 路径不支持，会提示改用 CJS 入口。
 - 其他平台：返回 `false`。
 
-#### Worker / Node.js 特性
+#### Worker 特性（ESM）
 - Worker：使用进程内内存缓存，不写文件。
+
+#### Node.js 特性（CJS）
 - 数据文件默认：`box.dat`。
 - 读取路径优先级：当前目录 -> `process.cwd()`。
 
+Node.js 使用说明：
+- 请通过 CJS 入口调用：`require("@nsnanocat/util").Storage` 或 `require("@nsnanocat/util/polyfill/Storage").Storage`
+- CJS 的 `Storage` 分支支持 `box.dat` 读写与落盘
+
 与 Web Storage 的行为差异：
 - 支持 `@key.path` 深路径读写（Web Storage 原生不支持）。
-- `removeItem/clear` 仅部分平台可用（目前为 Quantumult X、Worker、Node.js，以及 Surge 的 `removeItem`）。
+- `removeItem/clear` 仅部分平台可用：
+  - ESM 路径：Quantumult X、Worker，以及 Surge 的 `removeItem`
+  - CJS 路径：Worker、Node.js
 - `getItem` 会尝试 `JSON.parse`，`setItem` 写入对象会 `JSON.stringify`。
 
 平台后端映射：
@@ -472,8 +490,8 @@ const store = getStorage("@my_box", ["YouTube", "Global"], database);
 | --- | --- |
 | Surge / Loon / Stash / Egern / Shadowrocket | `$persistentStore.read/write` |
 | Quantumult X | `$prefs.valueForKey/setValueForKey` |
-| Worker | 进程内内存缓存 |
-| Node.js | 本地 `box.dat` |
+| Worker（ESM/CJS） | 进程内内存缓存 |
+| Node.js（仅 CJS） | 本地 `box.dat` |
 
 ### `polyfill/Console.mjs`
 

package/getStorage.mjs

@@ -1,7 +1,7 @@
 import "./lib/argument.mjs";
 import { Console } from "./polyfill/Console.mjs";
 import { Lodash as _ } from "./polyfill/Lodash.mjs";
-import { Storage } from "./polyfill/Storage.js";
+import { Storage } from "./polyfill/Storage.mjs";
 
 /**
  * 存储配置读取与合并结果。

package/index.cjs

@@ -0,0 +1,9 @@
+"use strict";
+
+const { fetch } = require("./polyfill/fetch.cjs");
+const { Storage } = require("./polyfill/Storage.cjs");
+
+module.exports = {
+	fetch,
+	Storage,
+};

package/index.js

@@ -5,11 +5,11 @@ export * from "./lib/notification.mjs";
 export * from "./lib/time.mjs";
 export * from "./lib/wait.mjs";
 export * from "./polyfill/Console.mjs";
-export * from "./polyfill/fetch.js";
+export * from "./polyfill/fetch.mjs";
 export * from "./polyfill/Lodash.mjs";
 export * from "./polyfill/qs.mjs";
 export * from "./polyfill/StatusTexts.mjs";
-export * from "./polyfill/Storage.js";
+export * from "./polyfill/Storage.mjs";
 
 /**
  * 已标准化的 `$argument` 快照。

package/package.json

@@ -14,10 +14,27 @@
   "license": "Apache-2.0",
   "bugs": "https://github.com/NSNanoCat/util/issues",
   "main": "index.js",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "require": "./index.cjs"
+    },
+    "./polyfill/fetch": {
+      "import": "./polyfill/fetch.mjs",
+      "require": "./polyfill/fetch.cjs"
+    },
+    "./polyfill/Storage": {
+      "import": "./polyfill/Storage.mjs",
+      "require": "./polyfill/Storage.cjs"
+    },
+    "./*": "./*"
+  },
   "types": "types/nsnanocat-util.d.ts",
   "scripts": {
     "tsc:build": "npx tsc",
     "test": "node --test test/*.test.js",
+    "test:fetch": "node --test test/fetch.test.js",
+    "test:fetch:cjs": "node --test test/fetch.test.cjs",
     "test:merge": "node --test test/Lodash.merge.test.js",
     "test:argument": "node --test test/argument.test.js",
     "deprecate": "npm deprecate -f '@nsnanocat/util@0.0.0-preview' \"this package has been deprecated\""
@@ -27,12 +44,17 @@
     "url": "git+https://github.com/NSNanoCat/util.git"
   },
   "files": [
+    "index.cjs",
     "index.js",
     "lib",
     "polyfill",
     "getStorage.mjs",
     "types"
   ],
+  "dependencies": {
+    "fetch-cookie": "^3.2.0",
+    "node-fetch": "^3.3.2"
+  },
   "devDependencies": {
     "@biomejs/biome": "2.4.6",
     "typescript": "^5.9.3"
@@ -41,5 +63,5 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "2.6.2"
+  "version": "2.6.4"
 }

package/polyfill/Storage.cjs

@@ -0,0 +1,220 @@
+"use strict";
+
+const { Lodash: _ } = require("./Lodash.mjs");
+
+/**
+ * 仅面向 Worker / Node.js 的持久化存储适配器（CJS 版本）。
+ * Persistent storage adapter for Worker / Node.js only (CJS version).
+ */
+class Storage {
+	/**
+	 * Worker / Node.js 环境下的内存数据缓存。
+	 * In-memory data cache for Worker / Node.js runtime.
+	 *
+	 * @type {Record<string, any>|null}
+	 */
+	static data = null;
+
+	/**
+	 * Node.js 持久化文件名。
+	 * Data file name used in Node.js.
+	 *
+	 * @type {string}
+	 */
+	static dataFile = "box.dat";
+
+	/**
+	 * `@key.path` 解析正则。
+	 * Regex for `@key.path` parsing.
+	 *
+	 * @type {RegExp}
+	 */
+	static #nameRegex = /^@(?<key>[^.]+)(?:\.(?<path>.*))?$/;
+
+	/**
+	 * 读取存储值。
+	 * Read value from persistent storage.
+	 *
+	 * @param {string} keyName 键名或路径键 / Key or path key.
+	 * @param {*} [defaultValue=null] 默认值 / Default value when key is missing.
+	 * @returns {*}
+	 */
+	static getItem(keyName, defaultValue = null) {
+		let keyValue = defaultValue;
+		switch (keyName.startsWith("@")) {
+			case true: {
+				const { key, path } = keyName.match(Storage.#nameRegex)?.groups;
+				keyName = key;
+				let value = Storage.getItem(keyName, {});
+				if (typeof value !== "object") value = {};
+				keyValue = _.get(value, path);
+				try {
+					keyValue = JSON.parse(keyValue);
+				} catch {}
+				break;
+			}
+			default:
+				if (typeof process !== "undefined" && process.versions?.node) {
+					Storage.data = Storage.#loaddata(Storage.dataFile);
+					keyValue = Storage.data?.[keyName];
+				} else {
+					Storage.data = Storage.data ?? {};
+					keyValue = Storage.data[keyName];
+				}
+				try {
+					keyValue = JSON.parse(keyValue);
+				} catch {}
+				break;
+		}
+		return keyValue ?? defaultValue;
+	}
+
+	/**
+	 * 写入存储值。
+	 * Write value into persistent storage.
+	 *
+	 * @param {string} keyName 键名或路径键 / Key or path key.
+	 * @param {*} keyValue 写入值 / Value to store.
+	 * @returns {boolean}
+	 */
+	static setItem(keyName = new String(), keyValue = new String()) {
+		let result = false;
+		switch (typeof keyValue) {
+			case "object":
+				keyValue = JSON.stringify(keyValue);
+				break;
+			default:
+				keyValue = String(keyValue);
+				break;
+		}
+		switch (keyName.startsWith("@")) {
+			case true: {
+				const { key, path } = keyName.match(Storage.#nameRegex)?.groups;
+				keyName = key;
+				let value = Storage.getItem(keyName, {});
+				if (typeof value !== "object") value = {};
+				_.set(value, path, keyValue);
+				result = Storage.setItem(keyName, value);
+				break;
+			}
+			default:
+				if (typeof process !== "undefined" && process.versions?.node) {
+					Storage.data = Storage.#loaddata(Storage.dataFile);
+					Storage.data[keyName] = keyValue;
+					Storage.#writedata(Storage.dataFile);
+					result = true;
+				} else {
+					Storage.data = Storage.data ?? {};
+					Storage.data[keyName] = keyValue;
+					result = true;
+				}
+				break;
+		}
+		return result;
+	}
+
+	/**
+	 * 删除存储值。
+	 * Remove value from persistent storage.
+	 *
+	 * @param {string} keyName 键名或路径键 / Key or path key.
+	 * @returns {boolean}
+	 */
+	static removeItem(keyName) {
+		let result = false;
+		switch (keyName.startsWith("@")) {
+			case true: {
+				const { key, path } = keyName.match(Storage.#nameRegex)?.groups;
+				keyName = key;
+				let value = Storage.getItem(keyName);
+				if (typeof value !== "object") value = {};
+				_.unset(value, path);
+				result = Storage.setItem(keyName, value);
+				break;
+			}
+			default:
+				if (typeof process !== "undefined" && process.versions?.node) {
+					Storage.data = Storage.#loaddata(Storage.dataFile);
+					delete Storage.data[keyName];
+					Storage.#writedata(Storage.dataFile);
+					result = true;
+				} else {
+					Storage.data = Storage.data ?? {};
+					delete Storage.data[keyName];
+					result = true;
+				}
+				break;
+		}
+		return result;
+	}
+
+	/**
+	 * 清空存储。
+	 * Clear storage.
+	 *
+	 * @returns {boolean}
+	 */
+	static clear() {
+		if (typeof process !== "undefined" && process.versions?.node) {
+			Storage.data = Storage.#loaddata(Storage.dataFile);
+			Storage.data = {};
+			Storage.#writedata(Storage.dataFile);
+			return true;
+		}
+		Storage.data = {};
+		return true;
+	}
+
+	/**
+	 * 从 Node.js 数据文件加载 JSON。
+	 * Load JSON data from Node.js data file.
+	 *
+	 * @private
+	 * @param {string} dataFile 数据文件名 / Data file name.
+	 * @returns {Record<string, any>}
+	 */
+	static #loaddata = dataFile => {
+		const fs = require("node:fs");
+		const path = require("node:path");
+		const curDirDataFilePath = path.resolve(dataFile);
+		const rootDirDataFilePath = path.resolve(process.cwd(), dataFile);
+		const isCurDirDataFile = fs.existsSync(curDirDataFilePath);
+		const isRootDirDataFile = !isCurDirDataFile && fs.existsSync(rootDirDataFilePath);
+		if (isCurDirDataFile || isRootDirDataFile) {
+			const datPath = isCurDirDataFile ? curDirDataFilePath : rootDirDataFilePath;
+			try {
+				return JSON.parse(fs.readFileSync(datPath));
+			} catch {
+				return {};
+			}
+		}
+		return {};
+	};
+
+	/**
+	 * 将内存数据写入 Node.js 数据文件。
+	 * Persist in-memory data to Node.js data file.
+	 *
+	 * @private
+	 * @param {string} [dataFile=this.dataFile] 数据文件名 / Data file name.
+	 * @returns {void}
+	 */
+	static #writedata = (dataFile = this.dataFile) => {
+		const fs = require("node:fs");
+		const path = require("node:path");
+		const curDirDataFilePath = path.resolve(dataFile);
+		const rootDirDataFilePath = path.resolve(process.cwd(), dataFile);
+		const isCurDirDataFile = fs.existsSync(curDirDataFilePath);
+		const isRootDirDataFile = !isCurDirDataFile && fs.existsSync(rootDirDataFilePath);
+		const jsondata = JSON.stringify(this.data);
+		if (isCurDirDataFile) {
+			fs.writeFileSync(curDirDataFilePath, jsondata);
+		} else if (isRootDirDataFile) {
+			fs.writeFileSync(rootDirDataFilePath, jsondata);
+		} else {
+			fs.writeFileSync(curDirDataFilePath, jsondata);
+		}
+	};
+}
+
+module.exports = { Storage };

package/polyfill/{Storage.js → Storage.mjs}

@@ -82,7 +82,7 @@ export class Storage {
 				keyValue = _.get(value, path);
 				try {
 					keyValue = JSON.parse(keyValue);
-				} catch (e) {}
+				} catch {}
 				break;
 			}
 			default:
@@ -102,16 +102,14 @@ export class Storage {
 						keyValue = Storage.data[keyName];
 						break;
 					case "Node.js":
-						Storage.data = Storage.#loaddata(Storage.dataFile);
-						keyValue = Storage.data?.[keyName];
-						break;
+						throw new Error(`${Storage.name}.getItem: ESM 版本不支持 Node.js，请改用 CJS 入口`);
 					default:
 						keyValue = Storage.data?.[keyName] || null;
 						break;
 				}
 				try {
 					keyValue = JSON.parse(keyValue);
-				} catch (e) {
+				} catch {
 					// do nothing
 				}
 				break;
@@ -165,11 +163,7 @@ export class Storage {
 						result = true;
 						break;
 					case "Node.js":
-						Storage.data = Storage.#loaddata(Storage.dataFile);
-						Storage.data[keyName] = keyValue;
-						Storage.#writedata(Storage.dataFile);
-						result = true;
-						break;
+						throw new Error(`${Storage.name}.setItem: ESM 版本不支持 Node.js，请改用 CJS 入口`);
 					default:
 						result = Storage.data?.[keyName] || null;
 						break;
@@ -200,7 +194,7 @@ export class Storage {
 				keyName = key;
 				let value = Storage.getItem(keyName);
 				if (typeof value !== "object") value = {};
-				keyValue = _.unset(value, path);
+				_.unset(value, path);
 				result = Storage.setItem(keyName, value);
 				break;
 			}
@@ -224,12 +218,7 @@ export class Storage {
 						result = true;
 						break;
 					case "Node.js":
-						// result = false;
-						Storage.data = Storage.#loaddata(Storage.dataFile);
-						delete Storage.data[keyName];
-						Storage.#writedata(Storage.dataFile);
-						result = true;
-						break;
+						throw new Error(`${Storage.name}.removeItem: ESM 版本不支持 Node.js，请改用 CJS 入口`);
 					default:
 						result = false;
 						break;
@@ -263,12 +252,7 @@ export class Storage {
 				result = true;
 				break;
 			case "Node.js":
-				// result = false;
-				Storage.data = Storage.#loaddata(Storage.dataFile);
-				Storage.data = {};
-				Storage.#writedata(Storage.dataFile);
-				result = true;
-				break;
+				throw new Error(`${Storage.name}.clear: ESM 版本不支持 Node.js，请改用 CJS 入口`);
 			default:
 				result = false;
 				break;
@@ -276,57 +260,4 @@ export class Storage {
 		return result;
 	}
 
-	/**
-	 * 从 Node.js 数据文件加载 JSON。
-	 * Load JSON data from Node.js data file.
-	 *
-	 * @private
-	 * @param {string} dataFile 数据文件名 / Data file name.
-	 * @returns {Record<string, any>}
-	 */
-	static #loaddata = dataFile => {
-		if ($app === "Node.js") {
-			this.fs = this.fs ? this.fs : require("fs");
-			this.path = this.path ? this.path : require("path");
-			const curDirDataFilePath = this.path.resolve(dataFile);
-			const rootDirDataFilePath = this.path.resolve(process.cwd(), dataFile);
-			const isCurDirDataFile = this.fs.existsSync(curDirDataFilePath);
-			const isRootDirDataFile = !isCurDirDataFile && this.fs.existsSync(rootDirDataFilePath);
-			if (isCurDirDataFile || isRootDirDataFile) {
-				const datPath = isCurDirDataFile ? curDirDataFilePath : rootDirDataFilePath;
-				try {
-					return JSON.parse(this.fs.readFileSync(datPath));
-				} catch (e) {
-					return {};
-				}
-			} else return {};
-		} else return {};
-	};
-
-	/**
-	 * 将内存数据写入 Node.js 数据文件。
-	 * Persist in-memory data to Node.js data file.
-	 *
-	 * @private
-	 * @param {string} [dataFile=this.dataFile] 数据文件名 / Data file name.
-	 * @returns {void}
-	 */
-	static #writedata = (dataFile = this.dataFile) => {
-		if ($app === "Node.js") {
-			this.fs = this.fs ? this.fs : require("fs");
-			this.path = this.path ? this.path : require("path");
-			const curDirDataFilePath = this.path.resolve(dataFile);
-			const rootDirDataFilePath = this.path.resolve(process.cwd(), dataFile);
-			const isCurDirDataFile = this.fs.existsSync(curDirDataFilePath);
-			const isRootDirDataFile = !isCurDirDataFile && this.fs.existsSync(rootDirDataFilePath);
-			const jsondata = JSON.stringify(this.data);
-			if (isCurDirDataFile) {
-				this.fs.writeFileSync(curDirDataFilePath, jsondata);
-			} else if (isRootDirDataFile) {
-				this.fs.writeFileSync(rootDirDataFilePath, jsondata);
-			} else {
-				this.fs.writeFileSync(curDirDataFilePath, jsondata);
-			}
-		}
-	};
 }

package/polyfill/fetch.cjs

@@ -0,0 +1,128 @@
+"use strict";
+
+/**
+ * 统一请求参数。
+ * Unified request payload.
+ *
+ * @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 {boolean} [redirection] 是否跟随重定向 / Whether to follow redirects.
+ * @property {boolean|number|string} ["auto-cookie"] Worker / Node.js Cookie 开关 / Worker / Node.js Cookie toggle.
+ */
+
+/**
+ * 统一响应结构。
+ * 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.
+ */
+
+/**
+ * 仅面向 Worker / Node.js 的 `fetch` 适配层（CJS 版本）。
+ * `fetch` adapter for Worker / Node.js only (CJS version).
+ *
+ * @async
+ * @param {FetchRequest|string} resource 请求对象或 URL / Request object or URL string.
+ * @param {Partial<FetchRequest>} [options={}] 追加参数 / Extra options.
+ * @returns {Promise<FetchResponse>}
+ */
+async function fetch(resource, options = {}) {
+	switch (typeof resource) {
+		case "object":
+			resource = { ...options, ...resource };
+			break;
+		case "string":
+			resource = { ...options, url: resource };
+			break;
+		case "undefined":
+		default:
+			throw new TypeError(`${Function.name}: 参数类型错误, resource 必须为对象或字符串`);
+	}
+
+	if (!resource.method) {
+		resource.method = "GET";
+		if (resource.body ?? resource.bodyBytes) resource.method = "POST";
+	}
+	delete resource.headers?.Host;
+	delete resource.headers?.[":authority"];
+	delete resource.headers?.["Content-Length"];
+	delete resource.headers?.["content-length"];
+
+	if (!resource.timeout) resource.timeout = 5;
+	if (resource.timeout) {
+		resource.timeout = Number.parseInt(resource.timeout, 10);
+		if (resource.timeout > 500) resource.timeout = Math.round(resource.timeout / 1000);
+		resource.timeout = resource.timeout * 1000;
+	}
+
+	if (!globalThis.fetch) {
+		throw new Error(`${Function.name}: 当前 Node.js 运行时缺少全局 fetch，请升级 Node.js 版本`);
+	}
+
+	switch (resource["auto-cookie"]) {
+		case undefined:
+		case "true":
+		case true:
+		case "1":
+		case 1:
+		default:
+			if (!globalThis.fetch?.cookieJar) globalThis.fetch = require("fetch-cookie").default(globalThis.fetch);
+			break;
+		case "false":
+		case false:
+		case "0":
+		case 0:
+		case "-1":
+		case -1:
+			break;
+	}
+
+	resource.redirect = resource.redirection ? "follow" : "manual";
+	const { url, ...fetchOptions } = resource;
+
+	return Promise.race([
+		globalThis
+			.fetch(url, fetchOptions)
+			.then(async response => {
+				const bodyBytes = await response.arrayBuffer();
+				let headers;
+				try {
+					headers = response.headers.raw();
+				} catch {
+					headers = Array.from(response.headers.entries()).reduce((acc, [key, value]) => {
+						acc[key] = acc[key] ? [...acc[key], value] : [value];
+						return acc;
+					}, {});
+				}
+				return {
+					ok: response.ok ?? /^2\d\d$/.test(response.status),
+					status: response.status,
+					statusCode: response.status,
+					statusText: response.statusText,
+					body: new TextDecoder("utf-8").decode(bodyBytes),
+					bodyBytes,
+					headers: Object.fromEntries(Object.entries(headers).map(([key, value]) => [key, key.toLowerCase() !== "set-cookie" ? value.toString() : value])),
+				};
+			})
+			.catch(error => Promise.reject(error.message)),
+		new Promise((resolve, reject) => {
+			setTimeout(() => {
+				reject(new Error(`${Function.name}: 请求超时, 请检查网络后重试`));
+			}, resource.timeout);
+		}),
+	]);
+}
+
+module.exports = { fetch };

package/polyfill/{fetch.js → fetch.mjs}

@@ -1,5 +1,4 @@
 import { $app } from "../lib/app.mjs";
-import { Console } from "./Console.mjs";
 import { Lodash as _ } from "./Lodash.mjs";
 import { StatusTexts } from "./StatusTexts.mjs";
 
@@ -17,7 +16,6 @@ import { StatusTexts } from "./StatusTexts.mjs";
  * @property {string} [policy] 指定策略 / Preferred policy.
  * @property {boolean} [redirection] 是否跟随重定向 / Whether to follow redirects.
  * @property {boolean} ["auto-redirect"] 平台重定向字段 / Platform redirect flag.
- * @property {boolean|number|string} ["auto-cookie"] Worker / Node.js Cookie 开关 / Worker / Node.js Cookie toggle.
  * @property {Record<string, any>} [opts] 平台扩展字段 / Platform extension fields.
  */
 
@@ -36,35 +34,8 @@ import { StatusTexts } from "./StatusTexts.mjs";
  */
 
 /**
- * 跨平台 `fetch` 适配层。
- * Cross-platform `fetch` adapter.
- *
- * 设计目标:
- * Design goal:
- * - 仿照 Web API `fetch`（`Window.fetch`）接口设计
- * - Modeled after Web API `fetch` (`Window.fetch`)
- * - 统一 VPN App、Worker 与 Node.js 环境中的请求调用
- * - Unify request calls across VPN apps, Worker, and Node.js
- *
- * 功能:
- * Features:
- * - 统一 Quantumult X / Loon / Surge / Stash / Egern / Shadowrocket / Worker / Node.js 请求接口
- * - Normalize request APIs across Quantumult X / Loon / Surge / Stash / Egern / Shadowrocket / Worker / 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`
- * - Worker / Node.js 共享基于 `fetch` 的请求分支
- * - Worker / Node.js share the `fetch`-based request branch
- * - `auto-cookie` 在 Worker / Node.js 共享分支中识别
- * - `auto-cookie` is recognized by the shared Worker / Node.js branch
- * - 非浏览器平台通过 `$httpClient/$task` 实现，不是原生 Fetch 实现
- * - Non-browser platforms use `$httpClient/$task` instead of native Fetch engine
- * - 返回结构包含 `statusCode/bodyBytes` 等兼容字段
- * - Response includes compatibility fields like `statusCode/bodyBytes`
+ * 仅面向 iOS 脚本平台的 `fetch` 适配层（ESM 版本）。
+ * `fetch` adapter for iOS script platforms only (ESM version).
  *
  * @link https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch
  * @link https://developer.mozilla.org/zh-CN/docs/Web/API/Window/fetch
@@ -74,8 +45,6 @@ import { StatusTexts } from "./StatusTexts.mjs";
  * @returns {Promise<FetchResponse>}
  */
 export async function fetch(resource, options = {}) {
-	// 初始化参数。
-	// Initialize request input.
 	switch (typeof resource) {
 		case "object":
 			resource = { ...options, ...resource };
@@ -87,63 +56,39 @@ export async function fetch(resource, options = {}) {
 		default:
 			throw new TypeError(`${Function.name}: 参数类型错误, resource 必须为对象或字符串`);
 	}
-	// 自动判断请求方法。
-	// Infer the HTTP method automatically.
+
 	if (!resource.method) {
 		resource.method = "GET";
 		if (resource.body ?? resource.bodyBytes) resource.method = "POST";
 	}
-	// 移除需要由底层实现自动生成的请求头。
-	// Remove headers that should be generated by the underlying runtime.
 	delete resource.headers?.Host;
 	delete resource.headers?.[":authority"];
 	delete resource.headers?.["Content-Length"];
 	delete resource.headers?.["content-length"];
-	// 统一请求方法为小写，方便后续索引平台 API。
-	// Normalize the method to lowercase for platform API lookups.
 	const method = resource.method.toLocaleLowerCase();
-	// 默认请求超时时间为 5 秒。
-	// Default request timeout to 5 seconds.
+
 	if (!resource.timeout) resource.timeout = 5;
-	// 智能矫正请求超时时间，兼容用户输入的秒或毫秒。
-	// Normalize timeout input so both seconds and milliseconds are accepted.
 	if (resource.timeout) {
 		resource.timeout = Number.parseInt(resource.timeout, 10);
-		// 统一先转换为秒，大于 500 视为毫秒输入。
-		// Convert to seconds first and treat values above 500 as milliseconds.
 		if (resource.timeout > 500) resource.timeout = Math.round(resource.timeout / 1000);
 	}
-	// 某些平台要求毫秒级超时，进行二次换算。
-	// Some platforms expect timeout in milliseconds, so convert again.
 	if (resource.timeout) {
 		switch ($app) {
 			case "Loon":
 			case "Quantumult X":
-			case "Worker":
-			case "Node.js":
-				// 这些平台要求毫秒，因此把秒重新换算为毫秒。
-				// These platforms expect milliseconds, so convert seconds back to milliseconds.
 				resource.timeout = resource.timeout * 1000;
 				break;
-			case "Shadowrocket":
-			case "Stash":
-			case "Egern":
-			case "Surge":
 			default:
 				break;
 		}
 	}
-	// 根据当前平台选择请求实现。
-	// Select the request engine for the current platform.
+
 	switch ($app) {
 		case "Loon":
 		case "Surge":
 		case "Stash":
 		case "Egern":
 		case "Shadowrocket":
-		default:
-			// 转换通用请求参数到 `$httpClient` 语义。
-			// Map shared request fields to `$httpClient` semantics.
 			if (resource.policy) {
 				switch ($app) {
 					case "Loon":
@@ -158,14 +103,10 @@ export async function fetch(resource, options = {}) {
 				}
 			}
 			if (typeof resource.redirection === "boolean") resource["auto-redirect"] = resource.redirection;
-			// 优先把 `bodyBytes` 映射回 `$httpClient` 能接受的 `body`。
-			// Prefer mapping `bodyBytes` back to the `body` field expected by `$httpClient`.
 			if (resource.bodyBytes && !resource.body) {
 				resource.body = resource.bodyBytes;
 				resource.bodyBytes = undefined;
 			}
-			// 根据 `Accept` 推断是否需要二进制响应体。
-			// Infer whether the response should be treated as binary from `Accept`.
 			switch ((resource.headers?.Accept || resource.headers?.accept)?.split(";")?.[0]) {
 				case "application/protobuf":
 				case "application/x-protobuf":
@@ -177,8 +118,6 @@ export async function fetch(resource, options = {}) {
 					resource["binary-mode"] = true;
 					break;
 			}
-			// 发送 `$httpClient` 请求并归一化返回结构。
-			// Send the `$httpClient` request and normalize the response payload.
 			return new Promise((resolve, reject) => {
 				globalThis.$httpClient[method](resource, (error, response, body) => {
 					if (error) reject(error);
@@ -195,12 +134,8 @@ export async function fetch(resource, options = {}) {
 				});
 			});
 		case "Quantumult X":
-			// 转换 Quantumult X 专有请求参数。
-			// Map request fields to Quantumult X specific options.
 			if (resource.policy) _.set(resource, "opts.policy", resource.policy);
 			if (typeof resource["auto-redirect"] === "boolean") _.set(resource, "opts.redirection", resource["auto-redirect"]);
-			// Quantumult X 使用 `bodyBytes` 传输二进制请求体。
-			// Quantumult X uses `bodyBytes` for binary request payloads.
 			if (resource.body instanceof ArrayBuffer) {
 				resource.bodyBytes = resource.body;
 				resource.body = undefined;
@@ -208,8 +143,6 @@ export async function fetch(resource, options = {}) {
 				resource.bodyBytes = resource.body.buffer.slice(resource.body.byteOffset, resource.body.byteLength + resource.body.byteOffset);
 				resource.body = undefined;
 			} else if (resource.body) resource.bodyBytes = undefined;
-			// 发送请求，并用 `Promise.race` 提供统一超时保护。
-			// Send the request and enforce timeout with `Promise.race`.
 			return Promise.race([
 				globalThis.$task.fetch(resource).then(
 					response => {
@@ -242,66 +175,9 @@ export async function fetch(resource, options = {}) {
 				}),
 			]);
 		case "Worker":
-		case "Node.js": {
-			// Worker 复用宿主 `fetch`；Node.js 优先复用原生 `fetch`，缺失时再回退到 `node-fetch`。
-			// Worker reuses host `fetch`; Node.js reuses native `fetch` first and falls back to `node-fetch`.
-			if (!globalThis.fetch) globalThis.fetch = require("node-fetch");
-			switch (resource["auto-cookie"]) {
-				case undefined:
-				case "true":
-				case true:
-				case "1":
-				case 1:
-				default:
-					// 仅在尚未包裹 CookieJar 时注入 `fetch-cookie`，避免重复包装。
-					// Inject `fetch-cookie` only once when a cookie jar is not already attached.
-					if (!globalThis.fetch?.cookieJar) globalThis.fetch = require("fetch-cookie").default(globalThis.fetch);
-					break;
-				case "false":
-				case false:
-				case "0":
-				case 0:
-				case "-1":
-				case -1:
-					break;
-			}
-			// 将通用字段映射到 Worker / Node.js Fetch 语义。
-			// Map shared fields to Worker / Node.js Fetch semantics.
-			resource.redirect = resource.redirection ? "follow" : "manual";
-			const { url, ...options } = resource;
-			// 发起请求并归一化响应头、文本与二进制响应体。
-			// Send the request and normalize headers, text, and binary response data.
-			return Promise.race([
-				globalThis
-					.fetch(url, options)
-					.then(async response => {
-						const bodyBytes = await response.arrayBuffer();
-						let headers;
-						try {
-							headers = response.headers.raw();
-						} catch {
-							headers = Array.from(response.headers.entries()).reduce((acc, [key, value]) => {
-								acc[key] = acc[key] ? [...acc[key], value] : [value];
-								return acc;
-							}, {});
-						}
-						return {
-							ok: response.ok ?? /^2\d\d$/.test(response.status),
-							status: response.status,
-							statusCode: response.status,
-							statusText: response.statusText,
-							body: new TextDecoder("utf-8").decode(bodyBytes),
-							bodyBytes: bodyBytes,
-							headers: Object.fromEntries(Object.entries(headers).map(([key, value]) => [key, key.toLowerCase() !== "set-cookie" ? value.toString() : value])),
-						};
-					})
-					.catch(error => Promise.reject(error.message)),
-				new Promise((resolve, reject) => {
-					setTimeout(() => {
-						reject(new Error(`${Function.name}: 请求超时, 请检查网络后重试`));
-					}, resource.timeout);
-				}),
-			]);
-		}
+		case "Node.js":
+			throw new Error(`${Function.name}: ESM 版本不支持 Worker/Node.js，请改用 CJS 入口`);
+		default:
+			throw new Error(`${Function.name}: 当前平台不支持`);
 	}
 }

package/polyfill/fetch.mts

@@ -1,4 +1,4 @@
-import { fetch as fetchRuntime } from "./fetch.js";
+import { fetch as fetchRuntime } from "./fetch.mjs";
 import type { Fetch } from "./fetch.d.ts";
 
 export type { Fetch, FetchRequest, FetchResponse } from "./fetch.d.ts";

package/polyfill/index.d.ts

@@ -3,9 +3,9 @@
  * Aggregated exports for polyfill modules.
  */
 export { Console } from "./Console.mjs";
-export { fetch } from "./fetch.js";
-export type { Fetch, FetchRequest, FetchResponse } from "./fetch.mjs";
+export { fetch } from "./fetch.mjs";
+export type { Fetch, FetchRequest, FetchResponse } from "./fetch.d.ts";
 export { Lodash } from "./Lodash.mjs";
 export { qs } from "./qs.mjs";
 export { StatusTexts } from "./StatusTexts.mjs";
-export { Storage } from "./Storage.js";
+export { Storage } from "./Storage.mjs";

package/polyfill/index.js

@@ -1,6 +1,6 @@
 export * from "./Console.mjs";
-export * from "./fetch.js";
+export * from "./fetch.mjs";
 export * from "./Lodash.mjs";
 export * from "./qs.mjs";
 export * from "./StatusTexts.mjs";
-export * from "./Storage.js";
+export * from "./Storage.mjs";