schema-dsl 1.2.4 → 2.0.0

package/changelogs/v1.1.0.md

@@ -1,389 +0,0 @@
-# v1.1.0 变更日志
-
-> **发布日期**: 2026-01-05  
-> **版本号**: v1.1.0  
-> **类型**: 🎉 重大功能发布
-
----
-
-## 📋 变更概览
-
-| 类型 | 数量 | 说明 |
-|------|------|------|
-| 🎉 新功能 | 2 | 跨类型联合验证、运行时多语言支持 |
-| ⚡ 功能增强 | 1 | 插件系统增强 |
-| 📚 文档更新 | 3 | 新增联合类型、运行时多语言、插件文档 |
-
----
-
-## 🎉 新功能
-
-### 1. 跨类型联合验证 (Union Types)
-
-**一行代码支持多种类型，告别繁琐的类型判断**
-
-#### 基础用法
-
-```javascript
-const { dsl, validate } = require('schema-dsl');
-
-// 字段可以是字符串或数字
-const schema = dsl({
-  value: 'types:string|number'
-});
-
-validate(schema, { value: 'hello' });  // ✅ 通过
-validate(schema, { value: 123 });      // ✅ 通过
-validate(schema, { value: true });     // ❌ 失败
-```
-
-#### 带约束的联合类型
-
-```javascript
-// 邮箱或手机号
-const schema1 = dsl({
-  contact: 'types:email|phone!'
-});
-
-// 数字价格或"面议"字符串
-const schema2 = dsl({
-  price: 'types:number:0-|string:1-20'
-});
-
-// 枚举或空值
-const schema3 = dsl({
-  status: 'types:active|inactive|null'
-});
-```
-
-#### 实际应用场景
-
-**场景1：用户注册 - 支持邮箱或手机号**
-```javascript
-const registerSchema = dsl({
-  username: 'string:3-20!',
-  contact: 'types:email|phone!',  // 灵活的联系方式
-  password: 'string:8-32!',
-  age: 'types:integer:1-150|null' // 年龄可选
-});
-
-// ✅ 使用邮箱注册
-validate(registerSchema, {
-  username: 'john',
-  contact: 'john@example.com',
-  password: '12345678',
-  age: 25
-});
-
-// ✅ 使用手机号注册
-validate(registerSchema, {
-  username: 'jane',
-  contact: '13800138000',
-  password: 'abcd1234',
-  age: null
-});
-```
-
-**场景2：商品价格 - 数字或"面议"**
-```javascript
-const productSchema = dsl({
-  name: 'string:1-100!',
-  price: 'types:number:0-|string:1-20',  // 价格或"面议"
-  stock: 'integer:0-'
-});
-
-// ✅ 数字价格
-validate(productSchema, {
-  name: '商品A',
-  price: 99.99,
-  stock: 100
-});
-
-// ✅ "面议"价格
-validate(productSchema, {
-  name: '商品B',
-  price: '面议',
-  stock: 0
-});
-```
-
-**场景3：API参数 - 单个ID或ID数组**
-```javascript
-const querySchema = dsl({
-  id: 'types:string|array<string>'  // 单个或多个ID
-});
-
-// ✅ 单个ID
-validate(querySchema, { id: '123' });
-
-// ✅ ID数组
-validate(querySchema, { id: ['123', '456', '789'] });
-```
-
-#### 技术实现
-
-- ✅ 支持基础类型联合：`string|number|boolean`
-- ✅ 支持格式类型联合：`email|phone|url`
-- ✅ 支持带约束的联合：`number:0-100|string:1-20`
-- ✅ 支持null值：`string|null`
-- ✅ 支持数组类型：`string|array<string>`
-
----
-
-### 2. 运行时多语言支持
-
-**无需修改全局设置，每次调用时指定语言**
-
-#### 核心API
-
-**dsl.error.create()** - 创建多语言错误
-```javascript
-dsl.error.create(
-  code: string,          // 错误代码（如 'account.notFound'）
-  params?: object,       // 参数插值（如 { balance: 50 }）
-  statusCode?: number,   // HTTP 状态码（默认 400）
-  locale?: string        // 🆕 运行时语言（如 'en-US'）
-): I18nError
-```
-
-**dsl.error.throw()** - 抛出多语言错误
-```javascript
-dsl.error.throw(
-  code: string,
-  params?: object,
-  statusCode?: number,
-  locale?: string        // 🆕 运行时语言
-): never
-```
-
-**dsl.error.assert()** - 断言多语言错误
-```javascript
-dsl.error.assert(
-  condition: any,
-  code: string,
-  params?: object,
-  statusCode?: number,
-  locale?: string        // 🆕 运行时语言
-): void
-```
-
-#### 使用示例
-
-**方式1：根据请求头动态返回不同语言**
-```javascript
-app.post('/api/account', (req, res) => {
-  const locale = req.headers['accept-language'] || 'en-US';
-  const account = getAccount(req.user.id);
-  
-  try {
-    // 运行时指定语言，不影响全局设置
-    dsl.error.assert(account, 'account.notFound', {}, 404, locale);
-    
-    dsl.error.assert(
-      account.balance >= 100,
-      'account.insufficientBalance',
-      { balance: account.balance, required: 100 },
-      400,
-      locale
-    );
-    
-    // 验证通过，继续处理...
-    res.json({ success: true });
-  } catch (error) {
-    // 错误消息已经是请求的语言
-    res.status(error.statusCode).json(error.toJSON());
-  }
-});
-```
-
-**方式2：同一请求中使用多种语言**
-```javascript
-// 创建不同语言的错误消息
-const error1 = dsl.error.create('account.notFound', {}, 404, 'zh-CN');
-console.log(error1.message);  // "账户不存在"
-console.log(error1.locale);   // "zh-CN"
-
-const error2 = dsl.error.create('account.notFound', {}, 404, 'en-US');
-console.log(error2.message);  // "Account not found"
-console.log(error2.locale);   // "en-US"
-
-const error3 = dsl.error.create('account.notFound', {}, 404, 'ja-JP');
-console.log(error3.message);  // "アカウントが見つかりません"
-console.log(error3.locale);   // "ja-JP"
-```
-
-**方式3：微服务架构 - 错误传递保持原语言**
-```javascript
-// 服务A抛出错误（带语言信息）
-class ServiceA {
-  async getAccount(id, locale) {
-    const account = await db.findAccount(id);
-    dsl.error.assert(account, 'account.notFound', {}, 404, locale);
-    return account;
-  }
-}
-
-// 服务B接收错误（保持原语言）
-class ServiceB {
-  async processAccount(accountId, locale) {
-    try {
-      const account = await serviceA.getAccount(accountId, locale);
-      // 处理账户...
-    } catch (error) {
-      if (error instanceof I18nError) {
-        // 错误消息保持原语言
-        console.log(error.locale);   // locale 参数传入的语言
-        console.log(error.message);  // 该语言的错误消息
-        
-        // 转发给客户端
-        throw error;
-      }
-    }
-  }
-}
-```
-
-#### 适用场景
-
-- ✅ **多语言 API**: 根据请求头 `Accept-Language` 动态返回
-- ✅ **微服务架构**: 错误在服务间传递时保持原语言
-- ✅ **国际化应用**: 同一请求中需要多种语言的错误消息
-- ✅ **A/B测试**: 不同用户组使用不同语言
-
-#### 与全局语言设置的对比
-
-| 特性 | 全局设置 | 运行时指定 |
-|------|---------|-----------|
-| **使用场景** | 单一语言应用 | 多语言API |
-| **切换方式** | `Locale.setLocale()` | 每次调用指定 |
-| **影响范围** | 全局所有错误 | 仅当前错误 |
-| **线程安全** | ⚠️ 需注意并发 | ✅ 完全安全 |
-| **推荐度** | 简单应用 | **API开发** |
-
----
-
-### 3. 插件系统增强
-
-**简化自定义类型注册流程**
-
-#### 改进前（v1.0.x）
-
-```javascript
-// 需要手动处理注册逻辑
-const customValidator = {
-  name: 'slug',
-  validate: (value) => /^[a-z0-9-]+$/.test(value)
-};
-
-// 手动添加到验证器
-validator.addCustomType('slug', customValidator);
-```
-
-#### 改进后（v1.1.0+）
-
-```javascript
-// 使用插件系统统一管理
-const slugPlugin = {
-  name: 'slug-validator',
-  version: '1.0.0',
-  install(core) {
-    core.registerType('slug', {
-      validate: (value) => /^[a-z0-9-]+$/.test(value),
-      message: 'must be a valid slug (lowercase, numbers, hyphens)'
-    });
-  }
-};
-
-// 注册插件
-pluginManager.register(slugPlugin);
-pluginManager.install(schemaCore);
-
-// 使用自定义类型
-const schema = dsl({ url: 'slug!' });
-```
-
-#### 新增功能
-
-- ✅ 插件生命周期管理（install/uninstall）
-- ✅ 插件版本控制
-- ✅ 插件依赖检查
-- ✅ 插件热重载（开发环境）
-
----
-
-## 📚 文档更新
-
-1. ✅ **联合类型文档**: [docs/union-types.md](../docs/union-types.md)
-2. ✅ **运行时多语言文档**: [docs/runtime-locale-support.md](../docs/runtime-locale-support.md)
-3. ✅ **插件系统文档**: [docs/plugin-system.md](../docs/plugin-system.md)
-
----
-
-## 🔄 破坏性变更
-
-**无破坏性变更** - 所有新功能都是向后兼容的。
-
----
-
-## 🎯 升级指南
-
-### 从 v1.0.x 升级到 v1.1.0
-
-```bash
-npm install schema-dsl@1.1.0
-```
-
-**可选：启用新功能**
-
-1. **使用联合类型**（可选）
-   ```javascript
-   // 之前
-   const schema = dsl({ value: 'string' });
-   
-   // 现在（可选使用）
-   const schema = dsl({ value: 'types:string|number' });
-   ```
-
-2. **使用运行时多语言**（可选）
-   ```javascript
-   // 之前
-   I18nError.throw('account.notFound');
-   
-   // 现在（可选使用）
-   I18nError.throw('account.notFound', {}, 404, 'en-US');
-   ```
-
----
-
-## 📦 依赖变更
-
-**无依赖变更**
-
----
-
-## 📊 性能影响
-
-- ✅ 联合类型验证：性能损失 <5%（可接受）
-- ✅ 运行时多语言：无性能影响（仅参数传递）
-- ✅ 插件系统：初始化性能优化 10%
-
----
-
-## 🙏 致谢
-
-感谢社区贡献者提出联合类型验证的需求和反馈。
-
----
-
-## 🔗 相关链接
-
-- [GitHub Repository](https://github.com/vextjs/schema-dsl)
-- [npm Package](https://www.npmjs.com/package/schema-dsl)
-- [完整文档](../docs/INDEX.md)
-
----
-
-**发布者**: schema-dsl Team  
-**发布时间**: 2026-01-05  
-**下一版本**: v1.1.1
-

package/changelogs/v1.1.1.md

@@ -1,308 +0,0 @@
-# v1.1.1 变更日志
-
-> **发布日期**: 2026-01-06  
-> **版本号**: v1.1.1  
-> **类型**: 🎉 新功能
-
----
-
-## 📋 变更概览
-
-| 类型 | 数量 | 说明 |
-|------|------|------|
-| 🎉 新功能 | 1 | ConditionalBuilder 独立消息支持 |
-| ⚡ 功能增强 | 1 | I18nError 多语言错误抛出 |
-
----
-
-## 🎉 新功能
-
-### ConditionalBuilder 独立消息支持
-
-**让条件验证的每个分支都有独立的错误消息**
-
-#### 问题场景
-
-在 v1.1.0 之前，条件验证只能有一个统一的错误消息：
-
-```javascript
-// ❌ v1.1.0：所有条件失败都显示同一消息
-dsl.if(d => !d)
-  .and(d => d.status !== 'active')
-  .and(d => d.balance < 100)
-  .message('验证失败')  // 无法区分具体哪个条件失败
-  .assert(account);
-```
-
-#### 解决方案
-
-v1.1.1 支持为每个条件分支设置独立的消息：
-
-```javascript
-// ✅ v1.1.1：每个条件都有清晰的错误消息
-dsl.if(d => !d)
-  .message('ACCOUNT_NOT_FOUND')  // 第一个条件的消息
-  .and(d => d.status !== 'active')
-  .message('ACCOUNT_INACTIVE')   // 第二个条件的消息
-  .and(d => d.balance < 100)
-  .message('INSUFFICIENT_BALANCE')  // 第三个条件的消息
-  .assert(account);
-```
-
-#### 实际应用场景
-
-**场景1：账户验证 - 多重检查**
-
-```javascript
-const { dsl } = require('schema-dsl');
-
-// 检查账户的多个条件
-function validateAccount(account, amount) {
-  dsl.if(d => !d)
-    .message('ACCOUNT_NOT_FOUND')
-    .and(d => d.status !== 'active')
-    .message('ACCOUNT_INACTIVE')
-    .and(d => d.balance < amount)
-    .message('INSUFFICIENT_BALANCE')
-    .assert(account);
-}
-
-// 使用示例
-try {
-  validateAccount(null, 100);
-} catch (error) {
-  console.log(error.message);  // "账户不存在" (ACCOUNT_NOT_FOUND)
-}
-
-try {
-  validateAccount({ status: 'suspended', balance: 200 }, 100);
-} catch (error) {
-  console.log(error.message);  // "账户未激活" (ACCOUNT_INACTIVE)
-}
-
-try {
-  validateAccount({ status: 'active', balance: 50 }, 100);
-} catch (error) {
-  console.log(error.message);  // "余额不足" (INSUFFICIENT_BALANCE)
-}
-```
-
-**场景2：权限检查 - 分层验证**
-
-```javascript
-function checkPermission(user, resource) {
-  dsl.if(d => !d)
-    .message('USER_NOT_FOUND')
-    .and(d => d.role !== 'admin' && d.role !== 'moderator')
-    .message('INSUFFICIENT_ROLE')
-    .and(d => !d.permissions.includes(resource))
-    .message('PERMISSION_DENIED')
-    .assert(user);
-}
-```
-
-**场景3：订单验证 - 业务规则**
-
-```javascript
-function validateOrder(order) {
-  dsl.if(d => !d)
-    .message('ORDER_NOT_FOUND')
-    .and(d => d.status === 'cancelled')
-    .message('ORDER_CANCELLED')
-    .and(d => d.status === 'completed')
-    .message('ORDER_ALREADY_COMPLETED')
-    .and(d => d.payment === null)
-    .message('PAYMENT_MISSING')
-    .and(d => !d.payment.isPaid)
-    .message('ORDER_NOT_PAID')
-    .assert(order);
-}
-```
-
-#### API 增强
-
-**ConditionalBuilder.message()**
-
-```typescript
-message(
-  code: string,           // 错误代码（支持多语言）
-  params?: object         // 参数插值（可选）
-): ConditionalBuilder
-```
-
-**链式调用示例**
-
-```javascript
-dsl.if(condition1)
-  .message('ERROR_1')
-  .and(condition2)
-  .message('ERROR_2', { param: 'value' })
-  .and(condition3)
-  .message('ERROR_3')
-  .assert(data);
-```
-
----
-
-## ⚡ 功能增强
-
-### I18nError 统一多语言错误抛出
-
-**业务代码中统一的多语言错误处理**
-
-#### 核心 API
-
-```javascript
-const { I18nError, dsl } = require('schema-dsl');
-
-// 方式1：直接抛出
-I18nError.throw('account.notFound');
-
-// 方式2：带参数插值
-I18nError.throw('account.insufficientBalance', {
-  balance: 50,
-  required: 100
-});
-
-// 方式3：断言风格（推荐）
-I18nError.assert(account, 'account.notFound');
-I18nError.assert(
-  account.balance >= 100,
-  'account.insufficientBalance',
-  { balance: account.balance, required: 100 }
-);
-
-// 方式4：快捷方法
-dsl.error.throw('user.noPermission');
-dsl.error.assert(user.role === 'admin', 'user.noPermission');
-```
-
-#### Express/Koa 集成
-
-```javascript
-// 错误处理中间件
-app.use((error, req, res, next) => {
-  if (error instanceof I18nError) {
-    return res.status(error.statusCode).json(error.toJSON());
-  }
-  next(error);
-});
-
-// 业务代码中使用
-app.post('/withdraw', (req, res) => {
-  const account = getAccount(req.user.id);
-  I18nError.assert(account, 'account.notFound');
-  I18nError.assert(
-    account.balance >= req.body.amount,
-    'account.insufficientBalance',
-    { balance: account.balance, required: req.body.amount }
-  );
-  // 验证通过，继续处理...
-});
-```
-
-#### 内置错误代码
-
-**通用错误**:
-- `error.notFound` - 资源不存在
-- `error.forbidden` - 禁止访问
-- `error.unauthorized` - 未授权
-
-**账户错误**:
-- `account.notFound` - 账户不存在
-- `account.insufficientBalance` - 余额不足
-- `account.inactive` - 账户未激活
-
-**用户错误**:
-- `user.notFound` - 用户不存在
-- `user.noPermission` - 无权限
-
-**订单错误**:
-- `order.notPaid` - 订单未支付
-- `order.paymentMissing` - 缺少支付信息
-
----
-
-## 📚 文档更新
-
-- ✅ 新增条件验证独立消息文档
-- ✅ 新增 I18nError 使用指南
-- ✅ 更新 Express/Koa 集成示例
-- ✅ 添加内置错误代码列表
-
----
-
-## 🔄 破坏性变更
-
-**无破坏性变更** - 所有新功能都是向后兼容的。
-
-旧的用法仍然有效：
-
-```javascript
-// ✅ 旧用法仍然有效
-dsl.if(condition)
-  .message('ERROR')  // 统一消息
-  .and(condition2)
-  .assert(data);
-```
-
----
-
-## 🎯 升级指南
-
-### 从 v1.1.0 升级到 v1.1.1
-
-```bash
-npm install schema-dsl@1.1.1
-```
-
-**可选：使用独立消息**
-
-```javascript
-// 之前（v1.1.0）：统一消息
-dsl.if(d => !d)
-  .and(d => d.status !== 'active')
-  .message('验证失败')
-  .assert(account);
-
-// 现在（v1.1.1）：独立消息（推荐）
-dsl.if(d => !d)
-  .message('ACCOUNT_NOT_FOUND')
-  .and(d => d.status !== 'active')
-  .message('ACCOUNT_INACTIVE')
-  .assert(account);
-```
-
-**可选：使用 I18nError**
-
-```javascript
-// 之前：手动抛出错误
-if (!account) {
-  throw new Error('账户不存在');
-}
-
-// 现在：使用 I18nError（支持多语言）
-I18nError.assert(account, 'account.notFound');
-```
-
----
-
-## 📦 依赖变更
-
-**无依赖变更**
-
----
-
-## 🔗 相关链接
-
-- [GitHub Repository](https://github.com/vextjs/schema-dsl)
-- [npm Package](https://www.npmjs.com/package/schema-dsl)
-- [条件验证文档](../docs/conditional-api.md)
-- [I18nError 示例](../examples/i18n-error.examples.js)
-
----
-
-**发布者**: schema-dsl Team  
-**发布时间**: 2026-01-06  
-**下一版本**: v1.1.2
-