allahjs-utils
一个功能丰富的 JavaScript/TypeScript 工具库，提供常用的工具函数，帮助开发者提高开发效率。
特性
- 🚀 TypeScript 支持 - 完整的类型定义
- 📦 模块化设计 - 支持按需导入
- 🌐 多环境支持 - 支持 Node.js 和浏览器环境
- 🧪 完整测试 - 高覆盖率的单元测试
- 📚 详细文档 - 完整的 API 文档和示例
安装
# 使用 pnpm
pnpm install @allahjs/utils
# 使用 npm
npm install @allahjs/utils
使用方法
完整导入
import * as utils from '@allahjs/utils';
// 使用字符串工具
const result = utils.capitalize('hello world'); // "Hello world"
按需导入
import { capitalize, formatDate, unique } from '@allahjs/utils';
const text = capitalize('hello'); // "Hello"
const date = formatDate(new Date(), 'YYYY-MM-DD'); // "2024-01-01"
const arr = unique([1, 2, 2, 3]); // [1, 2, 3]
分模块导入
import { capitalize, toCamelCase } from '@allahjs/utils/string';
import { unique, chunk } from '@allahjs/utils/array';
import { deepClone, merge } from '@allahjs/utils/object';
API 文档
请求工具 (Request)
封装了跨平台的 HTTP 请求，根据运行环境自动选择合适的请求库：
| 环境 | reqEnv 值 | 底层实现 |
|---|---|---|
| 浏览器 / Node.js（默认） | 'browser' | Axios |
| Fetch | 'fetch' | 原生 fetch API |
| React Native | 'rn' | 原生 fetch API |
| UniApp / 微信小程序 | 'uni' | uni.request（通过 Axios 适配器） |
import { request } from '@allahjs/utils';
// POST 请求（默认，使用 Axios）
const data = await request('/api/list', {
params: { pageNum: 1 },
manner: 'json'
});
// GET 请求
const detail = await request('/api/detail', {
method: 'get',
params: { id: 1 }
});
// 指定环境
await request('/api/data', { reqEnv: 'fetch' }); // 使用 fetch
await request('/api/data', { reqEnv: 'rn' }); // React Native
await request('/api/data', { reqEnv: 'uni' }); // UniApp
字符串工具 (String)
capitalize(str)- 首字母大写toCamelCase(str)- 转换为驼峰命名toKebabCase(str)- 转换为短横线命名toSnakeCase(str)- 转换为下划线命名truncate(str, length, suffix)- 截断字符串trim(str)- 移除两端空白randomString(length, chars)- 生成随机字符串
数组工具 (Array)
unique(arr)- 数组去重chunk(arr, size)- 数组分块flatten(arr, depth)- 数组扁平化shuffle(arr)- 数组洗牌intersection(arr1, arr2)- 求交集difference(arr1, arr2)- 求差集groupBy(arr, keyFn)- 数组分组
对象工具 (Object)
deepClone(obj)- 深拷贝merge(target, ...sources)- 合并对象get(obj, path, defaultValue)- 获取属性值set(obj, path, value)- 设置属性值unset(obj, path)- 删除属性paths(obj)- 获取所有路径
日期工具 (Date)
formatDate(date, format)- 格式化日期timeAgo(date)- 相对时间addTime(date, amount, unit)- 添加时间getDateRange(date, unit)- 获取日期范围isSameDay(date1, date2)- 判断同一天isLeapYear(year)- 判断闰年getDaysInMonth(year, month)- 获取月份天数
数字工具 (Number)
formatNumber(num, separator)- 格式化数字toFixed(num, digits)- 保留小数位random(min, max, integer)- 生成随机数clamp(num, min, max)- 限制范围mapRange(value, fromMin, fromMax, toMin, toMax)- 映射范围isEven(num)/isOdd(num)- 判断奇偶percentage(value, total, digits)- 计算百分比formatBytes(bytes, digits)- 格式化文件大小
验证工具 (Validation)
isEmail(email)- 验证邮箱isPhone(phone)- 验证手机号isIdCard(idCard)- 验证身份证isUrl(url)- 验证URLisIp(ip)- 验证IP地址passwordStrength(password, options)- 密码强度isBankCard(cardNumber)- 验证银行卡hasChinese(text)/isChineseOnly(text)- 中文验证
异步工具 (Async)
delay(ms)- 延迟执行withTimeout(promise, timeout)- 超时控制retry(fn, maxRetries, delayMs)- 重试机制concurrent(tasks, concurrency)- 并发控制debounce(fn, delay)- 防抖函数throttle(fn, interval)- 节流函数AsyncQueue- 异步队列类memoizeAsync(fn, keyFn, ttl)- 异步缓存
DOM 工具 (DOM)
$(selector, parent)/$$(selector, parent)- 元素查询addClass(element, className)- 添加CSS类removeClass(element, className)- 移除CSS类toggleClass(element, className)- 切换CSS类hasClass(element, className)- 检查CSS类setStyle(element, styles)- 设置样式getStyle(element, property)- 获取样式createElement(tagName, attributes, children)- 创建元素getElementPosition(element)- 获取位置isInViewport(element, threshold)- 检查是否在视口scrollToElement(element, options)- 滚动到元素copyToClipboard(text)- 复制到剪贴板observeResize(element, callback)- 监听大小变化
开发
# 安装依赖
pnpm install
# 开发模式（监听文件变化）
pnpm run dev
# 构建
pnpm run build
# 运行测试
pnpm run test
# 监听测试
pnpm run test:watch
# 代码检查
pnpm run lint
# 修复代码风格
pnpm run lint:fix
# 类型检查
pnpm run type-check
发布到 NPM
首次发布
-
检查当前 registry：
npm config get registry -
设置为 npm 官方源：
npm config set registry https://registry.npmjs.org/ -
登录 npm 账号：
npm login --registry=https://registry.npmjs.org/ -
验证登录状态：
npm whoami --registry=https://registry.npmjs.org/ -
测试发布（推荐先执行）：
pnpm run publish:dry -
正式发布：
pnpm run publish:npm
后续版本发布
-
更新版本号：
npm version patch # 修复版本 1.0.0 -> 1.0.1 npm version minor # 功能版本 1.0.0 -> 1.1.0 npm version major # 重大版本 1.0.0 -> 2.0.0 -
发布新版本：
pnpm run publish:npm
发布前自动执行
- 🧹 清理旧的构建文件
- 🔨 重新构建项目
- 🧪 运行所有测试
- ✅ 只有测试通过才能发布
注意事项
- 📝 如果平时使用淘宝镜像源，发布时必须切换到 npm 官方源
- 🔐 登录时需要输入 npm 用户名、密码和邮箱
- ✅ 发布完成后可以切换回常用的镜像源：
npm config set registry https://registry.npmmirror.com/
贡献
欢迎提交 Issue 和 Pull Request！
许可证
MIT License
更新日志
1.0.0
- 初始版本发布
- 包含字符串、数组、对象、日期、数字、验证、异步、DOM 等工具函数
本包通过 semantic-release 自动发布，提交信息请遵循 Conventional Commits 规范。