cats-effect-io

Cats Effect IO（Scala）

クイックスタート

• すべての副作用と非決定性の原因をエフェクト値として扱い、必要最小限の Cats Effect の機能を備えた IO[A]、SyncIO[A]、または F[A] を返します。
• 事前に計算した結果ではなく、副作用を伴う呼び出し自体をサスペンドします。Instant.now()、乱数や UUID の生成、環境変数の読み取り、new Array[...] などの可変オブジェクトの割り当ては、IO(...)、Sync[F].delay、Clock、Random、またはエフェクトを返すファクトリーの中で行います。
• 共有される可変状態は、IO／F／Resource のファクトリーを通じて初期化し、得られた参照やサービスを引き渡します。コンストラクター、トップレベルの val、デフォルト引数にエフェクトを隠さないでください。
• Java のブロッキング処理の使用フェーズの呼び出しは、デフォルトで IO.interruptible（または Sync[F].interruptible）でラップします。取得、ファイナライザー、および中断すべきでない操作には blocking を使用します。
• リソースの取得と解放には Resource を使用し、プログラムのエントリーポイントには IOApp を使用します。
• 手動でファイバーを管理するより、構造化並行処理（parTraverse、parMapN、background、Supervisor）を優先します。
• アプリケーションコードやテストでは unsafeRun*（unsafeRunSync、unsafeRunAndForget など）を使用しないでください。Cats Effect に準拠しないコールバック API と連携する場合は、Dispatcher を使用します。
• 概念、レシピ、FAQ の指針、および検証済みのサンプルについては、references/cats-effect-io.md を参照してください。
• Resource の詳細なガイダンスについては、cats-effect-resource スキルを使用してください（インストール：npx skills add https://github.com/alexandru/skills --skill cats-effect-resource）。

ワークフロー

1. 時刻、乱数、可変オブジェクトの割り当て、共有状態の読み書きなど、すべての副作用と非決定的な値を特定します。
2. エフェクト型を選びます。具体型の IO、または必要最小限の機能（Clock、Random、Sync、Async、Temporal、Concurrent など）を備えた多相型の F[_] を選択します。
3. 副作用を伴うコードを IO(...)、IO.interruptible、IO.blocking、IO.async、または対応する型クラスの操作でラップします。
4. 状態を持つサービスの初期化を、F[A] または Resource[F, A] を返す create／resource ファクトリーに移します。
5. flatMap／for 内包表記やコレクション用コンビネーター（traverse、parTraverse）でエフェクトを合成します。
6. 並行処理プリミティブ（Ref、Deferred、Queue、Semaphore、Supervisor）と構造化並行処理を使用し、ファイバーのリークを防ぎます。
7. エフェクトの実行は境界（IOApp、フレームワークのランタイム）に限定します。コールバック形式の API と連携する場合は、Dispatcher で橋渡しします。

副作用に関するルール（IO、SyncIO、および F[_]: Sync/Async に適用）

• 副作用を伴う関数はすべて、IO（または Cats Effect の型クラス／機能を備えた F[_]）でラップした結果を返す必要があります。
• 副作用には、すべての非決定性（呼び出し箇所が参照透過でないもの）が含まれます。
  • あらゆる I/O（ファイル、ソケット、コンソール、データベース）。
  • Instant.now()、System.currentTimeMillis()、Random.nextInt()、UUID.randomUUID()。
  • 環境変数、システムプロパティ、クロック、乱数ソース、共有可変状態からの読み取り。
  • アイデンティティや変更が外部に漏れる可能性がある、可変構造体（Array、mutable.Map、Java コレクション、AtomicReference、キャッシュ）の割り当てや返却。
• ローカルに限定された非公開の可変処理は、可変ブロック全体がサスペンドされ、可変値が外部に漏れない場合に限り許容されます。

ブロッキング I/O に関するルール

• ブロッキング処理の使用フェーズの操作には、IO.interruptible／Sync[F].interruptible を優先します。これによりキャンセル時に基盤のスレッドを中断できる可能性が生まれ、ネットワークやソケット形式のブロッキング API に適したデフォルトになります。
• interruptible を使用する前に、すべての Java API が中断に従うという証明を求めないでください。中断を無視する API もあるため、キャンセルへの応答性が重要で、テストで中断だけでは不十分と判明した場合は、リソース固有のキャンセルプロトコルを追加します。
• 取得、クリーンアップ、破棄（Closeable#close、AutoCloseable#close）には IO.blocking／Sync[F].blocking を使用します。このような処理で中断を試みると、ライフサイクルの状態が不明確になる可能性があります。

出力に関する期待事項

• シグネチャで副作用を明示してください（IO／SyncIO または F[_]: Sync/Async）。ここでのガイダンスは、具体型の IO と多相型の F[_] のどちらにも同様に適用されます。
• 必要な操作をサポートする、最小限の型クラス制約を使用してください。
• 副作用は値として保持し、コンストラクターやトップレベルの val で実行しないでください。
• Scala の例を追加または変更した場合は、同梱の scripts/verify-examples.scala スクリプトを更新してコンパイルしてください。

実行とテストのルール

• 本番コードとテストコードでは、import cats.effect.unsafe.implicits.global を含め、unsafeRun* を使用してはいけません。
• Cats Effect 以外のコールバックから副作用を実行する必要がある場合は、Dispatcher を使用してください。
• 副作用を手動で実行するのではなく、IO[Assertion]／F[Assertion] を返すなど、副作用をネイティブに扱えるテストスタイルを優先してください。
• TestControl を使った仮想時間のテストでない限り、ユニットテストで IO.sleep／Thread.sleep を使用しないでください。

参考資料

• ドキュメントの概要とパターンについては、references/cats-effect-io.md を読み込んでください。
• 具体例については、references/cats-effect-io.md を参照してください。代表的なチェックは scripts/verify-examples.scala です。
• Resource に特化したワークフローとパターンには、cats-effect-resource スキルを使用してください（インストール方法：npx skills add https://github.com/alexandru/skills --skill cats-effect-resource）。