cats-mtl-typed-errors

Cats MTL の型付きエラー（Scala）

クイックスタート

• ドメインエラー型を定義します。状況に応じて Throwable を拡張しても、しなくてもかまいません。
• エラーを発生させる可能性がある関数では、Cats MTL の Raise[F, E] を使用します。
• Handle.allow／rescue（Scala 3）または Handle.allowF（Scala 2）を使って、エラー機能をスコープ内で導入し、try/catch のように処理します。
• IO[Either[E, A]] より Cats MTL を優先し、EitherT[IO, E, A] は避けます。API 境界で純粋関数が Either[E, A] を返すのは問題ありません。
• F[_] は任意です。プロジェクトに応じて、IO 固有のコードを書くことも、ポリモーフィズムのために F[_] を使うこともできます。

ワークフロー

1. ドメインエラーを sealed ADT（Scala 2）または enum（Scala 3）としてモデル化します
2. エラーを発生させる可能性があるエフェクトフルなコードでは、Raise[F, E]（および Monad[F] または Applicative[F]）を要求します。
3. .raise でエラーを発生させ、成功値は pure で返します。
4. 境界で Handle.allow（Scala 3）または Handle.allowF（Scala 2）を使い、エラーの発生が有効なスコープを作成します。
5. .rescue でスコープを閉じ、各エラーケースを明示的に処理します。
6. モノファンクターのエラーチャネルを維持して、Cats Effect のリソースおよび並行性のセマンティクスを保ちます。

適用するパターン

• シグネチャ内の型付きエラー：エラー型パラメーター E を、関数シグネチャ内のチェック例外チャネルとして扱います。
• スコープ付きのエラー機能：失敗する可能性のある関数では Raise[F, E] を要求します。エラーからの回復も必要な場合は Handle[F, E] を使用します。
• Scala 3 の使いやすさ：using と allow を使ったコンテキスト関数を優先します。型推論が大幅に改善されます。
• Scala 2 との互換性：allowF と明示的な implicit パラメーターを使用します。波括弧や明示的な型が増えることを想定してください。
• 純粋コードとの相互運用：解析や検証には純粋な Either[E, A] を使い、必要に応じて F にリフトします。
• トランスフォーマーのスタックを避ける：型付きエラーチャネルを得るためだけに EitherT を使わないでください。Cats MTL はスタックなしでこの機能を提供します。
• sealed 同士の継承を避ける：エラー階層は sealed の継承チェーンではなく、合成（ラッパーのケースクラス）でモデル化します。

参考資料

• 詳しいガイダンス、Scala 2／3 の構文、および Typelevel の記事に基づく根拠については、references/custom-error-types.md を読み込んでください。