mm_lang 2.0.0 → 3.0.1

package/lib/langs.js

@@ -1,32 +1,32 @@
-const KvStore = require('mm_kv_store').KvStore;
-
-/**
- * 语言存储类，键和值都只能是字符串
- * 由原 mm_langs 模块融合而来，作为多语言模块的数据侧：只负责键值管理与持久化，
- * 不感知语言词条的嵌套语义（嵌套结构的适配由 lib/store.js 承担）
- * @class
- * @augments {KvStore}
- */
-class Langs extends KvStore {
-  /**
-   * 获取存储项名称，用于覆盖冲突提示
-   * @returns {string} 存储项名称
-   */
-  _getName() {
-    return 'langs';
-  }
-
-  /**
-   * 校验值是否为字符串
-   * @param {*} value 值
-   * @returns {void}
-   * @throws {TypeError} 值不是字符串时抛出
-   */
-  _checkValue(value) {
-    if (typeof value !== 'string') {
-      throw new TypeError('langs 的值必须是字符串');
-    }
-  }
-}
-
-module.exports = Langs;
+const KvStore = require('mm_kv_store').KvStore;
+
+/**
+ * 语言存储类，键和值都只能是字符串
+ * 由原 mm_langs 模块融合而来，作为多语言模块的数据侧：只负责键值管理与持久化，
+ * 不感知语言词条语义（Lang 侧内存词条同为扁平 string→string 形态，两侧无需结构转换）
+ * @class
+ * @augments {KvStore}
+ */
+class Langs extends KvStore {
+  /**
+   * 获取存储项名称，用于覆盖冲突提示
+   * @returns {string} 存储项名称
+   */
+  _getName() {
+    return 'langs';
+  }
+
+  /**
+   * 校验值是否为字符串
+   * @param {*} value 值
+   * @returns {void}
+   * @throws {TypeError} 值不是字符串时抛出
+   */
+  _checkValue(value) {
+    if (typeof value !== 'string') {
+      throw new TypeError('langs 的值必须是字符串');
+    }
+  }
+}
+
+module.exports = Langs;

package/lib/langs_admin.js

@@ -0,0 +1,13 @@
+const { reg } = require('mm_admin');
+const Langs = require('./langs.js');
+
+/**
+ * 语言存储实例管理器（数据侧）
+ * 独立成模块以便 lib/lang.js 引用而不产生循环依赖
+ * Lang 配置 file 时以文件路径为作用域键从管理器取实例，相同文件的 Lang 复用同一存储
+ * @type {Admin}
+ */
+const langs_admin = reg('lang.langs');
+langs_admin.setClass(Langs);
+
+module.exports = langs_admin;

package/lib/tools/index.js

@@ -0,0 +1,16 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+/** 模块能力层：懒加载工具实现，避免模块入口被 require 时加载全部实现 */
+module.exports = new Proxy({}, {
+  get(_t, key) {
+    if (typeof key !== 'string') return undefined;
+    if (!fs.existsSync(path.join(__dirname, key, 'index.js'))) return undefined;
+    return require('./' + key);
+  },
+  has(_t, key) {
+    return typeof key === 'string' && fs.existsSync(path.join(__dirname, key, 'index.js'));
+  },
+  ownKeys() { return fs.readdirSync(__dirname, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name); },
+  getOwnPropertyDescriptor(_t, key) { return this.has(_t, key) ? { enumerable: true, configurable: true } : undefined; }
+});

package/lib/tools/lang/index.js

@@ -0,0 +1,59 @@
+'use strict';
+/**
+ * lang —— 多语言词条工具
+ * 复用模块 Lang 实例：层级键解析、回退链与格式化都由模块维护。
+ */
+const { langAdmin } = require('../../../index.js');
+
+async function main(params, ctx, options) {
+  void options;
+  const p = params || {};
+  const action = p.action || 't';
+  const done = (data) => { ctx.output = data; return data; };
+
+  try {
+    const lang = langAdmin(p.scope || 'os');
+
+    if (action === 't') {
+      if (!p.key) throw new TypeError('key 不能为空');
+      const text = lang.t(p.key, p.params || {}, p.lang);
+      return done({ code: 0, msg: '成功', key: p.key, text: String(text) });
+    }
+
+    if (action === 'get') {
+      return done({ code: 0, msg: '成功', lang: p.lang || '', value: lang.get(p.lang || undefined) });
+    }
+
+    if (action === 'set') {
+      if (!p.key) throw new TypeError('key 不能为空');
+      if (typeof p.value !== 'string') throw new TypeError('value 必须是字符串');
+      lang.set(p.key, p.value, p.lang);
+      if (typeof lang.save === 'function') lang.save();
+      return done({ code: 0, msg: '写入成功', key: p.key });
+    }
+
+    if (action === 'del') {
+      if (!p.key) throw new TypeError('key 不能为空');
+      const deleted = lang.del(p.key, p.lang);
+      if (typeof lang.save === 'function') lang.save();
+      return done({ code: 0, msg: deleted ? '删除成功' : '词条不存在', key: p.key, deleted: !!deleted });
+    }
+
+    if (action === 'langs') {
+      const langs = lang.getLangs();
+      const list = Array.isArray(langs) ? langs : Object.keys(langs || {});
+      return done({ code: 0, msg: '成功', count: list.length, langs: list });
+    }
+
+    if (action === 'save') {
+      lang.save();
+      return done({ code: 0, msg: '已落盘', ok: true });
+    }
+
+    return done({ code: 10001, msg: '不支持的操作: ' + action });
+  } catch (error) {
+    return done({ code: 10000, msg: '执行失败：' + error.message, error: { name: error.name, message: error.message } });
+  }
+}
+
+module.exports = { main };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mm_lang",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "description": "超级美眉多语言模块：融合 i18n 行为（Lang）与语言存储持久化（Langs），支持层级键、回退链、复数、格式化与 JSON 文件落盘",
   "main": "index.js",
   "repository": {
@@ -18,8 +18,8 @@
     "多语言",
     "语言包"
   ],
-  "layer": "infra",
-  "group": "data",
+  "layer": "infrastructure",
+  "group": "state",
   "author": "邱文武",
   "license": "ISC",
   "scripts": {
@@ -27,7 +27,7 @@
     "example": "node example/index.js"
   },
   "dependencies": {
-    "mm_corejs": "^1.1.6",
+    "mm_admin": "^1.1.0",
     "mm_kv_store": "^1.0.1"
   },
   "files": [
@@ -35,6 +35,7 @@
     "lib",
     "example",
     "README.md",
-    "package.json"
+    "package.json",
+    "tool"
   ]
 }

package/tool/lang/index.js

@@ -0,0 +1,7 @@
+'use strict';
+/**
+ * lang —— 工具契约适配层
+ * 业务实现归位于模块 lib/tools/lang/，本文件只把模块能力暴露给加载器。
+ * 其它模块可直接 require('mm_lang').tools.lang 复用。
+ */
+module.exports = require('../../lib/tools/lang');

package/tool/lang/tool.json

@@ -0,0 +1,84 @@
+{
+  "name": "lang",
+  "title": "多语言词条",
+  "description": "基于 mm_lang 的多语言能力：按语言取词条（支持层级键与格式化）、写入/删除词条、列出支持语言、落盘。适用场景：生成多语言文案、补词条、核对某语言是否支持。工作流提示：t 按 key 取词，key 用层级点号（如 common.save）；params 用于 {name} 之类占位。",
+  "category": "多语言",
+  "group": "i18n",
+  "type": "function",
+  "main": "./index.js",
+  "params": {
+    "type": "object",
+    "properties": {
+      "action": {
+        "type": "string",
+        "description": "操作类型: t(取词条)/get(读整表)/set(写词条)/del(删词条)/langs(支持语言)/save(落盘)",
+        "enum": [
+          "t",
+          "get",
+          "set",
+          "del",
+          "langs",
+          "save"
+        ],
+        "default": "t"
+      },
+      "key": {
+        "type": "string",
+        "description": "词条键(get/del/t 必填，支持 a.b.c 层级)"
+      },
+      "value": {
+        "type": "string",
+        "description": "词条文案(set 必填)"
+      },
+      "lang": {
+        "type": "string",
+        "description": "语言标识，缺省取实例默认语言"
+      },
+      "params": {
+        "type": "object",
+        "description": "占位参数(t 可选)"
+      },
+      "scope": {
+        "type": "string",
+        "description": "实例作用域，缺省 os",
+        "default": "os"
+      }
+    },
+    "required": [
+      "action"
+    ]
+  },
+  "returns": {
+    "type": "object",
+    "properties": {
+      "code": {
+        "type": "number",
+        "description": "0 表示成功，1xxxx 表示业务/执行异常"
+      },
+      "msg": {
+        "type": "string",
+        "description": "结果描述"
+      },
+      "text": {
+        "type": "string",
+        "description": "词条文案(t)"
+      },
+      "value": {
+        "description": "整表或单条值(get)"
+      },
+      "langs": {
+        "type": "array",
+        "description": "支持语言列表(langs)"
+      },
+      "count": {
+        "type": "number",
+        "description": "数量"
+      },
+      "error": {
+        "type": "object",
+        "description": "异常对象 { name, message }"
+      }
+    }
+  },
+  "handler": "manager"
+}

package/lib/store.js

@@ -1,190 +0,0 @@
-/**
- * 语言词条持久化适配层
- * @description 承担"动作侧适配"职责：把 Lang 的嵌套词条字典与 Langs 的
- * string→string 扁平键值互相转换。文件读写、键值校验等存储细节全部由 Langs 负责，
- * 本文件不触碰 fs。
- */
-
-const Langs = require('./langs');
-
-/**
- * 非词条的控制键，不参与扁平化与持久化
- * @type {Array<string>}
- */
-const CONTROL_KEYS = ['default', 'fallback', 'locale', 'options', 'file', 'store', 'silent'];
-
-/**
- * 非字符串词条（复数数组等）的标记前缀
- * 落盘后仍是字符串，满足 Langs 的 string→string 约束；读取时按前缀还原
- * @type {string}
- */
-const MARK = '\u0001';
-
-/**
- * 判断是否为控制键
- * @param {string} key 键名
- * @returns {boolean} 是控制键返回 true
- */
-function isControlKey(key) {
-  return CONTROL_KEYS.indexOf(key) !== -1;
-}
-
-/**
- * 将词条值序列化为存储字符串
- * @param {*} val 词条值
- * @returns {string|null} 存储字符串，不可序列化的值返回 null
- */
-function encodeValue(val) {
-  if (typeof (val) === 'string') {
-    return val;
-  }
-  if (Array.isArray(val)) {
-    return MARK + JSON.stringify(val);
-  }
-  if (typeof (val) === 'number' || typeof (val) === 'boolean') {
-    return String(val);
-  }
-  return null;
-}
-
-/**
- * 将存储字符串还原为词条值
- * @param {string} val 存储字符串
- * @returns {*} 词条值
- */
-function decodeValue(val) {
-  if (typeof (val) !== 'string') {
-    return val;
-  }
-  if (val.charAt(0) === MARK) {
-    try {
-      return JSON.parse(val.slice(1));
-    } catch (e) {
-      return val;
-    }
-  }
-  return val;
-}
-
-/**
- * 嵌套词条字典扁平化为 string→string 键值
- * 键形如 `语言代码.层级键`，复数数组等非字符串值按 MARK 前缀编码
- * @param {Object} dict 嵌套词条字典
- * @param {string} [prefix] 键前缀
- * @param {Object} [out] 输出容器
- * @returns {Object} 扁平键值表
- */
-function flatten(dict, prefix, out) {
-  var flat = out || {};
-  if (!dict || typeof (dict) !== 'object') {
-    return flat;
-  }
-  for (var key in dict) {
-    if (!Object.prototype.hasOwnProperty.call(dict, key)) {
-      continue;
-    }
-    if (!prefix && isControlKey(key)) {
-      continue;
-    }
-    var val = dict[key];
-    var path = prefix ? prefix + '.' + key : key;
-    if (val && typeof (val) === 'object' && !Array.isArray(val)) {
-      flatten(val, path, flat);
-    } else {
-      var str = encodeValue(val);
-      if (str !== null) {
-        flat[path] = str;
-      }
-    }
-  }
-  return flat;
-}
-
-/**
- * 按点号路径向对象写入值
- * @param {Object} obj 目标对象
- * @param {string} path 点号路径
- * @param {*} val 值
- * @returns {void}
- */
-function setByPath(obj, path, val) {
-  var keys = path.split('.');
-  var cur = obj;
-  for (var i = 0; i < keys.length - 1; i++) {
-    if (!cur[keys[i]] || typeof (cur[keys[i]]) !== 'object') {
-      cur[keys[i]] = {};
-    }
-    cur = cur[keys[i]];
-  }
-  cur[keys[keys.length - 1]] = val;
-}
-
-/**
- * 扁平键值还原为嵌套词条字典
- * @param {Object} flat 扁平键值表
- * @returns {Object} 嵌套词条字典
- */
-function unflatten(flat) {
-  var dict = {};
-  if (!flat || typeof (flat) !== 'object') {
-    return dict;
-  }
-  for (var path in flat) {
-    if (!Object.prototype.hasOwnProperty.call(flat, path)) {
-      continue;
-    }
-    setByPath(dict, path, decodeValue(flat[path]));
-  }
-  return dict;
-}
-
-/**
- * 深度合并词条字典，来源值覆盖目标值
- * @param {Object} target 目标字典
- * @param {Object} source 来源字典
- * @returns {Object} 合并后的目标字典
- */
-function assignDeep(target, source) {
-  for (var key in source) {
-    if (!Object.prototype.hasOwnProperty.call(source, key)) {
-      continue;
-    }
-    var val = source[key];
-    if (val && typeof (val) === 'object' && !Array.isArray(val)
-      && target[key] && typeof (target[key]) === 'object' && !Array.isArray(target[key])) {
-      assignDeep(target[key], val);
-    } else {
-      target[key] = val;
-    }
-  }
-  return target;
-}
-
-/**
- * 创建语言存储实例
- * 优先复用外部注入的实例（动作与数据解耦），其次按文件路径新建，都没有则返回 null
- * @param {Langs} [injected] 注入的存储实例
- * @param {string} [file] 持久化文件路径
- * @returns {Langs|null} 存储实例
- */
-function createStore(injected, file) {
-  if (injected && typeof (injected.set) === 'function' && typeof (injected.save) === 'function') {
-    return injected;
-  }
-  if (file) {
-    return new Langs({ file: file });
-  }
-  return null;
-}
-
-module.exports = {
-  CONTROL_KEYS,
-  MARK,
-  isControlKey,
-  encodeValue,
-  decodeValue,
-  flatten,
-  unflatten,
-  assignDeep,
-  createStore
-};