@nsnanocat/util 2.1.4 → 2.1.7

package/README.md

@@ -87,7 +87,7 @@ import {
 ### 仓库中存在但未从主入口导出
 - `lib/environment.mjs`
 - `lib/runScript.mjs`
-- `getStorage.mjs`（薯条项目自用，仅当你的存储结构与薯条项目一致时再使用）
+- `getStorage.mjs`（薯条项目自用，仅当你的存储结构与薯条项目一致时再使用；请通过子路径 `@nsnanocat/util/getStorage.mjs` 导入）
 
 ## 模块依赖关系
 
@@ -331,7 +331,25 @@ await runScript("$done({})", { timeout: 20 });
 
 示例：
 ```js
-import { getStorage } from "@nsnanocat/util/getStorage.mjs";
+import getStorage from "@nsnanocat/util/getStorage.mjs";
+
+const store = getStorage("@my_box", ["YouTube", "Global"], database);
+```
+
+#### 命名导出（辅助函数）
+
+`getStorage.mjs` 同时导出以下辅助函数：
+- `traverseObject(o, c)`：深度遍历对象并替换叶子值
+- `string2number(string)`：将纯数字字符串转换为数字
+- `value2array(value)`：字符串按逗号拆分；数字/布尔值会被包装为单元素数组
+
+示例：
+```js
+import getStorage, {
+  traverseObject,
+  string2number,
+  value2array,
+} from "@nsnanocat/util/getStorage.mjs";
 
 const store = getStorage("@my_box", ["YouTube", "Global"], database);
 ```
@@ -412,10 +430,12 @@ const store = getStorage("@my_box", ["YouTube", "Global"], database);
 #### `Storage.removeItem(keyName)`
 - Quantumult X：可用（`$prefs.removeValueForKey`）。
 - Surge：通过 `$persistentStore.write(null, keyName)` 删除。
-- Loon / Stash / Egern / Shadowrocket / Node.js：返回 `false`。
+- Node.js：可用（删除 `box.dat` 中对应 key 并落盘）。
+- Loon / Stash / Egern / Shadowrocket：返回 `false`。
 
 #### `Storage.clear()`
 - Quantumult X：可用（`$prefs.removeAllValues`）。
+- Node.js：可用（清空 `box.dat` 并落盘）。
 - 其他平台：返回 `false`。
 
 #### Node.js 特性
@@ -424,7 +444,7 @@ const store = getStorage("@my_box", ["YouTube", "Global"], database);
 
 与 Web Storage 的行为差异：
 - 支持 `@key.path` 深路径读写（Web Storage 原生不支持）。
-- `removeItem/clear` 仅部分平台可用（目前为 Quantumult X，以及 Surge 的 `removeItem`）。
+- `removeItem/clear` 仅部分平台可用（目前为 Quantumult X、Node.js，以及 Surge 的 `removeItem`）。
 - `getItem` 会尝试 `JSON.parse`，`setItem` 写入对象会 `JSON.stringify`。
 
 平台后端映射：
@@ -604,7 +624,7 @@ console.log(value); // 1
 | 通知 | `$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` | 可用 | 不可用 | `removeItem` 可用 / `clear` 不可用 | 不可用 | 不可用 | 不可用 | 可用 |
 | `policy` 注入（`fetch/done`） | `opts.policy` | `node` | `X-Surge-Policy`(done) | `X-Stash-Selected-Proxy` | 无专门映射 | `X-Surge-Proxy`(fetch) | 无 |
 
 ## 已知限制与注意事项

package/getStorage.mjs

@@ -36,8 +36,11 @@ import { Storage } from "./polyfill/Storage.mjs";
  * @param {string|string[]|Array<string|string[]>} names 目标配置名 / Target profile names.
  * @param {Record<string, any>} database 默认数据库 / Default database object.
  * @returns {StorageProfile}
+ *
+ * @module getStorage
+ * @default
  */
-export function getStorage(key, names, database) {
+export default function getStorage(key, names, database) {
 	if (database?.Default?.Settings?.LogLevel) Console.logLevel = database.Default.Settings.LogLevel;
 	Console.debug("☑️ getStorage");
 	names = [names].flat(Number.POSITIVE_INFINITY);
@@ -103,12 +106,20 @@ export function getStorage(key, names, database) {
 	/***************** traverseObject *****************/
 	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
-		else if (typeof value === "string") {
-			if (value.includes(","))
-				value = value.split(",").map(item => string2number(item)); // 字符串转数组转数字
-			else value = string2number(value); // 字符串转数字
+		switch (typeof value) {
+			case "string":
+				switch (value) {
+					case "true":
+					case "false":
+					case "[]":
+						value = JSON.parse(value); // 字符串转Boolean/空数组
+						break;
+					default:
+						if (value.includes(","))
+							value = value2array(value).map(item => string2number(item)); // 字符串转数组转数字
+						else value = string2number(value); // 字符串转数字
+				}
+				break;
 		}
 		return value;
 	});
@@ -125,7 +136,7 @@ export function getStorage(key, names, database) {
  * @param {(key: string, value: any) => any} c 处理回调 / Transformer callback.
  * @returns {Record<string, any>}
  */
-function traverseObject(o, c) {
+export function traverseObject(o, c) {
 	for (const t in o) {
 		const n = o[t];
 		o[t] = "object" === typeof n && null !== n ? traverseObject(n, c) : c(t, n);
@@ -140,7 +151,26 @@ function traverseObject(o, c) {
  * @param {string} string 输入字符串 / Input string.
  * @returns {string|number}
  */
-function string2number(string) {
+export function string2number(string) {
 	if (/^\d+$/.test(string)) string = Number.parseInt(string, 10);
 	return string;
 }
+
+/**
+ * 将值包装为数组。
+ * Split value into array.
+ *
+ * @param {string|number|boolean|string[]|null|undefined} value 输入值 / Input value.
+ * @returns {(string|number|boolean)[]}
+ */
+export function value2array(value) {
+	switch (typeof value) {
+		case "string":
+			return value.split(",");
+		case "number":
+		case "boolean":
+			return [value];
+		default:
+			return value || [];
+	}
+}

package/package.json

@@ -14,6 +14,7 @@
   "license": "Apache-2.0",
   "bugs": "https://github.com/NSNanoCat/util/issues",
   "main": "index.js",
+  "types": "types/nsnanocat-util.d.ts",
   "type": "module",
   "scripts": {
     "tsc:build": "npx tsc",
@@ -30,7 +31,8 @@
     "index.js",
     "lib",
     "polyfill",
-    "getStorage.mjs"
+    "getStorage.mjs",
+    "types"
   ],
   "devDependencies": {
     "typescript": "^5.6.3"
@@ -39,5 +41,5 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "2.1.4"
+  "version": "2.1.7"
 }

package/polyfill/Storage.mjs

@@ -208,7 +208,11 @@ export class Storage {
 						result = $prefs.removeValueForKey(keyName);
 						break;
 					case "Node.js":
-						result = false;
+						// result = false;
+						Storage.data = Storage.#loaddata(Storage.dataFile);
+						delete Storage.data[keyName];
+						Storage.#writedata(Storage.dataFile);
+						result = true;
 						break;
 					default:
 						result = false;
@@ -239,7 +243,11 @@ export class Storage {
 				result = $prefs.removeAllValues();
 				break;
 			case "Node.js":
-				result = false;
+				// result = false;
+				Storage.data = Storage.#loaddata(Storage.dataFile);
+				Storage.data = {};
+				Storage.#writedata(Storage.dataFile);
+				result = true;
 				break;
 			default:
 				result = false;

package/types/nsnanocat-util.d.ts

@@ -0,0 +1,143 @@
+declare module "@nsnanocat/util" {
+	export type AppName = "Quantumult X" | "Loon" | "Shadowrocket" | "Node.js" | "Egern" | "Surge" | "Stash";
+
+	export const $app: AppName | undefined;
+	export const $argument: Record<string, unknown>;
+	export const argument: typeof $argument;
+
+	export interface DonePayload {
+		status?: number | string;
+		url?: string;
+		headers?: Record<string, unknown>;
+		body?: string | ArrayBuffer | ArrayBufferView;
+		bodyBytes?: ArrayBuffer;
+		policy?: string;
+	}
+
+	export function done(object?: DonePayload): void;
+
+	export interface NotificationContentObject {
+		open?: string;
+		"open-url"?: string;
+		url?: string;
+		openUrl?: string;
+		copy?: string;
+		"update-pasteboard"?: string;
+		updatePasteboard?: string;
+		media?: string;
+		"media-url"?: string;
+		mediaUrl?: string;
+		mime?: string;
+		"auto-dismiss"?: number;
+		sound?: string;
+	}
+
+	export type NotificationContent = NotificationContentObject | string | number | boolean;
+
+	export function notification(
+		title?: string,
+		subtitle?: string,
+		body?: string,
+		content?: NotificationContent,
+	): void;
+
+	export function time(format: string, ts?: number): string;
+	export function wait(delay?: number): Promise<void>;
+
+	export interface FetchRequest {
+		url: string;
+		method?: string;
+		headers?: Record<string, unknown>;
+		body?: string | ArrayBuffer | ArrayBufferView | object;
+		bodyBytes?: ArrayBuffer;
+		timeout?: number | string;
+		policy?: string;
+		redirection?: boolean;
+		"auto-redirect"?: boolean;
+		opts?: Record<string, unknown>;
+		[key: string]: unknown;
+	}
+
+	export interface FetchResponse {
+		ok: boolean;
+		status: number;
+		statusCode?: number;
+		statusText?: string;
+		headers?: Record<string, unknown>;
+		body?: string | ArrayBuffer;
+		bodyBytes?: ArrayBuffer;
+		[key: string]: unknown;
+	}
+
+	export function fetch(resource: FetchRequest | string, options?: Partial<FetchRequest>): Promise<FetchResponse>;
+
+	export class Console {
+		static clear(): void;
+		static count(label?: string): void;
+		static countReset(label?: string): void;
+		static debug(...msg: unknown[]): void;
+		static error(...msg: unknown[]): void;
+		static exception(...msg: unknown[]): void;
+		static group(label: string): number;
+		static groupEnd(): string | undefined;
+		static info(...msg: unknown[]): void;
+		static get logLevel(): "OFF" | "ERROR" | "WARN" | "INFO" | "DEBUG" | "ALL";
+		static set logLevel(level: number | string);
+		static log(...msg: unknown[]): void;
+		static time(label?: string): Map<string, number>;
+		static timeEnd(label?: string): boolean;
+		static timeLog(label?: string): void;
+		static warn(...msg: unknown[]): void;
+	}
+
+	export class Lodash {
+		static escape(string: string): string;
+		static get<T = unknown, D = undefined>(object?: Record<string, unknown>, path?: string | string[], defaultValue?: D): T | D;
+		static merge<T extends Record<string, unknown>>(object: T, ...sources: Array<Record<string, unknown> | null | undefined>): T;
+		static omit<T extends Record<string, unknown>>(object?: T, paths?: string | string[]): T;
+		static pick<T extends Record<string, unknown>, K extends keyof T>(object?: T, paths?: K | K[]): Pick<T, K>;
+		static set<T extends Record<string, unknown>>(object: T, path: string | string[], value: unknown): T;
+		static toPath(value: string): string[];
+		static unescape(string: string): string;
+		static unset(object?: Record<string, unknown>, path?: string | string[]): boolean;
+	}
+
+	export const StatusTexts: Record<number, string>;
+
+	export class Storage {
+		static data: Record<string, unknown> | null;
+		static dataFile: string;
+		static getItem<T = unknown>(keyName: string, defaultValue?: T): T;
+		static setItem(keyName: string, keyValue: unknown): boolean;
+		static removeItem(keyName: string): boolean;
+		static clear(): boolean;
+	}
+}
+
+declare module "@nsnanocat/util/getStorage.mjs" {
+	export interface StorageProfile {
+		Settings: Record<string, unknown>;
+		Configs: Record<string, unknown>;
+		Caches: Record<string, unknown>;
+	}
+
+	export function traverseObject(
+		o: Record<string, unknown>,
+		c: (key: string, value: unknown) => unknown,
+	): Record<string, unknown>;
+
+	export function string2number(string: string): string | number;
+
+	export function value2array(value: string | number | boolean | string[] | null | undefined): Array<string | number | boolean>;
+
+	export default function getStorage(
+		key: string,
+		names: string | string[] | Array<string | string[]>,
+		database: Record<string, unknown>,
+	): StorageProfile;
+}
+
+declare module "@nsnanocat/util/lib/environment.mjs" {
+	export const $environment: Record<string, unknown>;
+	export function environment(): Record<string, unknown>;
+}