@snack-kit/lib 0.1.0 → 0.3.0

package/dist/types/utils.d.ts

@@ -0,0 +1,410 @@
+/**
+ * 类型检测工具
+ *
+ * 统一使用 Object.prototype.toString 确保跨环境准确性，
+ * 规避 typeof null === 'object' 等已知陷阱。
+ */
+/**
+ * 是否为数字（含可转换的字符串数字，如 '42'、'3.14'）
+ * @example IsNumber(42) // true
+ * @example IsNumber('42') // true
+ * @example IsNumber('abc') // false
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const IsNumber: (val: unknown) => boolean;
+/**
+ * 是否为严格数字类型（不含字符串数字）
+ * @example IsRealNumber(42) // true
+ * @example IsRealNumber('42') // false
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const IsRealNumber: (val: unknown) => val is number;
+/**
+ * 是否为字符串
+ * @example IsString('hello') // true
+ * @example IsString(new String('hello')) // true
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const IsString: (val: unknown) => val is string;
+/**
+ * 是否为布尔值
+ * @example IsBoolean(true) // true
+ * @example IsBoolean(1) // false
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const IsBoolean: (val: unknown) => val is boolean;
+/**
+ * 是否为数组
+ * @example IsArray([1, 2]) // true
+ * @example IsArray({}) // false
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3.5+ · Safari 4+ · Node.js 0.10+
+ */
+declare const IsArray: (val: unknown) => val is unknown[];
+/**
+ * 是否为函数
+ * @example IsFunction(() => {}) // true
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const IsFunction: (val: unknown) => val is (...args: unknown[]) => unknown;
+/**
+ * 是否为普通对象（排除 null 和数组）
+ * @example IsObject({}) // true
+ * @example IsObject([]) // false
+ * @example IsObject(null) // false
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const IsObject: (val: unknown) => val is Record<string, unknown>;
+/**
+ * 是否为空值（null / undefined / 空字符串）
+ * @example IsNull(null) // true
+ * @example IsNull(undefined) // true
+ * @example IsNull('') // true
+ * @example IsNull(0) // false
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const IsNull: (val: unknown) => boolean;
+/**
+ * 深度相等比较，支持对象和数组的递归比较。
+ *
+ * 注意：仅比较自身可枚举属性，不比较原型链上的属性。
+ * 不支持 Map、Set、Date、RegExp 等特殊对象的深度比较。
+ * @example IsEqual({ a: 1 }, { a: 1 }) // true
+ * @example IsEqual([1, 2], [1, 2]) // true
+ * @example IsEqual({ a: 1 }, { a: 2 }) // false
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const IsEqual: (a: unknown, b: unknown) => boolean;
+
+/**
+ * 输入校验工具 + 常用正则常量
+ */
+/**
+ * 常用正则规则常量，来源参考 any-rule（https://github.com/any86/any-rule）
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const REGEX: {
+    /** 手机号（宽松：13-19 开头） */
+    readonly phone: RegExp;
+    /** 手机号（严谨，基于工信部 2019 年最新公布号段） */
+    readonly strictPhone: RegExp;
+    /** 邮箱（符合 RFC 标准） */
+    readonly email: RegExp;
+    /** URL（支持 http / https / ftp） */
+    readonly url: RegExp;
+    /** IPv4 地址 */
+    readonly ipv4: RegExp;
+    /** 整数（含负数和零） */
+    readonly integer: RegExp;
+    /** 正整数（不含零） */
+    readonly positiveInteger: RegExp;
+    /** 二代身份证 */
+    readonly idcard: RegExp;
+    /** 日期（宽松，如 2022-9-1） */
+    readonly date: RegExp;
+    /** 16 进制颜色值 */
+    readonly color: RegExp;
+};
+/**
+ * 是否为合法邮箱地址
+ * @example IsEmail('user@example.com') // true
+ * @example IsEmail('invalid') // false
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const IsEmail: (val: string) => boolean;
+/**
+ * 是否为中国大陆手机号（宽松校验）
+ * @example IsPhone('13812345678') // true
+ * @example IsPhone('12345678901') // false
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const IsPhone: (val: string) => boolean;
+/**
+ * 是否为合法 URL
+ * @example IsUrl('https://example.com') // true
+ * @example IsUrl('not-a-url') // false
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const IsUrl: (val: string) => boolean;
+/**
+ * 是否为合法 IPv4 地址
+ * @example IsIpv4('192.168.1.1') // true
+ * @example IsIpv4('999.0.0.1') // false
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const IsIpv4: (val: string) => boolean;
+/**
+ * 是否为整数（含负数和零）
+ * @example IsInteger('42') // true
+ * @example IsInteger('-10') // true
+ * @example IsInteger('3.14') // false
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const IsInteger: (val: string) => boolean;
+/**
+ * 是否为正整数（不含零）
+ * @example IsPositiveInteger('1') // true
+ * @example IsPositiveInteger('0') // false
+ * @example IsPositiveInteger('-1') // false
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const IsPositiveInteger: (val: string) => boolean;
+
+/**
+ * 数组工具
+ */
+/**
+ * 数组去重（基于 Set，时间复杂度 O(n)）
+ * @example Unique([1, 2, 1, 3]) // [1, 2, 3]
+ * @remarks
+ * 浏览器兼容性：Chrome 38+ · Firefox 13+ · Safari 7.1+ · Node.js 0.12+
+ *
+ * 依赖 `Set`（ES2015）。
+ */
+declare const Unique: <T>(arr: T[]) => T[];
+/**
+ * 按对象指定 key 的值去重，保留首次出现的元素
+ * @param arr 待去重数组
+ * @param key 用于去重的对象属性名
+ * @example
+ * UniqueByKey([{ id: 1, name: 'a' }, { id: 1, name: 'b' }], 'id')
+ * // [{ id: 1, name: 'a' }]
+ * @remarks
+ * 浏览器兼容性：Chrome 38+ · Firefox 13+ · Safari 7.1+ · Node.js 0.12+
+ *
+ * 依赖 `Set`（ES2015）。
+ */
+declare const UniqueByKey: <T extends object>(arr: T[], key: keyof T) => T[];
+/**
+ * 差集：返回只在 arr 中存在、不在 other 中存在的元素（基于 Set，时间复杂度 O(n)）
+ * @param arr 基础数组
+ * @param other 比较数组
+ * @example Minus([1, 2, 3], [2, 3, 4]) // [1]
+ * @remarks
+ * 浏览器兼容性：Chrome 38+ · Firefox 13+ · Safari 7.1+ · Node.js 0.12+
+ *
+ * 依赖 `Set`（ES2015）。
+ */
+declare const Minus: <T>(arr: T[], other: T[]) => T[];
+
+/**
+ * 对象工具
+ */
+/**
+ * 深拷贝对象或数组。
+ *
+ * 优先使用原生 `structuredClone`（支持 Date、RegExp、Map、Set、循环引用等），
+ * 降级为 JSON 序列化（不支持 undefined、函数、循环引用）。
+ * @example DeepClone({ a: { b: 1 } }) // { a: { b: 1 } }（新对象）
+ * @remarks
+ * 浏览器兼容性：
+ * - `structuredClone`（优先）：Chrome 98+ · Firefox 94+ · Safari 15.4+ · Node.js 17.0+
+ * - JSON 降级（自动回退）：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ *
+ * 在不支持 `structuredClone` 的环境中自动降级为 `JSON.parse(JSON.stringify(obj))`，
+ * 降级时不支持 `undefined`、函数、`Date`、`RegExp`、循环引用。
+ */
+declare const DeepClone: <T>(obj: T) => T;
+/**
+ * 删除对象中值为 null 或 undefined 的属性，返回新对象（不修改原对象）。
+ *
+ * 注意：空字符串、false、0 等假值不会被删除。
+ * @example CleanObject({ a: 1, b: null, c: undefined }) // { a: 1 }
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const CleanObject: <T extends object>(obj: T) => Partial<T>;
+/**
+ * 按 key 列表提取对象子集，返回新对象（类型安全）。
+ * @example Pick({ a: 1, b: 2, c: 3 }, ['a', 'c']) // { a: 1, c: 3 }
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ */
+declare const Pick: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>;
+/**
+ * 排除指定 key 后返回新对象（类型安全）。
+ * @example Omit({ a: 1, b: 2, c: 3 }, ['b']) // { a: 1, c: 3 }
+ * @remarks
+ * 浏览器兼容性：Chrome 38+ · Firefox 13+ · Safari 7.1+ · Node.js 0.12+
+ *
+ * 依赖 `Set`（ES2015）。
+ */
+declare const Omit: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>;
+
+/**
+ * 函数工具
+ */
+/**
+ * 防抖：在最后一次调用后等待 delay 毫秒再执行（trailing edge）。
+ *
+ * 适合搜索输入、窗口 resize、表单提交等场景。
+ * @param fn 要防抖的函数
+ * @param delay 延迟毫秒数，默认 300ms
+ * @example
+ * const handleInput = Debounce((val: string) => search(val), 500)
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ *
+ * 依赖 `setTimeout` / `clearTimeout`，全平台支持。
+ */
+declare const Debounce: <T extends (...args: Parameters<T>) => ReturnType<T>>(fn: T, delay?: number) => ((...args: Parameters<T>) => void);
+/**
+ * 节流：在 delay 毫秒内最多执行一次（leading edge，时间戳实现）。
+ *
+ * 适合滚动监听、mousemove、高频点击等场景。
+ * @param fn 要节流的函数
+ * @param delay 节流间隔毫秒数，默认 50ms
+ * @example
+ * const handleScroll = Throttle(() => updatePosition(), 100)
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ *
+ * 依赖 `Date.now()`，无 `setTimeout` 悬空回调风险。
+ */
+declare const Throttle: <T extends (...args: Parameters<T>) => ReturnType<T>>(fn: T, delay?: number) => ((...args: Parameters<T>) => void);
+/**
+ * Promise 延迟：等待指定毫秒数后 resolve。
+ * @param ms 延迟毫秒数
+ * @example await Delay(1000) // 等待 1 秒
+ * @remarks
+ * 浏览器兼容性：Chrome 32+ · Firefox 29+ · Safari 8+ · Node.js 0.12+
+ *
+ * 依赖 `Promise`（ES2015）和 `setTimeout`。
+ */
+declare const Delay: (ms: number) => Promise<void>;
+
+/**
+ * 字符串 / UUID / URL 工具
+ */
+/**
+ * 生成标准 RFC 4122 v4 UUID。
+ *
+ * 优先使用 `crypto.randomUUID()`（现代浏览器 / Node.js 19+），
+ * 降级为基于 `crypto.getRandomValues` 的手动实现。
+ * @example UUID() // 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
+ * @remarks
+ * 浏览器兼容性：
+ * - `crypto.randomUUID()`（优先）：Chrome 92+ · Firefox 95+ · Safari 15.4+ · Node.js 19.0+
+ * - `crypto.getRandomValues` 降级：Chrome 11+ · Firefox 21+ · Safari 6.1+ · Node.js 15.0+
+ *
+ * Node.js 14.17+ 可通过 `import { randomUUID } from 'crypto'` 单独使用，
+ * 但全局 `crypto` 对象需 Node.js 15.0+ 才可用。
+ */
+declare const UUID: () => string;
+/**
+ * 从 URL 中获取指定查询参数的值，不存在则返回空字符串。
+ * @param name 参数名
+ * @param url 目标 URL，默认取 `window.location.href`
+ * @example GetURLParam('page', 'https://example.com?page=2&size=10') // '2'
+ * @remarks
+ * 浏览器兼容性：Chrome 49+ · Firefox 44+ · Safari 10.1+ · Node.js 10.0+
+ *
+ * 依赖 `URL` API 和 `URLSearchParams`（WHATWG URL Standard）。
+ * 若 URL 格式非法会静默返回空字符串。
+ */
+declare const GetURLParam: (name: string, url?: string) => string;
+/**
+ * 获取 URL 中所有查询参数，以键值对对象返回。
+ *
+ * 若同名参数出现多次，取最后一个值。
+ * @param url 目标 URL，默认取 `window.location.href`
+ * @example GetURLParams('https://example.com?a=1&b=2') // { a: '1', b: '2' }
+ * @remarks
+ * 浏览器兼容性：Chrome 49+ · Firefox 44+ · Safari 10.1+ · Node.js 10.0+
+ *
+ * 依赖 `URL` API 和 `URLSearchParams`（WHATWG URL Standard）。
+ * 若 URL 格式非法会静默返回空对象。
+ */
+declare const GetURLParams: (url?: string) => Record<string, string>;
+/**
+ * 将对象转换为 URL 查询字符串（以 `?` 开头）。
+ *
+ * 值为 null / undefined 的属性会被跳过，特殊字符自动编码。
+ * @example ObjectToQuery({ page: 1, size: 10 }) // '?page=1&size=10'
+ * @example ObjectToQuery({}) // ''
+ * @remarks
+ * 浏览器兼容性：Chrome 49+ · Firefox 44+ · Safari 10.1+ · Node.js 10.0+
+ *
+ * 依赖 `URLSearchParams`（WHATWG URL Standard）。
+ * 空格编码为 `+`（application/x-www-form-urlencoded 规范），
+ * 与 `encodeURIComponent` 的 `%20` 编码略有差异。
+ */
+declare const ObjectToQuery: (obj: Record<string, unknown>) => string;
+/**
+ * 将查询字符串解析为键值对对象。
+ *
+ * 支持以 `?` 开头或不以 `?` 开头的格式，自动解码编码字符。
+ * @example QueryToObject('?a=1&b=hello%20world') // { a: '1', b: 'hello world' }
+ * @remarks
+ * 浏览器兼容性：Chrome 49+ · Firefox 44+ · Safari 10.1+ · Node.js 10.0+
+ *
+ * 依赖 `URLSearchParams`（WHATWG URL Standard）。
+ */
+declare const QueryToObject: (query: string) => Record<string, string>;
+
+/**
+ * 时间日期工具
+ */
+/**
+ * 格式化日期时间。
+ *
+ * 支持占位符：`yyyy`（年）、`MM`（月）、`dd`（日）、`HH`（24 小时制小时）、`mm`（分钟）、`ss`（秒）。
+ * @param date 日期，默认当前时间，支持 Date 对象、日期字符串、时间戳
+ * @param format 格式字符串，默认 `'yyyy-MM-dd HH:mm:ss'`
+ * @example FormatDate(new Date('2024-01-05 09:05:03')) // '2024-01-05 09:05:03'
+ * @example FormatDate(new Date('2024-01-05'), 'yyyy/MM/dd') // '2024/01/05'
+ * @example FormatDate(new Date('2024-01-05'), 'yy-MM-dd') // '24-01-05'
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ *
+ * 依赖原生 `Date` API，全平台支持。
+ * 传入非法日期字符串时返回空字符串。
+ */
+declare const FormatDate: (date?: Date | string | number, format?: string) => string;
+/**
+ * 获取指定日期偏移 N 天后的日期字符串。
+ *
+ * 正数表示往后，负数表示往前。不修改传入的 Date 对象。
+ * @param date 基准日期，默认当前时间
+ * @param days 偏移天数（正数往后，负数往前）
+ * @param format 格式字符串，默认 `'yyyy-MM-dd HH:mm:ss'`
+ * @example GetDateOffset(new Date('2024-01-10'), 3, 'yyyy-MM-dd')  // '2024-01-13'
+ * @example GetDateOffset(new Date('2024-01-10'), -3, 'yyyy-MM-dd') // '2024-01-07'
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ *
+ * 依赖原生 `Date` API，全平台支持。
+ */
+declare const GetDateOffset: (date?: Date, days?: number, format?: string) => string;
+/**
+ * 获取指定日期当天的开始时间戳（00:00:00.000）和结束时间戳（23:59:59.999）。
+ * @param date 指定日期，默认当前时间
+ * @example GetDayRange(new Date('2024-01-05'))
+ * // { start: 1704384000000, end: 1704470399999 }
+ * @remarks
+ * 浏览器兼容性：Chrome 5+ · Firefox 3+ · Safari 4+ · Node.js 0.10+
+ *
+ * 依赖原生 `Date` API，全平台支持。
+ * 时间戳基于本地时区计算。
+ */
+declare const GetDayRange: (date?: Date) => {
+    start: number;
+    end: number;
+};
+
+export { CleanObject, Debounce, DeepClone, Delay, FormatDate, GetDateOffset, GetDayRange, GetURLParam, GetURLParams, IsArray, IsBoolean, IsEmail, IsEqual, IsFunction, IsInteger, IsIpv4, IsNull, IsNumber, IsObject, IsPhone, IsPositiveInteger, IsRealNumber, IsString, IsUrl, Minus, ObjectToQuery, Omit, Pick, QueryToObject, REGEX, Throttle, UUID, Unique, UniqueByKey };