effect

Effect

このスキルでは、現在の Effect v4 API と本番環境向けのデフォルト設定を使用します。タスクで明示的に変更する場合を除き、確立済みのプロジェクト規約を引き続き優先してください。

ソースルール

Effect 4.0.0 および上流コミット 6389d9ac6 に照らして確認済みです。 v3 または v4 のプレリリースからアップグレードする場合は、references/V4_APIS.md を読んでください。 インストール済みのバージョンが優先されます。プレリリースでは API やインポートパスが異なる場合があります。

推測する前に、次の項目を確認してください。

• 最も近い AGENTS.md と、プロジェクト内に Effect の実践方法をまとめたドキュメントがあればそれ
• プロジェクトで指定されている effect パッケージのソースとバージョン
• インストール済みのパッケージで疑問が解決しない場合は、現在の上流 Effect ソース

ブランチの選択

タスクに該当するブランチのリファレンスのみを読んでください。

• データモデル、スキーマ、ブランド、バリアント、オプションキー、デコーダー：references/SCHEMA.md を読んでください。
• サービス、モジュールのサーフェス、レイヤー、ランタイムの配線、エラー、Effect.fn、テストサービス：references/SERVICES_LAYERS.md を読んでください。
• ランタイム設定、環境変数、ConfigProvider、layerConfig：references/CONFIG.md を読んでください。
• リトライ、繰り返し、ポーリング、バックオフ、ジッター、レート制限対応のポリシー、またはパスループ：references/SCHEDULING.md を読んでください。
• メモ化、キーごとの TTL キャッシュ、同時実行されるルックアップの重複排除、またはリクエストのバッチ処理：references/CACHING.md を読んでください。
• ストリーム、イベントソース、非同期イテラブル、キュー／PubSub、ページネーション、バックプレッシャー、またはストリームコンシューマー：references/STREAMS.md を読んでください。
• 外部への HTTP 呼び出し、Effect HttpClient、ステータス処理、または HTTP レート制限：references/HTTP_CLIENTS.md を読んでください。
• Effect のテスト、時間、スリープ、並行処理の同期、またはフェイク：references/TESTING.md を読んでください。

複数のブランチにまたがるタスクでは、編集前に該当するすべてのファイルを読んでください。

コアのデフォルト設定

• ワークフローは Effect.gen(function* () { ... }) で合成してください。
• 公開サービスメソッドと、複雑な内部サービスメソッドは Effect.fn("Domain.operation") で定義してください。
• Effect.fnUntraced は、スタックフレームやスパンのメタデータが意図的に不要な内部ヘルパーに限って使用してください。
• コードベースで別の現在のサービスタグ形式が標準化されていない場合は、アプリケーションサービスに Context.Service を優先してください。
• 実際のサービス実装は Layer.effect(Service, Effect.gen(...)) で構築し、Service.of({ ... }) を返してください。
• レコードは Schema.Struct(...) と、同名の interface でモデル化してください。
• 型付き Effect エラーは Schema.TaggedError でモデル化してください。
• ランタイム設定は Config を通じて読み取り、アプリケーションロジックで process.env に直接アクセスしないでください。
• リトライ、繰り返し、ポーリング、ペーシング、バックオフのポリシーには Schedule を使用してください。
• 時間の経過とともに多くの値を出力し、プル、バックプレッシャー、中断、変換が必要なエフェクトフルなソースには Stream を使用してください。
• 型付きエラー、レイヤー、クライアント変換が役立つ場合は、Effect アプリケーションから外部への HTTP 通信に Effect HTTP クライアントのモジュールを優先してください。
• スリープよりも、Effect 対応のテスト、明示的なレイヤー、決定的な同期を優先してください。
• 未知のワイヤー入力は Schema.decodeUnknownEffect(...) でデコードしてください。検証が必要な型付きコンストラクター入力には schema.makeEffect(...) を使用してください。信頼できる構築に限り、例外をスローする schema.make(...) を使用し、検証を省略するためにキャストを使わないでください。

クイック選択ガイド

• 通常のオブジェクトレコード：Schema.Struct(...) と同名の interface。
• スカラー ID／値オブジェクト：制約付きのブランドスキーマ。
• 内部ワークフローの判定または状態：Data.TaggedEnum<...> と Data.taggedEnum<...>() コンストラクター、および網羅的な $match。
• 再利用可能で境界を越えるタグ付きバリアント：Schema.TaggedStruct(...) と同名の interface。
• 境界を越えるタグ付きユニオン：.cases、.guards、.match を備えた Schema.TaggedUnion(...)。
• type など、外部またはカスタムの識別子：Schema.Struct({ type: Schema.tag("variant"), ... })。ユニオンヘルパーが必要な場合は Schema.toTaggedUnion("type") を使用します。
• 想定される型付きエラー：Schema.TaggedError。
• 境界から受け取る未知のペイロード：Schema.decodeUnknownEffect(...)。
• サービス境界：Context.Service<Service, Interface>()(...)、Layer.effect(...)、Service.of(...)。
• 公開メソッドまたは複雑な内部サービスメソッド：Effect.fn("Domain.operation")。
• ランタイム設定：レイヤー内で読み込む Config レシピ。テストでは ConfigProvider で上書きします。
• イベントソース：Stream.runForEach(...) で消費し、所有するレイヤー内で Effect.forkScoped を使ってフォークする Stream。
• キューを基盤とするイベントソース：プロデューサー境界には Queue、コンシューマーには Stream.fromQueue(...)。
• ブロードキャストイベントソース：最新値の状態には PubSub／Stream.fromPubSub(...)、または SubscriptionRef。
• ポーリングワーカー：runPass().pipe(Effect.repeat(Schedule.spaced(...)))。型付きのパスエラーは繰り返し処理の前に処理します。
• 一時的な操作の再試行：上限のある Schedule と Effect.retry(...)／Effect.retryOrElse(...)。
• TTL 付きキー検索キャッシュと同時検索の重複排除：ライフサイクルと削除モデルが適合する場合は、Cache.make(...)／終了値を考慮する Cache.makeWith(...) を優先します。
• 単一の Effect 結果をメモ化：Effect.cached(...)／Effect.cachedWithTTL(...)。
• N 個のキーを 1 回のバックエンド呼び出しにまとめる（実際のバッチエンドポイントがある場合のみ）：Effect.request(...) と RequestResolver。
• Effect アプリケーション内での HTTP リクエスト：Effect の HttpClient と、リクエスト／レスポンスのスキーマデコードを優先します。
• HTTP の一時的なエラーの再試行：HttpClient.retryTransient(...)。
• 時間に依存するテスト：実際にスリープするのではなく TestClock を使用します。
• 並行処理／バックグラウンドテストの同期：Deferred、Queue、Latch、Ref、または明示的なテストフックを使用します。

境界のルール

• HTTP ハンドラーは薄く保ちます。入力をデコードし、コンテキストを読み取り、サービスを呼び出し、型付きエラーをトランスポートのレスポンスにマッピングします。
• ビジネスルールはトランスポートハンドラーではなく、サービスまたはドメイン関数に置きます。
• HTTP クライアント、SDK、CLI、外部連携は、アダプター境界で名前付き Effect にラップします。
• 保存された行の値が明らかに信頼できるものではない場合は、Schema または SQL 固有のヘルパーでデコードします。
• プロバイダー／ネットワーク呼び出しは、権威あるデータベーストランザクションの外で行います。
• 現在の境界で真実性のあるレスポンスを返せる場合に限り、エラーを捕捉するか再試行します。
• 冪等性が確認された操作のみ再試行します。
• 境界に実際のフォールバックがない限り、再試行を使い切ったエラーは見える状態のままにします。

禁止事項

• Effect の型付けの問題を黙らせるために、as any、非 null アサーション、未検証のキャストを使用しないでください。
• アプリケーションのデータモデリングにおける標準パターンとして、Schema.Class や Schema.TaggedClass を導入しないでください。
• Schema.TaggedError が適している場合に、_tag を持つエラークラスを独自に作成しないでください。
• 型付きエラーのリカバリーで十分な場合に、Cause レベルのリカバリーを使用しないでください。
• やみくもにコンパイルを通すための手段として Layer.mergeAll(...) や provideMerge(...) を使用しないでください。
• 必須のアプリケーション権限、認証情報、永続化、トランスポート、外部サービスを、デフォルト値を持つ Context.Reference の背後に隠さないでください。
• 決定論的な同期プリミティブが利用できる場合、テストに任意の Effect.sleep(...) を追加しないでください。
• effect/Cache が適している場合に、Map／TTL／prune キャッシュや実行中処理の重複排除を独自に実装しないでください。