better-result-migrate-v2

better-result Migrate v2

将 better-result 的错误定义从 v1 的 TaggedError API 升级到 v2 的工厂函数 API。

适用场景

用户遇到以下情况时，请使用此技能：

• 将 better-result 从 v1 升级到 v2
• 有直接 extend TaggedError 的类
• 仍在使用 TaggedError.match、TaggedError.matchPartial 或 TaggedError.isTaggedError
• 需要帮助将构造函数调用改写为新的对象形式

阅读顺序

任务	要阅读的文件
规划并执行迁移	此文件
查看具体的迁移前后对照	references/migration-patterns.md
验证当前库的行为	如存在，则查看 opensrc/

API 快速对照

v1	v2
class FooError extends TaggedError	class FooError extends TaggedError("FooError")<Props>() {}
readonly _tag = "FooError" as const	_tag 由工厂函数生成
new FooError("123")	new FooError({ id: "123", message: "..." })
TaggedError.match(...)	matchError(...)
TaggedError.matchPartial(...)	matchErrorPartial(...)
TaggedError.isTaggedError(...)	isTaggedError(...) 或 TaggedError.is(...)

迁移工作流

1. 在整个代码库中搜索 extends TaggedError。
2. 对于每个类，提取：
   • _tag 字面量
   • 构造函数参数和运行时属性
   • 任何计算所得的消息或验证逻辑
3. 将类改写为 TaggedError("Tag")<Props>()。
4. 如果存在构造函数逻辑，请保留自定义构造函数，使其接受一个对象并调用 super({...})。
5. 将调用点从位置参数改为对象参数。
6. 将静态辅助函数替换为新的独立辅助函数。
7. 更新导入。
8. 运行测试，并再次搜索旧 API 的残留用法。

转换规则

• 简单类：移除 _tag，替换基类，并将字段移入泛型 props 对象。
• 计算所得的消息：保留自定义构造函数，并在 super(...) 之前计算 message。
• 验证逻辑：在自定义构造函数中保留验证逻辑。
• 额外的运行时字段：将它们包含在传给 super(...) 的 props 对象中。
• 用法：将 new FooError(a, b) 迁移为 new FooError({ a, b, message })，或使用等效的派生消息构造函数。

如果目标类并不简单，请先阅读 references/migration-patterns.md，再进行编辑。

搜索清单

迁移前后，请搜索以下所有内容：

• extends TaggedError
• readonly _tag =
• TaggedError.match
• TaggedError.matchPartial
• TaggedError.isTaggedError
• 已迁移错误类的 new 调用点

完成标准

满足以下条件时，迁移即告完成：

• 没有类再直接继承旧版 v1 TaggedError 基类
• 已迁移的类使用 TaggedError("...")<...>()
• 调用点使用新的构造函数形式
• 静态辅助函数调用已替换为 matchError、matchErrorPartial 或 isTaggedError
• 导入已更新为新的辅助函数
• 使用升级后的包版本运行测试并通过

常见问题

• 改写时丢失自定义验证逻辑
• 忘记在 props 形状中包含 message
• 只更新类声明，却未更新构造函数调用点
• 替换了 TaggedError.match，却漏掉 matchPartial 或 isTaggedError
• 迁移了类型，却未保留时间戳或代码等额外的运行时字段

本参考文档包含的内容

文件	用途
references/migration-patterns.md	v1 → v2 迁移的详细前后对比示例及导入辅助函数的变更

如果存在 opensrc/，请使用它确认已安装软件包公开的确切 v2 API。