effect

Effect

タスクの対象となるアプリケーションコード全体でEffectを使用してください。Promiseベースのアプリケーション全体を1つのEffectで包むだけでは、導入が不十分です。

検証済みの参照スナップショットは [email protected]（初の安定版v4リリース、npmのlatest、LTS）です。依存関係を変更する前に、インストール済みのバージョンを確認してください。v3とv4のAPIを混在させないでください。引き続き4.0.0-rc.* / beta.*を使用しているプロジェクトでは、migration.mdに記載されているRCから4.0へのアップグレードを適用してください（インポートパスと複数の名称が変更されています）。

導入に関する必須方針

• ユースケース、サービスメソッド、I/O、予期される失敗、リソースの所有権、並行処理はEffectの中に含めてください。
• カスタムヘルパーを作成したり、機能が重複するライブラリを追加したりする前に、該当するEffectの機能を選んでください。以下の索引を参照してください。
• アプリケーションが所有するバリデーションとコーデックにはEffect Schemaを、依存関係にはContextとLayerを、クリーンアップにはScopeを使用してください。
• 同じ責務を担う独自のシステムを並行して作らず、Effectのスケジューリング、並行処理、状態管理、設定、可観測性を使用してください。
• Promise、コールバック、フレームワーク、ベンダーのAPIは、名前付きアダプターの境界に留めてください。境界に入るときと出るときに、それぞれ一度だけ変換してください。
• 既存のElysiaルートはPromiseを返してもかまいません。ハンドラーはEffectのユースケースに処理を委譲し、ビジネスロジックはハンドラーの外に置いてください。
• ドメインサービス内でランタイムのランナーを呼び出し、EffectをPromise APIのように見せないでください。
• 純粋な計算や通常のTypeScriptデータはシンプルに保ってください。失敗する場合や副作用を実行する場合を除き、Effectで包む必要はありません。
• 新たな重複ユーティリティを追加するより、Effectの標準ライブラリを優先してください。明快な言語演算子やネイティブのデータ構造を機械的に置き換えないでください。
• 指定されたスコープを守ってください。変更するユースケースはエンドツーエンドで変換し、無関係なリポジトリ全体の移行には着手しないでください。
• Effectを使わない境界が残る場合は、その具体的な制約とともに記録してください。利便性だけでは、2つ目のアプリケーションアーキテクチャを導入する理由になりません。

混在するコードベースの実装、レビュー、移行を行う際は、adoption-boundaries.mdをお読みください。

機能の詳細インデックス

実装を選ぶ前に、この一覧を確認してください。リンク先のカタログには、スナップショット内のすべての公開モジュール名前空間と公開モノレポパッケージが掲載されています。 これは機能／モジュールのインデックスであり、すべての関数を列挙したものではありません。シグネチャはインストール済みの宣言で確認してください。unstable と記された領域は、インポートパスに unstable セグメントがなくても、@stability unstable（マイナーリリースで破壊的変更が発生する可能性があります）です。

責務	Effect の機能
ユースケース、型付きの失敗、回復	Effect.fn、Effect.gen、Cause、Exit、Result、Option、Match
依存関係、アプリケーションのライフタイム	Context、Layer、ManagedRuntime、Scope、LayerMap、LayerRef
バリデーション、コーデック、ドメイン型、派生フォーマット	Schema、Brand、Data、StandardSchema、JsonSchema、Optic、不安定な schema JIT/AOT コンパイラー
設定、シークレット、時間、サイズ、乱数	Config（PascalCase コンストラクター）、ConfigProvider、Redacted、Clock、DateTime、Duration、ByteSize、Random
リトライ、繰り返し、タイムアウト、フォールバック	Schedule、Cron、Effect のタイムアウト／リトライ、ExecutionPlan
並行処理、キャンセル、同期	Fiber、ファイバーコレクション、Deferred、Latch、Semaphore、PartitionedSemaphore
共有状態とトランザクション状態	Ref、SynchronizedRef、SubscriptionRef、ScopedRef、Effect.tx、すべての Tx* モジュール
ストリーミングとバックプレッシャー	Stream、Sink、Queue、PubSub、低レベルの Channel、Pull、Take、ChannelSchema
キャッシュ、バッチ処理、再利用可能なリソース	Cache、ScopedCache、Request、RequestResolver、Pool、Resource、RcRef、RcMap
コレクション、テキスト、数値、等価性、アルゴリズム	Array/Chunk/Record/Hash コレクション、Graph、Trie、HashRing、BigDecimal、プリミティブおよびプロトコルモジュール
ファイル、パス、ターミナル、暗号化	FileSystem、Path、Stdio、Terminal、Crypto、プラットフォーム実装
ログ、トレース、メトリクス、診断	Logger、LogLevel、Tracer、Metric、ErrorReporter、不安定な effect/observability、effect/devtools
HTTP、型付き API、ソケット、アドレス、RPC	不安定な effect/http、effect/http-api、effect/socket、effect/net、effect/rpc
データベース、モデル、マイグレーション	不安定な effect/sql、effect/schema、SQL ドライバーパッケージ
永続化、レート制限、イベントソーシング	不安定な effect/persistence、effect/eventlog
AI、ツール、MCP、埋め込み、構造化された判断	不安定な effect/ai（Decision / DecisionModel を含む）、プロバイダーパッケージ
UI 状態、無効化、ハイドレーション	不安定な effect/reactivity、React/Solid/Vue バインディング
コマンド、サブプロセス、ワーカープール	不安定な effect/cli、effect/process、effect/workers
分散エンティティ、耐久性のある処理	不安定な effect/cluster、effect/workflow
バイトおよびワイヤーフォーマット	effect/encoding：Base64、Base64Url、Hex（安定版）、NDJSON、SSE、YAML、TOML、INI、SchemaBinary（不安定）。MessagePack は削除されました
テスト、プロパティチェック、ドキュメント／クライアントの生成	effect/testing、不安定な Arbitrary、@effect/vitest、docgen/doctest/OpenAPI ツール

正確な一覧：コアとテスト、すべてのサブパス領域、すべての公開パッケージ。

ワークフロー

1. ローカルの Effect の構成を確認します。effect / @effect/* のバージョン、インポート形式（from "effect" と effect/Effect のどちらか）、ランタイム（CLI、HTTP、worker、ブラウザー、テスト）、および layers/config/platform がすでに使用されているかを確認します。
2. Effect-TS/effect のローカルチェックアウトを、インストール済みリリースタグ（例：[email protected]）で .temp/effect に置くことを優先します。Effect-TS/effect-smol はアーカイブ済みです。v4 は Effect-TS/effect の main に、v3 は v3 ブランチにあります。ソース、LLMS.md、MIGRATION.md、migration/*、packages/effect/SCHEMA.md、ai-docs/ を確認します。詳細はソースマップを参照してください。
3. インストール済みのバージョンがスナップショットと異なる場合、またはタスクで最新の API が求められる場合は、ドキュメントを更新します。ライブラリのドキュメントを確認してから、インストール済みの .d.ts を確認します。
4. 関心領域に応じて参照先を選びます。
   • インストール、Effect.fn/gen、エラー、fork、実行、Config → setup-core.md
   • サービス、layers、scopes、ManagedRuntime、Layer.launch → services-layers-runtime.md
   • 安定版モジュールの全カタログ（各モジュールの用途）→ modules-stable.md
   • Stream、Queue/PubSub、ファイバー、STM に似た Tx*、キャッシュ、リクエスト → concurrency.md
   • Schema v4 → schema-v4.md
   • サブパス領域（effect/http、effect/sql、effect/ai など）→ modules-unstable.md
   • @effect/platform-*、sql-*、ai-*、atom-*、OTel、ツール → ecosystem.md
   • @effect/vitest → vitest-testing.md
   • v3 → v4、および v4 RC → 4.0 → migration.md
5. 互換性のあるプロジェクト規約を維持しながら、必要な採用ポリシーを実装します。インストール済みのバージョンに合わせ、フレームワークとの境界を薄く保ち、layers を明示的に合成します。@stability unstable の領域（effect/http、effect/sql、effect/ai など）はマイナーリリースで破壊的変更が発生する可能性があり、@stability experimental の API はパッチリリースでも変更される可能性があるものとして扱います。

コーディングスタイル（標準）

Effect 独自の LLMS.md / ai-docs に基づきます。

• Effect のインラインコードでは Effect.gen を使用します。再利用可能なエフェクト関数には、トレーススパンが有用な場合は Effect.fn("name")、ライブラリコードや、トレース境界として有用でないホットパスには Effect.fnUntraced を使用します。Effect.gen をラップして返すだけの通常の関数は書かないでください。また、Effect.fn の結果に .pipe を適用しないでください。
• ドメインエラーには Schema.TaggedError を使用します。TypeScript の型が絞り込まれるよう、失敗時は必ず return yield* を使います。
• サービスには Context.Service を使用し、識別子は "myapp/db/Database" のようにします。Database.of({ ... }) で実装し、static readonly layer を付けます。1 行で済む場合を除き、Service.use より yield* Service を優先します。
• 信頼できないデータには、その場しのぎの述語ではなく Schema を使用します。isString / isObject / 合成には Predicate を使い、これらのヘルパーを独自に作らないでください。
• Effect プログラム内の日付・時刻には、生の Date.now() ではなく DateTime と Clock を使用します。
• オブザーバビリティには、コアのログ／トレース／メトリクスを使用します。新規プロジェクトでは effect/observability の OTLP を優先します。既存の OTel SDK が必要な場合は @effect/opentelemetry を使用します。
• プロセスのエントリーポイントには NodeRuntime.runMain / BunRuntime.runMain（BunRuntime は Node と共有のランナー）、DenoRuntime / BrowserRuntime、または Layer.launch を使用します。Runtime.makeRunMain よりこれらを優先します。Cloudflare にはプラットフォームパッケージがありません。Fetch と SQL D1/DO ドライバーを使用してください。
• Channel より Stream/Sink、SchemaAST より Schema を優先します。concurrency.md に従い、用途に応じて Cache / ScopedCache / Pool / RcMap を使い分けます。

判断

• Align v4 のモノレポ統合パッケージは、effect と同じリリースにそろえます。独立したツールパッケージは、それぞれのピア依存関係を確認します。
• TypeScript 5.9+（Effect の TS ツールでは 7 を推奨）。strict: true。通常は Node 18+ が必要ですが、一部の SQL ドライバーでは Node 22.16+ が必要です。
• 4.0 では Config のコンストラクターは PascalCase です（Config.String、Config.Int、Config.Redacted、Config.URL、…）。Config.mapOrFail は Config.mapEffect です。
• v4 のコードでは v3 API を使いません：Context.Tag / GenericTag、Effect.Tag / Effect.Service、Either、FiberRef、Effect.catchAll、Effect.fork（forkChild を使用）、Effect.async（callback を使用）。
• レイヤーは、{ local: true } または Layer.fresh を指定しない限り、Effect.provide をまたいでメモ化されます。
• Runtime<R> は廃止されました。Effect.run* / run*With(context) または ManagedRuntime で実行します。
• Ref / Deferred / Fiber は yield 可能な Effect ではありません。Ref.get、Deferred.await、Fiber.join を使用します。
• throw/die よりも、型付き失敗を優先します。欠陥はプログラマーのエラーです。
• 境界では Schema の Encoded と Type の違いが分かるようにします。
• テスト：@effect/vitest@4 + vitest@^5（ピア依存関係は >=5 <6）。it.effect を優先します（すでにスコープ化され、TestClock が適用されています。Effect.scoped で囲まないでください）。TestClock は effect/testing からインポートします。it.effect はログを抑制しますが、it.live は抑制しません。
• 使用禁止：effect/unstable/* のインポート（4.0 で削除）/effect/Encoding/effect/testing/FastCheck/小文字の Config.string/catchAll/fork/forkDaemon/Context.Tag/Effect.Service/.Default/Either/FiberRef/Date.now/gen 内の try/catch/ISO 文字列に対する Schema.Date/Union(A,B)/追加の Effect.scoped を伴う it.effect。

モジュールの選び方（簡易版）

必要なもの	使用するもの
ワークフロー、エラー、並行処理	Effect、Cause、Exit、Result、Fiber
DI	Context、Layer、ManagedRuntime
設定	Config、ConfigProvider
検証 / ドメイン型	Schema（+ Schema.Class / TaggedError）
時間	Clock、Duration、DateTime、Cron、Schedule
コレクション	Array、Chunk、HashMap、HashSet、Record、Option
1 つのプロデューサー、多数のコンシューマー	PubSub
作業キュー	Queue
プルストリーム	Stream / Sink / Channel（低レベル）
複数 Ref のアトミックな更新	Effect.tx + TxRef / TxQueue / …
HTTP クライアント/サーバー	effect/http + @effect/platform-*
Schema ファーストの HTTP API	effect/http-api
SQL	effect/sql + @effect/sql-*
LLM / ツール	effect/ai + @effect/ai-*
テスト / プロパティチェック	@effect/vitest、effect/testing、Arbitrary

すべてのルートモジュール：modules-stable.md。すべてのサブパス領域：modules-unstable.md。

検証

• Effect<A, E, R>、レイヤー、Schema の encoded/type 側、インストール済み API 名を型チェックします。
• 変更したユースケース全体を確認し、隠れた Promise、ランタイム呼び出し、管理されていないリソース、インフラストラクチャの重複がないか調べます。
• 動作に変更がある場合は、アダプターのエラーマッピング、キャンセル、リクエストのクリーンアップ、アプリケーションのシャットダウンをテストします。
• 正当な非 Effect 境界と、残っている移行作業を報告します。未解決の箇所がある間は、完全に導入済みだと主張しないでください。
• @effect/vitest：it.effect、TestClock、Exit/Result、分離が重要な場合はテストごとの Effect.provide。
• Schema：有効/無効な入力、デフォルト値、余分なキー、クラス、タグ付きエラー、JSON Schema。
• 移行スキャン：v3 のインポート、Either、FiberRef、旧式の catch/fork/runtime/Schema API、RC の残存箇所（effect/unstable/、effect/Encoding、FastCheck、小文字の Config.*、旧式の Schema.is* チェック名）。