@alibarbar/common 1.0.0

package/README.md

@@ -0,0 +1,338 @@
+# @alibarbar/common
+
+Alibarbar 通用工具库
+
+> 📋 查看 [开发路线图](./ROADMAP.md) 了解未来规划  
+> 🔧 查看 [快速调试指南](./QUICK_START_DEBUG.md) 开始本地调试
+
+## 安装
+
+```bash
+npm install @alibarbar/common
+# 或
+yarn add @alibarbar/common
+# 或
+pnpm add @alibarbar/common
+```
+
+## 配置 npm 源
+
+项目已配置使用淘宝镜像源（速度更快）。如需修改，请编辑 `.npmrc` 文件。
+
+**当前配置**：`registry=https://registry.npmmirror.com`
+
+**切换源**：
+- 编辑 `.npmrc` 文件，取消注释你想要的源
+- 或使用命令：`npm config set registry <源地址>`
+
+**发布到 npm**：
+发布时建议切换到官方源：
+```bash
+npm config set registry https://registry.npmjs.org/
+npm publish
+```
+
+## 使用示例
+
+### 字符串工具
+
+```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...'
+```
+
+### 数组工具
+
+```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]
+```
+
+### 对象工具
+
+```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');
+```
+
+### 日期工具
+
+```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
+```
+
+### 验证工具
+
+```typescript
+import { isValidEmail, isValidPhone, isValidUrl, isEmpty } from '@alibarbar/common';
+
+isValidEmail('test@example.com'); // true
+isValidPhone('13800138000'); // true
+isValidUrl('https://example.com'); // true
+isEmpty(''); // true
+```
+
+### 文件上传（分片上传、断点续传）
+
+```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();
+```
+
+### 文件工具
+
+```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'
+```
+
+## 开发
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 构建
+
+```bash
+npm run build
+```
+
+### 开发模式（监听文件变化）
+
+```bash
+npm run dev
+```
+
+### 测试
+
+```bash
+npm test
+```
+
+### 代码检查
+
+```bash
+npm run lint
+npm run lint:fix
+```
+
+### 代码格式化
+
+```bash
+npm run format
+```
+
+## 发布
+
+### 配置私有 npm 仓库
+
+在发布前，需要配置私有 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
+```
+
+### 发布步骤
+
+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`
+
+### 临时禁用发布配置（仅开发阶段）
+
+如果暂时不需要发布，可以注释掉 `package.json` 中的 `publishConfig`：
+```json
+// "publishConfig": {
+//   "registry": "https://your-private-npm-registry.com"
+// }
+```
+
+## 📚 文档
+
+- [最佳实践](./docs/BEST_PRACTICES.md) - 使用建议和最佳实践
+- [迁移指南](./docs/MIGRATION.md) - 从其他库迁移的指南
+- [常见问题](./docs/FAQ.md) - 常见问题解答
+- [性能对比](./docs/PERFORMANCE.md) - 性能对比和优化建议
+- [兼容性文档](./docs/COMPATIBILITY.md) - 浏览器和 Node.js 兼容性说明
+- [本地调试指南](./docs/DEBUGGING.md) - 本地开发和调试方法
+- [开发路线图](./ROADMAP.md) - 项目开发计划和进度
+
+## 目录结构
+
+```
+.
+├── 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
+```
+
+## 文件上传功能说明
+
+### 特性
+
+- ✅ **分片上传**: 支持大文件分片上传，默认2MB每片
+- ✅ **断点续传**: 自动检测已上传分片，支持断点续传
+- ✅ **并发控制**: 可配置并发上传数量，默认3个
+- ✅ **进度追踪**: 实时获取上传进度
+- ✅ **错误重试**: 自动重试失败的分片，默认重试3次
+- ✅ **暂停/恢复**: 支持暂停和恢复上传
+- ✅ **秒传支持**: 如果文件已存在，直接返回文件URL
+
+### API接口
+
+文件上传功能使用以下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}` - 取消上传
+
+### 注意事项
+
+1. **MD5计算**: 当前实现使用SHA-256作为简化方案，如需真正的MD5，建议使用 `spark-md5` 库
+2. **浏览器兼容性**: 需要支持 `FileReader`、`FormData`、`fetch` API
+3. **认证**: 如需认证，请在 `headers` 选项中添加认证信息
+
+## 开发路线图
+
+查看 [ROADMAP.md](./ROADMAP.md) 了解详细的功能规划和开发计划。
+
+### 近期计划
+- ✅ 基础工具函数（字符串、数组、对象、日期、验证）
+- ✅ 文件上传功能（分片上传、断点续传）
+- 🔄 核心工具扩展（更多实用函数）
+- 📋 新工具模块（数字、URL、存储、加密、网络、性能、DOM）
+- 📋 测试覆盖率提升到 90%+
+
+## License
+
+UNLICENSED - 私有项目
+

package/dist/algorithm.d.mts

@@ -0,0 +1,66 @@
+/**
+ * 算法工具函数
+ */
+/**
+ * 二分查找
+ * @param array - 已排序的数组
+ * @param target - 目标值
+ * @param compareFn - 比较函数（可选）
+ * @returns 目标值的索引，如果未找到返回 -1
+ */
+declare function binarySearch<T>(array: T[], target: T, compareFn?: (a: T, b: T) => number): number;
+/**
+ * 快速排序
+ * @param array - 要排序的数组
+ * @param compareFn - 比较函数（可选）
+ * @returns 排序后的新数组
+ */
+declare function quickSort<T>(array: T[], compareFn?: (a: T, b: T) => number): T[];
+/**
+ * 归并排序
+ * @param array - 要排序的数组
+ * @param compareFn - 比较函数（可选）
+ * @returns 排序后的新数组
+ */
+declare function mergeSort<T>(array: T[], compareFn?: (a: T, b: T) => number): T[];
+/**
+ * 冒泡排序
+ * @param array - 要排序的数组
+ * @param compareFn - 比较函数（可选）
+ * @returns 排序后的新数组
+ */
+declare function bubbleSort<T>(array: T[], compareFn?: (a: T, b: T) => number): T[];
+/**
+ * 计算斐波那契数列的第n项
+ * @param n - 位置（从0开始）
+ * @returns 斐波那契数
+ */
+declare function fibonacci(n: number): number;
+/**
+ * 计算斐波那契数列（返回前n项）
+ * @param n - 项数
+ * @returns 斐波那契数列数组
+ */
+declare function fibonacciSequence(n: number): number[];
+/**
+ * 计算阶乘
+ * @param n - 非负整数
+ * @returns 阶乘结果
+ */
+declare function factorial(n: number): number;
+/**
+ * 计算最大公约数（GCD）
+ * @param a - 第一个数
+ * @param b - 第二个数
+ * @returns 最大公约数
+ */
+declare function gcd(a: number, b: number): number;
+/**
+ * 计算最小公倍数（LCM）
+ * @param a - 第一个数
+ * @param b - 第二个数
+ * @returns 最小公倍数
+ */
+declare function lcm(a: number, b: number): number;
+
+export { binarySearch, bubbleSort, factorial, fibonacci, fibonacciSequence, gcd, lcm, mergeSort, quickSort };

package/dist/algorithm.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 算法工具函数
+ */
+/**
+ * 二分查找
+ * @param array - 已排序的数组
+ * @param target - 目标值
+ * @param compareFn - 比较函数（可选）
+ * @returns 目标值的索引，如果未找到返回 -1
+ */
+declare function binarySearch<T>(array: T[], target: T, compareFn?: (a: T, b: T) => number): number;
+/**
+ * 快速排序
+ * @param array - 要排序的数组
+ * @param compareFn - 比较函数（可选）
+ * @returns 排序后的新数组
+ */
+declare function quickSort<T>(array: T[], compareFn?: (a: T, b: T) => number): T[];
+/**
+ * 归并排序
+ * @param array - 要排序的数组
+ * @param compareFn - 比较函数（可选）
+ * @returns 排序后的新数组
+ */
+declare function mergeSort<T>(array: T[], compareFn?: (a: T, b: T) => number): T[];
+/**
+ * 冒泡排序
+ * @param array - 要排序的数组
+ * @param compareFn - 比较函数（可选）
+ * @returns 排序后的新数组
+ */
+declare function bubbleSort<T>(array: T[], compareFn?: (a: T, b: T) => number): T[];
+/**
+ * 计算斐波那契数列的第n项
+ * @param n - 位置（从0开始）
+ * @returns 斐波那契数
+ */
+declare function fibonacci(n: number): number;
+/**
+ * 计算斐波那契数列（返回前n项）
+ * @param n - 项数
+ * @returns 斐波那契数列数组
+ */
+declare function fibonacciSequence(n: number): number[];
+/**
+ * 计算阶乘
+ * @param n - 非负整数
+ * @returns 阶乘结果
+ */
+declare function factorial(n: number): number;
+/**
+ * 计算最大公约数（GCD）
+ * @param a - 第一个数
+ * @param b - 第二个数
+ * @returns 最大公约数
+ */
+declare function gcd(a: number, b: number): number;
+/**
+ * 计算最小公倍数（LCM）
+ * @param a - 第一个数
+ * @param b - 第二个数
+ * @returns 最小公倍数
+ */
+declare function lcm(a: number, b: number): number;
+
+export { binarySearch, bubbleSort, factorial, fibonacci, fibonacciSequence, gcd, lcm, mergeSort, quickSort };

package/dist/algorithm.js

@@ -0,0 +1,44 @@
+'use strict';
+
+var chunkO3O67R4I_js = require('./chunk-O3O67R4I.js');
+
+
+
+Object.defineProperty(exports, "binarySearch", {
+  enumerable: true,
+  get: function () { return chunkO3O67R4I_js.binarySearch; }
+});
+Object.defineProperty(exports, "bubbleSort", {
+  enumerable: true,
+  get: function () { return chunkO3O67R4I_js.bubbleSort; }
+});
+Object.defineProperty(exports, "factorial", {
+  enumerable: true,
+  get: function () { return chunkO3O67R4I_js.factorial; }
+});
+Object.defineProperty(exports, "fibonacci", {
+  enumerable: true,
+  get: function () { return chunkO3O67R4I_js.fibonacci; }
+});
+Object.defineProperty(exports, "fibonacciSequence", {
+  enumerable: true,
+  get: function () { return chunkO3O67R4I_js.fibonacciSequence; }
+});
+Object.defineProperty(exports, "gcd", {
+  enumerable: true,
+  get: function () { return chunkO3O67R4I_js.gcd; }
+});
+Object.defineProperty(exports, "lcm", {
+  enumerable: true,
+  get: function () { return chunkO3O67R4I_js.lcm; }
+});
+Object.defineProperty(exports, "mergeSort", {
+  enumerable: true,
+  get: function () { return chunkO3O67R4I_js.mergeSort; }
+});
+Object.defineProperty(exports, "quickSort", {
+  enumerable: true,
+  get: function () { return chunkO3O67R4I_js.quickSort; }
+});
+//# sourceMappingURL=algorithm.js.map
+//# sourceMappingURL=algorithm.js.map

package/dist/algorithm.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"algorithm.js"}

package/dist/algorithm.mjs

@@ -0,0 +1,3 @@
+export { binarySearch, bubbleSort, factorial, fibonacci, fibonacciSequence, gcd, lcm, mergeSort, quickSort } from './chunk-JHZ7M2MR.mjs';
+//# sourceMappingURL=algorithm.mjs.map
+//# sourceMappingURL=algorithm.mjs.map

package/dist/algorithm.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"algorithm.mjs"}

package/dist/array.d.mts

@@ -0,0 +1,139 @@
+/**
+ * 数组工具函数
+ */
+/**
+ * 数组去重
+ * @param arr - 输入数组
+ * @returns 去重后的数组
+ */
+declare function unique<T>(arr: T[]): T[];
+/**
+ * 数组分组
+ * @param arr - 输入数组
+ * @param keyFn - 分组键函数或属性名
+ * @returns 分组后的对象
+ */
+declare function groupBy<T, K extends string | number>(arr: T[], keyFn: ((item: T) => K) | string): Record<K, T[]>;
+/**
+ * 数组分块
+ * @param arr - 输入数组
+ * @param size - 每块大小
+ * @returns 分块后的二维数组
+ */
+declare function chunk<T>(arr: T[], size: number): T[][];
+/**
+ * 数组扁平化
+ * @param arr - 输入数组
+ * @param depth - 扁平化深度，默认为 1
+ * @returns 扁平化后的数组
+ */
+declare function flatten<T>(arr: (T | T[])[], depth?: number): T[];
+/**
+ * 数组随机打乱（Fisher-Yates算法）
+ * @param arr - 输入数组
+ * @returns 打乱后的新数组
+ */
+declare function shuffle<T>(arr: T[]): T[];
+/**
+ * 随机取样
+ * @param arr - 输入数组
+ * @param count - 取样数量，默认为 1。当 count=1 时返回单个元素，否则返回数组
+ * @returns 随机取样的数组或单个元素
+ */
+declare function sample<T>(arr: T[]): T;
+declare function sample<T>(arr: T[], count: number): T | T[];
+/**
+ * 数组差集（在arr1中但不在arr2中的元素）
+ * @param arr1 - 第一个数组
+ * @param arr2 - 第二个数组
+ * @returns 差集数组
+ */
+declare function difference<T>(arr1: T[], arr2: T[]): T[];
+/**
+ * 数组交集
+ * @param arr1 - 第一个数组
+ * @param arr2 - 第二个数组
+ * @returns 交集数组
+ */
+declare function intersection<T>(arr1: T[], arr2: T[]): T[];
+/**
+ * 数组并集
+ * @param arr1 - 第一个数组
+ * @param arr2 - 第二个数组
+ * @returns 并集数组
+ */
+declare function union<T>(arr1: T[], arr2: T[]): T[];
+/**
+ * 按属性排序
+ * @param arr - 输入数组
+ * @param keyFn - 获取排序键的函数或属性名
+ * @param order - 排序顺序，'asc' 或 'desc'，默认为 'asc'
+ * @returns 排序后的新数组
+ */
+declare function sortBy<T, K extends string | number>(arr: T[], keyFn: ((item: T) => K) | string, order?: 'asc' | 'desc'): T[];
+/**
+ * 按条件查找索引
+ * @param arr - 输入数组
+ * @param predicate - 条件函数
+ * @returns 找到的索引，未找到返回 -1
+ */
+declare function findIndexBy<T>(arr: T[], predicate: (item: T) => boolean): number;
+/**
+ * 数组分割（满足条件/不满足条件）
+ * @param arr - 输入数组
+ * @param predicate - 条件函数
+ * @returns 包含两个数组的元组：[满足条件的数组, 不满足条件的数组]
+ */
+declare function partition<T>(arr: T[], predicate: (item: T) => boolean): [T[], T[]];
+/**
+ * 数组压缩（将多个数组合并成元组数组）
+ * @param arrays - 要压缩的数组
+ * @returns 压缩后的元组数组
+ */
+declare function zip<T extends readonly unknown[]>(...arrays: T): Array<{
+    [K in keyof T]: T[K] extends readonly (infer U)[] ? U : never;
+}>;
+/**
+ * 数组解压（将元组数组拆分成多个数组）
+ * @param array - 要解压的数组
+ * @returns 解压后的数组元组
+ */
+declare function unzip<T extends readonly unknown[]>(array: Array<{
+    [K in keyof T]: T[number] extends readonly (infer U)[] ? U : never;
+}>): T;
+/**
+ * 移除假值（null, undefined, false, 0, ''）
+ * @param arr - 输入数组
+ * @returns 移除假值后的数组
+ */
+declare function compact<T>(arr: (T | null | undefined | false | 0 | '')[]): T[];
+/**
+ * 取前N个元素
+ * @param arr - 输入数组
+ * @param n - 要取的元素数量
+ * @returns 前N个元素的数组
+ */
+declare function take<T>(arr: T[], n: number): T[];
+/**
+ * 跳过前N个元素
+ * @param arr - 输入数组
+ * @param n - 要跳过的元素数量
+ * @returns 跳过后的数组
+ */
+declare function drop<T>(arr: T[], n: number): T[];
+/**
+ * 条件取元素（直到条件不满足）
+ * @param arr - 输入数组
+ * @param predicate - 条件函数
+ * @returns 满足条件的连续元素数组
+ */
+declare function takeWhile<T>(arr: T[], predicate: (item: T) => boolean): T[];
+/**
+ * 条件跳过元素（直到条件不满足）
+ * @param arr - 输入数组
+ * @param predicate - 条件函数
+ * @returns 跳过后的数组
+ */
+declare function dropWhile<T>(arr: T[], predicate: (item: T) => boolean): T[];
+
+export { chunk, compact, difference, drop, dropWhile, findIndexBy, flatten, groupBy, intersection, partition, sample, shuffle, sortBy, take, takeWhile, union, unique, unzip, zip };