# fe-pro-utils

**Repository Path**: george_chen/fe-pro-utils

## Basic Information

- **Project Name**: fe-pro-utils
- **Description**: 一个现代化的 JavaScript/TypeScript 工具库，专为前端开发者设计，提供丰富、高效且类型安全的工具函数。
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-06
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# fe-pro-utils

## 介绍

一个现代化的 JavaScript/TypeScript 工具库，专为前端开发者设计，提供丰富、高效且类型安全的工具函数。

fe-pro-utils 遵循 MIT 开源协议发布，支持现代浏览器和 Node.js 运行环境。

## 特性

- 🚀 **多框架支持**: 与 Vue、React 等主流框架无缝集成
- 📦 **按需引入**: 支持 Tree Shaking，最小化打包体积
- 🛠 **TypeScript**: 完整的类型支持，提供优秀的开发体验
- ✅ **全面测试**: 完整的单元测试覆盖，保证代码质量
- 📖 **详尽文档**: 详细的中文文档和示例，快速上手
- 📝 **自动文档**: 基于 JSDoc 注释自动生成 API 文档，确保文档与代码同步
- 🔄 **模块化设计**: 以命名空间组织功能模块，便于维护和扩展
- 🌐 **跨平台兼容**: 支持浏览器和 Node.js 环境

## 安装

### 1. 通过包管理器安装（推荐）

```bash
# npm
npm install fe-pro-utils

# yarn
yarn add fe-pro-utils

# pnpm
pnpm add fe-pro-utils
```

### 2. 浏览器环境直接引入&全局变量形式使用

```html
<!-- 下载到本地引入 -->
<script src="path/to/fe-pro-utils/packages/core/dist/index.umd.js"></script>
<script type="module">
const fetchSomeData = async () => {
  try {
    // 模拟异步数据获取
    await new Promise(resolve => setTimeout(resolve, 1000));
    return { ready: true };
    // const response = await fetch('/api/latest-data');
    // return await response.json();
  } catch (error) {
    console.error('数据获取失败:', error);
    return { error: true, ready: false };
  }
};
// 全局变量形式使用
const status = await FeProUtils.others.polling({
  runCallback: async () => {
    const data = await fetchSomeData();
    return data.ready ? false : true;
  }
});
console.log('polling status: ', status);
</script>
```

### 3. Node.js 环境引入&使用

```javascript
// 方式一：ESM 环境中引入
import { others } from 'fe-pro-utils';
const status = await others.polling({
  runCallback: async () => {
    const data = await fetchSomeData();
    return data.ready ? false : true;
  }
});
console.log('polling status: ', status);

// 方式二：CommonJS 环境中引入
const FeProUtils = require('fe-pro-utils');
const status = await FeProUtils.others.polling({
  runCallback: async () => {
    const data = await fetchSomeData();
    return data.ready ? false : true;
  }
});
console.log('polling status: ', status);

// 模拟异步数据获取方法
async function fetchSomeData () {
  try {
    // 模拟异步数据获取
    await new Promise(resolve => setTimeout(resolve, 1000));
    return { ready: true };
    // const response = await fetch('/api/latest-data');
    // return await response.json();
  } catch (error) {
    console.error('数据获取失败:', error);
    return { error: true, ready: false };
  }
}
```

## 快速开始

### 基础使用示例

#### 全量引入使用示例

```javascript
import { others } from 'fe-pro-utils';
const fetchSomeData = async () => {
  try {
    // 模拟异步数据获取
    await new Promise(resolve => setTimeout(resolve, 1000));
    return { ready: true };
    // const response = await fetch('/api/latest-data');
    // return await response.json();
  } catch (error) {
    console.error('数据获取失败:', error);
    return { error: true, ready: false };
  }
};
const status = await others.polling({
  runCallback: async () => {
    const data = await fetchSomeData();
    return data.ready ? false : true;
  }
});
console.log('polling status: ', status);
```

#### 按需引入使用示例

```javascript
import { polling } from 'fe-pro-utils/others';
const fetchSomeData = async () => {
  try {
    // 模拟异步数据获取
    await new Promise(resolve => setTimeout(resolve, 1000));
    return { ready: true };
    // const response = await fetch('/api/latest-data');
    // return await response.json();
  } catch (error) {
    console.error('数据获取失败:', error);
    return { error: true, ready: false };
  }
};
const status = await polling({
  runCallback: async () => {
    const data = await fetchSomeData();
    return data.ready ? false : true;
  }
});
console.log('polling status: ', status);
```

### 在框架中使用示例

- [React 18 示例](https://gitee.com/george_chen/fe-pro-utils/blob/master/packages/examples/react-example/src/App.tsx)
- [Vue 2 示例](https://gitee.com/george_chen/fe-pro-utils/blob/master/packages/examples/vue2-example/src/App.vue)
- [Vue 3 示例](https://gitee.com/george_chen/fe-pro-utils/blob/master/packages/examples/vue3-example/src/App.vue)

为了开发调试方便，框架示例一律使用全量引入的方式，如需使用按需引入，参考"### 基础使用示例 - #### 按需引入使用示例"。

## 兼容性

fe-pro-utils 支持以下环境：

- 现代浏览器：Chrome、Firefox、Safari、Edge (最新版本)
- Node.js：18.x 及以上版本
- 构建工具：Webpack、Rollup、Vite 等

## 开发指南

### 环境要求

> 推荐使用 Node 版本 18.19.0 或以上，方便后续排查 Node 相关的问题
> 本项目使用 pnpm 进行依赖管理，请确保先安装 pnpm，推荐 pnpm 版本 9.0.0 或以上
> 注意：package.json 中的 engines 字段指定了项目需要的 Node 版本 >= 18.0.0，pnpm 版本 >= 9.0.0，请确保使用兼容的版本

### 开发步骤

```bash
# 1. 安装 pnpm（如果尚未安装）
npm install -g pnpm@9.0.0
# 如果太慢可以加上代理：
npm install -g pnpm@9.0.0 --registry=https://registry.npmmirror.com
# 查看 pnpm 版本
pnpm -v

# 2. 安装依赖
pnpm install

# 3. 运行 prepare 指令，安装husky
pnpm run prepare

# 4. 本地开发
pnpm run dev
# 开发服务器会监听文件变化，自动重新构建，并会生成最新的文件到 packages/core/dist 目录

# 5. 编写单元测试用例 packages/core/__tests__
# 运行单测用例
pnpm run test

# 6. 构建
# 先删除 packages/core/dist 目录，再执行构建
pnpm run build

# 7.1 修改 examples/react-example 项目，引入新增的工具函数并使用
cd packages/examples/react-example
# 安装依赖并确保使用本地最新的fe-pro-utils包
# （如有）先删除node_modules，然后重新安装依赖
pnpm install
# 运行开发服务器
pnpm run dev
# 访问 http://localhost:8081

# 7.2 修改 examples/vue2-example 项目，引入新增的工具函数并使用
cd packages/examples/vue2-example
# 安装依赖并确保使用本地最新的fe-pro-utils包
# （如有）先删除node_modules，然后重新安装依赖
pnpm install
# 运行开发服务器
pnpm run dev
# 访问 http://localhost:8082

# 7.3 修改 examples/vue3-example 项目，引入新增的工具函数并使用
cd packages/examples/vue3-example
# 安装依赖并确保使用本地最新的fe-pro-utils包
# （如有）先删除node_modules，然后重新安装依赖
pnpm install
# 运行开发服务器
pnpm run dev
# 访问 http://localhost:8083

# 8. 生成文档（默认生成所有文档）
pnpm run docs:generate
# 支持指定文件生成文档（注意：该指令也会更新packages/docs/api/index.md文件，所以最后还需要执行pnpm run docs:generate进行所有文档的生成）
pnpm run docs:generate -- packages/core/src/formatter/formatCurrency.ts

# 9. 本地预览文档
pnpm run docs:dev

# 10. 提交代码（见“贡献指南”）

# 11. 版本管理&发布NPM（见“发布NPM”和“版本管理”）

```

## 发布NPM

### 注意

- 发布前请确保所有变更都已提交到 Git 仓库，并且所有测试都已通过。

### 操作步骤

- 在命令行界面中，进入到包含您的npm包代码的项目文件夹，并运行以下命令来登录到npm账号：

```bash
pnpm login
```

- 输入您的npm账号凭据（用户名、密码和电子邮件），以登录到npm账号。

- 发布您的npm包：在项目根目录下运行以下命令，将您的npm包发布到npm registry：

```bash
# 没有指定版本，默认更新修订版本号(patch)
pnpm run release
```

- 确认发布：发布成功后，您可以在npm registry上查看并确认您的包已发布。

## 版本管理

- 本项目使用 [standard-version](https://github.com/conventional-changelog/standard-version) 来管理版本和生成 CHANGELOG.md 文件。standard-version 遵循语义化版本控制(SemVer)规范，采用 x.y.z 格式：
  - x 表示主版本号(major)，当您进行不兼容的 API 变更时，需要增加主版本号。
  - y 表示次版本号(minor)，当您添加了向下兼容的新功能时，需要增加次版本号。
  - z 表示修订版本号(patch)，当您进行向下兼容的问题修复时，需要增加修订版本号。
- 每次发布时，会自动更新版本号、生成 CHANGELOG.md 文件并提交到 Git 仓库。

### 相关命令

```bash
# 更新到大版本
pnpm run release -- --release-as major

# 更新到次版本
pnpm run release -- --release-as minor

# 更新到修订版本
pnpm run release -- --release-as patch

# 也可以指定具体版本号
pnpm run release -- --release-as 1.0.0
```

## 目录结构

```bash
fe-pro-utils/
├── packages/                # 项目主包目录
│   ├── core/                # 核心工具库
│   │   ├── src/             # 工具函数源代码目录
│   │   │   ├── ...          # 各工具函数模块目录
│   │   │   └── index.ts     # 主入口文件
│   │   ├── __tests__/       # 单元测试
│   │   ├──    └── ...
│   │   ├── dist/            # 构建输出目录
│   │   └── tsconfig.json    # TypeScript配置
│   ├── examples/            # 示例项目目录
│   │   ├── react-example/   # React示例项目
│   │   ├── vue2-example/    # Vue2示例项目
│   │   └── vue3-example/    # Vue3示例项目
│   └── docs/                # 文档网站
│       ├── api/             # API文档
│       ├── .vitepress/      # VitePress配置
│       └── index.md         # 文档首页
├── scripts/                 # 构建和文档脚本
├── .eslintignore            # ESLint忽略配置
├── .eslintrc.cjs            # ESLint配置
├── .gitignore               # Git忽略文件
├── .husky/                  # Git钩子配置
├── .npmrc                   # npm配置
├── .prettierignore          # Prettier忽略配置
├── .prettierrc.cjs          # Prettier配置
├── .versionrc.json          # standard-version配置
├── jest.config.js           # Jest测试配置
├── LICENSE                  # 许可证文件
├── package.json             # 项目配置
├── pnpm-lock.yaml           # pnpm依赖锁文件
├── tsconfig.json            # 根目录TypeScript配置
└── README.md                # 项目说明文档
```

## 许可证

本项目基于 MIT 许可证开源，你可以在遵守许可证条款的前提下自由使用、修改和分发本项目的代码。

## 贡献指南

我们非常欢迎社区贡献！如果你想参与项目开发，请按照以下步骤：

1. Fork 本仓库
2. 新建 feat_xxx 分支
3. 提交代码，推送到分支 (`git push origin feat_xxx`)
4. 新建 Pull Request

### 开发规范

- 代码风格：遵循项目的 ESLint 和 Prettier 配置
- 测试要求：为新功能添加单元测试
- 文档要求：更新相关文档和注释
- 提交信息：使用语义化的提交消息格式

## 联系方式

如有问题或建议，欢迎通过以下方式联系：

- Gitee Issues: https://gitee.com/george_chen/fe-pro-utils/issues
- Email: chenchaozhibuaa@163.com