@nsnanocat/util 2.1.1 → 2.1.3

package/README.md

@@ -64,7 +64,7 @@ import {
   time,       // 时间格式化工具
   wait,       // 延时等待工具（Promise）
   Console,    // 统一日志工具（支持 logLevel）
-  Lodash,     // 内置的 Lodash 部分方法实现
+  Lodash as _, // Lodash 建议按官方示例惯例使用 `_` 作为工具对象别名
   Storage,    // 统一持久化存储接口（适配 $prefs / $persistentStore / 文件）
 } from "@nsnanocat/util";
 ```
@@ -177,7 +177,7 @@ console.log(environment()); // 当前环境对象
   - 使用点路径展开对象（`a.b=1 -> { a: { b: "1" } }`）。
 - 当全局 `$argument` 为 `object` 时：
   - 将 key 当路径写回新对象（`{"a.b":"1"}` -> `{a:{b:"1"}}`）。
-- 当 `$argument` 为 `undefined`：不处理。
+- 当 `$argument` 为 `null` 或 `undefined`：会归一化为 `{}`。
 - 若 `$argument.LogLevel` 存在：同步到 `Console.logLevel`。
 
 #### 用法
@@ -315,13 +315,15 @@ await runScript("$done({})", { timeout: 20 });
   - `database: object`（默认数据库）
 - 返回：`{ Settings, Configs, Caches }`
 
-合并顺序：
-1. `database.Default` -> 初始 `Store`
-2. 持久化中的 BoxJS 值（`Storage.getItem(key)`）
-3. 按 `names` 合并 `database[name]` + `BoxJs[name]`
-4. 最后合并 `$argument`
+合并顺序由 `$argument.Storage` 控制（持久化读取统一使用 `PersistentStore = Storage.getItem(key, {})`）：
+1. 默认（`undefined`）：`database[name]` -> `$argument` -> `PersistentStore[name]`
+2. `$argument`：`database[name]` -> `PersistentStore[name]` -> `$argument`
+3. `PersistentStore` / `BoxJs`：`database[name]` -> `PersistentStore[name]`
+4. `database`：仅 `database[name]`
 
-自动类型转换（`Store.Settings`）：
+注意：`Configs` 与 `Caches` 始终按每个 `name` 合并（与 `$argument.Storage` 无关）。
+
+自动类型转换（`Root.Settings`）：
 - 字符串 `"true"/"false"` -> `boolean`
 - 纯数字字符串 -> `number`
 - 含逗号字符串 -> `array`，并尝试逐项转数字
@@ -408,7 +410,8 @@ const store = getStorage("@my_box", ["YouTube", "Global"], database);
 
 #### `Storage.removeItem(keyName)`
 - Quantumult X：可用（`$prefs.removeValueForKey`）。
-- Surge / Loon / Stash / Egern / Shadowrocket / Node.js：返回 `false`。
+- Surge：通过 `$persistentStore.write(null, keyName)` 删除。
+- Loon / Stash / Egern / Shadowrocket / Node.js：返回 `false`。
 
 #### `Storage.clear()`
 - Quantumult X：可用（`$prefs.removeAllValues`）。
@@ -420,7 +423,7 @@ const store = getStorage("@my_box", ["YouTube", "Global"], database);
 
 与 Web Storage 的行为差异：
 - 支持 `@key.path` 深路径读写（Web Storage 原生不支持）。
-- `removeItem/clear` 仅部分平台可用（目前主要是 Quantumult X）。
+- `removeItem/clear` 仅部分平台可用（目前为 Quantumult X，以及 Surge 的 `removeItem`）。
 - `getItem` 会尝试 `JSON.parse`，`setItem` 写入对象会 `JSON.stringify`。
 
 平台后端映射：
@@ -499,6 +502,28 @@ console.log(Console.logLevel); // "WARN"
 - https://www.lodashjs.com
 - https://lodash.com
 
+导入约定（建议）：
+- 这是 lodash 官方示例中常见的惯例写法：使用 `_` 作为工具对象别名。
+
+```js
+import { Lodash as _ } from "@nsnanocat/util";
+
+const data = {};
+_.set(data, "a.b", 1);
+console.log(data); // { a: { b: 1 } }
+
+const value = _.get(data, "a.b", 0);
+console.log(value); // 1
+```
+
+示例对应的 lodash 官方文档页面：
+- `set(object, path, value)`
+  - 官方文档：https://lodash.com/docs/#set
+  - 中文文档：https://www.lodashjs.com/docs/lodash.set
+- `get(object, path, defaultValue)`
+  - 官方文档：https://lodash.com/docs/#get
+  - 中文文档：https://www.lodashjs.com/docs/lodash.get
+
 当前实现包含：
 - `escape(string)`
 - `unescape(string)`
@@ -510,6 +535,35 @@ console.log(Console.logLevel); // "WARN"
 - `omit(object, paths)`
 - `merge(object, ...sources)`
 
+对应 lodash 官方文档页面：
+- `escape(string)`
+  - 官方文档：https://lodash.com/docs/#escape
+  - 中文文档：https://www.lodashjs.com/docs/lodash.escape
+- `unescape(string)`
+  - 官方文档：https://lodash.com/docs/#unescape
+  - 中文文档：https://www.lodashjs.com/docs/lodash.unescape
+- `toPath(value)`
+  - 官方文档：https://lodash.com/docs/#toPath
+  - 中文文档：https://www.lodashjs.com/docs/lodash.toPath
+- `get(object, path, defaultValue)`
+  - 官方文档：https://lodash.com/docs/#get
+  - 中文文档：https://www.lodashjs.com/docs/lodash.get
+- `set(object, path, value)`
+  - 官方文档：https://lodash.com/docs/#set
+  - 中文文档：https://www.lodashjs.com/docs/lodash.set
+- `unset(object, path)`
+  - 官方文档：https://lodash.com/docs/#unset
+  - 中文文档：https://www.lodashjs.com/docs/lodash.unset
+- `pick(object, paths)`
+  - 官方文档：https://lodash.com/docs/#pick
+  - 中文文档：https://www.lodashjs.com/docs/lodash.pick
+- `omit(object, paths)`
+  - 官方文档：https://lodash.com/docs/#omit
+  - 中文文档：https://www.lodashjs.com/docs/lodash.omit
+- `merge(object, ...sources)`
+  - 官方文档：https://lodash.com/docs/#merge
+  - 中文文档：https://www.lodashjs.com/docs/lodash.merge
+
 参数与返回值：
 
 | 方法 | 参数 | 返回值 | 说明 |
@@ -549,7 +603,7 @@ console.log(Console.logLevel); // "WARN"
 | 通知 | `$notify` | `$notification.post` | `$notification.post` | `$notification.post` | `$notification.post` | `$notification.post` | 无 |
 | 持久化 | `$prefs` | `$persistentStore` | `$persistentStore` | `$persistentStore` | `$persistentStore` | `$persistentStore` | `box.dat` |
 | 结束脚本 | `$done` | `$done` | `$done` | `$done` | `$done` | `$done` | `process.exit(1)` |
-| `removeItem/clear` | 可用 | 不可用 | 不可用 | 不可用 | 不可用 | 不可用 | 不可用 |
+| `removeItem/clear` | 可用 | 不可用 | `removeItem` 可用 / `clear` 不可用 | 不可用 | 不可用 | 不可用 | 不可用 |
 | `policy` 注入（`fetch/done`） | `opts.policy` | `node` | `X-Surge-Policy`(done) | `X-Stash-Selected-Proxy` | 无专门映射 | `X-Surge-Proxy`(fetch) | 无 |
 
 ## 已知限制与注意事项

package/getStorage.mjs

@@ -17,13 +17,17 @@ import { Storage } from "./polyfill/Storage.mjs";
  * 读取并合并默认配置、持久化配置与 `$argument`。
  * Read and merge default config, persisted config and `$argument`.
  *
- * 合并顺序:
- * Merge order:
- * 1) `database.Default`
- * 2) BoxJS persisted value
- * 3) `database[name]` + `BoxJs[name]`
- * 4) `$argument`
+ * 注意：`Configs` 与 `Caches` 始终按每个 profile（`names`）合并；`Settings` 的合并顺序由 `$argument.Storage` 控制。
+ * Note: `Configs` and `Caches` are always merged per-profile (`names`); the merge order for `Settings` is controlled by `$argument.Storage`.
  *
+ * 合并来源与顺序由 `$argument.Storage` 控制:
+ * Merge source order is controlled by `$argument.Storage`:
+ * - `undefined`(默认): `database[name]` -> `$argument` -> `PersistentStore[name]`
+ * - `$argument`: `database[name]` -> `PersistentStore[name]` -> `$argument`
+ * - `PersistentStore` / `BoxJs`: `database[name]` -> `PersistentStore[name]`
+ * - `database`: 仅 `database[name]`
+ *
+ * @since 2.1.2
  * @link https://github.com/NanoCat-Me/utils/blob/main/getStorage.mjs
  * @author VirgilClyne
  * @param {string} key 持久化主键 / Persistent store key.
@@ -36,36 +40,63 @@ export function getStorage(key, names, database) {
 	Console.debug("☑️ getStorage");
 	names = [names].flat(Number.POSITIVE_INFINITY);
 	/***************** Default *****************/
-	const Store = { Settings: database?.Default?.Settings || {}, Configs: database?.Default?.Configs || {}, Caches: {} };
-	Console.debug("Default", `Store.Settings类型: ${typeof Store.Settings}`, `Store.Settings: ${JSON.stringify(Store.Settings)}`);
-	/***************** BoxJs *****************/
+	const Root = { Settings: database?.Default?.Settings || {}, Configs: database?.Default?.Configs || {}, Caches: {} };
+	Console.debug("Default", `Root.Settings类型: ${typeof Root.Settings}`, `Root.Settings: ${JSON.stringify(Root.Settings)}`);
+	/***************** PersistentStore *****************/
 	// 包装为局部变量，用完释放内存
-	// BoxJs的清空操作返回假值空字符串, 逻辑或操作符会在左侧操作数为假值时返回右侧操作数。
-	const BoxJs = Storage.getItem(key);
-	if (BoxJs) {
-		Console.debug("☑️ BoxJs", `BoxJs类型: ${typeof BoxJs}`, `BoxJs内容: ${JSON.stringify(BoxJs || {})}`);
+	// BoxJs 的清空操作返回假值空字符串, 逻辑或操作符会在左侧操作数为假值时返回右侧操作数。
+	const PersistentStore = Storage.getItem(key, {});
+	if (PersistentStore) {
+		Console.debug("☑️ PersistentStore", `PersistentStore类型: ${typeof PersistentStore}`, `PersistentStore内容: ${JSON.stringify(PersistentStore || {})}`);
 		names.forEach(name => {
-			if (typeof BoxJs?.[name]?.Settings === "string") {
-				BoxJs[name].Settings = JSON.parse(BoxJs[name].Settings || "{}");
+			if (typeof PersistentStore?.[name]?.Settings === "string") {
+				PersistentStore[name].Settings = JSON.parse(PersistentStore[name].Settings || "{}");
 			}
-			if (typeof BoxJs?.[name]?.Caches === "string") {
-				BoxJs[name].Caches = JSON.parse(BoxJs[name].Caches || "{}");
+			if (typeof PersistentStore?.[name]?.Caches === "string") {
+				PersistentStore[name].Caches = JSON.parse(PersistentStore[name].Caches || "{}");
 			}
 		});
-		if (BoxJs.LogLevel) Console.logLevel = BoxJs.LogLevel;
-		Console.debug("✅ BoxJs", `Store.Settings类型: ${typeof Store.Settings}`, `Store.Settings: ${JSON.stringify(Store.Settings)}`);
+		if (PersistentStore.LogLevel) Console.logLevel = PersistentStore.LogLevel;
+		Console.debug("✅ PersistentStore", `Root.Settings类型: ${typeof Root.Settings}`, `Root.Settings: ${JSON.stringify(Root.Settings)}`);
 	}
 	/***************** Merge *****************/
 	names.forEach(name => {
-		_.merge(Store.Settings, database?.[name]?.Settings, BoxJs?.[name]?.Settings);
-		_.merge(Store.Configs, database?.[name]?.Configs);
-		_.merge(Store.Caches, BoxJs?.[name]?.Caches);
+		_.merge(Root.Configs, database?.[name]?.Configs);
+		_.merge(Root.Caches, PersistentStore?.[name]?.Caches);
 	});
-	_.merge(Store.Settings, $argument);
-	if (Store.Settings.LogLevel) Console.logLevel = Store.Settings.LogLevel;
-	Console.debug("✅ Merge", `Store.Settings类型: ${typeof Store.Settings}`, `Store.Settings: ${JSON.stringify(Store.Settings)}`);
+	switch ($argument.Storage) {
+		case "$argument":
+			names.forEach(name => {
+				_.merge(Root.Settings, database?.[name]?.Settings, PersistentStore?.[name]?.Settings);
+			});
+			_.merge(Root.Settings, $argument);
+			break;
+		case "BoxJs":
+		case "PersistentStore":
+			names.forEach(name => {
+				_.merge(Root.Settings, database?.[name]?.Settings, PersistentStore?.[name]?.Settings);
+			});
+			break;
+		case "database":
+			names.forEach(name => {
+				_.merge(Root.Settings, database?.[name]?.Settings);
+			});
+			break;
+		default:
+		case undefined:
+			names.forEach(name => {
+				_.merge(Root.Settings, database?.[name]?.Settings);
+			});
+			_.merge(Root.Settings, $argument);
+			names.forEach(name => {
+				_.merge(Root.Settings, PersistentStore?.[name]?.Settings);
+			});
+			break;
+	}
+	if (Root.Settings.LogLevel) Console.logLevel = Root.Settings.LogLevel;
+	Console.debug("✅ Merge", `Root.Settings类型: ${typeof Root.Settings}`, `Root.Settings: ${JSON.stringify(Root.Settings)}`);
 	/***************** traverseObject *****************/
-	traverseObject(Store.Settings, (key, value) => {
+	traverseObject(Root.Settings, (key, value) => {
 		Console.debug("☑️ traverseObject", `${key}: ${typeof value}`, `${key}: ${JSON.stringify(value)}`);
 		if (value === "true" || value === "false")
 			value = JSON.parse(value); // 字符串转Boolean
@@ -76,9 +107,9 @@ export function getStorage(key, names, database) {
 		}
 		return value;
 	});
-	Console.debug("✅ traverseObject", `Store.Settings类型: ${typeof Store.Settings}`, `Store.Settings: ${JSON.stringify(Store.Settings)}`);
+	Console.debug("✅ traverseObject", `Root.Settings类型: ${typeof Root.Settings}`, `Root.Settings: ${JSON.stringify(Root.Settings)}`);
 	Console.debug("✅ getStorage");
-	return Store;
+	return Root;
 }
 
 /**

package/lib/argument.mjs

@@ -18,25 +18,37 @@ import { Lodash as _ } from "../polyfill/Lodash.mjs";
  * Execution timing:
  * - 该模块为即时执行模块，`import` 时立即处理全局 `$argument`
  * - This module executes immediately and mutates global `$argument` on import
+ *
+ * 归一化规则补充:
+ * Normalization details:
+ * - 使用 `globalThis.$argument` 读写，避免运行环境下未声明变量引用问题
+ * - Read/write via `globalThis.$argument` to avoid undeclared variable access
+ * - 当 `$argument` 为 `null` 或 `undefined` 时，会重置为 `{}`
+ * - When `$argument` is `null` or `undefined`, it is normalized to `{}`
  */
 (() => {
 	Console.debug("☑️ $argument");
-	switch (typeof $argument) {
+	switch (typeof globalThis.$argument) {
 		case "string": {
-			const argument = Object.fromEntries($argument.split("&").map(item => item.split("=", 2).map(i => i.replace(/\"/g, ""))));
-			$argument = {};
-			Object.keys(argument).forEach(key => _.set($argument, key, argument[key]));
+			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($argument).forEach(key => _.set(argument, key, $argument[key]));
-			$argument = argument;
+			Object.keys(globalThis.$argument).forEach(key => _.set(argument, key, globalThis.$argument[key]));
+			globalThis.$argument = argument;
 			break;
 		}
 		case "undefined":
+			globalThis.$argument = {};
 			break;
 	}
-	if ($argument.LogLevel) Console.logLevel = $argument.LogLevel;
-	Console.debug("✅ $argument", `$argument: ${JSON.stringify($argument)}`);
+	if (globalThis.$argument.LogLevel) Console.logLevel = globalThis.$argument.LogLevel;
+	Console.debug("✅ $argument", `$argument: ${JSON.stringify(globalThis.$argument)}`);
 })();

package/package.json

@@ -39,5 +39,5 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "2.1.1"
+  "version": "2.1.3"
 }

package/polyfill/Lodash.mjs

@@ -9,6 +9,8 @@
  * - This is a simplified subset, not a full Lodash implementation
  * - 各方法语义可参考 Lodash 官方文档
  * - Method semantics can be referenced from official Lodash docs
+ * - 导入时建议使用 `Lodash as _`，遵循 lodash 官方示例惯例
+ * - Use `Lodash as _` when importing, following official lodash example convention
  *
  * 参考:
  * Reference:
@@ -22,6 +24,8 @@ export class Lodash {
 	 *
 	 * @param {string} string 输入文本 / Input text.
 	 * @returns {string}
+	 * @see {@link https://lodash.com/docs/#escape lodash.escape}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.escape lodash.escape (中文)}
 	 */
 	static escape(string) {
 		const map = {
@@ -42,6 +46,8 @@ export class Lodash {
 	 * @param {string|string[]} [path=""] 路径 / Path.
 	 * @param {*} [defaultValue=undefined] 默认值 / Default value.
 	 * @returns {*}
+	 * @see {@link https://lodash.com/docs/#get lodash.get}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.get lodash.get (中文)}
 	 */
 	static get(object = {}, path = "", defaultValue = undefined) {
 		// translate array case to dot case, then split with .
@@ -80,6 +86,8 @@ export class Lodash {
 	 * @param {...object} sources - Source objects.
 	 * @returns {object} 返回合并后的目标对象
 	 * @returns {object} Merged target object.
+	 * @see {@link https://lodash.com/docs/#merge lodash.merge}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.merge lodash.merge (中文)}
 	 * @example
 	 * const target = { a: { b: 1 }, c: 2 };
 	 * const source = { a: { d: 3 }, e: 4 };
@@ -141,6 +149,8 @@ export class Lodash {
 	 * @param {*} value - Value to check.
 	 * @returns {boolean} 如果是普通对象返回 true
 	 * @returns {boolean} Returns true when value is a plain object.
+	 * @see {@link https://lodash.com/docs/#isPlainObject lodash.isPlainObject}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.isPlainObject lodash.isPlainObject (中文)}
 	 */
 	static #isPlainObject(value) {
 		if (value === null || typeof value !== "object") return false;
@@ -155,6 +165,8 @@ export class Lodash {
 	 * @param {object} [object={}] 目标对象 / Target object.
 	 * @param {string|string[]} [paths=[]] 要删除的路径 / Paths to remove.
 	 * @returns {object}
+	 * @see {@link https://lodash.com/docs/#omit lodash.omit}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.omit lodash.omit (中文)}
 	 */
 	static omit(object = {}, paths = []) {
 		if (!Array.isArray(paths)) paths = [paths.toString()];
@@ -169,6 +181,8 @@ export class Lodash {
 	 * @param {object} [object={}] 目标对象 / Target object.
 	 * @param {string|string[]} [paths=[]] 需要保留的键 / Keys to keep.
 	 * @returns {object}
+	 * @see {@link https://lodash.com/docs/#pick lodash.pick}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.pick lodash.pick (中文)}
 	 */
 	static pick(object = {}, paths = []) {
 		if (!Array.isArray(paths)) paths = [paths.toString()];
@@ -184,6 +198,8 @@ export class Lodash {
 	 * @param {string|string[]} path 路径 / Path.
 	 * @param {*} value 写入值 / Value.
 	 * @returns {object}
+	 * @see {@link https://lodash.com/docs/#set lodash.set}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.set lodash.set (中文)}
 	 */
 	static set(object, path, value) {
 		if (!Array.isArray(path)) path = Lodash.toPath(path);
@@ -197,6 +213,8 @@ export class Lodash {
 	 *
 	 * @param {string} value 路径字符串 / Path string.
 	 * @returns {string[]}
+	 * @see {@link https://lodash.com/docs/#toPath lodash.toPath}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.toPath lodash.toPath (中文)}
 	 */
 	static toPath(value) {
 		return value
@@ -211,6 +229,8 @@ export class Lodash {
 	 *
 	 * @param {string} string 输入文本 / Input text.
 	 * @returns {string}
+	 * @see {@link https://lodash.com/docs/#unescape lodash.unescape}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.unescape lodash.unescape (中文)}
 	 */
 	static unescape(string) {
 		const map = {
@@ -230,6 +250,8 @@ export class Lodash {
 	 * @param {object} [object={}] 目标对象 / Target object.
 	 * @param {string|string[]} [path=""] 路径 / Path.
 	 * @returns {boolean}
+	 * @see {@link https://lodash.com/docs/#unset lodash.unset}
+	 * @see {@link https://www.lodashjs.com/docs/lodash.unset lodash.unset (中文)}
 	 */
 	static unset(object = {}, path = "") {
 		if (!Array.isArray(path)) path = Lodash.toPath(path);

package/polyfill/Storage.mjs

@@ -172,6 +172,12 @@ export class Storage {
 	 * 删除存储值。
 	 * Remove value from persistent storage.
 	 *
+	 * 平台说明:
+	 * Platform notes:
+	 * - Quantumult X: `$prefs.removeValueForKey`
+	 * - Surge: 通过 `$persistentStore.write(null, keyName)` 删除
+	 * - 其余平台当前返回 `false`
+	 *
 	 * @param {string} keyName 键名或路径键 / Key or path key.
 	 * @returns {boolean}
 	 */
@@ -190,6 +196,8 @@ export class Storage {
 			default:
 				switch ($app) {
 					case "Surge":
+						result = $persistentStore.write(null, keyName);
+						break;
 					case "Loon":
 					case "Stash":
 					case "Egern":