schema-dsl 1.2.1 → 1.2.2

package/index.js

@@ -203,6 +203,79 @@ function getDefaultValidator() {
   return _defaultValidator;
 }
 
+/**
+ * 智能类型转换：只转换字符串→数字（当schema要求number且能转换时）
+ * @private
+ * @param {*} data - 原始数据
+ * @param {Object} schema - JSON Schema对象
+ * @returns {*} 转换后的数据
+ */
+function smartCoerceTypes(data, schema) {
+  if (!data || typeof data !== 'object') return data;
+
+  // 获取 schema 对象
+  const schemaObj = schema.toSchema ? schema.toSchema() : schema;
+  const properties = schemaObj.properties || {};
+
+  // 处理数组
+  if (Array.isArray(data)) {
+    return data.map(item => smartCoerceTypes(item, schema));
+  }
+
+  // 处理对象
+  const result = { ...data };
+
+  Object.keys(result).forEach(key => {
+    const value = result[key];
+    const fieldSchema = properties[key];
+
+    if (!fieldSchema) return;
+
+    // ⚠️ 关键修复：如果字段有 enum 约束，不进行类型转换
+    // 原因：枚举验证需要严格匹配类型
+    // 例如：数字枚举 [1,2,3] 不应该接受字符串 "1"
+    if (fieldSchema.enum) {
+      return; // 跳过枚举字段的转换
+    }
+
+    // 核心规则：只有同时满足以下三个条件才转换
+    // 1. 值是字符串
+    // 2. Schema 要求 number 类型
+    // 3. 能正常转换为有效数字
+    // 4. 不是枚举字段（已在上面检查）
+    if (fieldSchema.type === 'number' && typeof value === 'string') {
+      const trimmed = value.trim();
+      if (trimmed !== '') {
+        const num = Number(trimmed);
+        if (!isNaN(num)) {
+          result[key] = num;
+        }
+      }
+    }
+    // 处理嵌套对象
+    else if (fieldSchema.type === 'object' && typeof value === 'object' && value !== null) {
+      result[key] = smartCoerceTypes(value, fieldSchema);
+    }
+    // 处理数组元素
+    else if (fieldSchema.type === 'array' && Array.isArray(value)) {
+      if (fieldSchema.items && fieldSchema.items.type === 'number') {
+        result[key] = value.map(item => {
+          if (typeof item === 'string') {
+            const trimmed = item.trim();
+            if (trimmed !== '') {
+              const num = Number(trimmed);
+              return !isNaN(num) ? num : item;
+            }
+          }
+          return item;
+        });
+      }
+    }
+  });
+
+  return result;
+}
+
 /**
  * 便捷验证方法（使用默认Validator）
  * @param {Object} schema - JSON Schema对象
@@ -211,6 +284,7 @@ function getDefaultValidator() {
  * @param {boolean} [options.format=true] - 是否格式化错误
  * @param {string} [options.locale] - 动态指定语言（如 'zh-CN', 'en-US'）
  * @param {Object} [options.messages] - 自定义错误消息
+ * @param {boolean} [options.coerce=true] - 是否启用智能类型转换（字符串→数字）
  * @returns {Object} 验证结果
  *
  * @example
@@ -218,13 +292,24 @@ function getDefaultValidator() {
  *
  * const schema = dsl({ email: 'email!' });
  *
- * // 基本验证
- * const result1 = validate(schema, { email: 'test@example.com' });
+ * // 基本验证（默认启用智能转换）
+ * const result1 = validate(schema, { userId: '123', age: '25' });
+ * // userId 和 age 自动转为数字
+ *
+ * // 禁用智能转换
+ * const result2 = validate(schema, data, { coerce: false });
  *
  * // 指定语言
- * const result2 = validate(schema, { email: 'invalid' }, { locale: 'zh-CN' });
+ * const result3 = validate(schema, { email: 'invalid' }, { locale: 'zh-CN' });
  */
-function validate(schema, data, options) {
+function validate(schema, data, options = {}) {
+  // 默认启用智能转换（只转换字符串→数字）
+  const shouldCoerce = options.coerce !== false;
+
+  if (shouldCoerce) {
+    data = smartCoerceTypes(data, schema);
+  }
+
   return getDefaultValidator().validate(schema, data, options);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schema-dsl",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "简洁强大的JSON Schema验证库 - DSL语法 + String扩展 + 便捷validate",
   "main": "index.js",
   "types": "index.d.ts",

package/docs/typescript-never-in-try-catch.md

@@ -1,298 +0,0 @@
-# TypeScript never 类型在 try-catch 中的行为分析
-
-## 问题描述
-
-当在 `try-catch` 的 `catch` 块中使用 `dsl.error.throw()` 时，TypeScript 可能会报错或者类型推断不正确。
-
-## 原因分析
-
-### 1. TypeScript 的控制流分析
-
-TypeScript 的控制流分析（Control Flow Analysis）对 `try-catch` 块有特殊处理：
-
-```typescript
-function test(): string {
-  try {
-    return 'value';
-  } catch (error) {
-    // 在 catch 块中，TypeScript 需要确定：
-    // 1. 这个块是否会正常返回？
-    // 2. 这个块是否会抛出异常？
-    // 3. 这个块是否永不返回（never）？
-  }
-  // 这里：TypeScript 需要判断是否可达
-}
-```
-
-### 2. never 类型的特殊性
-
-`never` 类型表示"永不返回"，但在 `try-catch` 中，TypeScript 的推断可能受限：
-
-**场景A - 直接调用（✅ 正常工作）**:
-```typescript
-function directCall(id: string | null) {
-  if (!id) {
-    dsl.error.throw('error'); // TypeScript 知道这里 never 返回
-  }
-  console.log(id.toUpperCase()); // ✅ id 被收窄为 string
-}
-```
-
-**场景B - 在 catch 中调用（⚠️ 可能有问题）**:
-```typescript
-function inCatch(id: string | null): string {
-  try {
-    if (!id) throw new Error();
-    return id.toUpperCase();
-  } catch (error) {
-    dsl.error.throw('error'); // ⚠️ TypeScript 可能不确定这里 never 返回
-  }
-  // ❌ 这里可能被认为是可达的
-}
-```
-
-### 3. 为什么添加 unreachable 保证有效？
-
-我们的修复方案（添加第二个 throw）帮助 TypeScript 更明确地理解函数行为：
-
-**修复前**:
-```javascript
-static throw(code, paramsOrLocale, statusCode, locale) {
-  throw new I18nError(...);
-  // TypeScript: "函数体结束了，但我不确定是否永不返回"
-}
-```
-
-**修复后**:
-```javascript
-static throw(code, paramsOrLocale, statusCode, locale) {
-  throw new I18nError(...);
-  // eslint-disable-next-line no-unreachable
-  throw new Error('unreachable');
-  // TypeScript: "哦，有两个 throw，这个函数确实永不返回"
-}
-```
-
-## 测试结果
-
-### 当前版本 (v1.2.0) - 所有场景通过 ✅
-
-经过测试，以下所有场景都**不再报错**：
-
-| 场景 | 描述 | 结果 |
-|------|------|------|
-| scenario1 | 直接使用 throw | ✅ 通过 |
-| scenario2 | catch 块中使用 throw（无返回值） | ✅ 通过 |
-| scenario3 | catch 块中使用 throw（有返回类型） | ✅ 通过 |
-| scenario4 | catch 块中 throw 后有其他代码 | ✅ 通过 |
-| scenario5 | 使用类型断言 | ✅ 通过 |
-| scenario6 | 多层 try-catch 嵌套 | ✅ 通过 |
-| scenario7 | 普通 throw 对比 | ✅ 通过 |
-| scenario8 | 返回 never 函数 | ✅ 通过 |
-| scenario9 | 严格模式无 return | ✅ 通过 |
-| scenario10 | catch 后有代码块 | ✅ 通过 |
-| scenario11 | 条件分支中的 throw | ✅ 通过 |
-| scenario12 | 类型收窄测试 | ✅ 通过 |
-
-## 为什么会报错（理论情况）
-
-在某些 TypeScript 配置或版本下，可能出现以下报错：
-
-### 错误1: "Function lacks ending return statement"
-
-```typescript
-function test(): string {
-  try {
-    return 'value';
-  } catch (error) {
-    dsl.error.throw('error');
-  }
-  // TS2366: Function lacks ending return statement and return type does not include 'undefined'.
-}
-```
-
-**原因**: TypeScript 不确定 catch 块是否永不返回
-
-### 错误2: "Not all code paths return a value"
-
-```typescript
-function test(): string {
-  try {
-    return 'value';
-  } catch (error) {
-    dsl.error.throw('error');
-  }
-  console.log('after catch');
-  // TS7030: Not all code paths return a value.
-}
-```
-
-**原因**: TypeScript 认为 catch 块可能正常结束，导致后面的代码可达
-
-### 错误3: 类型收窄失效
-
-```typescript
-function test(value: string | null) {
-  try {
-    if (!value) {
-      throw new Error();
-    }
-    return value.toUpperCase();
-  } catch (error) {
-    dsl.error.throw('error');
-  }
-  // value 在这里可能仍然是 string | null，而不是 string
-}
-```
-
-**原因**: TypeScript 的控制流分析在 try-catch 边界可能失效
-
-## 解决方案对比
-
-### 方案1: 我们的修复（推荐）✅
-
-```javascript
-// lib/errors/I18nError.js
-static throw(code, paramsOrLocale, statusCode, locale) {
-  throw new I18nError(code, params, actualStatusCode, actualLocale);
-  // eslint-disable-next-line no-unreachable
-  throw new Error('unreachable');
-}
-```
-
-**优点**:
-- ✅ 修复了类型系统问题
-- ✅ 不影响运行时行为
-- ✅ 不需要用户修改代码
-
-### 方案2: 用户使用类型断言（临时方案）
-
-```typescript
-function test(): string {
-  try {
-    return 'value';
-  } catch (error) {
-    dsl.error.throw('error');
-    return undefined as never; // 类型断言
-  }
-}
-```
-
-**缺点**:
-- ❌ 需要用户每次都写
-- ❌ 代码不优雅
-- ❌ 容易忘记
-
-### 方案3: 使用 return
-
-```typescript
-function test(): string {
-  try {
-    return 'value';
-  } catch (error) {
-    return dsl.error.throw('error'); // return 一个 never
-  }
-}
-```
-
-**缺点**:
-- ❌ 语义不清晰（return 一个永不返回的函数？）
-- ❌ 用户需要记住这个用法
-
-### 方案4: 不使用 try-catch（规避）
-
-```typescript
-function test(id: string | null): string {
-  if (!id) {
-    dsl.error.throw('error'); // ✅ 这样就没问题
-  }
-  return id.toUpperCase();
-}
-```
-
-**缺点**:
-- ❌ 限制了用户的代码结构
-- ❌ 不适用于需要捕获异常的场景
-
-## TypeScript 版本兼容性
-
-| TypeScript 版本 | 修复前 | 修复后 |
-|----------------|--------|--------|
-| 4.5+ | ⚠️ 可能报错 | ✅ 正常 |
-| 4.0-4.4 | ⚠️ 可能报错 | ✅ 正常 |
-| 3.x | ⚠️ 可能报错 | ✅ 正常 |
-
-## 实际使用建议
-
-### ✅ 推荐用法
-
-```typescript
-// 1. 直接在条件分支中使用（最推荐）
-function test1(id: string | null) {
-  if (!id) {
-    dsl.error.throw('error');
-  }
-  return id.toUpperCase();
-}
-
-// 2. 在 catch 块中使用（v1.2.0+ 支持）
-function test2(): string {
-  try {
-    return processData();
-  } catch (error) {
-    dsl.error.throw('processing.failed'); // ✅ 正常工作
-  }
-}
-
-// 3. 使用 assert（推荐）
-function test3(account: any) {
-  dsl.error.assert(account, 'account.notFound');
-  return account.balance; // account 已被收窄为 truthy
-}
-```
-
-### ⚠️ 注意事项
-
-```typescript
-// 1. 条件分支中的 throw（需要确保所有分支都覆盖）
-function test(shouldThrow: boolean): string {
-  try {
-    return 'value';
-  } catch (error) {
-    if (shouldThrow) {
-      dsl.error.throw('error');
-    }
-    return 'fallback'; // ⚠️ 这个 return 是必需的
-  }
-}
-
-// 2. finally 块中不要使用 throw
-function test(): string {
-  try {
-    return 'value';
-  } catch (error) {
-    dsl.error.throw('error');
-  } finally {
-    // ❌ 不要在这里使用 throw
-    // dsl.error.throw('finally.error');
-  }
-}
-```
-
-## 总结
-
-1. **问题根源**: TypeScript 的控制流分析在 try-catch 中对 never 类型的推断可能不够准确
-
-2. **修复方案**: 在 throw 方法末尾添加 `throw new Error('unreachable')`，明确告诉 TypeScript 这个函数永不返回
-
-3. **修复效果**: v1.2.0 版本后，所有测试场景都通过，不再报错
-
-4. **用户影响**: 用户无需修改任何代码，升级到 v1.2.0 即可解决问题
-
-5. **向后兼容**: 完全向后兼容，不影响现有功能
-
-## 参考资料
-
-- [TypeScript Control Flow Analysis](https://www.typescriptlang.org/docs/handbook/2/narrowing.html)
-- [TypeScript never Type](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#the-never-type)
-- [TypeScript Issue #8655](https://github.com/microsoft/TypeScript/issues/8655) - never in try-catch

package/test-try-catch-scenario.ts

@@ -1,183 +0,0 @@
-/**
- * 测试场景：在 try-catch 中使用 throw 方法
- * 验证 TypeScript 类型推断是否正确
- */
-import { dsl } from './index';
-
-// ===== 场景1：直接在函数中使用 throw（正常工作）=====
-function scenario1_direct(id: string | null) {
-  if (!id) {
-    dsl.error.throw('account.notFound');
-    // ✅ TypeScript 知道这里永不返回
-  }
-  // ✅ TypeScript 知道 id 一定不是 null
-  console.log(id.toUpperCase());
-}
-
-// ===== 场景2：在 try-catch 的 catch 块中使用 throw =====
-function scenario2_inCatch(id: string | null) {
-  try {
-    // 一些可能抛错的操作
-    if (!id) {
-      throw new Error('id is null');
-    }
-    return id.toUpperCase();
-  } catch (error) {
-    // ⚠️ 在 catch 块中调用 dsl.error.throw
-    dsl.error.throw('account.notFound');
-    // ❌ 问题：TypeScript 可能不知道这里永不返回
-  }
-  // ❌ TypeScript 可能认为这里可达，报错："Not all code paths return a value"
-}
-
-// ===== 场景3：在 catch 块中使用 throw，有返回类型声明 =====
-function scenario3_withReturnType(id: string | null): string {
-  try {
-    if (!id) {
-      throw new Error('id is null');
-    }
-    return id.toUpperCase();
-  } catch (error) {
-    dsl.error.throw('account.notFound');
-  }
-  // ❌ TypeScript 会报错："Function lacks ending return statement"
-}
-
-// ===== 场景4：在 catch 块中先 throw，再有其他代码 =====
-function scenario4_codeAfterThrow(id: string | null): string {
-  try {
-    if (!id) {
-      throw new Error('id is null');
-    }
-    return id.toUpperCase();
-  } catch (error) {
-    dsl.error.throw('account.notFound');
-    console.log('这行代码永远不会执行'); // ⚠️ 但 TypeScript 可能认为会执行
-    return 'default'; // ⚠️ TypeScript 可能认为这是有效的返回
-  }
-}
-
-// ===== 场景5：使用类型断言（workaround）=====
-function scenario5_withAssertion(id: string | null): string {
-  try {
-    if (!id) {
-      throw new Error('id is null');
-    }
-    return id.toUpperCase();
-  } catch (error) {
-    dsl.error.throw('account.notFound');
-    return undefined as never; // 类型断言 workaround
-  }
-}
-
-// ===== 场景6：多层 try-catch 嵌套 =====
-function scenario6_nested(id: string | null): string {
-  try {
-    try {
-      if (!id) {
-        throw new Error('id is null');
-      }
-      return id.toUpperCase();
-    } catch (innerError) {
-      dsl.error.throw('account.notFound');
-    }
-  } catch (outerError) {
-    return 'fallback';
-  }
-  // ❌ TypeScript 可能报错
-}
-
-// ===== 场景7：对比 - 使用普通 throw（正常工作）=====
-function scenario7_normalThrow(id: string | null): string {
-  try {
-    if (!id) {
-      throw new Error('id is null');
-    }
-    return id.toUpperCase();
-  } catch (error) {
-    throw new Error('account not found'); // ✅ TypeScript 知道这里永不返回
-  }
-  // ✅ 不会报错
-}
-
-// ===== 场景8：在 catch 中返回 never 类型的函数调用 =====
-function throwHelper(): never {
-  throw new Error('helper');
-}
-
-function scenario8_helperFunction(id: string | null): string {
-  try {
-    if (!id) {
-      throw new Error('id is null');
-    }
-    return id.toUpperCase();
-  } catch (error) {
-    return throwHelper(); // ⚠️ return 一个 never 类型的函数
-  }
-  // ✅ 可能不报错，但这不是正确的用法
-}
-
-// ===== 场景9：严格模式 - 没有 return 语句 =====
-function scenario9_strictNoReturn(id: string | null): string {
-  try {
-    if (!id) {
-      throw new Error('id is null');
-    }
-    return id.toUpperCase();
-  } catch (error) {
-    dsl.error.throw('account.notFound');
-  }
-  // 在这里没有 return 语句
-}
-
-// ===== 场景10：catch 后面有额外代码块 =====
-function scenario10_codeAfterCatch(id: string | null): string {
-  try {
-    if (!id) {
-      throw new Error('id is null');
-    }
-    return id.toUpperCase();
-  } catch (error) {
-    dsl.error.throw('account.notFound');
-  }
-
-  // 这里有代码
-  console.log('after catch');
-  return 'default';
-}
-
-// ===== 场景11：条件分支中的 throw =====
-function scenario11_conditionalThrow(id: string | null, shouldThrow: boolean): string {
-  try {
-    if (!id) {
-      throw new Error('id is null');
-    }
-    return id.toUpperCase();
-  } catch (error) {
-    if (shouldThrow) {
-      dsl.error.throw('account.notFound');
-    }
-    return 'fallback'; // 这个 return 是必需的
-  }
-}
-
-// ===== 场景12：测试类型收窄 =====
-function scenario12_typeNarrowing(value: string | number | null): string {
-  try {
-    if (value === null) {
-      throw new Error('value is null');
-    }
-
-    if (typeof value === 'number') {
-      return value.toString();
-    }
-
-    return value.toUpperCase();
-  } catch (error) {
-    dsl.error.throw('validation.failed');
-  }
-}
-
-console.log('✅ 如果编译成功，说明所有场景的类型都正确');
-
-