一个在多项目中复用的通用工具函数集合,涵盖类型判断、对象处理、字符串与数字处理、随机工具、文件处理、时间与地理工具、错误与调试等常见场景。
npm install @libeilong/func一个在多项目中复用的通用工具函数集合,涵盖类型判断、对象处理、字符串与数字处理、随机工具、文件处理、时间与地理工具、错误与调试等常见场景。
``bash`
pnpm add @libeilong/func或
npm install @libeilong/func或
yarn add @libeilong/func
> 本包声明了 dayjs 为 peerDependencies,部分与时间相关的工具可能依赖 dayjs。在使用这些工具时,请在你的项目中安装:`
>
> bash`
> pnpm add dayjs
>
以下只列出主要工具函数名称,方便快速浏览。详细实现可以直接查看源码(大多为纯函数,易于理解)。
- isNil / isNotNil:判断值是否为 null 或 undefinedisNumber
- :安全判断是否为数字isClass
- :判断传入是否为类构造器isServer
- :判断当前运行环境是否为服务端(SSR / Node)isKeyOf
- :类型安全地判断 key 是否属于某个对象类型
- objectKeys:带类型的 Object.keysobjectEntries
- :带类型的 Object.entriesobjectPick
- :从对象中按键名挑选子集insertBetweenElements
- :在数组元素之间插入分隔符transDict
- :简单的字典转换/映射辅助
- convertToPascalCase:将字符串转换为 PascalCaseensurePrefix
- :确保字符串带有指定前缀omitText
- :按长度省略文本,追加省略号toFixed
- :对数字做固定小数位格式化(带一些安全处理)toFullNumberString
- :将数字转换为完整字符串(避免科学计数法)formatSize
- :按 B / KB / MB / GB 等单位格式化字节大小
- randomNumber:生成指定区间随机数randomWeight
- :按权重随机选取元素randomElement
- :从数组中随机选择一个元素randomColor16
- :生成随机 16 进制颜色字符串uniqueIdForSession
- :在当前会话内生成全局唯一 ID
- getDateRangeStartingPoints:按天/周/月等范围生成起点时间(依赖 dayjs)measureLnglatDistance
- :测量两个经纬度之间的近似距离
- file2Text:浏览器环境中将 File/Blob 转换为文本file2Image
- :浏览器环境中将 File 转换为 HTMLImageElementbuffer2Text
- :Node/浏览器中将 ArrayBuffer / Buffer 转为字符串
- error2string:将各种 Error/未知异常安全地转为字符串extractErrorMessage
- :从异常对象中尽可能提取出人类可读的 messageprintStackTrace
- :辅助打印堆栈信息safeJsonParse
- :安全的 JSON 解析,避免直接抛错noPromise
- :将返回 Promise 的函数转换为 Node 风格回调或更易用形式sleep
- :延时等待(返回 Promise)
- executionTime:用于统计函数/方法执行时间的装饰器,方便简单埋点与性能调试
不建议一次性 import * as func,推荐按需导入,方便 Tree-Shaking:
`ts
import { isNil, objectPick, randomNumber } from '@libeilong/func'
if (!isNil(value)) {
// ...
}
`
`ts
import { objectPick } from '@libeilong/func'
const user = { id: 1, name: 'Jack', age: 18, password: '*' }
const safeUser = objectPick(user, ['id', 'name'])
// => { id: 1, name: 'Jack' }
`
`ts
import { randomWeight } from '@libeilong/func'
const list = [
{ value: 'A', weight: 1 },
{ value: 'B', weight: 3 },
{ value: 'C', weight: 6 },
]
const picked = randomWeight(list, (item) => item.weight)
// 返回其中一个元素,C 被选中的概率最高
`
`ts
import { file2Text } from '@libeilong/func'
async function handleFile(file: File) {
const text = await file2Text(file)
console.log(text)
}
`
> 注意:file2Text / file2Image 仅适用于浏览器环境。
`ts
import { extractErrorMessage } from '@libeilong/func'
try {
// ... 可能抛错的逻辑
} catch (err) {
console.error('请求失败:', extractErrorMessage(err))
}
`
`ts
import { measureLnglatDistance } from '@libeilong/func'
const distance = measureLnglatDistance(
{ lng: 116.397428, lat: 39.90923 },
{ lng: 121.473701, lat: 31.230416 },
)
console.log('北京到上海直线距离约(米):', distance)
`
`ts
import { executionTime } from '@libeilong/func'
class Demo {
@executionTime('Demo.fetchData')
async fetchData() {
// 模拟耗时操作
await new Promise((resolve) => setTimeout(resolve, 500))
}
}
const demo = new Demo()
demo.fetchData()
// 控制台会打印类似:Execution time of Demo.fetchData: 500ms
`
- 尽量按需导入需要的工具函数,这样更利于打包体积优化。
- 文件 / DOM 相关工具请仅在浏览器环境中使用;服务端(Node.js)中请留意环境判断(例如 isServer)。
- 大部分函数都是无副作用的纯函数,可以放心在单元测试和业务代码中复用。
本项目基于 MIT 协议开源,详见本包内的 LICENSE` 文件。