Effect入門──次の新規開発で役立つ実践指針

「バリデーションは整えたのに内部ロジックの分岐が膨らむ」という課題を起点に、Effectで依存関係ごとの責務分離、失敗チャネルの一元化、テスト容易性の向上をどう実現できるかを紹介します。
Effect.tryで例外を型付きに受け止める方法、Effect.genで段階的なフローを一本化する書き方、そして将来の拡張を見据えた設計の考え方を5分に凝縮。
新しく始めるTypeScriptプロジェクトでEffectを採用するか判断する際のヒントをお届けします。

https://hokuriku.tskaigi.org/talks/16

Transcript

1. Effect 入門 次の新規開発で役立つ実践指針 TSKaigi Hokuriku fumiya 今日のゴール： 次の新規 TypeScript プロジェクトで Effect を採用するかどうか判断するための材料を持 ち帰っていただく 1
2. 自己紹介 株式会社 tacoms でソフトウェアエンジニアをやっている與野史也です。tacoms は飲食系 の SaaS を作っている会社で外食ラブな私としてはとても楽しい業界です。直近は飲食店の メニューを管理したり配信したりするプロダクトを作ったりしています私の誕生日はジョ ン・レノン，ドン小西，サンシャイン池崎と同じです 出身は大阪で、これまで大阪 → 東 京 → 福岡 → 東京と転々としているような、していないようなことをしています。趣味は映 画、Audible(3.5 倍で聴けます)、飲食店巡り、カラオケ、スノーボード/ボルダリングで す。人生を楽しみたいので多趣味でありたいです。国内、海外旅行も好きで、これまでに行 って一番良かった都道府県は静岡です。青春時代で美化されている可能性はあります。x(旧 Twitter)やってます。fumiyakiです。kiってなんだって話ですが語感が良かったので ki をつ けたのですがそれも被ったので渋々 ki_が混じっています。裏話ですが今日の発表は副業先 の KENCOPA でやっているブラウザを自動で動かす AI エージェント開発で得た知見を元に しています。tacoms でも AI で電話するやつ作ってたりするから是非ブースで TS や AI 周 りについてお話しましょう。 2
3. 今日の流れ 1. よくある初期セットアップ 2. createUserHandler の現在と XXX 日後 3. 目指すべき姿の確認（ createUser & Handler） 4. Effect 概要 5. i. 境界（OAuth / DB）を loadUserContext に集約する 6. ii. ビジネスロジックの分岐を型＋ Effect に分割する 7. Effect を使うことで嬉しい点 8. どんなプロジェクトなら導入効果が出やすいか & どこから導入するか 9. まとめ 3
4. よくある初期セットアップ API クライアント OpenAPI / GraphQL schema からコード生成 バリデーション Zod / Valibot でリクエスト & レスポンスを検証 永続化 ORM で DB アクセスを抽象化 ロギング pino / tslog などで構造化ログ レイヤー設計 Controller → Service → Repository など 4
5. リリース初期の createUserHandler 5
6. XXX 日後の分岐 XXX 日後のテスト 6
7. このセッションで目指す姿： Effect を使って createUser を ユースケース と Handler を分離 7
8. このセッションで目指す姿： Effect を使って createUser を ユースケース と Handler を分離 8
9. Effect を軽く紹介 9
10. Effect を軽く紹介 今日のゴール： ユースケースを Effect.Effect<User, AppError, Requirements> として切り出し Handler で分岐のないフローを作る Effect.provide(LiveLayer) で Requirements を埋めて Effect.matchEffect で HTTP に変換して Effect.runPromise で実行する 10
11. Effect を使ってcreateUser を ユースケース と Handler を分離するために 1. 境界（OAuth / DB）を loadUserContext に集約する 2. ビジネスロジックの分岐を型＋ Effect に分割する 11
12. 1. 境界（OAuth / DB）を loadUserContext に集約 する 12
13. 1. 境界（OAuth / DB）を loadUserContext に集約 する 13
14. 1. 境界（OAuth / DB）を loadUserContext に集約 する 14
15. 2. ビジネスロジックの分岐を型 ＋ Effect に分割 15
16. 2. ビジネスロジックの分岐を型 ＋ Effect に分割 16
17. 2. ビジネスロジックの分岐を型 ＋ Effect に分割 17
18. AppError： このサービスの全てのユースケースで起こ りうる失敗をまとめた型 18
19. After： UserSegment / UserContext / AppError を使った createUser 19
20. Effect を使うことで嬉しい点 ① 「壊れ方」を型で制御 できる Effect<Success, Error, Requirements> Error = AppError にすることで「壊れ方」を型で制御できる createUser の型に反映され： 以下のようなコードが自動的にコンパイルエラーになる： Effect を使うことで AppError にまとまるため、 appErrorToHttp のようなコードを書き やすくなる 変更があった時にコンパイルエラーとして検知できる 20
21. Effect を使うことで嬉しい点 ① 「壊れ方」を型で制御 できる 21
22. Effect を使うことで嬉しい点 ① 「壊れ方」を型で制御 できる 22
23. Effect を使うことで嬉しい点 ① 「壊れ方」を型で制御 できる 23
24. Effect を使うことで嬉しい点 ② テスト単位が「ユース ケース」になっていく 24
25. Effect を使うことで嬉しい点 ② テスト単位が「ユース ケース」になっていく 25
26. Effect を使うことで嬉しい点 ② テスト単位が「ユース ケース」になっていく Before handler 経由でのテストのイメージ After createUser のテスト 「ユースケースは Effect を返す」という形に揃えておくと、HTTP やフレームワーク抜 きで role / plan / isFirstLogin 　によるビジネスロジックのフローだけ のテストが書き やすい。 26
27. どんなプロジェクトなら導入効果が出やすいか？ 導入効果が出やすい ビジネスルールの分岐が多い ロール / プラン / 初回オンボーディング / フラグ / スコア など 外部サービスとの境界が多い REST / GraphQL / DB / OAuth / LLM / キュー / 通知 など 長期運用前提で、仕様変更が定期的に入る 27
28. どんなプロジェクトなら導入効果が出やすいか？ 導入効果が出づらい 単純な CRUD 中心の小さなツール 数週間で捨てる PoC 抽象化や型に十分な時間を割けない 28
29. どんなプロジェクトなら導入効果が出やすいか？ Effect の導入で増えるもの / 減るもの 増えるもの： Effect の抽象、学習コスト、設計コスト 減るもの： handler の if/else が肥大化したコード 境界と分岐が混在したサービス層 テストでモックと例外ハンドリングを毎回書くコスト 29
30. どこから導入すれば良いか？ 1. Effect を導入するユースケースを決める ビジネスルールが複雑 / 外部サービスが多め なエンドポイント 「単純な CRUD の一覧 / 詳細」などは Promise ベースでもよい 30
31. どこから導入すれば良いか？ 2. Effect ベースの設計をする i. loadXxxContext を作る REST / DB / OAuth などの境界処理や、Zod / JSON.parse を 1 つの Effect に集約 ii. XxxSegment 型 + runSegmentEffect を導入 role / plan / isFirstLogin などのビジネスロジックの分岐を「分類」と「処 理」に分ける iii. ユースケース本体 ( createUser など) は Effect.Effect<Success, AppError, Requirements> を返す関数にする 31
32. どこから導入すれば良いか？ 3. それ以外のユースケースは、必要になったところから同じパターンに揃えていく まずは create 系など「if が増えそうなところ」だけ Effect 化 うまく回り始めたら、 共通の AppError Requirements / Layer loadXxxContext / XxxSegment の書き方 をリポジトリ全体のルールとして整理していく 32
33. どこから導入すれば良いか？ 新規開発の最初の数日で「1 ユースケース分の型付きパターン」を作っておくと、 あとは同じ型に乗せていくだけになるので、チームとしても導入しやすくなります。 33
34. まとめ 初期リリースでは plan だけのシンプルな createUserHandler でも、半年後には role / isFirstLogin の仕様追加で handler が肥大化しがち Effect を使うと： A: 境界（OAuth / DB）を loadUserContext のような 1 本の Effect に集約できる B: 分岐の意味を UserSegment + runSegmentEffect に引き上げられる ユースケースは Effect.Effect<User, AppError, Requirements> という形で「成功」 「失敗」 「依存」が型に現れる 34
35. まとめ 採用判断の観点では： 分岐と外部サービスが多く、長期運用なプロジェクトなら特におすすめ とりあえず「1 つのユースケース」で境界の分離・集約、ビジネスロジックの整理から 始める 35
36. おまけ(AGENTS.md / CLAUDE.md) 36