migrate-better-result-3

better-result を 3.0 に移行する

コンパイラーを移行台帳として扱います。まず棚卸しを行い、機械的な変更を加えてから、残った各エラーを API の分岐ごとに解決します。

1. 移行対象を明確にする

リポジトリーの指示、パッケージマニフェスト、ロックファイル、TypeScript の設定、検証コマンドを確認します。ソースのバージョンが better-result 2.x であることを確認し、入手できる場合はインストール済みの 3.0 の宣言を調べます。記憶している API よりも、パッケージのソースを優先してください。

本番コードとテストで次を検索します。

rg -n --glob '*.{ts,tsx,mts,cts}' \
  'TaggedError|Result\.(serialize|deserialize|hydrate|tryRecover|tryRecoverAsync|tryPromise|partition|gen)|matchError(Partial)?|TaggedErrorClass|Serialized(Result|Ok|Err)'

references/v3-api-diff.md に記載された監査対象の API 変更ごとに、ヒットした箇所を分類します。タグ付きエラーを含む Result を構造的に比較するテストも含めてください。v3 ではタグ付きエラーが反復可能になりますが、Result.gen のシグネチャは変わりません。生成コードまたはベンダーコードのヒットは別に記録し、編集しないでください。

完了条件： インストール済みのソースバージョン、移行先である 3.0 の API、検証コマンド、本番コードとテストで該当するすべての箇所、およびタグ付きエラーを含む Result のすべてのアサーションについて、ファイルと移行分岐を特定して記録していること。

2. TaggedError の codemod を適用する

安全に変更できる末尾の呼び出しを一覧表示します。

node <skill-dir>/scripts/migrate-tagged-error-v3.mjs . --list

一覧にあるクラスの継承式を確認してから、変更を適用します。

node <skill-dir>/scripts/migrate-tagged-error-v3.mjs . --write
node <skill-dir>/scripts/migrate-tagged-error-v3.mjs . --check

この変換で変更されるのは、v2 のクラス継承の形式だけです。

class NotFoundError extends TaggedError("NotFoundError")<{ id: string }>() {}
// becomes
class NotFoundError extends TaggedError("NotFoundError")<{ id: string }> {}

コンストラクター、プロパティ、書式、呼び出し箇所は維持されます。エクスポートされた TaggedErrorClass<Tag, Props> 注釈を、v3 のクラス型 TaggedErrorClass<Tag> に手動で更新し、ペイロードの型は上記のサブクラスの適用箇所に移します。

完了条件： スクリプトのチェックが成功し、検索結果に生成コードまたはベンダーコード以外の v2 形式の末尾ファクトリー呼び出しや、2 引数の TaggedErrorClass の使用箇所がないこと。

3. 削除されたシリアライズヘルパーを置き換える

棚卸しに Result.serialize、Result.deserialize、または Result.hydrate が含まれる場合は、references/result-codec-migration.md に従ってください。各コーデックは、1 つのアプリケーション契約を検証します。つまり、メソッドの実際の Ok および Err ペイロードを、両方向について検証します。スキーマの断片、ファクトリー、エラーポリシーのヘルパーはコーデック間で共有し、異なる成功契約は、個別の名前付きコーデックとして維持します。

制御フローの変更も考慮してください。シリアライズでは ResultSerializationError が返されるようになり、デシリアライズでは ResultDeserializationError が追加されます。また、同期／非同期スキーマによって、コーデック操作が Result と Promise<Result> のどちらを返すかが決まります。リポジトリーがプロデューサーとコンシューマーの両方を管理し、契約の不一致を欠陥として扱う場合は、コーデックエラー処理のボイラープレートをなくすために serializeUnsafe と deserializeUnsafe を優先してください。serializeUnsafe はパニックを発生させて ResultSerializationError をなくします。deserializeUnsafe がなくすのは ResultDeserializationError だけで、有効なデコード済みのドメイン Err 値は保持されます。公開境界、独立したバージョン管理を行う境界、永続化境界、その他の信頼できない境界では、安全なメソッドを使用してください。

完了条件： 削除されたヘルパーの呼び出しすべてに、メソッドまたは境界固有のコーデックと 4 つのペイロードスキーマが設定され、ワイヤー上の Err が意図したドメインエラーとしてすべて再構築され、各境界でコーデックエラーまたは意図的な unsafe Panic ポリシー、および非同期の戻り値が処理されていること。

4. 変更された推論とオプション API を調整する

機械的な変更とコーデックの変更後に型チェックを行います。references/v3-api-diff.md を参照して診断を解決してください。特に、次の点に注意してください。

• tryRecover と tryRecoverAsync は、元の成功型を保持し、これに異なる復旧後の成功型を加えたユニオン型を返すようになりました。
• matchError、matchErrorPartial、および追加された TaggedError#match メソッドは、戻り値が異なるハンドラーからユニオン型を推論します。網羅的なマッチングでは、スローするハンドラーは Panic に変換されます。match は予約済みの名前なので、v3 の型で拒否された、ペイロードやサブクラスとの名前の衝突は変更してください。
• matchErrorPartial ではフォールバックを省略できます。その場合、処理されないタグ付きエラーは変更されずに返されます。
• Result.partition は異種の入力に対応するようになり、all、allAsync、partitionAsync が新たに追加されました。
• Result.tryPromise は、中断コンテキスト、動的な遅延、ジッターを追加しつつ、有効な v2 の静的な再試行設定も引き続きサポートします。
• タグ付きエラーは Result.gen で直接 yield* できるよう、反復可能になりました。タグ付きエラーに対する構造的な深い等価性アサーションは、Result の状態とエラーの同一性／フィールドを個別に確認するアサーションに置き換えてください。

ユーザーから新しい 3.0 の機能を採用するよう求められていない限り、既存の実行時の動作を維持してください。キャストよりも、正確に拡張された型と明示的な絞り込みを優先してください。

完了条件： 変更された 3.0 のシグネチャが原因のコンパイラー診断がすべて解決され、意図的に推論されたユニオン型がすべて明示的な処理箇所に到達し、無関係な動作が変更されていないこと。

5. 移行をアップグレードして検証する

直接依存関係とロックファイルを、指定された安定版またはプレリリース版の 3.0 の正確なバージョンに更新します。移行時の動作を調査する間は、そのバージョンを固定してください。

まず、移行対象を絞ったテストを 1 つ実行します。パッケージスクリプトとパッケージマネージャーの引数引き渡しルールを確認し、テストランナーが収集したファイルの出力に、意図したテストファイルだけが含まれていることを確認してください。リポジトリで必要なフォーマット、Lint、型チェック、全テストスイート、ビルドの各コマンドを実行します。インベントリ検索と codemod チェックを再度実行してください。リポジトリ全体に対するフォーマッターが既存の失敗を報告した場合は、無関係なファイルを変更しないでください。

バージョンの変更、ブランチごとに移行したファイル、コーデック／エラー処理に関する判断、採用したオプション機能、検証の証拠を報告してください。

完了条件： 対象を絞った実行で意図したファイルだけがテストされ、記録済みの生成コード／ベンダーコードを除いて、削除された API や v2 の TaggedError 構文が残っておらず、インベントリに記録された箇所がすべて対応済みで、指定されたバージョンが引き続きインストールされ、リポジトリのすべてのチェックが成功しているか、失敗の具体的な内容が報告されていること。