Cats Effect 3 の型クラスチートシート

Cats の チートシートの Cats Effect 3 版を作った。

## はじめに
Scala の 関数型プログラミングに慣れると、生のメソッドのシグネーチャより一段高い抽象度で型を考えたいことがある[^10]。そのために Cats では [Glossary](https://typelevel.org/cats/nomenclature.html)（または [Cheatsheet](https://arosien.github.io/cats-cheatsheets/typeclasses.pdf)）が利用されてきた。

こんな感じ。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/9633/472c630e-89b6-0551-3e08-d901f58c1b3c.png)

個人的にはすでに cats-free, cats-mtl, cats-effect 2.x, atnos-eff のチートシートを作って普段から使っていたが、ここでは新たに cats-effect 3 版を作る。

### 方針
- 高い抽象度で一望・比較するためにあえて詳細を省いて、曖昧さもある程度許容している。
- 基本的にオリジナルのスタイルを踏襲しつつ、さらに略記して見た目を簡潔にしている。
- 概念の意味や各メソッドの用法の解説はしていない。
- すべてのメソッドを載せるような網羅性にもこだわらない。

### 略記法

- 1: Unit
- 2: Boolean
- n: Int
- X?: Option[X]
- X*: List[X]
- F[X]: FX[^8]
- X×Y: (X, Y)
- X＋Y: Either[X, Y]
- ⤳ : FunctionK
- e: Throwable
- fd: FiniteDuration
- その他、必要に応じて各型クラスに個別に注釈した。

## チートシート
※ syntax として提供されてる関数と型クラスインスタンス本体のメソッドで、シグネーチャが微妙に違うことがある[^9]。その場合 syntax を優先した。

### MonadCancel
安全なリソース管理[^7]。2.x の [Bracket](https://typelevel.org/cats-effect/api/2.x/cats/effect/Bracket.html) に相当。MonadError[^3] から派生。
|type	  |method	  |memo  |
|---|---|---|
|FA → FB → FB|forceR|!> とも書ける|
|FA → FA|uncancelable||
|FA → F1 → FA|onCancel||
|FA → (A→FB) → (A→F1) → FB|bracket||
|FA → (A→FB) → (A×ocB→F1) → FB|bracketCase||
|FA → F1 → FA|guarantee||
|FA → (ocA→F1) → FA|guaranteeCase||

ocX: Outcome[F,E,X] ... 2.x の ExitCase 相当。結果を表現。
[Documentation](https://typelevel.org/cats-effect/docs/typeclasses/monadcancel)、[Scaladoc](https://typelevel.org/cats-effect/api/3.x/cats/effect/kernel/MonadCancel.html)

### Unique
JVM 内ユニークなトークンを提供する型クラス。Spawn と Sync がこれを継承。
|type	  |method	  |memo  |
|---|---|---|
|F[Token]|unique||

[Documentation](https://typelevel.org/cats-effect/docs/typeclasses/unique)、[Scaladoc](https://typelevel.org/cats-effect/api/3.x/cats/effect/kernel/Unique.html)

### Spawn [^1]
Fiber[^4] 生成の型クラス。MonadCancel と Unique を継承。2.x の [Concurrent](https://typelevel.org/cats-effect/api/2.x/cats/effect/Concurrent.html) の一部を引き継いでいる。
|type	  |method	  |memo  |
|---|---|---|
|F1|cede|2.x の Async.shift|
|FA|never||
|FA → F[fbA]|start||
|FA → rs[ocA]|background|rs[X]: Resource[F,FX]|
|FA → FB → F[A+B]|race||
|FA → FB → F[ocA + ocB]|raceOutcome||
|FA → FB → F[ocA×fbB + fbA×ocB]|racePair||
|FA → FB → F[A×B]|both||
|FA → FB → F[ocA × ocB]|bothOutcome||

fbX: Fiber[F, E, X]
ocX: Outcome[F,E,X]

[Documentation](https://typelevel.org/cats-effect/docs/typeclasses/spawn)、[Scaladoc](https://typelevel.org/cats-effect/api/3.x/cats/effect/kernel/GenSpawn.html)

### Concurrent
Ref[^5] と Defered[^6] を扱う型クラス。Spawn を継承。2.x の Concurrent に相当するが、多くのメソッドが他の型クラスに移動してスリムになっている。
|type	  |method	  |memo  |
|---|---|---|
|A → F[rfA]|ref|rfX: Ref[F, X]|
|F[dfA]|deferred|dfX: Deferred[F, X]|
|FA → FFA|memoize||
|n → m → FA → F[A*] |parReplicateAN|n はパラレル数, m は複製するAの数|
|n → TA → (A→FB) → FTB|parTraverseN|T は Traverse|
|n → TFA → FTA|parSequenceN||

[Documentation](https://typelevel.org/cats-effect/docs/typeclasses/concurrent)、[Scaladoc](https://typelevel.org/cats-effect/api/3.x/cats/effect/kernel/GenConcurrent.html)

### Clock
エフェクトフルな単調増加時間 / システム時間。2.x の Clock に相当。Sync と Temporal がこれを継承。
|type	  |method	  |memo  |
|---|---|---|
|F[fd]|monotonic||
|F[fd]|realTime||
|FA → F[fd × A]|timed|fd はかかった時間|

[Documentation](https://typelevel.org/cats-effect/docs/typeclasses/clock)、[Scaladoc](https://typelevel.org/cats-effect/api/3.x/cats/effect/kernel/Clock.html)

### Temporal
Fiber のサスペンドとタイムアウトを扱う型クラス。Concurrent と Clock を継承。2.x の Concurrent、Timer あたり。
|type	  |method	  |memo  |
|---|---|---|
|fd → F1|sleep||
|FA → fd → FA|delayBy||
|FA → fd → FA|andWait||
|FA → fd → FA → FA|timeoutTo|フォールバック指定可能|
|FA → fd → FA|timeout||
|FA → fd → FA|timeoutAndForget||

[Documentation](https://typelevel.org/cats-effect/docs/typeclasses/temporal)、[Scaladoc](https://typelevel.org/cats-effect/api/3.x/cats/effect/kernel/GenTemporal.html) 

### Sync
同期FFI[^2] を扱う型クラス。Defer[^3], Clock, Unique, MonadCancel を継承。2.x の [Sync](https://typelevel.org/cats-effect/api/2.x/cats/effect/Sync.html) と [Blocker](https://typelevel.org/cats-effect/api/2.x/cats/effect/Blocker.html) あたり。
|type	  |method	  |memo  |
|---|---|---|
|A → FA|delay||
|A → FA|blocking||
|A → FA|interruptible||
|A → FA|interruptibleMany||
|Sync.Type → A → FA|suspend|Type が delay 以下 4タイプに対応|
|FA → FA|defer||

[Documentation](https://typelevel.org/cats-effect/docs/typeclasses/sync)、[Scaladoc](https://typelevel.org/cats-effect/api/3.x/cats/effect/kernel/Sync.html)

### Async
非同期FFI を扱う型クラス。Temporal, Sync を継承。
|type	  |method	  |memo  |
|---|---|---|
|(e+A → 1) → F[F1?] → FA|async||
|(e+A → 1) → 1 → FA|async_||
|FA → ec → FA|evalOn|ec: ExecusionContext|
|ec → FA → (F⤳F)|evalOnK||
|FA → ec → F[fbA]|startOn|fbX: Fiber[F, Throwable, X]|
|FA → ec → rs[ocA]|backgroundOn||
|F[ec]|executionContext||
|F[ftA] → FA|fromFuture|ftA: Future[A]|

rs[X]: Resource[F,FX]
ocX: Outcome[F, Throwable, X]

[Documentation](https://typelevel.org/cats-effect/docs/typeclasses/async)、[Scaladoc](https://typelevel.org/cats-effect/api/3.x/cats/effect/kernel/Async.html)

### 参考
- [Cats Effect の７つの型クラス](https://qiita.com/yasuabe2613/items/855fa0ad0d500e39849e)
- [Cats Glossary (cheatsheet)](https://typelevel.org/cats/nomenclature.html)

[^1]: 伝統的にプロセスを生成する関数が *spawn* と呼ばれてきたが、この spawn は `Fiber` を産み出す。
[^2]: ここで言う *FFI* は、文字通りの外部言語とのI/Fというより、副作用のある inpure 界と参照透過な pure 界のI/Fといった意味（[参照](https://github.com/slouc/concurrency-in-scala-with-ce#asynchronous-methods-ffi)）
[^3]: MonadError と Defer は Cats 本体の型クラス。
[^4]: Fiber: [概念](https://typelevel.org/cats-effect/docs/concepts#fibers)、[API doc](https://typelevel.org/cats-effect/api/3.x/cats/effect/kernel/Fiber.html), 
[^5]: Ref: [概念](https://typelevel.org/cats-effect/docs/std/ref)、[API doc](https://typelevel.org/cats-effect/api/3.x/cats/effect/kernel/Ref.html)
[^6]: Defered: [概念](https://typelevel.org/cats-effect/docs/std/deferred)、[API doc](https://typelevel.org/cats-effect/api/3.x/cats/effect/kernel/Deferred.html)
[^7]: 昔ながらのローンパターンのような感じ
[^8]: ［］を省略するとわかりにくい場合は残した
[^9]: たとえば MonadCancel#uncancelable で Poll を渡すかどうかの違いなど。
[^10]: この逆も言えると思う。