schema-dsl 1.2.4 → 2.0.0

package/docs/type-converter.md

@@ -1,6 +1,6 @@
 # TypeConverter 类型转换工具
 
-> **模块**: `lib/utils/TypeConverter.js`  
+> **模块**: `src/utils/TypeConverter.ts`  
 
 > **用途**: 提供 JSON Schema 与各种数据库类型之间的转换
 
@@ -34,7 +34,7 @@
 ## 快速开始
 
 ```javascript
-const { TypeConverter } = require('schema-dsl/lib/utils');
+const { TypeConverter } = require('schema-dsl');
 
 // JSON Schema 类型转 MongoDB 类型
 const mongoType = TypeConverter.toMongoDBType('integer');
@@ -45,40 +45,29 @@ const mysqlType = TypeConverter.toMySQLType('string', { maxLength: 100 });
 console.log(mysqlType); // 'VARCHAR(100)'
 
 // JSON Schema 类型转 PostgreSQL 类型
-const pgType = TypeConverter.toPostgreSQLType('string', { format: 'uuid' });
-console.log(pgType); // 'UUID'
+const pgType = TypeConverter.toPostgreSQLType('string', { format: 'date-time' });
+console.log(pgType); // 'TIMESTAMP'
 ```
 
 ---
 
 ## API 参考
 
-### `toJSONSchemaType(simpleType)`
+### `toJSONSchemaType(nativeType)`
 
-将简单类型字符串转换为 JSON Schema 类型对象。
+将类型标识转换为 JSON Schema 的 `type` 字符串。
 
 ```javascript
 TypeConverter.toJSONSchemaType('string');
-// { type: 'string' }
+// 'string'
 
-TypeConverter.toJSONSchemaType('int');
-// { type: 'integer' }
+TypeConverter.toJSONSchemaType('integer');
+// 'integer'
 
-TypeConverter.toJSONSchemaType('bool');
-// { type: 'boolean' }
+TypeConverter.toJSONSchemaType('email');
+// 'string'
 ```
 
-**支持的别名**：
-
-| 完整类型 | 别名 |
-|---------|------|
-| `string` | `str`, `s` |
-| `number` | `num`, `n` |
-| `integer` | `int`, `i` |
-| `boolean` | `bool`, `b` |
-| `object` | `obj`, `o` |
-| `array` | `arr`, `a` |
-
 ---
 
 ### `toMongoDBType(jsonSchemaType)`
@@ -94,7 +83,7 @@ TypeConverter.toMongoDBType('boolean'); // 'bool'
 
 ---
 
-### `toMySQLType(jsonSchemaType, constraints)`
+### `toMySQLType(jsonSchemaType, schemaFragment)`
 
 JSON Schema 类型转 MySQL 数据类型。
 
@@ -115,21 +104,21 @@ TypeConverter.toMySQLType('string', { maxLength: 500 });
 TypeConverter.toMySQLType('string', { format: 'email' });
 // 'VARCHAR(255)'
 
-// 整数范围
-TypeConverter.toMySQLType('integer', { maximum: 100 });
+// 整数范围（minimum + maximum 命中 TINYINT 分支）
+TypeConverter.toMySQLType('integer', { minimum: 0, maximum: 100 });
 // 'TINYINT'
 ```
 
 ---
 
-### `toPostgreSQLType(jsonSchemaType, constraints)`
+### `toPostgreSQLType(jsonSchemaType, schemaFragment)`
 
 JSON Schema 类型转 PostgreSQL 数据类型。
 
 ```javascript
 // UUID 格式
 TypeConverter.toPostgreSQLType('string', { format: 'uuid' });
-// 'UUID'
+// 'VARCHAR(255)'  // 当前实现不会因 format=uuid 自动切换到 UUID 列类型
 
 // 日期时间
 TypeConverter.toPostgreSQLType('string', { format: 'date-time' });
@@ -142,34 +131,35 @@ TypeConverter.toPostgreSQLType('object');
 
 ---
 
-### `normalizePropertyName(name, style)`
+### `normalizePropertyName(name)`
 
-规范化属性名，转换命名风格。
+规范化属性名：去除首尾空白、将非法字符替换为下划线，并压缩连续下划线。
 
 ```javascript
-// camelCase 转 snake_case
-TypeConverter.normalizePropertyName('userName', 'snake_case');
+TypeConverter.normalizePropertyName('user name');
 // 'user_name'
 
-TypeConverter.normalizePropertyName('createdAt', 'snake_case');
-// 'created_at'
+TypeConverter.normalizePropertyName('123created-at');
+// '123created_at'
 ```
 
 ---
 
 ### `formatToRegex(format)`
 
-获取格式对应的正则表达式。
+获取格式对应的 `RegExp` 实例；未知格式返回 `null`。
 
 ```javascript
-TypeConverter.formatToRegex('email');
-// '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$'
+const emailRegex = TypeConverter.formatToRegex('email');
+emailRegex?.test('user@example.com');
+// true
 
-TypeConverter.formatToRegex('uuid');
-// '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+const uuidRegex = TypeConverter.formatToRegex('uuid');
+uuidRegex?.test('123e4567-e89b-12d3-a456-426614174000');
+// true
 
-TypeConverter.formatToRegex('ipv4');
-// IPv4 正则表达式
+TypeConverter.formatToRegex('unknown');
+// null
 ```
 
 ---
@@ -217,12 +207,8 @@ const constraints = TypeConverter.extractConstraints(schema);
 // {
 //   minLength: 3,
 //   maxLength: 32,
-//   minimum: undefined,
-//   maximum: undefined,
 //   pattern: '^[a-z]+$',
-//   format: 'email',
-//   enum: undefined,
-//   default: undefined
+//   format: 'email'
 // }
 ```
 
@@ -251,7 +237,7 @@ const constraints = TypeConverter.extractConstraints(schema);
 | `string` | `maxLength: 500` | `TEXT` |
 | `string` | `format: email` | `VARCHAR(255)` |
 | `string` | `format: date-time` | `DATETIME` |
-| `integer` | `maximum: 127` | `TINYINT` |
+| `integer` | `minimum: 0, maximum: 100` | `TINYINT` |
 | `integer` | `maximum: 32767` | `SMALLINT` |
 | `integer` | `maximum: 2147483647` | `INT` |
 | `integer` | - | `BIGINT` |
@@ -267,11 +253,9 @@ const constraints = TypeConverter.extractConstraints(schema);
 | `string` | - | `VARCHAR(255)` |
 | `string` | `maxLength: 50` | `VARCHAR(50)` |
 | `string` | `maxLength: 500` | `TEXT` |
-| `string` | `format: uuid` | `UUID` |
+| `string` | `format: uuid` | `VARCHAR(255)` |
 | `string` | `format: date` | `DATE` |
 | `string` | `format: date-time` | `TIMESTAMP` |
-| `integer` | `maximum: 32767` | `SMALLINT` |
-| `integer` | `maximum: 2147483647` | `INTEGER` |
 | `integer` | - | `BIGINT` |
 | `number` | - | `DOUBLE PRECISION` |
 | `boolean` | - | `BOOLEAN` |
@@ -285,7 +269,7 @@ const constraints = TypeConverter.extractConstraints(schema);
 ### 批量类型转换
 
 ```javascript
-const { TypeConverter } = require('schema-dsl/lib/utils');
+const { TypeConverter } = require('schema-dsl');
 
 const fields = ['string', 'number', 'integer', 'boolean', 'object', 'array'];
 
@@ -317,3 +301,10 @@ console.log(regex.test('invalid-email'));     // false
 - [MySQL 导出器](mysql-exporter.md)
 - [PostgreSQL 导出器](postgresql-exporter.md)
 
+---
+
+## 对应示例文件
+
+**示例入口**: [type-converter.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/type-converter.ts)  
+**说明**: 覆盖类型映射、枚举到 MySQL `ENUM(...)`、PostgreSQL 实际 UUID 映射、属性名规范化、正则获取、Schema 合并和约束提取。
+

package/docs/type-reference.md

@@ -1,6 +1,6 @@
-# schema-dsl 完整类型列表
+# schema-dsl 类型参考
 
-> **更新时间**: 2025-12-25  
+> **更新时间**: 2026-05-08  
 
 ---
 
@@ -8,7 +8,7 @@
 
 ### 基本类型
 
-| 类型 | SchemaI-DSL | JSON Schema | 说明 |
+| 类型 | schema-dsl DSL | JSON Schema | 说明 |
 |------|----------|-------------|------|
 | 字符串 | `string` | `{ type: 'string' }` | 文本类型 |
 | 数字 | `number` | `{ type: 'number' }` | 浮点数 |
@@ -23,14 +23,17 @@
 
 ### 格式类型（基于 string）
 
-| 类型 | SchemaI-DSL | JSON Schema format | 说明 |
+| 类型 | schema-dsl DSL | JSON Schema format | 说明 |
 |------|----------|-------------------|------|
 | 邮箱 | `email` | `email` | 邮箱地址 |
 | URL | `url` | `uri` | 网址 |
+| URI | `uri` | `uri` | URI 字符串 |
 | UUID | `uuid` | `uuid` | UUID格式 |
+| IP（IPv4/IPv6） | `ip` | `anyOf(ipv4, ipv6)` | 双栈 IP |
 | 日期 | `date` | `date` | YYYY-MM-DD |
 | 日期时间 | `datetime` | `date-time` | ISO 8601 |
 | 时间 | `time` | `time` | HH:mm:ss |
+| 主机名 | `hostname` | `hostname` | 主机名 |
 | IPv4 | `ipv4` | `ipv4` | IPv4地址 |
 | IPv6 | `ipv6` | `ipv6` | IPv6地址 |
 
@@ -38,13 +41,22 @@
 
 ### 特殊类型
 
-| 类型 | SchemaI-DSL | JSON Schema | 说明 |
+| 类型 | schema-dsl DSL | JSON Schema | 说明 |
 |------|----------|-------------|------|
 | 二进制 | `binary` | `contentEncoding: base64` | Base64编码 |
 | ObjectId | `objectId` | `pattern: ^[0-9a-fA-F]{24}$` | MongoDB ObjectId |
 | HexColor | `hexColor` | `pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$` | CSS 16进制颜色 |
 | MAC地址 | `macAddress` | `pattern: ^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$` | MAC地址 |
 | Cron | `cron` | `pattern: ...` | Cron表达式 |
+| Slug | `slug` | `pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$` | URL Slug |
+| 中文姓名 | `chineseName` | `pattern: ^[\u4e00-\u9fa5]{2,10}$` | 中文姓名 |
+| 中文文本 | `chinese` | `pattern: ^[\u4e00-\u9fa5]+$` | 纯中文文本 |
+| 邮箱域扩展 | `emailDomain` | `format: email` | 邮箱 + 域名扩展校验 |
+| 只含字母数字 | `alphanum` | `alphanum: true` | 自定义 AJV keyword |
+| 小写字符串 | `lower` | `lowercase: true` | 自定义 AJV keyword |
+| 大写字符串 | `upper` | `uppercase: true` | 自定义 AJV keyword |
+| JSON字符串 | `json` | `jsonString: true` | 自定义 AJV keyword |
+| 端口号 | `port` | `port: true` | 整数端口号 |
 
 ---
 
@@ -87,14 +99,14 @@ const schema8 = dsl({ data: 'any' });
 
 ---
 
-### 扩展验证类型
+### 参数化 DSL 类型
 
 ```javascript
-// 手机号
+// 手机号（默认 cn）
 const schema1 = dsl({ mobile: 'phone:cn!' });
 
 // 身份证
-const schema2 = dsl({ id_card: 'idCard:cn!' });
+const schema2 = dsl({ idCard: 'idCard:cn!' });
 
 // 信用卡
 const schema3 = dsl({ card: 'creditCard:visa!' });
@@ -106,7 +118,7 @@ const schema4 = dsl({ plate: 'licensePlate:cn!' });
 const schema5 = dsl({ zip: 'postalCode:cn!' });
 
 // 护照
-const schema6 = dsl({ passport: 'passport:cn!' });
+const schema6 = dsl({ passportNo: 'passport:cn!' });
 ```
 
 ---
@@ -156,7 +168,7 @@ const schema = dsl({
 
 ### 完整对照表
 
-| joi | SchemaI-DSL | 说明 |
+| joi | schema-dsl DSL | 说明 |
 |-----|--------------|------|
 | `Joi.string()` | `'string'` | 字符串 |
 | `Joi.string().email()` | `'email'` | 邮箱 |
@@ -190,23 +202,27 @@ const schema = dsl({
 
 ## ❓ 常见问题
 
-### Q1: 为什么没有 `Joi.alternatives()` 对应？
+### Q1: 为什么没有直接叫 `Joi.alternatives()` 的 API？
 
-A: 使用条件验证 `dsl.match()` 实现：
+A: schema-dsl 把这类需求拆成两类：
+
+- 单字段跨类型联合: 使用 `types:` 语法
+- 根据其他字段做条件分支: 使用 `dsl.match()`
 
 ```javascript
 const schema = dsl({
+  value: 'types:string|number',
   contactType: 'email|phone',
   contact: dsl.match('contactType', {
     email: 'email!',
-    phone: 'string:11!'
+    phone: 'phone:cn!'
   })
 });
 ```
 
 ### Q2: 为什么 `integer` 不是 `number().integer()`？
 
-A: SchemaI-DSL 使用 JSON Schema 标准，`integer` 是独立类型。
+A: schema-dsl 使用 JSON Schema 标准，`integer` 是独立类型。
 
 ### Q3: 不支持简写吗？
 
@@ -214,6 +230,13 @@ A: 不支持 `s`/`n`/`i`/`b` 等简写，统一使用完整类型名（`string`/
 
 ---
 
-**最后更新**: 2025-12-25
+**最后更新**: 2026-05-08
+
+---
+
+## 对应示例文件
+
+**示例入口**: [type-reference.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/type-reference.ts)  
+**说明**: 用一份 schema 串起常用内置类型、参数化 DSL 类型和运行时错误路径，方便快速核对实际支持范围。
 
 

package/docs/typescript-guide.md

@@ -1,7 +1,7 @@
 # TypeScript 使用指南
 
-> **版本**: schema-dsl v1.0.6+  
-> **更新日期**: 2026-01-04  
+> **版本**: schema-dsl v2.0.0-beta.2  
+> **更新日期**: 2026-05-08  
 > **重要**: v1.0.6 移除了全局 String 类型扩展以避免类型污染
 
 ---
@@ -106,7 +106,10 @@ const emailBuilder = dsl('email!');
 emailBuilder.label('邮箱')
 //          ^? IDE 自动提示所有可用方法
   .pattern(/^[a-z]+@[a-z]+\.[a-z]+$/)
-  .messages({ required: '邮箱必填' });
+  .error({ required: '邮箱必填' });
+
+> ℹ️ 当前类型声明优先覆盖稳定链式 API，例如 `label()`、`pattern()`、`error()`、`default()`。  
+> 某些运行时扩展方法依然可用，但如果类型声明未暴露，建议在 TypeScript 代码里优先改写为上述稳定组合。
 ```
 
 ---
@@ -128,12 +131,13 @@ emailBuilder.label('邮箱')
 ```typescript
 const schema = dsl({
   username: dsl('string:3-32!')
-    .pattern(/^[a-zA-Z0-9_]+$/, '只能包含字母、数字和下划线')
+    .pattern(/^[a-zA-Z0-9_]+$/)
     .label('用户名'),
+    .error({ pattern: '只能包含字母、数字和下划线' }),
   
   email: dsl('email!')
     .label('邮箱地址')
-    .messages({ required: '邮箱必填' }),
+    .error({ required: '邮箱必填' }),
   
   age: dsl('number:18-100')
     .label('年龄')
@@ -151,17 +155,21 @@ const schema = dsl({
 // 定义可复用的字段
 const emailField = dsl('email!')
   .label('邮箱地址')
-  .messages({ required: '邮箱必填' });
+  .error({ required: '邮箱必填' });
 
 const usernameField = dsl('string:3-32!')
   .pattern(/^[a-zA-Z0-9_]+$/)
-  .label('用户名');
+  .label('用户名')
+  .error({ pattern: '用户名只能包含字母、数字和下划线' });
 
 // 组合使用
 const registrationSchema = dsl({
   email: emailField,
   username: usernameField,
-  password: dsl('string:8-64!').password('strong')
+  password: dsl('string:8-64!')
+    .pattern(/^(?=.*[A-Za-z])(?=.*\d).{8,}$/)
+    .label('密码')
+    .error({ pattern: '密码至少 8 位且必须包含字母和数字' })
 });
 
 const loginSchema = dsl({
@@ -203,20 +211,18 @@ import { dsl, validateAsync, ValidationError } from 'schema-dsl';
 const registrationSchema = dsl({
   profile: dsl({
     username: dsl('string:3-32!')
-      .pattern(/^[a-zA-Z0-9_]+$/, '只能包含字母、数字和下划线')
+      .pattern(/^[a-zA-Z0-9_]+$/)
       .label('用户名')
-      .messages({
-        min: '用户名至少3个字符',
-        max: '用户名最多32个字符'
-      }),
+      .error({ pattern: '只能包含字母、数字和下划线' }),
     
     email: dsl('email!')
       .label('邮箱地址')
-      .messages({ required: '邮箱必填' }),
+      .error({ required: '邮箱必填' }),
     
-    password: dsl('string!')
-      .password('strong')
-      .label('密码'),
+    password: dsl('string:8-64!')
+      .pattern(/^(?=.*[A-Za-z])(?=.*\d).{8,}$/)
+      .label('密码')
+      .error({ pattern: '密码至少 8 位且必须包含字母和数字' }),
     
     age: dsl('number:18-100')
       .label('年龄')
@@ -269,7 +275,7 @@ registerUser({
 ### 4.2 API 请求验证
 
 ```typescript
-import { dsl, validateAsync } from 'schema-dsl';
+import { ValidationError, dsl, validateAsync } from 'schema-dsl';
 import express from 'express';
 
 const app = express();
@@ -322,15 +328,17 @@ import { dsl } from 'schema-dsl';
 const commonFields = {
   email: dsl('email!')
     .label('邮箱地址')
-    .messages({ required: '邮箱必填' }),
+    .error({ required: '邮箱必填' }),
   
   username: dsl('string:3-32!')
     .pattern(/^[a-zA-Z0-9_]+$/)
-    .label('用户名'),
+    .label('用户名')
+    .error({ pattern: '用户名只能包含字母、数字和下划线' }),
   
-  password: dsl('string!')
-    .password('strong')
+  password: dsl('string:8-64!')
+    .pattern(/^(?=.*[A-Za-z])(?=.*\d).{8,}$/)
     .label('密码')
+    .error({ pattern: '密码至少 8 位且必须包含字母和数字' })
 };
 
 // 注册表单
@@ -456,23 +464,21 @@ try {
 
 ## 6. 进阶技巧
 
-### 6.1 自定义验证器
+### 6.1 额外业务规则
 
 ```typescript
 const schema = dsl({
-  username: dsl('string:3-32!')
-    .custom(async (value) => {
-      // 异步验证（检查用户名是否已存在）
-      const exists = await checkUsernameExists(value);
-      if (exists) {
-        return { error: 'USERNAME_EXISTS', message: '用户名已存在' };
-      }
-      return true;
-    })
-    .label('用户名')
+  username: dsl('string:3-32!').label('用户名')
 });
+
+const result = await validateAsync(schema, data);
+if (result.username === 'admin') {
+  throw new Error('用户名已存在');
+}
 ```
 
+这种写法的好处是：结构校验仍由 schema-dsl 负责，业务唯一性、数据库查重等规则继续留在 TypeScript 业务层，避免把外部依赖塞进字段声明。
+
 ### 6.2 条件验证
 
 ```typescript
@@ -499,14 +505,14 @@ const baseUserSchema = dsl({
 });
 
 // 扩展为管理员 Schema
-const adminSchema = SchemaUtils.extend(baseUserSchema.toJsonSchema(), {
+const adminSchema = SchemaUtils.extend(baseUserSchema, {
   role: dsl('string!').default('admin').label('角色'),
   permissions: dsl('array<string>').label('权限列表')
 });
 
 // 只选择部分字段
 const publicUserSchema = SchemaUtils.pick(
-  baseUserSchema.toJsonSchema(),
+  baseUserSchema,
   ['username']
 );
 ```
@@ -515,16 +521,14 @@ const publicUserSchema = SchemaUtils.pick(
 
 ## 7. 性能优化
 
-### 7.1 Schema 预编译
+### 7.1 复用 Schema 与默认缓存
 
 ```typescript
-// 预编译 Schema（只编译一次）
 const schema = dsl({
   email: dsl('email!').label('邮箱')
 });
-schema.compile();  // 预编译
 
-// 多次验证（使用缓存的编译结果）
+// 多次验证会复用默认 Validator 的编译缓存
 await validateAsync(schema, data1);
 await validateAsync(schema, data2);
 await validateAsync(schema, data3);
@@ -554,7 +558,7 @@ dsl.config({
 4. ✅ **复用常用字段定义**
 5. ✅ **使用 `ValidationError` 类型守卫处理错误**
 6. ✅ **为用户提供友好的错误消息**
-7. ✅ **预编译常用的 Schema**
+7. ✅ **复用常用 Schema 对象，让默认缓存命中**
 
 ---
 
@@ -568,6 +572,13 @@ dsl.config({
 
 ---
 
-**更新日期**: 2025-12-31  
-**文档版本**: v1.0.4
+## 对应示例文件
+
+**示例入口**: [typescript-guide.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/typescript-guide.ts)  
+**说明**: 展示 TypeScript 下推荐的 `dsl()` 包裹写法、`validate<T>()` / `validateAsync<T>()`、以及 `ValidationError` 的字段错误读取方式。
+
+---
+
+**更新日期**: 2026-05-08  
+**文档版本**: v2.0.0-beta.2
 

package/docs/union-type-guide.md

@@ -2,6 +2,9 @@
 
 > 使用 `.pattern()` 方法匹配多种格式
 
+> ⚠️ 这篇文档描述的是“同一字符串字段匹配多种格式”的做法。  
+> 如果你需要真正的跨基础类型联合语义，例如 `string | number | null`，请优先使用 [types: 语法](./union-types.md)。
+
 ---
 
 ## 基本用法
@@ -137,11 +140,18 @@ testData.forEach((data, index) => {
 ```
 
 **输出**：
-```
+```text
 测试1: ✅
 测试2: ✅
 测试3: ❌
   错误: 必须是邮箱或手机号
 ```
 
+---
+
+## 对应示例文件
+
+**示例入口**: [union-type-guide.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/union-type-guide.ts)  
+**说明**: 展示基于 `.pattern()` 的“单个字符串字段匹配多种格式”方案，以及对应的中英文错误消息。
+
 

package/docs/union-types.md

@@ -55,7 +55,7 @@ validate(schema, { value: 101 });      // ❌ 超范围
 
 ### 基本格式
 
-```
+```text
 types:type1|type2|type3[!]
 ```
 
@@ -65,7 +65,7 @@ types:type1|type2|type3[!]
 
 ### 带约束格式
 
-```
+```text
 types:type1:constraint1|type2:constraint2
 ```
 
@@ -267,7 +267,7 @@ DslBuilder.registerType('phone_cn', { ... });
 
 - [插件系统](./plugin-system.md)
 - [自定义类型注册](./plugin-type-registration.md)
-- [代码规范](../specs/rules/代码规范.md)
+- [贡献指南](https://github.com/vextjs/schema-dsl/blob/main/CONTRIBUTING.md)
 
 ---
 
@@ -275,3 +275,10 @@ DslBuilder.registerType('phone_cn', { ... });
 
 - **v1.1.0** - 首次发布跨类型联合验证功能
 
+---
+
+## 对应示例文件
+
+**示例入口**: [union-types.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/union-types.ts)  
+**说明**: 覆盖 `types:` 语法的 `oneOf` 生成、字符串/数字联合，以及内置类型与自定义类型混用路径。
+