@xxkatt/utils 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xxkatt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+<h1 align="center">@xxkatt/utils</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">把常用的小工具，放在一起。</p>
+<p align="center">轻量、类型齐全的 JavaScript / TypeScript 工具函数库</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@xxkatt/utils"><img src="https://img.shields.io/npm/v/@xxkatt/utils?color=a1b858&amp;label=version" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@xxkatt/utils"><img src="https://img.shields.io/npm/dm/@xxkatt/utils?color=50a36f&amp;label=downloads" alt="npm downloads" /></a>
+  <a href="https://github.com/xxkatt/xxkatt-utils/blob/master/packages/js/utils/LICENSE"><img src="https://img.shields.io/npm/l/@xxkatt/utils?color=3178c6" alt="MIT license" /></a>
+</p>
+
+## 👀 文档
+
+[查看文档](https://xxkatt.github.io/xxkatt-utils/) · [源码仓库](https://github.com/xxkatt/xxkatt-utils) · [问题反馈](https://github.com/xxkatt/xxkatt-utils/issues)
+
+## 🚀 特性
+
+- 🦾 **类型齐全**：使用 TypeScript 编写，提供类型声明与参数提示。
+- 💫 **零依赖**：无运行时依赖，只安装工具库本身。
+- ⚡️ **按需打包**：提供 ESM 导出，支持 Tree-shaking。
+- 🌎 **框架无关**：支持 Node.js 24+ 和现代浏览器，可搭配不同的前端框架使用。
+
+## 📦 安装
+
+```sh
+# npm
+npm install @xxkatt/utils
+
+# pnpm
+pnpm add @xxkatt/utils
+
+# yarn
+yarn add @xxkatt/utils
+```
+
+## 许可证
+
+[MIT © 2026 xxkatt](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 生成 UUID v4，默认返回 32 个小写十六进制字符。
+ *
+ * @param prefix 原样拼接在 UUID 前的前缀，分隔符需自行提供。
+ * @param hyphens 是否保留标准 UUID 中的横杠，默认 false。
+ * @example
+ * uuid()
+ * uuid('', true)
+ * uuid('user_')
+ * uuid('user_', true)
+ */
+export declare function uuid(prefix?: string, hyphens?: boolean): string;
+/**
+ * 使用加密安全随机数生成 ID；自定义长度的 ID 不遵循 UUID 格式。
+ * 字符表依次为 0–9、a–z、A–Z，使用前 radix 个字符。
+ *
+ * @param length 字符数量，必须为非负安全整数，默认 32；0 返回空字符串。
+ * @param radix 基数，必须为 2–62 的整数，默认 16。
+ * @example
+ * randomId(8, 10)
+ * randomId(21, 62)
+ */
+export declare function randomId(length?: number, radix?: number): string;
+/**
+ * 在浏览器中下载 URL、完整 Data URL 或 Blob/File。
+ *
+ * @param source 文件地址或文件内容；字符串始终作为地址处理。
+ * @param filename 建议保存的完整文件名，包含扩展名。
+ * @returns 触发下载后完成，不代表文件已保存到磁盘。
+ * @example
+ * await download('/files/report.pdf', 'report.pdf')
+ * await download(new Blob(['hello'], { type: 'text/plain' }), 'hello.txt')
+ */
+export declare function download(source: string | Blob, filename: string): Promise<void>;
+export interface DebouncedFunction<This, Args extends unknown[]> {
+  (this: This, ...args: Args): void;
+  cancel(): void;
+}
+/**
+ * 防抖：停止调用 wait 毫秒后，使用最后一次调用的 this 和参数执行回调。
+ *
+ * @param fn 要延迟执行的回调。
+ * @param wait 等待时间，单位毫秒，遵循原生 setTimeout 的时间规则。
+ * @returns 带有 cancel() 方法的防抖函数；cancel() 取消尚未执行的回调。
+ * @example
+ * const search = debounce((keyword: string) => console.log(keyword), 300)
+ * search('hello')
+ * search.cancel()
+ */
+export declare function debounce<This, Args extends unknown[]>(fn: (this: This, ...args: Args) => unknown, wait: number): DebouncedFunction<This, Args>;
+export interface ThrottledFunction<This, Args extends unknown[]> {
+  (this: This, ...args: Args): void;
+  cancel(): void;
+}
+/**
+ * 节流：首次调用立即执行，间隔内的调用在 wait 毫秒后以最后一次的 this 和参数执行。
+ * 持续调用时，每隔 wait 毫秒执行一次；仅调用一次时不会重复执行。
+ *
+ * @param fn 要限制执行频率的回调。
+ * @param wait 执行间隔，单位毫秒，遵循原生 setTimeout 的时间规则。
+ * @returns 带有 cancel() 方法的节流函数；cancel() 取消待执行回调并重置间隔。
+ * @example
+ * const update = throttle((position: number) => console.log(position), 100)
+ * update(10)
+ * update.cancel()
+ */
+export declare function throttle<This, Args extends unknown[]>(fn: (this: This, ...args: Args) => unknown, wait: number): ThrottledFunction<This, Args>;
+/** 按 Object.prototype.toString 的标签判断类型，如 'Date'、'Map'；区分大小写。 */
+export declare function is(value: unknown, type: string): boolean;
+/** 仅判断原始字符串，不包含 String 包装对象。 */
+export declare function isString(value: unknown): value is string;
+/** 判断原始 number，包含 NaN 和 Infinity，不进行数值有效性检查。 */
+export declare function isNumber(value: unknown): value is number;
+/** 仅判断原始布尔值。 */
+export declare function isBoolean(value: unknown): value is boolean;
+export declare function isBigInt(value: unknown): value is bigint;
+export declare function isSymbol(value: unknown): value is symbol;
+export declare function isUndefined(value: unknown): value is undefined;
+/** 排除 undefined，保留 null。 */
+export declare function isDefined<T>(value: T): value is Exclude<T, undefined>;
+export declare function isNull(value: unknown): value is null;
+/** 判断 null 或 undefined。 */
+export declare function isNil(value: unknown): value is null | undefined;
+/** 判断非 null 的对象，包含数组、内置对象和类实例，不包含函数。 */
+export declare function isObject(value: unknown): value is object;
+/** 判断普通对象，支持对象字面量、跨 realm 对象和 Object.create(null)。 */
+export declare function isPlainObject(value: unknown): value is Record<PropertyKey, unknown>;
+/** 判断 Date 类型，包含 Invalid Date。 */
+export declare function isDate(value: unknown): value is Date;
+export declare function isRegExp(value: unknown): value is RegExp;
+/** 包含普通函数、异步函数和生成器函数；不检查参数或返回值类型。 */
+export declare function isFunction(value: unknown): value is (...args: never[]) => unknown;
+/** 仅判断数组，不检查元素类型。 */
+export declare function isArray(value: unknown): value is unknown[];
+export declare function isMap(value: unknown): value is Map<unknown, unknown>;
+export declare function isSet(value: unknown): value is Set<unknown>;
+/** 判断 Promise 或具有可调用 then 方法的对象/函数，收窄为 PromiseLike。 */
+export declare function isPromise(value: unknown): value is PromiseLike<unknown>;
+/** 判断可被 JSON.parse 解析的字符串，包含 JSON 原始值。 */
+export declare function isJSON(value: unknown): boolean;
+/** 判断空字符串、数组、Map、Set 或无自有可枚举属性的普通对象。 */
+export declare function isEmpty(value: unknown): boolean;
+/** 在 isEmpty 的基础上，将 null、undefined 也视为空。 */
+export declare function isAllEmpty(value: unknown): boolean;
+/** 判断绝对 HTTP(S) URL，拒绝空白字符、反斜杠和相对地址。 */
+export declare function isUrl(value: unknown): boolean;
+/** 常用邮箱格式校验，不验证邮箱是否存在，不覆盖完整 RFC 邮箱语法。 */
+export declare function isEmail(value: unknown): boolean;
+/** 中国大陆 11 位手机号格式：以 1 开头，第二位为 3–9；不验证号段分配或号码存在性。 */
+export declare function isPhone(value: unknown): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,270 @@
+// src/uuid/index.ts
+const ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+/**
+* 生成 UUID v4，默认返回 32 个小写十六进制字符。
+*
+* @param prefix 原样拼接在 UUID 前的前缀，分隔符需自行提供。
+* @param hyphens 是否保留标准 UUID 中的横杠，默认 false。
+* @example
+* uuid()
+* uuid('', true)
+* uuid('user_')
+* uuid('user_', true)
+*/
+function uuid(prefix = "", hyphens = false) {
+	const crypto = globalThis.crypto;
+	let value;
+	if (typeof crypto?.randomUUID === "function") value = crypto.randomUUID();
+	else {
+		if (typeof crypto?.getRandomValues !== "function") throw new Error("uuid requires crypto.randomUUID or crypto.getRandomValues");
+		const bytes = /* @__PURE__ */ new Uint8Array(16);
+		crypto.getRandomValues(bytes);
+		bytes[6] = bytes[6] & 15 | 64;
+		bytes[8] = bytes[8] & 63 | 128;
+		const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+		value = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+	}
+	return prefix + (hyphens ? value : value.replace(/-/g, ""));
+}
+/**
+* 使用加密安全随机数生成 ID；自定义长度的 ID 不遵循 UUID 格式。
+* 字符表依次为 0–9、a–z、A–Z，使用前 radix 个字符。
+*
+* @param length 字符数量，必须为非负安全整数，默认 32；0 返回空字符串。
+* @param radix 基数，必须为 2–62 的整数，默认 16。
+* @example
+* randomId(8, 10)
+* randomId(21, 62)
+*/
+function randomId(length = 32, radix = 16) {
+	if (!Number.isSafeInteger(length) || length < 0) throw new RangeError("length must be a non-negative safe integer");
+	if (!Number.isInteger(radix) || radix < 2 || radix > 62) throw new RangeError("radix must be an integer between 2 and 62");
+	if (length === 0) return "";
+	const bytes = new Uint8Array(Math.min(length, 65536));
+	const limit = 256 - 256 % radix;
+	let value = "";
+	while (value.length < length) {
+		globalThis.crypto.getRandomValues(bytes);
+		for (const byte of bytes) {
+			if (byte >= limit) continue;
+			value += ALPHABET.charAt(byte % radix);
+			if (value.length === length) break;
+		}
+	}
+	return value;
+}
+// src/download/index.ts
+/**
+* 在浏览器中下载 URL、完整 Data URL 或 Blob/File。
+*
+* @param source 文件地址或文件内容；字符串始终作为地址处理。
+* @param filename 建议保存的完整文件名，包含扩展名。
+* @returns 触发下载后完成，不代表文件已保存到磁盘。
+* @example
+* await download('/files/report.pdf', 'report.pdf')
+* await download(new Blob(['hello'], { type: 'text/plain' }), 'hello.txt')
+*/
+async function download(source, filename) {
+	if (typeof document === "undefined" || !document.body) throw new Error("download requires a browser environment");
+	let blob;
+	if (typeof source === "string") {
+		const response = await fetch(source);
+		if (!response.ok) throw new Error(`Download failed: HTTP ${response.status}`);
+		blob = await response.blob();
+	} else blob = source;
+	const anchor = document.createElement("a");
+	const url = URL.createObjectURL(blob);
+	try {
+		anchor.href = url;
+		anchor.download = filename;
+		anchor.hidden = true;
+		document.body.append(anchor);
+		anchor.click();
+	} finally {
+		anchor.remove();
+		setTimeout(() => URL.revokeObjectURL(url), 1e3);
+	}
+}
+// src/debounce/index.ts
+/**
+* 防抖：停止调用 wait 毫秒后，使用最后一次调用的 this 和参数执行回调。
+*
+* @param fn 要延迟执行的回调。
+* @param wait 等待时间，单位毫秒，遵循原生 setTimeout 的时间规则。
+* @returns 带有 cancel() 方法的防抖函数；cancel() 取消尚未执行的回调。
+* @example
+* const search = debounce((keyword: string) => console.log(keyword), 300)
+* search('hello')
+* search.cancel()
+*/
+function debounce(fn, wait) {
+	let timer;
+	function debounced(...args) {
+		if (timer !== void 0) clearTimeout(timer);
+		timer = setTimeout(() => {
+			timer = void 0;
+			fn.apply(this, args);
+		}, wait);
+	}
+	debounced.cancel = () => {
+		if (timer !== void 0) clearTimeout(timer);
+		timer = void 0;
+	};
+	return debounced;
+}
+// src/throttle/index.ts
+/**
+* 节流：首次调用立即执行，间隔内的调用在 wait 毫秒后以最后一次的 this 和参数执行。
+* 持续调用时，每隔 wait 毫秒执行一次；仅调用一次时不会重复执行。
+*
+* @param fn 要限制执行频率的回调。
+* @param wait 执行间隔，单位毫秒，遵循原生 setTimeout 的时间规则。
+* @returns 带有 cancel() 方法的节流函数；cancel() 取消待执行回调并重置间隔。
+* @example
+* const update = throttle((position: number) => console.log(position), 100)
+* update(10)
+* update.cancel()
+*/
+function throttle(fn, wait) {
+	let timer;
+	let pending;
+	function onTimeout() {
+		timer = void 0;
+		if (!pending) return;
+		const { thisArg, args } = pending;
+		pending = void 0;
+		timer = setTimeout(onTimeout, wait);
+		fn.apply(thisArg, args);
+	}
+	function throttled(...args) {
+		if (timer === void 0) {
+			timer = setTimeout(onTimeout, wait);
+			fn.apply(this, args);
+		} else pending = {
+			thisArg: this,
+			args
+		};
+	}
+	throttled.cancel = () => {
+		if (timer !== void 0) clearTimeout(timer);
+		timer = void 0;
+		pending = void 0;
+	};
+	return throttled;
+}
+// src/is/index.ts
+/** 按 Object.prototype.toString 的标签判断类型，如 'Date'、'Map'；区分大小写。 */
+function is(value, type) {
+	return Object.prototype.toString.call(value) === `[object ${type}]`;
+}
+/** 仅判断原始字符串，不包含 String 包装对象。 */
+function isString(value) {
+	return typeof value === "string";
+}
+/** 判断原始 number，包含 NaN 和 Infinity，不进行数值有效性检查。 */
+function isNumber(value) {
+	return typeof value === "number";
+}
+/** 仅判断原始布尔值。 */
+function isBoolean(value) {
+	return typeof value === "boolean";
+}
+function isBigInt(value) {
+	return typeof value === "bigint";
+}
+function isSymbol(value) {
+	return typeof value === "symbol";
+}
+function isUndefined(value) {
+	return value === void 0;
+}
+/** 排除 undefined，保留 null。 */
+function isDefined(value) {
+	return value !== void 0;
+}
+function isNull(value) {
+	return value === null;
+}
+/** 判断 null 或 undefined。 */
+function isNil(value) {
+	return value === null || value === void 0;
+}
+/** 判断非 null 的对象，包含数组、内置对象和类实例，不包含函数。 */
+function isObject(value) {
+	return value !== null && typeof value === "object";
+}
+/** 判断普通对象，支持对象字面量、跨 realm 对象和 Object.create(null)。 */
+function isPlainObject(value) {
+	if (!is(value, "Object")) return false;
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype === null) return true;
+	const constructor = Object.hasOwn(prototype, "constructor") && prototype.constructor;
+	return typeof constructor === "function" && Function.prototype.toString.call(constructor) === Function.prototype.toString.call(Object);
+}
+/** 判断 Date 类型，包含 Invalid Date。 */
+function isDate(value) {
+	return is(value, "Date");
+}
+function isRegExp(value) {
+	return is(value, "RegExp");
+}
+/** 包含普通函数、异步函数和生成器函数；不检查参数或返回值类型。 */
+function isFunction(value) {
+	return typeof value === "function";
+}
+/** 仅判断数组，不检查元素类型。 */
+function isArray(value) {
+	return Array.isArray(value);
+}
+function isMap(value) {
+	return is(value, "Map");
+}
+function isSet(value) {
+	return is(value, "Set");
+}
+/** 判断 Promise 或具有可调用 then 方法的对象/函数，收窄为 PromiseLike。 */
+function isPromise(value) {
+	return (isObject(value) || isFunction(value)) && "then" in value && isFunction(value.then);
+}
+/** 判断可被 JSON.parse 解析的字符串，包含 JSON 原始值。 */
+function isJSON(value) {
+	if (!isString(value)) return false;
+	try {
+		JSON.parse(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** 判断空字符串、数组、Map、Set 或无自有可枚举属性的普通对象。 */
+function isEmpty(value) {
+	if (isString(value) || isArray(value)) return value.length === 0;
+	if (isMap(value) || isSet(value)) return value.size === 0;
+	if (isPlainObject(value)) return !Reflect.ownKeys(value).some((key) => Object.prototype.propertyIsEnumerable.call(value, key));
+	return false;
+}
+/** 在 isEmpty 的基础上，将 null、undefined 也视为空。 */
+function isAllEmpty(value) {
+	return isNil(value) || isEmpty(value);
+}
+/** 判断绝对 HTTP(S) URL，拒绝空白字符、反斜杠和相对地址。 */
+function isUrl(value) {
+	if (!isString(value) || !/^https?:\/\//i.test(value) || /[\s\\]/.test(value)) return false;
+	try {
+		const url = new URL(value);
+		return (url.protocol === "http:" || url.protocol === "https:") && url.hostname !== "";
+	} catch {
+		return false;
+	}
+}
+/** 常用邮箱格式校验，不验证邮箱是否存在，不覆盖完整 RFC 邮箱语法。 */
+function isEmail(value) {
+	return isString(value) && /^[a-z\d!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z\d!#$%&'*+/=?^_`{|}~-]+)*@(?:[a-z\d](?:[a-z\d-]*[a-z\d])?\.)+[a-z]{2,}$/i.test(value);
+}
+/** 中国大陆 11 位手机号格式：以 1 开头，第二位为 3–9；不验证号段分配或号码存在性。 */
+function isPhone(value) {
+	return isString(value) && /^1[3-9]\d{9}$/.test(value);
+}
+export { debounce, download, is, isAllEmpty, isArray, isBigInt, isBoolean, isDate, isDefined, isEmail, isEmpty, isFunction, isJSON, isMap, isNil, isNull, isNumber, isObject, isPhone, isPlainObject, isPromise, isRegExp, isSet, isString, isSymbol, isUndefined, isUrl, randomId, throttle, uuid };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/uuid/index.ts","../src/download/index.ts","../src/debounce/index.ts","../src/throttle/index.ts","../src/is/index.ts"],"sourcesContent":["const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'\n\n/**\n * 生成 UUID v4，默认返回 32 个小写十六进制字符。\n *\n * @param prefix 原样拼接在 UUID 前的前缀，分隔符需自行提供。\n * @param hyphens 是否保留标准 UUID 中的横杠，默认 false。\n * @example\n * uuid()\n * uuid('', true)\n * uuid('user_')\n * uuid('user_', true)\n */\nexport function uuid(prefix: string = '', hyphens: boolean = false): string {\n  const crypto = globalThis.crypto\n  let value: string\n\n  if (typeof crypto?.randomUUID === 'function') {\n    value = crypto.randomUUID()\n  } else {\n    if (typeof crypto?.getRandomValues !== 'function') {\n      throw new Error('uuid requires crypto.randomUUID or crypto.getRandomValues')\n    }\n\n    const bytes = new Uint8Array(16)\n    crypto.getRandomValues(bytes)\n    // 设置 UUID v4 的版本位和 RFC 变体位，保留其余随机位。\n    bytes[6] = (bytes[6]! & 0x0f) | 0x40\n    bytes[8] = (bytes[8]! & 0x3f) | 0x80\n    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('')\n    value = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`\n  }\n\n  return prefix + (hyphens ? value : value.replace(/-/g, ''))\n}\n\n/**\n * 使用加密安全随机数生成 ID；自定义长度的 ID 不遵循 UUID 格式。\n * 字符表依次为 0–9、a–z、A–Z，使用前 radix 个字符。\n *\n * @param length 字符数量，必须为非负安全整数，默认 32；0 返回空字符串。\n * @param radix 基数，必须为 2–62 的整数，默认 16。\n * @example\n * randomId(8, 10)\n * randomId(21, 62)\n */\nexport function randomId(length: number = 32, radix: number = 16): string {\n  if (!Number.isSafeInteger(length) || length < 0) {\n    throw new RangeError('length must be a non-negative safe integer')\n  }\n  if (!Number.isInteger(radix) || radix < 2 || radix > ALPHABET.length) {\n    throw new RangeError('radix must be an integer between 2 and 62')\n  }\n  if (length === 0) return ''\n\n  const bytes = new Uint8Array(Math.min(length, 65_536))\n  const limit = 256 - (256 % radix)\n  let value = ''\n\n  while (value.length < length) {\n    globalThis.crypto.getRandomValues(bytes)\n    for (const byte of bytes) {\n      // 丢弃无法均分到字符表的尾部区间，避免取模导致分布偏差。\n      if (byte >= limit) continue\n      value += ALPHABET.charAt(byte % radix)\n      if (value.length === length) break\n    }\n  }\n\n  return value\n}\n","/**\n * 在浏览器中下载 URL、完整 Data URL 或 Blob/File。\n *\n * @param source 文件地址或文件内容；字符串始终作为地址处理。\n * @param filename 建议保存的完整文件名，包含扩展名。\n * @returns 触发下载后完成，不代表文件已保存到磁盘。\n * @example\n * await download('/files/report.pdf', 'report.pdf')\n * await download(new Blob(['hello'], { type: 'text/plain' }), 'hello.txt')\n */\nexport async function download(source: string | Blob, filename: string): Promise<void> {\n  if (typeof document === 'undefined' || !document.body) {\n    throw new Error('download requires a browser environment')\n  }\n\n  let blob: Blob\n  if (typeof source === 'string') {\n    const response = await fetch(source)\n    if (!response.ok) {\n      throw new Error(`Download failed: HTTP ${response.status}`)\n    }\n    blob = await response.blob()\n  } else {\n    blob = source\n  }\n\n  const anchor = document.createElement('a')\n  const url = URL.createObjectURL(blob)\n  try {\n    anchor.href = url\n    anchor.download = filename\n    anchor.hidden = true\n    document.body.append(anchor)\n    anchor.click()\n  } finally {\n    anchor.remove()\n    // 留出浏览器开始读取文件的时间，避免同步释放导致下载失败。\n    setTimeout(() => URL.revokeObjectURL(url), 1000)\n  }\n}\n","export interface DebouncedFunction<This, Args extends unknown[]> {\n  (this: This, ...args: Args): void\n  cancel(): void\n}\n\n/**\n * 防抖：停止调用 wait 毫秒后，使用最后一次调用的 this 和参数执行回调。\n *\n * @param fn 要延迟执行的回调。\n * @param wait 等待时间，单位毫秒，遵循原生 setTimeout 的时间规则。\n * @returns 带有 cancel() 方法的防抖函数；cancel() 取消尚未执行的回调。\n * @example\n * const search = debounce((keyword: string) => console.log(keyword), 300)\n * search('hello')\n * search.cancel()\n */\nexport function debounce<This, Args extends unknown[]>(\n  fn: (this: This, ...args: Args) => unknown,\n  wait: number,\n): DebouncedFunction<This, Args> {\n  let timer: ReturnType<typeof setTimeout> | undefined\n\n  function debounced(this: This, ...args: Args): void {\n    if (timer !== undefined) clearTimeout(timer)\n    timer = setTimeout(() => {\n      timer = undefined\n      fn.apply(this, args)\n    }, wait)\n  }\n\n  debounced.cancel = (): void => {\n    if (timer !== undefined) clearTimeout(timer)\n    timer = undefined\n  }\n\n  return debounced\n}\n","export interface ThrottledFunction<This, Args extends unknown[]> {\n  (this: This, ...args: Args): void\n  cancel(): void\n}\n\n/**\n * 节流：首次调用立即执行，间隔内的调用在 wait 毫秒后以最后一次的 this 和参数执行。\n * 持续调用时，每隔 wait 毫秒执行一次；仅调用一次时不会重复执行。\n *\n * @param fn 要限制执行频率的回调。\n * @param wait 执行间隔，单位毫秒，遵循原生 setTimeout 的时间规则。\n * @returns 带有 cancel() 方法的节流函数；cancel() 取消待执行回调并重置间隔。\n * @example\n * const update = throttle((position: number) => console.log(position), 100)\n * update(10)\n * update.cancel()\n */\nexport function throttle<This, Args extends unknown[]>(\n  fn: (this: This, ...args: Args) => unknown,\n  wait: number,\n): ThrottledFunction<This, Args> {\n  let timer: ReturnType<typeof setTimeout> | undefined\n  let pending: { thisArg: This; args: Args } | undefined\n\n  function onTimeout(): void {\n    timer = undefined\n    if (!pending) return\n\n    const { thisArg, args } = pending\n    pending = undefined\n    // 在执行用户回调前建立下一轮间隔，支持回调内再次调用或取消。\n    timer = setTimeout(onTimeout, wait)\n    fn.apply(thisArg, args)\n  }\n\n  function throttled(this: This, ...args: Args): void {\n    if (timer === undefined) {\n      timer = setTimeout(onTimeout, wait)\n      fn.apply(this, args)\n    } else {\n      pending = { thisArg: this, args }\n    }\n  }\n\n  throttled.cancel = (): void => {\n    if (timer !== undefined) clearTimeout(timer)\n    timer = undefined\n    pending = undefined\n  }\n\n  return throttled\n}\n","/** 按 Object.prototype.toString 的标签判断类型，如 'Date'、'Map'；区分大小写。 */\nexport function is(value: unknown, type: string): boolean {\n  return Object.prototype.toString.call(value) === `[object ${type}]`\n}\n\n/** 仅判断原始字符串，不包含 String 包装对象。 */\nexport function isString(value: unknown): value is string {\n  return typeof value === 'string'\n}\n\n/** 判断原始 number，包含 NaN 和 Infinity，不进行数值有效性检查。 */\nexport function isNumber(value: unknown): value is number {\n  return typeof value === 'number'\n}\n\n/** 仅判断原始布尔值。 */\nexport function isBoolean(value: unknown): value is boolean {\n  return typeof value === 'boolean'\n}\n\nexport function isBigInt(value: unknown): value is bigint {\n  return typeof value === 'bigint'\n}\n\nexport function isSymbol(value: unknown): value is symbol {\n  return typeof value === 'symbol'\n}\n\nexport function isUndefined(value: unknown): value is undefined {\n  return value === undefined\n}\n\n/** 排除 undefined，保留 null。 */\nexport function isDefined<T>(value: T): value is Exclude<T, undefined> {\n  return value !== undefined\n}\n\nexport function isNull(value: unknown): value is null {\n  return value === null\n}\n\n/** 判断 null 或 undefined。 */\nexport function isNil(value: unknown): value is null | undefined {\n  return value === null || value === undefined\n}\n\n/** 判断非 null 的对象，包含数组、内置对象和类实例，不包含函数。 */\nexport function isObject(value: unknown): value is object {\n  return value !== null && typeof value === 'object'\n}\n\n/** 判断普通对象，支持对象字面量、跨 realm 对象和 Object.create(null)。 */\nexport function isPlainObject(value: unknown): value is Record<PropertyKey, unknown> {\n  if (!is(value, 'Object')) return false\n  const prototype = Object.getPrototypeOf(value)\n  if (prototype === null) return true\n  const constructor = Object.hasOwn(prototype, 'constructor') && prototype.constructor\n  return (\n    typeof constructor === 'function' &&\n    Function.prototype.toString.call(constructor) === Function.prototype.toString.call(Object)\n  )\n}\n\n/** 判断 Date 类型，包含 Invalid Date。 */\nexport function isDate(value: unknown): value is Date {\n  return is(value, 'Date')\n}\n\nexport function isRegExp(value: unknown): value is RegExp {\n  return is(value, 'RegExp')\n}\n\n/** 包含普通函数、异步函数和生成器函数；不检查参数或返回值类型。 */\nexport function isFunction(value: unknown): value is (...args: never[]) => unknown {\n  return typeof value === 'function'\n}\n\n/** 仅判断数组，不检查元素类型。 */\nexport function isArray(value: unknown): value is unknown[] {\n  return Array.isArray(value)\n}\n\nexport function isMap(value: unknown): value is Map<unknown, unknown> {\n  return is(value, 'Map')\n}\n\nexport function isSet(value: unknown): value is Set<unknown> {\n  return is(value, 'Set')\n}\n\n/** 判断 Promise 或具有可调用 then 方法的对象/函数，收窄为 PromiseLike。 */\nexport function isPromise(value: unknown): value is PromiseLike<unknown> {\n  return (isObject(value) || isFunction(value)) && 'then' in value && isFunction(value.then)\n}\n\n/** 判断可被 JSON.parse 解析的字符串，包含 JSON 原始值。 */\nexport function isJSON(value: unknown): boolean {\n  if (!isString(value)) return false\n  try {\n    JSON.parse(value)\n    return true\n  } catch {\n    return false\n  }\n}\n\n/** 判断空字符串、数组、Map、Set 或无自有可枚举属性的普通对象。 */\nexport function isEmpty(value: unknown): boolean {\n  if (isString(value) || isArray(value)) return value.length === 0\n  if (isMap(value) || isSet(value)) return value.size === 0\n  if (isPlainObject(value)) {\n    return !Reflect.ownKeys(value).some((key) =>\n      Object.prototype.propertyIsEnumerable.call(value, key),\n    )\n  }\n  return false\n}\n\n/** 在 isEmpty 的基础上，将 null、undefined 也视为空。 */\nexport function isAllEmpty(value: unknown): boolean {\n  return isNil(value) || isEmpty(value)\n}\n\n/** 判断绝对 HTTP(S) URL，拒绝空白字符、反斜杠和相对地址。 */\nexport function isUrl(value: unknown): boolean {\n  if (!isString(value) || !/^https?:\\/\\//i.test(value) || /[\\s\\\\]/.test(value)) return false\n  try {\n    const url = new URL(value)\n    return (url.protocol === 'http:' || url.protocol === 'https:') && url.hostname !== ''\n  } catch {\n    return false\n  }\n}\n\n/** 常用邮箱格式校验，不验证邮箱是否存在，不覆盖完整 RFC 邮箱语法。 */\nexport function isEmail(value: unknown): boolean {\n  return (\n    isString(value) &&\n    /^[a-z\\d!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-z\\d!#$%&'*+/=?^_`{|}~-]+)*@(?:[a-z\\d](?:[a-z\\d-]*[a-z\\d])?\\.)+[a-z]{2,}$/i.test(\n      value,\n    )\n  )\n}\n\n/** 中国大陆 11 位手机号格式：以 1 开头，第二位为 3–9；不验证号段分配或号码存在性。 */\nexport function isPhone(value: unknown): boolean {\n  return isString(value) && /^1[3-9]\\d{9}$/.test(value)\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@xxkatt/utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2",
+  "description": "常用的 JavaScript / TypeScript 工具函数",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xxkatt/xxkatt-utils.git",
+    "directory": "packages/js/utils"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\""
+  }
 }