@tanwan/utils 1.1.0 → 1.2.0

package/dist/getByPath.d.cts

@@ -0,0 +1,20 @@
+//#region src/object/getByPath/index.d.ts
+/**
+* 通过路径字符串安全获取嵌套对象的值
+*
+* @param obj - 源对象
+* @param path - 属性路径，支持点号分隔和方括号，如 `'a.b[0].c'`
+* @param defaultValue - 路径不存在时的默认值
+* @returns 路径对应的值，或默认值
+*
+* @example
+* ```ts
+* import getByPath from '@tanwan/utils/getByPath'
+* const obj = { a: { b: [{ c: 42 }] } }
+* getByPath(obj, 'a.b[0].c')       // 42
+* getByPath(obj, 'a.x.y')          // undefined
+* getByPath(obj, 'a.x.y', 'none')  // 'none'
+* ```
+*/
+declare function getByPath<T = unknown>(obj: Record<string, unknown>, path: string, defaultValue?: T): T | undefined;
+export = getByPath;

package/dist/getByPath.d.ts

@@ -0,0 +1,21 @@
+//#region src/object/getByPath/index.d.ts
+/**
+* 通过路径字符串安全获取嵌套对象的值
+*
+* @param obj - 源对象
+* @param path - 属性路径，支持点号分隔和方括号，如 `'a.b[0].c'`
+* @param defaultValue - 路径不存在时的默认值
+* @returns 路径对应的值，或默认值
+*
+* @example
+* ```ts
+* import getByPath from '@tanwan/utils/getByPath'
+* const obj = { a: { b: [{ c: 42 }] } }
+* getByPath(obj, 'a.b[0].c')       // 42
+* getByPath(obj, 'a.x.y')          // undefined
+* getByPath(obj, 'a.x.y', 'none')  // 'none'
+* ```
+*/
+declare function getByPath<T = unknown>(obj: Record<string, unknown>, path: string, defaultValue?: T): T | undefined;
+//#endregion
+export { getByPath as default };

package/dist/getByPath.js

@@ -0,0 +1,29 @@
+//#region src/object/getByPath/index.ts
+/**
+* 通过路径字符串安全获取嵌套对象的值
+*
+* @param obj - 源对象
+* @param path - 属性路径，支持点号分隔和方括号，如 `'a.b[0].c'`
+* @param defaultValue - 路径不存在时的默认值
+* @returns 路径对应的值，或默认值
+*
+* @example
+* ```ts
+* import getByPath from '@tanwan/utils/getByPath'
+* const obj = { a: { b: [{ c: 42 }] } }
+* getByPath(obj, 'a.b[0].c')       // 42
+* getByPath(obj, 'a.x.y')          // undefined
+* getByPath(obj, 'a.x.y', 'none')  // 'none'
+* ```
+*/
+function getByPath(obj, path, defaultValue) {
+	const keys = path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+	let current = obj;
+	for (const key of keys) {
+		if (current === null || current === void 0 || typeof current !== "object") return defaultValue;
+		current = current[key];
+	}
+	return current === void 0 ? defaultValue : current;
+}
+//#endregion
+export { getByPath as default };

package/dist/getCssVar.cjs

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

package/dist/getCssVar.d.cts

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

package/dist/getCssVar.d.ts

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

package/dist/getCssVar.js

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

package/dist/{date/getRelativeTime.d.cts → getRelativeTime.d.cts}

@@ -9,5 +9,4 @@
 * ```
 */
 declare function getRelativeTime(date: number | string | Date, now?: Date): string;
-export = getRelativeTime;
-//# sourceMappingURL=getRelativeTime.d.cts.map
+export = getRelativeTime;

package/dist/{date/getRelativeTime.d.ts → getRelativeTime.d.ts}

@@ -10,5 +10,4 @@
 */
 declare function getRelativeTime(date: number | string | Date, now?: Date): string;
 //#endregion
-export { getRelativeTime as default };
-//# sourceMappingURL=getRelativeTime.d.ts.map
+export { getRelativeTime as default };

package/dist/{date/getRelativeTime.js → getRelativeTime.js}

@@ -27,5 +27,3 @@ function getRelativeTime(date, now = /* @__PURE__ */ new Date()) {
 }
 //#endregion
 export { getRelativeTime as default };
-
-//# sourceMappingURL=getRelativeTime.js.map

package/dist/getScrollTop.cjs

@@ -0,0 +1,28 @@
+//#region src/dom/getScrollTop/index.ts
+/**
+* 获取或设置页面/元素的垂直滚动位置
+*
+* @param value - 设置滚动位置（传数字），不传则返回当前滚动位置
+* @param el - 指定元素，不传则使用全局滚动
+* @returns 当前滚动位置（仅 get 模式）
+*
+* @example
+* ```ts
+* import getScrollTop from '@tanwan/utils/getScrollTop'
+* getScrollTop()          // 获取全局滚动位置
+* getScrollTop(100)       // 设置全局滚动位置为 100
+* getScrollTop(0, el)     // 设置元素滚动位置为 0
+* ```
+*/
+function getScrollTop(value, el) {
+	if (value === void 0) {
+		const target = el || window;
+		if (target === window) return window.scrollY || document.documentElement.scrollTop;
+		return target.scrollTop;
+	}
+	const target = el || window;
+	if (target === window) window.scrollTo({ top: value });
+	else target.scrollTop = value;
+}
+//#endregion
+module.exports = getScrollTop;

package/dist/getScrollTop.d.cts

@@ -0,0 +1,18 @@
+//#region src/dom/getScrollTop/index.d.ts
+/**
+* 获取或设置页面/元素的垂直滚动位置
+*
+* @param value - 设置滚动位置（传数字），不传则返回当前滚动位置
+* @param el - 指定元素，不传则使用全局滚动
+* @returns 当前滚动位置（仅 get 模式）
+*
+* @example
+* ```ts
+* import getScrollTop from '@tanwan/utils/getScrollTop'
+* getScrollTop()          // 获取全局滚动位置
+* getScrollTop(100)       // 设置全局滚动位置为 100
+* getScrollTop(0, el)     // 设置元素滚动位置为 0
+* ```
+*/
+declare function getScrollTop(value?: number, el?: Element | Window): number | void;
+export = getScrollTop;

package/dist/getScrollTop.d.ts

@@ -0,0 +1,19 @@
+//#region src/dom/getScrollTop/index.d.ts
+/**
+* 获取或设置页面/元素的垂直滚动位置
+*
+* @param value - 设置滚动位置（传数字），不传则返回当前滚动位置
+* @param el - 指定元素，不传则使用全局滚动
+* @returns 当前滚动位置（仅 get 模式）
+*
+* @example
+* ```ts
+* import getScrollTop from '@tanwan/utils/getScrollTop'
+* getScrollTop()          // 获取全局滚动位置
+* getScrollTop(100)       // 设置全局滚动位置为 100
+* getScrollTop(0, el)     // 设置元素滚动位置为 0
+* ```
+*/
+declare function getScrollTop(value?: number, el?: Element | Window): number | void;
+//#endregion
+export { getScrollTop as default };

package/dist/getScrollTop.js

@@ -0,0 +1,28 @@
+//#region src/dom/getScrollTop/index.ts
+/**
+* 获取或设置页面/元素的垂直滚动位置
+*
+* @param value - 设置滚动位置（传数字），不传则返回当前滚动位置
+* @param el - 指定元素，不传则使用全局滚动
+* @returns 当前滚动位置（仅 get 模式）
+*
+* @example
+* ```ts
+* import getScrollTop from '@tanwan/utils/getScrollTop'
+* getScrollTop()          // 获取全局滚动位置
+* getScrollTop(100)       // 设置全局滚动位置为 100
+* getScrollTop(0, el)     // 设置元素滚动位置为 0
+* ```
+*/
+function getScrollTop(value, el) {
+	if (value === void 0) {
+		const target = el || window;
+		if (target === window) return window.scrollY || document.documentElement.scrollTop;
+		return target.scrollTop;
+	}
+	const target = el || window;
+	if (target === window) window.scrollTo({ top: value });
+	else target.scrollTop = value;
+}
+//#endregion
+export { getScrollTop as default };

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/{array/groupBy.d.cts → groupBy.d.cts}

@@ -23,5 +23,4 @@
 * ```
 */
 declare function groupBy<T>(arr: T[], iteratee: keyof T | ((item: T) => string | number)): Record<string, T[]>;
-export = groupBy;
-//# sourceMappingURL=groupBy.d.cts.map
+export = groupBy;

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

@@ -24,5 +24,4 @@
 */
 declare function groupBy<T>(arr: T[], iteratee: keyof T | ((item: T) => string | number)): Record<string, T[]>;
 //#endregion
-export { groupBy as default };
-//# sourceMappingURL=groupBy.d.ts.map
+export { groupBy as default };

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

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

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 };