ts-pattern 路线图前瞻:.narrow 可选化、P.array.includes 等 8 项新功能即将上线

原创2026-09-21 22:48:521,940 阅读
文章标签:开发工具

ts-pattern 路线图前瞻:.narrow 可选化、P.array.includes 等 8 项新功能即将上线

ts-pattern 是 TypeScript 生态中最受欢迎的穷举模式匹配库,提供 match、P 通配符与智能类型推导。它官方仓库的 docs/roadmap.md 刚刚公布了 8 项待上线的新功能——从 .narrow() 可选化,到 P.array.includes(x)、P.record 键模式等。这篇前瞻带你快速看懂:每一项是什么、能解决什么问题,以及哪些老功能已经落地可用。

一图看懂:8 项新功能速览 📋

# 功能 一句话说明
1 P.ExactPattern<Type> 推导"要完整覆盖某类型必须写下的精确模式"
2 isMatching<Type>(pattern) 支持类型参数,约束模式对应的输入类型
3 更优的 variant 推导 .with 中类型推导的精度继续打磨
4 .narrow() 可选化 收窄变为显式开启,按需排除已处理分支
5 P.array.includes(x) 判断数组中"至少包含"某个元素
6 P.record(Pkey, Pvalue) P.record 支持自定义键模式
7 P.record 增强 Record 模式匹配能力持续完善
8 P.unknown 别名 与 any 语义对齐的通配别名

完整清单见 docs/roadmap.md,源码入口在 src/patterns.ts 与 src/is-matching.ts。

重点功能 1:.narrow() 改为可选开启(opt-in)

这是本次路线图里最受关注的一条。

目前 .narrow() 用于把输入类型"深度收窄",自动排除掉前面 .with 已经处理过的分支。例如处理一个 color: 'red' | 'blue' 的联合类型时,调用 .narrow() 之后,后续分支里的输入类型会剔除掉已命中的组合:

match(input)
  .with({ color: 'red', size: 'small' }, () => '红小')
  .narrow() // 👈 排除已处理分支
  .otherwise((rest) => {
    // rest 只剩 red+large 和 blue+small 两种组合
  });

路线图的方向是:把这种收窄变成显式 opt-in 选项——只在 .with 之后需要时才收窄。这样做的好处:

  • 类型推导更可预期:不想收窄的场景保持原始类型,避免意外的类型变化;
  • 编译更快:深度收窄涉及较重的类型计算(参考 src/types/DeepExclude.ts),按需执行能缩短大型项目的检查时间。

重点功能 2:P.array.includes(x) 数组包含判断

现在想匹配"数组里至少有一个元素是 x",只能用 P.array(P.union(x, P._)) 之类的迂回写法,或者干脆手写 P.when。

新增的 P.array.includes(x) 会把这件事变成一个一等公民:

match(input)
  .with(P.array(P.number).includes(42), (xs) => '数组里含有 42')
  .otherwise(() => '没有 42');

这与已有的链式 API(如 P.string.includes('str')、P.number.between(1, 10),见 src/patterns.ts)风格完全一致,学习成本几乎为零。

重点功能 3:P.record 支持键模式

当前版本的 P.record(keyPattern, valuePattern) 已经支持按值模式匹配 Record 对象。路线图上的 P.record(Pkey), {Pvalue}) 条目将进一步打磨键/值双模式写法,让"匹配一个键为数字、值为字符串的字典"这类需求更顺手:

match(data)
  .with(P.record(P.string, P.number), (scores) => '全是数字分值')
  .otherwise(() => '其他');

实现位于 src/patterns.ts,后续增强会直接落在这里。

其余功能:小而美

P.ExactPattern<Type>:帮你"写出完整模式"

穷举匹配最怕漏属性。P.ExactPattern<Type> 会从类型反向推导出你必须写下的精确模式——相当于告诉编辑器:"要完整覆盖这个类型,模式得长这样"。对经常处理大型联合类型的同学是个明显的减负。

isMatching<Type>(pattern):约束更精确

现在 isMatching 已经可以当类型守卫用(单参数返回守卫函数,双参数返回布尔值)。新增的类型参数 isMatching<Type>(pattern) 能显式约束模式对应的输入类型,减少推导歧义。

P.unknown:any 的"安全别名"

统一通配符语义,让 P.unknown 与 any 在匹配行为上对齐,进一步减少 any 与 unknown 混用的心智负担。

更优的 variant 推导

官方标注了 "better variant attempt":继续优化 .with 对判别联合(discriminated union)的类型推导质量,目标是在多分支场景下给出更窄、更准的参数类型。

已经落地的"前辈们":这些功能你现在就能用 ✅

路线图下半部分是已勾选的完成项,正好可以作为上手参考(详见 README.md):

  • 链式模式 API:P.string.startsWith / endsWith / includes / regex、P.number.between / lt / gt / int 等;
  • .optional() / .select() 组合:如 P.string.optional.select();
  • 自定义匹配协议(Matcher Protocol):数据结构实现 <a href="https://link.gitcode.com/i/d858a88db7c2e515c84d0c3d8d56bb0e" target="_blank">P.matcher] 后就能直接参与匹配,见 [src/patterns.ts 中的 unstable_Matchable 类型;
  • P.array 可变形组(variadic tuple):<a href="https://link.gitcode.com/i/2cb76b3026f56098a275b89a7fc4744d" target="_blank">P.any, ...P.array(P.number)] 这类写法已可用,官方示例见 [examples/one-file-demo/one-file-demo.ts;
  • P.union(...) / 多模式 .with / P.not / 穷举检查 .exhaustive():模式匹配的"全家桶"核心能力。

总结:这次路线图意味着什么?

一句话:类型推导更可控(.narrow opt-in),日常写法更顺手(includes、record 键模式),类型工具更完整(ExactPattern、isMatching<Type>)。

对新手而言,现在入门 ts-pattern 正是好时机——8 项功能全部围绕"更省心、更精确"展开,不打算打破现有 API;对老用户来说,最值得盯紧的是 .narrow() 的行为调整,升级新版本时留意 docs/v4-to-v5-migration-guide.md 这类迁移文档即可。

登录后查看全文
ts-pattern