@nsnanocat/util 2.6.3 → 2.6.4

package/README.md

@@ -90,6 +90,7 @@ import {
 - `lib/environment.mjs`
 - `lib/runScript.mjs`
 - `getStorage.mjs`（薯条项目自用，仅当你的存储结构与薯条项目一致时再使用；请通过子路径 `@nsnanocat/util/getStorage.mjs` 导入）
+- `polyfill/Storage.cjs`（Node.js / Worker CJS 入口；请通过子路径 `@nsnanocat/util/polyfill/Storage` 导入）
 
 ## 模块依赖关系
 
@@ -108,7 +109,7 @@ import {
 | `getStorage.mjs` | `lib/argument.mjs`, `polyfill/Console.mjs`, `polyfill/Lodash.mjs`, `polyfill/Storage.mjs` | `Console.debug`, `Console.logLevel`, `Lodash.merge`, `Storage.getItem` | 先标准化 `$argument`，再合并默认配置/持久化配置/运行参数 |
 | `polyfill/Console.mjs` | `lib/app.mjs` | `$app` | 日志在 Worker / Node.js 与 iOS 脚本环境使用不同错误输出策略 |
 | `polyfill/fetch.mjs` | `lib/app.mjs`, `polyfill/Lodash.mjs`, `polyfill/StatusTexts.mjs`, `polyfill/Console.mjs` | `$app`, `Lodash.set`, `StatusTexts`（`Console` 当前版本未实际调用） | 按平台选请求引擎并做参数映射、响应结构统一 |
-| `polyfill/Storage.mjs` | `lib/app.mjs`, `polyfill/Lodash.mjs` | `$app`, `Lodash.get`, `Lodash.set`, `Lodash.unset` | 按平台选持久化后端并支持 `@key.path` 读写 |
+| `polyfill/Storage.mjs` | `lib/app.mjs`, `polyfill/Lodash.mjs` | `$app`, `Lodash.get`, `Lodash.set`, `Lodash.unset` | ESM 路径下按平台选持久化后端并支持 `@key.path` 读写（Node.js 请走 `Storage.cjs`） |
 | `polyfill/Lodash.mjs` | 无 | 无 | 提供路径/合并等基础能力，被多个模块复用 |
 | `polyfill/qs.mjs` | `polyfill/Lodash.mjs` | `Lodash.get`, `Lodash.set`, `Lodash.toPath` | 提供查询字符串与对象之间的解析/序列化能力 |
 | `polyfill/StatusTexts.mjs` | 无 | 无 | 提供 HTTP 状态文案，供 `fetch/done` 使用 |
@@ -434,7 +435,11 @@ Worker / Node.js 使用说明：
 
 ### `polyfill/Storage.mjs`
 
-`Storage` 是仿照 Web Storage 接口（`Storage`）设计的跨平台持久化适配器：
+`Storage` 已拆分为 ESM / CJS 两条运行路径：
+- `polyfill/Storage.mjs`：用于 iOS 脚本平台 + Worker
+- `polyfill/Storage.cjs`：用于 Worker / Node.js（含 `box.dat` 文件读写）
+
+`polyfill/Storage.mjs` 仍仿照 Web Storage 接口（`Storage`）设计：
 - 参考文档：https://developer.mozilla.org/en-US/docs/Web/API/Storage
 - 中文文档：https://developer.mozilla.org/zh-CN/docs/Web/API/Storage
 - 目标：统一 VPN App 脚本环境中的持久化读写接口，并尽量贴近 Web Storage 行为
@@ -452,23 +457,31 @@ Worker / Node.js 使用说明：
 - Quantumult X：可用（`$prefs.removeValueForKey`）。
 - Surge：通过 `$persistentStore.write(null, keyName)` 删除。
 - Worker：可用（仅删除内存缓存中的对应 key，不持久化）。
-- Node.js：可用（删除 `box.dat` 中对应 key 并落盘）。
+- Node.js：ESM 路径不支持，会提示改用 CJS 入口。
 - Loon / Stash / Egern / Shadowrocket：返回 `false`。
 
 #### `Storage.clear()`
 - Quantumult X：可用（`$prefs.removeAllValues`）。
 - Worker：可用（仅清空内存缓存，不持久化）。
-- Node.js：可用（清空 `box.dat` 并落盘）。
+- Node.js：ESM 路径不支持，会提示改用 CJS 入口。
 - 其他平台：返回 `false`。
 
-#### Worker / Node.js 特性
+#### Worker 特性（ESM）
 - Worker：使用进程内内存缓存，不写文件。
+
+#### Node.js 特性（CJS）
 - 数据文件默认：`box.dat`。
 - 读取路径优先级：当前目录 -> `process.cwd()`。
 
+Node.js 使用说明：
+- 请通过 CJS 入口调用：`require("@nsnanocat/util").Storage` 或 `require("@nsnanocat/util/polyfill/Storage").Storage`
+- CJS 的 `Storage` 分支支持 `box.dat` 读写与落盘
+
 与 Web Storage 的行为差异：
 - 支持 `@key.path` 深路径读写（Web Storage 原生不支持）。
-- `removeItem/clear` 仅部分平台可用（目前为 Quantumult X、Worker、Node.js，以及 Surge 的 `removeItem`）。
+- `removeItem/clear` 仅部分平台可用：
+  - ESM 路径：Quantumult X、Worker，以及 Surge 的 `removeItem`
+  - CJS 路径：Worker、Node.js
 - `getItem` 会尝试 `JSON.parse`，`setItem` 写入对象会 `JSON.stringify`。
 
 平台后端映射：
@@ -477,8 +490,8 @@ Worker / Node.js 使用说明：
 | --- | --- |
 | Surge / Loon / Stash / Egern / Shadowrocket | `$persistentStore.read/write` |
 | Quantumult X | `$prefs.valueForKey/setValueForKey` |
-| Worker | 进程内内存缓存 |
-| Node.js | 本地 `box.dat` |
+| Worker（ESM/CJS） | 进程内内存缓存 |
+| Node.js（仅 CJS） | 本地 `box.dat` |
 
 ### `polyfill/Console.mjs`
 

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

package/index.cjs

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

package/index.js

@@ -9,7 +9,7 @@ export * from "./polyfill/fetch.mjs";
 export * from "./polyfill/Lodash.mjs";
 export * from "./polyfill/qs.mjs";
 export * from "./polyfill/StatusTexts.mjs";
-export * from "./polyfill/Storage.js";
+export * from "./polyfill/Storage.mjs";
 
 /**
  * 已标准化的 `$argument` 快照。

package/package.json

@@ -23,6 +23,10 @@
       "import": "./polyfill/fetch.mjs",
       "require": "./polyfill/fetch.cjs"
     },
+    "./polyfill/Storage": {
+      "import": "./polyfill/Storage.mjs",
+      "require": "./polyfill/Storage.cjs"
+    },
     "./*": "./*"
   },
   "types": "types/nsnanocat-util.d.ts",
@@ -59,5 +63,5 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "2.6.3"
+  "version": "2.6.4"
 }

package/polyfill/Storage.cjs

@@ -0,0 +1,220 @@
+"use strict";
+
+const { Lodash: _ } = require("./Lodash.mjs");
+
+/**
+ * 仅面向 Worker / Node.js 的持久化存储适配器（CJS 版本）。
+ * Persistent storage adapter for Worker / Node.js only (CJS version).
+ */
+class Storage {
+	/**
+	 * Worker / Node.js 环境下的内存数据缓存。
+	 * In-memory data cache for Worker / Node.js runtime.
+	 *
+	 * @type {Record<string, any>|null}
+	 */
+	static data = null;
+
+	/**
+	 * Node.js 持久化文件名。
+	 * Data file name used in Node.js.
+	 *
+	 * @type {string}
+	 */
+	static dataFile = "box.dat";
+
+	/**
+	 * `@key.path` 解析正则。
+	 * Regex for `@key.path` parsing.
+	 *
+	 * @type {RegExp}
+	 */
+	static #nameRegex = /^@(?<key>[^.]+)(?:\.(?<path>.*))?$/;
+
+	/**
+	 * 读取存储值。
+	 * Read value from persistent storage.
+	 *
+	 * @param {string} keyName 键名或路径键 / Key or path key.
+	 * @param {*} [defaultValue=null] 默认值 / Default value when key is missing.
+	 * @returns {*}
+	 */
+	static getItem(keyName, defaultValue = null) {
+		let keyValue = defaultValue;
+		switch (keyName.startsWith("@")) {
+			case true: {
+				const { key, path } = keyName.match(Storage.#nameRegex)?.groups;
+				keyName = key;
+				let value = Storage.getItem(keyName, {});
+				if (typeof value !== "object") value = {};
+				keyValue = _.get(value, path);
+				try {
+					keyValue = JSON.parse(keyValue);
+				} catch {}
+				break;
+			}
+			default:
+				if (typeof process !== "undefined" && process.versions?.node) {
+					Storage.data = Storage.#loaddata(Storage.dataFile);
+					keyValue = Storage.data?.[keyName];
+				} else {
+					Storage.data = Storage.data ?? {};
+					keyValue = Storage.data[keyName];
+				}
+				try {
+					keyValue = JSON.parse(keyValue);
+				} catch {}
+				break;
+		}
+		return keyValue ?? defaultValue;
+	}
+
+	/**
+	 * 写入存储值。
+	 * Write value into persistent storage.
+	 *
+	 * @param {string} keyName 键名或路径键 / Key or path key.
+	 * @param {*} keyValue 写入值 / Value to store.
+	 * @returns {boolean}
+	 */
+	static setItem(keyName = new String(), keyValue = new String()) {
+		let result = false;
+		switch (typeof keyValue) {
+			case "object":
+				keyValue = JSON.stringify(keyValue);
+				break;
+			default:
+				keyValue = String(keyValue);
+				break;
+		}
+		switch (keyName.startsWith("@")) {
+			case true: {
+				const { key, path } = keyName.match(Storage.#nameRegex)?.groups;
+				keyName = key;
+				let value = Storage.getItem(keyName, {});
+				if (typeof value !== "object") value = {};
+				_.set(value, path, keyValue);
+				result = Storage.setItem(keyName, value);
+				break;
+			}
+			default:
+				if (typeof process !== "undefined" && process.versions?.node) {
+					Storage.data = Storage.#loaddata(Storage.dataFile);
+					Storage.data[keyName] = keyValue;
+					Storage.#writedata(Storage.dataFile);
+					result = true;
+				} else {
+					Storage.data = Storage.data ?? {};
+					Storage.data[keyName] = keyValue;
+					result = true;
+				}
+				break;
+		}
+		return result;
+	}
+
+	/**
+	 * 删除存储值。
+	 * Remove value from persistent storage.
+	 *
+	 * @param {string} keyName 键名或路径键 / Key or path key.
+	 * @returns {boolean}
+	 */
+	static removeItem(keyName) {
+		let result = false;
+		switch (keyName.startsWith("@")) {
+			case true: {
+				const { key, path } = keyName.match(Storage.#nameRegex)?.groups;
+				keyName = key;
+				let value = Storage.getItem(keyName);
+				if (typeof value !== "object") value = {};
+				_.unset(value, path);
+				result = Storage.setItem(keyName, value);
+				break;
+			}
+			default:
+				if (typeof process !== "undefined" && process.versions?.node) {
+					Storage.data = Storage.#loaddata(Storage.dataFile);
+					delete Storage.data[keyName];
+					Storage.#writedata(Storage.dataFile);
+					result = true;
+				} else {
+					Storage.data = Storage.data ?? {};
+					delete Storage.data[keyName];
+					result = true;
+				}
+				break;
+		}
+		return result;
+	}
+
+	/**
+	 * 清空存储。
+	 * Clear storage.
+	 *
+	 * @returns {boolean}
+	 */
+	static clear() {
+		if (typeof process !== "undefined" && process.versions?.node) {
+			Storage.data = Storage.#loaddata(Storage.dataFile);
+			Storage.data = {};
+			Storage.#writedata(Storage.dataFile);
+			return true;
+		}
+		Storage.data = {};
+		return true;
+	}
+
+	/**
+	 * 从 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 => {
+		const fs = require("node:fs");
+		const path = require("node:path");
+		const curDirDataFilePath = path.resolve(dataFile);
+		const rootDirDataFilePath = path.resolve(process.cwd(), dataFile);
+		const isCurDirDataFile = fs.existsSync(curDirDataFilePath);
+		const isRootDirDataFile = !isCurDirDataFile && fs.existsSync(rootDirDataFilePath);
+		if (isCurDirDataFile || isRootDirDataFile) {
+			const datPath = isCurDirDataFile ? curDirDataFilePath : rootDirDataFilePath;
+			try {
+				return JSON.parse(fs.readFileSync(datPath));
+			} catch {
+				return {};
+			}
+		}
+		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) => {
+		const fs = require("node:fs");
+		const path = require("node:path");
+		const curDirDataFilePath = path.resolve(dataFile);
+		const rootDirDataFilePath = path.resolve(process.cwd(), dataFile);
+		const isCurDirDataFile = fs.existsSync(curDirDataFilePath);
+		const isRootDirDataFile = !isCurDirDataFile && fs.existsSync(rootDirDataFilePath);
+		const jsondata = JSON.stringify(this.data);
+		if (isCurDirDataFile) {
+			fs.writeFileSync(curDirDataFilePath, jsondata);
+		} else if (isRootDirDataFile) {
+			fs.writeFileSync(rootDirDataFilePath, jsondata);
+		} else {
+			fs.writeFileSync(curDirDataFilePath, jsondata);
+		}
+	};
+}
+
+module.exports = { Storage };

package/polyfill/{Storage.js → Storage.mjs}

@@ -82,7 +82,7 @@ export class Storage {
 				keyValue = _.get(value, path);
 				try {
 					keyValue = JSON.parse(keyValue);
-				} catch (e) {}
+				} catch {}
 				break;
 			}
 			default:
@@ -102,16 +102,14 @@ export class Storage {
 						keyValue = Storage.data[keyName];
 						break;
 					case "Node.js":
-						Storage.data = Storage.#loaddata(Storage.dataFile);
-						keyValue = Storage.data?.[keyName];
-						break;
+						throw new Error(`${Storage.name}.getItem: ESM 版本不支持 Node.js，请改用 CJS 入口`);
 					default:
 						keyValue = Storage.data?.[keyName] || null;
 						break;
 				}
 				try {
 					keyValue = JSON.parse(keyValue);
-				} catch (e) {
+				} catch {
 					// do nothing
 				}
 				break;
@@ -165,11 +163,7 @@ export class Storage {
 						result = true;
 						break;
 					case "Node.js":
-						Storage.data = Storage.#loaddata(Storage.dataFile);
-						Storage.data[keyName] = keyValue;
-						Storage.#writedata(Storage.dataFile);
-						result = true;
-						break;
+						throw new Error(`${Storage.name}.setItem: ESM 版本不支持 Node.js，请改用 CJS 入口`);
 					default:
 						result = Storage.data?.[keyName] || null;
 						break;
@@ -200,7 +194,7 @@ export class Storage {
 				keyName = key;
 				let value = Storage.getItem(keyName);
 				if (typeof value !== "object") value = {};
-				keyValue = _.unset(value, path);
+				_.unset(value, path);
 				result = Storage.setItem(keyName, value);
 				break;
 			}
@@ -224,12 +218,7 @@ export class Storage {
 						result = true;
 						break;
 					case "Node.js":
-						// result = false;
-						Storage.data = Storage.#loaddata(Storage.dataFile);
-						delete Storage.data[keyName];
-						Storage.#writedata(Storage.dataFile);
-						result = true;
-						break;
+						throw new Error(`${Storage.name}.removeItem: ESM 版本不支持 Node.js，请改用 CJS 入口`);
 					default:
 						result = false;
 						break;
@@ -263,12 +252,7 @@ export class Storage {
 				result = true;
 				break;
 			case "Node.js":
-				// result = false;
-				Storage.data = Storage.#loaddata(Storage.dataFile);
-				Storage.data = {};
-				Storage.#writedata(Storage.dataFile);
-				result = true;
-				break;
+				throw new Error(`${Storage.name}.clear: ESM 版本不支持 Node.js，请改用 CJS 入口`);
 			default:
 				result = false;
 				break;
@@ -276,57 +260,4 @@ 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/index.d.ts

@@ -8,4 +8,4 @@ export type { Fetch, FetchRequest, FetchResponse } from "./fetch.d.ts";
 export { Lodash } from "./Lodash.mjs";
 export { qs } from "./qs.mjs";
 export { StatusTexts } from "./StatusTexts.mjs";
-export { Storage } from "./Storage.js";
+export { Storage } from "./Storage.mjs";

package/polyfill/index.js

@@ -3,4 +3,4 @@ export * from "./fetch.mjs";
 export * from "./Lodash.mjs";
 export * from "./qs.mjs";
 export * from "./StatusTexts.mjs";
-export * from "./Storage.js";
+export * from "./Storage.mjs";