@tanwan/utils 1.0.0 → 1.2.0

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.cjs → debounce.cjs}

@@ -3,7 +3,7 @@
 * 防抖函数
 * @example
 * ```ts
-* import debounce from '@tw/utils/debounce'
+* import debounce from '@tanwan/utils/debounce'
 * const search = debounce((keyword: string) => {
 *   console.log('搜索:', keyword)
 * }, 300)

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

@@ -3,12 +3,11 @@
 * 防抖函数
 * @example
 * ```ts
-* import debounce from '@tw/utils/debounce'
+* import debounce from '@tanwan/utils/debounce'
 * const search = debounce((keyword: string) => {
 *   console.log('搜索:', keyword)
 * }, 300)
 * ```
 */
 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}

@@ -3,7 +3,7 @@
 * 防抖函数
 * @example
 * ```ts
-* import debounce from '@tw/utils/debounce'
+* import debounce from '@tanwan/utils/debounce'
 * const search = debounce((keyword: string) => {
 *   console.log('搜索:', keyword)
 * }, 300)
@@ -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}

@@ -3,7 +3,7 @@
 * 防抖函数
 * @example
 * ```ts
-* import debounce from '@tw/utils/debounce'
+* import debounce from '@tanwan/utils/debounce'
 * const search = debounce((keyword: string) => {
 *   console.log('搜索:', keyword)
 * }, 300)
@@ -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 };

package/dist/debounceSubmit.js

@@ -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
+export { debounceSubmit as default };

package/dist/decodeBase64.cjs

@@ -0,0 +1,19 @@
+//#region src/business/decodeBase64/index.ts
+/**
+* Base64 解码（支持中文）
+*
+* @param str - Base64 编码的字符串
+* @returns 解码结果
+*
+* @example
+* ```ts
+* import { encodeBase64, decodeBase64 } from '@tanwan/utils'
+* decodeBase64('SGVsbG8=')    // 'Hello'
+* decodeBase64('5L2g5aW9')    // '你好'
+* ```
+*/
+function decodeBase64(str) {
+	return decodeURIComponent(escape(atob(str)));
+}
+//#endregion
+module.exports = decodeBase64;

package/dist/decodeBase64.d.cts

@@ -0,0 +1,16 @@
+//#region src/business/decodeBase64/index.d.ts
+/**
+* Base64 解码（支持中文）
+*
+* @param str - Base64 编码的字符串
+* @returns 解码结果
+*
+* @example
+* ```ts
+* import { encodeBase64, decodeBase64 } from '@tanwan/utils'
+* decodeBase64('SGVsbG8=')    // 'Hello'
+* decodeBase64('5L2g5aW9')    // '你好'
+* ```
+*/
+declare function decodeBase64(str: string): string;
+export = decodeBase64;

package/dist/decodeBase64.d.ts

@@ -0,0 +1,17 @@
+//#region src/business/decodeBase64/index.d.ts
+/**
+* Base64 解码（支持中文）
+*
+* @param str - Base64 编码的字符串
+* @returns 解码结果
+*
+* @example
+* ```ts
+* import { encodeBase64, decodeBase64 } from '@tanwan/utils'
+* decodeBase64('SGVsbG8=')    // 'Hello'
+* decodeBase64('5L2g5aW9')    // '你好'
+* ```
+*/
+declare function decodeBase64(str: string): string;
+//#endregion
+export { decodeBase64 as default };

package/dist/decodeBase64.js

@@ -0,0 +1,19 @@
+//#region src/business/decodeBase64/index.ts
+/**
+* Base64 解码（支持中文）
+*
+* @param str - Base64 编码的字符串
+* @returns 解码结果
+*
+* @example
+* ```ts
+* import { encodeBase64, decodeBase64 } from '@tanwan/utils'
+* decodeBase64('SGVsbG8=')    // 'Hello'
+* decodeBase64('5L2g5aW9')    // '你好'
+* ```
+*/
+function decodeBase64(str) {
+	return decodeURIComponent(escape(atob(str)));
+}
+//#endregion
+export { decodeBase64 as default };

package/dist/{base/deepClone.cjs → deepClone.cjs}

@@ -1,10 +1,10 @@
-const require_base_isObject = require("./isObject.cjs");
+const require_isObject = require("./isObject.cjs");
 //#region src/base/deepClone/index.ts
 /**
 * 深拷贝变量
 * @example
 * ```ts
-* import deepClone from '@tw/utils/deepClone'
+* import deepClone from '@tanwan/utils/deepClone'
 * const obj = { a: 1, b: { c: 2 } }
 * const clone = deepClone(obj)
 * clone.b.c = 3
@@ -36,7 +36,7 @@ function deepClone(v, cache = /* @__PURE__ */ new WeakMap()) {
 	}
 	if (v instanceof WeakMap) throw new Error("Cannot clone WeakMap");
 	if (v instanceof WeakSet) throw new Error("Cannot clone WeakSet");
-	if (require_base_isObject(v)) {
+	if (require_isObject(v)) {
 		const cloned = {};
 		cache.set(v, cloned);
 		for (const key in v) if (Object.prototype.hasOwnProperty.call(v, key)) cloned[key] = deepClone(v[key], cache);

package/dist/{base/deepClone.d.cts → deepClone.d.cts}

@@ -3,7 +3,7 @@
 * 深拷贝变量
 * @example
 * ```ts
-* import deepClone from '@tw/utils/deepClone'
+* import deepClone from '@tanwan/utils/deepClone'
 * const obj = { a: 1, b: { c: 2 } }
 * const clone = deepClone(obj)
 * clone.b.c = 3
@@ -11,5 +11,4 @@
 * ```
 */
 declare function deepClone<T>(v: T, cache?: WeakMap<object, unknown>): T;
-export = deepClone;
-//# sourceMappingURL=deepClone.d.cts.map
+export = deepClone;

package/dist/{base/deepClone.d.ts → deepClone.d.ts}

@@ -3,7 +3,7 @@
 * 深拷贝变量
 * @example
 * ```ts
-* import deepClone from '@tw/utils/deepClone'
+* import deepClone from '@tanwan/utils/deepClone'
 * const obj = { a: 1, b: { c: 2 } }
 * const clone = deepClone(obj)
 * clone.b.c = 3
@@ -12,5 +12,4 @@
 */
 declare function deepClone<T>(v: T, cache?: WeakMap<object, unknown>): T;
 //#endregion
-export { deepClone as default };
-//# sourceMappingURL=deepClone.d.ts.map
+export { deepClone as default };

package/dist/{base/deepClone.js → deepClone.js}

@@ -4,7 +4,7 @@ import isObject from "./isObject.js";
 * 深拷贝变量
 * @example
 * ```ts
-* import deepClone from '@tw/utils/deepClone'
+* import deepClone from '@tanwan/utils/deepClone'
 * const obj = { a: 1, b: { c: 2 } }
 * const clone = deepClone(obj)
 * clone.b.c = 3
@@ -46,5 +46,3 @@ function deepClone(v, cache = /* @__PURE__ */ new WeakMap()) {
 }
 //#endregion
 export { deepClone as default };
-
-//# sourceMappingURL=deepClone.js.map

package/dist/deepMerge.cjs

@@ -0,0 +1,39 @@
+const require_isObject = require("./isObject.cjs");
+//#region src/object/deepMerge/index.ts
+/**
+* 深度合并多个对象，返回新对象
+*
+* - 后面的对象会覆盖前面对象的同名属性
+* - 嵌套对象会递归合并，数组和基本类型直接覆盖
+*
+* @param sources - 要合并的源对象列表
+* @returns 合并后的新对象
+*
+* @example
+* ```ts
+* import deepMerge from '@tanwan/utils/deepMerge'
+* deepMerge({ a: 1 }, { b: 2 })
+* // { a: 1, b: 2 }
+*
+* deepMerge({ a: { x: 1 } }, { a: { y: 2 } })
+* // { a: { x: 1, y: 2 } }
+*
+* deepMerge({ a: [1] }, { a: [2] })
+* // { a: [2] }
+* ```
+*/
+function deepMerge(...sources) {
+	const result = {};
+	for (const source of sources) {
+		if (!source) continue;
+		for (const key of Object.keys(source)) {
+			const sv = source[key];
+			const rv = result[key];
+			if (require_isObject(sv) && require_isObject(rv) && !Array.isArray(sv) && !Array.isArray(rv)) result[key] = deepMerge(rv, sv);
+			else result[key] = sv;
+		}
+	}
+	return result;
+}
+//#endregion
+module.exports = deepMerge;

package/dist/deepMerge.d.cts

@@ -0,0 +1,25 @@
+//#region src/object/deepMerge/index.d.ts
+/**
+* 深度合并多个对象，返回新对象
+*
+* - 后面的对象会覆盖前面对象的同名属性
+* - 嵌套对象会递归合并，数组和基本类型直接覆盖
+*
+* @param sources - 要合并的源对象列表
+* @returns 合并后的新对象
+*
+* @example
+* ```ts
+* import deepMerge from '@tanwan/utils/deepMerge'
+* deepMerge({ a: 1 }, { b: 2 })
+* // { a: 1, b: 2 }
+*
+* deepMerge({ a: { x: 1 } }, { a: { y: 2 } })
+* // { a: { x: 1, y: 2 } }
+*
+* deepMerge({ a: [1] }, { a: [2] })
+* // { a: [2] }
+* ```
+*/
+declare function deepMerge<T extends Record<string, unknown>>(...sources: T[]): T;
+export = deepMerge;

package/dist/deepMerge.d.ts

@@ -0,0 +1,26 @@
+//#region src/object/deepMerge/index.d.ts
+/**
+* 深度合并多个对象，返回新对象
+*
+* - 后面的对象会覆盖前面对象的同名属性
+* - 嵌套对象会递归合并，数组和基本类型直接覆盖
+*
+* @param sources - 要合并的源对象列表
+* @returns 合并后的新对象
+*
+* @example
+* ```ts
+* import deepMerge from '@tanwan/utils/deepMerge'
+* deepMerge({ a: 1 }, { b: 2 })
+* // { a: 1, b: 2 }
+*
+* deepMerge({ a: { x: 1 } }, { a: { y: 2 } })
+* // { a: { x: 1, y: 2 } }
+*
+* deepMerge({ a: [1] }, { a: [2] })
+* // { a: [2] }
+* ```
+*/
+declare function deepMerge<T extends Record<string, unknown>>(...sources: T[]): T;
+//#endregion
+export { deepMerge as default };

package/dist/deepMerge.js

@@ -0,0 +1,39 @@
+import isObject from "./isObject.js";
+//#region src/object/deepMerge/index.ts
+/**
+* 深度合并多个对象，返回新对象
+*
+* - 后面的对象会覆盖前面对象的同名属性
+* - 嵌套对象会递归合并，数组和基本类型直接覆盖
+*
+* @param sources - 要合并的源对象列表
+* @returns 合并后的新对象
+*
+* @example
+* ```ts
+* import deepMerge from '@tanwan/utils/deepMerge'
+* deepMerge({ a: 1 }, { b: 2 })
+* // { a: 1, b: 2 }
+*
+* deepMerge({ a: { x: 1 } }, { a: { y: 2 } })
+* // { a: { x: 1, y: 2 } }
+*
+* deepMerge({ a: [1] }, { a: [2] })
+* // { a: [2] }
+* ```
+*/
+function deepMerge(...sources) {
+	const result = {};
+	for (const source of sources) {
+		if (!source) continue;
+		for (const key of Object.keys(source)) {
+			const sv = source[key];
+			const rv = result[key];
+			if (isObject(sv) && isObject(rv) && !Array.isArray(sv) && !Array.isArray(rv)) result[key] = deepMerge(rv, sv);
+			else result[key] = sv;
+		}
+	}
+	return result;
+}
+//#endregion
+export { deepMerge as default };

package/dist/delay.cjs

@@ -0,0 +1,8 @@
+//#region src/function/delay/index.ts
+function delay(ms = 0, value) {
+	return new Promise((resolve) => {
+		setTimeout(() => resolve(value), ms);
+	});
+}
+//#endregion
+module.exports = delay;

package/dist/delay.d.cts

@@ -0,0 +1,18 @@
+//#region src/function/delay/index.d.ts
+/**
+* 返回一个在指定毫秒后 resolve 的 Promise
+*
+* @param ms - 延迟毫秒数，默认为 0
+* @param value - 可选，resolve 时传递的值
+* @returns 在延迟后 resolve 的 Promise
+*
+* @example
+* ```ts
+* import delay from '@tanwan/utils/delay'
+* await delay(1000)        // 等待 1 秒后 resolve
+* const result = await delay(500, 'done')  // 500ms 后 resolve 'done'
+* ```
+*/
+declare function delay(ms?: number): Promise<void>;
+declare function delay<T>(ms: number, value: T): Promise<T>;
+export = delay;

package/dist/delay.d.ts

@@ -0,0 +1,19 @@
+//#region src/function/delay/index.d.ts
+/**
+* 返回一个在指定毫秒后 resolve 的 Promise
+*
+* @param ms - 延迟毫秒数，默认为 0
+* @param value - 可选，resolve 时传递的值
+* @returns 在延迟后 resolve 的 Promise
+*
+* @example
+* ```ts
+* import delay from '@tanwan/utils/delay'
+* await delay(1000)        // 等待 1 秒后 resolve
+* const result = await delay(500, 'done')  // 500ms 后 resolve 'done'
+* ```
+*/
+declare function delay(ms?: number): Promise<void>;
+declare function delay<T>(ms: number, value: T): Promise<T>;
+//#endregion
+export { delay as default };

package/dist/delay.js

@@ -0,0 +1,8 @@
+//#region src/function/delay/index.ts
+function delay(ms = 0, value) {
+	return new Promise((resolve) => {
+		setTimeout(() => resolve(value), ms);
+	});
+}
+//#endregion
+export { delay as default };

package/dist/difference.cjs

@@ -0,0 +1,24 @@
+//#region src/array/difference/index.ts
+/**
+* 计算两个数组的差集 —— 返回在 `source` 中但不在 `target` 中的元素
+*
+* @param source - 被减数组
+* @param target - 要排除的元素数组
+* @returns 差集新数组
+*
+* @example
+* ```ts
+* import difference from '@tanwan/utils/difference'
+* difference([1, 2, 3], [2])
+* // [1, 3]
+*
+* difference(['a', 'b', 'c'], ['b', 'd'])
+* // ['a', 'c']
+* ```
+*/
+function difference(source, target) {
+	const targetSet = new Set(target);
+	return source.filter((item) => !targetSet.has(item));
+}
+//#endregion
+module.exports = difference;

package/dist/difference.d.cts

@@ -0,0 +1,20 @@
+//#region src/array/difference/index.d.ts
+/**
+* 计算两个数组的差集 —— 返回在 `source` 中但不在 `target` 中的元素
+*
+* @param source - 被减数组
+* @param target - 要排除的元素数组
+* @returns 差集新数组
+*
+* @example
+* ```ts
+* import difference from '@tanwan/utils/difference'
+* difference([1, 2, 3], [2])
+* // [1, 3]
+*
+* difference(['a', 'b', 'c'], ['b', 'd'])
+* // ['a', 'c']
+* ```
+*/
+declare function difference<T>(source: T[], target: T[]): T[];
+export = difference;

package/dist/difference.d.ts

@@ -0,0 +1,21 @@
+//#region src/array/difference/index.d.ts
+/**
+* 计算两个数组的差集 —— 返回在 `source` 中但不在 `target` 中的元素
+*
+* @param source - 被减数组
+* @param target - 要排除的元素数组
+* @returns 差集新数组
+*
+* @example
+* ```ts
+* import difference from '@tanwan/utils/difference'
+* difference([1, 2, 3], [2])
+* // [1, 3]
+*
+* difference(['a', 'b', 'c'], ['b', 'd'])
+* // ['a', 'c']
+* ```
+*/
+declare function difference<T>(source: T[], target: T[]): T[];
+//#endregion
+export { difference as default };

package/dist/difference.js

@@ -0,0 +1,24 @@
+//#region src/array/difference/index.ts
+/**
+* 计算两个数组的差集 —— 返回在 `source` 中但不在 `target` 中的元素
+*
+* @param source - 被减数组
+* @param target - 要排除的元素数组
+* @returns 差集新数组
+*
+* @example
+* ```ts
+* import difference from '@tanwan/utils/difference'
+* difference([1, 2, 3], [2])
+* // [1, 3]
+*
+* difference(['a', 'b', 'c'], ['b', 'd'])
+* // ['a', 'c']
+* ```
+*/
+function difference(source, target) {
+	const targetSet = new Set(target);
+	return source.filter((item) => !targetSet.has(item));
+}
+//#endregion
+export { difference as default };

package/dist/downloadFile.cjs

@@ -0,0 +1,31 @@
+//#region src/business/downloadFile/index.ts
+/**
+* 下载文件（支持 URL 或 Blob）
+*
+* @param source - 文件 URL 地址或 Blob 对象
+* @param filename - 下载文件名
+*
+* @example
+* ```ts
+* import downloadFile from '@tanwan/utils/downloadFile'
+* // 下载 URL
+* downloadFile('https://example.com/file.pdf', 'document.pdf')
+*
+* // 下载 Blob
+* const blob = new Blob(['hello'], { type: 'text/plain' })
+* downloadFile(blob, 'hello.txt')
+* ```
+*/
+function downloadFile(source, filename) {
+	const url = typeof source === "string" ? source : URL.createObjectURL(source);
+	const a = document.createElement("a");
+	a.href = url;
+	a.download = filename;
+	a.style.display = "none";
+	document.body.appendChild(a);
+	a.click();
+	document.body.removeChild(a);
+	if (source instanceof Blob) URL.revokeObjectURL(url);
+}
+//#endregion
+module.exports = downloadFile;