mm_hook_func 0.0.0-stage → 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/index.js

@@ -0,0 +1,24 @@
+const { HookFunc } = require('./lib/hook_func.js');
+
+/**
+ * 钩子函数单例
+ * @type {HookFunc|null}
+ */
+let hook_func = null;
+
+/**
+ * 获取钩子函数单例
+ * @param {object} config 配置选项
+ * @returns {HookFunc} 钩子函数实例
+ */
+function getHookFunc(config) {
+  if (!hook_func) {
+    hook_func = new HookFunc(config);
+  }
+  return hook_func;
+}
+
+module.exports = {
+  HookFunc,
+  getHookFunc
+};

package/lib/hook_func.js

@@ -0,0 +1,178 @@
+'use strict';
+
+const { Base } = require('mm_mod');
+
+/**
+ * 钩子函数类
+ *
+ * 维护一个「函数名 → 函数体」的注册表，供业务按名调用可替换的函数；
+ * 同时可作为插件通过 bind(web) 向 web 请求管道的 render 阶段注册钩子，
+ * 在渲染阶段对字符串结果按配置的函数名做统一处理。
+ */
+class HookFunc extends Base {
+  /**
+   * 模块默认配置
+   */
+  static config = {
+    name: 'hook_func',
+    title: '钩子函数模块',
+    description: '函数名值注册表，并向 web 管道注册 render 钩子',
+    render_name: 'html_filter'
+  };
+
+  /**
+   * 函数注册表
+   * @type {Object<string, Function>}
+   */
+  #funcs = {};
+
+  /**
+   * 已挂载的 web 服务器实例
+   * @type {Object|null}
+   */
+  #web = null;
+
+  /**
+   * 添加函数
+   * @param {string} name 函数名称
+   * @param {Function} func 函数体
+   * @returns {HookFunc} 当前实例
+   * @throws {TypeError} 名称非法或函数体非函数时
+   */
+  addFunc(name, func) {
+    if (typeof name !== 'string' || name === '') {
+      throw new TypeError(`${this._label()} name must be a non-empty string`);
+    }
+    if (typeof func !== 'function') {
+      throw new TypeError(`${this._label()} func must be a function`);
+    }
+    this.#funcs[name] = func;
+    return this;
+  }
+
+  /**
+   * 删除函数
+   * @param {string} name 函数名称
+   * @returns {boolean} 是否删除成功
+   */
+  delFunc(name) {
+    if (!this.hasFunc(name)) return false;
+    delete this.#funcs[name];
+    return true;
+  }
+
+  /**
+   * 获取函数
+   * @param {string} name 函数名称
+   * @returns {Function|undefined} 函数体，未注册时为 undefined
+   */
+  getFunc(name) {
+    return this.#funcs[name];
+  }
+
+  /**
+   * 判断函数是否存在
+   * @param {string} name 函数名称
+   * @returns {boolean} 是否存在
+   */
+  hasFunc(name) {
+    return typeof this.#funcs[name] === 'function';
+  }
+
+  /**
+   * 列出所有函数名称
+   * @returns {Array<string>} 函数名称列表
+   */
+  listFuncs() {
+    return Object.keys(this.#funcs);
+  }
+
+  /**
+   * 清空函数注册表
+   * @returns {HookFunc} 当前实例
+   */
+  clear() {
+    this.#funcs = {};
+    return this;
+  }
+
+  /**
+   * 运行函数
+   * @param {string} name 函数名称
+   * @param {...*} args 函数参数
+   * @returns {Promise<*>} 函数返回值；未注册时原样返回最后一个参数
+   */
+  async runFunc(name, ...args) {
+    const func = this.getFunc(name);
+    if (!func) {
+      return args.length > 0 ? args[args.length - 1] : undefined;
+    }
+    return await func(...args);
+  }
+
+  /**
+   * 绑定 web 服务器：向其请求管道的 render 阶段注册渲染钩子
+   *
+   * 支持两代管线：
+   * - 新代（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 不具备 getEventManager/getHandle 方法时
+   */
+  bind(web) {
+    if (!web) {
+      throw new TypeError(`${this._label()} web is required`);
+    }
+    // 旧代管线（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()`);
+  }
+
+  /**
+   * 执行 render 钩子：对字符串结果调用配置的渲染函数
+   * @param {Object} ctx 上下文对象
+   * @param {Object} params 请求参数
+   * @returns {Promise<*>} 渲染后的结果；结果非字符串时返回 undefined
+   */
+  async _runRender(ctx, params) {
+    const html = ctx.result;
+    if (typeof html !== 'string') return undefined;
+    return await this.runFunc(this.config.render_name, ctx, params, html);
+  }
+}
+
+module.exports = {
+  HookFunc
+};

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,6 +1,35 @@
 {
-  "name": "mm_hook_func",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "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/test.js

@@ -0,0 +1,22 @@
+'use strict';
+const assert = require('assert');
+const mod = require('./index.js');
+
+// 验证导出结构
+assert.strictEqual(typeof mod.HookFunc, 'function', '应导出 HookFunc 类');
+assert.strictEqual(typeof mod.getHookFunc, 'function', '应导出 getHookFunc 函数');
+
+// 验证单例：多次获取返回同一实例
+const h1 = mod.getHookFunc();
+const h2 = mod.getHookFunc();
+assert.ok(h1 instanceof mod.HookFunc, 'getHookFunc 应返回 HookFunc 实例');
+assert.strictEqual(h1, h2, 'getHookFunc 应返回单例');
+
+// 验证函数注册表基本功能
+const fn = () => 'ok';
+h1.addFunc('test_func', fn);
+assert.strictEqual(h1.hasFunc('test_func'), true, 'addFunc 后 hasFunc 应为 true');
+assert.strictEqual(h1.delFunc('test_func'), true, 'delFunc 应删除成功');
+assert.strictEqual(h1.hasFunc('test_func'), false, 'delFunc 后 hasFunc 应为 false');
+
+console.log('mm_hook_func 模块测试通过');

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 方法时应抛错'
+  );
+});

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.