cats-effect-io

Cats Effect IO (Scala)

Quick start

• Treat every side effect as an effect value: return IO[A], SyncIO[A], or F[A] with F[_]: Sync/Async/Temporal as needed.
• Wrap Java blocking calls with IO.blocking or IO.interruptible (or Sync[F].blocking/interruptible).
• Use Resource to acquire/​release resources and IOApp for program entry points.
• Prefer structured concurrency (parTraverse, parMapN, background, Supervisor) over manual fiber management.
• Read references/​cats-effect-io.md for concepts, recipes, and FAQ guidance.
• For deeper Resource guidance, use the cats-effect-resource skill (install: npx skills add https://github.com/alexandru/skills --skill cats-effect-resource).

Workflow

1. Classify side effects and choose the effect type: IO directly or polymorphic F[_] with the smallest required Cats Effect typeclass (Sync, Async, Temporal, Concurrent).
2. Wrap side-effectful code using IO(...), IO.blocking, IO.interruptible, or IO.async (or their Sync/Async equivalents).
3. Manage resources with Resource or bracket and keep acquisition/​release inside effects.
4. Compose effects with flatMap/​for-comprehensions and collection combinators (traverse, parTraverse).
5. Use concurrency primitives (Ref, Deferred, Queue, Semaphore, Supervisor) and structured concurrency to avoid fiber leaks.

Side-effect rules (apply to IO, SyncIO, and to F[_]: Sync/​Async)

• All side-effectful functions must return results wrapped in IO (or F[_] with Cats Effect typeclasses).
• Side-effects include all non-determinism (call sites are not referentially transparent):
  • Any I/​O (files, sockets, console, databases).
  • Instant.now(), Random.nextInt().
  • Any read from shared mutable state (the read itself is the side effect).
  • Returning mutable data structures (for example, Array[Int]).

Blocking I/​O rules

• Java blocking methods must be wrapped in IO.blocking or IO.interruptible (or Sync[F].blocking/interruptible) so they run on the blocking pool.
• Prefer IO.interruptible for methods that may throw InterruptedException or IOException, but not for resource disposal.
• Use IO.blocking for cleanup/​disposal (Closeable#close, AutoCloseable#close).

Output expectations

• Make side effects explicit in signatures (IO/SyncIO or F[_]: Sync/​Async); the guidance here applies equally to concrete IO and polymorphic F[_].
• Use the smallest typeclass constraint that supports the needed operations.
• Keep effects as values; do not execute effects in constructors or top-level vals.

References

• Load references/​cats-effect-io.md for documentation summary and patterns.
• For concrete samples, read references/​cats-effect-io.md.
• Use the cats-effect-resource skill for Resource-specific workflows and patterns (install: npx skills add https://github.com/alexandru/skills --skill cats-effect-resource).