schema-dsl 1.1.3 → 1.1.5

package/index.d.ts

@@ -1,9 +1,64 @@
-// Type definitions for schema-dsl v1.1.2
+// Type definitions for schema-dsl v1.1.5
 // Project: https://github.com/vextjs/schema-dsl
 // Definitions by: schema-dsl Team
 
 // ========== 核心类型 ==========
 
+/**
+ * 错误消息配置（字符串或对象）
+ *
+ * @description v1.1.5 新增：支持对象格式配置错误代码和消息
+ *
+ * @example 字符串格式（向后兼容）
+ * ```typescript
+ * const messages = {
+ *   'user.notFound': '用户不存在'
+ * };
+ * ```
+ *
+ * @example 对象格式（v1.1.5 新增）
+ * ```typescript
+ * const messages = {
+ *   'account.notFound': {
+ *     code: 'ACCOUNT_NOT_FOUND',
+ *     message: '账户不存在'
+ *   }
+ * };
+ * ```
+ *
+ * @since v1.1.5
+ */
+export type ErrorMessageConfig =
+  | string  // 向后兼容：'账户不存在'
+  | {       // 新格式：{ code, message }
+      /** 错误代码（可选，默认使用 key） */
+      code?: string;
+      /** 错误消息（必需） */
+      message: string;
+    };
+
+/**
+ * 语言包定义
+ *
+ * @description 语言包对象，key 为错误代码，value 为错误消息配置
+ *
+ * @example
+ * ```typescript
+ * const zhCN: LocaleMessages = {
+ *   'user.notFound': '用户不存在',
+ *   'account.notFound': {
+ *     code: 'ACCOUNT_NOT_FOUND',
+ *     message: '账户不存在'
+ *   }
+ * };
+ * ```
+ *
+ * @since v1.1.5
+ */
+export interface LocaleMessages {
+  [key: string]: ErrorMessageConfig;
+}
+
 /**
  * JSON Schema 对象
  * 
@@ -285,13 +340,24 @@ export class DslBuilder {
 
   /**
    * 构造函数
-   * @param dslString - DSL字符串（如 'email!', 'string:3-32!', 'types:string|number'）
+   * @param dslString - DSL字符串（如 'email!', 'string:3-32!', 'string?', 'types:string|number'）
    *
    * @example 基础类型
    * ```typescript
-   * const builder = new DslBuilder('email!');
-   * const builder2 = new DslBuilder('string:3-32');
-   * const builder3 = new DslBuilder('types:string|number');
+   * const builder = new DslBuilder('email!');      // 必填邮箱
+   * const builder2 = new DslBuilder('string:3-32'); // 可选字符串（默认）
+   * const builder3 = new DslBuilder('string?');     // 显式可选字符串
+   * const builder4 = new DslBuilder('email?');      // 显式可选邮箱
+   * const builder5 = new DslBuilder('types:string|number'); // 联合类型
+   * ```
+   *
+   * @example 必填与可选标记
+   * ```typescript
+   * new DslBuilder('string!')      // 必填字符串
+   * new DslBuilder('string')       // 可选字符串（默认）
+   * new DslBuilder('string?')      // 显式可选字符串
+   * new DslBuilder('email?')       // 可选邮箱
+   * new DslBuilder('string:3-32?') // 可选字符串，长度3-32
    * ```
    *
    * @example 数字类型比较运算符 (v1.1.2+)
@@ -317,6 +383,7 @@ export class DslBuilder {
    * // 配合必填标记
    * new DslBuilder('number:>=18!')     // 必填且 >= 18
    * new DslBuilder('number:>0!')       // 必填且 > 0
+   * new DslBuilder('number:>0?')       // 可选且 > 0（当有值时）
    * ```
    */
   constructor(dslString: string);
@@ -1254,12 +1321,26 @@ export namespace dsl {
      * @param code - 错误代码（多语言 key）
      * @param params - 错误参数
      * @param statusCode - HTTP 状态码
+     * @param locale - 语言环境（可选，不传则使用全局语言）
      * @returns 错误实例
+     *
+     * @example 全局语言
+     * ```typescript
+     * Locale.setLocale('zh-CN');
+     * const error = dsl.error.create('account.notFound');
+     * ```
+     *
+     * @example 运行时指定语言
+     * ```typescript
+     * const error1 = dsl.error.create('account.notFound', {}, 404, 'zh-CN');
+     * const error2 = dsl.error.create('account.notFound', {}, 404, 'en-US');
+     * ```
      */
     create(
       code: string,
       params?: Record<string, any>,
-      statusCode?: number
+      statusCode?: number,
+      locale?: string
     ): I18nError;
 
     /**
@@ -1267,12 +1348,25 @@ export namespace dsl {
      * @param code - 错误代码（多语言 key）
      * @param params - 错误参数
      * @param statusCode - HTTP 状态码
+     * @param locale - 语言环境（可选，不传则使用全局语言）
      * @throws I18nError
+     *
+     * @example 全局语言
+     * ```typescript
+     * Locale.setLocale('zh-CN');
+     * dsl.error.throw('account.notFound');
+     * ```
+     *
+     * @example 运行时指定语言
+     * ```typescript
+     * dsl.error.throw('account.notFound', {}, 404, 'en-US');
+     * ```
      */
     throw(
       code: string,
       params?: Record<string, any>,
-      statusCode?: number
+      statusCode?: number,
+      locale?: string
     ): never;
 
     /**
@@ -1281,13 +1375,26 @@ export namespace dsl {
      * @param code - 错误代码（多语言 key）
      * @param params - 错误参数
      * @param statusCode - HTTP 状态码
+     * @param locale - 语言环境（可选，不传则使用全局语言）
      * @throws I18nError 条件为 false 时抛出
+     *
+     * @example 全局语言
+     * ```typescript
+     * Locale.setLocale('zh-CN');
+     * dsl.error.assert(account, 'account.notFound');
+     * ```
+     *
+     * @example 运行时指定语言
+     * ```typescript
+     * dsl.error.assert(account, 'account.notFound', {}, 404, 'en-US');
+     * ```
      */
     assert(
       condition: any,
       code: string,
       params?: Record<string, any>,
-      statusCode?: number
+      statusCode?: number,
+      locale?: string
     ): asserts condition;
   };
 }
@@ -1648,7 +1755,10 @@ export class I18nError extends Error {
   /** 错误消息（已翻译） */
   message: string;
 
-  /** 错误代码（多语言 key） */
+  /** 原始 key（v1.1.5 新增） */
+  originalKey: string;
+
+  /** 错误代码（从对象提取或使用 key） */
   code: string;
 
   /** 错误参数（用于插值） */
@@ -1679,12 +1789,30 @@ export class I18nError extends Error {
    * @param code - 错误代码
    * @param params - 错误参数
    * @param statusCode - HTTP 状态码
+   * @param locale - 语言环境（可选，不传则使用全局语言）
    * @returns 错误实例
+   *
+   * @example 全局语言
+   * ```typescript
+   * Locale.setLocale('zh-CN');
+   * const error = I18nError.create('account.notFound');
+   * // message: "账户不存在"
+   * ```
+   *
+   * @example 运行时指定语言
+   * ```typescript
+   * const error1 = I18nError.create('account.notFound', {}, 404, 'zh-CN');
+   * // message: "账户不存在"
+   *
+   * const error2 = I18nError.create('account.notFound', {}, 404, 'en-US');
+   * // message: "Account not found"
+   * ```
    */
   static create(
     code: string,
     params?: Record<string, any>,
-    statusCode?: number
+    statusCode?: number,
+    locale?: string
   ): I18nError;
 
   /**
@@ -1692,12 +1820,25 @@ export class I18nError extends Error {
    * @param code - 错误代码
    * @param params - 错误参数
    * @param statusCode - HTTP 状态码
+   * @param locale - 语言环境（可选，不传则使用全局语言）
    * @throws I18nError
+   *
+   * @example 全局语言
+   * ```typescript
+   * Locale.setLocale('zh-CN');
+   * I18nError.throw('account.notFound');
+   * ```
+   *
+   * @example 运行时指定语言
+   * ```typescript
+   * I18nError.throw('account.notFound', {}, 404, 'en-US');
+   * ```
    */
   static throw(
     code: string,
     params?: Record<string, any>,
-    statusCode?: number
+    statusCode?: number,
+    locale?: string
   ): never;
 
   /**
@@ -1706,13 +1847,46 @@ export class I18nError extends Error {
    * @param code - 错误代码
    * @param params - 错误参数
    * @param statusCode - HTTP 状态码
+   * @param locale - 语言环境（可选，不传则使用全局语言）
    * @throws I18nError 条件为 false 时抛出
+   *
+   * @example 全局语言
+   * ```typescript
+   * Locale.setLocale('zh-CN');
+   * I18nError.assert(account, 'account.notFound');
+   * ```
+   *
+   * @example 运行时指定语言
+   * ```typescript
+   * I18nError.assert(account, 'account.notFound', {}, 404, 'en-US');
+   * ```
+   */
+  /**
+   * 断言方法 - 条件不满足时抛错
+   * @param condition - 条件表达式
+   * @param code - 错误代码
+   * @param params - 错误参数
+   * @param statusCode - HTTP 状态码
+   * @param locale - 语言环境（可选，不传则使用全局语言）
+   * @throws I18nError 条件为 false 时抛出
+   *
+   * @example 全局语言
+   * ```typescript
+   * Locale.setLocale('zh-CN');
+   * I18nError.assert(account, 'account.notFound');
+   * ```
+   *
+   * @example 运行时指定语言
+   * ```typescript
+   * I18nError.assert(account, 'account.notFound', {}, 404, 'en-US');
+   * ```
    */
   static assert(
     condition: any,
     code: string,
     params?: Record<string, any>,
-    statusCode?: number
+    statusCode?: number,
+    locale?: string
   ): asserts condition;
 
   /**
@@ -1725,9 +1899,26 @@ export class I18nError extends Error {
   /**
    * 转为 JSON 格式（用于 API 响应）
    * @returns JSON 对象
+   *
+   * @example
+   * ```typescript
+   * const json = error.toJSON();
+   * // {
+   * //   error: 'I18nError',
+   * //   originalKey: 'account.notFound',  // v1.1.5 新增
+   * //   code: 'ACCOUNT_NOT_FOUND',
+   * //   message: '账户不存在',
+   * //   params: {},
+   * //   statusCode: 400,
+   * //   locale: 'zh-CN'
+   * // }
+   * ```
+   *
+   * @since v1.1.5 - 新增 originalKey 字段
    */
   toJSON(): {
     error: string;
+    originalKey: string;  // v1.1.5 新增
     code: string;
     message: string;
     params: Record<string, any>;

package/index.js

@@ -59,18 +59,20 @@ dsl.error = {
    * @param {string} code - 错误代码（多语言 key）
    * @param {Object} params - 错误参数
    * @param {number} statusCode - HTTP 状态码
+   * @param {string} locale - 语言环境（可选，不传则使用全局语言）
    * @returns {I18nError} 错误实例
    */
-  create: (code, params, statusCode) => I18nError.create(code, params, statusCode),
+  create: (code, params, statusCode, locale) => I18nError.create(code, params, statusCode, locale),
 
   /**
    * 抛出多语言错误
    * @param {string} code - 错误代码（多语言 key）
    * @param {Object} params - 错误参数
    * @param {number} statusCode - HTTP 状态码
+   * @param {string} locale - 语言环境（可选，不传则使用全局语言）
    * @throws {I18nError} 直接抛出错误
    */
-  throw: (code, params, statusCode) => I18nError.throw(code, params, statusCode),
+  throw: (code, params, statusCode, locale) => I18nError.throw(code, params, statusCode, locale),
 
   /**
    * 断言方法 - 条件不满足时抛错
@@ -78,8 +80,9 @@ dsl.error = {
    * @param {string} code - 错误代码（多语言 key）
    * @param {Object} params - 错误参数
    * @param {number} statusCode - HTTP 状态码
+   * @param {string} locale - 语言环境（可选，不传则使用全局语言）
    */
-  assert: (condition, code, params, statusCode) => I18nError.assert(condition, code, params, statusCode)
+  assert: (condition, code, params, statusCode, locale) => I18nError.assert(condition, code, params, statusCode, locale)
 };
 
 /**

package/index.mjs

@@ -1,4 +1,4 @@
-import schema-dsl from './index.js';
+import schemaDsl from './index.js';
 
 export const {
   dsl,
@@ -26,5 +26,5 @@ export const {
   uninstallStringExtensions
 } = schema-dsl;
 
-export default schema-dsl;
+export default schemaDsl;
 

package/lib/core/DslBuilder.js

@@ -123,11 +123,20 @@ class DslBuilder {
       processedDsl = trimmed.replace(/^array!/, 'array:') + '!';
     }
 
+    // 🔴 处理必填标记 ! 和可选标记 ?
+    // 优先级：! > ?（如果同时存在，! 优先）
     this._required = processedDsl.endsWith('!');
-    const dslWithoutRequired = this._required ? processedDsl.slice(0, -1) : processedDsl;
+    this._optional = processedDsl.endsWith('?') && !this._required;
+
+    let dslWithoutMarker = processedDsl;
+    if (this._required) {
+      dslWithoutMarker = processedDsl.slice(0, -1);
+    } else if (this._optional) {
+      dslWithoutMarker = processedDsl.slice(0, -1);
+    }
 
     // 简单解析为基础Schema（避免循环依赖）
-    this._baseSchema = this._parseSimple(dslWithoutRequired);
+    this._baseSchema = this._parseSimple(dslWithoutMarker);
 
     // 扩展属性
     this._customMessages = {};

package/lib/core/Locale.js

@@ -62,11 +62,12 @@ class Locale {
   }
 
   /**
-   * 获取错误消息模板
+   * 获取错误消息配置
    * @param {string} type - 错误类型或消息字符串
    * @param {Object} [customMessages] - 自定义消息
    * @param {string} [locale] - 指定语言（可选，默认使用当前语言）
-   * @returns {string} 消息模板
+   * @returns {Object|string} 消息配置对象 { code, message } 或字符串（向后兼容）
+   * @version 1.1.5 - 支持对象格式
    */
   static getMessage(type, customMessages = {}, locale = null) {
     // 使用指定的语言或当前全局语言
@@ -74,32 +75,37 @@ class Locale {
 
     // 优先级: 自定义消息 > 全局自定义消息 > 语言包 > ErrorCodes > 原字符串
 
-    // 1. 自定义消息
-    if (customMessages[type]) {
-      return customMessages[type];
+    // 1. 查找消息配置
+    let messageConfig = customMessages[type]
+                     || this.customMessages[type]
+                     || (this.locales[targetLocale] && this.locales[targetLocale][type]);
+
+    // 2. 如果未找到，尝试从 ErrorCodes 获取
+    if (!messageConfig) {
+      const errorInfo = getErrorInfo(type);
+      if (errorInfo.code === 'UNKNOWN_ERROR') {
+        // ✅ 向后兼容：直接返回原字符串（支持硬编码消息）
+        return type;
+      }
+      messageConfig = errorInfo.message;
     }
 
-    // 2. 全局自定义消息
-    if (this.customMessages[type]) {
-      return this.customMessages[type];
+    // 3. 规范化为对象格式（v1.1.5 新增）
+    if (typeof messageConfig === 'string') {
+      // 字符串格式 → 转换为对象格式（向后兼容）
+      return { code: type, message: messageConfig };
     }
 
-    // 3. 语言包（使用指定的语言）
-    const localeMessages = this.locales[targetLocale];
-    if (localeMessages && localeMessages[type]) {
-      return localeMessages[type];
+    if (typeof messageConfig === 'object' && messageConfig !== null && messageConfig.message) {
+      // 对象格式 → 直接使用
+      return {
+        code: messageConfig.code || type,  // 无 code 时使用 type 作为 code
+        message: messageConfig.message
+      };
     }
 
-    // 4. 默认消息（从ErrorCodes获取）
-    const errorInfo = getErrorInfo(type);
-
-    // 5. 如果是未知错误，说明不是预定义的错误码
-    if (errorInfo.code === 'UNKNOWN_ERROR') {
-      // ✅ 向后兼容：直接返回原字符串（支持硬编码消息）
-      return type;
-    }
-
-    return errorInfo.message;
+    // 4. 降级处理（边界情况）
+    return { code: type, message: type };
   }
 
   /**

package/lib/core/MessageTemplate.js

@@ -29,32 +29,41 @@ class MessageTemplate {
   render(context = {}) {
     let message = this.template;
 
-    // 替换所有模板变量
-    message = message.replace(/\{\{#(\w+)\}\}/g, (match, key) => {
-      const value = context[key];
+    // 定义支持的模板格式（按优先级）
+    const patterns = [
+      /\{\{#(\w+)\}\}/g,  // {{#variable}} - 优先级1（现有格式）
+      /\{\{(\w+)\}\}/g,   // {{variable}}  - 优先级2（无井号）
+      /\{(\w+)\}/g        // {variable}    - 优先级3（单花括号）
+    ];
 
-      // 特殊处理
-      if (value === undefined || value === null) {
-        return match; // 保留原样
-      }
+    // 按优先级依次替换
+    for (const pattern of patterns) {
+      message = message.replace(pattern, (match, key) => {
+        const value = context[key];
 
-      // 数组转字符串
-      if (Array.isArray(value)) {
-        return value.join(', ');
-      }
+        // 特殊处理
+        if (value === undefined || value === null) {
+          return match; // 保留原样
+        }
 
-      // RegExp转字符串
-      if (value instanceof RegExp) {
-        return value.toString();
-      }
+        // 数组转字符串
+        if (Array.isArray(value)) {
+          return value.join(', ');
+        }
 
-      // Date转字符串
-      if (value instanceof Date) {
-        return value.toISOString();
-      }
+        // RegExp转字符串
+        if (value instanceof RegExp) {
+          return value.toString();
+        }
 
-      return String(value);
-    });
+        // Date转字符串
+        if (value instanceof Date) {
+          return value.toISOString();
+        }
+
+        return String(value);
+      });
+    }
 
     return message;
   }

package/lib/core/Validator.js

@@ -477,7 +477,12 @@ class Validator {
             const errorMsg = failedMessage || cond.message;
             // 支持多语言：如果 message 是 key（如 'conditional.underAge'），从语言包获取翻译
             // 传递 locale 参数以支持动态语言切换
-            const errorMessage = Locale.getMessage(errorMsg, options.messages || {}, locale);
+            const messageConfig = Locale.getMessage(errorMsg, options.messages || {}, locale);
+
+            // v1.1.5: Locale.getMessage 返回对象 { code, message }，需要提取 message
+            const errorMessage = typeof messageConfig === 'object' && messageConfig.message
+              ? messageConfig.message
+              : messageConfig;
 
             return {
               valid: false,