mm_lang 3.0.0 → 3.0.1

package/lib/lang.js

@@ -2,8 +2,7 @@
  * 内置语言类
  * 国际化(i18n)核心：扁平词条表上的取词、回退、复数与格式化
  * 词条表与持久化同构：内存即 `语言代码.层级键 → 文本` 的扁平形态，save/load 无需转换
- * 只接受扁平入参（键为 `语言.层级键`，或 default/fallback/locale/silent/file/store 控制键），
- * 嵌套语言包由调用方展开（mm_tpl 在加载语言包文件后自行扁平化）
+ * 只接受扁平入参（键为 `语言.层级键`，或控制键），嵌套语言包由调用方展开（如 mm_tpl）
  * 持久化通过 langsAdmin 管理的 Langs 存储实例（this.store）完成，本类不做文件 IO
  * @class
  */
@@ -34,40 +33,46 @@ function isControlKey(key) {
 }
 
 /**
- * 将词条值编码为可落盘的字符串
+ * 校验参数为非空字符串，否则抛出类型错误
+ */
+function checkKey(val, name) {
+  if (!val || typeof val !== 'string') {
+    throw new TypeError(name + '必须是字符串');
+  }
+}
+
+/**
+ * 将词条值编码为可落盘的字符串（数组加标记后 JSON 化；数字/布尔转字符串）
  * @param {*} val 词条值
  * @returns {string|null} 存储字符串，不可序列化的值返回 null
  */
 function encodeValue(val) {
-  if (typeof (val) === 'string') {
+  if (typeof val === 'string') {
     return val;
   }
   if (Array.isArray(val)) {
     return MARK + JSON.stringify(val);
   }
-  if (typeof (val) === 'number' || typeof (val) === 'boolean') {
+  if (typeof val === 'number' || typeof val === 'boolean') {
     return String(val);
   }
   return null;
 }
 
 /**
- * 将落盘字符串还原为词条值
+ * 将落盘字符串还原为词条值（带标记前缀的还原为数组）
  * @param {string} val 存储字符串
  * @returns {*} 词条值
  */
 function decodeValue(val) {
-  if (typeof (val) !== 'string') {
+  if (typeof val !== 'string' || val.charAt(0) !== MARK) {
     return val;
   }
-  if (val.charAt(0) === MARK) {
-    try {
-      return JSON.parse(val.slice(1));
-    } catch (e) {
-      return val;
-    }
+  try {
+    return JSON.parse(val.slice(1));
+  } catch (e) {
+    return val;
   }
-  return val;
 }
 
 /**
@@ -81,14 +86,24 @@ 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' || Array.isArray(cur[keys[i]])) {
-      cur[keys[i]] = {};
+    var next = cur[keys[i]];
+    if (!next || typeof next !== 'object' || Array.isArray(next)) {
+      next = cur[keys[i]] = {};
     }
-    cur = cur[keys[i]];
+    cur = next;
   }
   cur[keys[keys.length - 1]] = val;
 }
 
+/**
+ * 两位数补零
+ * @param {number} n 数值
+ * @returns {string} 补零后的字符串
+ */
+function pad(n) {
+  return String(n).padStart(2, '0');
+}
+
 class Lang {
   /**
    * 创建语言实例
@@ -96,32 +111,29 @@ class Lang {
    *   可含控制键 default、fallback、locale、silent 及存储配置 file、store
    */
   constructor(config = {}) {
-    var cg = Object.assign({}, config);
+    var cg = Object.assign({
+      default: 'zh_cn',
+      fallback: true
+    }, config);
     var file = cg.file || '';
     var injected = cg.store;
     delete cg.file;
     delete cg.store;
 
-    /**
-     * 扁平词条表，键为 `语言代码.层级键`，与持久化格式一致；控制键并存于同一层
-     * @type {Object}
-     */
-    this.config = Object.assign({
-      default: 'zh_cn',
-      fallback: true
-    }, cg);
-
     // 词条值不能是嵌套对象，嵌套语言包需由调用方展开为扁平键
-    for (var key in this.config) {
-      if (!Object.prototype.hasOwnProperty.call(this.config, key) || isControlKey(key)) {
-        continue;
-      }
-      var val = this.config[key];
-      if (val && typeof (val) === 'object' && !Array.isArray(val)) {
+    for (var key in cg) {
+      var val = cg[key];
+      if (!isControlKey(key) && val && typeof val === 'object' && !Array.isArray(val)) {
         throw new TypeError('词条 "' + key + '" 的值不能是对象，请使用扁平键（语言.层级键）');
       }
     }
 
+    /**
+     * 扁平词条表，键为 `语言代码.层级键`，与持久化格式一致；控制键并存于同一层
+     * @type {Object}
+     */
+    this.config = cg;
+
     /**
      * 复数规则表，键为语言代码，值为按数量返回形式的索引的函数
      * @type {Object}
@@ -139,7 +151,7 @@ class Lang {
      * 当前语言代码
      * @type {string}
      */
-    this.now = this.config.default || 'zh_cn';
+    this.now = cg.default || 'zh_cn';
 
     /**
      * 区域映射表，完整语言代码到基础语言代码
@@ -148,7 +160,7 @@ class Lang {
     this.locale = Object.assign({
       zh: 'zh_cn',
       en: 'en'
-    }, this.config.locale);
+    }, cg.locale);
 
     /**
      * 持久化文件路径
@@ -157,7 +169,7 @@ class Lang {
     this.file = file;
 
     /**
-     * 语言存储实例（数据侧）：优先用注入实例，否则按文件路径经 langsAdmin 取共享实例，
+     * 语言存储实例：优先用注入实例，否则按文件路径经 langsAdmin 取共享实例，
      * 两者都无则为 null（纯内存）
      * @type {Langs|null}
      */
@@ -166,22 +178,32 @@ class Lang {
 }
 
 /**
- * 获取翻译文本
- * @param {string} key - 键，支持 a.b 形式的层级键
- * @param {...any} param - 参数，依次替换 {0}、{1} 等占位符
- * @returns {string} 翻译后的文本
+ * 取以 `语言.` 为前缀的全部词条键 - 内部方法
  */
-Lang.prototype.get = function (key, ...param) {
-  if (!key || typeof (key) !== 'string') {
-    throw new TypeError('key必须是字符串');
-  }
-  var val = this._getVal(key);
-  if (typeof (val) === 'string' && param.length > 0) {
-    for (var i = 0; i < param.length; i++) {
-      var reg = new RegExp('\\{' + i + '\\}', 'ig');
-      val = val.replace(reg, param[i]);
+Lang.prototype._keysOf = function (lang) {
+  var prefix = lang + '.';
+  var keys = [];
+  for (var key in this.config) {
+    if (key.indexOf(prefix) === 0) {
+      keys.push(key);
     }
   }
+  return keys;
+};
+
+/**
+ * 占位符替换 - 内部方法
+ * useCount 为 true 时先替换 {count}（复数场景），序号占位符从 {1} 开始；否则从 {0} 开始
+ */
+Lang.prototype._fill = function (str, count, param, useCount) {
+  var val = String(str);
+  if (useCount) {
+    val = val.replace(/\{count\}/ig, count);
+  }
+  var offset = useCount ? 1 : 0;
+  for (var i = 0; i < param.length; i++) {
+    val = val.replace(new RegExp('\\{' + (i + offset) + '\\}', 'ig'), param[i]);
+  }
   return val;
 };
 
@@ -193,14 +215,15 @@ Lang.prototype.get = function (key, ...param) {
  * @private
  */
 Lang.prototype._getVal = function (key) {
-  var val = this._getFrom(this.now, key);
+  var val = this.config[this.now + '.' + key];
   if (val === undefined && this.config.fallback) {
-    var lang = this._getBase(this.now);
-    if (lang && lang !== this.now) {
-      val = this._getFrom(lang, key);
+    var base = this._getBase(this.now);
+    if (base !== this.now) {
+      val = this.config[base + '.' + key];
     }
-    if (val === undefined && this.config.default && this.config.default !== this.now) {
-      val = this._getFrom(this.config.default, key);
+    var def = this.config.default;
+    if (val === undefined && def && def !== this.now) {
+      val = this.config[def + '.' + key];
     }
   }
   if (val === undefined) {
@@ -209,17 +232,6 @@ Lang.prototype._getVal = function (key) {
   return val;
 };
 
-/**
- * 从指定语言中获取扁平词条 - 内部方法
- * @param {string} lang - 语言代码
- * @param {string} key - 键
- * @returns {any} 值
- * @private
- */
-Lang.prototype._getFrom = function (lang, key) {
-  return this.config[lang + '.' + key];
-};
-
 /**
  * 获取基础语言代码 - 内部方法
  * @param {string} lang - 完整语言代码
@@ -235,82 +247,32 @@ Lang.prototype._getBase = function (lang) {
 };
 
 /**
- * 设置语言键值到当前语言
- * @param {string} key - 键名，支持 a.b 形式的层级键
- * @param {any} val - 值
- * @returns {any} 返回设置的值
- */
-Lang.prototype.set = function (key, val) {
-  if (!key || typeof (key) !== 'string') {
-    throw new TypeError('key必须是字符串');
-  }
-  this.config[this.now + '.' + key] = val;
-  return val;
-};
-
-/**
- * 切换语言
- * 扁平结构下语言是否存在以是否有该语言前缀的词条为准
- * @param {string} lang - 语言代码
- * @returns {string} 切换后的语言代码
- */
-Lang.prototype.setLang = function (lang) {
-  if (!lang || typeof (lang) !== 'string') {
-    throw new TypeError('lang必须是字符串');
-  }
-  if (isControlKey(lang)) {
-    this._log('error', '语言未找到: ' + lang);
-    return this.now;
-  }
-  if (this.hasLang(lang)) {
-    this.now = lang;
-    return this.now;
-  }
-  var base_lang = this._getBase(lang);
-  if (base_lang !== lang && this.hasLang(base_lang)) {
-    this.now = base_lang;
-    return this.now;
-  }
-  this._log('error', '语言未找到: ' + lang);
-  return this.now;
-};
-
-/**
- * 判断某语言是否存在词条
- * @param {string} lang - 语言代码
- * @returns {boolean} 存在该语言的词条时返回 true
+ * 输出日志 - 内部方法，使用 console
+ * 配置 silent 为 true 时静默（供上层自带日志体系的场景使用，如 mm_tpl）
+ * @param {string} level - 日志级别
+ * @param {string} message - 日志消息
+ * @param {...any} args - 附加参数
+ * @private
  */
-Lang.prototype.hasLang = function (lang) {
-  if (!lang || typeof (lang) !== 'string') {
-    return false;
-  }
-  var prefix = lang + '.';
-  for (var key in this.config) {
-    if (key.indexOf(prefix) === 0) {
-      return true;
-    }
+Lang.prototype._log = function (level, message, ...args) {
+  if (!this.config.silent) {
+    (console[level] || console.log).call(console, message, ...args);
   }
-  return false;
 };
 
 /**
- * 删除某语言的全部词条
- * @param {string} lang - 语言代码
- * @returns {boolean} 是否删除成功
+ * 获取翻译文本
+ * @param {string} key - 键，支持 a.b 形式的层级键
+ * @param {...any} param - 参数，依次替换 {0}、{1} 等占位符
+ * @returns {string} 翻译后的文本
  */
-Lang.prototype.del = function (lang) {
-  if (!lang || typeof (lang) !== 'string') {
-    throw new TypeError('lang必须是字符串');
-  }
-  var prefix = lang + '.';
-  var removed = false;
-  for (var key in this.config) {
-    if (key.indexOf(prefix) === 0) {
-      delete this.config[key];
-      removed = true;
-    }
+Lang.prototype.get = function (key, ...param) {
+  checkKey(key, 'key');
+  var val = this._getVal(key);
+  if (typeof val === 'string' && param.length > 0) {
+    val = this._fill(val, 0, param, false);
   }
-  return removed;
+  return val;
 };
 
 /**
@@ -332,97 +294,73 @@ Lang.prototype.t = function (key, ...param) {
  * @returns {string} 翻译后的文本
  */
 Lang.prototype.tc = function (key, count, ...param) {
-  if (!key || typeof (key) !== 'string') {
-    throw new TypeError('key必须是字符串');
-  }
-  if (typeof (count) !== 'number') {
+  checkKey(key, 'key');
+  if (typeof count !== 'number') {
     throw new TypeError('count必须是数字');
   }
-  var lang = this.now;
-  var rule = this.rules[lang] || this.rules[this._getBase(lang)] || this.rules['en'];
-  var idx = rule(count);
-  var obj = this._getVal(key);
-  var val;
-  if (typeof (obj) === 'object' && obj !== null) {
-    val = obj[idx];
+  var rule = this.rules[this.now] || this.rules[this._getBase(this.now)] || this.rules.en;
+  var val = this._getVal(key);
+  if (val !== null && typeof val === 'object') {
+    val = val[rule(count)];
   }
-  if (typeof (val) === 'string') {
-    val = val.replace(/\{count\}/ig, count);
-    for (var i = 0; i < param.length; i++) {
-      var reg = new RegExp('\\{' + (i + 1) + '\\}', 'ig');
-      val = val.replace(reg, param[i]);
-    }
+  if (typeof val === 'string') {
+    val = this._fill(val, count, param, true);
   }
   return val;
 };
 
 /**
- * 格式化日期
- * @param {Date|number} dt - 日期对象或时间戳
- * @param {string} format - 格式，默认 YYYY-MM-DD hh:mm:ss
- * @returns {string} 格式化后的日期字符串
+ * 设置语言键值到当前语言
+ * @param {string} key - 键名，支持 a.b 形式的层级键
+ * @param {any} val - 值
+ * @returns {any} 返回设置的值
  */
-Lang.prototype.formatDate = function (dt, format) {
-  if (!dt) {
-    throw new TypeError('date不能为空');
-  }
-  var fmt = format || 'YYYY-MM-DD hh:mm:ss';
-  var d = new Date(dt);
-  if (isNaN(d.getTime())) {
-    throw new TypeError('无效的日期');
-  }
-  var year = d.getFullYear();
-  var month = String(d.getMonth() + 1).padStart(2, '0');
-  var day = String(d.getDate()).padStart(2, '0');
-  var hours = String(d.getHours()).padStart(2, '0');
-  var minutes = String(d.getMinutes()).padStart(2, '0');
-  var seconds = String(d.getSeconds()).padStart(2, '0');
-  return fmt
-    .replace('YYYY', year)
-    .replace('yyyy', year)
-    .replace('MM', month)
-    .replace('DD', day)
-    .replace('dd', day)
-    .replace('HH', hours)
-    .replace('hh', hours)
-    .replace('mm', minutes)
-    .replace('ss', seconds);
+Lang.prototype.set = function (key, val) {
+  checkKey(key, 'key');
+  this.config[this.now + '.' + key] = val;
+  return val;
 };
 
 /**
- * 格式化数字
- * @param {number} num - 要格式化的数字
- * @param {Object} options - 选项，含 decimals、decimal_separator、thousands_separator
- * @returns {string} 格式化后的数字字符串
+ * 切换语言
+ * 扁平结构下语言是否存在以是否有该语言前缀的词条为准
+ * @param {string} lang - 语言代码
+ * @returns {string} 切换后的语言代码
  */
-Lang.prototype.formatNumber = function (num, options) {
-  if (typeof (num) !== 'number' || isNaN(num)) {
-    throw new TypeError('num必须是有效的数字');
+Lang.prototype.setLang = function (lang) {
+  checkKey(lang, 'lang');
+  var base = this._getBase(lang);
+  var target = this.hasLang(lang) ? lang
+    : base !== lang && this.hasLang(base) ? base : '';
+  if (isControlKey(lang) || !target) {
+    this._log('error', '语言未找到: ' + lang);
+    return this.now;
   }
-  var opt = options || {};
-  var decimals = typeof (opt.decimals) === 'number' ? opt.decimals : 2;
-  var decimal_sepa = opt.decimal_separator || '.';
-  var thou_sepa = opt.thousands_separator || ',';
-  var parts = num.toFixed(decimals).split('.');
-  parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, thou_sepa);
-  return parts.join(decimal_sepa);
+  this.now = target;
+  return target;
 };
 
 /**
- * 注册语言复数规则
+ * 判断某语言是否存在词条
  * @param {string} lang - 语言代码
- * @param {Function} rule - 复数规则函数，按数量返回形式的索引
- * @returns {boolean} 是否注册成功
+ * @returns {boolean} 存在该语言的词条时返回 true
  */
-Lang.prototype.registerPlural = function (lang, rule) {
-  if (!lang || typeof (lang) !== 'string') {
-    throw new TypeError('lang必须是字符串');
-  }
-  if (typeof (rule) !== 'function') {
-    throw new TypeError('rule必须是函数');
+Lang.prototype.hasLang = function (lang) {
+  return !!lang && typeof lang === 'string' && this._keysOf(lang).length > 0;
+};
+
+/**
+ * 删除某语言的全部词条
+ * @param {string} lang - 语言代码
+ * @returns {boolean} 是否删除成功
+ */
+Lang.prototype.del = function (lang) {
+  checkKey(lang, 'lang');
+  var keys = this._keysOf(lang);
+  for (var i = 0; i < keys.length; i++) {
+    delete this.config[keys[i]];
   }
-  this.rules[lang] = rule;
-  return true;
+  return keys.length > 0;
 };
 
 /**
@@ -433,9 +371,6 @@ Lang.prototype.registerPlural = function (lang, rule) {
 Lang.prototype.getLangs = function () {
   var langs = [];
   for (var key in this.config) {
-    if (isControlKey(key)) {
-      continue;
-    }
     var dot = key.indexOf('.');
     if (dot === -1) {
       continue;
@@ -455,23 +390,91 @@ Lang.prototype.getLangs = function () {
  * @returns {Object|null} 嵌套词条字典，该语言无词条时返回 null
  */
 Lang.prototype.getDict = function (lang) {
-  if (!lang || typeof (lang) !== 'string' || isControlKey(lang)) {
-    return null;
-  }
-  var prefix = lang + '.';
+  var prefix = lang && typeof lang === 'string' ? lang + '.' : '';
+  var keys = prefix ? this._keysOf(lang) : [];
   var dict = null;
-  for (var key in this.config) {
-    if (key.indexOf(prefix) !== 0) {
-      continue;
-    }
-    if (!dict) {
-      dict = {};
-    }
-    setByPath(dict, key.slice(prefix.length), this.config[key]);
+  for (var i = 0; i < keys.length; i++) {
+    dict = dict || {};
+    setByPath(dict, keys[i].slice(prefix.length), this.config[keys[i]]);
   }
   return dict;
 };
 
+/**
+ * 检查语言是否支持
+ * @param {string} lang - 语言代码
+ * @returns {boolean} 是否支持
+ */
+Lang.prototype.isSupported = function (lang) {
+  return !!lang && typeof lang === 'string'
+    && (this.hasLang(lang) || this.hasLang(this._getBase(lang)));
+};
+
+/**
+ * 注册语言复数规则
+ * @param {string} lang - 语言代码
+ * @param {Function} rule - 复数规则函数，按数量返回形式的索引
+ * @returns {boolean} 是否注册成功
+ */
+Lang.prototype.registerPlural = function (lang, rule) {
+  checkKey(lang, 'lang');
+  if (typeof rule !== 'function') {
+    throw new TypeError('rule必须是函数');
+  }
+  this.rules[lang] = rule;
+  return true;
+};
+
+/**
+ * 格式化日期
+ * @param {Date|number} dt - 日期对象或时间戳
+ * @param {string} format - 格式，默认 YYYY-MM-DD hh:mm:ss
+ * @returns {string} 格式化后的日期字符串
+ */
+Lang.prototype.formatDate = function (dt, format) {
+  if (!dt) {
+    throw new TypeError('date不能为空');
+  }
+  var d = new Date(dt);
+  if (isNaN(d.getTime())) {
+    throw new TypeError('无效的日期');
+  }
+  var year = d.getFullYear();
+  var map = {
+    YYYY: year,
+    yyyy: year,
+    MM: pad(d.getMonth() + 1),
+    DD: pad(d.getDate()),
+    dd: pad(d.getDate()),
+    HH: pad(d.getHours()),
+    hh: pad(d.getHours()),
+    mm: pad(d.getMinutes()),
+    ss: pad(d.getSeconds())
+  };
+  var fmt = format || 'YYYY-MM-DD hh:mm:ss';
+  for (var token in map) {
+    fmt = fmt.replace(token, map[token]);
+  }
+  return fmt;
+};
+
+/**
+ * 格式化数字
+ * @param {number} num - 要格式化的数字
+ * @param {Object} options - 选项，含 decimals、decimal_separator、thousands_separator
+ * @returns {string} 格式化后的数字字符串
+ */
+Lang.prototype.formatNumber = function (num, options) {
+  if (typeof num !== 'number' || isNaN(num)) {
+    throw new TypeError('num必须是有效的数字');
+  }
+  var opt = options || {};
+  var decimals = typeof opt.decimals === 'number' ? opt.decimals : 2;
+  var parts = num.toFixed(decimals).split('.');
+  parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, opt.thousands_separator || ',');
+  return parts.join(opt.decimal_separator || '.');
+};
+
 /**
  * 保存语言包到持久化文件
  * 内存词条表即扁平 string→string 形态（数组值按标记编码），直接写入存储实例落盘
@@ -485,12 +488,11 @@ Lang.prototype.save = function () {
   try {
     this.store.clear();
     for (var key in this.config) {
-      if (!Object.prototype.hasOwnProperty.call(this.config, key) || isControlKey(key)) {
-        continue;
-      }
-      var str = encodeValue(this.config[key]);
-      if (str !== null) {
-        this.store.set(key, str);
+      if (!isControlKey(key)) {
+        var str = encodeValue(this.config[key]);
+        if (str !== null) {
+          this.store.set(key, str);
+        }
       }
     }
     return this.store.save() !== false;
@@ -510,53 +512,19 @@ Lang.prototype.load = function () {
     this._log('error', '未配置持久化文件路径或存储实例，无法加载语言包');
     return false;
   }
-  var ok = false;
   try {
-    ok = this.store.load();
+    if (!this.store.load()) {
+      return false;
+    }
   } catch (e) {
     this._log('error', '语言包加载失败: ' + e.message);
     return false;
   }
-  if (!ok) {
-    return false;
-  }
   var list = this.store.list();
   for (var key in list) {
-    if (Object.prototype.hasOwnProperty.call(list, key)) {
-      this.config[key] = decodeValue(list[key]);
-    }
+    this.config[key] = decodeValue(list[key]);
   }
   return true;
 };
 
-/**
- * 检查语言是否支持
- * @param {string} lang - 语言代码
- * @returns {boolean} 是否支持
- */
-Lang.prototype.isSupported = function (lang) {
-  if (!lang || typeof (lang) !== 'string' || isControlKey(lang)) {
-    return false;
-  }
-  return this.hasLang(lang) || this.hasLang(this._getBase(lang));
-};
-
-/**
- * 输出日志 - 内部方法，使用 console
- * 配置 silent 为 true 时静默（供上层自带日志体系的场景使用，如 mm_tpl）
- * @param {string} level - 日志级别
- * @param {string} message - 日志消息
- * @param {...any} args - 附加参数
- * @private
- */
-Lang.prototype._log = function (level, message, ...args) {
-  if (this.config.silent) {
-    return;
-  }
-  var fn = console[level] || console.log;
-  if (typeof (fn) === 'function') {
-    fn.call(console, message, ...args);
-  }
-};
-
 module.exports = Lang;