mirror of https://github.com/allinssl/allinssl
275 lines
6.0 KiB
Markdown
275 lines
6.0 KiB
Markdown
# 数据处理工具函数文档
|
||
|
||
这个模块提供了一系列用于数据处理的实用工具函数。该模块使用 Ramda.js 进行函数式编程，并提供了完整的 TypeScript 类型支持。
|
||
|
||
## 目录
|
||
|
||
1. [数据转换](#数据转换)
|
||
2. [数据校验](#数据校验)
|
||
3. [数据过滤与重组](#数据过滤与重组)
|
||
4. [数据映射](#数据映射)
|
||
|
||
## 数据转换
|
||
|
||
### 对象值转字符串
|
||
|
||
```typescript
|
||
objectToString(obj: Record<string, any>): Record<string, string>
|
||
```
|
||
|
||
将对象的所有值转换为字符串。使用 Ramda.js 的 `map` 函数进行转换。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
objectToString({ age: 25, score: 98.5 }) // 返回: { age: "25", score: "98.5" }
|
||
```
|
||
|
||
### 数组转对象
|
||
|
||
```typescript
|
||
arrayToObject<T extends Record<string, any>>(key: string, array: T[]): Record<string, T>
|
||
```
|
||
|
||
将数组转换为对象，使用指定的 key 作为新对象的键。提供柯里化支持。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
const users = [
|
||
{ id: '1', name: 'Alice' },
|
||
{ id: '2', name: 'Bob' },
|
||
]
|
||
arrayToObject('id', users) // 返回: { '1': { id: '1', name: 'Alice' }, '2': { id: '2', name: 'Bob' } }
|
||
```
|
||
|
||
### 对象深度扁平化
|
||
|
||
```typescript
|
||
flattenObject<T extends Record<string, any>>(obj: T): Record<string, any>
|
||
```
|
||
|
||
将嵌套的对象结构扁平化，使用点号连接键名。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
const nested = {
|
||
user: {
|
||
info: {
|
||
name: 'Alice',
|
||
age: 25,
|
||
},
|
||
},
|
||
}
|
||
flattenObject(nested) // 返回: { 'user.info.name': 'Alice', 'user.info.age': 25 }
|
||
```
|
||
|
||
## 数据校验
|
||
|
||
### 正则匹配验证
|
||
|
||
```typescript
|
||
matchesPattern<T extends RegExp>(pattern: T, str: string): boolean
|
||
```
|
||
|
||
验证字符串是否符合指定的正则表达式模式。提供柯里化支持。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
const isEmail = matchesPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
|
||
isEmail('test@example.com') // 返回: true
|
||
```
|
||
|
||
### 必需键验证
|
||
|
||
```typescript
|
||
hasRequiredKeys<T extends Record<string, any>>(requiredKeys: string[], obj: T): boolean
|
||
```
|
||
|
||
验证对象是否包含所有指定的必需键。提供柯里化支持。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
const requiredFields = ['name', 'email']
|
||
hasRequiredKeys(requiredFields, { name: 'Alice', email: 'alice@example.com' }) // 返回: true
|
||
```
|
||
|
||
### 数值范围验证
|
||
|
||
```typescript
|
||
isInRange<T extends number>(min: T, max: T, value: T): boolean
|
||
```
|
||
|
||
验证数值是否在指定的范围内。提供柯里化支持。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
const isValidAge = isInRange(0, 120)
|
||
isValidAge(25) // 返回: true
|
||
```
|
||
|
||
## 数据过滤与重组
|
||
|
||
### 对象属性过滤
|
||
|
||
```typescript
|
||
filterObject<T extends Record<string, any>>(predicate: (value: any) => boolean, obj: T): Record<string, any>
|
||
```
|
||
|
||
根据条件函数过滤对象的属性。提供柯里化支持。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
const removeEmpty = filterObject((value) => value !== '')
|
||
removeEmpty({ name: 'Alice', title: '', age: 25 }) // 返回: { name: 'Alice', age: 25 }
|
||
```
|
||
|
||
### 数组分组
|
||
|
||
```typescript
|
||
groupByKey<T extends Record<string, any>>(key: string, array: T[]): Record<string, T[]>
|
||
```
|
||
|
||
按照指定的键对数组进行分组。提供柯里化支持。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
const users = [
|
||
{ role: 'admin', name: 'Alice' },
|
||
{ role: 'user', name: 'Bob' },
|
||
{ role: 'admin', name: 'Charlie' },
|
||
]
|
||
groupByKey('role', users)
|
||
// 返回: {
|
||
// admin: [{ role: 'admin', name: 'Alice' }, { role: 'admin', name: 'Charlie' }],
|
||
// user: [{ role: 'user', name: 'Bob' }]
|
||
// }
|
||
```
|
||
|
||
### 深层属性提取
|
||
|
||
```typescript
|
||
pluckDeep<T extends Record<string, any>>(path: string[], list: T[]): T[]
|
||
```
|
||
|
||
从对象数组中提取指定路径的值。提供柯里化支持。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
const users = [{ info: { name: 'Alice', age: 25 } }, { info: { name: 'Bob', age: 30 } }]
|
||
pluckDeep(['info', 'name'], users) // 返回: ['Alice', 'Bob']
|
||
```
|
||
|
||
### 数组扁平化去重
|
||
|
||
```typescript
|
||
flattenAndUniq<T>(array: T[]): T[]
|
||
```
|
||
|
||
对嵌套数组进行扁平化处理并去除重复元素。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
flattenAndUniq([
|
||
[1, 2],
|
||
[2, 3],
|
||
[3, 4],
|
||
]) // 返回: [1, 2, 3, 4]
|
||
```
|
||
|
||
## 数据映射
|
||
|
||
### 对象映射
|
||
|
||
```typescript
|
||
mapData(
|
||
mapper: [string, string][] | Record<string, string>,
|
||
data: Record<string, unknown> | Record<string, unknown>[],
|
||
options: MapperOption = { deep: true }
|
||
): Record<string, unknown> | Record<string, unknown>[]
|
||
```
|
||
|
||
根据映射表将对象或数组映射为新的数据结构。
|
||
|
||
参数：
|
||
|
||
- `mapper`: 映射表，可以是键值对数组或对象
|
||
- `data`: 要映射的数据，可以是对象或对象数组
|
||
- `options`: 映射选项
|
||
- `inherit`: 要继承的字段数组
|
||
- `deep`: 是否深度映射（默认 true）
|
||
- `ignore`: 要忽略的字段数组
|
||
|
||
特点：
|
||
|
||
- 支持深度映射
|
||
- 支持字段继承和忽略
|
||
- 支持嵌套路径映射
|
||
- 自动处理数组数据
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
const mapper = {
|
||
'user.name': 'userName',
|
||
'user.age': 'userAge',
|
||
}
|
||
const data = {
|
||
user: {
|
||
name: 'Alice',
|
||
age: 25,
|
||
},
|
||
}
|
||
mapData(mapper, data) // 返回: { userName: 'Alice', userAge: 25 }
|
||
|
||
// 使用继承选项
|
||
mapData(mapper, data, { inherit: ['user.name'] })
|
||
// 返回: { userName: 'Alice' }
|
||
|
||
// 使用忽略选项，或者在映射表中直接忽略，如果未启用
|
||
mapData(mapper, data, { ignore: ['user.age'] })
|
||
// 返回: { userName: 'Alice' }
|
||
```
|
||
|
||
### 生成映射表
|
||
|
||
```typescript
|
||
generateMapper(obj: Record<string, unknown>): [string, unknown][]
|
||
```
|
||
|
||
将对象的所有字段转换为小驼峰格式的映射表。
|
||
|
||
示例：
|
||
|
||
```typescript
|
||
const obj = {
|
||
user_name: 'name',
|
||
user_age: 'age',
|
||
}
|
||
generateMapper(obj) // 返回: [['userName', 'name'], ['userAge', 'age']]
|
||
```
|
||
|
||
## 特点
|
||
|
||
1. 使用 TypeScript 编写，提供完整的类型支持
|
||
2. 使用 Ramda.js 进行函数式编程
|
||
3. 所有函数都提供柯里化支持
|
||
4. 支持深层数据结构处理
|
||
5. 提供丰富的数据验证方法
|
||
|
||
## 注意事项
|
||
|
||
1. 所有函数都是纯函数，不会修改原始数据
|
||
2. 对象扁平化会处理所有层级的嵌套
|
||
3. 数组转对象时要确保指定的 key 在数组对象中存在
|
||
4. 数据映射的 inherit 和 ignore 选项不能同时使用
|
||
5. 映射表中的路径必须存在于源数据中
|