@nsnanocat/util 2.4.1 → 2.5.1

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.1"
 }

package/polyfill/fetch.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 统一请求参数。
+ * 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` adapter.
+ *
+ * @param resource 请求对象或 URL / Request object or URL string.
+ * @param options 追加参数 / Extra options.
+ * @returns 统一响应结构 / Normalized response payload.
+ */
+export function fetch(resource: FetchRequest | string, options?: Partial<FetchRequest>): Promise<FetchResponse>;

package/polyfill/fetch.mts

@@ -0,0 +1,48 @@
+import { fetch as fetchRuntime } from "./fetch.mjs";
+
+/**
+ * 统一请求参数。
+ * 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` adapter.
+ *
+ * @param resource 请求对象或 URL / Request object or URL string.
+ * @param options 追加参数 / Extra options.
+ * @returns 统一响应结构 / Normalized response payload.
+ */
+export const fetch: (resource: FetchRequest | string, options?: Partial<FetchRequest>) => Promise<FetchResponse> = fetchRuntime as (
+	resource: FetchRequest | string,
+	options?: Partial<FetchRequest>,
+) => Promise<FetchResponse>;

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/types/nsnanocat-util.d.ts

@@ -2,6 +2,5 @@
 /// <reference path="./modules/fetch.d.ts" />
 /// <reference path="./modules/polyfills.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>;
-	}
-}