@nsnanocat/util 2.1.3 → 2.1.5

package/README.md

@@ -315,10 +315,11 @@ await runScript("$done({})", { timeout: 20 });
   - `database: object`（默认数据库）
 - 返回：`{ Settings, Configs, Caches }`
 
-合并顺序由 `$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]`
+合并顺序由 `$argument.Storage` 控制（持久化读取统一使用 `PersistentStore = Storage.getItem(key, {})`；支持别名）：
+- 可用值（大小写敏感）：`undefined` | `Argument` | `$argument` | `PersistentStore` | `BoxJs` | `boxjs` | `$persistentStore` | `database`
+1. `undefined`：`database[name]` -> `$argument` -> `PersistentStore[name]`
+2. `Argument` / `$argument`：`database[name]` -> `PersistentStore[name]` -> `$argument`
+3. `PersistentStore` / `BoxJs` / `$persistentStore`（默认）：`database[name]` -> `PersistentStore[name]`
 4. `database`：仅 `database[name]`
 
 注意：`Configs` 与 `Caches` 始终按每个 `name` 合并（与 `$argument.Storage` 无关）。
@@ -330,7 +331,7 @@ 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);
 ```

package/getStorage.mjs

@@ -17,25 +17,30 @@ import { Storage } from "./polyfill/Storage.mjs";
  * 读取并合并默认配置、持久化配置与 `$argument`。
  * Read and merge default config, persisted config and `$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`.
+ * 注意：`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` (aliases supported).
  *
- * 合并来源与顺序由 `$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]`
+ * 合并来源与顺序由 `$argument.Storage` 控制（支持以下值 / 别名）：
+ * Merge source order is controlled by `$argument.Storage` (accepted values / aliases):
+ * - `undefined`: `database[name]` -> `$argument` -> `PersistentStore[name]`
+ * - `Argument` / `$argument`: `database[name]` -> `PersistentStore[name]` -> `$argument`
+ * - `PersistentStore` / `BoxJs` / `boxjs` / `$persistentStore`（默认）：`database[name]` -> `PersistentStore[name]`
  * - `database`: 仅 `database[name]`
  *
- * @since 2.1.2
+ * 注意：字符串比较为精确匹配（区分大小写）。
+ *
+ * @since 2.1.3
  * @link https://github.com/NanoCat-Me/utils/blob/main/getStorage.mjs
  * @author VirgilClyne
  * @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}
+ *
+ * @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);
@@ -65,14 +70,18 @@ export function getStorage(key, names, database) {
 		_.merge(Root.Caches, PersistentStore?.[name]?.Caches);
 	});
 	switch ($argument.Storage) {
+		case "Argument":
 		case "$argument":
 			names.forEach(name => {
 				_.merge(Root.Settings, database?.[name]?.Settings, PersistentStore?.[name]?.Settings);
 			});
 			_.merge(Root.Settings, $argument);
 			break;
+		default:
 		case "BoxJs":
+		case "boxjs":
 		case "PersistentStore":
+		case "$persistentStore":
 			names.forEach(name => {
 				_.merge(Root.Settings, database?.[name]?.Settings, PersistentStore?.[name]?.Settings);
 			});
@@ -82,7 +91,6 @@ export function getStorage(key, names, database) {
 				_.merge(Root.Settings, database?.[name]?.Settings);
 			});
 			break;
-		default:
 		case undefined:
 			names.forEach(name => {
 				_.merge(Root.Settings, database?.[name]?.Settings);

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.3"
+  "version": "2.1.5"
 }

package/types/nsnanocat-util.d.ts

@@ -0,0 +1,134 @@
+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 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>;
+}