npm package: @libeilong/func
Description: 一个在多项目中复用的通用工具函数集合，涵盖类型判断、对象处理、字符串与数字处理、随机工具、文件处理、时间与地理工具、错误与调试等常见场景。
Author: lblblong
Latest version: 0.34.4

# @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` 或 `undefined`
- `isNumber`：安全判断是否为数字
- `isClass`：判断传入是否为类构造器
- `isServer`：判断当前运行环境是否为服务端（SSR / Node）
- `isKeyOf`：类型安全地判断 key 是否属于某个对象类型

### 对象与数组工具

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

### 字符串与数字工具

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

### 随机与 ID 工具

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

### 时间与地理

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

### 文件与 Buffer 处理

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

### 错误与调试

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

### 装饰器

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

## 使用示例

### 基本导入方式

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

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

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

### 对象工具：`objectPick`

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

### 随机权重选择：`randomWeight`

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

### 文件转文本：`file2Text`

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

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

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

### 错误信息提取：`extractErrorMessage`

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

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

### 经纬度距离：`measureLnglatDistance`

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

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

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

### 执行时间装饰器：`executionTime`

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