@aoao-y33/utils 0.0.1 → 0.0.2

package/README.md

@@ -1,60 +1,253 @@
-## 功能特性
-
-- 🚀 轻量级工具函数集合
-- 📦 基于 TypeScript 编写，提供完整类型定义
-- 🌲 支持 Tree Shaking，按需加载
-- 🧪 包含单元测试
-
-## 使用方法
-
-### 导入方式
-
-````javascript 
-// 全量导入 
-import * as utils from '@aoaoy33/utils'
-// 按需导入（推荐） 
-import {  } from '@aoaoy33/utils'
-````
-
-## API 文档
-
-### isObject(obj)
-
-判断传入的值是否为有效对象（非 null、非 undefined、非数组的纯对象）。
-
-**参数：**
-- `obj` (any) - 需要判断的值
-
-**返回值：**
-- `boolean` - 如果是有效对象返回 true，否则返回 false
-
-**示例：**
-
-```typescript
-isObject({}) // true 
-isObject({ a: 1 }) // true 
-isObject(null) // false 
-isObject(undefined) // false 
-isObject([]) // false 
-isObject([1, 2, 3]) // false 
-isObject('string') // false
-```
-
-### mergeDeep(source, target)
-
-深度合并两个对象，相同属性会以 target 为准进行覆盖。
-
-**参数：**
-- `source` (T) - 源对象
-- `target` (T | Partial<T>) - 目标对象
-
-**返回值：**
-- `T` - 合并后的新对象
-
-**示例：**
-```javascript
-const source = { a: 1, b: { c: 2, d: 3 } } 
-const target = { b: { c: 4 }, e: 5 }
-const result = mergeDeep(source, target) 
-console.log(result) // { a: 1, b: { c: 4, d: 3 }, e: 5 }
-```
+# @aoaoy33/utils
+
+> 一个基于 Vue 3 + TypeScript 的实用工具函数库，提供 HTTP 请求、对象操作、数组处理、类型定义、UI 工具和事件总线等功能。
+
+## ✨ 特性
+
+- 🎯 **TypeScript 支持**：完整的类型定义和智能提示
+- 🌐 **HTTP 请求封装**：基于 axios，支持拦截器链式处理
+- 🎨 **UI 工具**：主题切换、Element Plus 动态主题色生成
+- 🌳 **树形数据处理**：递归平展树形结构
+- 🔧 **类型工具**：Vue Emits 与 Props 类型转换
+- 📡 **事件总线**：基于 mitt 的轻量级发布/订阅
+- 🚀 **ESM Only**：纯 ES Module 格式，现代化打包
+
+## 📦 安装
+
+```bash
+pnpm add @aoaoy33/utils
+```
+或
+```bash
+npm install @aoaoy33/utils 
+yarn add @aoaoy33/utils
+```
+
+## 🚀 快速开始
+
+### 初始化配置
+```typescript
+ import { initConfig } from '@aoaoy33/utils'
+// 初始化全局配置 
+initConfig({ request: { baseUrl: 'https://api.example.com', timeout: 5000 } })
+```
+## 📖 API 文档
+
+### 配置管理 (config)
+
+#### `initConfig(config)`
+
+初始化工具模块的全局配置。
+
+```typescript
+import { initConfig } from '@aoaoy33/utils'
+initConfig({ request: { baseUrl: 'https://api.example.com', timeout: 5000 } })
+```
+
+---
+
+### HTTP 请求 (requestUtils)
+
+#### `get<T>(url, params?, config?)`
+
+发送 GET 请求。
+
+```typescript
+import { get } from '@aoaoy33/utils'
+interface User { id: number ,name: string }
+const user = await get<User>('/user/1', { id: 1 })
+```
+#### `post<T>(url, data?, config?)`
+
+发送 POST 请求。
+```typescript
+import { post } from '@aoaoy33/utils'
+const result = await post<{ success: boolean }>('/user', { name: 'John', age: 25 })
+```
+
+#### `addInterceptors(type, interceptor)`
+
+添加请求/响应拦截器。
+
+```typescript
+import { addInterceptors } from '@aoaoy33/utils'
+// 请求拦截器 - 添加认证 token 
+addInterceptors('requestSuccess', (config) => { 
+    const token = localStorage.getItem('token'); 
+    if (token) { 
+        config.headers.Authorization = `Bearer ${token}` } 
+    return config 
+})
+// 响应拦截器 - 统一错误处理 
+addInterceptors('responseError', (error) => { 
+    if (error.response?.status === 401) { // 跳转到登录页 
+         router.push('/login') } 
+         return error 
+})
+// 响应成功拦截器 - 数据转换 
+addInterceptors('responseSuccess', (response) => { 
+    console.log('API Response:', response.data) 
+    return response 
+})
+```
+
+---
+
+### 对象工具 (objectUtils)
+
+#### `isObject(obj)`
+
+判断是否是有效对象（排除 null、undefined 和数组）。
+
+```typescript
+import { isObject } from '@aoaoy33/utils'
+isObject({}) // true 
+isObject({ key: 1 }) // true 
+isObject(null) // false 
+isObject([]) // false 
+isObject('string') // false
+```
+
+#### `mergeDeep(source, target)`
+
+深度合并两个对象，递归合并嵌套对象。
+
+```typescript
+import { mergeDeep } from '@aoaoy33/utils'
+const source = { a: 1, b: { c: 2, d: 3 }, e: 4 }
+const target = { b: { c: 10 }, e: 5 }
+const result = mergeDeep(source, target) // 返回: { a: 1, b: { c: 10, d: 3 }, e: 5 }
+```
+---
+
+### 数组工具 (arrayUtils)
+
+#### `flattenTree(treeData, childrenKey?)`
+
+将树形结构数组平展为一维数组。
+
+```typescript
+import {flattenTree} from '@aoaoy33/utils'
+
+const tree = [
+    {
+        id: 1,
+        name: '根节点',
+        children: [{id: 2, name: '子节点1'}, {id: 3, name: '子节点2', children: [{id: 4, name: '孙节点'}]}]
+    }]
+const flat = flattenTree(tree) // 返回: [ // { id: 1, name: '根节点', children: [...] }, // { id: 2, name: '子节点1' }, // { id: 3, name: '子节点2', children: [...] }, // { id: 4, name: '孙节点' } // ]
+// 使用自定义子节点键名 
+flattenTree(data, 'subItems')
+```
+
+---
+
+### UI 工具 (uiUtils)
+
+#### `changeMode(isDark)`
+
+切换页面亮色/暗色模式。
+```typescript
+import { changeMode } from '@aoaoy33/utils'
+// 切换到暗色模式 
+changeMode(true)
+// 切换到亮色模式 
+changeMode(false)
+```
+> **注意**：需要在 CSS 中定义 `.dark` 类的样式
+
+#### `changeElTheme(color?)`
+
+更改 Element Plus 主题颜色，自动生成完整的主题色系列。
+```typescript
+import { changeElTheme } from '@aoaoy33/utils'
+// 使用自定义主题色 
+changeElTheme('#67C23A')
+// 使用默认蓝色主题 
+changeElTheme()
+```
+生成的 CSS 变量：
+- `--el-color-primary`: 主色调
+- `--el-color-primary-light-3`: 主色调混合 20% 白色
+- `--el-color-primary-light-5`: 主色调混合 30% 白色
+- `--el-color-primary-light-7`: 主色调混合 40% 白色
+- `--el-color-primary-light-8`: 主色调混合 50% 白色
+- `--el-color-primary-light-9`: 主色调混合 60% 白色
+---
+
+### 类型工具 (typeUtils)
+
+#### `EmitsToEventProps<T>`
+
+将 Vue Emits 接口转换为事件 Props 类型。
+```typescript
+import type { EmitsToEventProps } from '@aoaoy33/utils'
+// 定义 emits 
+interface Emits { 
+    change: [value: string],
+    click: [id: number]
+}
+// 转换为 props 类型 
+type EventProps = EmitsToEventProps<Emits> // 等价于: // {  onChange?: (data: string) => void , onClick?: (data: number) => void }
+```
+#### `ExtractEmitsProps<T>`
+
+从 Vue 组件定义中提取事件 Props 类型。
+```typescript
+import type { ExtractEmitsProps } from '@aoaoy33/utils'
+const emits = defineEmits<{ update: [value: string], close: [] }>()
+type Props = ExtractEmitsProps<typeof emits> // 结果: { onUpdate?: (data: string) => void }
+```
+---
+
+### 事件总线 (busUtils)
+
+#### `bus`
+
+基于 mitt 的事件总线实例。
+
+```typescript
+import { bus } from '@aoaoy33/utils'
+// 监听事件 
+bus.on('message', (data) => { console.log('收到消息:', data) });
+// 触发事件 
+bus.emit('message', { text: 'Hello' });
+// 移除特定监听 
+const handler = (data) => console.log(data);
+bus.on('event', handler);
+bus.off('event', handler)
+// 清除所有监听 
+bus.all.clear()
+```
+
+---
+
+## 🛠️ 开发
+
+```bash
+#安装依赖
+pnpm install
+
+#构建生产版本
+pnpm run build
+```
+
+---
+
+## 📋 依赖
+
+### 运行时依赖
+- **axios** (^1.16.1): HTTP 客户端
+- **colord** (^2.9.3): 颜色处理库
+- **mitt** (^3.0.1): 事件发射器
+- **lodash** (^4.17.21): 工具函数库
+
+### 对等依赖
+- **vue** (^3.0.0): Vue.js 框架
+
+---
+
+## 📄 License
+
+MIT License © aoaoy33
+

package/dist/arrayUtils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 数组工具模块
+ *
+ * 提供常用的数组操作方法，包括树形结构的处理
+ */
+/**
+ * 平展树形对象
+ *
+ * 将嵌套的树形结构数组转换为扁平的一维数组
+ * 通过递归遍历所有子节点，保持父节点在前的顺序
+ *
+ * @template T - 树节点的类型
+ * @param treeData - 树形结构数组
+ * @param childrenKey - 子节点的键名，默认为 'children'
+ * @returns {T[]} 平展后的一维数组
+ *
+ * @example
+ * // 树形数据
+ * const tree = [
+ *   { id: 1, name: '根节点', children: [
+ *     { id: 2, name: '子节点1' },
+ *     { id: 3, name: '子节点2' }
+ *   ]}
+ * ]
+ *
+ * // 平展结果
+ * flattenTree(tree)
+ * // 返回: [
+ * //   { id: 1, name: '根节点', children: [...] },
+ * //   { id: 2, name: '子节点1' },
+ * //   { id: 3, name: '子节点2' }
+ * // ]
+ *
+ * @example
+ * // 使用自定义的子节点键名
+ * flattenTree(data, 'subItems')
+ */
+export declare const flattenTree: <T>(treeData: T[], childrenKey?: keyof T) => T[];
+//# sourceMappingURL=arrayUtils.d.ts.map

package/dist/arrayUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrayUtils.d.ts","sourceRoot":"","sources":["../src/arrayUtils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,WAAW,GAAE,CAAC,EAAE,UAAU,CAAC,EAAE,EAAC,cAAY,MAAM,CAAwB,KAAE,CAAC,EAKvF,CAAA"}

package/dist/busUtils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 事件总线工具模块
+ *
+ * 基于 mitt 实现的轻量级事件发布/订阅系统
+ * 用于组件间、模块间的解耦通信
+ */
+/**
+ * 全局事件总线实例
+ *
+ * 提供事件的发布（emit）和订阅（on/off）功能
+ * 适用于任意层级组件或模块之间的通信
+ *
+ * @example
+ * // 监听事件
+ * bus.on('message', (data) => {
+ *   console.log('收到消息:', data)
+ * })
+ *
+ * @example
+ * // 触发事件
+ * bus.emit('message', { text: 'Hello' })
+ *
+ * @example
+ * // 移除特定事件的监听
+ * const handler = (data) => console.log(data)
+ * bus.on('event', handler)
+ * bus.off('event', handler)
+ *
+ * @example
+ * // 移除所有事件监听
+ * bus.all.clear()
+ *
+ * @remarks
+ * - mitt 是一个极简的事件 emitter，体积仅 200b
+ * - 支持 TypeScript 类型推断
+ * - 建议在应用启动时定义好事件类型
+ */
+export declare const bus: import('mitt').Emitter<Record<import('mitt').EventType, unknown>>;
+//# sourceMappingURL=busUtils.d.ts.map

package/dist/busUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"busUtils.d.ts","sourceRoot":"","sources":["../src/busUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,GAAG,mEAAS,CAAA"}

package/dist/config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 工具模块配置
+ *
+ * 提供统一的配置初始化接口，用于设置工具模块的全局配置
+ */
+/**
+ * 工具配置接口
+ *
+ * 定义了整个工具模块的配置选项
+ */
+export interface UtilsConfig {
+    /** HTTP 请求相关配置 */
+    request: {
+        /** API 基础URL，例如：'https://api.example.com' */
+        baseUrl?: string;
+        /** 请求超时时间（毫秒），默认 3000ms */
+        timeout?: number;
+    };
+}
+/**
+ * 初始化工具配置
+ *
+ * 根据传入的配置对象初始化整个工具模块
+ * 目前主要用于初始化 HTTP 请求工具的 baseURL 和 timeout
+ *
+ * @param config - 工具配置对象
+ *
+ * @example
+ * // 初始化配置
+ * initConfig({
+ *   request: {
+ *     baseUrl: 'https://api.example.com',
+ *     timeout: 5000
+ *   }
+ * })
+ *
+ * @example
+ * // 使用默认配置
+ * initConfig({
+ *   request: {}
+ * })
+ */
+export declare const initConfig: (config: UtilsConfig) => void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,kBAAkB;IAClB,OAAO,EAAE;QACL,6CAA6C;QAC7C,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,2BAA2B;QAC3B,OAAO,CAAC,EAAE,MAAM,CAAA;KACnB,CAAA;CACJ;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,WAAW,SAE7C,CAAA"}

package/dist/index.d.ts

@@ -1,2 +1,20 @@
-export * from './object';
+/**
+ * Utils 工具库入口文件
+ *
+ * 统一导出所有工具模块，提供完整的工具函数集合：
+ * - config: 配置初始化
+ * - objectUtils: 对象操作工具
+ * - requestUtils: HTTP 请求工具
+ * - arrayUtils: 数组操作工具
+ * - typeUtils: TypeScript 类型工具
+ * - uiUtils: UI 界面工具
+ * - busUtils: 事件总线工具
+ */
+export * from './config';
+export * from './objectUtils';
+export * from './requestUtils';
+export * from './arrayUtils.ts';
+export * from './typeUtils.ts';
+export * from './uiUtils.ts';
+export * from './busUtils.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAA"}