mm_expand 1.8.9 → 1.9.1

package/README.md

@@ -5,41 +5,79 @@
 
 mm_expand是一个功能丰富的JavaScript工具库，为原生类型（String、Array、Number、Date等）提供全面的原型函数扩展，帮助开发者简化数据操作，提高代码效率和可维护性。
 
+## 项目介绍
+
+这个库通过扩展JavaScript原生对象的原型链，提供了丰富的数据操作方法，使开发者能够用更简洁的代码处理常见的数据操作任务。同时，它还包含了强大的事件系统、文件操作工具和对象处理功能，适用于各种JavaScript应用场景。
+
 ## 特点
 
-- 丰富的原生类型扩展方法
-- 简化文件系统操作
-- 强大的对象处理功能
-- 灵活的事件系统
-- 轻量级且高性能
-- 跨平台兼容
+- **原生类型扩展**：为String、Array、Number、Date等原生类型提供丰富的原型方法
+- **对象操作增强**：提供深度拷贝、对象合并、属性遍历等实用功能
+- **文件系统简化**：直观的文件读写、复制、删除等操作方法
+- **灵活事件系统**：支持命名空间、优先级、中间件、节流防抖等高级特性
+- **数据转换工具**：JSON、XML、URL参数等格式转换功能
+- **轻量高效**：核心功能轻量，性能优化良好
+- **跨平台兼容**：支持Node.js和现代浏览器环境
 
 ## 安装
 
 ```bash
+# 使用npm
 npm install mm_expand --save
+
+# 使用yarn
+yarn add mm_expand
+
+# 使用pnpm
+pnpm add mm_expand
 ```
 
 ## 快速开始
 
 ```javascript
-// 引入模块
+// 引入模块（CommonJS）
 const $ = require('mm_expand');
 
-// 使用字符串扩展方法
+// 基本用法示例
+
+// 字符串扩展方法
 const fullPath = 'test.json'.fullname(); // 获取完整路径
+const isFile = 'test.json'.isFile(); // 检查是否为文件
 
-// 使用数组扩展方法
+// 数组扩展方法
 const newArray = [1, 2, 3].copy(); // 复制数组
+const hasValue = [1, 2, 3].has(2); // 检查数组是否包含值
+
+// 数字扩展方法
+const roundedNum = 3.14159.toRound(2); // 四舍五入到2位小数
 
-// 使用日期扩展方法
+// 日期扩展方法
 const date = '2024-01-01'.toTime(); // 转换为Date对象
+const formattedDate = new Date().toStr('yyyy-MM-dd hh:mm:ss'); // 格式化日期
 
-// 使用事件系统
-$.eventer.on('event', (data) => {
-  console.log(data);
+// 对象操作
+const copiedObj = $.copy({ a: 1, b: { c: 2 } }); // 深度拷贝对象
+
+// 事件系统使用
+// 注册事件
+$.eventer.on('user:login', (userData) => {
+  console.log('User logged in:', userData);
+});
+
+// 触发事件
+const result = $.eventer.emit('user:login', { id: 1, name: '张三' });
+
+// 一次性事件
+$.eventer.once('app:init', () => {
+  console.log('Application initialized');
 });
-$.eventer.run('event', { message: 'Hello' });
+
+// 并行触发事件
+$.eventer.runParallel('data:process', { items: [...] });
+
+// 暂停和恢复事件
+$.eventer.pause('user:*'); // 暂停所有用户相关事件
+$.eventer.resume('user:*'); // 恢复所有用户相关事件
 ```
 
 ## API文档
@@ -308,33 +346,100 @@ await $.sleep(2000, obj, 'ok');
 ### 事件系统
 
 #### $.eventer
-- 描述：事件管理器实例
+- 描述：功能强大的事件管理器实例，支持命名空间、优先级、中间件等高级特性
 
-##### $.eventer.on(eventName, handler, key)
+##### 事件注册与移除
+
+##### $.eventer.on(eventName, handler, options)
 - 描述：注册事件监听器
 - 参数：
-  - eventName: 事件名称
+  - eventName: 事件名称（支持命名空间格式：namespace:event）
   - handler: 事件处理函数
-  - key: 事件处理器标识（可选）
+  - options: 配置选项（可选）
+    - key: 事件处理器标识
+    - priority: 优先级（数字，默认0，值越大优先级越高）
+- 返回值：当前Eventer实例（支持链式调用）
+
+##### $.eventer.once(eventName, handler, options)
+- 描述：注册一次性事件监听器（只触发一次后自动移除）
+- 参数：同$.eventer.on
+- 返回值：当前Eventer实例
 
-##### $.eventer.once(eventName, handler, key)
-- 描述：注册一次性事件监听器（只触发一次）
+##### $.eventer.off(eventName, key)
+- 描述：移除事件监听器
 - 参数：
   - eventName: 事件名称
-  - handler: 事件处理函数
-  - key: 事件处理器标识（可选）
+  - key: 要移除的处理器标识（可选，不提供则移除指定事件的所有处理器）
+- 返回值：当前Eventer实例
+
+##### 事件触发
 
 ##### $.eventer.run(eventName, ...args)
-- 描述：触发事件
+- 描述：触发事件（同步执行）
 - 参数：
   - eventName: 事件名称
   - ...args: 传递给事件处理器的参数
+- 返回值：包含执行结果和取消方法的对象 { results: [...], cancel: Function }
 
-##### $.eventer.del(eventName, key)
-- 描述：移除事件监听器
+##### $.eventer.runParallel(eventName, ...args)
+- 描述：并行触发事件
+- 参数：同$.eventer.run
+- 返回值：包含执行结果和取消方法的对象 { results: [...], cancel: Function }
+
+##### $.eventer.emit(eventName, ...args)
+- 描述：触发事件（别名，同run）
+- 参数：同$.eventer.run
+- 返回值：包含执行结果和取消方法的对象
+
+##### $.eventer.emitParallel(eventName, ...args)
+- 描述：并行触发事件（别名，同runParallel）
+- 参数：同$.eventer.runParallel
+- 返回值：包含执行结果和取消方法的对象
+
+##### 事件控制
+
+##### $.eventer.pause(key)
+- 描述：暂停指定事件
 - 参数：
-  - eventName: 事件名称
-  - key: 要移除的处理器标识（可选，不提供则移除所有）
+  - key: 事件名称（可选，不提供则暂停所有事件）
+- 返回值：当前Eventer实例
+
+##### $.eventer.resume(key)
+- 描述：恢复指定事件
+- 参数：
+  - key: 事件名称（可选，不提供则恢复所有事件）
+- 返回值：当前Eventer实例
+
+##### $.eventer.pauseAll()
+- 描述：全局暂停所有事件
+- 返回值：当前Eventer实例
+
+##### $.eventer.resumeAll()
+- 描述：全局恢复所有事件
+- 返回值：当前Eventer实例
+
+##### $.eventer.isPaused(key)
+- 描述：检查事件是否被暂停
+- 参数：
+  - key: 事件名称（可选，不提供则检查全局暂停状态）
+- 返回值：布尔值
+
+##### 事件管理
+
+##### $.eventer.clear(keepNamespaces)
+- 描述：清空所有事件监听器
+- 参数：
+  - keepNamespaces: 是否保留命名空间结构（布尔值，默认false）
+- 返回值：当前Eventer实例
+
+##### $.eventer.getMemoryReport()
+- 描述：获取内存使用报告
+- 返回值：包含事件统计信息的对象
+
+##### $.eventer.setMaxListeners(max)
+- 描述：设置最大监听器数量（防止内存泄漏警告）
+- 参数：
+  - max: 最大监听器数量
 
 ### 代码执行
 
@@ -372,23 +477,63 @@ await $.sleep(2000, obj, 'ok');
 2. **错误处理**：检查所有文件操作（saveText、saveJson等）的返回值，它们都返回布尔值表示成功/失败
 3. **异步操作**：对于需要等待的操作，如sleep、事件触发等，使用await/async语法
 4. **对象深拷贝**：使用`$.copy()`进行对象深拷贝，避免引用问题
-5. **事件管理**：使用$.eventer系统进行事件发布订阅，降低代码耦合度
-6. **性能优化**：处理大量数据时，优先使用异步方法避免阻塞主线程
+5. **事件管理**：
+   - 使用命名空间组织相关事件（如`user:login`, `user:logout`）
+   - 为长时间运行的事件处理添加取消机制
+   - 使用中间件进行事件处理前的通用逻辑
+6. **内存管理**：在不再需要时使用`off()`方法移除事件监听器，避免内存泄漏
+7. **性能优化**：
+   - 处理大量数据时，优先使用异步方法避免阻塞主线程
+   - 对频繁触发的事件使用节流或防抖功能
+8. **代码组织**：按功能模块组织代码，合理使用库的不同功能模块
+
+## 使用提示
+
+- **原型扩展说明**：该库通过扩展原生对象的原型链提供功能，在某些严格模式或特殊环境中可能需要特别注意
+- **模块导入**：在需要树摇（tree-shaking）的环境中，可以考虑导入特定的功能模块
+- **版本兼容**：每次更新版本前，请查看更新日志了解可能的API变化
+- **浏览器环境**：在浏览器环境中使用时，建议通过webpack、rollup等打包工具引入
+
+## 常见问题
+
+**Q: 原型扩展会影响其他库吗？**
+A: 我们的扩展方法都经过精心设计，避免与原生方法和常见库冲突。如果发现冲突，请及时提交Issue。
+
+**Q: 如何在浏览器中使用？**
+A: 通过打包工具（如webpack）打包后引入，或使用CDN服务（未来将支持）。
+
+**Q: 支持TypeScript吗？**
+A: 目前提供基本的JavaScript支持，TypeScript类型定义正在规划中。
 
 ## 兼容性
 
-- Node.js 10.x及以上版本
-- 支持所有现代浏览器（通过打包工具使用）
+- Node.js 12.x及以上版本（推荐使用LTS版本）
+- 支持所有现代浏览器（Chrome、Firefox、Safari、Edge等，需通过webpack、rollup等打包工具使用）
+- 与CommonJS和ESM模块系统兼容
 
 ## 贡献指南
 
-欢迎提交Issue和Pull Request！请确保您的代码遵循项目的编码规范。
+欢迎提交Issue和Pull Request！请确保您的代码遵循以下规范：
+
+1. 代码风格与现有项目保持一致
+2. 添加适当的注释和文档
+3. 编写测试用例确保功能正常
+4. 提交前运行测试确保没有引入新的问题
+
+## 更新日志
+
+详细的更新日志请查看项目的[Release页面](https://gitee.com/qiuwenwu91/mm_expand/releases)。
 
 ## 许可证
 
-[ISC License](LICENSE)
+本项目采用 [ISC License](LICENSE) 开源许可。
 
 ## 联系作者
 
-- GitHub: [https://github.com/](https://github.com/)
+- 作者：邱文武
 - Gitee: [https://gitee.com/qiuwenwu91/mm_expand](https://gitee.com/qiuwenwu91/mm_expand)
+- 项目Issues: [https://gitee.com/qiuwenwu91/mm_expand/issues](https://gitee.com/qiuwenwu91/mm_expand/issues)
+
+## 鸣谢
+
+感谢所有为该项目做出贡献的开发者和用户！