@tanwan/utils 1.0.0 → 1.2.0

package/dist/getStorage.cjs

@@ -0,0 +1,27 @@
+//#region src/storage/getStorage/index.ts
+/**
+* 安全地从 localStorage 读取并解析 JSON
+*
+* @param key - 存储键名
+* @param defaultValue - 读取失败或不存在时的默认值
+* @returns 解析后的值或默认值
+*
+* @example
+* ```ts
+* import getStorage from '@tanwan/utils/getStorage'
+* localStorage.setItem('user', '{"name":"Alice"}')
+* getStorage('user')                 // { name: 'Alice' }
+* getStorage('notExist', 'default')  // 'default'
+* ```
+*/
+function getStorage(key, defaultValue) {
+	try {
+		const raw = localStorage.getItem(key);
+		if (raw === null) return defaultValue ?? null;
+		return JSON.parse(raw);
+	} catch {
+		return defaultValue ?? null;
+	}
+}
+//#endregion
+module.exports = getStorage;

package/dist/getStorage.d.cts

@@ -0,0 +1,18 @@
+//#region src/storage/getStorage/index.d.ts
+/**
+* 安全地从 localStorage 读取并解析 JSON
+*
+* @param key - 存储键名
+* @param defaultValue - 读取失败或不存在时的默认值
+* @returns 解析后的值或默认值
+*
+* @example
+* ```ts
+* import getStorage from '@tanwan/utils/getStorage'
+* localStorage.setItem('user', '{"name":"Alice"}')
+* getStorage('user')                 // { name: 'Alice' }
+* getStorage('notExist', 'default')  // 'default'
+* ```
+*/
+declare function getStorage<T = unknown>(key: string, defaultValue?: T): T | null;
+export = getStorage;

package/dist/getStorage.d.ts

@@ -0,0 +1,19 @@
+//#region src/storage/getStorage/index.d.ts
+/**
+* 安全地从 localStorage 读取并解析 JSON
+*
+* @param key - 存储键名
+* @param defaultValue - 读取失败或不存在时的默认值
+* @returns 解析后的值或默认值
+*
+* @example
+* ```ts
+* import getStorage from '@tanwan/utils/getStorage'
+* localStorage.setItem('user', '{"name":"Alice"}')
+* getStorage('user')                 // { name: 'Alice' }
+* getStorage('notExist', 'default')  // 'default'
+* ```
+*/
+declare function getStorage<T = unknown>(key: string, defaultValue?: T): T | null;
+//#endregion
+export { getStorage as default };

package/dist/getStorage.js

@@ -0,0 +1,27 @@
+//#region src/storage/getStorage/index.ts
+/**
+* 安全地从 localStorage 读取并解析 JSON
+*
+* @param key - 存储键名
+* @param defaultValue - 读取失败或不存在时的默认值
+* @returns 解析后的值或默认值
+*
+* @example
+* ```ts
+* import getStorage from '@tanwan/utils/getStorage'
+* localStorage.setItem('user', '{"name":"Alice"}')
+* getStorage('user')                 // { name: 'Alice' }
+* getStorage('notExist', 'default')  // 'default'
+* ```
+*/
+function getStorage(key, defaultValue) {
+	try {
+		const raw = localStorage.getItem(key);
+		if (raw === null) return defaultValue ?? null;
+		return JSON.parse(raw);
+	} catch {
+		return defaultValue ?? null;
+	}
+}
+//#endregion
+export { getStorage as default };

package/dist/getStyle.cjs

@@ -0,0 +1,20 @@
+//#region src/dom/getStyle/index.ts
+/**
+* 获取元素的计算样式
+*
+* @param el - DOM 元素
+* @param property - CSS 属性名（camelCase），如 `'fontSize'`
+* @returns 计算后的样式值
+*
+* @example
+* ```ts
+* import getStyle from '@tanwan/utils/getStyle'
+* getStyle(el, 'fontSize')  // '16px'
+* getStyle(el, 'color')     // 'rgb(0, 0, 0)'
+* ```
+*/
+function getStyle(el, property) {
+	return window.getComputedStyle(el).getPropertyValue(property);
+}
+//#endregion
+module.exports = getStyle;

package/dist/getStyle.d.cts

@@ -0,0 +1,17 @@
+//#region src/dom/getStyle/index.d.ts
+/**
+* 获取元素的计算样式
+*
+* @param el - DOM 元素
+* @param property - CSS 属性名（camelCase），如 `'fontSize'`
+* @returns 计算后的样式值
+*
+* @example
+* ```ts
+* import getStyle from '@tanwan/utils/getStyle'
+* getStyle(el, 'fontSize')  // '16px'
+* getStyle(el, 'color')     // 'rgb(0, 0, 0)'
+* ```
+*/
+declare function getStyle(el: Element, property: string): string;
+export = getStyle;

package/dist/getStyle.d.ts

@@ -0,0 +1,18 @@
+//#region src/dom/getStyle/index.d.ts
+/**
+* 获取元素的计算样式
+*
+* @param el - DOM 元素
+* @param property - CSS 属性名（camelCase），如 `'fontSize'`
+* @returns 计算后的样式值
+*
+* @example
+* ```ts
+* import getStyle from '@tanwan/utils/getStyle'
+* getStyle(el, 'fontSize')  // '16px'
+* getStyle(el, 'color')     // 'rgb(0, 0, 0)'
+* ```
+*/
+declare function getStyle(el: Element, property: string): string;
+//#endregion
+export { getStyle as default };

package/dist/getStyle.js

@@ -0,0 +1,20 @@
+//#region src/dom/getStyle/index.ts
+/**
+* 获取元素的计算样式
+*
+* @param el - DOM 元素
+* @param property - CSS 属性名（camelCase），如 `'fontSize'`
+* @returns 计算后的样式值
+*
+* @example
+* ```ts
+* import getStyle from '@tanwan/utils/getStyle'
+* getStyle(el, 'fontSize')  // '16px'
+* getStyle(el, 'color')     // 'rgb(0, 0, 0)'
+* ```
+*/
+function getStyle(el, property) {
+	return window.getComputedStyle(el).getPropertyValue(property);
+}
+//#endregion
+export { getStyle as default };

package/dist/getTextWidth.cjs

@@ -0,0 +1,26 @@
+//#region src/dom/getTextWidth/index.ts
+let ctx = null;
+function getContext() {
+	if (!ctx) ctx = document.createElement("canvas").getContext("2d");
+	return ctx;
+}
+/**
+* 获取文本渲染宽度（canvas 测量）
+*
+* @param text - 待测量文本
+* @param font - CSS font 字符串，如 `'bold 16px sans-serif'`
+* @returns 文本宽度（px）
+*
+* @example
+* ```ts
+* import getTextWidth from '@tanwan/utils/getTextWidth'
+* getTextWidth('Hello World', '16px Arial')
+* ```
+*/
+function getTextWidth(text, font) {
+	const context = getContext();
+	context.font = font;
+	return context.measureText(text).width;
+}
+//#endregion
+module.exports = getTextWidth;

package/dist/getTextWidth.d.cts

@@ -0,0 +1,16 @@
+//#region src/dom/getTextWidth/index.d.ts
+/**
+* 获取文本渲染宽度（canvas 测量）
+*
+* @param text - 待测量文本
+* @param font - CSS font 字符串，如 `'bold 16px sans-serif'`
+* @returns 文本宽度（px）
+*
+* @example
+* ```ts
+* import getTextWidth from '@tanwan/utils/getTextWidth'
+* getTextWidth('Hello World', '16px Arial')
+* ```
+*/
+declare function getTextWidth(text: string, font: string): number;
+export = getTextWidth;

package/dist/getTextWidth.d.ts

@@ -0,0 +1,17 @@
+//#region src/dom/getTextWidth/index.d.ts
+/**
+* 获取文本渲染宽度（canvas 测量）
+*
+* @param text - 待测量文本
+* @param font - CSS font 字符串，如 `'bold 16px sans-serif'`
+* @returns 文本宽度（px）
+*
+* @example
+* ```ts
+* import getTextWidth from '@tanwan/utils/getTextWidth'
+* getTextWidth('Hello World', '16px Arial')
+* ```
+*/
+declare function getTextWidth(text: string, font: string): number;
+//#endregion
+export { getTextWidth as default };

package/dist/getTextWidth.js

@@ -0,0 +1,26 @@
+//#region src/dom/getTextWidth/index.ts
+let ctx = null;
+function getContext() {
+	if (!ctx) ctx = document.createElement("canvas").getContext("2d");
+	return ctx;
+}
+/**
+* 获取文本渲染宽度（canvas 测量）
+*
+* @param text - 待测量文本
+* @param font - CSS font 字符串，如 `'bold 16px sans-serif'`
+* @returns 文本宽度（px）
+*
+* @example
+* ```ts
+* import getTextWidth from '@tanwan/utils/getTextWidth'
+* getTextWidth('Hello World', '16px Arial')
+* ```
+*/
+function getTextWidth(text, font) {
+	const context = getContext();
+	context.font = font;
+	return context.measureText(text).width;
+}
+//#endregion
+export { getTextWidth as default };

package/dist/groupBy.cjs

@@ -0,0 +1,36 @@
+//#region src/array/groupBy/index.ts
+/**
+* 根据指定的 key 或迭代函数对数组进行分组
+*
+* @param arr - 待分组的数组
+* @param iteratee - 分组依据：可以是属性名或返回分组 key 的函数
+* @returns 分组后的对象
+*
+* @example
+* ```ts
+* import groupBy from '@tanwan/utils/groupBy'
+* // 按属性名分组
+* groupBy([{ type: 'a', val: 1 }, { type: 'b', val: 2 }, { type: 'a', val: 3 }], 'type')
+* // { a: [{ type: 'a', val: 1 }, { type: 'a', val: 3 }], b: [{ type: 'b', val: 2 }] }
+*
+* // 按函数分组
+* groupBy([1.2, 2.3, 3.4], Math.floor)
+* // { 1: [1.2], 2: [2.3], 3: [3.4] }
+*
+* // 按条件分组
+* groupBy([1, 2, 3, 4, 5], (n) => (n % 2 === 0 ? 'even' : 'odd'))
+* // { even: [2, 4], odd: [1, 3, 5] }
+* ```
+*/
+function groupBy(arr, iteratee) {
+	const result = {};
+	const getKey = typeof iteratee === "function" ? iteratee : (item) => String(item[iteratee]);
+	for (const item of arr) {
+		const key = String(getKey(item));
+		if (!result[key]) result[key] = [];
+		result[key].push(item);
+	}
+	return result;
+}
+//#endregion
+module.exports = groupBy;

package/dist/groupBy.d.cts

@@ -0,0 +1,26 @@
+//#region src/array/groupBy/index.d.ts
+/**
+* 根据指定的 key 或迭代函数对数组进行分组
+*
+* @param arr - 待分组的数组
+* @param iteratee - 分组依据：可以是属性名或返回分组 key 的函数
+* @returns 分组后的对象
+*
+* @example
+* ```ts
+* import groupBy from '@tanwan/utils/groupBy'
+* // 按属性名分组
+* groupBy([{ type: 'a', val: 1 }, { type: 'b', val: 2 }, { type: 'a', val: 3 }], 'type')
+* // { a: [{ type: 'a', val: 1 }, { type: 'a', val: 3 }], b: [{ type: 'b', val: 2 }] }
+*
+* // 按函数分组
+* groupBy([1.2, 2.3, 3.4], Math.floor)
+* // { 1: [1.2], 2: [2.3], 3: [3.4] }
+*
+* // 按条件分组
+* groupBy([1, 2, 3, 4, 5], (n) => (n % 2 === 0 ? 'even' : 'odd'))
+* // { even: [2, 4], odd: [1, 3, 5] }
+* ```
+*/
+declare function groupBy<T>(arr: T[], iteratee: keyof T | ((item: T) => string | number)): Record<string, T[]>;
+export = groupBy;

package/dist/groupBy.d.ts

@@ -0,0 +1,27 @@
+//#region src/array/groupBy/index.d.ts
+/**
+* 根据指定的 key 或迭代函数对数组进行分组
+*
+* @param arr - 待分组的数组
+* @param iteratee - 分组依据：可以是属性名或返回分组 key 的函数
+* @returns 分组后的对象
+*
+* @example
+* ```ts
+* import groupBy from '@tanwan/utils/groupBy'
+* // 按属性名分组
+* groupBy([{ type: 'a', val: 1 }, { type: 'b', val: 2 }, { type: 'a', val: 3 }], 'type')
+* // { a: [{ type: 'a', val: 1 }, { type: 'a', val: 3 }], b: [{ type: 'b', val: 2 }] }
+*
+* // 按函数分组
+* groupBy([1.2, 2.3, 3.4], Math.floor)
+* // { 1: [1.2], 2: [2.3], 3: [3.4] }
+*
+* // 按条件分组
+* groupBy([1, 2, 3, 4, 5], (n) => (n % 2 === 0 ? 'even' : 'odd'))
+* // { even: [2, 4], odd: [1, 3, 5] }
+* ```
+*/
+declare function groupBy<T>(arr: T[], iteratee: keyof T | ((item: T) => string | number)): Record<string, T[]>;
+//#endregion
+export { groupBy as default };

package/dist/groupBy.js

@@ -0,0 +1,36 @@
+//#region src/array/groupBy/index.ts
+/**
+* 根据指定的 key 或迭代函数对数组进行分组
+*
+* @param arr - 待分组的数组
+* @param iteratee - 分组依据：可以是属性名或返回分组 key 的函数
+* @returns 分组后的对象
+*
+* @example
+* ```ts
+* import groupBy from '@tanwan/utils/groupBy'
+* // 按属性名分组
+* groupBy([{ type: 'a', val: 1 }, { type: 'b', val: 2 }, { type: 'a', val: 3 }], 'type')
+* // { a: [{ type: 'a', val: 1 }, { type: 'a', val: 3 }], b: [{ type: 'b', val: 2 }] }
+*
+* // 按函数分组
+* groupBy([1.2, 2.3, 3.4], Math.floor)
+* // { 1: [1.2], 2: [2.3], 3: [3.4] }
+*
+* // 按条件分组
+* groupBy([1, 2, 3, 4, 5], (n) => (n % 2 === 0 ? 'even' : 'odd'))
+* // { even: [2, 4], odd: [1, 3, 5] }
+* ```
+*/
+function groupBy(arr, iteratee) {
+	const result = {};
+	const getKey = typeof iteratee === "function" ? iteratee : (item) => String(item[iteratee]);
+	for (const item of arr) {
+		const key = String(getKey(item));
+		if (!result[key]) result[key] = [];
+		result[key].push(item);
+	}
+	return result;
+}
+//#endregion
+export { groupBy as default };

package/dist/hasClass.cjs

@@ -0,0 +1,19 @@
+//#region src/dom/hasClass/index.ts
+/**
+* 判断元素是否包含指定 CSS class
+*
+* @param el - DOM 元素
+* @param className - CSS class 名称
+* @returns 是否包含
+*
+* @example
+* ```ts
+* import hasClass from '@tanwan/utils/hasClass'
+* hasClass(document.getElementById('box'), 'active')
+* ```
+*/
+function hasClass(el, className) {
+	return el.classList.contains(className);
+}
+//#endregion
+module.exports = hasClass;

package/dist/hasClass.d.cts

@@ -0,0 +1,16 @@
+//#region src/dom/hasClass/index.d.ts
+/**
+* 判断元素是否包含指定 CSS class
+*
+* @param el - DOM 元素
+* @param className - CSS class 名称
+* @returns 是否包含
+*
+* @example
+* ```ts
+* import hasClass from '@tanwan/utils/hasClass'
+* hasClass(document.getElementById('box'), 'active')
+* ```
+*/
+declare function hasClass(el: Element, className: string): boolean;
+export = hasClass;

package/dist/hasClass.d.ts

@@ -0,0 +1,17 @@
+//#region src/dom/hasClass/index.d.ts
+/**
+* 判断元素是否包含指定 CSS class
+*
+* @param el - DOM 元素
+* @param className - CSS class 名称
+* @returns 是否包含
+*
+* @example
+* ```ts
+* import hasClass from '@tanwan/utils/hasClass'
+* hasClass(document.getElementById('box'), 'active')
+* ```
+*/
+declare function hasClass(el: Element, className: string): boolean;
+//#endregion
+export { hasClass as default };

package/dist/hasClass.js

@@ -0,0 +1,19 @@
+//#region src/dom/hasClass/index.ts
+/**
+* 判断元素是否包含指定 CSS class
+*
+* @param el - DOM 元素
+* @param className - CSS class 名称
+* @returns 是否包含
+*
+* @example
+* ```ts
+* import hasClass from '@tanwan/utils/hasClass'
+* hasClass(document.getElementById('box'), 'active')
+* ```
+*/
+function hasClass(el, className) {
+	return el.classList.contains(className);
+}
+//#endregion
+export { hasClass as default };