@tanwan/utils 1.0.0 → 1.2.0

package/dist/removeClass.d.cts

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

package/dist/removeClass.d.ts

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

package/dist/removeClass.js

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

package/dist/removeElement.cjs

@@ -0,0 +1,17 @@
+//#region src/dom/removeElement/index.ts
+/**
+* 安全地移除元素
+*
+* @param el - 要移除的 DOM 元素
+*
+* @example
+* ```ts
+* import removeElement from '@tanwan/utils/removeElement'
+* removeElement(document.getElementById('banner'))
+* ```
+*/
+function removeElement(el) {
+	el.remove();
+}
+//#endregion
+module.exports = removeElement;

package/dist/removeElement.d.cts

@@ -0,0 +1,14 @@
+//#region src/dom/removeElement/index.d.ts
+/**
+* 安全地移除元素
+*
+* @param el - 要移除的 DOM 元素
+*
+* @example
+* ```ts
+* import removeElement from '@tanwan/utils/removeElement'
+* removeElement(document.getElementById('banner'))
+* ```
+*/
+declare function removeElement(el: Element): void;
+export = removeElement;

package/dist/removeElement.d.ts

@@ -0,0 +1,15 @@
+//#region src/dom/removeElement/index.d.ts
+/**
+* 安全地移除元素
+*
+* @param el - 要移除的 DOM 元素
+*
+* @example
+* ```ts
+* import removeElement from '@tanwan/utils/removeElement'
+* removeElement(document.getElementById('banner'))
+* ```
+*/
+declare function removeElement(el: Element): void;
+//#endregion
+export { removeElement as default };

package/dist/removeElement.js

@@ -0,0 +1,17 @@
+//#region src/dom/removeElement/index.ts
+/**
+* 安全地移除元素
+*
+* @param el - 要移除的 DOM 元素
+*
+* @example
+* ```ts
+* import removeElement from '@tanwan/utils/removeElement'
+* removeElement(document.getElementById('banner'))
+* ```
+*/
+function removeElement(el) {
+	el.remove();
+}
+//#endregion
+export { removeElement as default };

package/dist/removeStorage.cjs

@@ -0,0 +1,19 @@
+//#region src/storage/removeStorage/index.ts
+/**
+* 安全地从 localStorage 删除指定键
+*
+* @param key - 存储键名
+*
+* @example
+* ```ts
+* import removeStorage from '@tanwan/utils/removeStorage'
+* removeStorage('user')
+* ```
+*/
+function removeStorage(key) {
+	try {
+		localStorage.removeItem(key);
+	} catch {}
+}
+//#endregion
+module.exports = removeStorage;

package/dist/removeStorage.d.cts

@@ -0,0 +1,14 @@
+//#region src/storage/removeStorage/index.d.ts
+/**
+* 安全地从 localStorage 删除指定键
+*
+* @param key - 存储键名
+*
+* @example
+* ```ts
+* import removeStorage from '@tanwan/utils/removeStorage'
+* removeStorage('user')
+* ```
+*/
+declare function removeStorage(key: string): void;
+export = removeStorage;

package/dist/removeStorage.d.ts

@@ -0,0 +1,15 @@
+//#region src/storage/removeStorage/index.d.ts
+/**
+* 安全地从 localStorage 删除指定键
+*
+* @param key - 存储键名
+*
+* @example
+* ```ts
+* import removeStorage from '@tanwan/utils/removeStorage'
+* removeStorage('user')
+* ```
+*/
+declare function removeStorage(key: string): void;
+//#endregion
+export { removeStorage as default };

package/dist/removeStorage.js

@@ -0,0 +1,19 @@
+//#region src/storage/removeStorage/index.ts
+/**
+* 安全地从 localStorage 删除指定键
+*
+* @param key - 存储键名
+*
+* @example
+* ```ts
+* import removeStorage from '@tanwan/utils/removeStorage'
+* removeStorage('user')
+* ```
+*/
+function removeStorage(key) {
+	try {
+		localStorage.removeItem(key);
+	} catch {}
+}
+//#endregion
+export { removeStorage as default };

package/dist/retry.cjs

@@ -0,0 +1,27 @@
+//#region src/business/retry/index.ts
+/**
+* 异步函数失败自动重试
+*
+* @param fn - 返回 Promise 的函数
+* @param maxRetries - 最大重试次数，默认 3
+* @param delayMs - 每次重试间隔（ms），默认 1000
+* @returns 执行结果
+*
+* @example
+* ```ts
+* import retry from '@tanwan/utils/retry'
+* const data = await retry(() => fetch('/api/data').then(r => r.json()), 3, 1000)
+* ```
+*/
+async function retry(fn, maxRetries = 3, delayMs = 1e3) {
+	let lastError;
+	for (let attempt = 0; attempt <= maxRetries; attempt++) try {
+		return await fn();
+	} catch (error) {
+		lastError = error;
+		if (attempt < maxRetries) await new Promise((resolve) => setTimeout(resolve, delayMs));
+	}
+	throw lastError;
+}
+//#endregion
+module.exports = retry;

package/dist/retry.d.cts

@@ -0,0 +1,17 @@
+//#region src/business/retry/index.d.ts
+/**
+* 异步函数失败自动重试
+*
+* @param fn - 返回 Promise 的函数
+* @param maxRetries - 最大重试次数，默认 3
+* @param delayMs - 每次重试间隔（ms），默认 1000
+* @returns 执行结果
+*
+* @example
+* ```ts
+* import retry from '@tanwan/utils/retry'
+* const data = await retry(() => fetch('/api/data').then(r => r.json()), 3, 1000)
+* ```
+*/
+declare function retry<T>(fn: () => Promise<T>, maxRetries?: number, delayMs?: number): Promise<T>;
+export = retry;

package/dist/retry.d.ts

@@ -0,0 +1,18 @@
+//#region src/business/retry/index.d.ts
+/**
+* 异步函数失败自动重试
+*
+* @param fn - 返回 Promise 的函数
+* @param maxRetries - 最大重试次数，默认 3
+* @param delayMs - 每次重试间隔（ms），默认 1000
+* @returns 执行结果
+*
+* @example
+* ```ts
+* import retry from '@tanwan/utils/retry'
+* const data = await retry(() => fetch('/api/data').then(r => r.json()), 3, 1000)
+* ```
+*/
+declare function retry<T>(fn: () => Promise<T>, maxRetries?: number, delayMs?: number): Promise<T>;
+//#endregion
+export { retry as default };

package/dist/retry.js

@@ -0,0 +1,27 @@
+//#region src/business/retry/index.ts
+/**
+* 异步函数失败自动重试
+*
+* @param fn - 返回 Promise 的函数
+* @param maxRetries - 最大重试次数，默认 3
+* @param delayMs - 每次重试间隔（ms），默认 1000
+* @returns 执行结果
+*
+* @example
+* ```ts
+* import retry from '@tanwan/utils/retry'
+* const data = await retry(() => fetch('/api/data').then(r => r.json()), 3, 1000)
+* ```
+*/
+async function retry(fn, maxRetries = 3, delayMs = 1e3) {
+	let lastError;
+	for (let attempt = 0; attempt <= maxRetries; attempt++) try {
+		return await fn();
+	} catch (error) {
+		lastError = error;
+		if (attempt < maxRetries) await new Promise((resolve) => setTimeout(resolve, delayMs));
+	}
+	throw lastError;
+}
+//#endregion
+export { retry as default };

package/dist/sample.cjs

@@ -0,0 +1,20 @@
+//#region src/array/sample/index.ts
+/**
+* 从数组中随机取一个元素
+*
+* @param arr - 源数组
+* @returns 随机元素，数组为空时返回 `undefined`
+*
+* @example
+* ```ts
+* import sample from '@tanwan/utils/sample'
+* sample([1, 2, 3, 4]) // 可能返回 2
+* sample([])           // undefined
+* ```
+*/
+function sample(arr) {
+	if (arr.length === 0) return void 0;
+	return arr[Math.floor(Math.random() * arr.length)];
+}
+//#endregion
+module.exports = sample;

package/dist/sample.d.cts

@@ -0,0 +1,16 @@
+//#region src/array/sample/index.d.ts
+/**
+* 从数组中随机取一个元素
+*
+* @param arr - 源数组
+* @returns 随机元素，数组为空时返回 `undefined`
+*
+* @example
+* ```ts
+* import sample from '@tanwan/utils/sample'
+* sample([1, 2, 3, 4]) // 可能返回 2
+* sample([])           // undefined
+* ```
+*/
+declare function sample<T>(arr: T[]): T | undefined;
+export = sample;

package/dist/sample.d.ts

@@ -0,0 +1,17 @@
+//#region src/array/sample/index.d.ts
+/**
+* 从数组中随机取一个元素
+*
+* @param arr - 源数组
+* @returns 随机元素，数组为空时返回 `undefined`
+*
+* @example
+* ```ts
+* import sample from '@tanwan/utils/sample'
+* sample([1, 2, 3, 4]) // 可能返回 2
+* sample([])           // undefined
+* ```
+*/
+declare function sample<T>(arr: T[]): T | undefined;
+//#endregion
+export { sample as default };

package/dist/sample.js

@@ -0,0 +1,20 @@
+//#region src/array/sample/index.ts
+/**
+* 从数组中随机取一个元素
+*
+* @param arr - 源数组
+* @returns 随机元素，数组为空时返回 `undefined`
+*
+* @example
+* ```ts
+* import sample from '@tanwan/utils/sample'
+* sample([1, 2, 3, 4]) // 可能返回 2
+* sample([])           // undefined
+* ```
+*/
+function sample(arr) {
+	if (arr.length === 0) return void 0;
+	return arr[Math.floor(Math.random() * arr.length)];
+}
+//#endregion
+export { sample as default };

package/dist/scrollToElement.cjs

@@ -0,0 +1,23 @@
+//#region src/dom/scrollToElement/index.ts
+/**
+* 平滑滚动到指定元素
+*
+* @param el - 目标 DOM 元素
+* @param options - ScrollIntoView 选项，默认 `{ behavior: 'smooth', block: 'start' }`
+*
+* @example
+* ```ts
+* import scrollToElement from '@tanwan/utils/scrollToElement'
+* scrollToElement(document.getElementById('section2'))
+* scrollToElement(el, { behavior: 'instant', block: 'center' })
+* ```
+*/
+function scrollToElement(el, options) {
+	el.scrollIntoView({
+		behavior: "smooth",
+		block: "start",
+		...options
+	});
+}
+//#endregion
+module.exports = scrollToElement;

package/dist/scrollToElement.d.cts

@@ -0,0 +1,16 @@
+//#region src/dom/scrollToElement/index.d.ts
+/**
+* 平滑滚动到指定元素
+*
+* @param el - 目标 DOM 元素
+* @param options - ScrollIntoView 选项，默认 `{ behavior: 'smooth', block: 'start' }`
+*
+* @example
+* ```ts
+* import scrollToElement from '@tanwan/utils/scrollToElement'
+* scrollToElement(document.getElementById('section2'))
+* scrollToElement(el, { behavior: 'instant', block: 'center' })
+* ```
+*/
+declare function scrollToElement(el: Element, options?: ScrollIntoViewOptions): void;
+export = scrollToElement;

package/dist/scrollToElement.d.ts

@@ -0,0 +1,17 @@
+//#region src/dom/scrollToElement/index.d.ts
+/**
+* 平滑滚动到指定元素
+*
+* @param el - 目标 DOM 元素
+* @param options - ScrollIntoView 选项，默认 `{ behavior: 'smooth', block: 'start' }`
+*
+* @example
+* ```ts
+* import scrollToElement from '@tanwan/utils/scrollToElement'
+* scrollToElement(document.getElementById('section2'))
+* scrollToElement(el, { behavior: 'instant', block: 'center' })
+* ```
+*/
+declare function scrollToElement(el: Element, options?: ScrollIntoViewOptions): void;
+//#endregion
+export { scrollToElement as default };

package/dist/scrollToElement.js

@@ -0,0 +1,23 @@
+//#region src/dom/scrollToElement/index.ts
+/**
+* 平滑滚动到指定元素
+*
+* @param el - 目标 DOM 元素
+* @param options - ScrollIntoView 选项，默认 `{ behavior: 'smooth', block: 'start' }`
+*
+* @example
+* ```ts
+* import scrollToElement from '@tanwan/utils/scrollToElement'
+* scrollToElement(document.getElementById('section2'))
+* scrollToElement(el, { behavior: 'instant', block: 'center' })
+* ```
+*/
+function scrollToElement(el, options) {
+	el.scrollIntoView({
+		behavior: "smooth",
+		block: "start",
+		...options
+	});
+}
+//#endregion
+export { scrollToElement as default };

package/dist/setCssVar.cjs

@@ -0,0 +1,22 @@
+//#region src/dom/setCssVar/index.ts
+/**
+* 设置 CSS 自定义属性（CSS 变量）
+*
+* @param name - CSS 变量名（可带 `--` 前缀或省略）
+* @param value - CSS 变量值
+* @param el - 指定元素，不传则设置到 `document.documentElement`（`:root`）
+*
+* @example
+* ```ts
+* import setCssVar from '@tanwan/utils/setCssVar'
+* setCssVar('--color-primary', '#ff0000')
+* setCssVar('color-primary', '#ff0000')   // 自动补 -- 前缀
+* setCssVar('--bg', 'dark', el)
+* ```
+*/
+function setCssVar(name, value, el = document.documentElement) {
+	const varName = name.startsWith("--") ? name : `--${name}`;
+	el.style.setProperty(varName, value);
+}
+//#endregion
+module.exports = setCssVar;

package/dist/setCssVar.d.cts

@@ -0,0 +1,18 @@
+//#region src/dom/setCssVar/index.d.ts
+/**
+* 设置 CSS 自定义属性（CSS 变量）
+*
+* @param name - CSS 变量名（可带 `--` 前缀或省略）
+* @param value - CSS 变量值
+* @param el - 指定元素，不传则设置到 `document.documentElement`（`:root`）
+*
+* @example
+* ```ts
+* import setCssVar from '@tanwan/utils/setCssVar'
+* setCssVar('--color-primary', '#ff0000')
+* setCssVar('color-primary', '#ff0000')   // 自动补 -- 前缀
+* setCssVar('--bg', 'dark', el)
+* ```
+*/
+declare function setCssVar(name: string, value: string, el?: HTMLElement): void;
+export = setCssVar;

package/dist/setCssVar.d.ts

@@ -0,0 +1,19 @@
+//#region src/dom/setCssVar/index.d.ts
+/**
+* 设置 CSS 自定义属性（CSS 变量）
+*
+* @param name - CSS 变量名（可带 `--` 前缀或省略）
+* @param value - CSS 变量值
+* @param el - 指定元素，不传则设置到 `document.documentElement`（`:root`）
+*
+* @example
+* ```ts
+* import setCssVar from '@tanwan/utils/setCssVar'
+* setCssVar('--color-primary', '#ff0000')
+* setCssVar('color-primary', '#ff0000')   // 自动补 -- 前缀
+* setCssVar('--bg', 'dark', el)
+* ```
+*/
+declare function setCssVar(name: string, value: string, el?: HTMLElement): void;
+//#endregion
+export { setCssVar as default };

package/dist/setCssVar.js

@@ -0,0 +1,22 @@
+//#region src/dom/setCssVar/index.ts
+/**
+* 设置 CSS 自定义属性（CSS 变量）
+*
+* @param name - CSS 变量名（可带 `--` 前缀或省略）
+* @param value - CSS 变量值
+* @param el - 指定元素，不传则设置到 `document.documentElement`（`:root`）
+*
+* @example
+* ```ts
+* import setCssVar from '@tanwan/utils/setCssVar'
+* setCssVar('--color-primary', '#ff0000')
+* setCssVar('color-primary', '#ff0000')   // 自动补 -- 前缀
+* setCssVar('--bg', 'dark', el)
+* ```
+*/
+function setCssVar(name, value, el = document.documentElement) {
+	const varName = name.startsWith("--") ? name : `--${name}`;
+	el.style.setProperty(varName, value);
+}
+//#endregion
+export { setCssVar as default };

package/dist/setStorage.cjs

@@ -0,0 +1,25 @@
+//#region src/storage/setStorage/index.ts
+/**
+* 安全地将值序列化为 JSON 并写入 localStorage
+*
+* @param key - 存储键名
+* @param value - 要存储的值
+* @returns 是否写入成功
+*
+* @example
+* ```ts
+* import setStorage from '@tanwan/utils/setStorage'
+* setStorage('user', { name: 'Alice' })
+* // localStorage.getItem('user') → '{"name":"Alice"}'
+* ```
+*/
+function setStorage(key, value) {
+	try {
+		localStorage.setItem(key, JSON.stringify(value));
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+module.exports = setStorage;

package/dist/setStorage.d.cts

@@ -0,0 +1,17 @@
+//#region src/storage/setStorage/index.d.ts
+/**
+* 安全地将值序列化为 JSON 并写入 localStorage
+*
+* @param key - 存储键名
+* @param value - 要存储的值
+* @returns 是否写入成功
+*
+* @example
+* ```ts
+* import setStorage from '@tanwan/utils/setStorage'
+* setStorage('user', { name: 'Alice' })
+* // localStorage.getItem('user') → '{"name":"Alice"}'
+* ```
+*/
+declare function setStorage(key: string, value: unknown): boolean;
+export = setStorage;

package/dist/setStorage.d.ts

@@ -0,0 +1,18 @@
+//#region src/storage/setStorage/index.d.ts
+/**
+* 安全地将值序列化为 JSON 并写入 localStorage
+*
+* @param key - 存储键名
+* @param value - 要存储的值
+* @returns 是否写入成功
+*
+* @example
+* ```ts
+* import setStorage from '@tanwan/utils/setStorage'
+* setStorage('user', { name: 'Alice' })
+* // localStorage.getItem('user') → '{"name":"Alice"}'
+* ```
+*/
+declare function setStorage(key: string, value: unknown): boolean;
+//#endregion
+export { setStorage as default };

package/dist/setStorage.js

@@ -0,0 +1,25 @@
+//#region src/storage/setStorage/index.ts
+/**
+* 安全地将值序列化为 JSON 并写入 localStorage
+*
+* @param key - 存储键名
+* @param value - 要存储的值
+* @returns 是否写入成功
+*
+* @example
+* ```ts
+* import setStorage from '@tanwan/utils/setStorage'
+* setStorage('user', { name: 'Alice' })
+* // localStorage.getItem('user') → '{"name":"Alice"}'
+* ```
+*/
+function setStorage(key, value) {
+	try {
+		localStorage.setItem(key, JSON.stringify(value));
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { setStorage as default };

package/dist/setStyle.cjs

@@ -0,0 +1,22 @@
+//#region src/dom/setStyle/index.ts
+/**
+* 批量设置元素行内样式
+*
+* @param el - DOM 元素
+* @param styles - 样式对象，属性名为 camelCase
+*
+* @example
+* ```ts
+* import setStyle from '@tanwan/utils/setStyle'
+* setStyle(el, {
+*   width: '100px',
+*   height: '200px',
+*   backgroundColor: 'red',
+* })
+* ```
+*/
+function setStyle(el, styles) {
+	for (const key of Object.keys(styles)) el.style[key] = String(styles[key]);
+}
+//#endregion
+module.exports = setStyle;