@tanwan/utils 1.1.0 → 1.2.0

package/dist/isInViewport.cjs

@@ -0,0 +1,22 @@
+//#region src/dom/isInViewport/index.ts
+/**
+* 判断元素是否在可视区域内
+*
+* @param el - DOM 元素
+* @param offset - 偏移量（px），正值提前触发，负值延迟触发
+* @returns 是否在视口中
+*
+* @example
+* ```ts
+* import isInViewport from '@tanwan/utils/isInViewport'
+* isInViewport(el)       // 完全或部分在视口中
+* isInViewport(el, 100)  // 提前 100px 就认为在视口中
+* ```
+*/
+function isInViewport(el, offset = 0) {
+	const rect = el.getBoundingClientRect();
+	const { innerHeight, innerWidth } = window;
+	return rect.top < innerHeight + offset && rect.bottom > -offset && rect.left < innerWidth + offset && rect.right > -offset;
+}
+//#endregion
+module.exports = isInViewport;

package/dist/isInViewport.d.cts

@@ -0,0 +1,17 @@
+//#region src/dom/isInViewport/index.d.ts
+/**
+* 判断元素是否在可视区域内
+*
+* @param el - DOM 元素
+* @param offset - 偏移量（px），正值提前触发，负值延迟触发
+* @returns 是否在视口中
+*
+* @example
+* ```ts
+* import isInViewport from '@tanwan/utils/isInViewport'
+* isInViewport(el)       // 完全或部分在视口中
+* isInViewport(el, 100)  // 提前 100px 就认为在视口中
+* ```
+*/
+declare function isInViewport(el: Element, offset?: number): boolean;
+export = isInViewport;

package/dist/isInViewport.d.ts

@@ -0,0 +1,18 @@
+//#region src/dom/isInViewport/index.d.ts
+/**
+* 判断元素是否在可视区域内
+*
+* @param el - DOM 元素
+* @param offset - 偏移量（px），正值提前触发，负值延迟触发
+* @returns 是否在视口中
+*
+* @example
+* ```ts
+* import isInViewport from '@tanwan/utils/isInViewport'
+* isInViewport(el)       // 完全或部分在视口中
+* isInViewport(el, 100)  // 提前 100px 就认为在视口中
+* ```
+*/
+declare function isInViewport(el: Element, offset?: number): boolean;
+//#endregion
+export { isInViewport as default };

package/dist/isInViewport.js

@@ -0,0 +1,22 @@
+//#region src/dom/isInViewport/index.ts
+/**
+* 判断元素是否在可视区域内
+*
+* @param el - DOM 元素
+* @param offset - 偏移量（px），正值提前触发，负值延迟触发
+* @returns 是否在视口中
+*
+* @example
+* ```ts
+* import isInViewport from '@tanwan/utils/isInViewport'
+* isInViewport(el)       // 完全或部分在视口中
+* isInViewport(el, 100)  // 提前 100px 就认为在视口中
+* ```
+*/
+function isInViewport(el, offset = 0) {
+	const rect = el.getBoundingClientRect();
+	const { innerHeight, innerWidth } = window;
+	return rect.top < innerHeight + offset && rect.bottom > -offset && rect.left < innerWidth + offset && rect.right > -offset;
+}
+//#endregion
+export { isInViewport as default };

package/dist/isNil.cjs

@@ -0,0 +1,19 @@
+//#region src/base/isNil/index.ts
+/**
+* 判断值是否为 `null` 或 `undefined`
+*
+* @example
+* ```ts
+* import isNil from '@tanwan/utils/isNil'
+* isNil(null)      // true
+* isNil(undefined) // true
+* isNil(0)         // false
+* isNil('')        // false
+* isNil(false)     // false
+* ```
+*/
+function isNil(value) {
+	return value === null || value === void 0;
+}
+//#endregion
+module.exports = isNil;

package/dist/isNil.d.cts

@@ -0,0 +1,16 @@
+//#region src/base/isNil/index.d.ts
+/**
+* 判断值是否为 `null` 或 `undefined`
+*
+* @example
+* ```ts
+* import isNil from '@tanwan/utils/isNil'
+* isNil(null)      // true
+* isNil(undefined) // true
+* isNil(0)         // false
+* isNil('')        // false
+* isNil(false)     // false
+* ```
+*/
+declare function isNil(value: unknown): value is null | undefined;
+export = isNil;

package/dist/isNil.d.ts

@@ -0,0 +1,17 @@
+//#region src/base/isNil/index.d.ts
+/**
+* 判断值是否为 `null` 或 `undefined`
+*
+* @example
+* ```ts
+* import isNil from '@tanwan/utils/isNil'
+* isNil(null)      // true
+* isNil(undefined) // true
+* isNil(0)         // false
+* isNil('')        // false
+* isNil(false)     // false
+* ```
+*/
+declare function isNil(value: unknown): value is null | undefined;
+//#endregion
+export { isNil as default };

package/dist/isNil.js

@@ -0,0 +1,19 @@
+//#region src/base/isNil/index.ts
+/**
+* 判断值是否为 `null` 或 `undefined`
+*
+* @example
+* ```ts
+* import isNil from '@tanwan/utils/isNil'
+* isNil(null)      // true
+* isNil(undefined) // true
+* isNil(0)         // false
+* isNil('')        // false
+* isNil(false)     // false
+* ```
+*/
+function isNil(value) {
+	return value === null || value === void 0;
+}
+//#endregion
+export { isNil as default };

package/dist/isNumber.cjs

@@ -0,0 +1,19 @@
+//#region src/base/isNumber/index.ts
+/**
+* 判断值是否为数值类型（不含 `NaN`）
+*
+* @example
+* ```ts
+* import isNumber from '@tanwan/utils/isNumber'
+* isNumber(0)       // true
+* isNumber(3.14)    // true
+* isNumber(NaN)     // false
+* isNumber('3')     // false
+* isNumber(null)    // false
+* ```
+*/
+function isNumber(value) {
+	return typeof value === "number" && !Number.isNaN(value);
+}
+//#endregion
+module.exports = isNumber;

package/dist/isNumber.d.cts

@@ -0,0 +1,16 @@
+//#region src/base/isNumber/index.d.ts
+/**
+* 判断值是否为数值类型（不含 `NaN`）
+*
+* @example
+* ```ts
+* import isNumber from '@tanwan/utils/isNumber'
+* isNumber(0)       // true
+* isNumber(3.14)    // true
+* isNumber(NaN)     // false
+* isNumber('3')     // false
+* isNumber(null)    // false
+* ```
+*/
+declare function isNumber(value: unknown): value is number;
+export = isNumber;

package/dist/isNumber.d.ts

@@ -0,0 +1,17 @@
+//#region src/base/isNumber/index.d.ts
+/**
+* 判断值是否为数值类型（不含 `NaN`）
+*
+* @example
+* ```ts
+* import isNumber from '@tanwan/utils/isNumber'
+* isNumber(0)       // true
+* isNumber(3.14)    // true
+* isNumber(NaN)     // false
+* isNumber('3')     // false
+* isNumber(null)    // false
+* ```
+*/
+declare function isNumber(value: unknown): value is number;
+//#endregion
+export { isNumber as default };

package/dist/isNumber.js

@@ -0,0 +1,19 @@
+//#region src/base/isNumber/index.ts
+/**
+* 判断值是否为数值类型（不含 `NaN`）
+*
+* @example
+* ```ts
+* import isNumber from '@tanwan/utils/isNumber'
+* isNumber(0)       // true
+* isNumber(3.14)    // true
+* isNumber(NaN)     // false
+* isNumber('3')     // false
+* isNumber(null)    // false
+* ```
+*/
+function isNumber(value) {
+	return typeof value === "number" && !Number.isNaN(value);
+}
+//#endregion
+export { isNumber as default };

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

@@ -10,5 +10,4 @@
 * ```
 */
 declare function isObject(v: unknown): v is Record<string, unknown>;
-export = isObject;
-//# sourceMappingURL=isObject.d.cts.map
+export = isObject;

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

@@ -11,5 +11,4 @@
 */
 declare function isObject(v: unknown): v is Record<string, unknown>;
 //#endregion
-export { isObject as default };
-//# sourceMappingURL=isObject.d.ts.map
+export { isObject as default };

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

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

package/dist/isPrimitive.cjs

@@ -0,0 +1,21 @@
+//#region src/base/isPrimitive/index.ts
+/**
+* 判断值是否为原始类型
+*
+* 原始类型包括：`string` / `number` / `boolean` / `null` / `undefined` / `symbol` / `bigint`
+*
+* @example
+* ```ts
+* import isPrimitive from '@tanwan/utils/isPrimitive'
+* isPrimitive('hello') // true
+* isPrimitive(42)      // true
+* isPrimitive(null)    // true
+* isPrimitive({})      // false
+* isPrimitive([])      // false
+* ```
+*/
+function isPrimitive(value) {
+	return value === null || typeof value !== "object" && typeof value !== "function";
+}
+//#endregion
+module.exports = isPrimitive;

package/dist/isPrimitive.d.cts

@@ -0,0 +1,18 @@
+//#region src/base/isPrimitive/index.d.ts
+/**
+* 判断值是否为原始类型
+*
+* 原始类型包括：`string` / `number` / `boolean` / `null` / `undefined` / `symbol` / `bigint`
+*
+* @example
+* ```ts
+* import isPrimitive from '@tanwan/utils/isPrimitive'
+* isPrimitive('hello') // true
+* isPrimitive(42)      // true
+* isPrimitive(null)    // true
+* isPrimitive({})      // false
+* isPrimitive([])      // false
+* ```
+*/
+declare function isPrimitive(value: unknown): boolean;
+export = isPrimitive;

package/dist/isPrimitive.d.ts

@@ -0,0 +1,19 @@
+//#region src/base/isPrimitive/index.d.ts
+/**
+* 判断值是否为原始类型
+*
+* 原始类型包括：`string` / `number` / `boolean` / `null` / `undefined` / `symbol` / `bigint`
+*
+* @example
+* ```ts
+* import isPrimitive from '@tanwan/utils/isPrimitive'
+* isPrimitive('hello') // true
+* isPrimitive(42)      // true
+* isPrimitive(null)    // true
+* isPrimitive({})      // false
+* isPrimitive([])      // false
+* ```
+*/
+declare function isPrimitive(value: unknown): boolean;
+//#endregion
+export { isPrimitive as default };

package/dist/isPrimitive.js

@@ -0,0 +1,21 @@
+//#region src/base/isPrimitive/index.ts
+/**
+* 判断值是否为原始类型
+*
+* 原始类型包括：`string` / `number` / `boolean` / `null` / `undefined` / `symbol` / `bigint`
+*
+* @example
+* ```ts
+* import isPrimitive from '@tanwan/utils/isPrimitive'
+* isPrimitive('hello') // true
+* isPrimitive(42)      // true
+* isPrimitive(null)    // true
+* isPrimitive({})      // false
+* isPrimitive([])      // false
+* ```
+*/
+function isPrimitive(value) {
+	return value === null || typeof value !== "object" && typeof value !== "function";
+}
+//#endregion
+export { isPrimitive as default };

package/dist/isPromise.cjs

@@ -0,0 +1,18 @@
+//#region src/base/isPromise/index.ts
+/**
+* 判断值是否为 Promise 实例
+*
+* @example
+* ```ts
+* import isPromise from '@tanwan/utils/isPromise'
+* isPromise(Promise.resolve()) // true
+* isPromise(new Promise(() => {})) // true
+* isPromise({ then: () => {} })    // false
+* isPromise(null)                  // false
+* ```
+*/
+function isPromise(value) {
+	return value instanceof Promise;
+}
+//#endregion
+module.exports = isPromise;

package/dist/isPromise.d.cts

@@ -0,0 +1,15 @@
+//#region src/base/isPromise/index.d.ts
+/**
+* 判断值是否为 Promise 实例
+*
+* @example
+* ```ts
+* import isPromise from '@tanwan/utils/isPromise'
+* isPromise(Promise.resolve()) // true
+* isPromise(new Promise(() => {})) // true
+* isPromise({ then: () => {} })    // false
+* isPromise(null)                  // false
+* ```
+*/
+declare function isPromise<T = unknown>(value: unknown): value is Promise<T>;
+export = isPromise;

package/dist/isPromise.d.ts

@@ -0,0 +1,16 @@
+//#region src/base/isPromise/index.d.ts
+/**
+* 判断值是否为 Promise 实例
+*
+* @example
+* ```ts
+* import isPromise from '@tanwan/utils/isPromise'
+* isPromise(Promise.resolve()) // true
+* isPromise(new Promise(() => {})) // true
+* isPromise({ then: () => {} })    // false
+* isPromise(null)                  // false
+* ```
+*/
+declare function isPromise<T = unknown>(value: unknown): value is Promise<T>;
+//#endregion
+export { isPromise as default };

package/dist/isPromise.js

@@ -0,0 +1,18 @@
+//#region src/base/isPromise/index.ts
+/**
+* 判断值是否为 Promise 实例
+*
+* @example
+* ```ts
+* import isPromise from '@tanwan/utils/isPromise'
+* isPromise(Promise.resolve()) // true
+* isPromise(new Promise(() => {})) // true
+* isPromise({ then: () => {} })    // false
+* isPromise(null)                  // false
+* ```
+*/
+function isPromise(value) {
+	return value instanceof Promise;
+}
+//#endregion
+export { isPromise as default };

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

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

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

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

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

@@ -13,5 +13,3 @@ function isString(v) {
 }
 //#endregion
 export { isString as default };
-
-//# sourceMappingURL=isString.js.map

package/dist/joinUrl.cjs

@@ -0,0 +1,25 @@
+//#region src/url/joinUrl/index.ts
+/**
+* 安全拼接 URL 片段，自动处理斜杠
+*
+* @param parts - URL 片段列表
+* @returns 拼接后的完整 URL
+*
+* @example
+* ```ts
+* import joinUrl from '@tanwan/utils/joinUrl'
+* joinUrl('https://api.example.com', 'users', '123')
+* // 'https://api.example.com/users/123'
+*
+* joinUrl('https://api.example.com/', '/users/', '/123/')
+* // 'https://api.example.com/users/123'
+* ```
+*/
+function joinUrl(...parts) {
+	return parts.map((part, i) => {
+		if (i === 0) return part.replace(/\/+$/, "");
+		return part.replace(/^\/+|\/+$/g, "");
+	}).filter(Boolean).join("/");
+}
+//#endregion
+module.exports = joinUrl;

package/dist/joinUrl.d.cts

@@ -0,0 +1,19 @@
+//#region src/url/joinUrl/index.d.ts
+/**
+* 安全拼接 URL 片段，自动处理斜杠
+*
+* @param parts - URL 片段列表
+* @returns 拼接后的完整 URL
+*
+* @example
+* ```ts
+* import joinUrl from '@tanwan/utils/joinUrl'
+* joinUrl('https://api.example.com', 'users', '123')
+* // 'https://api.example.com/users/123'
+*
+* joinUrl('https://api.example.com/', '/users/', '/123/')
+* // 'https://api.example.com/users/123'
+* ```
+*/
+declare function joinUrl(...parts: string[]): string;
+export = joinUrl;

package/dist/joinUrl.d.ts

@@ -0,0 +1,20 @@
+//#region src/url/joinUrl/index.d.ts
+/**
+* 安全拼接 URL 片段，自动处理斜杠
+*
+* @param parts - URL 片段列表
+* @returns 拼接后的完整 URL
+*
+* @example
+* ```ts
+* import joinUrl from '@tanwan/utils/joinUrl'
+* joinUrl('https://api.example.com', 'users', '123')
+* // 'https://api.example.com/users/123'
+*
+* joinUrl('https://api.example.com/', '/users/', '/123/')
+* // 'https://api.example.com/users/123'
+* ```
+*/
+declare function joinUrl(...parts: string[]): string;
+//#endregion
+export { joinUrl as default };

package/dist/joinUrl.js

@@ -0,0 +1,25 @@
+//#region src/url/joinUrl/index.ts
+/**
+* 安全拼接 URL 片段，自动处理斜杠
+*
+* @param parts - URL 片段列表
+* @returns 拼接后的完整 URL
+*
+* @example
+* ```ts
+* import joinUrl from '@tanwan/utils/joinUrl'
+* joinUrl('https://api.example.com', 'users', '123')
+* // 'https://api.example.com/users/123'
+*
+* joinUrl('https://api.example.com/', '/users/', '/123/')
+* // 'https://api.example.com/users/123'
+* ```
+*/
+function joinUrl(...parts) {
+	return parts.map((part, i) => {
+		if (i === 0) return part.replace(/\/+$/, "");
+		return part.replace(/^\/+|\/+$/g, "");
+	}).filter(Boolean).join("/");
+}
+//#endregion
+export { joinUrl as default };

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

@@ -3,5 +3,4 @@
 * 将字符串转换为短横线命名（kebab-case）
 */
 declare function kebabCase(str: string): string;
-export = kebabCase;
-//# sourceMappingURL=kebabCase.d.cts.map
+export = kebabCase;

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

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

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

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

package/dist/lazyLoadImages.cjs

@@ -0,0 +1,36 @@
+//#region src/dom/lazyLoadImages/index.ts
+/**
+* 为图片添加懒加载（IntersectionObserver）
+*
+* 图片需要有 `data-src` 属性存放真实 URL。加载时会替换到 `src`，并从 `data-src` 移除。
+*
+* @param selector - 图片选择器，默认 `'img[data-src]'`
+* @returns 清理函数（调用后取消懒加载）
+*
+* @example
+* ```ts
+* import lazyLoadImages from '@tanwan/utils/lazyLoadImages'
+* lazyLoadImages()
+* // 或指定选择器
+* lazyLoadImages('.lazy-img')
+* ```
+*/
+function lazyLoadImages(selector = "img[data-src]") {
+	const observer = new IntersectionObserver((entries) => {
+		for (const entry of entries) {
+			if (!entry.isIntersecting) continue;
+			const img = entry.target;
+			const src = img.dataset.src;
+			if (src) {
+				img.src = src;
+				delete img.dataset.src;
+			}
+			observer.unobserve(img);
+		}
+	}, { rootMargin: "100px" });
+	const images = document.querySelectorAll(selector);
+	for (const img of images) observer.observe(img);
+	return () => observer.disconnect();
+}
+//#endregion
+module.exports = lazyLoadImages;

package/dist/lazyLoadImages.d.cts

@@ -0,0 +1,19 @@
+//#region src/dom/lazyLoadImages/index.d.ts
+/**
+* 为图片添加懒加载（IntersectionObserver）
+*
+* 图片需要有 `data-src` 属性存放真实 URL。加载时会替换到 `src`，并从 `data-src` 移除。
+*
+* @param selector - 图片选择器，默认 `'img[data-src]'`
+* @returns 清理函数（调用后取消懒加载）
+*
+* @example
+* ```ts
+* import lazyLoadImages from '@tanwan/utils/lazyLoadImages'
+* lazyLoadImages()
+* // 或指定选择器
+* lazyLoadImages('.lazy-img')
+* ```
+*/
+declare function lazyLoadImages(selector?: string): () => void;
+export = lazyLoadImages;

package/dist/lazyLoadImages.d.ts

@@ -0,0 +1,20 @@
+//#region src/dom/lazyLoadImages/index.d.ts
+/**
+* 为图片添加懒加载（IntersectionObserver）
+*
+* 图片需要有 `data-src` 属性存放真实 URL。加载时会替换到 `src`，并从 `data-src` 移除。
+*
+* @param selector - 图片选择器，默认 `'img[data-src]'`
+* @returns 清理函数（调用后取消懒加载）
+*
+* @example
+* ```ts
+* import lazyLoadImages from '@tanwan/utils/lazyLoadImages'
+* lazyLoadImages()
+* // 或指定选择器
+* lazyLoadImages('.lazy-img')
+* ```
+*/
+declare function lazyLoadImages(selector?: string): () => void;
+//#endregion
+export { lazyLoadImages as default };