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大小)

import { logger, capitalize, deepClone, addClass } from '@icoolaw/utils'

2. 按环境导入 (推荐)

// 只导入通用工具
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. 按功能模块导入 (最佳实践)

// 字符串工具
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 中正确导出

示例：添加数学工具

// 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, 格式化输出等