mm_tpl 2.7.0 → 2.7.2

package/lib/sqlite.js

@@ -0,0 +1,176 @@
+const {
+  DatabaseSync
+} = require('node:sqlite');
+
+/**
+ * SQLite 存储
+ *
+ * 与内存存储（Memory）实现同一契约、方法一一对应，数据持久化到 SQLite 文件，
+ * 通过 new Tpl({ user_store: new Sqlite('tpl.db') }) 注入即可替换默认存储。
+ *
+ * 偏好按固定列存放（style / lang），写入时只更新本次传入的列，不触碰其他列，
+ * 且由单条 upsert 完成，无需读出整条再写回，故改一个字段不会影响另一个字段，
+ * 多个连接并发写同一文件时也不会互相覆盖。列可直接用于统计，例如
+ * SELECT style, COUNT(*) FROM users GROUP BY style。
+ *
+ * 标识一律按字符串入表，故数字 1001 与字符串 '1001' 视为同一键。
+ * 依赖 Node 内置的 node:sqlite（Node 22.5 起提供），低版本无法加载本模块。
+ *
+ * 初始化时若表不存在则自动建表。
+ *
+ * 存储契约（store）：
+ *   getUser(user_id) -> Object|null
+ *   setUser(user_id, prefs) -> Object
+ *   delUser(user_id) -> Boolean
+ *   hasUser(user_id) -> Boolean
+ *   listUsers() -> Array<String>
+ *   clear() -> Sqlite
+ * @class
+ */
+class Sqlite {
+  /**
+   * 构造函数
+   * @param {String} file - 数据库文件路径，缺省为 ':memory:'（进程退出即丢失）
+   */
+  constructor(file = ':memory:') {
+    /**
+     * 数据库连接
+     */
+    this._db = new DatabaseSync(file);
+    this._createTable();
+  }
+}
+
+/**
+ * 创建用户偏好表（私有方法）
+ * @returns {void}
+ */
+Sqlite.prototype._createTable = function () {
+  this._db.exec(
+    'CREATE TABLE IF NOT EXISTS users (' +
+    'user_id TEXT PRIMARY KEY NOT NULL, ' +
+    'style TEXT, ' +
+    'lang TEXT' +
+    ');'
+  );
+};
+
+/**
+ * 写入用户偏好
+ * 同一用户重复写入时按字段合并：本次传入的列取新值，未传入的列保持原值
+ * @param {String|Number} user_id - 用户标识
+ * @param {Object} prefs - 用户偏好，形如 { style, lang }
+ * @returns {Object} 保存后的偏好副本
+ */
+Sqlite.prototype.setUser = function (user_id, prefs) {
+  var data = prefs || {};
+  this._db
+    .prepare(
+      'INSERT INTO users(user_id, style, lang) VALUES(?, ?, ?) ' +
+      'ON CONFLICT(user_id) DO UPDATE SET ' +
+      'style = COALESCE(excluded.style, users.style), ' +
+      'lang = COALESCE(excluded.lang, users.lang)'
+    )
+    .run(this._key(user_id), this._val(data.style), this._val(data.lang));
+  return this.getUser(user_id);
+};
+
+/**
+ * 读取用户偏好
+ * 只返回已登记的字段，未登记时返回 null
+ * @param {String|Number} user_id - 用户标识
+ * @returns {Object|null} 用户偏好副本
+ */
+Sqlite.prototype.getUser = function (user_id) {
+  var row = this._db
+    .prepare('SELECT style, lang FROM users WHERE user_id = ?')
+    .get(this._key(user_id));
+  if (!row) {
+    return null;
+  }
+  var data = {};
+  if (row.style != null) {
+    data.style = row.style;
+  }
+  if (row.lang != null) {
+    data.lang = row.lang;
+  }
+  return data;
+};
+
+/**
+ * 删除用户偏好
+ * @param {String|Number} user_id - 用户标识
+ * @returns {Boolean} 是否删除了已登记的用户
+ */
+Sqlite.prototype.delUser = function (user_id) {
+  var result = this._db
+    .prepare('DELETE FROM users WHERE user_id = ?')
+    .run(this._key(user_id));
+  return result.changes > 0;
+};
+
+/**
+ * 判断用户是否已登记
+ * @param {String|Number} user_id - 用户标识
+ * @returns {Boolean} 是否已登记
+ */
+Sqlite.prototype.hasUser = function (user_id) {
+  var row = this._db
+    .prepare('SELECT 1 AS found FROM users WHERE user_id = ?')
+    .get(this._key(user_id));
+  return Boolean(row);
+};
+
+/**
+ * 列出已登记的用户标识
+ * @returns {Array<String>} 用户标识数组，按登记先后排列
+ */
+Sqlite.prototype.listUsers = function () {
+  var rows = this._db
+    .prepare('SELECT user_id FROM users ORDER BY rowid')
+    .all();
+  return rows.map(function (row) {
+    return row.user_id;
+  });
+};
+
+/**
+ * 清空全部用户偏好
+ * @returns {Sqlite} 当前实例
+ */
+Sqlite.prototype.clear = function () {
+  this._db.prepare('DELETE FROM users').run();
+  return this;
+};
+
+/**
+ * 关闭数据库连接
+ * @returns {void}
+ */
+Sqlite.prototype.close = function () {
+  this._db.close();
+};
+
+/**
+ * 统一存储键的表示（私有方法）
+ * @param {String|Number} user_id - 用户标识
+ * @returns {String} 文本标识
+ */
+Sqlite.prototype._key = function (user_id) {
+  return String(user_id);
+};
+
+/**
+ * 统一列值的绑定表示（私有方法）
+ * 未传入的字段绑定 null，交由 upsert 的 COALESCE 保留原值
+ * @param {String|undefined} value - 字段值
+ * @returns {String|null} 待绑定的值
+ */
+Sqlite.prototype._val = function (value) {
+  return (typeof (value) === 'string') ? value : null;
+};
+
+module.exports = {
+  Sqlite
+};

package/lib/template.js

@@ -0,0 +1,125 @@
+/**
+ * 模板文件加载器
+ * 模板按目录优先级覆盖：高优先级目录存在同名文件时覆盖低优先级目录的同名文件
+ * 模板目录链由引擎按「自定义目录、当前主题、默认主题」给出，主题目录下按功能划分，如 static/template/{主题}/article/list.html
+ * 组件目录链同构，只是每级多一个固定的组件子目录前缀，如 static/template/{主题}/component/bar.html
+ * @class
+ */
+class Template {
+  /**
+   * 创建模板文件加载器
+   * @param {Object} tpl - 所属模板实例
+   */
+  constructor(tpl) {
+    /**
+     * 所属模板实例
+     */
+    this.tpl = tpl;
+  }
+}
+
+/**
+ * 检查主题目录是否存在
+ * @param {string} theme - 主题名称
+ * @returns {boolean} 主题目录是否存在
+ */
+Template.prototype.hasTheme = function (theme) {
+  if (!theme) {
+    return false;
+  }
+  return this.tpl.getThemeDir(theme).hasDir();
+};
+
+/**
+ * 检查风格目录是否存在
+ * 当前主题或默认主题下存在该风格即视为有效
+ * @param {string} style - 风格名称
+ * @returns {boolean} 风格目录是否存在
+ */
+Template.prototype.hasStyle = function (style) {
+  if (!style) {
+    return false;
+  }
+  var tpl = this.tpl;
+  var cg = tpl.config;
+  var themes = [tpl.current_theme];
+  if (cg.default_theme && cg.default_theme !== tpl.current_theme) {
+    themes.push(cg.default_theme);
+  }
+  for (var i = 0; i < themes.length; i++) {
+    if (themes[i] && tpl.getStyleDir(themes[i], style).hasDir()) {
+      return true;
+    }
+  }
+  return false;
+};
+
+/**
+ * 补全文件扩展名
+ * 入参已带其他扩展名或已带模板扩展名时保持原样
+ * @param {string} file - 文件名
+ * @returns {string} 补全后的文件名
+ */
+Template.prototype._fixExt = function (file) {
+  var cg = this.tpl.config;
+  if (file.replace('./', '').indexOf('.') === -1 && !file.endsWith(cg.extname)) {
+    return file + cg.extname;
+  }
+  return file;
+};
+
+/**
+ * 按目录优先级搜索文件
+ * @param {string} file - 文件名
+ * @param {Array<string>} dirs - 目录列表，顺序即优先级，为空时视为未命中
+ * @returns {string} 命中的文件全路径；未命中时返回最后一个候选路径，其 hasFile() 为 false
+ */
+Template.prototype._locate = function (file, dirs) {
+  if (!dirs.length) {
+    // 返回不存在的路径，交由调用方按 hasFile() 判断
+    return file.fullname(this.tpl.dir) + '.not-exist';
+  }
+  var f = file.fullname(dirs[0]);
+  for (var i = 1; i < dirs.length && !f.hasFile(); i++) {
+    f = file.fullname(dirs[i]);
+  }
+  return f;
+};
+
+/**
+ * 获取模板文件
+ * 按目录优先级从高到低搜索，返回第一个存在的文件
+ * options.dir 指定时只在该目录查找，用于主题体系外的模板
+ * @param {string} file - 模板文件路径
+ * @param {Object} options - 配置参数，dir 为指定的查找目录
+ * @returns {string} 模板文件路径
+ */
+Template.prototype.getFile = function (file, options) {
+  if (typeof (file) !== 'string') {
+    throw new Error('模板文件路径必须是字符串');
+  }
+  file = this._fixExt(file);
+  var dirs = (options && options.dir) ? [options.dir.fullname(this.tpl.dir)] : this.tpl.getTemplateDirs();
+  return this._locate(file, dirs);
+};
+
+/**
+ * 获取组件文件
+ * 组件名相对组件目录解析，省略扩展名时自动补全；名称指向组件目录内的路径，可含子目录，如 article/card
+ * 组件名不相对调用方所在文件解析，而是沿组件目录链查找
+ * @param {string} name - 组件名称，如 bar、article/card
+ * @param {Object} options - 配置参数，dir 为指定的查找目录
+ * @returns {string} 组件文件路径
+ */
+Template.prototype.getComponent = function (name, options) {
+  if (typeof (name) !== 'string') {
+    throw new Error('组件名称必须是字符串');
+  }
+  var file = this._fixExt(name.replace(/^\.\//, ''));
+  var dirs = (options && options.dir) ? [options.dir.fullname(this.tpl.dir)] : this.tpl.getComponentDirs();
+  return this._locate(file, dirs);
+};
+
+module.exports = {
+  Template
+};

package/lib/tpl_rule.js

@@ -0,0 +1,288 @@
+'use strict';
+
+/**
+ * 原生模板语法规则
+ * @type {Object}
+ */
+var nativeRule = {
+  test: /[ \t\r\n]*<!--\[(#?)((?:==|=#|[=-])?)[ \t]*([\w\W]*?)[ \t]*(-?)\]-->/,
+
+  /**
+   * 处理原生模板语法
+   * @param {string} match - 匹配的字符串
+   * @param {string} comment - 注释标记
+   * @param {string} output - 输出类型
+   * @param {string} code - 代码内容
+   * @returns {Object} 处理结果
+   */
+  use: function use(match, comment, output, code /*, trimMode*/) {
+    output = {
+      '-': 'raw',
+      '=': 'escape',
+      '': false,
+      // v3 compat: raw output
+      '==': 'raw',
+      '=#': 'raw'
+    }[output];
+
+    // ejs compat: comment tag
+    if (comment) {
+      code = '/*' + code + '*/';
+      output = false;
+    }
+
+    // ejs compat: trims following newline
+    // if (trimMode) {}
+
+    return {
+      code: code,
+      output: output
+    };
+  }
+};
+
+/**
+ * 简洁模板语法规则
+ * @type {Object}
+ */
+var artRule = {
+  // 表达式内允许出现非嵌套的对象字面量，如 ${@$component('bar', { id: 1 })}
+  // 若只用 [\w\W]*? 会停在第一个 } 上，把对象字面量截断成语法错误
+  test: /[ \t\r\n]*\$\{([@#]?)[ \t]*(\/?)((?:[^{}]|\{[^{}]*\})*?)[ \t]*\}/,
+
+  /**
+   * 处理简洁模板语法
+   * @param {string} match - 匹配的字符串
+   * @param {string} raw - 原始输出标记
+   * @param {string} close - 闭合标记
+   * @param {string} code - 代码内容
+   * @returns {Object} 处理结果
+   */
+  use(match, raw, close, code) {
+    var compiler = this;
+    var options = compiler.options;
+    var esTokens = compiler.getEsTokens(code);
+    var values = esTokens.map(function (token) {
+      return token.value;
+    });
+    var result = {};
+
+    var group = void 0;
+    var output = raw ? 'raw' : false;
+    var key = close + values.shift();
+
+    // 旧版语法升级提示
+    var warn = function warn(oldSyntax, newSyntax) {
+      $.log.warn((options.filename || 'anonymous') + ':' + (match.line + 1) + ':' + (match.start + 1) + '\n' + (
+        'Template upgrade: ${' + oldSyntax + '} -> ${' + newSyntax + '}'));
+    };
+
+    // v3 compat: #value
+    if (raw === '#') {
+      warn('#value', '@value');
+    }
+
+    switch (key) {
+      case 'set':
+        code = 'var ' + values.join('').trim();
+        break;
+
+      case 'if':
+        code = 'if(' + values.join('').trim() + '){';
+        break;
+
+      case 'else':
+        var indexIf = values.indexOf('if');
+
+        if (~indexIf) {
+          values.splice(0, indexIf + 1);
+          code = '}else if(' + values.join('').trim() + '){';
+        } else {
+          code = '}else{';
+        }
+
+        break;
+
+      case '/if':
+        code = '}';
+        break;
+
+      case 'loop':
+      case 'each':
+        group = artRule._split(esTokens);
+        group.shift();
+
+        if (group[1] === 'as') {
+          // ... v3 compat ...
+          warn('each object as value index', 'each object value index');
+          group.splice(1, 1);
+        }
+
+        var object = group[0] || '$data';
+        var value = group[1] || '$value';
+        var index = group[2] || '$index';
+
+        code = '$each(' + object + ',function(' + value + ',' + index + '){';
+
+        break;
+
+      case '/loop':
+      case '/each':
+        code = '})';
+        break;
+
+      case 'block':
+        group = artRule._split(esTokens);
+        group.shift();
+        code = 'block(' + group.join(',').trim() + ',function(){';
+        break;
+
+      case '/block':
+        code = '})';
+        break;
+
+      case 'echo':
+        key = 'print';
+        warn('echo value', 'value');
+      case 'print':
+      case 'include':
+      case 'extend':
+        if (values.join('').trim().indexOf('(') !== 0) {
+          // 执行函数省略 `()` 与 `,`
+          group = artRule._split(esTokens);
+          group.shift();
+          code = key + '(' + group.join(',') + ')';
+          break;
+        }
+
+      default:
+        if (~values.indexOf('|')) {
+          var v3split = ':'; // ... v3 compat ...
+
+          // 将过滤器解析成二维数组
+          var _group = esTokens.reduce(function (group, token) {
+            var value = token.value,
+              type = token.type;
+
+            if (value === '|') {
+              group.push([]);
+            } else if (type !== 'whitespace' && type !== 'comment') {
+              if (!group.length) {
+                group.push([]);
+              }
+              if (value === v3split && group[group.length - 1].length === 1) {
+                warn('value | filter: argv', 'value | filter argv');
+              } else {
+                group[group.length - 1].push(token);
+              }
+            }
+            return group;
+          }, []).map(function (g) {
+            return artRule._split(g);
+          });
+
+          // 将过滤器管道化
+          code = _group.reduce(function (accumulator, filter) {
+            var name = filter.shift();
+            filter.unshift(accumulator);
+
+            return '$imports.' + name + '(' + filter.join(',') + ')';
+          }, _group.shift().join(' ').trim());
+        }
+
+        output = output || 'escape';
+
+        break;
+    }
+
+    result.code = code;
+    result.output = output;
+    return result;
+  },
+
+  /**
+   * 将多个javascript表达式拆分成组
+   * @param {Array} esTokens - ES令牌数组
+   * @returns {Array} 分组后的表达式数组
+   */
+  _split: function _split(esTokens) {
+    esTokens = esTokens.filter(function (_ref) {
+      var type = _ref.type;
+
+      return type !== 'whitespace' && type !== 'comment';
+    });
+
+    var current = 0;
+    var lastToken = esTokens.shift();
+    var punctuator = 'punctuator';
+    var close = /\]|\)/;
+    var group = [
+      [lastToken]
+    ];
+
+    while (current < esTokens.length) {
+      var esToken = esTokens[current];
+
+      if (esToken.type === punctuator || lastToken.type === punctuator && !close.test(lastToken.value)) {
+        group[group.length - 1].push(esToken);
+      } else {
+        group.push([esToken]);
+      }
+
+      lastToken = esToken;
+
+      current++;
+    }
+
+    return group.map(function (g) {
+      return g.map(function (g) {
+        return g.value;
+      }).join('');
+    });
+  }
+};
+
+/**
+ * HTML注释模板语法规则
+ * @type {Object}
+ */
+var htmlRule = Object.assign({}, artRule, {
+  test: /[ \t\r\n]*<!--\{([@#]?)[ \t]*(\/?)([\w\W]*?)[ \t]*\}-->/
+});
+
+/**
+ * JS注释模板语法规则
+ * @type {Object}
+ */
+var jsRule = Object.assign({}, artRule, {
+  test: /[ \t\r\n]*\/\*\[([@#]?)[ \t]*(\/?)([\w\W]*?)[ \t]*\]\*\//
+});
+
+/**
+ * Python注释模板语法规则
+ * @type {Object}
+ */
+var pyRule = Object.assign({}, artRule, {
+  test: /[ \t\r\n]*##([@#]?)[ \t]*(\/?)([\w\W]*?)[ \t]*##/
+});
+
+/**
+ * Python三引号注释模板语法规则
+ * @type {Object}
+ */
+var pyRule2 = Object.assign({}, artRule, {
+  test: /"""#([@#]?)[ \t]*(\/?)([\w\W]*?)[ \t]*#"""/
+});
+
+module.exports = {
+  htmlRule,
+  jsRule,
+  artRule,
+  nativeRule,
+  pyRule,
+  pyRule2
+};
+
+
+
+

package/lib/util.js

@@ -0,0 +1,79 @@
+const fs = require('fs');
+
+/**
+ * 模板工具类
+ * 收纳与实例状态无关的纯辅助函数，全部以静态方法提供
+ * @class
+ */
+class TplUtil {
+  /**
+   * 获取文件修改时间
+   * @param {string} file - 文件路径
+   * @returns {number} 修改时间戳，取不到时返回0
+   */
+  static getFileTime(file) {
+    try {
+      return fs.statSync(file).mtimeMs;
+    } catch {
+      return 0;
+    }
+  }
+
+  /**
+   * 转义正则表达式特殊字符
+   * @param {string} str - 原始字符串
+   * @returns {string} 转义后的字符串
+   */
+  static escapeRegExp(str) {
+    return str.replace('\\', '\\\\').replace('$', '\\$').replace('[', '\\[').replace(']', '\\]')
+      .replace('{', '\\{').replace('}', '\\}').replace('/', '\\/').replace('*', '\\*');
+  }
+
+  /**
+   * 构建字符转义规则
+   * 转义时把语法字符替换为中间字符，渲染后再还原，避免与模板语法冲突
+   * @param {Array<string>} change_str - 需要转义与还原的字符串列表
+   * @returns {Object} 转义规则，含 regex_in、str_in、regex_out、str_out
+   */
+  static buildEscapeRule(change_str) {
+    var rule = {
+      regex_in: [],
+      str_in: [],
+      regex_out: [],
+      str_out: []
+    };
+    var lt = change_str || [];
+    for (var i = 0; i < lt.length; i++) {
+      var str = lt[i];
+      rule.regex_in.push(new RegExp(TplUtil.escapeRegExp(str), 'gi'));
+      var str_in = str.split('').join('·') + '·';
+      rule.str_in.push(str_in);
+      rule.regex_out.push(new RegExp(TplUtil.escapeRegExp(str_in), 'gi'));
+      rule.str_out.push(str.replace('\\', ''));
+    }
+    return rule;
+  }
+
+  /**
+   * 转义或还原字符串
+   * @param {string} body - 字符串
+   * @param {Object} rule - 转义规则
+   * @param {boolean} restore - 是否还原
+   * @returns {string} 处理后的字符串
+   */
+  static escape(body, rule, restore) {
+    if (!body) {
+      return body;
+    }
+    var rx = restore ? rule.regex_out : rule.regex_in;
+    var st = restore ? rule.str_out : rule.str_in;
+    for (var i = 0; i < rx.length; i++) {
+      body = body.replace(rx[i], st[i]);
+    }
+    return body;
+  }
+}
+
+module.exports = {
+  TplUtil
+};

package/package.json

@@ -1,10 +1,13 @@
 {
     "name": "mm_tpl",
-    "version": "2.7.0",
+    "version": "2.7.2",
     "description": "Super Meimei Template Engine - High-performance template engine based on art-template with MVC pattern, hook system, theme switching and caching mechanism",
     "main": "index.js",
+    "io": true,
+    "priority": 100,
     "scripts": {
         "dev": "nodemon test.js",
+        "demo": "node example/demo.js",
         "test": "node test.js",
         "coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage"
     },
@@ -13,6 +16,9 @@
         "url": "git+https://gitee.com/qiuwenwu91/mm_tpl.git"
     },
     "keywords": [
+        "mm_mod",
+        "mm_infra",
+        "mm_web",
         "template",
         "engine",
         "mvc",
@@ -34,7 +40,7 @@
     "homepage": "https://gitee.com/qiuwenwu91/mm_tpl#readme",
     "dependencies": {
         "art-template": "^4.13.4",
-        "mm_expand": "^2.5.3"
+        "mm_expand": "^2.5.4"
     },
     "engines": {
         "node": ">=12.0.0"
@@ -43,8 +49,14 @@
         "index.js",
         "hook.js",
         "tpl_rule.js",
+        "lib/",
+        "doc/",
         "README.md",
         "README_EN.md",
         "package.json"
-    ]
+    ],
+    "devDependencies": {
+        "eslint": "^9.39.5",
+        "eslint-plugin-jsdoc": "^65.0.0"
+    }
 }