Valibot 中自定义类型转换在 v.is 方法中的限制分析

问题背景

Valibot 是一个用于数据验证和转换的 TypeScript 库。在实际开发中，我们经常需要对输入数据进行验证和转换。一个常见的使用场景是使用 v.transform 方法对数据进行处理后，再使用 v.is 方法进行类型检查。

核心问题

当我们在 Valibot 中使用 v.transform 进行自定义类型转换时，转换后的类型在 v.InferOutput 中能够正确推断，但在使用 v.is 方法进行类型检查时，这些自定义类型转换会丢失。

技术细节分析

1. 转换与验证的区别

v.transform 方法会对输入数据进行处理并返回一个新的值，而 v.is 方法仅用于验证输入数据是否符合给定的模式，不会修改原始数据。这是设计上的一个重要区别。

2. 类型系统行为

在 TypeScript 类型系统中，v.InferOutput 能够正确反映转换后的类型，因为它基于 schema 定义的类型转换逻辑。然而，v.is 方法的类型保护仅作用于输入数据的原始类型，不会反映转换后的类型。

3. 实际示例分析

考虑以下代码示例：

const Geolocation = v.pipe(
  v.object({ countryCode: v.string(), regionCode: v.optional(v.string()) }),
  v.transform(({ countryCode, regionCode }) => ({
    countryCode: countryCode.toLowerCase() as Lowercase<string>,
    regionCode: regionCode?.toLowerCase() as Lowercase<string> | undefined,
  })),
);

type Geolocation = v.InferOutput<typeof Geolocation>; // 类型正确

const input = {
  countryCode: 'DE',
  regionCode: undefined,
};

if (v.is(Geolocation, input)) {
  // 这里的 input 类型不会反映转换后的类型
  console.log(input);
}

解决方案

1. 使用 safeParse 替代

如果需要同时验证和转换数据，可以使用 v.safeParse 方法，它会返回一个包含转换后数据的结果对象：

const result = v.safeParse(Geolocation, input);
if (result.success) {
  // result.data 包含转换后的数据
  console.log(result.data);
}

2. 自定义 is 函数

可以创建一个自定义的 is 函数，结合 safeParse 来实现既验证又保留类型转换的功能：

function customIs<T>(schema: v.Schema<T>, input: unknown): input is T {
  const result = v.safeParse(schema, input);
  return result.success;
}

最佳实践建议

1. 明确区分数据验证和转换的用途
2. 如果只需要验证数据而不需要转换结果，使用 v.is
3. 如果需要获取转换后的数据，使用 v.safeParse 或 v.parse
4. 对于复杂的类型转换场景，考虑将验证和转换逻辑分离

总结

Valibot 中 v.is 方法的设计初衷是进行纯粹的类型检查，而不是数据转换。理解这一设计理念有助于我们更合理地使用库提供的各种功能。在实际开发中，根据具体需求选择合适的验证和转换方法，可以避免类型系统上的混淆。