mm_tpl 2.7.1 → 2.7.3

package/lib/sqlite.js

@@ -0,0 +1,174 @@
+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,129 @@
+const {
+  FileUtil
+} = require('./file.js');
+
+/**
+ * 模板文件加载器
+ * 模板按目录优先级覆盖：高优先级目录存在同名文件时覆盖低优先级目录的同名文件
+ * 模板目录链由引擎按「自定义目录、当前主题、默认主题」给出，主题目录下按功能划分，如 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 FileUtil.hasDir(this.tpl.getThemeDir(theme));
+};
+
+/**
+ * 检查风格目录是否存在
+ * 当前主题或默认主题下存在该风格即视为有效
+ * @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] && FileUtil.hasDir(tpl.getStyleDir(themes[i], style))) {
+      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} 命中的文件全路径；未命中时返回最后一个候选路径，其 FileUtil.hasFile 为 false
+ */
+Template.prototype._locate = function (file, dirs) {
+  if (!dirs.length) {
+    // 返回不存在的路径，交由调用方按 FileUtil.hasFile 判断
+    return FileUtil.fullname(file, this.tpl.dir) + '.not-exist';
+  }
+  var f = FileUtil.fullname(file, dirs[0]);
+  for (var i = 1; i < dirs.length && !FileUtil.hasFile(f); i++) {
+    f = FileUtil.fullname(file, 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) ? [FileUtil.fullname(options.dir, 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) ? [FileUtil.fullname(options.dir, this.tpl.dir)] : this.tpl.getComponentDirs();
+  return this._locate(file, dirs);
+};
+
+module.exports = {
+  Template
+};