mm_hook_func 0.0.0-stage → 1.0.0

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,143 @@
+'use strict';
+
+const { Base } = require('mm_corejs');
+
+/**
+ * 钩子函数类
+ *
+ * 维护一个「函数名 → 函数体」的注册表，供业务按名调用可替换的函数；
+ * 同时可作为插件通过 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 阶段注册渲染钩子
+   * @param {Object} web web 服务器实例，需提供 getHandle() 方法
+   * @returns {HookFunc} 当前实例
+   * @throws {TypeError} web 不具备 getHandle 方法时
+   */
+  bind(web) {
+    if (!web || typeof web.getHandle !== 'function') {
+      throw new TypeError(`${this._label()} web must provide getHandle()`);
+    }
+    this.#web = web;
+    web.getHandle().on('render', (params, ctx, options) => this._runRender(params, ctx, options), 100, 'hook_func');
+    return this;
+  }
+
+  /**
+   * 执行 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/package.json

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

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/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.