Doc Request: Write up what patterns were used and why
monksy opened this issue · 9 comments
This is a documentation request that there should be more documentation about how and why the project is structured as it is. I.e. Why is the PetService broken up into an algebra and what tagless is.
Thanks for the prompt, I have really been meaning to do this. I think I can start with at least a smaller / simpler overview and go from there. I tend to want to want to write a lot of documentation, then in my head it becomes this big TODO, and I push it off with the normal excuses because it feels big.
As far as tagless (tagless final or finally tagless), it is a mechanism to separate abstraction from implementation, while supporting extensibility of an embedded language (DSL).
The term "Algebra" defines a set of types and the operations / functions on those types. The Algebra is realized through an Interpreter which binds the Algebra to some implementation (like using doobie vs. Scalike vs. Slick).
From an OO perspective, the Algebra is the interface and the Interpreter is the Impl / concrete type. There is more to it than that but that helps cross the bridge (maybe?). I also think that tagless final is more relatable than something like the Free Monad.
I learned a lot on tagless final from the paper, but also Luka Jacobowitz has given it really good treatment in his talks (https://www.youtube.com/watch?v=1h11efA4k8E)
Is there any way we can break this up into smaller pieces?
I see this project as a way to show off what you can do with FP coming from a java world.
I would really like this as well :), but to be honest, for now, I wouldn't need to go as far as understunding tagless final. To me, as a beginner in "Functional Scala", I even have a hard time understanding why we're using fs2 right in the Server.scala file.
There's a couple of little things like this. For instance, another one is: why HTTP4S and not, for instance, Akka HTTP? Is it because it is hard to marshall a "generic F" in Akka HTTP and easier in HTTP4S? This is just an example :)
Other than that, thanks for good work Paul!
@fwlega I used HTTP4s mostly because I didn't have experience with it, and at the time I was trying to learn the emerging "typelevel stack" (I am sure some people just cringed).
HTTP4s does allow you to be lazy on the effect type all the way to boot up, which is actually really nice.
With Akka HTTP (afaik) in your routes you need to do ioThing.unsafeToFuture() which I am not happy with. Seeing unsafeXXX anywhere doesn't sit well with me.
@monksy curious what smaller pieces would look like. The motivation for this project is so you can see FP patterns / principles in practice in a pseudo-real application. The design of the pet store intentionally follows patterns you see coming out of domain driven design / onion-architecture (which I hope is familiar to OO devs, it is somewhat subjective based on my experience).
Part of the reason I built it was we would see examples of using the Free Monad, but they were entirely inapplicable to people like me trying to build an actual application. I always had questions like "how much of my system is written using Free and how much of it is not".
Open to ideas for sure. Just wanted to convey a little of the background for the project. Seeing all these libraries, patterns, and techniques (like scalacheck) in one application is what I was striving for.
@monksy also, you want to work together on an outline? There was similar interest from others a few months back that didn't get any traction.
Doesn't have to be anything super formal. I can hang up an issue and propose an outline, then we can iterate a little till it captures what others are looking for. After that, I can write up parts (but would be happy for others to contribute as well).
@monksy I added some content to the README, if you have time, curious what your thoughts are and what else I could add. I wanted to try and capture the high-level ideas here first.
My goal is to still fill out the documentation at somepoint, where all of these topics would get much more attention
That looks good!