@nsnanocat/util 2.5.1 → 2.5.3

package/package.json

@@ -15,7 +15,6 @@
   "bugs": "https://github.com/NSNanoCat/util/issues",
   "main": "index.js",
   "types": "types/nsnanocat-util.d.ts",
-  "type": "module",
   "scripts": {
     "tsc:build": "npx tsc",
     "test": "node --test test/*.test.js",
@@ -42,5 +41,5 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "2.5.1"
+  "version": "2.5.3"
 }

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

@@ -33,11 +33,13 @@ export interface FetchResponse {
 }
 
 /**
- * 跨平台 `fetch` 适配层。
- * Cross-platform `fetch` adapter.
+ * 跨平台 `fetch` 函数签名。
+ * Cross-platform `fetch` function signature.
  *
  * @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>;
+export type Fetch = (resource: FetchRequest | string, options?: Partial<FetchRequest>) => Promise<FetchResponse>;
+
+export const fetch: Fetch;

package/polyfill/fetch.mts

@@ -1,48 +1,6 @@
 import { fetch as fetchRuntime } from "./fetch.mjs";
+import type { Fetch } from "./fetch.d.ts";
 
-/**
- * 统一请求参数。
- * 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;
-}
+export type { Fetch, FetchRequest, FetchResponse } from "./fetch.d.ts";
 
-/**
- * 统一响应结构。
- * 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>;
+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/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,6 +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/getStorage.d.ts" />
 /// <reference path="./modules/environment.d.ts" />