fe-pro-utils
v0.0.21
Published
现代化 JavaScript 工具库
Maintainers
georgechenReadme
fe-pro-utils
介绍
一个现代化的 JavaScript/TypeScript 工具库，专为前端开发者设计，提供丰富、高效且类型安全的工具函数。
fe-pro-utils 遵循 MIT 开源协议发布，支持现代浏览器和 Node.js 运行环境。
特性
- 🚀 多框架支持: 与 Vue、React 等主流框架无缝集成
- 📦 按需引入: 支持 Tree Shaking，最小化打包体积
- 🛠 TypeScript: 完整的类型支持，提供优秀的开发体验
- ✅ 全面测试: 完整的单元测试覆盖，保证代码质量
- 📖 详尽文档: 详细的中文文档和示例，快速上手
- 📝 自动文档: 基于 JSDoc 注释自动生成 API 文档，确保文档与代码同步
- 🔄 模块化设计: 以命名空间组织功能模块，便于维护和扩展
- 🌐 跨平台兼容: 支持浏览器和 Node.js 环境
安装
1. 通过包管理器安装（推荐）
# npm
npm install fe-pro-utils
# yarn
yarn add fe-pro-utils
# pnpm
pnpm add fe-pro-utils2. 浏览器环境直接引入&全局变量形式使用
<!-- 下载到本地引入 -->
<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 环境引入&使用
// 方式一：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 };
}
}快速开始
基础使用示例
全量引入使用示例
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);按需引入使用示例
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);在框架中使用示例
为了开发调试方便，框架示例一律使用全量引入的方式，如需使用按需引入，参考"### 基础使用示例 - #### 按需引入使用示例"。
兼容性
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，请确保使用兼容的版本
开发步骤
# 1. 安装 pnpm（如果尚未安装）
npm install -g [email protected]
# 如果太慢可以加上代理：
npm install -g [email protected] --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账号：
pnpm login输入您的npm账号凭据（用户名、密码和电子邮件），以登录到npm账号。
发布您的npm包：在项目根目录下运行以下命令，将您的npm包发布到npm registry：
# 没有指定版本，默认更新修订版本号(patch)
pnpm run release- 确认发布：发布成功后，您可以在npm registry上查看并确认您的包已发布。
版本管理
- 本项目使用 standard-version 来管理版本和生成 CHANGELOG.md 文件。standard-version 遵循语义化版本控制(SemVer)规范，采用 x.y.z 格式：
- x 表示主版本号(major)，当您进行不兼容的 API 变更时，需要增加主版本号。
- y 表示次版本号(minor)，当您添加了向下兼容的新功能时，需要增加次版本号。
- z 表示修订版本号(patch)，当您进行向下兼容的问题修复时，需要增加修订版本号。
- 每次发布时，会自动更新版本号、生成 CHANGELOG.md 文件并提交到 Git 仓库。
相关命令
# 更新到大版本
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目录结构
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 许可证开源，你可以在遵守许可证条款的前提下自由使用、修改和分发本项目的代码。
贡献指南
我们非常欢迎社区贡献！如果你想参与项目开发，请按照以下步骤：
- Fork 本仓库
- 新建 feat_xxx 分支
- 提交代码，推送到分支 (
git push origin feat_xxx) - 新建 Pull Request
开发规范
- 代码风格：遵循项目的 ESLint 和 Prettier 配置
- 测试要求：为新功能添加单元测试
- 文档要求：更新相关文档和注释
- 提交信息：使用语义化的提交消息格式
联系方式
如有问题或建议，欢迎通过以下方式联系：
- Gitee Issues: https://gitee.com/george_chen/fe-pro-utils/issues
- Email: [email protected]