better-result-migrate-v2

better-result v2 への移行

better-result のエラー定義を、v1 の TaggedError API から v2 のファクトリーベースの API にアップグレードします。

使用するタイミング

次のような場合に、このスキルを使用します。

• better-result を v1 から v2 にアップグレードしている
• TaggedError を直接 extend するクラスがある
• 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 を確認してください。