@nsnanocat/util 2.6.3 → 2.6.7

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` 使用 |
@@ -434,7 +435,11 @@ Worker / Node.js 使用说明：
 
 ### `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 行为
@@ -452,23 +457,31 @@ Worker / Node.js 使用说明：
 - 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`。
 
 平台后端映射：
@@ -477,8 +490,8 @@ Worker / Node.js 使用说明：
 | --- | --- |
 | 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

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

package/index.js

@@ -9,7 +9,7 @@ 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

@@ -23,6 +23,10 @@
       "import": "./polyfill/fetch.mjs",
       "require": "./polyfill/fetch.cjs"
     },
+    "./polyfill/Storage": {
+      "import": "./polyfill/Storage.mjs",
+      "require": "./polyfill/Storage.cjs"
+    },
     "./*": "./*"
   },
   "types": "types/nsnanocat-util.d.ts",
@@ -59,5 +63,5 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "2.6.3"
+  "version": "2.6.7"
 }

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:
@@ -111,7 +111,7 @@ export class Storage {
 				}
 				try {
 					keyValue = JSON.parse(keyValue);
-				} catch (e) {
+				} catch {
 					// do nothing
 				}
 				break;
@@ -200,7 +200,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;
 			}

package/polyfill/fetch.mjs

@@ -16,6 +16,7 @@ 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.
  */
 
@@ -34,8 +35,35 @@ import { StatusTexts } from "./StatusTexts.mjs";
  */
 
 /**
- * 仅面向 iOS 脚本平台的 `fetch` 适配层（ESM 版本）。
- * `fetch` adapter for iOS script platforms only (ESM version).
+ * 跨平台 `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`
  *
  * @link https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch
  * @link https://developer.mozilla.org/zh-CN/docs/Web/API/Window/fetch
@@ -45,6 +73,8 @@ 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 };
@@ -56,39 +86,58 @@ 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;
 	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);
 	}
 	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":
+			// 转换通用请求参数到 `$httpClient` 语义。
+			// Map shared request fields to `$httpClient` semantics.
 			if (resource.policy) {
 				switch ($app) {
 					case "Loon":
@@ -103,21 +152,28 @@ 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":
 				case "application/vnd.google.protobuf":
 				case "application/vnd.apple.flatbuffer":
 				case "application/grpc":
+				case "application/grpc-web":
 				case "application/grpc+proto":
 				case "application/octet-stream":
 					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);
@@ -134,8 +190,12 @@ 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;
@@ -143,6 +203,8 @@ 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 => {
@@ -155,6 +217,7 @@ export async function fetch(resource, options = {}) {
 							case "application/vnd.google.protobuf":
 							case "application/vnd.apple.flatbuffer":
 							case "application/grpc":
+							case "application/grpc-web":
 							case "application/grpc+proto":
 							case "application/octet-stream":
 								response.body = response.bodyBytes;
@@ -175,8 +238,67 @@ export async function fetch(resource, options = {}) {
 				}),
 			]);
 		case "Worker":
-		case "Node.js":
-			throw new Error(`${Function.name}: ESM 版本不支持 Worker/Node.js，请改用 CJS 入口`);
+		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);
+				}),
+			]);
+		}
 		default:
 			throw new Error(`${Function.name}: 当前平台不支持`);
 	}

package/polyfill/index.d.ts

@@ -8,4 +8,4 @@ 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

@@ -3,4 +3,4 @@ export * from "./fetch.mjs";
 export * from "./Lodash.mjs";
 export * from "./qs.mjs";
 export * from "./StatusTexts.mjs";
-export * from "./Storage.js";
+export * from "./Storage.mjs";