@nsnanocat/util 2.1.0 → 2.1.2

package/getStorage.mjs

@@ -4,49 +4,82 @@ import { Lodash as _ } from "./polyfill/Lodash.mjs";
 import { Storage } from "./polyfill/Storage.mjs";
 
 /**
- * Get Storage Variables
+ * 存储配置读取与合并结果。
+ * Merged storage result object.
+ *
+ * @typedef {object} StorageProfile
+ * @property {Record<string, any>} Settings 运行设置 / Runtime settings.
+ * @property {Record<string, any>} Configs 静态配置 / Static configs.
+ * @property {Record<string, any>} Caches 缓存数据 / Runtime caches.
+ */
+
+/**
+ * 读取并合并默认配置、持久化配置与 `$argument`。
+ * Read and merge default config, persisted config and `$argument`.
+ *
+ * 合并来源与顺序由 `$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]`
+ *
  * @link https://github.com/NanoCat-Me/utils/blob/main/getStorage.mjs
  * @author VirgilClyne
- * @param {string} key - Persistent Store Key
- * @param {array | string} names - Platform Names
- * @param {object} database - Default Database
- * @return {object} { Settings, Caches, Configs }
+ * @param {string} key 持久化主键 / Persistent store key.
+ * @param {string|string[]|Array<string|string[]>} names 目标配置名 / Target profile names.
+ * @param {Record<string, any>} database 默认数据库 / Default database object.
+ * @returns {StorageProfile}
  */
 export 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);
 	/***************** 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);
+		switch ($argument.Storage) {
+			case "$argument":
+				_.merge(Root.Settings, database?.[name]?.Settings, PersistentStore?.[name]?.Settings, $argument);
+				break;
+			case "BoxJs":
+			case "PersistentStore":
+				_.merge(Root.Settings, database?.[name]?.Settings, PersistentStore?.[name]?.Settings);
+				break;
+			case "database":
+				_.merge(Root.Settings, database?.[name]?.Settings);
+				break;
+			default:
+			case undefined:
+				_.merge(Root.Settings, database?.[name]?.Settings, $argument, PersistentStore?.[name]?.Settings);
+				break;
+		}
+		_.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)}`);
+	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
@@ -57,11 +90,19 @@ 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;
 }
 
+/**
+ * 深度遍历对象并用回调替换叶子值。
+ * Deep-walk an object and replace leaf values using callback.
+ *
+ * @param {Record<string, any>} o 目标对象 / Target object.
+ * @param {(key: string, value: any) => any} c 处理回调 / Transformer callback.
+ * @returns {Record<string, any>}
+ */
 function traverseObject(o, c) {
 	for (const t in o) {
 		const n = o[t];
@@ -69,6 +110,14 @@ function traverseObject(o, c) {
 	}
 	return o;
 }
+
+/**
+ * 将纯数字字符串转换为数字。
+ * Convert integer-like string into number.
+ *
+ * @param {string} string 输入字符串 / Input string.
+ * @returns {string|number}
+ */
 function string2number(string) {
 	if (/^\d+$/.test(string)) string = Number.parseInt(string, 10);
 	return string;

package/index.js

@@ -9,4 +9,15 @@ export * from "./polyfill/fetch.mjs";
 export * from "./polyfill/Lodash.mjs";
 export * from "./polyfill/StatusTexts.mjs";
 export * from "./polyfill/Storage.mjs";
-export * from "./getStorage.mjs";
+
+/**
+ * 已标准化的 `$argument` 快照。
+ * Normalized `$argument` snapshot.
+ */
+export const $argument = globalThis.$argument ?? {};
+
+/**
+ * 兼容别名（建议优先使用 `$argument`）。
+ * Backward-compatible alias (prefer `$argument`).
+ */
+export const argument = $argument;

package/lib/app.mjs

@@ -1,7 +1,18 @@
 /**
- * Current app name
+ * 当前运行平台名称。
+ * Current runtime platform name.
  *
- * @type {("Quantumult X" | "Loon" | "Shadowrocket" | "Node.js" | "Egern" | "Surge" | "Stash")}
+ * 识别顺序:
+ * Detection order:
+ * 1) `$task` -> Quantumult X
+ * 2) `$loon` -> Loon
+ * 3) `$rocket` -> Shadowrocket
+ * 4) `module` -> Node.js
+ * 5) `Egern` -> Egern
+ * 6) `$environment["surge-version"]` -> Surge
+ * 7) `$environment["stash-version"]` -> Stash
+ *
+ * @type {("Quantumult X" | "Loon" | "Shadowrocket" | "Node.js" | "Egern" | "Surge" | "Stash" | undefined)}
  */
 export const $app = (() => {
 	const keys = Object.keys(globalThis);

package/lib/argument.mjs

@@ -1,24 +1,54 @@
 import { Console } from "../polyfill/Console.mjs";
 import { Lodash as _ } from "../polyfill/Lodash.mjs";
 
+/**
+ * 统一 `$argument` 输入格式并展开深路径。
+ * Normalize `$argument` input format and expand deep paths.
+ *
+ * 平台差异:
+ * Platform differences:
+ * - Surge / Stash / Egern 常见为字符串参数: `a=1&b=2`
+ * - Surge / Stash / Egern usually pass string args: `a=1&b=2`
+ * - Loon 支持字符串和对象两种形态
+ * - Loon supports both string and object forms
+ * - Quantumult X / Shadowrocket 一般不提供 `$argument`
+ * - Quantumult X / Shadowrocket usually do not expose `$argument`
+ *
+ * 执行时机:
+ * 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/lib/done.mjs

@@ -4,10 +4,30 @@ import { Lodash as _ } from "../polyfill/Lodash.mjs";
 import { StatusTexts } from "../polyfill/StatusTexts.mjs";
 
 /**
- * Complete the script execution
+ * `done` 的统一入参结构。
+ * Unified `done` input payload.
  *
- * @export
- * @param {object} object
+ * @typedef {object} DonePayload
+ * @property {number|string} [status] 响应状态码或状态行 / Response status code or status line.
+ * @property {string} [url] 响应 URL / Response URL.
+ * @property {Record<string, any>} [headers] 响应头 / Response headers.
+ * @property {string|ArrayBuffer|ArrayBufferView} [body] 响应体 / Response body.
+ * @property {ArrayBuffer} [bodyBytes] 二进制响应体 / Binary response body.
+ * @property {string} [policy] 指定策略名 / Preferred policy name.
+ */
+
+/**
+ * 结束脚本执行并按平台转换参数。
+ * Complete script execution with platform-specific parameter mapping.
+ *
+ * 说明:
+ * Notes:
+ * - 这是调用入口，平台原生 `$done` 差异在内部处理
+ * - This is the call entry and native `$done` differences are handled internally
+ * - Node.js 不调用 `$done`，而是直接退出进程
+ * - Node.js does not call `$done`; it exits the process directly
+ *
+ * @param {DonePayload} [object={}] 统一响应对象 / Unified response object.
  * @returns {void}
  */
 export function done(object = {}) {

package/lib/environment.mjs

@@ -1,6 +1,28 @@
 import { $app } from "./app.mjs";
 
+/**
+ * 标准化后的运行环境对象。
+ * Normalized runtime environment object.
+ *
+ * - Surge/Stash/Egern: 基于全局 `$environment` 并补充 `app`
+ * - Surge/Stash/Egern: based on global `$environment` with `app` patched
+ * - Loon: 解析 `$loon` 得到设备与版本信息
+ * - Loon: parse `$loon` into device/version fields
+ * - Quantumult X: 仅返回 `{ app: "Quantumult X" }`
+ * - Quantumult X: returns `{ app: "Quantumult X" }` only
+ * - Node.js: 复用 `process.env` 并写入 `process.env.app`
+ * - Node.js: reuses `process.env` and writes `process.env.app`
+ *
+ * @type {Record<string, any>}
+ */
 export const $environment = environment();
+
+/**
+ * 获取标准化环境对象。
+ * Build and return the normalized environment object.
+ *
+ * @returns {Record<string, any>}
+ */
 export function environment() {
 	switch ($app) {
 		case "Surge":

package/lib/index.js

@@ -4,3 +4,15 @@ export * from "./done.mjs";
 export * from "./notification.mjs";
 export * from "./time.mjs";
 export * from "./wait.mjs";
+
+/**
+ * 已标准化的 `$argument` 快照。
+ * Normalized `$argument` snapshot.
+ */
+export const $argument = globalThis.$argument ?? {};
+
+/**
+ * 兼容别名（建议优先使用 `$argument`）。
+ * Backward-compatible alias (prefer `$argument`).
+ */
+export const argument = $argument;

package/lib/notification.mjs

@@ -2,20 +2,41 @@ import { $app } from "./app.mjs";
 import { Console } from "../polyfill/Console.mjs";
 
 /**
- * 系统通知
+ * 通知内容扩展参数。
+ * Extended notification content options.
  *
- * > 通知参数: 同时支持 QuanX 和 Loon 两种格式, EnvJs根据运行环境自动转换, Surge 环境不支持多媒体通知
- *
- * 示例:
- * $.msg(title, subtitle, body, "twitter://")
- * $.msg(title, subtitle, body, { "open-url": "twitter://", "media-url": "https://github.githubassets.com/images/modules/open_graph/github-mark.png" })
- * $.msg(title, subtitle, body, { "open-url": "https://bing.com", "media-url": "https://github.githubassets.com/images/modules/open_graph/github-mark.png" })
+ * @typedef {object|string|number|boolean} NotificationContent
+ * @property {string} [open] 打开链接 / Open URL.
+ * @property {string} ["open-url"] 打开链接 (QuanX) / Open URL (QuanX).
+ * @property {string} [url] 打开链接 / Open URL.
+ * @property {string} [openUrl] 打开链接 (Loon/Shadowrocket) / Open URL (Loon/Shadowrocket).
+ * @property {string} [copy] 复制文本 / Copy text.
+ * @property {string} ["update-pasteboard"] 复制文本 (QuanX) / Copy text (QuanX).
+ * @property {string} [updatePasteboard] 复制文本 / Copy text.
+ * @property {string} [media] 媒体 URL 或 Base64 / Media URL or Base64.
+ * @property {string} ["media-url"] 媒体 URL / Media URL.
+ * @property {string} [mediaUrl] 媒体 URL / Media URL.
+ * @property {string} [mime] Base64 媒体 MIME / MIME type for Base64 media.
+ * @property {number} ["auto-dismiss"] 自动消失秒数 / Auto dismiss seconds.
+ * @property {string} [sound] 提示音 / Notification sound.
+ */
+
+/**
+ * 发送系统通知并按平台适配参数格式。
+ * Send system notification with platform-specific payload mapping.
  *
- * @param {string} title 标题
- * @param {string} subtitle 副标题
- * @param {string} body 内容
- * @param {*} mutableContent 通知扩展字段
+ * 说明:
+ * Notes:
+ * - iOS App 平台调用 `$notification.post` 或 `$notify`
+ * - iOS app platforms call `$notification.post` or `$notify`
+ * - Node.js 不支持 iOS 通知接口，仅输出日志
+ * - Node.js does not support iOS notification APIs; it logs only
  *
+ * @param {string} [title=`ℹ️ ${$app} 通知`] 标题 / Title.
+ * @param {string} [subtitle=""] 副标题 / Subtitle.
+ * @param {string} [body=""] 内容 / Message body.
+ * @param {NotificationContent} [content={}] 扩展参数 / Extended content options.
+ * @returns {void}
  */
 export function notification(title = `ℹ️ ${$app} 通知`, subtitle = "", body = "", content = {}) {
 	const mutableContent = MutableContent(content);
@@ -39,6 +60,14 @@ export function notification(title = `ℹ️ ${$app} 通知`, subtitle = "", bod
 	Console.groupEnd();
 }
 
+/**
+ * 将统一通知参数转换为平台可识别字段。
+ * Convert normalized content into platform-recognized fields.
+ *
+ * @private
+ * @param {NotificationContent} content 通知扩展参数 / Extended content options.
+ * @returns {Record<string, any>}
+ */
 const MutableContent = content => {
 	const mutableContent = {};
 	switch (typeof content) {

package/lib/runScript.mjs

@@ -3,6 +3,27 @@ import { fetch } from "../polyfill/fetch.mjs";
 import { Lodash as _ } from "../polyfill/Lodash.mjs";
 import { Storage } from "../polyfill/Storage.mjs";
 
+/**
+ * 远程脚本执行选项。
+ * Remote script execution options.
+ *
+ * @typedef {object} RunScriptOptions
+ * @property {number} [timeout] 执行超时秒数 / Timeout in seconds.
+ */
+
+/**
+ * 通过 BoxJS HTTP API 触发脚本执行。
+ * Trigger script execution through BoxJS HTTP API.
+ *
+ * 依赖键:
+ * Required keys:
+ * - `@chavy_boxjs_userCfgs.httpapi` (`password@host:port`)
+ * - `@chavy_boxjs_userCfgs.httpapi_timeout`
+ *
+ * @param {string} script 脚本文本 / Script source text.
+ * @param {RunScriptOptions} [runOpts] 运行选项 / Runtime options.
+ * @returns {Promise<void>}
+ */
 export async function runScript(script, runOpts) {
 	let httpapi = Storage.getItem("@chavy_boxjs_userCfgs.httpapi");
 	httpapi = httpapi?.replace?.(/\n/g, "")?.trim();

package/lib/time.mjs

@@ -1,14 +1,14 @@
 /**
- * time
- * 时间格式化
- * [version of ISO8601]{@link https://262.ecma-international.org/5.1/#sec-15.9.1.15}
- * 示例:time("yyyy-MM-dd qq HH:mm:ss.S") YYYY-MM-DDTHH:mm:ss.sssZ
- *    :time("yyyyMMddHHmmssS")
- *    YY:年 MM:月 dd:日 S:季 HH:时 m:分 ss:秒 sss:毫秒 Z:时区
- *    其中y可选0-4位占位符、S可选0-1位占位符，其余可选0-2位占位符
- * @param {string} format 格式化参数
- * @param {number} ts 可选: 根据指定时间戳返回格式化日期
+ * 按模板格式化时间字符串。
+ * Format date/time into a template string.
  *
+ * 支持占位符:
+ * Supported tokens:
+ * - `YY`, `yyyy`, `MM`, `dd`, `HH`, `mm`, `ss`, `sss`, `S`
+ *
+ * @param {string} format 格式模板 / Format template.
+ * @param {number} [ts] 可选时间戳 / Optional timestamp.
+ * @returns {string}
  */
 export function time(format, ts) {
 	const date = ts ? new Date(ts) : new Date();

package/lib/wait.mjs

@@ -1,9 +1,9 @@
 /**
- * wait
+ * 延时等待指定毫秒后继续执行。
+ * Wait for the given milliseconds before continuing.
  *
- * @export
- * @param {number} [delay=1000]
- * @returns {Promise<resolve>}
+ * @param {number} [delay=1000] 延迟毫秒 / Delay in milliseconds.
+ * @returns {Promise<void>}
  */
 export function wait(delay = 1000) {
 	return new Promise(resolve => setTimeout(resolve, delay));

package/package.json

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