mm_tpl 2.7.1 → 2.7.2

package/lib/hook.js

@@ -0,0 +1,302 @@
+
+const {
+  types
+} = require("util");
+
+/**
+ * 钩子管理类
+ * @class
+ */
+class Hook {
+  /**
+   * 创建钩子实例
+   */
+  constructor() {
+    this._func = {};
+    this._action = {};
+    this._filter = {};
+  }
+}
+
+/**
+ * 排序钩子列表
+ * @param {Array} list - 钩子列表
+ * @returns {Array} 排序后的列表
+ */
+Hook.prototype.sort = function (list) {
+  return list.sort((o1, o2) => {
+    return o2.sort - o1.sort
+  });
+};
+
+/**
+ * 获取函数别名
+ * @param {Function} func - 钩子函数
+ * @param {string} alias - 别名
+ * @returns {string} 函数别名
+ */
+Hook.prototype._getName = function (func, alias) {
+  if (!alias) {
+    var str = func.toString();
+    var name = str.between('function ', "(").trim();
+    if (name) {
+      alias = name;
+    } else {
+      alias = (new Date()).toString().md5().substring(0, 8);
+    }
+  }
+  return alias;
+};
+
+/**
+ * 添加函数钩子
+ * @param {string} name - 钩子名称
+ * @param {Function} func - 钩子函数
+ * @param {number} sort - 执行顺序
+ * @param {string} alias - 函数别名
+ * @returns {string} 函数别名
+ */
+Hook.prototype.addFunc = function (name, func, sort = 100, alias = "") {
+  alias = this._getName(func, alias);
+  var obj = {
+    func,
+    sort,
+    alias
+  }
+  var arr = this._func[name] || [];
+  arr.push(obj);
+  this._func[name] = this.sort(arr);
+  return alias;
+};
+
+/**
+ * 添加动作钩子
+ * @param {string} name - 钩子名称
+ * @param {Function} func - 钩子函数
+ * @param {number} sort - 执行顺序
+ * @param {string} alias - 函数别名
+ * @returns {string} 函数别名
+ */
+Hook.prototype.addAction = function (name, func, sort = 100, alias = "") {
+  alias = this._getName(func, alias);
+  var obj = {
+    func,
+    sort,
+    alias
+  }
+  var arr = this._action[name] || [];
+  arr.push(obj);
+  this._action[name] = this.sort(arr);
+  return alias;
+};
+
+/**
+ * 添加过滤钩子
+ * @param {string} name - 钩子名称
+ * @param {Function} func - 钩子函数
+ * @param {number} sort - 执行顺序
+ * @param {string} alias - 函数别名
+ * @returns {string} 函数别名
+ */
+Hook.prototype.addFilter = function (name, func, sort = 100, alias = "") {
+  alias = this._getName(func, alias);
+  var obj = {
+    func,
+    sort,
+    alias
+  }
+  var arr = this._filter[name] || [];
+  arr.push(obj);
+  this._filter[name] = this.sort(arr);
+  return alias;
+};
+
+/**
+ * 删除函数钩子
+ * @param {String} name 钩子名称
+ * @param {String} alias 函数别名
+ */
+Hook.prototype.delFunc = function (name, alias) {
+  var arr = this._func[name];
+  if (arr) {
+    var list = [];
+    for (var i = 0; i < arr.length; i++) {
+      var item = arr[i];
+      if (item.alias !== alias) {
+        list.push(item);
+      }
+    }
+    this._func[name] = list;
+  }
+};
+
+/**
+ * 删除动作钩子
+ * @param {String} name 钩子名称
+ * @param {String} alias 函数别名
+ */
+Hook.prototype.delAction = function (name, alias) {
+  var arr = this._action[name];
+  if (arr) {
+    var list = [];
+    for (var i = 0; i < arr.length; i++) {
+      var item = arr[i];
+      if (item.alias !== alias) {
+        list.push(item);
+      }
+    }
+    this._action[name] = list;
+  }
+};
+
+/**
+ * 删除过滤钩子
+ * @param {String} name 钩子名称
+ * @param {String} alias 函数别名
+ */
+Hook.prototype.delFilter = function (name, alias = "") {
+  var arr = this._filter[name];
+  if (arr) {
+    var list = [];
+    for (var i = 0; i < arr.length; i++) {
+      var item = arr[i];
+      if (item.alias !== alias) {
+        list.push(item);
+      }
+    }
+    this._filter[name] = list;
+  }
+};
+
+/**
+ * 执行函数钩子
+ * @param {string} name - 钩子名称
+ * @param {Object} param - 参数
+ * @param {Function} func - 钩子函数
+ */
+Hook.prototype.runFunc = async function (name, model, req, ...args) {
+  var ret;
+  var list = this._func[name];
+  if (list) {
+    for (var i = 0; i < list.length; i++) {
+      var item = list[i];
+      try {
+        var ret_new = item.func(model, req, ...args);
+        if (types.isPromise(ret_new)) {
+          ret_new = await ret_new;
+          if (ret_new) {
+            ret = ret_new;
+          }
+        }
+      } catch (err) {
+        $.log.error(`[${this.constructor.name}] 执行函数钩子失败 ${item.alias}`, err);
+      }
+    }
+  }
+  return ret;
+};
+
+/**
+ * 执行动作钩子
+ * @param {string} name - 钩子名称
+ * @param {Object} model - 模型对象
+ * @param {...any} args - 附加参数
+ * @returns {Object} 执行结果
+ */
+Hook.prototype.runAction = function (name, model, ...args) {
+  var ret = '';
+  var list = this._action[name];
+  if (list) {
+    for (var i = 0; i < list.length; i++) {
+      var o = list[i];
+      try {
+        ret += o.func(model, ...args);
+      } catch (err) {
+        $.log.error(`[${this.constructor.name}] 执行动作钩子失败 ${o.alias}`, err);
+      }
+    }
+  }
+  return ret;
+};
+
+/**
+ * 执行过滤钩子
+ * @param {string} name - 钩子名称
+ * @param {Object} model - 模型对象
+ * @param {Object} ret - 返回值
+ * @param {...any} args - 附加参数
+ * @returns {Object} 过滤后的参数
+ */
+Hook.prototype.runFilter = function (name, model, ret, ...args) {
+  var list = this._filter[name];
+  if (list) {
+    for (var i = 0; i < list.length; i++) {
+      var item = list[i];
+      try {
+        ret = item.func(model, ret, ...args) || ret;
+      } catch (err) {
+        $.log.error(`[${this.constructor.name}] 执行过滤钩子失败 ${item.alias}`, err);
+      }
+    }
+  }
+  return ret;
+};
+
+/**
+ * 删除钩子
+ * @param {string} name - 钩子名称
+ * @param {string} alias - 函数别名
+ */
+Hook.prototype.del = function (name, alias) {
+  var arr = this._func[name];
+  if (arr) {
+    var list = [];
+    for (var i = 0; i < arr.length; i++) {
+      var item = arr[i];
+      if (item.alias !== alias) {
+        list.push(item);
+      }
+    }
+    this._func[name] = list;
+  }
+  arr = this._action[name];
+  if (arr) {
+    var list = [];
+    for (var i = 0; i < arr.length; i++) {
+      var item = arr[i];
+      if (item.alias !== alias) {
+        list.push(item);
+      }
+    }
+    this._action[name] = list;
+  }
+  arr = this._filter[name];
+  if (arr) {
+    var list = [];
+    for (var i = 0; i < arr.length; i++) {
+      var item = arr[i];
+      if (item.alias !== alias) {
+        list.push(item);
+      }
+    }
+    this._filter[name] = list;
+  }
+};
+
+/**
+ * 清空钩子
+ * @param {string} name - 钩子名称
+ */
+Hook.prototype.clear = function (name) {
+  if (name) {
+    delete this._func[name];
+    delete this._action[name];
+    delete this._filter[name];
+  } else {
+    this._func = {};
+    this._action = {};
+    this._filter = {};
+  }
+};
+
+module.exports = Hook;

package/lib/js.js

@@ -0,0 +1,34 @@
+const {
+  Asset
+} = require('./asset.js');
+
+/**
+ * 脚本文件加载器
+ * 脚本与样式同属「引用多个文件」类资源，但不按风格分层
+ * 风格是视觉变体，脚本不因颜色明暗而变，按主题分层即可，公共脚本放应用级目录
+ * @class
+ */
+class Js extends Asset {
+  /**
+   * 创建脚本文件加载器
+   * @param {Object} tpl - 所属模板实例
+   */
+  constructor(tpl) {
+    super(tpl, '.js');
+  }
+}
+
+/**
+ * 获取脚本目录列表
+ * 优先级从高到低：自定义覆盖目录、当前主题、默认主题、应用级
+ * 返回顺序为优先级从高到低
+ * @param {string} theme - 主题名称，不传时取当前主题
+ * @returns {Array<string>} 脚本目录列表
+ */
+Js.prototype.getDirs = function (theme) {
+  return this.tpl.getJsDirs(theme);
+};
+
+module.exports = {
+  Js
+};

package/lib/lang.js

@@ -0,0 +1,184 @@
+const {
+  Lang: BaseLang
+} = require('mm_expand');
+const {
+  TplUtil
+} = require('./util.js');
+
+/**
+ * 语言包加载器
+ * 语言包按「配置字典 + 多个目录文件」合并，高优先级来源覆盖低优先级来源
+ * @class
+ */
+class Lang {
+  /**
+   * 创建语言包加载器
+   * @param {Object} tpl - 所属模板实例
+   */
+  constructor(tpl) {
+    /**
+     * 所属模板实例
+     */
+    this.tpl = tpl;
+  }
+}
+
+/**
+ * 获取语言包目录列表
+ * 优先级从低到高：应用级目录、默认主题目录、当前主题目录
+ * @returns {Array<string>} 语言包目录列表
+ */
+Lang.prototype.getDirs = function () {
+  var tpl = this.tpl;
+  var cg = tpl.config;
+  if (!cg.lang_dir) {
+    return [];
+  }
+  var dirs = [cg.lang_dir.fullname(tpl.dir)];
+  if (!cg.theme_lang_dir) {
+    return dirs;
+  }
+  var themes = [];
+  if (cg.default_theme) {
+    themes.push(cg.default_theme);
+  }
+  if (tpl.current_theme && tpl.current_theme !== cg.default_theme) {
+    themes.push(tpl.current_theme);
+  }
+  for (var i = 0; i < themes.length; i++) {
+    dirs.push(cg.theme_lang_dir.fullname(tpl.getThemeDir(themes[i])));
+  }
+  return dirs;
+};
+
+/**
+ * 获取目录下的语言包文件
+ * @param {string} dir - 语言包目录
+ * @returns {Array<string>} 语言包文件路径列表，已排序
+ */
+Lang.prototype.getFiles = function (dir) {
+  if (!dir || !dir.hasDir()) {
+    return [];
+  }
+  var files = $.file.get(dir, '*.json');
+  var list = [];
+  for (var i = 0; i < files.length; i++) {
+    if (files[i].extname() === '.json') {
+      list.push(files[i]);
+    }
+  }
+  // 排序保证指纹稳定
+  return list.sort();
+};
+
+/**
+ * 获取语言包文件指纹
+ * 由文件路径与修改时间组成，文件新增、修改、删除都会使指纹变化
+ * @param {Array<string>} dirs - 语言包目录列表
+ * @returns {string} 指纹字符串
+ */
+Lang.prototype.getFingerprint = function (dirs) {
+  var list = [];
+  for (var i = 0; i < dirs.length; i++) {
+    var files = this.getFiles(dirs[i]);
+    for (var j = 0; j < files.length; j++) {
+      list.push(files[j] + ':' + TplUtil.getFileTime(files[j]));
+    }
+  }
+  return list.join('|');
+};
+
+/**
+ * 加载语言包文件
+ * 文件名即语言代码，后加载的目录覆盖先加载的目录
+ * 结果按文件指纹缓存，文件未变化时直接复用
+ * @param {boolean} force - 是否跳过缓存强制重新加载
+ * @returns {Object} 语言包字典
+ */
+Lang.prototype.loadFiles = function (force) {
+  var dirs = this.getDirs();
+  var key = dirs.join('|');
+  var fingerprint = this.getFingerprint(dirs);
+  var cache = this.tpl.constructor.lang_cache;
+  var item = cache[key];
+  // 文件未变化时复用缓存，返回副本避免调用方改动污染缓存
+  if (!force && item && item.fingerprint === fingerprint) {
+    return $.copy(item.dict);
+  }
+  var dict = {};
+  for (var i = 0; i < dirs.length; i++) {
+    var files = this.getFiles(dirs[i]);
+    for (var j = 0; j < files.length; j++) {
+      var f = files[j];
+      var lang = f.basename().replace('.json', '');
+      var data = f.loadJson();
+      if (!lang || !data || typeof (data) !== 'object') {
+        continue;
+      }
+      if (!dict[lang]) {
+        dict[lang] = {};
+      }
+      // 高优先级目录的相同词条覆盖低优先级目录
+      $.push(dict[lang], data, true);
+    }
+  }
+  cache[key] = {
+    fingerprint: fingerprint,
+    dict: $.copy(dict)
+  };
+  return dict;
+};
+
+/**
+ * 构建语言包字典
+ * 优先级从低到高：语言包文件、配置语言包
+ * @param {boolean} force - 是否跳过缓存强制重新加载语言包文件
+ * @returns {Object} 语言包字典
+ */
+Lang.prototype.buildDict = function (force) {
+  var dict = this.loadFiles(force);
+  var langs = this.tpl.config.langs;
+  if (langs && Object.keys(langs).length) {
+    $.push(dict, langs, true);
+  }
+  // 未配置任何语言包时，复用全局语言包字典
+  // 深拷贝后再用，避免实例上 lang.set() 写入时改到全局 $.lang.config，进而污染其他实例
+  if (!Object.keys(dict).length) {
+    dict = ($.lang && $.lang.config) ? $.copy($.lang.config) : {};
+  }
+  return Object.assign({}, dict);
+};
+
+/**
+ * 创建语言实例
+ * 语言包字典在实例间共享，仅当前语言各自独立
+ * @param {Object} config - 配置参数
+ * @param {boolean} force - 是否跳过语言包缓存强制重新加载
+ * @returns {BaseLang} 语言实例
+ */
+Lang.prototype.create = function (config, force) {
+  var dict = this.buildDict(force);
+  dict.default = config.default_lang || dict.default || 'zh_cn';
+  var lang = new BaseLang(dict);
+  this.registerPlural(lang, config.plural_rules);
+  return lang;
+};
+
+/**
+ * 登记复数规则
+ * BaseLang 内置规则仅覆盖 zh_cn、en，配置中的语言代码需显式登记才能按语言取复数形式
+ * @param {BaseLang} lang - 语言实例
+ * @param {Object} plural_rules - 复数规则，键为语言代码
+ */
+Lang.prototype.registerPlural = function (lang, plural_rules) {
+  var rules = plural_rules || {};
+  for (var code in rules) {
+    if (!lang.rules[code] && typeof (rules[code]) === 'function') {
+      lang.registerPlural(code, rules[code]);
+    }
+  }
+};
+
+module.exports = {
+  Lang
+};

package/lib/memory.js

@@ -0,0 +1,103 @@
+/**
+ * 内存存储
+ *
+ * 模板引擎的默认用户偏好存储，在内存中维护 user_id -> { style, lang } 映射。
+ * 与 SQLite 存储（Sqlite）实现同一契约、方法一一对应，
+ * 通过 new Tpl({ user_store: new Sqlite('tpl.db') }) 注入即可替换默认存储。
+ *
+ * 标识一律按字符串入表，故数字 1001 与字符串 '1001' 视为同一键。
+ * 进程重启后数据丢失。
+ *
+ * 存储契约（store）：
+ *   getUser(user_id) -> Object|null
+ *   setUser(user_id, prefs) -> Object
+ *   delUser(user_id) -> Boolean
+ *   hasUser(user_id) -> Boolean
+ *   listUsers() -> Array<String>
+ *   clear() -> Memory
+ * @class
+ */
+class Memory {
+  /**
+   * 构造函数
+   */
+  constructor() {
+    /**
+     * 用户偏好映射，user_id -> { style, lang }
+     */
+    this._users = new Map();
+  }
+}
+
+/**
+ * 写入用户偏好
+ * 同一用户重复写入时按字段合并，只更新本次传入的字段
+ * @param {String|Number} user_id - 用户标识
+ * @param {Object} prefs - 用户偏好，形如 { style, lang }
+ * @returns {Object} 保存后的偏好副本
+ */
+Memory.prototype.setUser = function (user_id, prefs) {
+  var key = this._key(user_id);
+  var record = this._users.get(key) || {};
+  var data = Object.assign({}, record, prefs);
+  this._users.set(key, data);
+  return Object.assign({}, data);
+};
+
+/**
+ * 读取用户偏好
+ * @param {String|Number} user_id - 用户标识
+ * @returns {Object|null} 用户偏好副本，未登记时返回 null
+ */
+Memory.prototype.getUser = function (user_id) {
+  var record = this._users.get(this._key(user_id));
+  return record ? Object.assign({}, record) : null;
+};
+
+/**
+ * 删除用户偏好
+ * @param {String|Number} user_id - 用户标识
+ * @returns {Boolean} 是否删除了已登记的用户
+ */
+Memory.prototype.delUser = function (user_id) {
+  return this._users.delete(this._key(user_id));
+};
+
+/**
+ * 判断用户是否已登记
+ * @param {String|Number} user_id - 用户标识
+ * @returns {Boolean} 是否已登记
+ */
+Memory.prototype.hasUser = function (user_id) {
+  return this._users.has(this._key(user_id));
+};
+
+/**
+ * 列出已登记的用户标识
+ * @returns {Array<String>} 用户标识数组
+ */
+Memory.prototype.listUsers = function () {
+  return Array.from(this._users.keys());
+};
+
+/**
+ * 清空全部用户偏好
+ * @returns {Memory} 当前实例
+ */
+Memory.prototype.clear = function () {
+  this._users.clear();
+  return this;
+};
+
+/**
+ * 统一存储键的表示（私有方法）
+ * @param {String|Number} user_id - 用户标识
+ * @returns {String} 文本标识
+ */
+Memory.prototype._key = function (user_id) {
+  return String(user_id);
+};
+
+module.exports = {
+  Memory
+};