Publicize Free#foldStep

[djspiewak]

Due to the fact that the algebra itself is private, it is not currently possible to implement custom interpreters on top of Free. A first-order analogue for this limitation would be as if the only way to look at List was foldLeft: it's great, and technically can do anything, but it's immensely difficult to do things that are more complicated than a simple traversal. For example, imagine I want to convert a List[A] into a List[(A, A)] such that all adjacent even/odd values are paired together (i.e. index 0 with index 2, 1 with 3 and so on). Doing this with a foldLeft is possible, but hard (well, at least annoying). The analogous transformation on Free is exponentially more difficult with foldMap, and also impossible to type check (due to the existentials involved).

foldStep breaks down this restriction by giving safe, direct access to the internals of the data structure, enabling much more complex interpreters than what are currently possible with foldMap alone. My current practical example of this need comes from the ongoing Cats Effect 3 development, where I have implemented an interpreter which has cooperative parallelism semantics for Free, yielding at each suspension point, making it possible to write fully pure Fiber implementations which still exhibit parallel semantics.

[codecov-io]

Codecov Report

Merging #3225 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #3225   +/-   ##
=======================================
  Coverage   93.05%   93.05%           
=======================================
  Files         376      376           
  Lines        7412     7412           
  Branches      200      192    -8     
=======================================
  Hits         6897     6897           
  Misses        515      515

Flag	Coverage Δ
#scala_version_212	93.36% <ø> (-0.02%)	⬇️
#scala_version_213	92.82% <ø> (ø)	⬆️

Impacted Files	Coverage Δ
free/src/main/scala/cats/free/Free.scala	92.1% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 424f10a...e814bf7. Read the comment docs.

[travisbrown]

This seems reasonable to me.