ts-pattern 路线图前瞻:.narrow 可选化、P.array.includes 等 8 项新功能即将上线
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 这类迁移文档即可。
- 📍 路线图全文:docs/roadmap.md
- 📍 模式实现:src/patterns.ts
- 📍 类型推导核心:src/types/Match.ts
- 📍 版本迁移指南:docs/v3-to-v4-migration-guide.md、docs/v4-to-v5-migration-guide.md