mm_hook_func 1.0.0 → 1.0.1

package/example/index.js

@@ -0,0 +1,50 @@
+/**
+ * mm_hook_func 钩子函数模块示例
+ * 演示 HookFunc 的函数注册表：addFunc / hasFunc / runFunc / listFuncs / delFunc
+ * 运行：node example/index.js
+ */
+const { HookFunc, getHookFunc } = require('../index.js');
+
+/**
+ * 主函数
+ * @returns {Promise<void>}
+ */
+async function main() {
+  console.log('=== 钩子函数注册表 ===');
+
+  // 获取单例（多次获取返回同一实例）
+  var hook = getHookFunc();
+  var hook2 = getHookFunc();
+  console.log('getHookFunc 单例 ->', hook === hook2);
+
+  // 注册函数
+  hook.addFunc('html_filter', function (ctx, params, html) {
+    return html.replace(/<script[\s\S]*?<\/script>/ig, '');
+  });
+  hook.addFunc('hello', function (name) {
+    return '你好, ' + name + '!';
+  });
+  console.log('注册后函数列表 ->', hook.listFuncs().join(', '));
+  console.log('hasFunc("hello") ->', hook.hasFunc('hello'));
+
+  // 运行函数
+  console.log('runFunc("hello", "张三") ->', await hook.runFunc('hello', '张三'));
+  console.log('runFunc("html_filter") 过滤脚本标签 ->',
+    await hook.runFunc('html_filter', {}, {}, '<p>正文</p><script>alert(1)</script>'));
+
+  // 未注册函数：原样返回最后一个参数
+  console.log('runFunc("no_such_func") ->', await hook.runFunc('no_such_func', 'fallback'));
+
+  // 删除函数
+  console.log('delFunc("hello") ->', hook.delFunc('hello'));
+  console.log('删除后 hasFunc("hello") ->', hook.hasFunc('hello'));
+
+  // 直接实例化
+  var h2 = new HookFunc();
+  console.log('\n直接实例化 HookFunc ->', h2 instanceof HookFunc);
+}
+
+main().catch(function (err) {
+  console.error(err);
+  process.exit(1);
+});

package/lib/hook_func.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { Base } = require('mm_corejs');
+const { Base } = require('mm_mod');
 
 /**
  * 钩子函数类
@@ -112,17 +112,52 @@ class HookFunc extends Base {
 
   /**
    * 绑定 web 服务器：向其请求管道的 render 阶段注册渲染钩子
-   * @param {Object} web web 服务器实例，需提供 getHandle() 方法
+   *
+   * 支持两代管线：
+   * - 新代（mm_event 七阶段链）：web 提供 getEventManager()，本方法向其注册一个
+   *   render 阶段的事件驱动（驱动脚本 lib/render_hook.js）；
+   * - 旧代（Handle/Hooks）：web 提供 getHandle()，保持原有 on('render') 注册方式兼容。
+   *
+   * @param {Object} web web 服务器实例，需提供 getEventManager() 或 getHandle() 方法
    * @returns {HookFunc} 当前实例
-   * @throws {TypeError} web 不具备 getHandle 方法时
+   * @throws {TypeError} web 不具备 getEventManager/getHandle 方法时
    */
   bind(web) {
-    if (!web || typeof web.getHandle !== 'function') {
-      throw new TypeError(`${this._label()} web must provide getHandle()`);
+    if (!web) {
+      throw new TypeError(`${this._label()} web is required`);
     }
-    this.#web = web;
-    web.getHandle().on('render', (params, ctx, options) => this._runRender(params, ctx, options), 100, 'hook_func');
-    return this;
+    // 旧代管线（Handle/Hooks）：保留兼容
+    if (typeof web.getHandle === 'function') {
+      this.#web = web;
+      web.getHandle().on('render', (params, ctx, options) => this._runRender(params, ctx, options), 100, 'hook_func');
+      return this;
+    }
+    // 新代管线（mm_event 七阶段链）：注册 render 阶段事件驱动
+    if (typeof web.getEventManager === 'function') {
+      const manager = web.getEventManager();
+      if (!manager || typeof manager.add !== 'function') {
+        throw new TypeError(`${this._label()} web.getEventManager() must return an event manager with add()`);
+      }
+      this.#web = web;
+      /**
+       * 已注册的渲染阶段事件驱动
+       * @type {Object|null}
+       */
+      this._render_drive = manager.add({
+        name: 'hook_func_render',
+        title: '统一渲染钩子',
+        description: '由 mm_hook_func 注册：渲染阶段对字符串结果执行配置的过滤函数（默认 html_filter）',
+        target: '*',
+        stage: 'render',
+        sort: 100,
+        state: 1,
+        dir: __dirname,
+        main: 'render_hook.js',
+        func_name: 'main'
+      });
+      return this;
+    }
+    throw new TypeError(`${this._label()} web must provide getEventManager() or getHandle()`);
   }
 
   /**

package/lib/render_hook.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const { getHookFunc } = require('../index.js');
+
+/**
+ * 渲染阶段钩子（mm_event 七阶段链驱动脚本）
+ *
+ * 由 HookFunc.bind(web) 注册到 web 作用域事件管理器的 render 阶段：
+ * 对上下文结果中的字符串执行配置的渲染函数（默认 html_filter），
+ * 返回过滤后的内容，事件管理器会将其写回 ctx.result。
+ *
+ * @param {Object} params 请求参数
+ * @param {Object} ctx 请求上下文（ctx.result 为待渲染内容）
+ * @param {Object} options 事件选项
+ * @returns {Promise<string|undefined>} 过滤后的内容；结果非字符串时返回 undefined
+ */
+async function main(params, ctx, options) {
+  const hf = getHookFunc();
+  const html = ctx && ctx.result;
+  if (typeof html !== 'string') {
+    return undefined;
+  }
+  return await hf.runFunc(hf.config.render_name, ctx, options, html);
+}
+
+module.exports = { main };

package/package.json

@@ -1,30 +1,35 @@
 {
-  "name": "mm_hook_func",
-  "version": "1.0.0",
-  "description": "钩子函数模块，提供函数名值注册表并可作为插件向 web 管道注册 render 钩子。",
-  "main": "index.js",
-  "keywords": [
-    "mm_mod",
-    "mm_infra",
-    "mm_common",
-    "hook",
-    "func",
-    "render"
-  ],
-  "layer": "infra",
-  "group": "common",
-  "author": "邱文武",
-  "license": "ISC",
-  "dependencies": {
-    "mm_corejs": "^1.1.4"
-  },
-  "engines": {
-    "node": ">=12.0.0"
-  },
-  "directories": {
-    "lib": "lib"
-  },
-  "scripts": {
-    "test": "node test.js"
-  }
+    "name": "mm_hook_func",
+    "version": "1.0.1",
+    "description": "钩子函数模块，提供函数名值注册表并可作为插件向 web 管道注册 render 钩子。",
+    "main": "index.js",
+    "repository": {
+        "type": "git",
+        "url": "git+https://gitee.com/qiuwenwu91/mm_hook_func.git"
+    },
+    "keywords": [
+        "mm_mod",
+        "mm_infra",
+        "mm_common",
+        "hook",
+        "func",
+        "render"
+    ],
+    "layer": "infra",
+    "group": "common",
+    "author": "邱文武",
+    "license": "ISC",
+    "dependencies": {
+        "mm_corejs": "^1.1.4",
+        "mm_mod": "^1.0.1"
+    },
+    "engines": {
+        "node": ">=12.0.0"
+    },
+    "directories": {
+        "lib": "lib"
+    },
+    "scripts": {
+        "test": "node test.js && node --test tests/hook_func.test.js"
+    }
 }

package/tests/hook_func.test.js

@@ -0,0 +1,130 @@
+'use strict';
+/**
+ * mm_hook_func 单元测试
+ * @description 覆盖函数注册表、两代管线 bind（旧 Handle / 新 mm_event 七阶段链）与渲染驱动脚本
+ */
+const test = require('node:test');
+const assert = require('assert');
+const path = require('path');
+
+const { HookFunc, getHookFunc } = require('../index.js');
+
+test('导出结构与单例', () => {
+  assert.strictEqual(typeof HookFunc, 'function');
+  assert.strictEqual(typeof getHookFunc, 'function');
+  const h1 = getHookFunc();
+  const h2 = getHookFunc();
+  assert.ok(h1 instanceof HookFunc);
+  assert.strictEqual(h1, h2, 'getHookFunc 应返回单例');
+});
+
+test('函数注册表：增删查与运行', async () => {
+  const hf = new HookFunc();
+  assert.strictEqual(hf.hasFunc('x'), false);
+  hf.addFunc('x', (a) => `${a}!`);
+  assert.strictEqual(hf.hasFunc('x'), true);
+  assert.strictEqual(await hf.runFunc('x', 'hi'), 'hi!');
+  assert.strictEqual(hf.delFunc('x'), true);
+  assert.strictEqual(hf.delFunc('x'), false);
+  // 未注册时 runFunc 原样返回最后一个参数
+  assert.strictEqual(await hf.runFunc('none', 'a', 'b'), 'b');
+  assert.deepStrictEqual(hf.listFuncs(), []);
+  hf.addFunc('a', () => 1);
+  hf.addFunc('b', () => 2);
+  hf.clear();
+  assert.deepStrictEqual(hf.listFuncs(), []);
+});
+
+test('注册表参数校验', () => {
+  const hf = new HookFunc();
+  assert.throws(() => hf.addFunc('', () => {}), TypeError);
+  assert.throws(() => hf.addFunc(null, () => {}), TypeError);
+  assert.throws(() => hf.addFunc('y', 'not-a-fn'), TypeError);
+});
+
+test('bind 新代管线：向事件管理器注册 render 阶段驱动', () => {
+  const hf = new HookFunc();
+  const captured = [];
+  const web = {
+    getEventManager: () => ({
+      add: (config) => {
+        captured.push(config);
+        return { config };
+      },
+    }),
+  };
+  hf.bind(web);
+  assert.strictEqual(captured.length, 1, '应注册一个事件驱动');
+  const cfg = captured[0];
+  assert.strictEqual(cfg.name, 'hook_func_render');
+  assert.strictEqual(cfg.stage, 'render', '应注册到 render 阶段');
+  assert.strictEqual(cfg.target, '*');
+  assert.strictEqual(cfg.state, 1);
+  assert.strictEqual(cfg.main, 'render_hook.js', '驱动脚本应为 lib/render_hook.js');
+  assert.ok(cfg.dir && cfg.dir.endsWith('lib'), '驱动目录应指向模块 lib 目录');
+  // 重复绑定同一 web 不应无限累积（第二次 add 覆盖同名驱动由管理器负责）
+  hf.bind(web);
+  assert.strictEqual(captured.length, 2);
+});
+
+test('bind 新代管线：渲染驱动脚本对 ctx.result 执行 html_filter', async () => {
+  // 驱动脚本内部使用 getHookFunc() 单例，此处也用单例注册函数
+  const hf = getHookFunc();
+  hf.clear();
+  let cfg = null;
+  const web = {
+    getEventManager: () => ({
+      add: (config) => {
+        cfg = config;
+        return { config };
+      },
+    }),
+  };
+  hf.bind(web);
+  // 模拟事件管理器加载驱动脚本并执行 main
+  const drive = require(path.join(cfg.dir, cfg.main));
+  assert.strictEqual(typeof drive.main, 'function', '驱动脚本应导出 main 函数');
+
+  // 场景1：注册了 html_filter 时对字符串结果生效
+  hf.addFunc('html_filter', (ctx, options, html) => html.replace(/bad/g, 'good'));
+  const ctx1 = { result: 'bad word' };
+  const ret1 = await drive.main({}, ctx1, {});
+  assert.strictEqual(ret1, 'good word');
+  assert.strictEqual(ctx1.result, 'bad word', '驱动仅返回结果，写回 ctx.result 由事件管理器负责');
+
+  // 场景2：结果非字符串时返回 undefined
+  const ctx2 = { result: { json: true } };
+  assert.strictEqual(await drive.main({}, ctx2, {}), undefined);
+
+  // 场景3：未注册 html_filter 时原样返回内容（runFunc 回退语义）
+  hf.delFunc('html_filter');
+  const ctx3 = { result: 'plain' };
+  assert.strictEqual(await drive.main({}, ctx3, {}), 'plain');
+  hf.clear();
+});
+
+test('bind 旧代管线：getHandle 兼容路径仍可用', () => {
+  const hf = new HookFunc();
+  const registered = [];
+  const web = {
+    getHandle: () => ({
+      on: (stage, fn, priority, name) => registered.push({ stage, fn, priority, name }),
+    }),
+  };
+  hf.bind(web);
+  assert.strictEqual(registered.length, 1);
+  assert.strictEqual(registered[0].stage, 'render');
+  assert.strictEqual(registered[0].name, 'hook_func');
+  assert.strictEqual(typeof registered[0].fn, 'function');
+});
+
+test('bind 非法 web 抛出 TypeError', () => {
+  const hf = new HookFunc();
+  assert.throws(() => hf.bind(null), TypeError);
+  assert.throws(() => hf.bind({}), TypeError, '既无 getEventManager 也无 getHandle 时应抛错');
+  assert.throws(
+    () => hf.bind({ getEventManager: () => ({}) }),
+    TypeError,
+    '事件管理器缺少 add 方法时应抛错'
+  );
+});