@nsnanocat/util 2.1.7 → 2.2.0

package/README.md

@@ -116,7 +116,7 @@ import {
 ### `lib/app.mjs` 与 `lib/environment.mjs`（平台识别与环境）
 
 #### `$app`
-- 类型：`"Quantumult X" | "Loon" | "Shadowrocket" | "Node.js" | "Egern" | "Surge" | "Stash" | undefined`
+- 类型：`"Quantumult X" | "Loon" | "Shadowrocket" | "Egern" | "Surge" | "Stash" | "Node.js" | undefined`
 - 角色：核心模块。库内所有存在平台行为差异的模块都会先读取 `$app` 再分流（如 `done`、`notification`、`fetch`、`Storage`、`Console`、`environment`）。
 - 读取方式：
 
@@ -130,10 +130,12 @@ console.log(appName);
 1. 存在 `$task` -> `Quantumult X`
 2. 存在 `$loon` -> `Loon`
 3. 存在 `$rocket` -> `Shadowrocket`
-4. 存在 `module` -> `Node.js`
-5. 存在 `Egern` -> `Egern`
-6. 存在 `$environment` 且有 `surge-version` -> `Surge`
-7. 存在 `$environment` 且有 `stash-version` -> `Stash`
+4. 存在 `Egern` -> `Egern`
+5. 存在 `$environment` 且有 `surge-version` -> `Surge`
+6. 存在 `$environment` 且有 `stash-version` -> `Stash`
+7. 存在 `process.versions.node` -> `Node.js`
+8. 默认回落 -> `undefined`
+- 实现细节：内部使用 `'key' in globalThis` 检测平台标记，避免 `Object.keys(globalThis)` 漏掉不可枚举全局变量；因此在 Workers / Vercel 风格全局对象存在时，只要 `process.versions.node` 可用，仍会识别为 `Node.js`。
 
 #### `$environment` / `environment()`
 - 路径：`lib/environment.mjs`（未从包主入口导出）
@@ -221,6 +223,7 @@ console.log($argument); // { mode: "on", a: { b: "1" } }
 - Quantumult X 会丢弃未在白名单内的字段。
 - Quantumult X 的 `status` 在部分场景要求完整状态行（如 `HTTP/1.1 200 OK`），本库会在传入数字状态码时自动拼接（依赖 `StatusTexts`）。
 - Node.js 不调用 `$done`，而是直接退出进程，且退出码固定为 `1`。
+- 未识别平台（`$app === undefined`）只记录结束日志，不会尝试调用 `$done` 或退出进程。
 
 ### `lib/notification.mjs`
 
@@ -381,6 +384,7 @@ const store = getStorage("@my_box", ["YouTube", "Global"], database);
 - `timeout`
 - `policy`
 - `redirection` / `auto-redirect`
+- `auto-cookie`（仅 Node.js 分支识别；默认启用，传入 `false` / `0` / `-1` 可关闭）
 
 说明：下表是各 App 原生 HTTP 接口的差异补充，以及本库 `fetch` 的内部映射方式。调用方使用统一入参即可。
 
@@ -394,7 +398,7 @@ 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` |
-| Node.js | `fetch` + `fetch-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`
@@ -408,7 +412,8 @@ const store = getStorage("@my_box", ["YouTube", "Global"], database);
 不可用/差异点：
 - `policy` 在 Surge / Egern / Node.js 分支没有额外适配逻辑。
 - `redirection` 在部分平台会映射为 `auto-redirect` 或 `opts.redirection`。
-- Node.js 分支依赖 `globalThis.fetch` / `globalThis.fetchCookie` 或 `node-fetch` + `fetch-cookie`。
+- Node.js 分支优先复用 `globalThis.fetch`；若不存在则回退到 `node-fetch`，并在 `auto-cookie` 未关闭时按需包裹 `fetch-cookie`。
+- 传入 `timeout` 时，`5` 和 `5000` 都会被接受；库会先将用户输入归一化，再按平台要求转换为秒或毫秒。
 - 返回结构是统一兼容结构，不等同于浏览器 `Response` 对象。
 
 ### `polyfill/Storage.mjs`
@@ -631,7 +636,6 @@ console.log(value); // 1
 
 - `lib/argument.mjs` 为 `$argument` 标准化模块，`import` 时会按规则重写全局 `$argument`。
 - `lib/done.mjs` 在 Node.js 固定 `process.exit(1)`。
-- `polyfill/fetch.mjs` 的超时保护使用了 `Promise.race`，但当前实现里请求 Promise 先被 `await`，可能导致超时行为与预期不完全一致。
 - `Storage.removeItem("@a.b")` 分支存在未声明变量写入风险；如要大量使用路径删除，建议先本地验证。
 - `lib/runScript.mjs` 未从包主入口导出，需要按文件路径直接导入。
 

package/lib/app.mjs

@@ -1,36 +1,43 @@
 /**
- * 当前运行平台名称。
- * Current runtime platform name.
+ * 当前运行平台名称（脚本平台优先，模块系统次之）。
+ * Current runtime platform name (script platform first, module system second).
  *
  * 识别顺序:
  * Detection order:
  * 1) `$task` -> Quantumult X
  * 2) `$loon` -> Loon
  * 3) `$rocket` -> Shadowrocket
- * 4) `module` -> Node.js
- * 5) `Egern` -> Egern
- * 6) `$environment["surge-version"]` -> Surge
- * 7) `$environment["stash-version"]` -> Stash
+ * 4) `Egern` -> Egern
+ * 5) `$environment["surge-version"]` -> Surge
+ * 6) `$environment["stash-version"]` -> Stash
+ * 7) `process.versions.node` -> Node.js
+ * 8) 默认回落 -> undefined
+ *    default fallback -> undefined
  *
- * @type {("Quantumult X" | "Loon" | "Shadowrocket" | "Node.js" | "Egern" | "Surge" | "Stash" | undefined)}
+ * 说明:
+ * Notes:
+ * - 使用 `'key' in globalThis`，避免 `Object.keys` 对不可枚举全局变量漏检。
+ * - Use `'key' in globalThis` to avoid missing non-enumerable globals with `Object.keys`.
+ *
+ * @type {("Quantumult X" | "Loon" | "Shadowrocket" | "Egern" | "Surge" | "Stash" | "Node.js" | undefined)}
  */
 export const $app = (() => {
-	const keys = Object.keys(globalThis);
+	const has = (key) => key in globalThis;
 	switch (true) {
-		case keys.includes("$task"):
+		case has("$task"):
 			return "Quantumult X";
-		case keys.includes("$loon"):
+		case has("$loon"):
 			return "Loon";
-		case keys.includes("$rocket"):
+		case has("$rocket"):
 			return "Shadowrocket";
-		case typeof module !== "undefined":
-			return "Node.js";
-		case keys.includes("Egern"):
+		case has("Egern"):
 			return "Egern";
-		case keys.includes("$environment"):
-			if ($environment["surge-version"]) return "Surge";
-			if ($environment["stash-version"]) return "Stash";
-			return undefined;
+		case Boolean(globalThis.$environment?.["surge-version"]):
+			return "Surge";
+		case Boolean(globalThis.$environment?.["stash-version"]):
+			return "Stash";
+		case Boolean(globalThis.process?.versions?.node):
+			return "Node.js";
 		default:
 			return undefined;
 	}

package/lib/done.mjs

@@ -26,6 +26,8 @@ import { StatusTexts } from "../polyfill/StatusTexts.mjs";
  * - This is the call entry and native `$done` differences are handled internally
  * - Node.js 不调用 `$done`，而是直接退出进程
  * - Node.js does not call `$done`; it exits the process directly
+ * - 未识别平台仅记录结束日志，不会强制退出
+ * - Unknown runtimes only log completion and do not force an exit
  *
  * @param {DonePayload} [object={}] 统一响应对象 / Unified response object.
  * @returns {void}
@@ -79,9 +81,11 @@ export function done(object = {}) {
 			$done(object);
 			break;
 		case "Node.js":
-		default:
 			Console.log("🚩 执行结束!");
 			process.exit(1);
 			break;
+		default:
+			Console.log("🚩 执行结束!");
+			break;
 	}
 }

package/package.json

@@ -41,5 +41,5 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "2.1.7"
+  "version": "2.2.0"
 }

package/polyfill/fetch.mjs

@@ -17,6 +17,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"] Node.js Cookie 开关 / Node.js Cookie toggle.
  * @property {Record<string, any>} [opts] 平台扩展字段 / Platform extension fields.
  */
 
@@ -56,6 +57,8 @@ import { StatusTexts } from "./StatusTexts.mjs";
  * Known differences from Web `fetch`:
  * - 支持 `policy`、`auto-redirect` 等平台扩展字段
  * - Supports platform extension fields like `policy` and `auto-redirect`
+ * - Node.js 分支默认启用 Cookie 透传，可通过 `auto-cookie` 关闭
+ * - Node.js enables Cookie forwarding by default and can disable it via `auto-cookie`
  * - 非浏览器平台通过 `$httpClient/$task` 实现，不是原生 Fetch 实现
  * - Non-browser platforms use `$httpClient/$task` instead of native Fetch engine
  * - 返回结构包含 `statusCode/bodyBytes` 等兼容字段
@@ -69,7 +72,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 };
@@ -81,26 +85,34 @@ 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视为毫秒，小于等于500视为秒
+		// 统一先转换为秒，大于 500 视为毫秒输入。
+		// Convert to seconds first and treat values above 500 as milliseconds.
 		if (resource.timeout > 500) resource.timeout = Math.round(resource.timeout / 1000);
 	}
-	// 判断平台
+	// 根据当前平台选择请求实现。
+	// Select the request engine for the current platform.
 	switch ($app) {
 		case "Loon":
 		case "Surge":
@@ -108,10 +120,15 @@ export async function fetch(resource, options = {}) {
 		case "Egern":
 		case "Shadowrocket":
 		default:
-			// 转换请求参数
+			// 转换通用请求参数到 `$httpClient` 语义。
+			// Map shared request fields to `$httpClient` semantics.
 			if (resource.timeout) {
 				switch ($app) {
 					case "Loon":
+					case "Quantumult X":
+					case "Node.js":
+						// 这些平台要求毫秒，因此把秒重新换算为毫秒。
+						// These platforms expect milliseconds, so convert seconds back to milliseconds.
 						resource.timeout = resource.timeout * 1000;
 						break;
 					case "Shadowrocket":
@@ -136,12 +153,14 @@ 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":
@@ -153,9 +172,10 @@ export async function fetch(resource, options = {}) {
 					resource["binary-mode"] = true;
 					break;
 			}
-			// 发送请求
-			return await new Promise((resolve, reject) => {
-				$httpClient[method](resource, (error, response, body) => {
+			// 发送 `$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);
 					else {
 						response.ok = /^2\d\d$/.test(response.status);
@@ -170,11 +190,12 @@ export async function fetch(resource, options = {}) {
 				});
 			});
 		case "Quantumult X":
-			// 转换请求参数
-			resource.timeout = resource.timeout * 1000;
+			// 转换 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;
@@ -182,9 +203,10 @@ 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([
-				await $task.fetch(resource).then(
+				globalThis.$task.fetch(resource).then(
 					response => {
 						response.ok = /^2\d\d$/.test(response.statusCode);
 						response.status = response.statusCode;
@@ -215,16 +237,37 @@ export async function fetch(resource, options = {}) {
 				}),
 			]);
 		case "Node.js": {
-			const nodeFetch = globalThis.fetch ? globalThis.fetch : require("node-fetch");
-			const fetchCookie = globalThis.fetchCookie ? globalThis.fetchCookie : require("fetch-cookie").default;
-			const fetch = fetchCookie(nodeFetch);
-			// 转换请求参数
-			resource.timeout = resource.timeout * 1000;
+			// Node.js 优先复用原生/宿主 `fetch`，缺失时再回退到 `node-fetch`。
+			// Reuse host `fetch` in Node.js when available and fall back to `node-fetch` otherwise.
+			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;
+			}
+			// 将通用字段映射到 Node.js Fetch 语义。
+			// Map shared fields to 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([
-				await fetch(url, options)
+				globalThis
+					.fetch(url, options)
 					.then(async response => {
 						const bodyBytes = await response.arrayBuffer();
 						let headers;

package/types/nsnanocat-util.d.ts

@@ -1,5 +1,12 @@
 declare module "@nsnanocat/util" {
-	export type AppName = "Quantumult X" | "Loon" | "Shadowrocket" | "Node.js" | "Egern" | "Surge" | "Stash";
+	export type AppName =
+		| "Quantumult X"
+		| "Loon"
+		| "Shadowrocket"
+		| "Egern"
+		| "Surge"
+		| "Stash"
+		| "Node.js";
 
 	export const $app: AppName | undefined;
 	export const $argument: Record<string, unknown>;
@@ -54,6 +61,7 @@ declare module "@nsnanocat/util" {
 		policy?: string;
 		redirection?: boolean;
 		"auto-redirect"?: boolean;
+		"auto-cookie"?: boolean | number | string;
 		opts?: Record<string, unknown>;
 		[key: string]: unknown;
 	}