@nsnanocat/util 2.6.1 → 2.6.3

package/README.md

@@ -369,7 +369,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 +398,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 +412,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,12 +423,15 @@ 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`）设计的跨平台持久化适配器：

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.mjs";
+import { Storage } from "./polyfill/Storage.js";
 
 /**
  * 存储配置读取与合并结果。

package/index.cjs

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

package/index.js

@@ -5,7 +5,7 @@ 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";

package/package.json

@@ -14,10 +14,23 @@
   "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"
+    },
+    "./*": "./*"
+  },
   "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 +40,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 +59,5 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "2.6.1"
+  "version": "2.6.3"
 }

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,8 +3,8 @@
  * 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";

package/polyfill/index.js

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