ArkRegex：让正则表达式拥有 TypeScript 类型的类型安全包装器

正则表达式是一把双刃剑：几字符就能完成本该几十行命令式代码才能做的校验与解析，但它的类型安全却几乎是个盲区。在 JavaScript/TypeScript 里，new RegExp("...") 编译期只是个 RegExp 对象——.test() 返回 boolean，.exec() 返回的捕获组永远是 string | undefined，至于某个命名组到底叫什么、匹配出来是不是数字，类型系统一概不知。

ArkType 团队（以类型级运行时校验库 ArkType 闻名）推出的 arkregex 试图补上这一块：它是 new RegExp() 的一个类型安全包装器，在运行时几乎零开销，却能把正则模式字符串静态解析成精确的 TypeScript 类型。

一、它解决什么问题

传统 RegExp 的痛点：

• 捕获组无类型：result.groups.name 是 any 或 string | undefined，拼写错误要到运行时才发现；
• 引用不存在的捕获组不报错：代码里写了一个正则里根本没有的组名，类型系统毫无反应；
• .test() 结果是裸 boolean：你没法让 TS 知道”这个字符串一定匹配了 ^ok$”。

arkregex 的 regex() 函数把这些都搬到编译期。

二、它是怎么工作的

核心 API 只有一个 regex()，传入模式字符串与标志位，返回一个带类型参数的 Regex 实例。类型层面，它把正则的字面量结构翻译成 TypeScript 模板字面量类型：

import { regex } from "arkregex";

// Regex<"ok" | "oK" | "Ok" | "OK", { flags: "i" }>
const ok = regex("^ok$", "i");

// Regex<`${bigint}.${bigint}.${bigint}`,
//        { captures: [`${bigint}`, `${bigint}`, `${bigint}`] }>
const semver = regex("^(\\d*)\\.(\\d*)\\.(\\d*)$");

// Regex<`${string}@${string}.${string}`,
//        { names: { name: string; domain: `${string}.${string}` } }>
const email = regex("^(?<name>\\w+)@(?<domain>\\w+\\.\\w+)$");

三个例子分别对应三种典型推断：

也就是说，\d* 被推断成 `${bigint}` 而不是 string，命名捕获组 name/domain 直接出现在 .groups 的类型里。如果你在代码里引用了一个正则里不存在的捕获组名，那会变成一个类型错误——这正是它宣称的”Safety”。

三、四个特性：官方怎么定位

官网列出四个卖点，逐条看：

1. Types（类型推断）：从现有正则推断字符串类型，包括位置捕获与命名捕获；
2. Parity（功能对等）：宣称支持 new RegExp() 允许的 100% 特性，是即插即用替代品；
3. Safety（安全）：引用不存在的捕获组这类语法错误变成类型错误；
4. Zero Runtime（零运行时）：改善类型安全但不影响打包体积——因为类型推导全在类型层面，运行时它就是包了一层原生 RegExp。

官方建议配合 TypeScript 5.9+ 使用，并提供 ArkType 的 VS Code 扩展给 regex() 调用加语法高亮。安装就是 pnpm install arkregex。

四、口径偏差：推断”宁可粗，绝不错”

这一节是本文重点——官方 FAQ 自己讲清了类型推断的边界，读者不应把它理解成”正则即精确类型”。

1. 字符区间不会被精确展开。像 [a-Z] 这类模式，官方不会把它推断成所有可能字符的字面量联合。原因很实在：那样构造字符串字面量类型会发生组合爆炸，编译时间不可接受。官方明确说他们在”性能与精度之间取了平衡”。
2. 关键承诺：推断出的类型”最坏情况是不精确，但绝不会是错的”（at worst imprecise and never incorrect）。这句话很重要——它意味着类型系统是保守加宽的：宁可给你一个更宽的类型（比如把 \w+ 当成 string），也绝不会给你一个过窄、从而骗过运行时的类型。所以你永远不会因为它的类型推断而产生虚假的安全感，但也别指望它把每个字符类都折叠成精确字面量。
3. 超长/超复杂正则会推断失败。官方承认：如果正则特别长或特别复杂，TypeScript 会报那个著名的 “Type is excessively deep…”（类型过深）错误。这时要用逃生舱 regex.as<...>() 手动标注类型：

const complexPattern = regex.as<`pattern-${string}`, { captures: [string] }>(
  "very-long-complex-expression-here"
);

4. “零运行时”是真的，但它不是运行时校验器。它只在编译期给你类型；运行时它仍然是原生 RegExp，不会替你做运行时断言。要运行时校验还得配合 ArkType 本体。

五、评测方法与可信度

• 官方称其类型”经过广泛测试与 benchmark”，使用的是 attest（ArkType 自家的测试/benchmark 框架）。这意味着正确性测试主要覆盖它自己维护的用例集，而非外部独立基准。
• **“100% 支持 new RegExp() 特性”**指的是运行时行为对等，不等于这 100% 特性都能被精确推断成类型——大量模式只能得到保守的宽类型。
• 它依赖 TS 5.9+ 的最新类型能力；在旧版本 TS 上推断能力会打折。

六、优势与局限

优势：

1. 零运行时成本、零打包体积增加，类型推导纯在编译期；
2. 命名捕获组与位置捕获组都能推断成类型，重构正则时改组名会被 TS 抓住；
3. 引用不存在的捕获组从运行时 bug 变成编译期错误；
4. 即插即用：new RegExp(...) → regex(...)，API 对等；
5. 保守推断策略（宁可粗不会错）避免了误导性的”假类型安全”。

局限：

1. 字符类、区间等模式无法精确推断，类型常常只是 string / `${string}`；
2. 复杂/超长正则会触发 TS “类型过深”错误，需手动 regex.as；
3. 需要 TS 5.9+，旧项目升级有门槛；
4. 只做编译期类型，不提供运行时校验；
5. 生态新，真实大型代码库中的推断稳定性与编译性能仍需时间验证。

七、谁该关注

• 重度依赖正则做输入解析的 TS 项目：路由参数、表单校验、配置解析等场景，捕获组类型化收益明显；
• 受够了 result.groups.xxx 是 any 的开发者：想要改组名时编译器帮忙兜底的人；
• 在 ArkType 技术栈里的团队：与现有类型体系风格一致；
• 不建议：正则极其复杂超长、或还在用 TS 5.9 以下版本的项目——会遇到”类型过深”或推断退化。

参考来源

• Introducing ArkRegex（ArkType 官方博客）
• ArkType 官网
• arkregex GitHub
• Koala 项目库条目：ArkRegex