mm_machine 2.2.2 → 2.2.4

package/item.js

@@ -17,22 +17,64 @@ if (!$.tpl) {
 }
 
 /**
- * 增强require函数，支持热更新
- * @param {string} file 文件路径
- * @param {Function} func 回调函数
- * @returns {object} 加载的模块
+ * 增强require函数，专门用于脚本文件(.js)热重载
+ * 当脚本文件内容发生变化时，自动重新加载并触发回调
+ * @param {string} file 脚本文件路径(.js)
+ * @param {Function} func 热更新回调函数，文件变化时触发
+ * @returns {object} 加载的模块对象
+ * @throws {TypeError} 文件路径不是字符串或回调不是函数时抛出
+ * @example
+ * // 加载并监听脚本文件
+ * const module = $.require('./module.js', (newModule) => {
+ *   console.log('模块已重新加载');
+ * });
  */
 $.require = function (file, func) {
+  // 参数校验
+  if (typeof file !== 'string') {
+    throw new TypeError('文件路径必须是字符串');
+  }
+
+  if (func && typeof func !== 'function') {
+    throw new TypeError('回调函数必须是函数');
+  }
+
+  // 确保文件是.js文件
+  if (!file.endsWith('.js')) {
+    throw new TypeError('$.require 只能用于.js脚本文件');
+  }
+
   return $.mod.load(file, func);
 };
 
 /**
- * 增强JSON加载函数，支持热更新
- * @param {string} file 文件路径
- * @param {Function} func 回调函数
+ * 增强JSON加载函数，专门用于配置文件(.json)热重载
+ * 当配置文件内容发生变化时，自动重新加载并触发回调
+ * @param {string} file 配置文件路径(.json)
+ * @param {Function} func 热更新回调函数，文件变化时触发
  * @returns {object} 解析的JSON对象
+ * @throws {TypeError} 文件路径不是字符串或回调不是函数时抛出
+ * @example
+ * // 加载并监听配置文件
+ * const config = $.loadJson('./config.json', (newConfig) => {
+ *   console.log('配置已更新');
+ * });
  */
 $.loadJson = function (file, func) {
+  // 参数校验
+  if (typeof file !== 'string') {
+    throw new TypeError('文件路径必须是字符串');
+  }
+
+  if (func && typeof func !== 'function') {
+    throw new TypeError('回调函数必须是函数');
+  }
+
+  // 确保文件是.json文件
+  if (!file.endsWith('.json')) {
+    throw new TypeError('$.loadJson 只能用于.json配置文件');
+  }
+
   return $.mod.load(file, func);
 };
 
@@ -208,16 +250,16 @@ Item.prototype._remove = function (module) {
  * @param {string} file 脚本文件路径
  */
 Item.prototype.unloadScript = function (file) {
-  let target_file = file;
-  if (!target_file) {
+  let filename = file;
+  if (!filename) {
     let main = this.config.main;
     if (main) {
-      target_file = main.fullname(this.dir);
+      filename = main.fullname(this.dir);
     }
   }
 
-  if (target_file) {
-    this._remove(target_file);
+  if (filename) {
+    this._remove(filename);
   }
 
   this.complete = false;
@@ -225,10 +267,11 @@ Item.prototype.unloadScript = function (file) {
 
 /**
  * 重新加载脚本
+ * @returns {object | null} 返回加载的模块对象
  */
 Item.prototype.reloadScript = function () {
   this.unloadScript();
-  this.loadScript();
+  return this.loadScript();
 };
 
 /**
@@ -257,18 +300,15 @@ Item.prototype.unloadAfter = async function (remove) {
  * @returns {object | null} 返回加载的模块对象
  */
 Item.prototype.loadScript = function (file, name = '') {
-  let target_file = this._getScriptFile(file);
-  if (!target_file) return null;
+  let filename = this._getScriptFile(file);
+  if (!filename) return null;
 
-  let target_name = this._getScriptName(name);
+  let func_name = this._getScriptName(name);
 
   try {
-    let cs = this._loadScript(target_file, target_name);
-    this._setMainMethod(cs, target_name);
-    return cs;
+    this._loadScript(filename, func_name);
   } catch (err) {
     this.log('error', `加载脚本失败: `, err);
-    return null;
   }
 };
 
@@ -283,12 +323,12 @@ Item.prototype._getScriptFile = function (file) {
   let main = this.config.main;
   if (!main) return null;
 
-  let target_file = main.fullname(this.dir);
-  if (!target_file.hasFile()) {
-    this.newScript(target_file);
+  let filename = main.fullname(this.dir);
+  if (!filename.hasFile()) {
+    this.newScript(filename);
   }
 
-  return target_file;
+  return filename;
 };
 
 /**
@@ -301,16 +341,27 @@ Item.prototype._getScriptName = function (name) {
 };
 
 /**
- * 加载脚本模块
- * @param {string} file 文件路径
- * @param {string} name 函数名
- * @returns {object | null} 模块对象
+ * 加载脚本文件，支持热重载模式
+ * 在开发模式(mode=3或4)下使用 $.require 进行热重载
+ * 在生产模式下使用标准的 require 加载
+ * @param {string} file 脚本文件路径
+ * @param {string} func_name 函数名
+ * @returns {object | null} 加载的模块对象
  */
-Item.prototype._loadScript = function (file, name) {
+Item.prototype._loadScript = function (file, func_name) {
   if (this.mode === 3 || this.mode === 4) {
-    return $.require(file, this._handleHotReload.bind(this, name));
+    // 开发模式：使用 $.require 进行热重载，绑定热更新回调
+    var cs = $.require(file, (mod) => {
+      this._setMainMethod(mod, func_name);
+    });
+    this._setMainMethod(cs, func_name);
+    return cs;
+  }
+  else {
+    var cs = require(file);
+    this._setMainMethod(cs, func_name);
+    return cs;
   }
-  return require(file);
 };
 
 /**
@@ -351,6 +402,13 @@ Item.prototype.newConfig = function (file) {
   this._createConfigFile(file, this.config, this.dir_base);
 };
 
+/**
+ * 创建配置文件
+ * @param {string} file 目标文件路径
+ * @param {object} model 配置模型对象
+ * @param {string} tpl_dir 模板文件路径
+ * @returns {string} 配置文件内容
+ */
 Item.prototype._createConfigFile = function (file, model = {}, tpl_dir = '') {
   var tpl = this.getConfigTpl(tpl_dir);
   var content = $.tpl.render(tpl, model);
@@ -534,7 +592,7 @@ Item.prototype._removeConfigFile = function (file, name) {
  * @param {string} name 配置名称
  * @returns {string | null} 错误消息
  */
-Item.prototype._removeArrayItem = function (file, config, name) {
+Item.prototype._removeArray = function (file, config, name) {
   let index = config.findIndex((item) => item.name === name);
   if (index === -1) return null;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mm_machine",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "A flexible Node.js plugin mechanism system for dynamic loading, management and execution of modules. Supports hot reload, lifecycle management, and modern JavaScript features.",
   "main": "index.js",
   "scripts": {