@alibarbar/common

Alibarbar 通用工具库

> 📋 查看 开发路线图 了解未来规划
> 🔧 查看 快速调试指南 开始本地调试

安装

``bash
npm install @alibarbar/common


或

yarn add @alibarbar/common

或

pnpm add @alibarbar/common
`

$3

如果使用 SecureStorage 的纯 JS RSA 加密功能（非 HTTPS 环境），需要额外安装 node-forge：

`bash
pnpm add node-forge
`

注意：如果在 Vite 项目中使用，请参考 Vite 配置说明 进行配置。

配置 npm 源

项目已配置使用淘宝镜像源（速度更快）。如需修改，请编辑 .npmrc 文件。

当前配置：registry=https://registry.npmmirror.com

切换源：
- 编辑 .npmrc 文件，取消注释你想要的源
- 或使用命令：npm config set registry <源地址>

发布到 npm：
发布时建议切换到官方源：
`bash
npm config set registry https://registry.npmjs.org/
npm publish
`

使用示例

$3

`typescript
import { capitalize, camelCase, kebabCase, truncate } from '@alibarbar/common';

capitalize('hello'); // 'Hello'
camelCase('hello-world'); // 'helloWorld'
kebabCase('helloWorld'); // 'hello-world'
truncate('hello world', 5); // 'he...'
`

$3

`typescript
import { unique, groupBy, chunk, flatten } from '@alibarbar/common';

unique([1, 2, 2, 3]); // [1, 2, 3]
groupBy([{type: 'a'}, {type: 'b'}], item => item.type);
chunk([1, 2, 3, 4], 2); // [[1, 2], [3, 4]]
flatten([1, [2, 3]], 1); // [1, 2, 3]
`

$3

`typescript
import { deepClone, merge, deepMerge, get } from '@alibarbar/common';

const cloned = deepClone(original);
const merged = merge({a: 1}, {b: 2});
const deep = deepMerge({a: {b: 1}}, {a: {c: 2}});
const value = get(obj, 'a.b.c', 'default');
`

$3

`typescript
import { formatDate, getRelativeTime, isToday } from '@alibarbar/common';

formatDate(new Date(), 'YYYY-MM-DD'); // '2024-01-01'
getRelativeTime(new Date(Date.now() - 3600000)); // '1小时前'
isToday(new Date()); // true
`

$3

`typescript
import { isValidEmail, isValidPhone, isValidUrl, isEmpty } from '@alibarbar/common';

isValidEmail('test@example.com'); // true
isValidPhone('13800138000'); // true
isValidUrl('https://example.com'); // true
isEmpty(''); // true
`

$3

`typescript
import { createUploader } from '@alibarbar/common';

const file = document.querySelector('input[type="file"]').files[0];

const uploader = createUploader(file, {
baseURL: 'https://api.example.com',
chunkSize: 2 1024 1024, // 2MB分片
concurrency: 3, // 并发上传3个分片
onProgress: (progress) => {
console.log(上传进度: ${progress.percentage}%);
},
onComplete: (result) => {
console.log('上传完成:', result.fileUrl);
},
onError: (error) => {
console.error('上传失败:', error);
},
});

// 开始上传
await uploader.upload();

// 暂停上传
uploader.pause();

// 恢复上传
await uploader.resume();

// 取消上传
await uploader.cancel();
`

$3

`typescript
import {
calculateFileMD5,
splitFileIntoChunks,
formatFileSize,
getFileExtension
} from '@alibarbar/common';

const md5 = await calculateFileMD5(file);
const chunks = splitFileIntoChunks(file, 2 1024 1024);
const size = formatFileSize(1024 * 1024); // '1 MB'
const ext = getFileExtension('file.pdf'); // 'pdf'
`

开发

$3

`bash
npm install
`

$3

`bash
npm run build
`

$3

`bash
npm run dev
`

$3

`bash
npm test
`

$3

`bash
npm run lint
npm run lint:fix
`

$3

`bash
npm run format
`

发布

$3

在发布前，需要配置私有 npm 仓库：

1. 配置 .npmrc 文件（项目根目录）：
`bash


设置作用域包的仓库

@alibarbar:registry=https://your-private-npm-registry.com

配置认证令牌（使用环境变量）

//your-private-npm-registry.com/:_authToken=${NPM_TOKEN}
`

2. 设置环境变量：
`bash
export NPM_TOKEN=your-auth-token
`

或者创建 .env 文件（记得添加到 .gitignore）：
`
NPM_TOKEN=your-auth-token
`

3. 登录到私有仓库（如果需要）：
`bash
npm login --registry=https://your-private-npm-registry.com


或


npm adduser --registry=https://your-private-npm-registry.com
`

$3

1. 更新版本号（遵循语义化版本）：
`bash
npm version patch # 补丁版本 1.0.0 -> 1.0.1
npm version minor # 次版本 1.0.0 -> 1.1.0
npm version major # 主版本 1.0.0 -> 2.0.0
`

2. 构建项目：npm run build
3. 运行测试：npm test
4. 发布到私有仓库：npm publish

$3

如果暂时不需要发布，可以注释掉 package.json 中的 publishConfig：
`json
// "publishConfig": {
// "registry": "https://your-private-npm-registry.com"
// }
`

📚 文档

- 最佳实践 - 使用建议和最佳实践
- 迁移指南 - 从其他库迁移的指南
- 常见问题 - 常见问题解答
- 性能对比 - 性能对比和优化建议
- 兼容性文档 - 浏览器和 Node.js 兼容性说明
- 本地调试指南 - 本地开发和调试方法
- 故障排除 - 常见问题和解决方案
- 开发路线图 - 项目开发计划和进度

目录结构

`
.
├── src/ # 源代码目录
│ ├── core/ # 核心工具
│ │ ├── string.ts # 字符串工具
│ │ ├── array.ts # 数组工具
│ │ ├── object.ts # 对象工具
│ │ ├── date.ts # 日期工具
│ │ └── validation.ts # 验证工具
│ ├── format/ # 格式化工具
│ │ ├── number.ts # 数字工具
│ │ ├── url.ts # URL工具
│ │ ├── color.ts # 颜色工具
│ │ └── i18n.ts # 国际化工具
│ ├── browser/ # 浏览器相关工具
│ │ ├── dom.ts # DOM工具
│ │ ├── storage.ts # 存储工具
│ │ ├── network.ts # 网络工具
│ │ ├── file.ts # 文件工具
│ │ └── upload.ts # 文件上传工具
│ ├── data/ # 数据处理工具
│ │ ├── transform.ts # 数据转换
│ │ ├── data-structure.ts # 数据结构
│ │ └── algorithm.ts # 算法工具
│ ├── helper/ # 实用工具
│ │ ├── performance.ts # 性能工具
│ │ ├── crypto.ts # 加密工具
│ │ └── tracking.ts # 埋点工具
│ ├── types/ # 类型定义
│ │ ├── index.ts
│ │ ├── upload.ts
│ │ └── utils.ts
│ ├── api/ # API文档
│ │ └── docs.json
│ └── index.ts # 入口文件
├── dist/ # 构建输出目录
├── coverage/ # 测试覆盖率报告
├── docs/ # 文档目录
│ ├── BEST_PRACTICES.md
│ ├── MIGRATION.md
│ ├── FAQ.md
│ └── PERFORMANCE.md
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── README.md
`

文件上传功能说明

$3

- ✅ 分片上传: 支持大文件分片上传，默认2MB每片
- ✅ 断点续传: 自动检测已上传分片，支持断点续传
- ✅ 并发控制: 可配置并发上传数量，默认3个
- ✅ 进度追踪: 实时获取上传进度
- ✅ 错误重试: 自动重试失败的分片，默认重试3次
- ✅ 暂停/恢复: 支持暂停和恢复上传
- ✅ 秒传支持: 如果文件已存在，直接返回文件URL

$3

文件上传功能使用以下API接口：

- POST /api/files/common/init - 初始化上传
- POST /api/files/common/chunk - 上传分片
- POST /api/files/common/complete/{taskId} - 完成上传
- GET /api/files/common/progress/{taskId} - 获取上传进度
- GET /api/files/common/chunks/{taskId} - 获取已上传分片列表
- POST /api/files/common/cancel/{taskId} - 取消上传

$3

1. MD5计算: 当前实现使用SHA-256作为简化方案，如需真正的MD5，建议使用 spark-md5 库
2. 浏览器兼容性: 需要支持 FileReader、FormData、fetch API
3. 认证: 如需认证，请在 headers` 选项中添加认证信息

开发路线图

查看 ROADMAP.md 了解详细的功能规划和开发计划。

$3

- ✅ 基础工具函数（字符串、数组、对象、日期、验证）
- ✅ 文件上传功能（分片上传、断点续传）
- 🔄 核心工具扩展（更多实用函数）
- 📋 新工具模块（数字、URL、存储、加密、网络、性能、DOM）
- 📋 测试覆盖率提升到 90%+

License

UNLICENSED - 私有项目