@libeilong/func

一个在多项目中复用的通用工具函数集合，涵盖类型判断、对象处理、字符串与数字处理、随机工具、文件处理、时间与地理工具、错误与调试等常见场景。

安装

``bash
pnpm add @libeilong/func


或

npm install @libeilong/func

或

yarn add @libeilong/func
`

> 本包声明了 dayjs 为 peerDependencies，部分与时间相关的工具可能依赖 dayjs。在使用这些工具时，请在你的项目中安装：
>
> `bash
> pnpm add dayjs
> `

函数一览（按类别）

以下只列出主要工具函数名称，方便快速浏览。详细实现可以直接查看源码（大多为纯函数，易于理解）。

$3

- isNil / isNotNil：判断值是否为 null 或 undefined
- isNumber：安全判断是否为数字
- isClass：判断传入是否为类构造器
- isServer：判断当前运行环境是否为服务端（SSR / Node）
- isKeyOf：类型安全地判断 key 是否属于某个对象类型

$3

- objectKeys：带类型的 Object.keys
- objectEntries：带类型的 Object.entries
- objectPick：从对象中按键名挑选子集
- insertBetweenElements：在数组元素之间插入分隔符
- transDict：简单的字典转换/映射辅助

$3

- convertToPascalCase：将字符串转换为 PascalCase
- ensurePrefix：确保字符串带有指定前缀
- omitText：按长度省略文本，追加省略号
- toFixed：对数字做固定小数位格式化（带一些安全处理）
- toFullNumberString：将数字转换为完整字符串（避免科学计数法）
- formatSize：按 B / KB / MB / GB 等单位格式化字节大小

$3

- randomNumber：生成指定区间随机数
- randomWeight：按权重随机选取元素
- randomElement：从数组中随机选择一个元素
- randomColor16：生成随机 16 进制颜色字符串
- uniqueIdForSession：在当前会话内生成全局唯一 ID

$3

- getDateRangeStartingPoints：按天/周/月等范围生成起点时间（依赖 dayjs）
- measureLnglatDistance：测量两个经纬度之间的近似距离

$3

- file2Text：浏览器环境中将 File/Blob 转换为文本
- file2Image：浏览器环境中将 File 转换为 HTMLImageElement
- buffer2Text：Node/浏览器中将 ArrayBuffer / Buffer 转为字符串

$3

- error2string：将各种 Error/未知异常安全地转为字符串
- extractErrorMessage：从异常对象中尽可能提取出人类可读的 message
- printStackTrace：辅助打印堆栈信息
- safeJsonParse：安全的 JSON 解析，避免直接抛错
- noPromise：将返回 Promise 的函数转换为 Node 风格回调或更易用形式
- sleep：延时等待（返回 Promise）

$3

- executionTime：用于统计函数/方法执行时间的装饰器，方便简单埋点与性能调试

使用示例

$3

不建议一次性 import * as func，推荐按需导入，方便 Tree-Shaking：

`ts
import { isNil, objectPick, randomNumber } from '@libeilong/func'

if (!isNil(value)) {
// ...
}
`

$3

`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' }
`

$3

`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 被选中的概率最高
`

$3

`ts
import { file2Text } from '@libeilong/func'

async function handleFile(file: File) {
const text = await file2Text(file)
console.log(text)
}
`

> 注意：file2Text / file2Image 仅适用于浏览器环境。

$3

`ts
import { extractErrorMessage } from '@libeilong/func'

try {
// ... 可能抛错的逻辑
} catch (err) {
console.error('请求失败：', extractErrorMessage(err))
}
`

$3

`ts
import { measureLnglatDistance } from '@libeilong/func'

const distance = measureLnglatDistance(
{ lng: 116.397428, lat: 39.90923 },
{ lng: 121.473701, lat: 31.230416 },
)

console.log('北京到上海直线距离约（米）：', distance)
`

$3

`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` 文件。