Valibot 中正则表达式与类型系统的深度解析

在 JavaScript 和 TypeScript 开发中，数据验证是一个常见需求。Valibot 作为一个类型安全的验证库，在处理正则表达式验证时有其独特的类型系统考量。本文将深入探讨 Valibot 中正则表达式验证的最佳实践和类型系统的工作原理。

正则表达式验证的常见场景

开发者经常需要从字符串中提取特定格式的数据。例如，从"2024.01.30"这样的日期字符串中提取年份部分。一个直观的做法是：

const Schema = v.pipe(
  v.string(),
  v.transform(value => /^(\d{4})\.\d{2}\.\d{2}$/.exec(value)),
  v.array(v.string()),
  v.length(2),
  v.transform(value => Number(value[1])),
);

这段代码看似合理，但 Valibot 的类型系统会报错，原因是类型不匹配。

Valibot 的类型安全机制

Valibot 的管道(pipeline)验证有一个重要特性：它会确保每个步骤的输出类型能够被下一个步骤的输入类型所接受。这种设计避免了创建逻辑上不可能的类型转换。

在正则表达式场景中，RegExp.exec()返回的是RegExpExecArray | null类型，而v.array(v.string())期望的是Array<string>类型。TypeScript 认为这两种类型不兼容，因此会报错。

解决方案比较

方案一：确保类型兼容

const Schema = v.pipe(
  v.string(),
  v.transform(value => /^(\d{4})\.\d{2}\.\d{2}$/.exec(value) ?? new Array<string>()),
  v.length(2),
  v.transform(value => Number(value[1])),
);

这种方法通过提供默认值确保返回类型始终是数组，避免了类型不匹配问题。

方案二：使用 unknown 类型

const Schema = v.pipe(
  v.string(),
  v.transform((value): unknown => /^(\d{4})\.\d{2}\.\d{2}$/.exec(value)),
  v.array(v.string()),
  v.length(2),
  v.transform(value => Number(value[1])),
);

通过显式指定返回类型为unknown，绕过了类型检查，但牺牲了部分类型安全性。

推荐方案：前置验证

const DATE_REGEX = /^\d{4}\.\d{2}\.\d{2}$/u;

const Schema = v.pipe(
  v.string(),
  v.regex(DATE_REGEX),
  v.transform((input) => DATE_REGEX.exec(input)![1])
);

这是 Valibot 作者推荐的做法，先验证字符串格式，再进行转换，既保证了类型安全，又避免了重复的正则匹配。

高级技巧：自定义正则捕获动作

对于需要捕获命名分组的场景，可以创建自定义验证动作：

function captureRegex(
  regex: RegExp,
  message?: v.ErrorMessage<v.RawTransformIssue<string>> | undefined,
): v.RawTransformAction<string, Record<string, string>> {
  return v.rawTransform(({ dataset, addIssue, NEVER }) => {
    const match = regex.exec(dataset.value);
    if (!match) {
      addIssue({
        expected: String(regex),
        message: message ?? ((issue) => `Invalid format: Expected ${String(regex)} but received "${issue.input}"`),
      });
      return NEVER;
    }
    return match.groups ?? {};
  });
}

这个自定义动作可以直接返回正则匹配的命名分组，简化了后续处理流程。

总结

Valibot 的类型安全设计虽然在某些情况下会增加开发复杂度，但它能有效防止运行时错误。在处理正则表达式验证时：

1. 优先考虑使用v.regex进行前置验证
2. 确保转换函数的返回类型与后续步骤兼容
3. 对于复杂场景，可以创建自定义验证动作
4. 理解并尊重类型系统的约束，避免使用unknown绕过类型检查

这些最佳实践不仅能解决当前问题，还能帮助开发者构建更健壮、更易维护的数据验证逻辑。