effect-v4

Effect v4（ベータ）- 開発と移行

概要

Effect v4 の開発と v3 からの移行に関する包括的なガイダンスです。このスキルでは、次の内容を説明します。

1. v4 のコアパターン - Context、レイヤー、ジェネレーター、スキーマコーデックを使って新しい v4 コードを構築するためのガイド
2. v3 → v4 の移行 - API の名称変更、動作の変更、変更前と変更後の例を含む、段階的な移行ガイダンス

ステータス： Effect v4 は、effect-smol で活発に開発が進められているベータ版ソフトウェアです。コアとなるプログラミングモデルは安定していますが、effect/unstable/* モジュールにはマイナーリリースで破壊的変更が加わる場合があります。本番環境で使用する場合は、公式の v4 ベータ版ガイダンスと安定性に関する注記を確認してください。

同梱されている移行ガイドはすべて、公式の effect-smol 移行ドキュメントを参照しています。

2026 年 6 月 30 日までの上流の変更

上流のベータ版は、当初の 2026 年 2 月 22 日時点から大幅に変更され、さらに 2026 年 4 月 9 日のスキル更新後にも変更が加わっています。ServiceMap、Schema.makeUnsafe、SchemaParser.makeUnsafe、Effect.Yieldable に言及している古い例は、古い情報として扱ってください。現在のガイダンスでは、次を優先してください。

• ServiceMap.* ではなく、Context.Service / Context.Reference / Context<R>
• Schema.makeUnsafe(...) ではなく、Schema.make(...)
• SchemaParser.makeUnsafe(...) ではなく、SchemaParser.make(...)
• コンストラクター形式の検証で、例外をスローするのではなくエラーチャネルにエラーを返す場合は、Schema.makeEffect(...)
• カスタムの Effect 類似値には Effectable.Class / Effectable.Prototype を使用します。Effect.Yieldable や .asEffect() は推奨しないでください
• 生成されたアサーションヘルパーではなく、Schema.asserts(schema, input) / SchemaParser.asserts(schema, input)

クイックトリアージ

v4 コードの構築

• コアの Effect 型とコンビネーター（Result、Option、Chunk、Duration）：references/core-usage.md
• より幅広いデータ型（DateTime、BigDecimal、HashSet、Redacted）：references/data-types-advanced.md
• Equality、Order、Hash、Equivalence のセマンティクス：references/behavior-traits.md
• 予期されるエラーと欠陥、catch* コンビネーター：references/error-management.md
• サンドボックス化、Cause の検査、catchCause：references/error-tooling.md
• Exit と Cause の構造、結果の検査：references/exit-cause.md
• サービスと依存性注入（Context、レイヤー）：references/dependency-management.md
• レイヤーの構築、メモ化、{ local: true }：references/layer-patterns.md
• リソースのライフサイクル、Scope、acquireRelease：references/resource-management.md
• エフェクトの実行、Runtime の削除、実行境界：references/runtime-execution.md
• ファイバー、forkChild、forkDetach、フォークのオプション：references/concurrency.md
• Reference（FiberRef を置き換えるもの）、Context.Reference：references/concurrency-advanced.md
• スケジュール、反復、間隔指定／固定／指数バックオフ：references/scheduling.md
• 再試行、バックオフ、スケジュールの合成：references/scheduling-retry.md
• ストリーム、キュー、PubSub、STM：references/streams-queues-stm.md
• HTTP クライアントと外部 API：references/http-client.md
• HTTP サーバーと API 定義：references/http-server.md
• リクエストのバッチ処理とデータローダー：references/request-resolver.md
• キャッシュとメモ化：references/caching.md
• 設定と設定プロバイダー：references/configuration.md
• 高度な設定、秘匿化：references/configuration-advanced.md
• ログ、メトリクス、トレース：references/observability.md
• ロガー／メトリクス／トレースのセットアップとエクスポーター：references/observability-examples.md
• ログ／メトリクス／トレースのレイヤーの配線：references/observability-wiring.md
• 順次ワークフローとジェネレーターパターン：references/generators.md
• 上流の調査メモと4月以降のベータ版の変更：references/upstream-changes-2026-06-30.md
• スキーマの検証、解析、エンコード（コーデック）：references/schema.md
• リデューサー（Sink）を使ったストリームの消費：references/sink.md
• テストにおける決定論的な時間（TestClock）：references/testing.md
• より幅広いテスト用サービスとテストレイヤー：references/testing-stack.md
• Command、FileSystem、Path、Terminal、KeyValueStore：references/platform-primitives.md
• Effect AI を使った LLM ワークフロー、計画、ツールの使用：references/ai.md
• バンドルサイズに制約のあるランタイム（Micro）：references/micro.md
• Promise／async からの移行：references/migration-async.md
• よくある落とし穴とランタイムエラー：references/troubleshooting.md
• llms.txt からドキュメントガイドへの対応表：references/docs-index.md

v3 からの移行

• 移行の全体像、クイックリファレンス表、順序付きチェックリスト：references/migration.md
• ランタイムと実行関数：references/migration/runtime.md
• エラー処理とエラーチャネルの変更：references/migration/error-handling.md
• Cause のフラット化と新しい構造：references/migration/cause.md
• サービスと環境の変更（Context.Tag / Effect.Service → Context.Service）：references/migration/services.md
• ファイバー参照とコンテキストローカル：references/migration/fiberref.md
• フォークとファイバー API（fork → forkChild など）：references/migration/forking.md
• ファイバーの keep-alive 動作の変更：references/migration/fiber-keep-alive.md
• Scope とリソースのライフサイクルパターン：references/migration/scope.md
• レイヤーのメモ化と Layer.fresh：references/migration/layer-memoization.md
• ジェネレーターと Effect.gen の変更：references/migration/generators.md
• Effect のサブタイピングとカスタムの Effect 類似値：references/migration/yieldable.md
• Equality と構造的比較：references/migration/equality.md

ワークフロー

1. 対象となる v3 の API またはファイルと、避けるべき失敗やリグレッションを確認します。
2. references/migration/ から関連する移行ノートのみを開きます。
3. 移行前後のコードスニペットを含む、v3 から v4 への対応表を作成します。
4. 動作の変更点、エッジケース、必要なテストの更新を説明します。
5. 対象コードに合わせた、簡潔で順序立てた移行チェックリストを提示します。

信頼できる情報源

• まず、このスキルに含まれるリファレンスを確認します。
• 質問が新しいベータ版の動作に関わる場合は、次に公式ドキュメントと effect-smol の変更履歴を確認します。
• ドキュメントや変更履歴で不明確な場合、ユーザーが内部実装について尋ねている場合、または動作がドキュメントに記載されていないように見える場合に限り、effect-smol のソース内部を調べます。
• 同梱のリファレンスや公式ドキュメントで質問に回答できる場合、デフォルトではリポジトリをクローンしたり、ソースを読んだりしないでください。

リクエストの例

• 「この v3 の Runtime の使用箇所を v4 に移行し、新しい run 関数について説明してください。」
• 「v3 のエラー処理を v4 に更新し、移行前後の例を示してください。」
• 「FiberRefs と fork を使っています。v4 では何を変更する必要がありますか？」
• 「generator と Effectable の変更を説明し、この Effect.gen の使用箇所を更新してください。」
• 「v4 では Scope や Layer のメモ化の動作を変更する必要がありますか？」

リファレンス - v4 コア

v4 専用の包括的なガイド（すべて v4 API に合わせて更新済み。非推奨のパターンはありません）：

• references/core-usage.md - Effect のコア型とコンビネーター（Result、Option、Chunk）
• references/data-types-advanced.md - DateTime、BigDecimal、HashSet、Redacted
• references/behavior-traits.md - デフォルトの構造的等価性、Equal、Order、Hash
• references/error-management.md - catch* の名称変更、catchReason、catchEager
• references/error-tooling.md - catchCause、サンドボックス化、Cause の検査
• references/exit-cause.md - フラット化された Cause 構造、Reason の反復処理
• references/dependency-management.md - Context、サービス、レイヤー
• references/layer-patterns.md - 横断的な provide のメモ化、{ local: true }
• references/resource-management.md - Scope.provide（旧 Scope.extend）
• references/runtime-execution.md - Runtime<R> の削除、境界での run* の使用
• references/concurrency.md - forkChild／forkDetach、fork オプション、キープアライブ
• references/concurrency-advanced.md - Context.Reference（旧 FiberRef）
• references/scheduling.md - スケジュールと繰り返し
• references/scheduling-retry.md - リトライとバックオフ
• references/streams-queues-stm.md - ストリーム、キュー、PubSub、STM
• references/http-client.md - HTTP クライアント
• references/http-server.md - HTTP サーバー
• references/request-resolver.md - リクエストのバッチ処理
• references/caching.md - キャッシュとメモ化
• references/configuration.md - 設定
• references/configuration-advanced.md - 高度な設定、秘匿化
• references/observability.md - ログ、メトリクス、トレーシング
• references/observability-examples.md - ロガー／メトリクス／トレーシングの具体的な設定
• references/observability-wiring.md - オブザーバビリティレイヤーの接続
• references/generators.md - Effect.gen と generator パターン
• references/upstream-changes-2026-06-30.md - 2026 年 6 月 30 日までのコミット範囲の調査概要
• references/schema.md - Schema コーデックと Schema.make／Schema.makeEffect
• references/sink.md - Sink によるストリームの消費
• references/testing.md - TestClock と決定論的な時間
• references/testing-stack.md - テストレイヤーの合成
• references/platform-primitives.md - Command、FileSystem、Path、Terminal
• references/ai.md - Effect AI による LLM ワークフロー
• references/micro.md - バンドルサイズに制約があるランタイム
• references/migration-async.md - Promise／async からの移行
• references/troubleshooting.md - よくある落とし穴
• references/versioning.md - バージョンに関するガイダンス
• references/docs-index.md - ドキュメントからガイドへの対応表

参考資料 - v3 → v4 の移行

• references/migration.md - まずはこちらをご覧ください：全体概要、クイックリファレンステーブル、順序付きチェックリスト
• references/migration/cause.md - Cause のフラット化と構造
• references/migration/equality.md - 等価性と比較の変更
• references/migration/error-handling.md - エラーチャネルと catch* の名称変更
• references/migration/fiber-keep-alive.md - Fiber のライフサイクルの変更
• references/migration/fiberref.md - FiberRef と References の変更
• references/migration/forking.md - fork、forkChild、forkDetach の変更
• references/migration/generators.md - Effect.gen パターンの更新
• references/migration/layer-memoization.md - Layer.fresh とメモ化
• references/migration/runtime.md - Runtime と run* 関数
• references/migration/scope.md - Scope とリソースのライフサイクル
• references/migration/services.md - 現在の Context.Service API と、以前のベータ版における ServiceMap の名称変更に伴う影響
• references/migration/yieldable.md - Effect のサブタイピングの削除、Effectable、ジェネレーターの変更