# utils

**Repository Path**: w__gdong/utils

## Basic Information

- **Project Name**: utils
- **Description**: 模仿lodash的一个工具库，可以用作自己项目中特殊的功能处理
- **Primary Language**: JavaScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-20
- **Last Updated**: 2025-05-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# utils-npm

![npm version](https://img.shields.io/npm/v/utils-npm)
![license](https://img.shields.io/npm/l/utils-npm)

Lodash风格的TypeScript工具库，提供常用的数据结构操作和类型工具

## 📦 安装

```bash
npm install utils-npm
```

## 功能模块

### 字符串处理

- `camelToKebab` 驼峰转短横线命名
- `truncate` 智能字符串截断
- `escapeHTML` HTML特殊字符转义
- `parseUrlParams` URL参数解析
- `stringifyUrlParams` URL参数序列化

```typescript
// URL参数处理示例
import { parseUrlParams, stringifyUrlParams } from 'utils-npm';

// 解析含数组参数的URL
const params = parseUrlParams('?ids=1&ids=2&name=Alice');
// 返回 { ids: ['1','2'], name: 'Alice' }

// 处理特殊字符
const query = stringifyUrlParams({
  q: 'vue&react',
  price: '100$',
  filters: ['new', 'hot']
});
// 生成 'q=vue%26react&price=100%24&filters=new&filters=hot'

// 复杂对象序列化
const searchParams = {
  page: 1,
  size: 10,
  sort: ['-createdAt', 'title'],
  query: 'typescript&nodejs'
};
stringifyUrlParams(searchParams);
// 输出 'page=1&size=10&sort=-createdAt&sort=title&query=typescript%26nodejs'
```

```typescript
import { escapeHTML } from 'utils-npm'

// 防止XSS攻击
const userInput = '<script>alert(1)</script>'
const safeHTML = escapeHTML(userInput)
// 输出 &lt;script&gt;alert(1)&lt;/script&gt;
```

### 类型判断

- `isEmpty` 空值检测
- `deepEqual` 深度对象比较

```typescript
import { isEmpty, deepEqual } from 'utils-npm'

// 空值检测
console.log(isEmpty({})) // true
console.log(isEmpty([1])) // false
console.log(isEmpty('')) // true

// 深度比较对象
const objA = { a: 1, b: { c: 2 } }
const objB = { a: 1, b: { c: 2 } }
console.log(deepEqual(objA, objB)) // true
```

### 对象操作

### deepClone

深度克隆对象，支持循环引用和特殊对象类型

```typescript
import { deepClone } from 'utils-npm'

const obj = { date: new Date(), arr: [1, { a: 2 }] }
const cloned = deepClone(obj)
```

### shallowClone

浅层克隆对象，保留嵌套引用

```typescript
import { shallowClone } from 'utils-npm'

const original = { a: 1, b: { c: 2 } }
const cloned = shallowClone(original)
```

### 函数工具

- `throttle` 节流函数
- `debounce` 防抖函数

## 注意事项

- 深拷贝支持：普通对象/数组/Date/RegExp
- 浅拷贝支持：对象/数组
- 循环引用深度限制：1000层（超过将抛出错误）

## Usage

### Throttle Example

```typescript
import { throttle } from '@utils/function'

const updatePosition = () => console.log('Updating...')
const throttledUpdate = throttle(updatePosition, 1000)

// 快速调用多次
window.addEventListener('scroll', () => {
  throttledUpdate()
})
```

### Debounce Example

```typescript
import { debounce } from '@utils/function'

const searchAPI = () => console.log('Searching...')
const debouncedSearch = debounce(searchAPI, 300)

// 输入框实时搜索
searchInput.addEventListener('input', debouncedSearch)

// 取消未执行的搜索
searchInput.addEventListener('blur', () => {
  debouncedSearch.cancel()
})
```

## 使用示例

```javascript
import { chunk } from 'utils-npm'

console.log(chunk([1, 2, 3, 4], 2)) // [[1,2], [3,4]]

// 新增函数示例
// 数组去重
const duplicatedArray = [1, 2, 2, 3, 4, 4, 5]
console.log(uniqueArray(duplicatedArray)) // [1,2,3,4,5]

// 对象属性过滤
const user = { name: 'Alice', age: 30, password: '123' }
console.log(filterObject(user, ['name', 'age'])) // {name: 'Alice', age: 30}

// 日期格式化
console.log(formatDate(new Date(), 'YYYY-MM-DD HH:mm')) // 2024-03-20 14:30

// URL解析
console.log(parseURL('https://example.com?page=1&size=10'))
// {protocol: 'https', host: 'example.com', query: {page: '1', size: '10'}}
```

## 功能列表

- 数组工具

  - chunk/compact
  - uniqueArray 数组去重
  - 数组遍历（基础/多维/树形）

- 对象工具

  - filterObject 属性过滤

- 日期工具

  - formatDate 日期格式化

- URL工具
  - parseURL URL参数解析

### 遍历功能示例

```ts
// 基础遍历
traverse([1, 2, 3], n => console.log(n))

// 多维数组遍历
traverseMultiDimensional([[1, [2, 3]], 4], (item, path) => {
  console.log(`元素 ${item} 路径：${path}`)
})

// 树形DFS遍历
const tree = {
  value: 'root',
  children: [{ value: 'A', children: [{ value: 'B' }] }, { value: 'C' }],
}
traverseTree(
  tree,
  node => {
    console.log(node.value)
  },
  'DFS',
)
// 输出顺序: root → A → B → C
```

- 更多工具函数持续开发中...

## 开发指南

```bash
npm test  # 运行单元测试
npm run build  # 构建生产包
```