@tanwan/utils 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# @tanwan/utils
+
+## 1.2.0
+
+### Minor Changes
+
+- 扁平化导出路径：简化 import 路径从 `@tanwan/utils/array/chunk` 到 `@tanwan/utils/chunk`。
+
+## 1.1.0
+
+### Minor Changes
+
+- 新增 9 个实用工具函数：isEmpty (base), pick/omit (object), range/groupBy (array), uuid (string), delay (function), parseQueryString/stringifyQueryString (url)
+
+## 1.0.0
+
+### Major Changes
+
+- 初始化第一波版本

package/dist/addClass.cjs

@@ -0,0 +1,19 @@
+//#region src/dom/addClass/index.ts
+/**
+* 给元素添加 CSS class
+*
+* @param el - DOM 元素
+* @param className - 要添加的 class（支持空格分隔多个）
+*
+* @example
+* ```ts
+* import addClass from '@tanwan/utils/addClass'
+* addClass(el, 'active')
+* addClass(el, 'foo bar')
+* ```
+*/
+function addClass(el, className) {
+	el.classList.add(...className.split(/\s+/).filter(Boolean));
+}
+//#endregion
+module.exports = addClass;

package/dist/addClass.d.cts

@@ -0,0 +1,16 @@
+//#region src/dom/addClass/index.d.ts
+/**
+* 给元素添加 CSS class
+*
+* @param el - DOM 元素
+* @param className - 要添加的 class（支持空格分隔多个）
+*
+* @example
+* ```ts
+* import addClass from '@tanwan/utils/addClass'
+* addClass(el, 'active')
+* addClass(el, 'foo bar')
+* ```
+*/
+declare function addClass(el: Element, className: string): void;
+export = addClass;

package/dist/addClass.d.ts

@@ -0,0 +1,17 @@
+//#region src/dom/addClass/index.d.ts
+/**
+* 给元素添加 CSS class
+*
+* @param el - DOM 元素
+* @param className - 要添加的 class（支持空格分隔多个）
+*
+* @example
+* ```ts
+* import addClass from '@tanwan/utils/addClass'
+* addClass(el, 'active')
+* addClass(el, 'foo bar')
+* ```
+*/
+declare function addClass(el: Element, className: string): void;
+//#endregion
+export { addClass as default };

package/dist/addClass.js

@@ -0,0 +1,19 @@
+//#region src/dom/addClass/index.ts
+/**
+* 给元素添加 CSS class
+*
+* @param el - DOM 元素
+* @param className - 要添加的 class（支持空格分隔多个）
+*
+* @example
+* ```ts
+* import addClass from '@tanwan/utils/addClass'
+* addClass(el, 'active')
+* addClass(el, 'foo bar')
+* ```
+*/
+function addClass(el, className) {
+	el.classList.add(...className.split(/\s+/).filter(Boolean));
+}
+//#endregion
+export { addClass as default };

package/dist/{string/camelCase.d.cts → camelCase.d.cts}

@@ -3,5 +3,4 @@
 * 将字符串转换为驼峰命名
 */
 declare function camelCase(str: string, capital?: boolean): string;
-export = camelCase;
-//# sourceMappingURL=camelCase.d.cts.map
+export = camelCase;

package/dist/{string/camelCase.d.ts → camelCase.d.ts}

@@ -4,5 +4,4 @@
 */
 declare function camelCase(str: string, capital?: boolean): string;
 //#endregion
-export { camelCase as default };
-//# sourceMappingURL=camelCase.d.ts.map
+export { camelCase as default };

package/dist/{string/camelCase.js → camelCase.js}

@@ -9,5 +9,3 @@ function camelCase(str, capital = false) {
 }
 //#endregion
 export { camelCase as default };
-
-//# sourceMappingURL=camelCase.js.map

package/dist/{string/capitalize.d.cts → capitalize.d.cts}

@@ -9,5 +9,4 @@
 * ```
 */
 declare function capitalize(str: string): string;
-export = capitalize;
-//# sourceMappingURL=capitalize.d.cts.map
+export = capitalize;

package/dist/{string/capitalize.d.ts → capitalize.d.ts}

@@ -10,5 +10,4 @@
 */
 declare function capitalize(str: string): string;
 //#endregion
-export { capitalize as default };
-//# sourceMappingURL=capitalize.d.ts.map
+export { capitalize as default };

package/dist/{string/capitalize.js → capitalize.js}

@@ -14,5 +14,3 @@ function capitalize(str) {
 }
 //#endregion
 export { capitalize as default };
-
-//# sourceMappingURL=capitalize.js.map

package/dist/{array/chunk.d.cts → chunk.d.cts}

@@ -9,5 +9,4 @@
 * ```
 */
 declare function chunk<T>(arr: T[], size: number): T[][];
-export = chunk;
-//# sourceMappingURL=chunk.d.cts.map
+export = chunk;

package/dist/{array/chunk.d.ts → chunk.d.ts}

@@ -10,5 +10,4 @@
 */
 declare function chunk<T>(arr: T[], size: number): T[][];
 //#endregion
-export { chunk as default };
-//# sourceMappingURL=chunk.d.ts.map
+export { chunk as default };

package/dist/{array/chunk.js → chunk.js}

@@ -15,5 +15,3 @@ function chunk(arr, size) {
 }
 //#endregion
 export { chunk as default };
-
-//# sourceMappingURL=chunk.js.map

package/dist/{number/clamp.d.cts → clamp.d.cts}

@@ -10,5 +10,4 @@
 * ```
 */
 declare function clamp(value: number, min: number, max: number): number;
-export = clamp;
-//# sourceMappingURL=clamp.d.cts.map
+export = clamp;

package/dist/{number/clamp.d.ts → clamp.d.ts}

@@ -11,5 +11,4 @@
 */
 declare function clamp(value: number, min: number, max: number): number;
 //#endregion
-export { clamp as default };
-//# sourceMappingURL=clamp.d.ts.map
+export { clamp as default };

package/dist/{number/clamp.js → clamp.js}

@@ -14,5 +14,3 @@ function clamp(value, min, max) {
 }
 //#endregion
 export { clamp as default };
-
-//# sourceMappingURL=clamp.js.map

package/dist/convertCurrencyToChinese.cjs

@@ -0,0 +1,56 @@
+//#region src/business/convertCurrencyToChinese/index.ts
+/**
+* 金额转为中文大写
+*
+* @param amount - 金额数值
+* @returns 中文大写金额字符串
+*
+* @example
+* ```ts
+* import convertCurrencyToChinese from '@tanwan/utils/convertCurrencyToChinese'
+* convertCurrencyToChinese(1234.56)
+* // '壹仟贰佰叁拾肆元伍角陆分'
+* convertCurrencyToChinese(0)
+* // '零元整'
+* ```
+*/
+function convertCurrencyToChinese(amount) {
+	if (amount === 0) return "零元整";
+	const digits = "零壹贰叁肆伍陆柒捌玖";
+	const units = [
+		"",
+		"拾",
+		"佰",
+		"仟"
+	];
+	const bigUnits = [
+		"",
+		"万",
+		"亿"
+	];
+	const [intPart, decimalPart] = amount.toFixed(2).split(".");
+	const intLen = intPart.length;
+	let result = "";
+	for (let i = 0; i < intLen; i++) {
+		const digit = Number.parseInt(intPart[i]);
+		const pos = intLen - 1 - i;
+		const unitIdx = pos % 4;
+		const bigIdx = Math.floor(pos / 4);
+		if (digit !== 0) result += digits[digit] + units[unitIdx];
+		else if (i < intLen - 1 && intPart[i + 1] !== "0") result += digits[0];
+		if (unitIdx === 0 && bigIdx > 0) {
+			if (intPart.substring(i + 1).replace(/0+$/, "").length > 0) result += bigUnits[bigIdx];
+		}
+	}
+	result += "元";
+	const jiao = Number.parseInt(decimalPart[0]);
+	const fen = Number.parseInt(decimalPart[1]);
+	if (jiao === 0 && fen === 0) result += "整";
+	else {
+		if (jiao > 0) result += digits[jiao] + "角";
+		if (fen > 0) result += digits[fen] + "分";
+	}
+	return result;
+}
+//#endregion
+module.exports = convertCurrencyToChinese;

package/dist/convertCurrencyToChinese.d.cts

@@ -0,0 +1,18 @@
+//#region src/business/convertCurrencyToChinese/index.d.ts
+/**
+* 金额转为中文大写
+*
+* @param amount - 金额数值
+* @returns 中文大写金额字符串
+*
+* @example
+* ```ts
+* import convertCurrencyToChinese from '@tanwan/utils/convertCurrencyToChinese'
+* convertCurrencyToChinese(1234.56)
+* // '壹仟贰佰叁拾肆元伍角陆分'
+* convertCurrencyToChinese(0)
+* // '零元整'
+* ```
+*/
+declare function convertCurrencyToChinese(amount: number): string;
+export = convertCurrencyToChinese;

package/dist/convertCurrencyToChinese.d.ts

@@ -0,0 +1,19 @@
+//#region src/business/convertCurrencyToChinese/index.d.ts
+/**
+* 金额转为中文大写
+*
+* @param amount - 金额数值
+* @returns 中文大写金额字符串
+*
+* @example
+* ```ts
+* import convertCurrencyToChinese from '@tanwan/utils/convertCurrencyToChinese'
+* convertCurrencyToChinese(1234.56)
+* // '壹仟贰佰叁拾肆元伍角陆分'
+* convertCurrencyToChinese(0)
+* // '零元整'
+* ```
+*/
+declare function convertCurrencyToChinese(amount: number): string;
+//#endregion
+export { convertCurrencyToChinese as default };

package/dist/convertCurrencyToChinese.js

@@ -0,0 +1,56 @@
+//#region src/business/convertCurrencyToChinese/index.ts
+/**
+* 金额转为中文大写
+*
+* @param amount - 金额数值
+* @returns 中文大写金额字符串
+*
+* @example
+* ```ts
+* import convertCurrencyToChinese from '@tanwan/utils/convertCurrencyToChinese'
+* convertCurrencyToChinese(1234.56)
+* // '壹仟贰佰叁拾肆元伍角陆分'
+* convertCurrencyToChinese(0)
+* // '零元整'
+* ```
+*/
+function convertCurrencyToChinese(amount) {
+	if (amount === 0) return "零元整";
+	const digits = "零壹贰叁肆伍陆柒捌玖";
+	const units = [
+		"",
+		"拾",
+		"佰",
+		"仟"
+	];
+	const bigUnits = [
+		"",
+		"万",
+		"亿"
+	];
+	const [intPart, decimalPart] = amount.toFixed(2).split(".");
+	const intLen = intPart.length;
+	let result = "";
+	for (let i = 0; i < intLen; i++) {
+		const digit = Number.parseInt(intPart[i]);
+		const pos = intLen - 1 - i;
+		const unitIdx = pos % 4;
+		const bigIdx = Math.floor(pos / 4);
+		if (digit !== 0) result += digits[digit] + units[unitIdx];
+		else if (i < intLen - 1 && intPart[i + 1] !== "0") result += digits[0];
+		if (unitIdx === 0 && bigIdx > 0) {
+			if (intPart.substring(i + 1).replace(/0+$/, "").length > 0) result += bigUnits[bigIdx];
+		}
+	}
+	result += "元";
+	const jiao = Number.parseInt(decimalPart[0]);
+	const fen = Number.parseInt(decimalPart[1]);
+	if (jiao === 0 && fen === 0) result += "整";
+	else {
+		if (jiao > 0) result += digits[jiao] + "角";
+		if (fen > 0) result += digits[fen] + "分";
+	}
+	return result;
+}
+//#endregion
+export { convertCurrencyToChinese as default };

package/dist/copyToClipboard.cjs

@@ -0,0 +1,38 @@
+//#region src/business/copyToClipboard/index.ts
+/**
+* 复制文本到剪贴板
+*
+* 优先使用 `navigator.clipboard.writeText`，不支持时降级为 `document.execCommand`
+*
+* @param text - 要复制的文本
+* @returns 是否复制成功
+*
+* @example
+* ```ts
+* import copyToClipboard from '@tanwan/utils/copyToClipboard'
+* await copyToClipboard('Hello World')
+* ```
+*/
+async function copyToClipboard(text) {
+	try {
+		if (navigator.clipboard && typeof navigator.clipboard.writeText === "function") {
+			await navigator.clipboard.writeText(text);
+			return true;
+		}
+	} catch {}
+	const textarea = document.createElement("textarea");
+	textarea.value = text;
+	textarea.style.position = "fixed";
+	textarea.style.opacity = "0";
+	document.body.appendChild(textarea);
+	textarea.select();
+	try {
+		return document.execCommand("copy");
+	} catch {
+		return false;
+	} finally {
+		document.body.removeChild(textarea);
+	}
+}
+//#endregion
+module.exports = copyToClipboard;

package/dist/copyToClipboard.d.cts

@@ -0,0 +1,17 @@
+//#region src/business/copyToClipboard/index.d.ts
+/**
+* 复制文本到剪贴板
+*
+* 优先使用 `navigator.clipboard.writeText`，不支持时降级为 `document.execCommand`
+*
+* @param text - 要复制的文本
+* @returns 是否复制成功
+*
+* @example
+* ```ts
+* import copyToClipboard from '@tanwan/utils/copyToClipboard'
+* await copyToClipboard('Hello World')
+* ```
+*/
+declare function copyToClipboard(text: string): Promise<boolean>;
+export = copyToClipboard;

package/dist/copyToClipboard.d.ts

@@ -0,0 +1,18 @@
+//#region src/business/copyToClipboard/index.d.ts
+/**
+* 复制文本到剪贴板
+*
+* 优先使用 `navigator.clipboard.writeText`，不支持时降级为 `document.execCommand`
+*
+* @param text - 要复制的文本
+* @returns 是否复制成功
+*
+* @example
+* ```ts
+* import copyToClipboard from '@tanwan/utils/copyToClipboard'
+* await copyToClipboard('Hello World')
+* ```
+*/
+declare function copyToClipboard(text: string): Promise<boolean>;
+//#endregion
+export { copyToClipboard as default };

package/dist/copyToClipboard.js

@@ -0,0 +1,38 @@
+//#region src/business/copyToClipboard/index.ts
+/**
+* 复制文本到剪贴板
+*
+* 优先使用 `navigator.clipboard.writeText`，不支持时降级为 `document.execCommand`
+*
+* @param text - 要复制的文本
+* @returns 是否复制成功
+*
+* @example
+* ```ts
+* import copyToClipboard from '@tanwan/utils/copyToClipboard'
+* await copyToClipboard('Hello World')
+* ```
+*/
+async function copyToClipboard(text) {
+	try {
+		if (navigator.clipboard && typeof navigator.clipboard.writeText === "function") {
+			await navigator.clipboard.writeText(text);
+			return true;
+		}
+	} catch {}
+	const textarea = document.createElement("textarea");
+	textarea.value = text;
+	textarea.style.position = "fixed";
+	textarea.style.opacity = "0";
+	document.body.appendChild(textarea);
+	textarea.select();
+	try {
+		return document.execCommand("copy");
+	} catch {
+		return false;
+	} finally {
+		document.body.removeChild(textarea);
+	}
+}
+//#endregion
+export { copyToClipboard as default };

package/dist/createElement.cjs

@@ -0,0 +1,27 @@
+//#region src/dom/createElement/index.ts
+/**
+* 快捷创建元素并设置属性
+*
+* @param tag - HTML 标签名
+* @param attrs - 属性对象，如 `{ id: 'box', class: 'card' }`
+* @param children - 子节点（文本、元素或元素数组）
+* @returns 创建的 DOM 元素
+*
+* @example
+* ```ts
+* import createElement from '@tanwan/utils/createElement'
+* createElement('div', { class: 'card' }, 'Hello')
+* createElement('ul', { id: 'list' },
+*   createElement('li', {}, 'Item 1'),
+*   createElement('li', {}, 'Item 2'),
+* )
+* ```
+*/
+function createElement(tag, attrs = {}, ...children) {
+	const el = document.createElement(tag);
+	for (const key of Object.keys(attrs)) el.setAttribute(key, attrs[key]);
+	for (const child of children) el.appendChild(typeof child === "string" ? document.createTextNode(child) : child);
+	return el;
+}
+//#endregion
+module.exports = createElement;

package/dist/createElement.d.cts

@@ -0,0 +1,21 @@
+//#region src/dom/createElement/index.d.ts
+/**
+* 快捷创建元素并设置属性
+*
+* @param tag - HTML 标签名
+* @param attrs - 属性对象，如 `{ id: 'box', class: 'card' }`
+* @param children - 子节点（文本、元素或元素数组）
+* @returns 创建的 DOM 元素
+*
+* @example
+* ```ts
+* import createElement from '@tanwan/utils/createElement'
+* createElement('div', { class: 'card' }, 'Hello')
+* createElement('ul', { id: 'list' },
+*   createElement('li', {}, 'Item 1'),
+*   createElement('li', {}, 'Item 2'),
+* )
+* ```
+*/
+declare function createElement<K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Record<string, string>, ...children: (string | Node)[]): HTMLElementTagNameMap[K];
+export = createElement;

package/dist/createElement.d.ts

@@ -0,0 +1,22 @@
+//#region src/dom/createElement/index.d.ts
+/**
+* 快捷创建元素并设置属性
+*
+* @param tag - HTML 标签名
+* @param attrs - 属性对象，如 `{ id: 'box', class: 'card' }`
+* @param children - 子节点（文本、元素或元素数组）
+* @returns 创建的 DOM 元素
+*
+* @example
+* ```ts
+* import createElement from '@tanwan/utils/createElement'
+* createElement('div', { class: 'card' }, 'Hello')
+* createElement('ul', { id: 'list' },
+*   createElement('li', {}, 'Item 1'),
+*   createElement('li', {}, 'Item 2'),
+* )
+* ```
+*/
+declare function createElement<K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Record<string, string>, ...children: (string | Node)[]): HTMLElementTagNameMap[K];
+//#endregion
+export { createElement as default };

package/dist/createElement.js

@@ -0,0 +1,27 @@
+//#region src/dom/createElement/index.ts
+/**
+* 快捷创建元素并设置属性
+*
+* @param tag - HTML 标签名
+* @param attrs - 属性对象，如 `{ id: 'box', class: 'card' }`
+* @param children - 子节点（文本、元素或元素数组）
+* @returns 创建的 DOM 元素
+*
+* @example
+* ```ts
+* import createElement from '@tanwan/utils/createElement'
+* createElement('div', { class: 'card' }, 'Hello')
+* createElement('ul', { id: 'list' },
+*   createElement('li', {}, 'Item 1'),
+*   createElement('li', {}, 'Item 2'),
+* )
+* ```
+*/
+function createElement(tag, attrs = {}, ...children) {
+	const el = document.createElement(tag);
+	for (const key of Object.keys(attrs)) el.setAttribute(key, attrs[key]);
+	for (const child of children) el.appendChild(typeof child === "string" ? document.createTextNode(child) : child);
+	return el;
+}
+//#endregion
+export { createElement as default };

package/dist/{function/debounce.d.cts → debounce.d.cts}

@@ -10,5 +10,4 @@
 * ```
 */
 declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number, immediate?: boolean): (...args: Parameters<T>) => void;
-export = debounce;
-//# sourceMappingURL=debounce.d.cts.map
+export = debounce;

package/dist/{function/debounce.d.ts → debounce.d.ts}

@@ -11,5 +11,4 @@
 */
 declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number, immediate?: boolean): (...args: Parameters<T>) => void;
 //#endregion
-export { debounce as default };
-//# sourceMappingURL=debounce.d.ts.map
+export { debounce as default };

package/dist/{function/debounce.js → debounce.js}

@@ -27,5 +27,3 @@ function debounce(func, wait, immediate = false) {
 }
 //#endregion
 export { debounce as default };
-
-//# sourceMappingURL=debounce.js.map

package/dist/debounceSubmit.cjs

@@ -0,0 +1,34 @@
+//#region src/business/debounceSubmit/index.ts
+/**
+* 包装异步函数，防止重复提交
+*
+* 在函数执行期间，后续调用会被忽略直到第一次调用完成
+*
+* @param fn - 异步提交函数
+* @returns 包装后的函数
+*
+* @example
+* ```ts
+* import debounceSubmit from '@tanwan/utils/debounceSubmit'
+* const submit = debounceSubmit(async (data: FormData) => {
+*   await fetch('/api/submit', { method: 'POST', body: data })
+* })
+*
+* await submit(formData) // 第一次执行
+* await submit(formData) // 忽略（上一次还在执行中）
+* ```
+*/
+function debounceSubmit(fn) {
+	let pending = false;
+	return (async (...args) => {
+		if (pending) return;
+		pending = true;
+		try {
+			return await fn(...args);
+		} finally {
+			pending = false;
+		}
+	});
+}
+//#endregion
+module.exports = debounceSubmit;

package/dist/debounceSubmit.d.cts

@@ -0,0 +1,22 @@
+//#region src/business/debounceSubmit/index.d.ts
+/**
+* 包装异步函数，防止重复提交
+*
+* 在函数执行期间，后续调用会被忽略直到第一次调用完成
+*
+* @param fn - 异步提交函数
+* @returns 包装后的函数
+*
+* @example
+* ```ts
+* import debounceSubmit from '@tanwan/utils/debounceSubmit'
+* const submit = debounceSubmit(async (data: FormData) => {
+*   await fetch('/api/submit', { method: 'POST', body: data })
+* })
+*
+* await submit(formData) // 第一次执行
+* await submit(formData) // 忽略（上一次还在执行中）
+* ```
+*/
+declare function debounceSubmit<T extends (...args: unknown[]) => Promise<unknown>>(fn: T): T;
+export = debounceSubmit;

package/dist/debounceSubmit.d.ts

@@ -0,0 +1,23 @@
+//#region src/business/debounceSubmit/index.d.ts
+/**
+* 包装异步函数，防止重复提交
+*
+* 在函数执行期间，后续调用会被忽略直到第一次调用完成
+*
+* @param fn - 异步提交函数
+* @returns 包装后的函数
+*
+* @example
+* ```ts
+* import debounceSubmit from '@tanwan/utils/debounceSubmit'
+* const submit = debounceSubmit(async (data: FormData) => {
+*   await fetch('/api/submit', { method: 'POST', body: data })
+* })
+*
+* await submit(formData) // 第一次执行
+* await submit(formData) // 忽略（上一次还在执行中）
+* ```
+*/
+declare function debounceSubmit<T extends (...args: unknown[]) => Promise<unknown>>(fn: T): T;
+//#endregion
+export { debounceSubmit as default };