@nsnanocat/util 2.3.0 → 2.4.0

package/README.md

@@ -5,7 +5,7 @@
 核心目标：
 - 统一不同平台的 HTTP、通知、持久化、结束脚本等调用方式。
 - 在一个脚本里尽量少写平台分支。
-- 提供一组可直接复用的 polyfill（`fetch` / `Storage` / `KV` / `Console` / `Lodash`）。
+- 提供一组可直接复用的 polyfill（`fetch` / `Storage` / `KV` / `Console` / `Lodash` / `qs`）。
 
 ## 目录
 - [安装与导入](#安装与导入)
@@ -66,6 +66,7 @@ import {
   Console,    // 统一日志工具（支持 logLevel）
   Lodash as _, // Lodash 建议按官方示例惯例使用 `_` 作为工具对象别名
   KV,         // Cloudflare Workers KV 异步适配器（显式传入 namespace binding）
+  qs,         // 查询字符串工具（parse / stringify）
   Storage,    // 统一持久化存储接口（适配 $prefs / $persistentStore / 内存 / 文件）
 } from "@nsnanocat/util";
 ```
@@ -83,6 +84,7 @@ import {
 - `polyfill/fetch.mjs`
 - `polyfill/KV.mjs`
 - `polyfill/Lodash.mjs`
+- `polyfill/qs.mjs`
 - `polyfill/StatusTexts.mjs`
 - `polyfill/Storage.mjs`
 
@@ -101,7 +103,7 @@ import {
 | --- | --- | --- | --- |
 | `lib/app.mjs` | 无 | 无 | 核心平台识别源头，供其他差异模块分流 |
 | `lib/environment.mjs` | `lib/app.mjs` | `$app` | 按平台生成统一 `$environment`（尤其补齐 `app` 字段） |
-| `lib/argument.mjs` | `polyfill/Console.mjs`, `polyfill/Lodash.mjs` | `Console.debug`, `Console.logLevel`, `Lodash.set` | 统一 `$argument` 结构并支持深路径写入 |
+| `lib/argument.mjs` | `polyfill/Console.mjs`, `polyfill/qs.mjs` | `Console.debug`, `Console.logLevel`, `qs.parse` | 统一 `$argument` 结构，并委托 `qs.parse` 处理字符串/对象/空值输入 |
 | `lib/done.mjs` | `lib/app.mjs`, `polyfill/Console.mjs`, `polyfill/Lodash.mjs`, `polyfill/StatusTexts.mjs` | `$app`, `Console.log`, `Lodash.set`, `Lodash.pick`, `StatusTexts` | 将各平台 `$done` 参数格式拉平并兼容状态码/策略字段 |
 | `lib/notification.mjs` | `lib/app.mjs`, `polyfill/Console.mjs` | `$app`, `Console.group`, `Console.log`, `Console.groupEnd`, `Console.error` | 将通知参数映射到各平台通知接口并统一日志输出 |
 | `lib/runScript.mjs` | `polyfill/Console.mjs`, `polyfill/fetch.mjs`, `polyfill/Storage.mjs`, `polyfill/Lodash.mjs` | `Console.error`, `fetch`, `Storage.getItem`（`Lodash` 当前版本未实际调用） | 读取 BoxJS 配置并发起统一 HTTP 调用执行脚本 |
@@ -111,6 +113,7 @@ import {
 | `polyfill/KV.mjs` | `lib/app.mjs`, `polyfill/Lodash.mjs`, `polyfill/Storage.mjs` | `$app`, `Lodash.get`, `Lodash.set`, `Lodash.unset`, `Storage` | 为 Cloudflare Workers KV 提供异步适配，并在非 Worker 平台回退到 `Storage` |
 | `polyfill/Storage.mjs` | `lib/app.mjs`, `polyfill/Lodash.mjs` | `$app`, `Lodash.get`, `Lodash.set`, `Lodash.unset` | 按平台选持久化后端并支持 `@key.path` 读写 |
 | `polyfill/Lodash.mjs` | 无 | 无 | 提供路径/合并等基础能力，被多个模块复用 |
+| `polyfill/qs.mjs` | `polyfill/Lodash.mjs` | `Lodash.get`, `Lodash.set`, `Lodash.toPath` | 提供查询字符串与对象之间的解析/序列化能力 |
 | `polyfill/StatusTexts.mjs` | 无 | 无 | 提供 HTTP 状态文案，供 `fetch/done` 使用 |
 | `index.js` / `lib/index.js` / `polyfill/index.js` | 多个模块 | `export *` | 聚合导出，不含业务逻辑 |
 
@@ -173,6 +176,7 @@ console.log(environment()); // 当前环境对象
 - 通过包入口导入（`import ... from "@nsnanocat/util"`）时会自动执行本模块。
 - JSCore 环境不支持 `await import`，请使用静态导入或直接走包入口导入。
 - 读取到的 `$argument` 会按 URL Params 样式格式化为对象，并支持深路径。
+- 内部实现统一委托给 `qs.parse(globalThis.$argument)`。
 - 你也可以通过 `import { $argument } from "@nsnanocat/util"` 读取当前已标准化的 `$argument` 快照。
 - 平台输入差异说明：
   - Surge / Stash / Egern：脚本参数通常以字符串形式传入（如 `a=1&b=2`）。
@@ -658,6 +662,53 @@ console.log(value); // 1
 - `undefined` 不覆盖，`null` 会覆盖。
 - 直接修改目标对象（mutates target）。
 
+### `polyfill/qs.mjs`
+
+当前实现为项目内使用的轻量子集，不追求与官方 `qs` 完全一致。
+
+#### `qs.parse(query)`
+- 签名：`qs.parse(query?: string | object | null): object`
+- 作用：将查询字符串或对象输入归一化为支持深路径的对象。
+- 依赖：内部使用 `Lodash.set` 展开路径。
+
+当前行为：
+- 当 `query` 为 `string` 时：
+  - 按 `&` / `=` 切分。
+  - 去掉值中的双引号。
+  - 使用点路径或数组下标路径展开对象。
+- 当 `query` 为 `object` 时：
+  - 将 key 当路径写入新对象（`{"a.b":"1"}` -> `{ a: { b: "1" } }`）。
+- 当 `query` 为 `null` 或 `undefined` 时：
+  - 返回 `{}`。
+
+```js
+import { qs } from "@nsnanocat/util";
+
+console.log(qs.parse("mode=on&a.b=1"));
+// { mode: "on", a: { b: "1" } }
+
+console.log(qs.parse({ "list[0]": "x", "list[1]": "y" }));
+// { list: ["x", "y"] }
+```
+
+#### `qs.stringify(object)`
+- 签名：`qs.stringify(object?: object): string`
+- 作用：将对象按深路径展开为查询字符串。
+- 依赖：内部使用 `Lodash.get` 与 `Lodash.toPath` 读取并格式化路径。
+
+当前行为：
+- 普通对象输出为点路径（`a.b=1`）。
+- 数组输出为索引路径（`list[0]=x`）。
+- 值始终执行 `encodeURIComponent` 编码。
+- `null` 会序列化为空值（`key=`），`undefined` 会跳过。
+
+```js
+import { qs } from "@nsnanocat/util";
+
+console.log(qs.stringify({ a: { b: "1" }, list: ["x", "y"] }));
+// a.b=1&list%5B0%5D=x&list%5B1%5D=y
+```
+
 ### `polyfill/StatusTexts.mjs`
 
 #### `StatusTexts`

package/index.js

@@ -8,6 +8,7 @@ export * from "./polyfill/Console.mjs";
 export * from "./polyfill/fetch.mjs";
 export * from "./polyfill/KV.mjs";
 export * from "./polyfill/Lodash.mjs";
+export * from "./polyfill/qs.mjs";
 export * from "./polyfill/StatusTexts.mjs";
 export * from "./polyfill/Storage.mjs";
 

package/lib/argument.mjs

@@ -1,5 +1,5 @@
 import { Console } from "../polyfill/Console.mjs";
-import { Lodash as _ } from "../polyfill/Lodash.mjs";
+import { qs } from "../polyfill/qs.mjs";
 
 /**
  * 统一 `$argument` 输入格式并展开深路径。
@@ -28,27 +28,7 @@ import { Lodash as _ } from "../polyfill/Lodash.mjs";
  */
 (() => {
 	Console.debug("☑️ $argument");
-	switch (typeof globalThis.$argument) {
-		case "string": {
-			const argument = Object.fromEntries(globalThis.$argument.split("&").map(item => item.split("=", 2).map(i => i.replace(/\"/g, ""))));
-			globalThis.$argument = {};
-			Object.keys(argument).forEach(key => _.set(globalThis.$argument, key, argument[key]));
-			break;
-		}
-		case "object": {
-			if (globalThis.$argument === null) {
-				globalThis.$argument = {};
-				break;
-			}
-			const argument = {};
-			Object.keys(globalThis.$argument).forEach(key => _.set(argument, key, globalThis.$argument[key]));
-			globalThis.$argument = argument;
-			break;
-		}
-		case "undefined":
-			globalThis.$argument = {};
-			break;
-	}
+	globalThis.$argument = qs.parse(globalThis.$argument);
 	if (globalThis.$argument.LogLevel) Console.logLevel = globalThis.$argument.LogLevel;
 	Console.debug("✅ $argument", `$argument: ${JSON.stringify(globalThis.$argument)}`);
 })();

package/package.json

@@ -42,5 +42,5 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "2.3.0"
+  "version": "2.4.0"
 }

package/polyfill/KV.mjs

@@ -75,7 +75,7 @@ export class KV {
 			default:
 				switch ($app) {
 					case "Worker":
-						keyValue = await this.#getNamespace().get(keyName);
+						keyValue = await this.namespace.get(keyName);
 						break;
 					default:
 						keyValue = Storage.getItem(keyName, defaultValue);
@@ -111,7 +111,7 @@ export class KV {
 			default:
 				switch ($app) {
 					case "Worker":
-						await this.#getNamespace().put(keyName, keyValue);
+						await this.namespace.put(keyName, keyValue);
 						result = true;
 						break;
 					default:
@@ -145,7 +145,7 @@ export class KV {
 			default:
 				switch ($app) {
 					case "Worker":
-						await this.#getNamespace().delete(keyName);
+						await this.namespace.delete(keyName);
 						result = true;
 						break;
 					default:
@@ -176,35 +176,13 @@ export class KV {
 	 */
 	async list(options = {}) {
 		switch ($app) {
-			case "Worker": {
-				const namespace = this.#getNamespace();
-				if (typeof namespace.list !== "function") throw new TypeError("KV namespace binding with list() is required in Worker runtime.");
-				return await namespace.list(options);
-			}
+			case "Worker":
+				return await this.namespace.list(options);
 			default:
 				throw new TypeError("KV.list() is only supported in Worker runtime.");
 		}
 	}
 
-	/**
-	 * 解析 Worker 所需的 namespace 绑定。
-	 * Resolve the namespace binding required by Workers.
-	 *
-	 * @private
-	 * @returns {{ get(key: string): Promise<string|null>; put(key: string, value: string): Promise<void>; delete(key: string): Promise<void>; list?(options?: { prefix?: string; limit?: number; cursor?: string }): Promise<{ keys: { name: string; expiration?: number; metadata?: object }[]; list_complete: boolean; cursor: string }> }}
-	 */
-	#getNamespace() {
-		if (
-			!this.namespace ||
-			typeof this.namespace.get !== "function" ||
-			typeof this.namespace.put !== "function" ||
-			typeof this.namespace.delete !== "function"
-		) {
-			throw new TypeError("KV namespace binding is required in Worker runtime.");
-		}
-		return this.namespace;
-	}
-
 	/**
 	 * 尝试将字符串反序列化为原始值。
 	 * Try to deserialize a string into its original value.

package/polyfill/index.js

@@ -2,5 +2,6 @@ export * from "./Console.mjs";
 export * from "./fetch.mjs";
 export * from "./KV.mjs";
 export * from "./Lodash.mjs";
+export * from "./qs.mjs";
 export * from "./StatusTexts.mjs";
 export * from "./Storage.mjs";

package/polyfill/qs.mjs

@@ -0,0 +1,142 @@
+import { Lodash as _ } from "./Lodash.mjs";
+
+/* https://github.com/ljharb/qs */
+/**
+ * 轻量 `qs` 查询字符串工具。
+ * Lightweight `qs` query-string utilities.
+ *
+ * 说明:
+ * Notes:
+ * - 参考 `qs` 的 `parse` / `stringify` 接口设计
+ * - Modeled after the `qs` `parse` / `stringify` API
+ * - `parse` 保持当前项目原有 `$argument` 字符串解析语义
+ * - `parse` preserves the existing `$argument` string parsing semantics
+ * - `stringify` 基于项目内 `Lodash` 路径能力展开对象
+ * - `stringify` expands objects via the in-project `Lodash` path helpers
+ *
+ * 参考:
+ * Reference:
+ * - https://github.com/ljharb/qs
+ * - https://www.npmjs.com/package/qs
+ */
+export class qs {
+	/**
+	 * 将查询字符串解析为对象。
+	 * Parse a query string into an object.
+	 *
+	 * @param {string | Record<string, unknown> | null | undefined} [query=""] 查询字符串或对象 / Query string or object.
+	 * @returns {Record<string, unknown>}
+	 */
+	static parse(query) {
+		let result = {};
+		switch (typeof query) {
+			case "string": {
+				const obj = Object.fromEntries(query.split("&").map(item => item.split("=", 2).map(i => i.replace(/\"/g, ""))));
+				Object.keys(obj).forEach(key => _.set(result, key, obj[key]));
+				break;
+			}
+			case "object": {
+				switch (query) {
+					case null:
+						break;
+					default: {
+						const obj = {};
+						Object.keys(query).forEach(key => _.set(obj, key, query[key]));
+						result = obj;
+						break;
+					}
+				}
+				break;
+			}
+			case "undefined":
+				result = {};
+				break;
+		}
+		return result;
+	}
+
+	/**
+	 * 将对象序列化为查询字符串。
+	 * Serialize an object into a query string.
+	 *
+	 * @param {Record<string, unknown>} [object={}] 输入对象 / Input object.
+	 * @returns {string}
+	 */
+	static stringify(object = {}) {
+		if (!object || typeof object !== "object") return "";
+
+		const entries = [];
+		Object.keys(object).forEach(key => qs.#collect(object, key, entries));
+
+		if (entries.length === 0) return "";
+		return entries
+			.map(([key, value]) => `${qs.#encode(qs.#formatPath(key))}=${qs.#encode(value)}`)
+			.join("&");
+	}
+
+	/**
+	 * 收集待序列化的键值对。
+	 * Collect key-value pairs for stringification.
+	 *
+	 * @param {Record<string, unknown>} object 输入对象 / Input object.
+	 * @param {string} path 当前路径 / Current path.
+	 * @param {[string, string][]} entries 输出数组 / Output entries.
+	 * @returns {void}
+	 */
+	static #collect(object, path, entries) {
+		const value = _.get(object, path);
+		if (value === undefined) return;
+		if (value === null) {
+			entries.push([path, ""]);
+			return;
+		}
+		if (Array.isArray(value)) {
+			value.forEach((item, index) => {
+				if (item === undefined) return;
+				qs.#collect(object, `${path}[${index}]`, entries);
+			});
+			return;
+		}
+		if (qs.#isPlainObject(value)) {
+			Object.keys(value).forEach(key => qs.#collect(object, `${path}.${key}`, entries));
+			return;
+		}
+		entries.push([path, String(value)]);
+	}
+
+	/**
+	 * 使用 `Lodash.toPath` 规范化输出路径。
+	 * Normalize output path via `Lodash.toPath`.
+	 *
+	 * @param {string} path 原始路径 / Raw path.
+	 * @returns {string}
+	 */
+	static #formatPath(path) {
+		const [head, ...tail] = _.toPath(path);
+		return tail.reduce((result, segment) => (/^\d+$/.test(segment) ? `${result}[${segment}]` : `${result}.${segment}`), head);
+	}
+
+	/**
+	 * 判断值是否为普通对象。
+	 * Check whether a value is a plain object.
+	 *
+	 * @param {unknown} value 输入值 / Input value.
+	 * @returns {boolean}
+	 */
+	static #isPlainObject(value) {
+		if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+		const proto = Object.getPrototypeOf(value);
+		return proto === null || proto === Object.prototype;
+	}
+
+	/**
+	 * 编码查询字符串片段。
+	 * Encode a query-string fragment.
+	 *
+	 * @param {string} value 原始值 / Raw value.
+	 * @returns {string}
+	 */
+	static #encode(value) {
+		return encodeURIComponent(value);
+	}
+}

package/types/modules/polyfills.d.ts

@@ -30,5 +30,11 @@ declare module "@nsnanocat/util" {
 		static unset(object?: Record<string, unknown>, path?: string | string[]): boolean;
 	}
 
+	export class qs {
+		static parse(query?: string | Record<string, unknown> | null): Record<string, unknown>;
+
+		static stringify(object?: Record<string, unknown>): string;
+	}
+
 	export const StatusTexts: Record<number, string>;
 }