mm_expand 1.8.3 → 1.8.4

package/README.md

@@ -1,6 +1,6 @@
 # mm_expand
 
-这是超级美眉原型函数拓展模块，更有利于对string、array、object的操作，避免出错，简化业务逻辑。
+这是超级美眉原型函数拓展模块，为JavaScript原生类型（String、Array、Number、Date等）提供丰富的拓展方法，使开发者能够更便捷地操作数据，简化业务逻辑，提高开发效率。
 
 ## 安装
 
@@ -8,16 +8,30 @@
 npm install mm_expand
 ```
 
-## 基础函数
+## 使用方法
 
-### info(obj)
-- 描述：获取函数或对象的详细信息
+```javascript
+// 引入模块
+const $ = require('mm_expand');
+
+// 开始使用拓展方法
+console.log('test.json'.fullname());
+console.log([1, 2, 3].copy());
+console.log('2024-01-01'.toTime());
+```
+
+## 核心功能模块
+
+### 基础工具函数
+
+#### $.info(obj)
+- 描述：获取函数或对象的详细信息，用于调试和开发
 - 参数：
   - obj: 要查看的函数或对象
 - 返回值：返回对象的详细字符串表示
 
-### sleep(milliSeconds, obj, key)
-- 描述：延迟执行（休眠）函数
+#### $.sleep(milliSeconds, obj, key)
+- 描述：延迟执行（休眠）函数，返回Promise
 - 参数：
   - milliSeconds: 休眠的毫秒数
   - obj: 判断对象或函数（可选）
@@ -25,128 +39,284 @@ npm install mm_expand
 - 示例：
 ```javascript
 // 简单休眠
-sleep(2000);
+await $.sleep(2000);
 
 // 带条件的休眠
 var obj = {ok: false};
-sleep(2000, obj, 'ok');
+await $.sleep(2000, obj, 'ok');
 ```
 
-### as(obj, query, all)
-- 描述：判断对象是否相似
+#### $.as(obj, defaultValue)
+- 描述：当对象为null或undefined时返回默认值，否则返回原对象
 - 参数：
-  - obj: 被判断对象
-  - query: 用作判断的对象
-  - all: 是否要求完全相同
-- 返回值：相似返回true，否则返回false
+  - obj: 要检查的对象
+  - defaultValue: 当obj为null或undefined时的默认返回值
+- 返回值：obj不为null/undefined时返回obj，否则返回defaultValue
 
-### speed(func, times)
-- 描述：测试函数执行速度
+#### $.speed(func, times)
+- 描述：测试函数执行速度性能
 - 参数：
   - func: 要测试的函数
   - times: 测试次数，默认1000000次
 
-## 对象操作
+### 对象操作
 
-### push(objA, objB, bl)
-- 描述：添加对象属性
+#### $.push(objA, objB, bl)
+- 描述：合并对象属性
 - 参数：
   - objA: 被添加的对象
   - objB: 用作添加的对象
   - bl: 是否补充没有的对象
 - 返回值：合并后的新对象
 
-### clear(obj)
+#### $.clear(obj)
 - 描述：清空对象值
 - 参数：
   - obj: 要清空的对象
 - 返回值：返回清空后的对象
 
-### copy(obj, has)
-- 描述：拷贝对象
+#### $.copy(obj, has)
+- 描述：深度拷贝对象
 - 参数：
   - obj: 被拷贝的对象
   - has: 是否只拷贝非空值
-- 返回值：新对象
+- 返回值：新的拷贝对象
 
-### keys(obj, file)
-- 描述：查看对象所有属性
+#### $.keys(obj, file)
+- 描述：获取对象所有属性名
 - 参数：
   - obj: 要查看的对象
   - file: 保存结果的文件路径（可选）
 
-## 数据转换
+### 数据转换
 
-### toJson(obj, format)
-- 描述：将对象转为JSON字符串
+#### $.toJson(obj, format)
+- 描述：将对象转换为JSON字符串
 - 参数：
   - obj: 要转换的对象
-  - format: 是否格式化输出
+  - format: 是否格式化输出（缩进美化）
 - 返回值：JSON格式字符串
 
-### toXml(obj, format, mode)
-- 描述：将对象转为XML字符串
+#### $.toXml(obj, format, mode)
+- 描述：将对象转换为XML字符串
 - 参数：
   - obj: 要转换的对象
-  - format: 是否格式化输出
+  - format: 是否格式化输出（缩进美化）
   - mode: 是否使用属性格式
 - 返回值：XML格式字符串
 
-### toUrl(obj, url)
-- 描述：将对象转为URL参数字符串
+#### $.toUrl(obj, url)
+- 描述：将对象转换为URL参数字符串
 - 参数：
   - obj: 要转换的对象
   - url: 基础URL地址（可选）
 - 返回值：URL参数格式字符串
 
-## 文件操作
+### String原型拓展
+
+#### String.prototype.fullname()
+- 描述：获取文件的完整路径
+- 返回值：完整的文件路径字符串
+
+#### String.prototype.isFile()
+- 描述：检查路径是否为文件
+- 返回值：是文件返回true，否则返回false
+
+#### String.prototype.isDir()
+- 描述：检查路径是否为目录
+- 返回值：是目录返回true，否则返回false
+
+#### String.prototype.saveText(data, encode)
+- 描述：将字符串保存为文本文件
+- 参数：
+  - data: 要保存的数据
+  - encode: 编码格式，默认'utf8'
+- 返回值：保存成功返回true，失败返回false
+
+#### String.prototype.loadText(encode)
+- 描述：读取文件内容为字符串
+- 参数：
+  - encode: 编码格式，默认'utf8'
+- 返回值：文件内容字符串
+
+#### String.prototype.saveJson(data, encode)
+- 描述：将JSON对象保存为文件
+- 参数：
+  - data: 要保存的JSON数据
+  - encode: 编码格式，默认'utf8'
+- 返回值：保存成功返回true，失败返回false
+
+#### String.prototype.loadJson(encode)
+- 描述：读取JSON文件内容
+- 参数：
+  - encode: 编码格式，默认'utf8'
+- 返回值：解析后的JSON对象
+
+#### String.prototype.checkFormat(type)
+- 描述：检查字符串格式
+- 参数：
+  - type: 格式类型，如'idcard'(身份证)、'phone'(手机号)等
+- 返回值：格式正确返回true，否则返回false
+
+#### String.prototype.toTime(format)
+- 描述：将字符串转换为Date对象
+- 参数：
+  - format: 日期格式（可选）
+- 返回值：Date对象
+
+#### String.prototype.toTimestamp()
+- 描述：将日期字符串转换为时间戳
+- 返回值：时间戳数字
+
+### Array原型拓展
+
+#### Array.prototype.copy()
+- 描述：复制数组
+- 返回值：新的数组实例
+
+#### Array.prototype.clear()
+- 描述：清空数组内容
+- 返回值：空数组
+
+#### Array.prototype.to2D(cols)
+- 描述：将一维数组转换为二维数组
+- 参数：
+  - cols: 每行的列数
+- 返回值：二维数组
+
+#### Array.prototype.addVal(val)
+- 描述：向数组添加值（如果不存在）
+- 参数：
+  - val: 要添加的值
+- 返回值：添加后的数组
+
+#### Array.prototype.delVal(val)
+- 描述：从数组中删除指定值
+- 参数：
+  - val: 要删除的值
+- 返回值：删除后的数组
+
+#### Array.prototype.has(val)
+- 描述：检查数组是否包含指定值
+- 参数：
+  - val: 要检查的值
+- 返回值：包含返回true，否则返回false
+
+### Number原型拓展
 
-### File 类
+#### Number.prototype.toFloor(digits)
+- 描述：向下取整
+- 参数：
+  - digits: 小数位数（可选）
+- 返回值：取整后的数字
+
+#### Number.prototype.toCeil(digits)
+- 描述：向上取整
+- 参数：
+  - digits: 小数位数（可选）
+- 返回值：取整后的数字
 
-#### File.prototype.getAll(dir, keyword, keyword_dir)
-- 描述：搜索目录下所有文件
+#### Number.prototype.toRound(digits)
+- 描述：四舍五入
+- 参数：
+  - digits: 小数位数（可选）
+- 返回值：四舍五入后的数字
+
+#### Number.prototype.toTime()
+- 描述：将时间戳转换为Date对象
+- 返回值：Date对象
+
+#### Number.prototype.stamp()
+- 描述：获取当前时间戳
+- 返回值：时间戳数字
+
+### Date原型拓展
+
+#### Date.prototype.toStr(format)
+- 描述：将Date对象格式化为字符串
+- 参数：
+  - format: 日期格式字符串，如'yyyy-MM-dd hh:mm:ss'
+- 返回值：格式化后的日期字符串
+
+### 文件操作
+
+#### File 类
+
+##### File.prototype.getAll(dir, keyword, keyword_dir)
+- 描述：递归搜索目录下所有文件
 - 参数：
   - dir: 目录地址
-  - keyword: 文件搜索关键词
-  - keyword_dir: 目录搜索关键词
+  - keyword: 文件搜索关键词（可选）
+  - keyword_dir: 目录搜索关键词（可选）
 - 返回值：文件路径数组
 
-#### File.prototype.get(dir, keyword)
-- 描述：获取当前目录下所有文件
+##### File.prototype.get(dir, keyword)
+- 描述：获取当前目录下所有文件（不递归）
 - 参数：
   - dir: 目录地址
-  - keyword: 搜索关键词
+  - keyword: 搜索关键词（可选）
 - 返回值：文件路径数组
 
-#### File.prototype.load(file, encode)
+##### File.prototype.load(file, encode)
 - 描述：加载文件内容
 - 参数：
   - file: 文件路径
-  - encode: 编码方式
+  - encode: 编码方式，默认'utf8'
 - 返回值：文件内容字符串
 
-#### File.prototype.save(file, data, encode)
-- 描述：保存文件
+##### File.prototype.save(file, data, encode)
+- 描述：保存文件内容
 - 参数：
   - file: 文件路径
-  - data: 要保存的数据
-  - encode: 编码方式
+  - data: 要保存的数据内容
+  - encode: 编码方式，默认'utf8'
 - 返回值：保存成功返回true，否则返回false
 
-#### File.prototype.copy(sourcePath, targetPath)
+##### File.prototype.copy(sourcePath, targetPath)
 - 描述：复制文件
 - 参数：
   - sourcePath: 源文件路径
   - targetPath: 目标路径
 
-#### File.prototype.del(file)
+##### File.prototype.delete(file)
 - 描述：删除文件
 - 参数：
   - file: 要删除的文件路径
 
-## 代码执行
+### 事件系统
+
+#### $.eventer
+- 描述：事件管理器实例
+
+##### $.eventer.on(eventName, handler, key)
+- 描述：注册事件监听器
+- 参数：
+  - eventName: 事件名称
+  - handler: 事件处理函数
+  - key: 事件处理器标识（可选）
+
+##### $.eventer.once(eventName, handler, key)
+- 描述：注册一次性事件监听器（只触发一次）
+- 参数：
+  - eventName: 事件名称
+  - handler: 事件处理函数
+  - key: 事件处理器标识（可选）
+
+##### $.eventer.run(eventName, ...args)
+- 描述：触发事件
+- 参数：
+  - eventName: 事件名称
+  - ...args: 传递给事件处理器的参数
 
-### run_code(code, cm, em, qm, rm)
+##### $.eventer.del(eventName, key)
+- 描述：移除事件监听器
+- 参数：
+  - eventName: 事件名称
+  - key: 要移除的处理器标识（可选，不提供则移除所有）
+
+### 代码执行
+
+#### $.run_code(code, cm, em, qm, rm)
 - 描述：执行动态代码
 - 参数：
   - code: 要执行的代码字符串
@@ -156,11 +326,38 @@ sleep(2000, obj, 'ok');
   - rm: 结果参数
 - 返回值：执行结果
 
+## 模块加载与管理
+
+#### $.load(id, module)
+- 描述：加载模块
+- 参数：
+  - id: 模块ID
+  - module: 模块对象
+
+#### $.unload(id)
+- 描述：卸载模块
+- 参数：
+  - id: 模块ID
+
+#### $.reload(id)
+- 描述：重新加载模块
+- 参数：
+  - id: 模块ID
+
+## 最佳实践
+
+1. **文件路径处理**：使用`String.prototype.fullname()`获取完整路径，确保跨平台兼容性
+2. **错误处理**：所有文件操作（saveText、saveJson等）都返回布尔值表示成功/失败，建议检查返回值
+3. **异步操作**：对于需要等待的操作，如sleep、事件触发等，使用await/async语法
+4. **对象深拷贝**：使用`$.copy()`进行对象深拷贝，避免引用问题
+5. **事件管理**：使用$.eventer系统进行事件发布订阅，避免直接函数调用导致的耦合
+
 ## 注意事项
 
-1. 所有文件路径操作都支持跨平台，内部会自动处理路径分隔符。
-2. 文件操作相关函数建议增加错误处理。
-3. 在处理大量数据时，建议使用异步方式。
+1. 所有文件路径操作都支持跨平台，内部会自动处理路径分隔符
+2. 文件操作相关函数已添加错误处理，返回布尔值表示操作结果
+3. 在处理大量数据时，建议使用异步方式避免阻塞主线程
+4. 原型扩展可能与其他库冲突，使用时请注意命名空间隔离
 
 ## 许可证