@nsnanocat/util 2.4.1 → 2.5.2

package/README.md

@@ -5,7 +5,7 @@
 核心目标：
 - 统一不同平台的 HTTP、通知、持久化、结束脚本等调用方式。
 - 在一个脚本里尽量少写平台分支。
-- 提供一组可直接复用的 polyfill（`fetch` / `Storage` / `KV` / `Console` / `Lodash` / `qs`）。
+ - 提供一组可直接复用的 polyfill（`fetch` / `Storage` / `Console` / `Lodash` / `qs`）。
 
 ## 目录
 - [安装与导入](#安装与导入)
@@ -65,7 +65,6 @@ import {
   wait,       // 延时等待工具（Promise）
   Console,    // 统一日志工具（支持 logLevel）
   Lodash as _, // Lodash 建议按官方示例惯例使用 `_` 作为工具对象别名
-  KV,         // Cloudflare Workers KV 异步适配器（显式传入 namespace binding）
   qs,         // 查询字符串工具（parse / stringify）
   Storage,    // 统一持久化存储接口（适配 $prefs / $persistentStore / 内存 / 文件）
 } from "@nsnanocat/util";
@@ -82,7 +81,6 @@ import {
 - `lib/wait.mjs`
 - `polyfill/Console.mjs`
 - `polyfill/fetch.mjs`
-- `polyfill/KV.mjs`
 - `polyfill/Lodash.mjs`
 - `polyfill/qs.mjs`
 - `polyfill/StatusTexts.mjs`
@@ -110,7 +108,6 @@ 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/KV.mjs` | `lib/app.mjs`, `polyfill/Lodash.mjs`, `polyfill/Storage.mjs` | `$app`, `Lodash.get`, `Lodash.set`, `Lodash.unset`, `Storage` | 为 Cloudflare Workers KV 提供异步适配，并在非 Worker 平台回退到 `Storage` |
 | `polyfill/Storage.mjs` | `lib/app.mjs`, `polyfill/Lodash.mjs` | `$app`, `Lodash.get`, `Lodash.set`, `Lodash.unset` | 按平台选持久化后端并支持 `@key.path` 读写 |
 | `polyfill/Lodash.mjs` | 无 | 无 | 提供路径/合并等基础能力，被多个模块复用 |
 | `polyfill/qs.mjs` | `polyfill/Lodash.mjs` | `Lodash.get`, `Lodash.set`, `Lodash.toPath` | 提供查询字符串与对象之间的解析/序列化能力 |
@@ -478,39 +475,6 @@ const store = getStorage("@my_box", ["YouTube", "Global"], database);
 | Worker | 进程内内存缓存 |
 | Node.js | 本地 `box.dat` |
 
-### `polyfill/KV.mjs`
-
-`KV` 是面向 Cloudflare Workers KV 的异步适配器：
-- 调用方显式传入 namespace binding：`new KV(env.NAMESPACE)`
-- Worker 分支直接调用 `namespace.get/put/delete/list`
-- `get()` 不传 `type`，默认按 Cloudflare 行为读取字符串
-- 非 Worker 平台会回退到 `Storage.getItem/setItem/removeItem`
-- `list()` 仅支持 Worker，返回 Cloudflare KV 原生列举结果
-- `clear()` 始终返回 `false`
-
-#### `new KV(namespace)`
-- `namespace` 需提供 `get(key)` / `put(key, value)` / `delete(key)`。
-
-#### `await kv.getItem(keyName, defaultValue = null)`
-- 支持普通 key。
-- 支持路径 key：`@root.path.to.key`。
-- 读取后会尝试 `JSON.parse`。
-
-#### `await kv.setItem(keyName, keyValue)`
-- 支持普通 key 与路径 key。
-- `keyValue` 为对象时自动 `JSON.stringify`。
-
-#### `await kv.removeItem(keyName)`
-- 支持普通 key 与路径 key。
-
-#### `await kv.list(options = {})`
-- 仅支持 Worker。
-- 透传 `prefix` / `limit` / `cursor` 到 `namespace.list(options)`。
-- 返回 Cloudflare KV 的原生结果：`keys` / `list_complete` / `cursor`。
-
-#### `await kv.clear()`
-- 始终返回 `false`。
-
 ### `polyfill/Console.mjs`
 
 `Console` 是统一日志工具（静态类）。

package/index.js

@@ -6,7 +6,6 @@ export * from "./lib/time.mjs";
 export * from "./lib/wait.mjs";
 export * from "./polyfill/Console.mjs";
 export * from "./polyfill/fetch.mjs";
-export * from "./polyfill/KV.mjs";
 export * from "./polyfill/Lodash.mjs";
 export * from "./polyfill/qs.mjs";
 export * from "./polyfill/StatusTexts.mjs";

package/package.json

@@ -42,5 +42,5 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "2.4.1"
+  "version": "2.5.2"
 }

package/polyfill/Console.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 跨平台控制台输出适配器。
+ * Cross-platform console output adapter.
+ */
+export class Console {
+	/**
+	 * 清空控制台输出。
+	 * Clear the console output.
+	 */
+	static clear(): void;
+
+	/**
+	 * 增加指定标签的计数。
+	 * Increment the counter for the given label.
+	 *
+	 * @param label 计数标签 / Counter label.
+	 */
+	static count(label?: string): void;
+
+	/**
+	 * 重置指定标签的计数。
+	 * Reset the counter for the given label.
+	 *
+	 * @param label 计数标签 / Counter label.
+	 */
+	static countReset(label?: string): void;
+
+	/**
+	 * 输出调试级别日志。
+	 * Print debug-level log messages.
+	 *
+	 * @param msg 日志内容 / Log payloads.
+	 */
+	static debug(...msg: unknown[]): void;
+
+	/**
+	 * 输出错误级别日志。
+	 * Print error-level log messages.
+	 *
+	 * @param msg 日志内容 / Log payloads.
+	 */
+	static error(...msg: unknown[]): void;
+
+	/**
+	 * 输出异常级别日志。
+	 * Print exception-level log messages.
+	 *
+	 * @param msg 日志内容 / Log payloads.
+	 */
+	static exception(...msg: unknown[]): void;
+
+	/**
+	 * 开始一个日志分组。
+	 * Start a log group.
+	 *
+	 * @param label 分组标签 / Group label.
+	 * @returns 当前分组深度 / Current group depth.
+	 */
+	static group(label: string): number;
+
+	/**
+	 * 结束当前日志分组。
+	 * End the current log group.
+	 *
+	 * @returns 已结束的分组标签 / Closed group label.
+	 */
+	static groupEnd(): string | undefined;
+
+	/**
+	 * 输出信息级别日志。
+	 * Print info-level log messages.
+	 *
+	 * @param msg 日志内容 / Log payloads.
+	 */
+	static info(...msg: unknown[]): void;
+
+	/**
+	 * 获取当前日志级别。
+	 * Get the current log level.
+	 */
+	static get logLevel(): "OFF" | "ERROR" | "WARN" | "INFO" | "DEBUG" | "ALL";
+
+	/**
+	 * 设置日志级别。
+	 * Set the current log level.
+	 *
+	 * @param level 日志级别 / Log level.
+	 */
+	static set logLevel(level: number | string);
+
+	/**
+	 * 输出普通日志。
+	 * Print standard log messages.
+	 *
+	 * @param msg 日志内容 / Log payloads.
+	 */
+	static log(...msg: unknown[]): void;
+
+	/**
+	 * 启动计时器。
+	 * Start a timer.
+	 *
+	 * @param label 计时器标签 / Timer label.
+	 * @returns 计时器映射表 / Timer map.
+	 */
+	static time(label?: string): Map<string, number>;
+
+	/**
+	 * 结束计时器并返回是否成功结束。
+	 * End a timer and return whether it was closed.
+	 *
+	 * @param label 计时器标签 / Timer label.
+	 * @returns 是否成功结束 / Whether the timer was closed.
+	 */
+	static timeEnd(label?: string): boolean;
+
+	/**
+	 * 输出计时器当前耗时。
+	 * Print current elapsed time for a timer.
+	 *
+	 * @param label 计时器标签 / Timer label.
+	 */
+	static timeLog(label?: string): void;
+
+	/**
+	 * 输出警告级别日志。
+	 * Print warn-level log messages.
+	 *
+	 * @param msg 日志内容 / Log payloads.
+	 */
+	static warn(...msg: unknown[]): void;
+}

package/polyfill/Lodash.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 轻量 Lodash 风格工具集。
+ * Lightweight Lodash-style utility helpers.
+ */
+export class Lodash {
+	/**
+	 * 对 HTML 字符进行转义。
+	 * Escape HTML characters.
+	 *
+	 * @param string 输入字符串 / Input string.
+	 * @returns 转义后的字符串 / Escaped string.
+	 */
+	static escape(string: string): string;
+
+	/**
+	 * 读取对象中的嵌套路径值。
+	 * Read a nested value from an object path.
+	 *
+	 * @param object 目标对象 / Target object.
+	 * @param path 路径表达式 / Path expression.
+	 * @param defaultValue 默认值 / Default value.
+	 * @returns 路径值或默认值 / Path value or default.
+	 */
+	static get<T = unknown, D = undefined>(object?: Record<string, unknown>, path?: string | string[], defaultValue?: D): T | D;
+
+	/**
+	 * 深度合并对象。
+	 * Deep-merge objects.
+	 *
+	 * @param object 目标对象 / Target object.
+	 * @param sources 源对象列表 / Source objects.
+	 * @returns 合并后的目标对象 / Merged target object.
+	 */
+	static merge<T extends Record<string, unknown>>(object: T, ...sources: Array<Record<string, unknown> | null | undefined>): T;
+
+	/**
+	 * 返回排除指定路径后的对象副本。
+	 * Return a copy without specific paths.
+	 *
+	 * @param object 目标对象 / Target object.
+	 * @param paths 排除路径 / Paths to omit.
+	 * @returns 排除后的对象 / Object without omitted paths.
+	 */
+	static omit<T extends Record<string, unknown>>(object?: T, paths?: string | string[]): T;
+
+	/**
+	 * 返回仅包含指定路径的对象副本。
+	 * Return a copy with only selected paths.
+	 *
+	 * @param object 目标对象 / Target object.
+	 * @param paths 选择路径 / Paths to pick.
+	 * @returns 仅保留指定路径的对象 / Object containing picked paths.
+	 */
+	static pick<T extends Record<string, unknown>, K extends keyof T>(object?: T, paths?: K | K[]): Pick<T, K>;
+
+	/**
+	 * 写入对象中的嵌套路径值。
+	 * Set a nested value by path.
+	 *
+	 * @param object 目标对象 / Target object.
+	 * @param path 路径表达式 / Path expression.
+	 * @param value 写入值 / Value to set.
+	 * @returns 修改后的目标对象 / Mutated target object.
+	 */
+	static set<T extends Record<string, unknown>>(object: T, path: string | string[], value: unknown): T;
+
+	/**
+	 * 将路径字符串转换为路径数组。
+	 * Convert a path string to path segments.
+	 *
+	 * @param value 路径字符串 / Path string.
+	 * @returns 路径数组 / Path segments.
+	 */
+	static toPath(value: string): string[];
+
+	/**
+	 * 还原 HTML 转义字符。
+	 * Unescape HTML entities.
+	 *
+	 * @param string 输入字符串 / Input string.
+	 * @returns 还原后的字符串 / Unescaped string.
+	 */
+	static unescape(string: string): string;
+
+	/**
+	 * 删除对象中的嵌套路径值。
+	 * Delete a nested value by path.
+	 *
+	 * @param object 目标对象 / Target object.
+	 * @param path 路径表达式 / Path expression.
+	 * @returns 是否删除成功 / Whether deletion succeeded.
+	 */
+	static unset(object?: Record<string, unknown>, path?: string | string[]): boolean;
+}

package/polyfill/StatusTexts.d.ts

@@ -0,0 +1,5 @@
+/**
+ * HTTP 状态码文案映射表。
+ * HTTP status code text map.
+ */
+export const StatusTexts: Record<number, string>;

package/polyfill/Storage.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 跨平台持久化存储适配器。
+ * Cross-platform persistent storage adapter.
+ */
+export class Storage {
+	/**
+	 * 运行时缓存的数据对象。
+	 * Runtime cached data object.
+	 */
+	static data: Record<string, unknown> | null;
+
+	/**
+	 * Node.js 分支持久化文件名。
+	 * Persistent filename for Node.js branch.
+	 */
+	static dataFile: string;
+
+	/**
+	 * 读取指定键值。
+	 * Read a value by key.
+	 *
+	 * @param keyName 键名 / Key name.
+	 * @param defaultValue 默认值 / Default value.
+	 * @returns 读取结果 / Read value.
+	 */
+	static getItem<T = unknown>(keyName: string, defaultValue?: T): T;
+
+	/**
+	 * 写入指定键值。
+	 * Write a value by key.
+	 *
+	 * @param keyName 键名 / Key name.
+	 * @param keyValue 写入值 / Value to write.
+	 * @returns 是否写入成功 / Whether write succeeded.
+	 */
+	static setItem(keyName: string, keyValue: unknown): boolean;
+
+	/**
+	 * 删除指定键。
+	 * Remove a value by key.
+	 *
+	 * @param keyName 键名 / Key name.
+	 * @returns 是否删除成功 / Whether removal succeeded.
+	 */
+	static removeItem(keyName: string): boolean;
+
+	/**
+	 * 清空存储。
+	 * Clear the storage.
+	 *
+	 * @returns 是否清空成功 / Whether clear succeeded.
+	 */
+	static clear(): boolean;
+}

package/polyfill/fetch.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 统一请求参数。
+ * Unified request payload.
+ */
+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;
+	"auto-cookie"?: boolean | number | string;
+	opts?: Record<string, unknown>;
+	[key: string]: unknown;
+}
+
+/**
+ * 统一响应结构。
+ * Unified response payload.
+ */
+export interface FetchResponse {
+	ok: boolean;
+	status: number;
+	statusCode?: number;
+	statusText?: string;
+	headers?: Record<string, unknown>;
+	body?: string | ArrayBuffer;
+	bodyBytes?: ArrayBuffer;
+	[key: string]: unknown;
+}
+
+/**
+ * 跨平台 `fetch` 函数签名。
+ * Cross-platform `fetch` function signature.
+ *
+ * @param resource 请求对象或 URL / Request object or URL string.
+ * @param options 追加参数 / Extra options.
+ * @returns 统一响应结构 / Normalized response payload.
+ */
+export type Fetch = (resource: FetchRequest | string, options?: Partial<FetchRequest>) => Promise<FetchResponse>;
+
+export const fetch: Fetch;

package/polyfill/fetch.mts

@@ -0,0 +1,6 @@
+import { fetch as fetchRuntime } from "./fetch.mjs";
+import type { Fetch } from "./fetch.d.ts";
+
+export type { Fetch, FetchRequest, FetchResponse } from "./fetch.d.ts";
+
+export const fetch: Fetch = fetchRuntime as Fetch;

package/polyfill/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Polyfill 模块聚合导出。
+ * Aggregated exports for polyfill modules.
+ */
+export { Console } from "./Console.mjs";
+export { fetch } from "./fetch.mjs";
+export type { Fetch, FetchRequest, FetchResponse } from "./fetch.mjs";
+export { Lodash } from "./Lodash.mjs";
+export { qs } from "./qs.mjs";
+export { StatusTexts } from "./StatusTexts.mjs";
+export { Storage } from "./Storage.mjs";

package/polyfill/index.js

@@ -1,6 +1,5 @@
 export * from "./Console.mjs";
 export * from "./fetch.mjs";
-export * from "./KV.mjs";
 export * from "./Lodash.mjs";
 export * from "./qs.mjs";
 export * from "./StatusTexts.mjs";

package/polyfill/qs.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 查询字符串解析与序列化工具。
+ * Query string parser and serializer.
+ */
+export class qs {
+	/**
+	 * 将查询字符串或对象解析为规范对象。
+	 * Parse a query string or object into a normalized object.
+	 *
+	 * @param query 查询输入 / Query input.
+	 * @returns 解析结果对象 / Parsed object.
+	 */
+	static parse(query?: string | Record<string, unknown> | null): Record<string, unknown>;
+
+	/**
+	 * 将对象序列化为查询字符串。
+	 * Serialize an object into a query string.
+	 *
+	 * @param object 输入对象 / Input object.
+	 * @returns 序列化后的查询字符串 / Serialized query string.
+	 */
+	static stringify(object?: Record<string, unknown>): string;
+}

package/types/modules/Lodash.d.ts

@@ -0,0 +1,7 @@
+import type { Lodash as SharedLodash } from "../../polyfill/Lodash.d.ts";
+
+declare module "@nsnanocat/util" {
+	export interface Lodash extends SharedLodash {}
+
+	export const Lodash: typeof import("../../polyfill/Lodash.d.ts").Lodash;
+}

package/types/modules/fetch.d.ts

@@ -1,29 +1,9 @@
+import type { Fetch as SharedFetch, FetchRequest as SharedFetchRequest, FetchResponse as SharedFetchResponse } from "../../polyfill/fetch.d.ts";
+
 declare module "@nsnanocat/util" {
-	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;
-		"auto-cookie"?: boolean | number | string;
-		opts?: Record<string, unknown>;
-		[key: string]: unknown;
-	}
+	export interface FetchRequest extends SharedFetchRequest {}
 
-	export interface FetchResponse {
-		ok: boolean;
-		status: number;
-		statusCode?: number;
-		statusText?: string;
-		headers?: Record<string, unknown>;
-		body?: string | ArrayBuffer;
-		bodyBytes?: ArrayBuffer;
-		[key: string]: unknown;
-	}
+	export interface FetchResponse extends SharedFetchResponse {}
 
-	export function fetch(resource: FetchRequest | string, options?: Partial<FetchRequest>): Promise<FetchResponse>;
+	export const fetch: SharedFetch;
 }

package/types/modules/polyfills.d.ts

@@ -1,40 +1,11 @@
-declare module "@nsnanocat/util" {
-	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;
-	}
+import type { Console as SharedConsole } from "../../polyfill/Console.d.ts";
 
-	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;
-	}
+type SharedStatusTexts = typeof import("../../polyfill/StatusTexts.d.ts").StatusTexts;
 
-	export class qs {
-		static parse(query?: string | Record<string, unknown> | null): Record<string, unknown>;
+declare module "@nsnanocat/util" {
+	export interface Console extends SharedConsole {}
 
-		static stringify(object?: Record<string, unknown>): string;
-	}
+	export const Console: typeof import("../../polyfill/Console.d.ts").Console;
 
-	export const StatusTexts: Record<number, string>;
+	export const StatusTexts: SharedStatusTexts;
 }

package/types/modules/qs.d.ts

@@ -0,0 +1,7 @@
+import type { qs as SharedQs } from "../../polyfill/qs.d.ts";
+
+declare module "@nsnanocat/util" {
+	export interface qs extends SharedQs {}
+
+	export const qs: typeof import("../../polyfill/qs.d.ts").qs;
+}

package/types/modules/storage.d.ts

@@ -1,10 +1,7 @@
+import type { Storage as SharedStorage } from "../../polyfill/Storage.d.ts";
+
 declare module "@nsnanocat/util" {
-	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;
-	}
+	export interface Storage extends SharedStorage {}
+
+	export const Storage: typeof import("../../polyfill/Storage.d.ts").Storage;
 }

package/types/nsnanocat-util.d.ts

@@ -1,7 +1,8 @@
 /// <reference path="./modules/core.d.ts" />
 /// <reference path="./modules/fetch.d.ts" />
+/// <reference path="./modules/Lodash.d.ts" />
 /// <reference path="./modules/polyfills.d.ts" />
+/// <reference path="./modules/qs.d.ts" />
 /// <reference path="./modules/storage.d.ts" />
-/// <reference path="./modules/kv.d.ts" />
 /// <reference path="./modules/getStorage.d.ts" />
 /// <reference path="./modules/environment.d.ts" />

package/polyfill/KV.mjs

@@ -1,218 +0,0 @@
-import { $app } from "../lib/app.mjs";
-import { Lodash as _ } from "./Lodash.mjs";
-import { Storage } from "./Storage.mjs";
-
-/**
- * Cloudflare Workers KV 异步适配器。
- * Async adapter for Cloudflare Workers KV.
- *
- * 设计目标:
- * Design goal:
- * - 提供与 `Storage` 接近的异步接口
- * - Provide an async API close to `Storage`
- * - 在 Worker 中使用显式传入的 KV namespace binding
- * - Use an explicitly passed KV namespace binding in Workers
- * - 在非 Worker 平台回退到 `Storage`
- * - Fall back to `Storage` on non-Worker platforms
- *
- * 支持路径键:
- * Supports path key:
- * - `@root.path.to.value`
- *
- * @link https://developers.cloudflare.com/kv/get-started/#5-access-your-kv-namespace-from-your-worker
- * @link https://developers.cloudflare.com/kv/api/read-key-value-pairs/
- * @link https://developers.cloudflare.com/kv/api/write-key-value-pairs/
- * @link https://developers.cloudflare.com/kv/api/delete-key-value-pairs/
- * @link https://developers.cloudflare.com/kv/api/list-keys/
- */
-export class KV {
-	/**
-	 * `@key.path` 解析正则。
-	 * Regex for `@key.path` parsing.
-	 *
-	 * @type {RegExp}
-	 */
-	static #nameRegex = /^@(?<key>[^.]+)(?:\.(?<path>.*))?$/;
-
-	/**
-	 * Cloudflare KV namespace 绑定。
-	 * Cloudflare KV namespace binding.
-	 *
-	 * @type {{ get(key: string): Promise<string|null>; put(key: string, value: string): Promise<void>; delete(key: string): Promise<void>; list?(options?: { prefix?: string; limit?: number; cursor?: string }): Promise<{ keys: { name: string; expiration?: number; metadata?: object }[]; list_complete: boolean; cursor: string }> } | undefined}
-	 */
-	namespace;
-
-	/**
-	 * 创建 KV 适配器实例。
-	 * Create a KV adapter instance.
-	 *
-	 * @param {{ get(key: string): Promise<string|null>; put(key: string, value: string): Promise<void>; delete(key: string): Promise<void>; list?(options?: { prefix?: string; limit?: number; cursor?: string }): Promise<{ keys: { name: string; expiration?: number; metadata?: object }[]; list_complete: boolean; cursor: string }> } | null | undefined} namespace KV namespace 绑定 / KV namespace binding.
-	 */
-	constructor(namespace) {
-		this.namespace = namespace ?? undefined;
-	}
-
-	/**
-	 * 读取存储值。
-	 * Read value from persistent storage.
-	 *
-	 * @param {string} keyName 键名或路径键 / Key or path key.
-	 * @param {*} [defaultValue=null] 默认值 / Default value when key is missing.
-	 * @returns {Promise<*>}
-	 */
-	async getItem(keyName, defaultValue = null) {
-		let keyValue = defaultValue;
-		switch (keyName.startsWith("@")) {
-			case true: {
-				const { key, path } = keyName.match(KV.#nameRegex)?.groups ?? {};
-				keyName = key;
-				let value = await this.getItem(keyName, {});
-				if (typeof value !== "object" || value === null) value = {};
-				keyValue = _.get(value, path);
-				keyValue = KV.#deserialize(keyValue);
-				break;
-			}
-			default:
-				switch ($app) {
-					case "Worker":
-						keyValue = await this.namespace.get(keyName);
-						break;
-					default:
-						keyValue = Storage.getItem(keyName, defaultValue);
-						break;
-				}
-				keyValue = KV.#deserialize(keyValue);
-				break;
-		}
-		return keyValue ?? defaultValue;
-	}
-
-	/**
-	 * 写入存储值。
-	 * Write value into persistent storage.
-	 *
-	 * @param {string} keyName 键名或路径键 / Key or path key.
-	 * @param {*} keyValue 写入值 / Value to store.
-	 * @returns {Promise<boolean>}
-	 */
-	async setItem(keyName = new String(), keyValue = new String()) {
-		let result = false;
-		keyValue = KV.#serialize(keyValue);
-		switch (keyName.startsWith("@")) {
-			case true: {
-				const { key, path } = keyName.match(KV.#nameRegex)?.groups ?? {};
-				keyName = key;
-				let value = await this.getItem(keyName, {});
-				if (typeof value !== "object" || value === null) value = {};
-				_.set(value, path, keyValue);
-				result = await this.setItem(keyName, value);
-				break;
-			}
-			default:
-				switch ($app) {
-					case "Worker":
-						await this.namespace.put(keyName, keyValue);
-						result = true;
-						break;
-					default:
-						result = Storage.setItem(keyName, keyValue);
-						break;
-				}
-				break;
-		}
-		return result;
-	}
-
-	/**
-	 * 删除存储值。
-	 * Remove value from persistent storage.
-	 *
-	 * @param {string} keyName 键名或路径键 / Key or path key.
-	 * @returns {Promise<boolean>}
-	 */
-	async removeItem(keyName) {
-		let result = false;
-		switch (keyName.startsWith("@")) {
-			case true: {
-				const { key, path } = keyName.match(KV.#nameRegex)?.groups ?? {};
-				keyName = key;
-				let value = await this.getItem(keyName);
-				if (typeof value !== "object" || value === null) value = {};
-				_.unset(value, path);
-				result = await this.setItem(keyName, value);
-				break;
-			}
-			default:
-				switch ($app) {
-					case "Worker":
-						await this.namespace.delete(keyName);
-						result = true;
-						break;
-					default:
-						result = Storage.removeItem(keyName);
-						break;
-				}
-				break;
-		}
-		return result;
-	}
-
-	/**
-	 * 清空存储。
-	 * Clear storage.
-	 *
-	 * @returns {Promise<boolean>}
-	 */
-	async clear() {
-		return false;
-	}
-
-	/**
-	 * 列出命名空间中的键。
-	 * List keys in the namespace.
-	 *
-	 * @param {{ prefix?: string; limit?: number; cursor?: string }} [options={}] 列举选项 / List options.
-	 * @returns {Promise<{ keys: { name: string; expiration?: number; metadata?: object }[]; list_complete: boolean; cursor: string }>}
-	 */
-	async list(options = {}) {
-		switch ($app) {
-			case "Worker":
-				return await this.namespace.list(options);
-			default:
-				throw new TypeError("KV.list() is only supported in Worker runtime.");
-		}
-	}
-
-	/**
-	 * 尝试将字符串反序列化为原始值。
-	 * Try to deserialize a string into its original value.
-	 *
-	 * @private
-	 * @param {*} value 原始值 / Raw value.
-	 * @returns {*}
-	 */
-	static #deserialize(value) {
-		try {
-			return JSON.parse(value);
-		} catch (e) {
-			return value;
-		}
-	}
-
-	/**
-	 * 规范化待写入的值。
-	 * Normalize a value before persisting it.
-	 *
-	 * @private
-	 * @param {*} value 原始值 / Raw value.
-	 * @returns {string}
-	 */
-	static #serialize(value) {
-		switch (typeof value) {
-			case "object":
-				return JSON.stringify(value);
-			default:
-				return String(value);
-		}
-	}
-}

package/types/modules/kv.d.ts

@@ -1,35 +0,0 @@
-declare module "@nsnanocat/util" {
-	export interface KVNamespaceLike {
-		get(key: string): Promise<string | null>;
-		put(key: string, value: string): Promise<void>;
-		delete(key: string): Promise<void>;
-		list?(options?: KVListOptions): Promise<KVListResult>;
-	}
-
-	export interface KVListOptions {
-		prefix?: string;
-		limit?: number;
-		cursor?: string;
-	}
-
-	export interface KVListKey {
-		name: string;
-		expiration?: number;
-		metadata?: Record<string, unknown>;
-	}
-
-	export interface KVListResult {
-		keys: KVListKey[];
-		list_complete: boolean;
-		cursor: string;
-	}
-
-	export class KV {
-		constructor(namespace?: KVNamespaceLike | null);
-		getItem<T = unknown>(keyName: string, defaultValue?: T): Promise<T>;
-		setItem(keyName: string, keyValue: unknown): Promise<boolean>;
-		removeItem(keyName: string): Promise<boolean>;
-		clear(): Promise<boolean>;
-		list(options?: KVListOptions): Promise<KVListResult>;
-	}
-}