mm_func 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# mm_func
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+函数钩子（Func Hook）管理模块：提供函数钩子的注册、删除与按名执行能力。
+
+与 `mm_action`（动作钩子）、`mm_filter`（过滤钩子）共同构成 mm 模块体系的三类钩子基础设施，
+`mm_tpl` 等上层模块通过组合这三个模块获得完整的钩子能力。
+
+## 安装
+
+```bash
+npm install mm_func
+```
+
+## 使用
+
+```js
+const { Func, funcAdmin } = require('mm_func');
+
+// 直接使用
+var func = new Func();
+
+// 注册函数钩子：name, func, sort（越大越先执行）, alias（删除用）
+func.addFunc('list', async function makeList(model, req) {
+  return await db.query('...');
+});
+func.addFunc('list', function makeStatic() {
+  return 'static list';
+}, 50);
+
+// 执行：按 sort 降序依次执行，支持异步函数，返回最后一个真值
+var ret = await func.runFunc('list', { query: { page: 1 } }, {});
+
+// 按别名删除
+func.delFunc('list', 'makeStatic');
+
+// 清空
+func.clear('list'); // 清空指定函数
+func.clear();       // 清空全部
+
+// 通过 Admin 工厂按作用域取实例（需安装 mm_corejs）
+var admin = funcAdmin('os', { /* config */ });
+```
+
+## API
+
+| 方法 | 说明 |
+| --- | --- |
+| `addFunc(name, func, sort = 100, alias = '')` | 添加函数钩子，返回别名 |
+| `delFunc(name, alias = '')` | 删除函数钩子，别名省略时清空该名称下全部 |
+| `getFunc(name)` | 获取第一个函数体，未注册时返回 undefined |
+| `hasFunc(name)` | 判断函数是否存在 |
+| `listFuncs(name)` | 列出函数名称（省略 name）或函数项列表 |
+| `runFunc(name, ...args)` | 异步按序执行，支持 Promise，返回最后一个真值 |
+| `clear(name)` | 清空函数 |
+
+## 语义约定
+
+- 同一函数名下可注册多个函数实现，按 `sort` **降序**依次执行；
+- `runFunc` 为异步执行，支持异步函数/Promise 返回值，返回**最后一个真值**结果；
+- 未注册函数名时执行返回 undefined；
+- 单个钩子异常只记录日志并跳过，不中断其他钩子。
+
+## 与 mm_tpl 的关系
+
+`mm_tpl` 内部的 `Hook` 类是本模块（以及 `mm_action`、`mm_filter`）的组合门面：
+模板中 `tpl.runFunc(name, req)` 的调用最终由 `mm_func` 执行。

package/index.js

@@ -0,0 +1,27 @@
+const Func = require('./lib/func');
+let Admin = null;
+try {
+  Admin = require('mm_corejs').Admin;
+} catch (e) {
+  // mm_corejs 未安装时仅提供核心类，Admin 工厂不可用
+}
+
+let admin = null;
+if (Admin) {
+  admin = new Admin();
+  admin.setClass(Func);
+}
+
+module.exports = {
+  Func,
+  admin,
+  funcAdmin(scope, config = {}) {
+    if (!admin) {
+      throw new Error('mm_func: mm_corejs 未安装，Admin 工厂不可用');
+    }
+    if (!scope) {
+      scope = 'os';
+    }
+    return admin.get(scope, config);
+  }
+};

package/lib/func.js

@@ -0,0 +1,192 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Func —— 函数钩子管理模块。
+ *
+ * 维护「函数名 → 函数列表」的注册表，提供函数钩子的注册、删除与按名执行能力。
+ *
+ * 语义约定：
+ * - 同一函数名下可注册多个函数实现，按 sort 降序依次执行（sort 越大越先执行）；
+ * - runFunc 为异步执行：支持异步函数/Promise 返回值，返回最后一个真值结果；
+ * - 未注册函数名时执行返回 undefined；
+ * - 单个函数执行异常只记录日志并跳过，不影响其他函数执行。
+ *
+ * @class
+ */
+class Func {
+  /**
+   * 构造函数
+   * @param {Object} [config] 模块配置
+   * @param {Object} [config.logger] 日志对象，需含 error 方法，缺省使用 console
+   */
+  constructor(config = {}) {
+    this.config = config;
+    /**
+     * 日志对象
+     */
+    this._logger = config.logger || console;
+    /**
+     * 函数注册表：函数名 → 函数项列表
+     * @type {Object<string, Array<{func: Function, sort: number, alias: string}>>}
+     */
+    this._methods = {};
+  }
+
+  /**
+   * 获取函数别名
+   * 具名函数取函数名，匿名函数用 md5 自动生成
+   * @param {Function} func - 钩子函数
+   * @param {string} alias - 别名
+   * @returns {string} 函数别名
+   */
+  _getName(func, alias) {
+    if (alias) {
+      return alias;
+    }
+    if (func.name) {
+      return func.name;
+    }
+    return crypto.createHash('md5').update((new Date()).toString()).digest('hex').substring(0, 8);
+  }
+
+  /**
+   * 添加函数钩子
+   * @param {string} name - 函数名称
+   * @param {Function} func - 函数体
+   * @param {number} [sort=100] - 执行顺序，越大越先执行
+   * @param {string} [alias=""] - 函数别名，用于删除；省略时自动生成
+   * @returns {string} 函数别名
+   * @throws {TypeError} 名称非法或函数体非函数时
+   */
+  addFunc(name, func, sort = 100, alias = '') {
+    if (typeof name !== 'string' || name === '') {
+      throw new TypeError(`[${this.constructor.name}] name must be a non-empty string`);
+    }
+    if (typeof func !== 'function') {
+      throw new TypeError(`[${this.constructor.name}] func must be a function`);
+    }
+    alias = this._getName(func, alias);
+    var arr = this._methods[name] || [];
+    arr.push({
+      func,
+      sort,
+      alias
+    });
+    arr.sort((o1, o2) => o2.sort - o1.sort);
+    this._methods[name] = arr;
+    return alias;
+  }
+
+  /**
+   * 删除函数钩子
+   * @param {string} name - 函数名称
+   * @param {string} [alias=""] - 函数别名；省略时删除该函数名下全部函数
+   * @returns {boolean} 是否删除成功
+   */
+  delFunc(name, alias = '') {
+    var arr = this._methods[name];
+    if (!arr || !arr.length) {
+      return false;
+    }
+    if (!alias) {
+      delete this._methods[name];
+      return true;
+    }
+    var list = [];
+    var removed = false;
+    for (var i = 0; i < arr.length; i++) {
+      var item = arr[i];
+      if (item.alias === alias) {
+        removed = true;
+      } else {
+        list.push(item);
+      }
+    }
+    if (removed) {
+      this._methods[name] = list;
+    }
+    return removed;
+  }
+
+  /**
+   * 获取函数
+   * @param {string} name - 函数名称
+   * @returns {Function|undefined} 第一个函数体；未注册时为 undefined
+   */
+  getFunc(name) {
+    var arr = this._methods[name];
+    return arr && arr.length ? arr[0].func : undefined;
+  }
+
+  /**
+   * 判断函数是否存在
+   * @param {string} name - 函数名称
+   * @returns {boolean} 是否存在
+   */
+  hasFunc(name) {
+    var arr = this._methods[name];
+    return !!(arr && arr.length);
+  }
+
+  /**
+   * 列出函数
+   * @param {string} [name] - 函数名称；省略时返回全部函数名称列表
+   * @returns {Array<string>|Array<{alias: string, sort: number}>} 函数名称列表或函数项列表
+   */
+  listFuncs(name) {
+    if (name === undefined) {
+      return Object.keys(this._methods);
+    }
+    var arr = this._methods[name] || [];
+    return arr.map((item) => ({
+      alias: item.alias,
+      sort: item.sort
+    }));
+  }
+
+  /**
+   * 执行函数钩子
+   * 按顺序异步执行该函数名下的全部函数，支持 Promise 返回值，返回最后一个真值
+   * @param {string} name - 函数名称
+   * @param {...any} args - 传递给函数的参数
+   * @returns {Promise<any>} 最后一个真值结果；未注册时为 undefined
+   */
+  async runFunc(name, ...args) {
+    var ret;
+    var arr = this._methods[name];
+    if (!arr) {
+      return ret;
+    }
+    for (var i = 0; i < arr.length; i++) {
+      var item = arr[i];
+      try {
+        var ret_new = item.func(...args);
+        if (ret_new && typeof ret_new.then === 'function') {
+          ret_new = await ret_new;
+        }
+        if (ret_new) {
+          ret = ret_new;
+        }
+      } catch (err) {
+        this._logger.error(`[${this.constructor.name}] 执行函数钩子失败 ${item.alias}`, err);
+      }
+    }
+    return ret;
+  }
+
+  /**
+   * 清空函数钩子
+   * @param {string} [name] - 函数名称；省略时清空全部函数
+   */
+  clear(name) {
+    if (name) {
+      delete this._methods[name];
+    } else {
+      this._methods = {};
+    }
+  }
+}
+
+module.exports = Func;

package/package.json

@@ -1,6 +1,30 @@
 {
-  "name": "mm_func",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "mm_func",
+    "version": "1.0.1",
+    "description": "函数钩子管理模块：提供函数钩子 addFunc/delFunc/runFunc 的注册与按名执行能力",
+    "main": "index.js",
+    "repository": {
+        "type": "git",
+        "url": "git+https://gitee.com/qiuwenwu91/mm_func.git"
+    },
+    "keywords": [
+        "mm_mod",
+        "mm_infra",
+        "func",
+        "hook",
+        "函数"
+    ],
+    "layer": "infra",
+    "group": "common",
+    "author": "邱文武",
+    "license": "ISC",
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "scripts": {
+        "test": "node test.js"
+    },
+    "dependencies": {
+        "mm_corejs": "^1.1.6"
+    }
+}

package/test.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const assert = require('assert');
+const mod = require('./index.js');
+const Func = require('./lib/func');
+
+// 1. 导出结构校验
+assert.strictEqual(typeof mod.Func, 'function', '应导出 Func 类');
+assert.strictEqual(typeof mod.funcAdmin, 'function', '应导出 funcAdmin 函数');
+
+async function test() {
+  console.log('=== mm_func 测试开始 ===');
+
+  // 2. 添加与执行
+  var func = new Func();
+  func.addFunc('list', async function makeList(model, req) {
+    return ['article1', 'article2'];
+  });
+  func.addFunc('list', function makeStatic() {
+    return 'static';
+  }, 50);
+  var ret = await func.runFunc('list', { query: { page: 1 } }, {});
+  // sort 大的先执行：makeList(100) 先返回数组，makeStatic(50) 后返回字符串，取最后一个真值
+  assert.strictEqual(ret, 'static');
+  console.log('√ 添加与异步执行（返回最后一个真值）');
+
+  // 3. 未注册返回 undefined
+  assert.strictEqual(await func.runFunc('none'), undefined);
+  console.log('√ 未注册返回 undefined');
+
+  // 4. getFunc：取函数体
+  var got = func.getFunc('list');
+  assert.strictEqual(typeof got, 'function');
+  assert.strictEqual(got.name, 'makeList');
+  assert.strictEqual(func.getFunc('none'), undefined);
+  console.log('√ getFunc 取函数体');
+
+  // 5. 别名：具名函数自动取函数名
+  var func2 = new Func();
+  var alias = func2.addFunc('test', function myFunc() {});
+  assert.strictEqual(alias, 'myFunc');
+  var alias2 = func2.addFunc('test', function () {});
+  assert.ok(alias2 && alias2.length === 8);
+  console.log('√ 别名自动生成');
+
+  // 5. 删除：按别名删除 / 清空
+  var func3 = new Func();
+  func3.addFunc('run', function f1() { return 1; });
+  func3.addFunc('run', function f2() { return 2; });
+  assert.ok(func3.delFunc('run', 'f1'));
+  assert.strictEqual(await func3.runFunc('run'), 2);
+  assert.ok(func3.delFunc('run'));
+  assert.ok(!func3.hasFunc('run'));
+  console.log('√ 按别名删除与清空');
+
+  // 6. 参数透传
+  var func4 = new Func();
+  func4.addFunc('add', function (a, b, c) {
+    return a + b + c;
+  });
+  assert.strictEqual(await func4.runFunc('add', 1, 2, 3), 6);
+  console.log('√ 参数透传');
+
+  // 7. 异常隔离：单个钩子报错不影响其他钩子
+  var func5 = new Func({ logger: { error() {} } });
+  func5.addFunc('boom', function () {
+    throw new Error('boom');
+  });
+  func5.addFunc('boom', async function ok() {
+    return 'ok';
+  });
+  assert.strictEqual(await func5.runFunc('boom'), 'ok');
+  console.log('√ 异常隔离');
+
+  // 8. 参数校验
+  var func6 = new Func();
+  assert.throws(() => func6.addFunc('', function () {}), TypeError);
+  assert.throws(() => func6.addFunc('x', 'not a function'), TypeError);
+  console.log('√ 参数校验');
+
+  // 9. listFuncs / clear
+  var func7 = new Func();
+  func7.addFunc('a', function x1() {});
+  func7.addFunc('b', function x2() {});
+  assert.deepStrictEqual(func7.listFuncs().sort(), ['a', 'b']);
+  assert.strictEqual(func7.listFuncs('a')[0].alias, 'x1');
+  func7.clear();
+  assert.deepStrictEqual(func7.listFuncs(), []);
+  console.log('√ listFuncs / clear');
+
+  console.log('=== mm_func 测试全部通过 ===');
+}
+
+test().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});