@nsnanocat/util 2.6.4 → 2.6.8

package/README.md

@@ -655,9 +655,11 @@ console.log(value); // 1
 
 当前行为：
 - 当 `query` 为 `string` 时：
+  - 支持前导 `?`（会先去掉）。
   - 按 `&` / `=` 切分。
+  - key 与 value 都会先执行 URL 解码（`decodeURIComponent`，并将 `+` 视为空格）。
   - 去掉值中的双引号。
-  - 使用点路径或数组下标路径展开对象。
+  - 支持点路径、数组下标路径，以及方括号 key（如 `a[b]`）展开对象。
 - 当 `query` 为 `object` 时：
   - 将 key 当路径写入新对象（`{"a.b":"1"}` -> `{ a: { b: "1" } }`）。
 - 当 `query` 为 `null` 或 `undefined` 时：
@@ -669,6 +671,9 @@ import { qs } from "@nsnanocat/util";
 console.log(qs.parse("mode=on&a.b=1"));
 // { mode: "on", a: { b: "1" } }
 
+console.log(qs.parse("a%5Bb%5D=c%20d"));
+// { a: { b: "c d" } }
+
 console.log(qs.parse({ "list[0]": "x", "list[1]": "y" }));
 // { list: ["x", "y"] }
 ```

package/package.json

@@ -63,5 +63,5 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "2.6.4"
+  "version": "2.6.8"
 }

package/polyfill/Storage.mjs

@@ -102,7 +102,9 @@ export class Storage {
 						keyValue = Storage.data[keyName];
 						break;
 					case "Node.js":
-						throw new Error(`${Storage.name}.getItem: ESM 版本不支持 Node.js，请改用 CJS 入口`);
+						Storage.data = Storage.#loaddata(Storage.dataFile);
+						keyValue = Storage.data?.[keyName];
+						break;
 					default:
 						keyValue = Storage.data?.[keyName] || null;
 						break;
@@ -163,7 +165,11 @@ export class Storage {
 						result = true;
 						break;
 					case "Node.js":
-						throw new Error(`${Storage.name}.setItem: ESM 版本不支持 Node.js，请改用 CJS 入口`);
+						Storage.data = Storage.#loaddata(Storage.dataFile);
+						Storage.data[keyName] = keyValue;
+						Storage.#writedata(Storage.dataFile);
+						result = true;
+						break;
 					default:
 						result = Storage.data?.[keyName] || null;
 						break;
@@ -218,7 +224,12 @@ export class Storage {
 						result = true;
 						break;
 					case "Node.js":
-						throw new Error(`${Storage.name}.removeItem: ESM 版本不支持 Node.js，请改用 CJS 入口`);
+						// result = false;
+						Storage.data = Storage.#loaddata(Storage.dataFile);
+						delete Storage.data[keyName];
+						Storage.#writedata(Storage.dataFile);
+						result = true;
+						break;
 					default:
 						result = false;
 						break;
@@ -252,7 +263,12 @@ export class Storage {
 				result = true;
 				break;
 			case "Node.js":
-				throw new Error(`${Storage.name}.clear: ESM 版本不支持 Node.js，请改用 CJS 入口`);
+				// result = false;
+				Storage.data = Storage.#loaddata(Storage.dataFile);
+				Storage.data = {};
+				Storage.#writedata(Storage.dataFile);
+				result = true;
+				break;
 			default:
 				result = false;
 				break;
@@ -260,4 +276,57 @@ 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.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/qs.mjs

@@ -31,7 +31,18 @@ export class qs {
 		let result = {};
 		switch (typeof query) {
 			case "string": {
-				const obj = Object.fromEntries(query.split("&").map(item => item.split("=", 2).map(i => i.replace(/\"/g, ""))));
+				const source = query.replace(/^\?/, "");
+				if (!source) break;
+				const obj = Object.fromEntries(
+					source
+						.split("&")
+						.filter(Boolean)
+						.map(item => {
+							const [rawKey = "", rawValue = ""] = item.split("=", 2);
+							const key = qs.#decode(rawKey).replace(/\[([^\[\]]+)\]/g, ".$1");
+							return [key, qs.#decode(rawValue).replace(/\"/g, "")];
+						}),
+				);
 				Object.keys(obj).forEach(key => _.set(result, key, obj[key]));
 				break;
 			}
@@ -139,4 +150,15 @@ export class qs {
 	static #encode(value) {
 		return encodeURIComponent(value);
 	}
+
+	/**
+	 * 解码查询字符串片段。
+	 * Decode a query-string fragment.
+	 *
+	 * @param {string} value 编码值 / Encoded value.
+	 * @returns {string}
+	 */
+	static #decode(value) {
+		return decodeURIComponent(value.replace(/\+/g, " "));
+	}
 }