Module @iap/utils

@iap/utils

企业级共享工具函数库，提供类型守卫、格式化、日期时间、对象、异步、表单校验与事件订阅等零依赖工具函数。

所有 API 均为具名导出，支持 tree-shaking——只引入 formatMoney 时，validate、event 等模块不会被打包进来。

特性

类型守卫：isString、isNumber、isObject、isDefined 等运行时类型判断
格式化：金额千分位、K/M 缩写、CSS 类名合并
日期时间：格式化、时间戳转换、日期范围、过期判断
对象与数组：深拷贝、omit / pick、去重、JSON 安全解析
异步：sleep、防抖、节流、延迟 Promise、超时竞争
表单校验：Schema 驱动的通用校验 + 邮箱 / 银行卡 / 密码等专用校验器
事件订阅：轻量级 EventEmitter，单例由业务层按需 new
零外部依赖，完整 TypeScript 类型支持

安装

pnpm add @iap/utils

快速开始

import { debounce, formatMoney, validateEmail, EventEmitter } from '@iap/utils'

// 防抖
const onInput = debounce(() => search(), 300)

// 金额格式化
formatMoney(1234567.891)   // '1,234,567.89'

// 校验
validateEmail('a@b.com')   // true

// 事件（业务层自行创建实例）
const emitter = new EventEmitter()
const off = emitter.on('login', (user) => console.log(user))

API 参考

类型守卫（type-guards）

函数	说明
`isNull(value)`	是否为 `null` / `undefined`
`isEmptyString(value)`	是否为空字符串或纯空白字符串
`isNullOrEmpty(value)`	是否为 `null`、`undefined` 或空字符串
`isObject(value)`	是否为普通对象（排除 `null` 和数组）
`isArray(value)`	是否为数组
`isString(value)`	是否为字符串
`isNumber(value)`	是否为有效数字（排除 `NaN`）
`isFunction(value)`	是否为函数
`isDefined(value)`	是否已定义（非 `null` 且非 `undefined`）

格式化（format）

函数	说明
`formatMoney(money, toFixed?, prefix?)`	千分位金额格式化，默认保留 2 位小数
`formatNumberWithCommas(value)`	千分位 + 2 位小数，≥1000 万显示 M 后缀
`formatLargeNumber(num)`	K / M 缩写
`classNames(...args)`	合并 CSS 类名并过滤假值

日期时间（date）

函数	说明
`formatDateStr(date, pattern?)`	按占位符（yyyy/MM/dd/HH/mm/ss）格式化日期
`formatDateTime(date)`	格式化为 `'yyyy-MM-dd HH:mm:ss'`
`toTimestamp(date)`	转换为毫秒级时间戳
`daysDiff(from, to)`	两个日期相差的完整天数
`addDaysToDate(date, days)`	增加 N 天
`getStartOfDay(date)` / `getEndOfDay(date)`	当天开始 / 结束时间
`isExpired(date)`	是否早于当前时间
`getDateRange(start, to)`	区间内每一天的 `Date` 数组（含首尾）
`formatTimestampToDate(ts, showTime?)`	秒/毫秒时间戳自动识别并格式化

对象与数组（object）

函数	说明
`deepClone(obj)`	深拷贝（支持基本类型、`Date`、数组、普通对象）
`omit(obj, keys)`	排除指定键的浅拷贝
`pick(obj, keys)`	仅保留指定键
`toArray(value)`	单个值或数组统一转为数组
`parseJSON(str, fallback)`	JSON 安全解析，失败返回 `fallback`
`removeDuplicates(arr, prop)`	按属性去重，保留首次出现
`findMaxByProperty(arr, prop)`	属性值最大的元素

异步与定时（async）

函数	说明
`sleep(ms)`	暂停指定毫秒
`debounce(fn, delay)`	防抖
`throttle(fn, limit)`	节流
`createDeferred()`	延迟 Promise
`withTimeout(promise, ms)`	超时竞争
`noop()`	空操作函数

表单校验（validate）

函数	说明
`validateField(value, rule)`	按规则校验单个字段
`validateForm(values, schema)`	按 Schema 整体校验
`validateEmail(email)`	邮箱格式
`validateBankCard(cardCode)`	银行卡号（15/16 位纯数字）
`validateCashApp(account)`	CashApp cashtag
`validatePassword(password)`	密码（≥ 8 字符）
`validateZipCode(zipCode)`	邮政编码（4–10 字符）

事件订阅（event）

EventEmitter 类提供 on / off / emit / once / clear 方法。包内不创建单例，由业务层按需实例化：

const emitter = new EventEmitter()
emitter.on('ready', handler)
emitter.emit('ready', data)

DOM / 环境（dom）

函数	说明
`canUseDom`	是否为浏览器环境（常量）
`runOnClient(fn)`	仅客户端执行
`getWindow()` / `getDocument()`	SSR 安全获取 `window` / `document`

类型导出

import type {
    Deferred,          // 延迟 Promise 对象
    EventHandler,      // 事件处理函数
    Theme,             // 'light' | 'dark'
    ValidationRule,    // 字段校验规则
    ValidationSchema,  // 表单校验 Schema
    ValidationErrors,  // 校验错误结果
} from '@iap/utils'

Classes

EventEmitter

Interfaces

Deferred
ValidationRule

Type Aliases

EventHandler
Theme
ValidationErrors
ValidationSchema