schema-dsl 1.0.0 → 1.0.4

package/examples/i18n-full-demo.js

@@ -14,26 +14,24 @@ console.log('========== 多语言配置完整示例 ==========\n');
 // ========================================
 // 步骤 1：应用启动时配置
 // ========================================
-console.log('【步骤 1】配置用户语言包和缓存\n');
+console.log('【步骤 1】配置用户语言包\n');
 
 dsl.config({
-  // 用户语言包配置
+  // 方式 A：从目录加载（推荐用于大型项目）
+  // i18n: path.join(__dirname, 'i18n/dsl')
+
+  // 方式 B：直接传入对象（推荐用于小型项目）
   i18n: {
-    // 方式 A：从目录加载（推荐用于大型项目）
-    // localesPath: path.join(__dirname, 'i18n/labels'),
-
-    // 方式 B：直接传入对象（推荐用于小型项目）
-    locales: {
-      'zh-CN': {
-        // 字段标签
-        'username': '用户名',
-        'email': '邮箱地址',
-        'password': '密码',
-        'age': '年龄',
-        'phone': '手机号',
-
-        // 嵌套字段
-        'address.city': '城市',
+    'zh-CN': {
+      // 字段标签
+      'username': '用户名',
+      'email': '邮箱地址',
+      'password': '密码',
+      'age': '年龄',
+      'phone': '手机号',
+
+      // 嵌套字段
+      'address.city': '城市',
         'address.street': '街道',
 
         // 自定义错误消息
@@ -79,13 +77,6 @@ dsl.config({
         'custom.passwordWeak': 'パスワードが弱すぎます'
       }
     }
-  },
-
-  // 缓存配置（可选，大型项目推荐）
-  cache: {
-    maxSize: 10000,   // 大型项目：1万个 Schema
-    ttl: 7200000      // 2 小时
-  }
 });
 
 console.log('✅ 配置完成\n');

package/examples/schema-utils-chaining.examples.js

@@ -1,13 +1,13 @@
 /**
  * SchemaUtils 核心方法示例
  *
- * 展示 v2.1.0 简化后的核心 4 个方法：
+ * 展示 v1.0.3 简化后的核心 4 个方法：
  * 1. omit() - 排除字段
  * 2. pick() - 保留字段
  * 3. partial() - 部分验证
  * 4. extend() - 扩展字段
  *
- * @version 2.1.0 (简化版)
+ * @version 1.0.3 (简化版)
  * @date 2025-12-29
  */
 

package/examples/slug.examples.js

@@ -0,0 +1,179 @@
+/**
+ * slug 类型验证示例
+ *
+ * slug 用于 URL 友好的字符串，只能包含：
+ * - 小写字母 (a-z)
+ * - 数字 (0-9)
+ * - 连字符 (-)
+ *
+ * 格式规则：
+ * - 必须以字母或数字开头
+ * - 必须以字母或数字结尾
+ * - 中间可以有连字符，但不能连续
+ */
+
+const { dsl, validate } = require('../index');
+
+// ========== 示例 1: 基础用法 ==========
+console.log('\n========== 示例 1: 基础 slug 验证 ==========');
+
+const schema1 = dsl({
+  slug: 'slug!'
+});
+
+console.log('✅ 有效的 slug:');
+console.log('  my-blog-post:', validate(schema1, { slug: 'my-blog-post' }).valid);
+console.log('  hello-world:', validate(schema1, { slug: 'hello-world' }).valid);
+console.log('  post-123:', validate(schema1, { slug: 'post-123' }).valid);
+console.log('  article:', validate(schema1, { slug: 'article' }).valid);
+
+console.log('\n❌ 无效的 slug:');
+console.log('  My-Blog-Post:', validate(schema1, { slug: 'My-Blog-Post' }).valid); // 大写
+console.log('  hello_world:', validate(schema1, { slug: 'hello_world' }).valid);   // 下划线
+console.log('  -hello:', validate(schema1, { slug: '-hello' }).valid);             // 开头连字符
+console.log('  hello-:', validate(schema1, { slug: 'hello-' }).valid);             // 结尾连字符
+console.log('  hello--world:', validate(schema1, { slug: 'hello--world' }).valid); // 连续连字符
+console.log('  hello world:', validate(schema1, { slug: 'hello world' }).valid);   // 空格
+
+// ========== 示例 2: DSL 字符串语法 ==========
+console.log('\n========== 示例 2: DSL 字符串语法 ==========');
+
+const schema2 = dsl({
+  articleSlug: 'slug:3-100!'  // slug + 长度限制
+});
+
+console.log('✅ 3-100字符的 slug:');
+console.log('  abc:', validate(schema2, { articleSlug: 'abc' }).valid);
+console.log('  my-long-article-title-with-many-words:',
+  validate(schema2, { articleSlug: 'my-long-article-title-with-many-words' }).valid);
+
+console.log('\n❌ 长度不符:');
+console.log('  ab:', validate(schema2, { articleSlug: 'ab' }).valid);  // 太短
+
+// ========== 示例 3: 链式调用 ==========
+console.log('\n========== 示例 3: 链式调用 ==========');
+
+const schema3 = dsl({
+  pageSlug: 'string!'.slug().label('页面别名')
+});
+
+console.log('✅ 链式调用验证:');
+console.log('  about-us:', validate(schema3, { pageSlug: 'about-us' }).valid);
+console.log('  contact:', validate(schema3, { pageSlug: 'contact' }).valid);
+
+// ========== 示例 4: 实际应用场景 ==========
+console.log('\n========== 示例 4: 博客文章Schema ==========');
+
+const blogPostSchema = dsl({
+  title: 'string:1-200!',
+  slug: 'slug:3-100!',
+  author: 'string!',
+  content: 'string:10-!',
+  tags: 'array<slug>',  // slug 数组
+  publishedAt: 'datetime'
+});
+
+const validPost = {
+  title: 'Getting Started with Node.js',
+  slug: 'getting-started-with-nodejs',
+  author: 'John Doe',
+  content: 'This is a comprehensive guide to Node.js...',
+  tags: ['nodejs', 'javascript', 'backend'],
+  publishedAt: '2025-12-31T10:00:00Z'
+};
+
+console.log('✅ 有效的博客文章:', validate(blogPostSchema, validPost).valid);
+
+const invalidPost = {
+  title: 'Invalid Post',
+  slug: 'Invalid Slug!',  // ❌ 包含大写和特殊字符
+  author: 'Jane',
+  content: 'Short content',
+  tags: ['Node.js', 'JavaScript'],  // ❌ 标签包含大写
+  publishedAt: '2025-12-31T10:00:00Z'
+};
+
+const result = validate(blogPostSchema, invalidPost);
+console.log('\n❌ 无效的博客文章:', result.valid);
+if (!result.valid) {
+  console.log('错误信息:');
+  result.errors.forEach(err => {
+    console.log(`  - ${err.path}: ${err.message}`);
+  });
+}
+
+// ========== 示例 5: URL 生成应用 ==========
+console.log('\n========== 示例 5: 自动生成 slug ==========');
+
+function generateSlug(title) {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')  // 替换非字母数字为连字符
+    .replace(/^-+|-+$/g, '');      // 移除首尾连字符
+}
+
+const titles = [
+  'Hello World!',
+  'Getting Started with Node.js',
+  'Top 10 JavaScript Tips & Tricks',
+  '2025年的技术趋势'
+];
+
+const urlSchema = dsl({ slug: 'slug!' });
+
+console.log('标题 → slug 转换:');
+titles.forEach(title => {
+  const slug = generateSlug(title);
+  const isValid = validate(urlSchema, { slug }).valid;
+  console.log(`  "${title}"`);
+  console.log(`    → "${slug}" ${isValid ? '✅' : '❌'}`);
+});
+
+// ========== 示例 6: 多语言支持 ==========
+console.log('\n========== 示例 6: 多语言错误消息 ==========');
+
+const { Validator } = require('../index');
+const validator = new Validator();
+
+const schema6 = dsl({ slug: 'slug!' });
+
+// 中文
+const resultCN = validator.validate(schema6, { slug: 'Invalid Slug!' }, { locale: 'zh-CN' });
+console.log('中文错误:', resultCN.errors[0]?.message);
+
+// 英文
+const resultEN = validator.validate(schema6, { slug: 'Invalid Slug!' }, { locale: 'en-US' });
+console.log('英文错误:', resultEN.errors[0]?.message);
+
+// 西班牙语
+const resultES = validator.validate(schema6, { slug: 'Invalid Slug!' }, { locale: 'es-ES' });
+console.log('西班牙语错误:', resultES.errors[0]?.message);
+
+// ========== 示例 7: 常见错误 ==========
+console.log('\n========== 示例 7: 常见 slug 错误 ==========');
+
+const testCases = [
+  { slug: 'valid-slug-123', expected: true, reason: '✅ 正确格式' },
+  { slug: 'Valid-Slug', expected: false, reason: '❌ 包含大写字母' },
+  { slug: 'hello_world', expected: false, reason: '❌ 包含下划线' },
+  { slug: 'hello world', expected: false, reason: '❌ 包含空格' },
+  { slug: '-hello', expected: false, reason: '❌ 以连字符开头' },
+  { slug: 'hello-', expected: false, reason: '❌ 以连字符结尾' },
+  { slug: 'hello--world', expected: false, reason: '❌ 连续连字符' },
+  { slug: 'hello.world', expected: false, reason: '❌ 包含点号' },
+  { slug: '123-456', expected: true, reason: '✅ 纯数字+连字符' },
+  { slug: 'a', expected: true, reason: '✅ 单个字母' },
+  { slug: '1', expected: true, reason: '✅ 单个数字' }
+];
+
+const testSchema = dsl({ slug: 'slug!' });
+
+console.log('测试用例:');
+testCases.forEach(({ slug, expected, reason }) => {
+  const result = validate(testSchema, { slug });
+  const passed = result.valid === expected;
+  console.log(`  ${passed ? '✅' : '❌'} "${slug}" - ${reason}`);
+});
+
+console.log('\n========== 所有示例完成 ==========');
+

package/index.d.ts

@@ -1,6 +1,6 @@
-// Type definitions for SchemaIO v2.1.2
-// Project: https://github.com/schema-dsl/schema-dsl
-// Definitions by: SchemaIO Team
+// Type definitions for schema-dsl v1.0.3
+// Project: https://github.com/vextjs/schema-dsl
+// Definitions by: schema-dsl Team
 
 
 declare module 'schema-dsl' {
@@ -130,9 +130,9 @@ declare module 'schema-dsl' {
    * ```
    */
   export interface ErrorMessages {
-    /** 最小长度/最小值错误 (v2.1.2+: 推荐使用min代替minLength) */
+    /** 最小长度/最小值错误 (v1.0.3+: 推荐使用min代替minLength) */
     min?: string;
-    /** 最大长度/最大值错误 (v2.1.2+: 推荐使用max代替maxLength) */
+    /** 最大长度/最大值错误 (v1.0.3+: 推荐使用max代替maxLength) */
     max?: string;
     /** 最小长度错误 (向后兼容，推荐使用min) */
     minLength?: string;
@@ -411,30 +411,100 @@ declare module 'schema-dsl' {
 
   /**
    * String 扩展全局接口
-   * 让字符串直接支持链式调用
+   *
+   * ⚠️ TypeScript 用户注意事项
+   *
+   * 由于 TypeScript 对全局扩展的类型推导限制，在 .ts 文件中使用链式调用时，
+   * 推荐使用 dsl() 函数包裹字符串以获得完整的类型提示：
    *
    * @example
    * ```typescript
+   * // ❌ 不推荐：可能缺少类型提示
+   * const schema = dsl({
+   *   email: 'email!'.label('邮箱')  // TypeScript 可能无法推导
+   * });
+   *
+   * // ✅ 推荐：使用 dsl() 包裹获得完整类型推导
    * const schema = dsl({
-   *   email: 'email!'.pattern(/custom/).label('邮箱')
+   *   email: dsl('email!').label('邮箱').pattern(/custom/)
+   * });
+   *
+   * // ✅ 也可以：先定义再使用
+   * const emailField = dsl('email!').label('邮箱');
+   * const schema = dsl({ email: emailField });
+   *
+   * // 📝 JavaScript 用户不受影响，可以直接使用
+   * const schema = dsl({
+   *   email: 'email!'.label('邮箱')  // JavaScript 中完全正常
    * });
    * ```
    */
   global {
     interface String {
+      /**
+       * 添加正则验证
+       * @deprecated TypeScript 用户请使用 dsl(string).pattern()
+       */
       pattern(regex: RegExp | string, message?: string): DslBuilder;
+
+      /**
+       * 设置字段标签
+       * @deprecated TypeScript 用户请使用 dsl(string).label()
+       */
       label(text: string): DslBuilder;
+
+      /**
+       * 自定义错误消息
+       * @deprecated TypeScript 用户请使用 dsl(string).messages()
+       */
       messages(messages: ErrorMessages): DslBuilder;
+
+      /**
+       * 设置描述
+       * @deprecated TypeScript 用户请使用 dsl(string).description()
+       */
       description(text: string): DslBuilder;
+
+      /**
+       * 自定义验证器
+       * @deprecated TypeScript 用户请使用 dsl(string).custom()
+       */
       custom(validator: (value: any) => boolean | Promise<boolean> | { error: string; message: string }): DslBuilder;
+
+      /**
+       * 条件验证
+       * @deprecated TypeScript 用户请使用 dsl(string).when()
+       */
       when(refField: string, options: { is: any; then: DslBuilder | JSONSchema; otherwise?: DslBuilder | JSONSchema }): DslBuilder;
+
+      /**
+       * 设置默认值
+       * @deprecated TypeScript 用户请使用 dsl(string).default()
+       */
       default(value: any): DslBuilder;
+
+      /**
+       * 转为 JSON Schema
+       * @deprecated TypeScript 用户请使用 dsl(string).toSchema()
+       */
       toSchema(): JSONSchema;
-      /** 用户名验证 */
+
+      /**
+       * 用户名验证
+       * @deprecated TypeScript 用户请使用 dsl(string).username()
+       */
       username(preset?: 'short' | 'medium' | 'long' | string): DslBuilder;
-      /** 密码强度验证 */
+
+      /**
+       * 密码强度验证
+       * @deprecated TypeScript 用户请使用 dsl(string).password()
+       */
       password(strength?: 'weak' | 'medium' | 'strong' | 'veryStrong'): DslBuilder;
-      /** 手机号验证 */
+
+      /**
+       * 手机号验证
+       * @deprecated TypeScript 用户请使用 dsl(string).phone()
+       */
       phone(country?: 'cn' | 'us' | 'uk' | 'hk' | 'tw' | 'international'): DslBuilder;
     }
   }
@@ -623,8 +693,25 @@ declare module 'schema-dsl' {
      * 
      * @example
      * ```typescript
+     * // 方式 1: 使用 i18n 配置（推荐，v1.0.4+）
+     * dsl.config({
+     *   i18n: {
+     *     locales: {
+     *       'zh-CN': { required: '必填' },
+     *       'en-US': { required: 'Required' }
+     *     }
+     *   }
+     * });
+     *
+     * // 方式 2: 使用 locales 配置（向后兼容）
+     * dsl.config({
+     *   locales: {
+     *     'zh-CN': { required: '必填' }
+     *   }
+     * });
+     *
+     * // 自定义手机号规则
      * dsl.config({
-     *   // 自定义手机号规则
      *   patterns: {
      *     phone: {
      *       cn: {
@@ -634,13 +721,15 @@ declare module 'schema-dsl' {
      *         key: 'phone.cn'
      *       }
      *     }
-     *   },
-     *   // 设置语言包
-     *   locales: 'zh-CN'
+     *   }
      * });
      * ```
      */
     export function config(options: {
+      /** i18n 配置（推荐，v1.0.4+） */
+      i18n?: I18nConfig;
+      /** 缓存配置 */
+      cache?: CacheConfig;
       /** 自定义验证规则 */
       patterns?: {
         /** 手机号规则 */
@@ -652,7 +741,7 @@ declare module 'schema-dsl' {
       };
       /** 手机号规则（兼容旧版） */
       phone?: Record<string, { pattern: RegExp; min?: number; max?: number; key?: string }>;
-      /** 语言包配置 */
+      /** 语言包配置（兼容旧版，推荐使用 i18n.locales） */
       locales?: Record<string, ErrorMessages> | string;
     }): void;
 
@@ -826,8 +915,8 @@ declare module 'schema-dsl' {
   }
 
   /**
-   * 便捷验证方法（推荐）
-   * 
+   * 便捷验证方法（同步）
+   *
    * @description 使用默认的单例Validator，无需new
    * 
    * @example
@@ -844,6 +933,146 @@ declare module 'schema-dsl' {
    */
   export function validate<T = any>(schema: JSONSchema | SchemaIO, data: any): ValidationResult<T>;
 
+  /**
+   * 便捷异步验证方法（推荐）
+   *
+   * @description
+   * - 异步验证数据，验证失败时抛出 ValidationError
+   * - 推荐在异步场景下使用此方法
+   * - 验证成功返回验证后的数据，失败抛出异常
+   *
+   * @param schema - JSON Schema对象或SchemaIO实例
+   * @param data - 要验证的数据
+   * @param options - 验证选项（可选）
+   * @returns 验证成功返回数据的Promise
+   * @throws {ValidationError} 验证失败时抛出
+   *
+   * @example
+   * ```typescript
+   * import { dsl, validateAsync, ValidationError } from 'schema-dsl';
+   *
+   * const schema = dsl({
+   *   email: dsl('email!').label('邮箱'),
+   *   username: dsl('string:3-32!').label('用户名')
+   * });
+   *
+   * try {
+   *   const validData = await validateAsync(schema, {
+   *     email: 'test@example.com',
+   *     username: 'testuser'
+   *   });
+   *   console.log('验证通过:', validData);
+   * } catch (error) {
+   *   if (error instanceof ValidationError) {
+   *     console.log('验证失败:', error.errors);
+   *     error.errors.forEach(err => {
+   *       console.log(`${err.path}: ${err.message}`);
+   *     });
+   *   }
+   * }
+   * ```
+   */
+  export function validateAsync<T = any>(
+    schema: JSONSchema | SchemaIO,
+    data: any,
+    options?: ValidatorOptions
+  ): Promise<T>;
+
+  /**
+   * 验证错误类
+   *
+   * @description 当 validateAsync 验证失败时抛出此错误
+   *
+   * @example
+   * ```typescript
+   * import { ValidationError, validateAsync, dsl } from 'schema-dsl';
+   *
+   * const schema = dsl({
+   *   email: dsl('email!').label('邮箱'),
+   *   age: dsl('number:18-100').label('年龄')
+   * });
+   *
+   * try {
+   *   await validateAsync(schema, { email: 'invalid' });
+   * } catch (error) {
+   *   if (error instanceof ValidationError) {
+   *     // 获取所有错误
+   *     console.log('错误列表:', error.errors);
+   *
+   *     // 获取错误数量
+   *     console.log('错误数量:', error.errors.length);
+   *
+   *     // 遍历处理每个字段错误
+   *     error.errors.forEach(err => {
+   *       console.log(`字段 ${err.path}: ${err.message}`);
+   *     });
+   *
+   *     // 转为 JSON 格式
+   *     const json = error.toJSON();
+   *     console.log('JSON格式:', json);
+   *   }
+   * }
+   * ```
+   */
+  export class ValidationError extends Error {
+    /** 错误名称（固定为 'ValidationError'） */
+    readonly name: 'ValidationError';
+
+    /** 错误消息 */
+    message: string;
+
+    /** 验证错误列表 */
+    errors: ValidationError[];
+
+    /**
+     * 构造函数
+     * @param errors - 验证错误数组
+     * @param message - 错误消息（可选）
+     */
+    constructor(errors: ValidationError[], message?: string);
+
+    /**
+     * 转为 JSON 格式
+     * @returns JSON 对象
+     */
+    toJSON(): {
+      name: string;
+      message: string;
+      errors: Array<{
+        field: string;
+        message: string;
+        keyword: string;
+        params?: Record<string, any>;
+      }>;
+    };
+
+    /**
+     * 获取指定字段的错误
+     * @param field - 字段路径
+     * @returns 错误对象或 null
+     */
+    getFieldError(field: string): ValidationError | null;
+
+    /**
+     * 获取所有字段的错误映射
+     * @returns 字段错误映射对象
+     */
+    getFieldErrors(): Record<string, ValidationError>;
+
+    /**
+     * 检查指定字段是否有错误
+     * @param field - 字段路径
+     * @returns 是否有错误
+     */
+    hasFieldError(field: string): boolean;
+
+    /**
+     * 获取错误总数
+     * @returns 错误数量
+     */
+    getErrorCount(): number;
+  }
+
   /**
    * 获取默认Validator实例（单例）
    *