open-index/open-npm huggingface dataset:
npm package: @icoolaw/utils
Description: Utility functions for icoolaw toolchain
Author: DeepSea
Latest version: 0.1.1

# Utils 目录结构说明

## 📁 目录结构

```
packages/utils/src/
├── browser/          # 浏览器环境专用工具
│   ├── dom/         # DOM 操作相关
│   ├── storage/     # 本地存储相关 (localStorage, sessionStorage)
│   ├── event/       # 事件处理相关
│   └── index.js     # 浏览器工具导出
├── node/            # Node.js 环境专用工具
│   ├── logger/      # 日志工具 (chalk, ora)
│   ├── fs/          # 文件系统操作
│   ├── process/     # 进程相关工具
│   └── index.js     # Node.js工具导出
├── shared/          # 通用工具 (浏览器和Node.js都可用)
│   ├── string/      # 字符串处理
│   ├── object/      # 对象操作
│   ├── array/       # 数组操作
│   ├── date/        # 日期处理
│   ├── math/        # 数学计算
│   ├── validation/  # 数据验证
│   └── index.js     # 通用工具导出
├── types/           # TypeScript 类型定义
└── index.js         # 主导出文件
```

## 📦 使用方式

### 1. 完整导入 (不推荐，会增加bundle大小)
```javascript
import { logger, capitalize, deepClone, addClass } from '@icoolaw/utils'
```

### 2. 按环境导入 (推荐)
```javascript
// 只导入通用工具
import { capitalize, deepClone, formatDate } from '@icoolaw/utils/shared'

// 只导入浏览器工具
import { addClass, removeClass, getStyle } from '@icoolaw/utils/browser'

// 只导入Node.js工具
import { logger } from '@icoolaw/utils/node'
```

### 3. 按功能模块导入 (最佳实践)
```javascript
// 字符串工具
import { capitalize, kebabCase, camelCase } from '@icoolaw/utils/shared/string'

// 对象工具
import { deepClone, deepMerge, get, set } from '@icoolaw/utils/shared/object'

// DOM工具
import { addClass, removeClass, toggleClass } from '@icoolaw/utils/browser/dom'

// 日志工具
import { logger, log, success, warn, error } from '@icoolaw/utils/node/logger'
```

## 🎯 设计原则

1. **环境分离**: 明确区分浏览器和Node.js环境的工具，避免环境冲突
2. **按需加载**: 支持细粒度的按需导入，减少bundle大小
3. **功能分类**: 按功能将工具分类到不同目录，便于管理和查找
4. **向后兼容**: 保持主导出文件的兼容性，现有代码无需修改

## 🔧 开发指南

### 添加新工具函数

1. **确定环境**: 判断工具函数适用的环境
   - `shared/`: 通用工具，不依赖特定环境
   - `browser/`: 浏览器专用，使用DOM API、Web API等
   - `node/`: Node.js专用，使用Node.js API、第三方Node包等

2. **选择分类**: 根据功能选择合适的分类目录
   - `string/`: 字符串处理
   - `object/`: 对象操作
   - `array/`: 数组操作
   - `date/`: 日期时间
   - `dom/`: DOM操作
   - `logger/`: 日志记录
   - 等等...

3. **添加函数**: 在对应目录的 `index.js` 中添加函数

4. **更新导出**: 确保在上级 `index.js` 中正确导出

### 示例：添加数学工具

```javascript
// 1. 创建 shared/math/index.js
export function add(a, b) {
  return a + b
}

export function multiply(a, b) {
  return a * b
}

// 2. 更新 shared/index.js
export * from './math/index.js'

// 3. 使用
import { add, multiply } from '@icoolaw/utils/shared/math'
```

## 📋 当前工具清单

### Shared (通用工具)
- **string**: capitalize, kebabCase, camelCase, randomString, truncate
- **object**: deepClone, deepMerge, isObject, get, set
- **array**: unique, chunk, flatten, shuffle, groupBy, sum
- **date**: formatDate, timeAgo, isToday, getDateRange, addDays

### Browser (浏览器工具)
- **dom**: addClass, removeClass, toggleClass, hasClass, getStyle, setStyle, getRect, isInViewport

### Node.js (Node.js工具)
- **logger**: Logger类, 各种日志方法, spinner, 格式化输出等