schema-dsl 1.1.0 → 1.1.1

package/lib/errors/I18nError.js

@@ -0,0 +1,222 @@
+/**
+ * I18nError - 多语言错误工具类
+ *
+ * 提供统一的多语言错误抛出机制，支持：
+ * - 多语言 key 自动翻译
+ * - 参数插值（如 {{field}}, {{limit}}）
+ * - 自定义错误代码
+ * - Express/Koa 集成
+ *
+ * @module lib/errors/I18nError
+ * @version 1.1.1
+ *
+ * @example 基础用法
+ * const { I18nError } = require('schema-dsl');
+ *
+ * // 抛出多语言错误
+ * throw I18nError.create('error.notFound', { resource: '账户' });
+ * // 中文: "找不到账户"
+ * // 英文: "Account not found"
+ *
+ * @example 业务代码中使用
+ * function getAccount(id) {
+ *   const account = db.findAccount(id);
+ *   if (!account) {
+ *     throw I18nError.create('account.notFound', { accountId: id });
+ *   }
+ *   if (account.balance < 100) {
+ *     throw I18nError.create('account.insufficientBalance', {
+ *       balance: account.balance,
+ *       required: 100
+ *     });
+ *   }
+ *   return account;
+ * }
+ *
+ * @example Express 中间件
+ * app.use((error, req, res, next) => {
+ *   if (error instanceof I18nError) {
+ *     return res.status(error.statusCode).json(error.toJSON());
+ *   }
+ *   next(error);
+ * });
+ */
+
+const Locale = require('../core/Locale');
+const MessageTemplate = require('../core/MessageTemplate');
+
+/**
+ * 多语言错误类
+ *
+ * @class I18nError
+ * @extends Error
+ *
+ * @property {string} name - 错误名称（固定为 'I18nError'）
+ * @property {string} message - 错误消息（已翻译）
+ * @property {string} code - 错误代码（多语言 key）
+ * @property {Object} params - 错误参数（用于插值）
+ * @property {number} statusCode - HTTP 状态码（默认 400）
+ * @property {string} locale - 使用的语言环境
+ */
+class I18nError extends Error {
+  /**
+   * 构造函数
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数（用于插值）
+   * @param {number} statusCode - HTTP 状态码（默认 400）
+   * @param {string} locale - 语言环境（默认使用当前语言）
+   */
+  constructor(code, params = {}, statusCode = 400, locale = null) {
+    // 获取翻译后的消息模板
+    const actualLocale = locale || Locale.getLocale();
+    const template = Locale.getMessage(code, {}, actualLocale);
+
+    // 使用 MessageTemplate 进行参数插值
+    const messageTemplate = new MessageTemplate(template);
+    const message = messageTemplate.render(params || {});
+
+    super(message);
+
+    this.name = 'I18nError';
+    this.code = code;
+    this.params = params || {};
+    this.statusCode = statusCode;
+    this.locale = actualLocale;
+
+    // 保持堆栈跟踪
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, I18nError);
+    }
+  }
+
+  /**
+   * 静态工厂方法 - 创建并抛出错误
+   *
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数
+   * @param {number} statusCode - HTTP 状态码
+   * @returns {I18nError} 错误实例
+   *
+   * @example
+   * // 创建错误（不抛出）
+   * const error = I18nError.create('error.notFound', { resource: '用户' });
+   *
+   * @example
+   * // 直接抛出
+   * throw I18nError.create('error.notFound', { resource: '用户' });
+   */
+  static create(code, params = {}, statusCode = 400) {
+    return new I18nError(code, params, statusCode);
+  }
+
+  /**
+   * 静态工厂方法 - 快速抛出错误
+   *
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数
+   * @param {number} statusCode - HTTP 状态码
+   * @throws {I18nError} 直接抛出错误
+   *
+   * @example
+   * I18nError.throw('error.notFound', { resource: '用户' });
+   * // 等同于：throw I18nError.create('error.notFound', { resource: '用户' });
+   */
+  static throw(code, params = {}, statusCode = 400) {
+    throw new I18nError(code, params, statusCode);
+  }
+
+  /**
+   * 断言方法 - 条件不满足时抛错
+   *
+   * @param {boolean} condition - 条件表达式
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数
+   * @param {number} statusCode - HTTP 状态码
+   * @throws {I18nError} 条件为 false 时抛出错误
+   *
+   * @example
+   * I18nError.assert(account, 'account.notFound', { accountId: id });
+   * // 等同于：if (!account) throw I18nError.create('account.notFound', { accountId: id });
+   *
+   * @example
+   * I18nError.assert(
+   *   account.balance >= 100,
+   *   'account.insufficientBalance',
+   *   { balance: account.balance, required: 100 }
+   * );
+   */
+  static assert(condition, code, params = {}, statusCode = 400) {
+    if (!condition) {
+      throw new I18nError(code, params, statusCode);
+    }
+  }
+
+  /**
+   * 检查错误是否为指定代码
+   *
+   * @param {string} code - 错误代码
+   * @returns {boolean} 是否匹配
+   *
+   * @example
+   * try {
+   *   // ...
+   * } catch (error) {
+   *   if (error instanceof I18nError && error.is('account.notFound')) {
+   *     // 处理账户不存在的情况
+   *   }
+   * }
+   */
+  is(code) {
+    return this.code === code;
+  }
+
+  /**
+   * 转换为 JSON 格式（用于 API 响应）
+   *
+   * @returns {Object} JSON 对象
+   * @returns {string} return.error - 错误名称
+   * @returns {string} return.code - 错误代码
+   * @returns {string} return.message - 错误消息（已翻译）
+   * @returns {Object} return.params - 错误参数
+   * @returns {number} return.statusCode - 状态码
+   * @returns {string} return.locale - 语言环境
+   *
+   * @example
+   * const json = error.toJSON();
+   * res.status(error.statusCode).json(json);
+   * // {
+   * //   error: 'I18nError',
+   * //   code: 'account.notFound',
+   * //   message: '找不到账户',
+   * //   params: { accountId: '123' },
+   * //   statusCode: 404,
+   * //   locale: 'zh-CN'
+   * // }
+   */
+  toJSON() {
+    return {
+      error: this.name,
+      code: this.code,
+      message: this.message,
+      params: this.params,
+      statusCode: this.statusCode,
+      locale: this.locale
+    };
+  }
+
+  /**
+   * 转换为字符串
+   *
+   * @returns {string} 格式化的错误信息
+   *
+   * @example
+   * console.log(error.toString());
+   * // "I18nError [account.notFound]: 找不到账户"
+   */
+  toString() {
+    return `${this.name} [${this.code}]: ${this.message}`;
+  }
+}
+
+module.exports = I18nError;
+

package/lib/locales/en-US.js

@@ -17,6 +17,31 @@ module.exports = {
   'conditional.blocked': 'Account has been blocked',
   'conditional.notAllowed': 'Registration not allowed',
 
+  // I18nError - General errors (v1.1.1)
+  'error.notFound': '{{#resource}} not found',
+  'error.forbidden': 'Access to {{#resource}} is forbidden',
+  'error.unauthorized': 'Unauthorized, please log in',
+  'error.invalid': 'Invalid {{#field}}',
+  'error.duplicate': '{{#resource}} already exists',
+  'error.conflict': 'Operation conflict: {{#reason}}',
+
+  // I18nError - Account related (v1.1.1)
+  'account.notFound': 'Account not found',
+  'account.inactive': 'Account is inactive',
+  'account.banned': 'Account has been banned',
+  'account.insufficientBalance': 'Insufficient balance, current: {{#balance}}, required: {{#required}}',
+  'account.insufficientCredits': 'Insufficient credits, current: {{#credits}}, required: {{#required}}',
+
+  // I18nError - User related (v1.1.1)
+  'user.notFound': 'User not found',
+  'user.notVerified': 'User is not verified',
+  'user.noPermission': 'No admin permission',
+
+  // I18nError - Order related (v1.1.1)
+  'order.notPaid': 'Order not paid',
+  'order.paymentMissing': 'Payment information missing',
+  'order.addressMissing': 'Shipping address missing',
+
   // Formats
   'format.email': '{{#label}} must be a valid email address',
   'format.url': '{{#label}} must be a valid URL',

package/lib/locales/zh-CN.js

@@ -17,6 +17,31 @@ module.exports = {
   'conditional.blocked': '账号已被封禁',
   'conditional.notAllowed': '不允许注册',
 
+  // I18nError - 通用错误消息 (v1.1.1)
+  'error.notFound': '找不到{{#resource}}',
+  'error.forbidden': '没有权限访问{{#resource}}',
+  'error.unauthorized': '未授权，请先登录',
+  'error.invalid': '{{#field}}无效',
+  'error.duplicate': '{{#resource}}已存在',
+  'error.conflict': '操作冲突: {{#reason}}',
+
+  // I18nError - 账户相关 (v1.1.1)
+  'account.notFound': '账户不存在',
+  'account.inactive': '账户未激活',
+  'account.banned': '账户已被封禁',
+  'account.insufficientBalance': '余额不足，当前余额{{#balance}}，需要{{#required}}',
+  'account.insufficientCredits': '积分不足，当前积分{{#credits}}，需要{{#required}}',
+
+  // I18nError - 用户相关 (v1.1.1)
+  'user.notFound': '用户不存在',
+  'user.notVerified': '用户未验证',
+  'user.noPermission': '没有管理员权限',
+
+  // I18nError - 订单相关 (v1.1.1)
+  'order.notPaid': '订单未支付',
+  'order.paymentMissing': '缺少支付信息',
+  'order.addressMissing': '缺少收货地址',
+
   // Formats
   'format.email': '{{#label}}必须是有效的邮箱地址',
   'format.url': '{{#label}}必须是有效的URL地址',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schema-dsl",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "简洁强大的JSON Schema验证库 - DSL语法 + String扩展 + 便捷validate",
   "main": "index.js",
   "types": "index.d.ts",