Free Monads Sample

[JorgeCastilloPrz]

Free Monads Sample

Fixes #7

Motivations

The only purpose of using Free is to be able to model your app / system logic in an abstract way depending on Free instead of concrete types, and provide semantics (real effect-causing implementations) to it through an interpreter later on, the moment you want to run it.

The abstract execution tree that you created declaratively based on Free is called AST (Abstract syntax tree), and it is unfolded step by step by Free using an interpreter to provide semantics to each one of the steps (operations).

This allows you to decouple contracts from implementations and be able to swap side effect implementations by fakes at testing time easily. You would just need to provide a different interpreter which does not include real side effects.

More concise definition extracted from Functional and Reactive Domain Modeling book:

"The interpreter provides the denotation to each of the elements of algebra that your free monad has recursively built within your composed DSL. And the interpretation may also include side effects."

How to go Free with KΛTEGORY

KΛTEGORY enables Free and effects like IO or Async related effects to help us on this matter. The process of modeling a complete system or just a part of it using Free is composed of 4 different steps:

1. Define your algebra of operations: You need to declare the operations that you want to model on your system / layer where you are implementing Free. It is an algebraic data type (ADT) that I am declaring using a Kotlin sealed class. The algebra declares a constrained amount of operations that will be available and composable just in case you need to create more complex ones.

   This is an example of an Algebra, where each one of the types on the sealed hierarchy represents an atomic operation:

   @higherkind sealed class HeroesAlgebra<A> : HeroesAlgebraKind<A> {
       object GetAll : HeroesAlgebra<List<CharacterDto>>()
       class GetSingle(val heroId: String) : HeroesAlgebra<CharacterDto>()
       class HandlePresentationEffects(val result: Either<CharacterError, List<CharacterDto>>) : 
   HeroesAlgebra<Unit>()
       class Attempt<A>(val fa: FreeHeroesAlgebra<A>): HeroesAlgebra<Either<Throwable, A>>()
       companion object : FreeMonadInstance<HeroesAlgebraHK>
   }

   We have a closed hierarchy of ops available here. Each one has it's particular return type
   depending on what's gonna do. So GetAll is an algebra of List<CharacterDto> because it's
   potentially returning a list of characters. Another example: HandlePresentationEffects would
   represent the operation causing effects to render use case results on screen (which would be
   equivalent to presentation logic) so, since it is representing a side effect by itself, it needs to return Unit.

2. Lift everything to the context of Free: We need to lift each one of the algebra ops to the context of Free to be able to compose our app AST using those. This is how I am doing it:

   fun getAllHeroes(): FreeHeroesAlgebra<List<CharacterDto>> =
           Free.liftF(HeroesAlgebra.GetAll)
   
   fun getSingleHero(heroId: String): FreeHeroesAlgebra<CharacterDto> =
           Free.liftF(HeroesAlgebra.GetSingle(heroId))
   
   fun handlePresentationEffects(result: Either<CharacterError, List<CharacterDto>>): 
   FreeHeroesAlgebra<Unit> =
           Free.liftF(HeroesAlgebra.HandlePresentationEffects(result))
   
   fun <A> attempt(fa: FreeHeroesAlgebra<A>): FreeHeroesAlgebra<Either<Throwable, A>> =
           Free.liftF(HeroesAlgebra.Attempt(fa))

   As you can see, I am just providing handful utility pure functions to lift each operation to Free. Now we can start using those in our app to concatenate code through different layers and compose the whole AST.

3. Provide semantics with the Interpreter: Once you have your whole AST depending on Free and never on concrete types, we need to create a interpreter to provide those details.
   This is my interpreter:

   fun <F> interpreter(ctx: SuperHeroesContext, ME: MonadError<F, Throwable>,
       AC: AsyncContext<F>): FunctionK<HeroesAlgebraHK, F> =
       object : FunctionK<HeroesAlgebraHK, F> {
         override fun <A> invoke(fa: HeroesAlgebraKind<A>): HK<F, A> {
           val op = fa.ev()
           return when (op) {
             is HeroesAlgebra.GetAll -> getAllHeroesImpl(ctx, ME, AC)
             is HeroesAlgebra.GetSingle -> getHeroDetailsImpl(ctx, ME, AC, op.heroId)
             is HeroesAlgebra.HandlePresentationEffects -> {
               ME.catch({ handlePresentationEffectsImpl(ctx, op.result) })
             }
             is HeroesAlgebra.Attempt<*> -> {
               val result = op.fa.foldMap(interpreter(ctx, ME, AC), ME)
               ME.attempt(result)
             }
           } as HK<F, A>
         }
       }
   
   private fun <F, A, B> runInAsyncContext(
       f: () -> A,
       onError: (Throwable) -> B,
       onSuccess: (A) -> B,
       AC: AsyncContext<F>): HK<F, B> {
     return AC.runAsync { proc ->
       async(CommonPool) {
         val result = Try { f() }.fold(onError, onSuccess)
         proc(result.right())
       }
     }
   }
   
   fun <F> getAllHeroesImpl(
       ctx: SuperHeroesContext,
       ME: MonadError<F, Throwable>,
       AC: AsyncContext<F>): HK<F, List<CharacterDto>> {
     return ME.bindingE {
       val query = Builder.create().withOffset(0).withLimit(50).build()
       runInAsyncContext(
           f = { ctx.apiClient.getAll(query).response.characters.toList() },
           onError = { ME.raiseError<List<CharacterDto>>(it) },
           onSuccess = { ME.pure(it) },
           AC = AC
       ).bind()
     }
   }
   
   fun <F> getHeroDetailsImpl(
       ctx: SuperHeroesContext,
       ME: MonadError<F, Throwable>,
       AC: AsyncContext<F>,
       heroId: String): HK<F, CharacterDto> =
       ME.bindingE {
         runInAsyncContext(
             f = { ctx.apiClient.getCharacter(heroId).response },
             onError = { ME.raiseError<CharacterDto>(it) },
             onSuccess = { ME.pure(it) },
             AC = AC
         ).bind()
       }
   
   fun handlePresentationEffectsImpl(
       ctx: SuperHeroesContext,
       result: Either<CharacterError, List<CharacterDto>>): Unit =
       when (result) {
         is Left -> {
           displayErrors(ctx, result.a); }
         is Right -> when (ctx) {
           is GetHeroesContext -> ctx.view.drawHeroes(result.b.map {
             SuperHeroViewModel(
                 it.id,
                 it.name,
                 it.thumbnail.getImageUrl(MarvelImage.Size.PORTRAIT_UNCANNY),
                 it.description)
       })
           is GetHeroDetailsContext -> ctx.view.drawHero(result.b.map {
             SuperHeroViewModel(
                 it.id,
                 it.name,
                 it.thumbnail.getImageUrl(MarvelImage.Size.PORTRAIT_UNCANNY),
                 it.description)
           }[0])
         }
       }
   
   fun displayErrors(ctx: SuperHeroesContext, c: CharacterError): Unit {
     when (c) {
       is NotFoundError -> ctx.view.showNotFoundError()
       is UnknownServerError -> ctx.view.showGenericError()
       is AuthenticationError -> ctx.view.showAuthenticationError()
     }
   }

   So the main point of interest here is the interpreter() function, which is providing an
   interpreter to use to resolve each one of the steps on the AST when the user decides to "unfold" it.
   It's just a simple when statement matching over the operation type and running the required
   effects in response by using the chosen monad instance.
   So literally, the interpreter here is in charge of providing all the implementation details / side
   effects that we wanted to abstract.

   The key point about which parts of your system should be declared as operations in the
   algebra and therefore abstracted using Free, is whether you need to replace those
   implementations at runtime or at testing time. This was my baseline thought used when
   implementing this sample.

   After all, Free is just a way of decoupling system declarations from implementation details
   used to run them.

4. Unfold the AST using the interpreter: Finally you would just need to run the system passing in the interpreter to be used to provide semantics, and the monad implementation that you are chosing to do all the work inside of it.

   getSuperHeroes().unsafePerformEffects(GetHeroesContext(this, this))
   
   fun <A> FreeHeroesAlgebra<A>.unsafePerformEffects(ctx: SuperHeroesContext): Unit {
     val ME = IO.monadError()
     val result: IO<A> = this.foldMap(interpreter(ctx, ME, IO.asyncContext()), ME).ev()
   }

   The getSuperHeroes() function is just the beginning of the AST and it's gonna return a composed Free based tree. On this example I am chosing to use an instance of MonadError to foldMap the AST and use it on the interpreter provided on step 3. Now Free is able to run the whole chain since it has been provided implementation details (interpreter) and a monad instance to use to resolve those.

So cheers, there we have our Free Monads sample over Android! 🎉

Recommended bibliography

• FP for the Average Joe III - 47deg
• Free Monoids and Free Monads by Rúnar Bjarnason
• Function and Reactive Domain Modeling book

[JorgeCastilloPrz]

Thanks @raulraja for helping on understanding and polishing some details on this. You always become very helpful 👏 .

[raulraja]

👏

[raulraja]

Free<S, A> where S is your algebra

[raulraja]

resolve all effects / perform execution of effects in a controlled context

[raulraja]

rationale