schema-dsl 1.2.4 → 2.0.0

package/docs/plugin-type-registration.md

@@ -0,0 +1,34 @@
+# 自定义类型注册
+
+当前版本通过 `TypeRegistry` 提供类型注册能力；如果你更偏向 DSL 侧入口，也可以使用 `DslBuilder.registerType()`，它内部会委托给 `TypeRegistry`。
+
+```javascript
+const { TypeRegistry, dsl } = require('schema-dsl');
+
+TypeRegistry.register('evenNumber', {
+  baseSchema: { type: 'number', multipleOf: 2 }
+});
+
+const schema = dsl({ value: 'evenNumber!' });
+```
+
+如果你希望统一从 Builder 侧管理自定义类型，也可以这样写：
+
+```javascript
+const { DslBuilder } = require('schema-dsl');
+
+DslBuilder.registerType('orderCode', {
+  type: 'string',
+  pattern: '^ORD\\d{6}$'
+});
+```
+
+插件化扩展可结合 [plugin-system.md](./plugin-system.md) 使用。
+
+---
+
+## 对应示例文件
+
+**示例入口**: [plugin-type-registration.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/plugin-type-registration.ts)  
+**说明**: 同时覆盖 `TypeRegistry.register()` 和 `DslBuilder.registerType()` 两条入口，以及注册后的真实验证与清理流程。
+

package/docs/postgresql-exporter.md

@@ -1,6 +1,6 @@
 # PostgreSQL 导出器文档
 
-> **模块**: `lib/exporters/PostgreSQLExporter.js`  
+> **模块**: `src/exporters/PostgreSQLExporter.ts`  
 
 > **用途**: 将 JSON Schema 转换为 PostgreSQL CREATE TABLE 语句
 
@@ -20,7 +20,7 @@
 
 ## 概述
 
-`PostgreSQLExporter` 将 SchemaI-DSL 生成的 JSON Schema 转换为 PostgreSQL 的 DDL 语句，支持丰富的 PostgreSQL 特性。
+`PostgreSQLExporter` 将 schema-dsl 生成的 JSON Schema 转换为 PostgreSQL 的 DDL 语句，支持丰富的 PostgreSQL 特性。
 
 ### 核心功能
 
@@ -302,3 +302,10 @@ exporter.generateIndex('users', 'metadata', { method: 'gin' });
 - [TypeConverter](type-converter.md)
 - [**导出限制说明**](export-limitations.md) ⚠️
 
+---
+
+## 对应示例文件
+
+**示例入口**: [postgresql-exporter.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/postgresql-exporter.ts)  
+**说明**: 覆盖 PostgreSQL DDL 导出、CHECK 约束示意，以及 `generateIndex()` 生成 `gin` 索引。
+

package/docs/public/favicon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
+  <rect width="64" height="64" rx="14" fill="#0F172A" />
+  <path d="M18 22.5L32 14L46 22.5V41.5L32 50L18 41.5V22.5Z" fill="#38BDF8" />
+  <path d="M32 20L40 24.8V34.2L32 39L24 34.2V24.8L32 20Z" fill="#E2E8F0" />
+</svg>

package/docs/quick-start.md

@@ -28,6 +28,10 @@
 npm install schema-dsl
 ```
 
+> **Node.js 要求**：`>=18.0.0`
+> 
+> 当前 TypeScript 重构版以 `Node.js >=18.0.0` 为唯一运行时基线，不再承诺旧 Node 版本兼容。
+
 ---
 
 ## 📖 5分钟快速入门
@@ -135,34 +139,32 @@ const schema = dsl({
 ### 4. 完整示例（2分钟）
 
 ```javascript
-const { dsl, Validator } = require('schema-dsl');
+const { dsl, validate } = require('schema-dsl');
 
 // 定义用户注册Schema
 const registerSchema = dsl({
   // 用户名：正则验证
-  username: 'string:3-32!'
+  username: dsl('string:3-32!')
     .pattern(/^[a-zA-Z0-9_]+$/)
     .label('用户名')
-    .messages({
-      'pattern': '只能包含字母、数字和下划线',
-      'min': '至少3个字符',
-      'max': '最多32个字符'
+    .error({
+      pattern: '只能包含字母、数字和下划线'
     }),
   
   // 邮箱：标签
-  email: 'email!'.label('邮箱地址'),
+  email: dsl('email!').label('邮箱地址'),
   
   // 密码：复杂正则
-  password: 'string:8-64!'
+  password: dsl('string:8-64!')
     .pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$/)
     .label('密码')
-    .messages({
-      'pattern': '必须包含大小写字母和数字'
+    .error({
+      pattern: '必须包含大小写字母和数字'
     }),
   
   // 简单字段
   age: 'number:18-120',
-  gender: 'male|female|other'
+  role: 'user|admin'
 });
 
 // 验证数据
@@ -171,7 +173,7 @@ const testData = {
   email: 'john@example.com',
   password: 'Password123',
   age: 25,
-  gender: 'male'
+  role: 'user'
 };
 
 const result = validate(registerSchema, testData);
@@ -236,12 +238,13 @@ const formSchema = dsl({
 
 ### 自定义验证
 
+> `.custom()` 当前仅支持同步函数；如果需要异步查重，请在 `validate()` / `validateAsync()` 通过后于业务层单独执行。
+
 ```javascript
 const schema = dsl({
   username: 'string:3-32!'
-    .custom(async (value) => {
-      const exists = await checkUsernameExists(value);
-      if (exists) {
+    .custom((value) => {
+      if (value === 'admin') {
         return '用户名已存在';
       }
     })
@@ -277,9 +280,9 @@ const schema = dsl({
 
 ### 示例代码
 
-- [String扩展完整示例](../examples/string-extensions.js)
-- [用户注册示例](../examples/user-registration/)
-- [数据库导出示例](../examples/export-demo.js)
+- [Quick Start 完整示例](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/quick-start.ts)
+
+其余主题示例现在都已分别挂到各自文档底部，并统一切到稳定 GitHub 示例链接。
 
 ### 高级功能
 
@@ -344,31 +347,20 @@ Schema-DSL 使用**运行时解析 DSL**，而非编译时构建（如 Zod），
 
 #### ⚠️ 性能权衡
 
-运行时解析的代价是性能略低于编译时构建：
+S1 有效数据与 Zod 持平，S3 嵌套场景快约 28%，无效数据公平对比快 89x：
 
-| 库名 | 每秒操作数 | 说明 |
+| 库名 | 性能 | 场景 |
 |------|-----------|------|
-| Ajv | 2,000,000 ops/s | 原生 JSON Schema（最快） |
-| Zod | 526,316 ops/s | 编译时构建 |
-| **Schema-DSL** | **277,778 ops/s** | 运行时解析（第3名） |
-| Joi | 97,087 ops/s | 功能丰富 |
-| Yup | 60,241 ops/s | React 生态 |
+| Ajv (raw) | 4.732M ops/s | 底层引擎，无 DSL 层 |
+| **Schema-DSL** | **1.301M ops/s**（S1有效） | 全功能（DSL + i18n + coerce）|
+| **Schema-DSL** | **1.205M ops/s**（S2 无效，均无 i18n）| 公平对比（均无 i18n）|
+| Zod | 1.305M ops/s（S1有效）/ 13.49K（S2 无效）| 编译时构建，错误路径异常驱动 |
+| Joi | 154K ops/s | 功能丰富 |
 
 **结论**:
-- ✅ Schema-DSL 比 Joi 快 **2.86倍**，比 Yup 快 **4.61倍**
-- ✅ 对大多数应用足够（27万+ ops/s）
-- ⚠️ 如需极致性能（>50万 ops/s），推荐使用 Zod 或 Ajv
-
-**权衡**:
-```
-损失: 比 Zod 慢 1.9倍
-换来: 
-  ✅ 代码量减少 65%
-  ✅ 完全动态的验证规则
-  ✅ 多租户/配置驱动支持
-  ✅ 前后端共享规则
-  ✅ 低代码平台基础
-```
+- ✅ S3 嵌套有效场景比 Zod 快 **28%**；S1 简单有效场景持平（差 <1%）
+- ✅ 无效数据公平对比（均无 i18n）比 Zod 快 **89x**
+- ✅ 内置缓存，热路径零解析开销
 
 ### 适用场景
 
@@ -413,13 +405,13 @@ uninstallStringExtensions();
 
 ### Q: 支持TypeScript吗？
 
-**A**: 支持！SchemaI-DSL提供完整的TypeScript类型定义。
+**A**: 支持！schema-dsl 提供完整的 TypeScript 类型定义。
 
 ---
 
 ## 🎉 恭喜！
 
-你已经掌握了SchemaI-DSL的核心用法！
+你已经掌握了 schema-dsl 的核心用法！
 
 **核心要点**:
 1. ✅ DSL语法简洁直观
@@ -431,331 +423,13 @@ uninstallStringExtensions();
 
 ---
 
----
-
-**最后更新**: 2025-12-26
-- [🔧 自定义验证](#-自定义验证)
-- [🗄️ 数据库导出](#️-数据库导出)
-- [📚 下一步](#-下一步)
-
----
-
-## 🚀 安装
-
-```bash
-npm install schema-dsl
-```
-
----
-
-## 📖 5分钟快速入门
-
-### 1. Hello World（30秒）
-
-```javascript
-const { dsl, Validator } = require('schema-dsl');
-
-// 定义Schema
-const schema = dsl({
-  name: 'string:1-50!',
-  email: 'email!'
-});
-
-// 验证数据
-const validator = new Validator();
-const result = validator.validate(schema, {
-  name: '张三',
-  email: 'zhangsan@example.com'
-});
-
-console.log(result.valid); // true
-```
-
-**解释**:
-- `'string:1-50!'` - 必填字符串，长度1-50
-- `'email!'` - 必填邮箱
-- `!` 表示必填
-
----
-
-### 2. DSL 语法速查（1分钟）
-
-```javascript
-// 基本类型
-'string'           // 字符串
-'number'           // 数字
-'integer'          // 整数
-'boolean'          // 布尔值
-'email'            // 邮箱
-'url'              // URL
-'date'             // 日期
-
-// 约束
-'string:3-32'      // 长度3-32（范围）
-'string:100'       // 最大长度100（简写）
-'string:-100'      // 最大长度100（明确写法）
-'string:10-'       // 最小长度10（无最大限制）
-'number:18-120'    // 范围18-120
-
-// 必填
-'string!'          // 必填字符串
-'email!'           // 必填邮箱
-
-// 枚举
-'active|inactive|pending'    // 三选一
-
-// 数组
-'array<string>'              // 字符串数组
-'array:1-10<string>'         // 1-10个字符串
-'array<string:1-50>'         // 带约束的数组元素
-```
-
-**语法规则**:
-- `type:max` → 最大值（简写）
-- `type:min-max` → 范围
-- `type:min-` → 只限最小
-- `type:-max` → 只限最大
-
----
-
-### 3. String 扩展 - 核心特性（2分钟）
-
-字符串支持链式调用：
+## 对应示例文件
 
-```javascript
-const schema = dsl({
-  // ✨ 字符串直接链式调用，无需 dsl() 包裹
-  email: 'email!'
-    .pattern(/custom/)
-    .label('邮箱地址'),
-  
-  username: 'string:3-32!'
-    .pattern(/^[a-zA-Z0-9_]+$/)
-    .messages({
-      'string.pattern': '只能包含字母、数字和下划线'
-    })
-    .label('用户名'),
-  
-  // 简单字段仍然可以用纯DSL
-  age: 'number:18-120',
-  role: 'user|admin'
-});
-```
-
-**可用方法**:
-- `.pattern(regex)` - 正则验证
-- `.label(text)` - 字段标签
-- `.messages(obj)` - 自定义消息
-- `.description(text)` - 描述
-- `.custom(fn)` - 自定义验证器
+**示例入口**: [quick-start.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/quick-start.ts)  
+**说明**: 覆盖快速上手中的 Hello World、String 扩展、用户注册示例，以及 `validate()` 与 `Validator.compile()` 的基础复用路径，可直接运行参考。
 
 ---
 
-### 4. 完整示例（2分钟）
-
-```javascript
-const { dsl, validate } = require('schema-dsl');
-
-// 定义用户注册Schema
-const registerSchema = dsl({
-  // 用户名：正则验证
-  username: 'string:3-32!'
-    .pattern(/^[a-zA-Z0-9_]+$/)
-    .label('用户名')
-    .messages({
-      'pattern': '只能包含字母、数字和下划线',
-      'min': '至少3个字符',
-      'max': '最多32个字符'
-    }),
-  
-  // 邮箱：标签
-  email: 'email!'.label('邮箱地址'),
-  
-  // 密码：复杂正则
-  password: 'string:8-64!'
-    .pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$/)
-    .label('密码')
-    .messages({
-      'pattern': '必须包含大小写字母和数字'
-    }),
-  
-  // 简单字段
-  age: 'number:18-120',
-  gender: 'male|female|other'
-});
-
-// 验证数据
-const testData = {
-  username: 'john_doe',
-  email: 'john@example.com',
-  password: 'Password123',
-  age: 25,
-  gender: 'male'
-};
-
-const result = validate(registerSchema, testData);
-
-if (result.valid) {
-  console.log('✅ 验证通过！');
-} else {
-  console.log('❌ 验证失败:', result.errors);
-}
-```
-
----
-
-## 💡 最佳实践
-
-### 1. 简单字段用纯DSL
-
-```javascript
-const schema = dsl({
-  name: 'string:1-50!',     // ✅ 简洁
-  age: 'number:18-120',     // ✅ 清晰
-  role: 'user|admin'        // ✅ 直观
-});
-```
-
-### 2. 复杂字段用String扩展
-
-```javascript
-const schema = dsl({
-  email: 'email!'
-    .pattern(/custom/)
-    .messages({...})
-    .label('邮箱'),
-  
-  username: 'string:3-32!'
-    .pattern(/^\w+$/)
-    .custom(checkExists)
-});
-```
-
-### 3. 80/20 法则
-
-**80%字段用纯DSL，20%字段用String扩展**
-
----
-
-## 🎯 常见场景
-
-### 表单验证
-
-```javascript
-const formSchema = dsl({
-  email: 'email!'.label('邮箱地址'),
-  password: 'string:8-64!'.label('密码'),
-  nickname: 'string:2-20'.label('昵称'),
-  bio: 'string:500',
-  website: 'url',
-  age: 'number:18-120',
-  gender: 'male|female|other'
-});
-```
-
-### 自定义验证
-
-```javascript
-const schema = dsl({
-  username: 'string:3-32!'
-    .custom(async (value) => {
-      const exists = await checkUsernameExists(value);
-      if (exists) {
-        return { error: 'username.exists', message: '用户名已存在' };
-      }
-      return true;
-    })
-});
-```
-
-### 嵌套对象
-
-```javascript
-const schema = dsl({
-  user: {
-    profile: {
-      name: 'string:1-50!'.label('姓名'),
-      avatar: 'url'.label('头像'),
-      social: {
-        twitter: 'url'.pattern(/twitter\.com/),
-        github: 'url'.pattern(/github\.com/)
-      }
-    }
-  }
-});
-```
-
----
-
-## 📚 下一步
-
-### 深入学习
-
-- [DSL 语法完整指南](./dsl-syntax.md)
-- [API 参考文档](./api-reference.md)
-- [String 扩展文档](./string-extensions.md)
-
-### 示例代码
-
-- [String扩展完整示例](../examples/string-extensions.js)
-- [用户注册示例](../examples/user-registration/)
-- [数据库导出示例](../examples/export-demo.js)
-
-### 高级功能
-
-- [自定义验证器](./api-reference.md#custom)
-- [条件验证（when）](./api-reference.md#when)
-- [数据库Schema导出](./api-reference.md#导出器)
-
----
-
-## 🆘 常见问题
-
-### Q: String扩展和纯DSL有什么区别？
-
-**A**: 
-- **纯DSL**: 适合简单字段，语法简洁
-- **String扩展**: 适合复杂验证，支持链式调用
-
-```javascript
-// 纯DSL（简单）
-name: 'string:1-50!'
-
-// String扩展（复杂）
-email: 'email!'
-  .pattern(/custom/)
-  .messages({...})
-```
-
-### Q: 如何禁用String扩展？
-
-**A**: 
-```javascript
-const { uninstallStringExtensions } = require('schema-dsl');
-uninstallStringExtensions();
-```
-
-### Q: 支持TypeScript吗？
-
-**A**: 支持！SchemaI-DSL提供完整的TypeScript类型定义。
-
----
-
-## 🎉 恭喜！
-
-你已经掌握了SchemaI-DSL的核心用法！
-
-**核心要点**:
-1. ✅ DSL语法简洁直观
-2. ✅ String扩展强大灵活
-3. ✅ 80%用DSL，20%用扩展
-4. ✅ 字符串可以直接链式调用
-
-**开始使用**: `npm install schema-dsl`
-
----
-
-
-**最后更新**: 2025-12-25
+**最后更新**: 2026-05-08
 
 

package/docs/runtime-locale-support.md

@@ -188,13 +188,17 @@ dsl.error.assert(
 ```javascript
 const { dsl } = require('schema-dsl');
 
+function getRequestLocale(acceptLanguage) {
+  return acceptLanguage?.split(',')[0]?.trim() || 'zh-CN';
+}
+
 // Express 中间件
 app.get('/api/account/:id', async (req, res, next) => {
   try {
     const account = await getAccount(req.params.id);
     
     // 根据请求头获取语言
-    const locale = req.headers['accept-language'] || 'zh-CN';
+    const locale = getRequestLocale(req.headers['accept-language']);
     
     // 使用运行时语言抛出错误
     dsl.error.assert(account, 'account.notFound', {}, 404, locale);
@@ -236,7 +240,7 @@ async function getUserService(userId, locale) {
 // 服务 B: API 网关
 app.get('/api/users/:id', async (req, res) => {
   try {
-    const locale = req.headers['accept-language'] || 'zh-CN';
+    const locale = getRequestLocale(req.headers['accept-language']);
     
     // 调用用户服务，传递 locale
     const user = await getUserService(req.params.id, locale);
@@ -343,7 +347,7 @@ const resolvers = {
 // ❌ 并发不安全
 app.get('/api/account/:id', async (req, res) => {
   // 修改全局状态
-  Locale.setLocale(req.headers['accept-language']);
+  Locale.setLocale(req.headers['accept-language']?.split(',')[0]?.trim() || 'zh-CN');
   
   // 如果同时有多个请求，语言会互相干扰
   const error = dsl.error.create('account.notFound');
@@ -356,7 +360,7 @@ app.get('/api/account/:id', async (req, res) => {
 ```javascript
 // ✅ 并发安全
 app.get('/api/account/:id', async (req, res) => {
-  const locale = req.headers['accept-language'];
+  const locale = req.headers['accept-language']?.split(',')[0]?.trim() || 'zh-CN';
   
   // 不修改全局状态，每个请求独立
   const error = dsl.error.create('account.notFound', {}, 404, locale);
@@ -422,7 +426,7 @@ console.log(error2.message);  // "Insufficient balance, current: 50, required: 1
 ```javascript
 // ✅ 推荐
 app.get('/api/account/:id', async (req, res) => {
-  const locale = req.headers['accept-language'] || 'zh-CN';
+  const locale = req.headers['accept-language']?.split(',')[0]?.trim() || 'zh-CN';
   
   try {
     const account = await getAccount(req.params.id);
@@ -435,7 +439,7 @@ app.get('/api/account/:id', async (req, res) => {
 
 // ❌ 不推荐
 app.get('/api/account/:id', async (req, res) => {
-  Locale.setLocale(req.headers['accept-language']);  // 并发不安全
+  Locale.setLocale(req.headers['accept-language']?.split(',')[0]?.trim() || 'zh-CN');  // 并发不安全
   // ...
 });
 ```
@@ -446,7 +450,7 @@ app.get('/api/account/:id', async (req, res) => {
 // 工具函数
 function getUserLocale(req) {
   return req.user?.locale || 
-         req.headers['accept-language'] || 
+         req.headers['accept-language']?.split(',')[0]?.trim() || 
          'zh-CN';
 }
 
@@ -504,7 +508,7 @@ app.get('/api/users/:id', async (req, res) => {
 - 现有代码无需修改
 - `locale` 参数为可选参数
 - 不传 `locale` 时使用全局语言
-- 所有单元测试通过（949/949）
+- 相关单元测试已覆盖
 
 ---
 
@@ -516,6 +520,13 @@ app.get('/api/users/:id', async (req, res) => {
 
 ---
 
-**最后更新**: 2026-01-13  
+## 对应示例文件
+
+**示例入口**: [runtime-locale-support.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/runtime-locale-support.ts)  
+**说明**: 覆盖运行时指定 locale 创建错误对象、参数插值，以及“局部语言切换不污染全局状态”的关键行为。
+
+---
+
+**最后更新**: 2026-05-08  
 **作者**: schema-dsl Team
 

package/docs/schema-helper.md

@@ -1,6 +1,6 @@
 # SchemaHelper Schema辅助工具
 
-> **模块**: `lib/utils/SchemaHelper.js`  
+> **模块**: `src/utils/SchemaHelper.ts`  
 
 > **用途**: 提供 JSON Schema 操作的常用辅助方法
 
@@ -36,8 +36,7 @@
 ## 快速开始
 
 ```javascript
-const { SchemaHelper } = require('schema-dsl/lib/utils');
-const { dsl } = require('schema-dsl');
+const { SchemaHelper, dsl } = require('schema-dsl');
 
 // 创建 Schema
 const userSchema = dsl({
@@ -263,8 +262,7 @@ const summary = SchemaHelper.summarizeSchema(userSchema);
 ### Schema 分析工具
 
 ```javascript
-const { SchemaHelper } = require('schema-dsl/lib/utils');
-const { dsl } = require('schema-dsl');
+const { SchemaHelper, dsl } = require('schema-dsl');
 
 function analyzeSchema(schema, name = 'Schema') {
   console.log(`\n=== ${name} 分析 ===`);
@@ -338,3 +336,10 @@ function compareSchemaVersions(oldSchema, newSchema) {
 - [SchemaUtils](schema-utils.md)
 - [API 参考](api-reference.md)
 
+---
+
+## 对应示例文件
+
+**示例入口**: [schema-helper.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/schema-helper.ts)  
+**说明**: 覆盖 `isValidSchema()`、`generateSchemaId()`、`flattenSchema()`、`extractRequiredFields()`、`summarizeSchema()` 与 `compareSchemas()`。
+