polysemy: Higher-order, low-boilerplate, zero-cost free monads.

[ bsd3, language, library ] [ Propose Tags ]
This version is deprecated.
Versions [RSS],,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, (info)
Change log ChangeLog.md
Dependencies base (>=4.7 && <5), mtl (>=2.2.2 && <2.3), random (>=1.1 && <1.2), syb (>=0.7 && <0.8), template-haskell (>= && <2.15), transformers (>= && <0.6) [details]
License BSD-3-Clause
Copyright 2019 Sandy Maguire
Author Sandy Maguire
Maintainer sandy@sandymaguire.me
Category Language
Home page https://github.com/isovector/polysemy#readme
Bug tracker https://github.com/isovector/polysemy/issues
Source repo head: git clone https://github.com/isovector/polysemy
Uploaded by isovector at 2019-04-10T20:28:42Z
Distributions Arch:, LTSHaskell:, NixOS:, Stackage:
Reverse Dependencies 76 direct, 4 indirect [details]
Downloads 18476 total (189 in the last 30 days)
Rating 2.75 (votes: 9) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for polysemy-

[back to package description]


Build Status Hackage


The word 'good' has many meanings. For example, if a man were to shoot his grandmother at a range of five hundred yards, I should call him a good shot, but not necessarily a good man.

Gilbert K. Chesterton


polysemy is a library for writing high-power, low-boilerplate, zero-cost, domain specific languages. It allows you to separate your business logic from your implementation details. And in doing so, polysemy lets you turn your implementation code into reusable library code.

It's like mtl but composes better, requires less boilerplate, and avoids the O(n^2) instances problem.

It's like freer-simple but more powerful and 700x faster.

It's like fused-effects but with an order of magnitude less boilerplate.


  • Effects are higher-order, meaning it's trivial to write bracket and local as first-class effects.
  • Effects are low-boilerplate, meaning you can create new effects in a single-digit number of lines. New interpreters are nothing but functions and pattern matching.
  • Effects are zero-cost, meaning that GHC1 can optimize away the entire abstraction at compile time.

1: Unfortunately this is not true in GHC 8.6.3, but will be true as soon as my patch lands.


Console effect:

{-# LANGAUGE TemplateHaskell #-}

import Polysemy

data Console m a where
  GetLine :: Console m String
  PutLine :: String -> Console m ()

makeSemantic ''Console

runConsoleIO :: Member (Lift IO) r => Semantic (Console ': r) a -> Semantic r a
runConsoleIO = interpret $ \case
  GetLine     -> sendM getLine
  PutLine msg -> sendM $ putStrLn msg

Resource effect:

{-# LANGUAGE TemplateHaskell #-}

import qualified Control.Exception as X
import           Polysemy

data Resource m a where
  Bracket :: m a -> (a -> m ()) -> (a -> m b) -> Resource m b

makeSemantic ''Resource

    :: forall r a
     . Member (Lift IO) r
    => (∀ x. Semantic r x -> IO x)
    -> Semantic (Resource ': r) a
    -> Semantic r a
runResource finish = interpretH $ \case
  Bracket alloc dealloc use -> do
    a <- runT  alloc
    d <- bindT dealloc
    u <- bindT use

    let runIt :: Semantic (Resource ': r) x -> IO x
        runIt = finish .@ runResource

    sendM $ X.bracket (runIt a) (runIt . d) (runIt . u)


Friendly Error Messages

Free monad libraries aren't well known for their ease-of-use. But following in the shoes of freer-simple, polysemy takes a serious stance on providing helpful error messages.

For example, the library exposes both the interpret and interpretH combinators. If you use the wrong one, the library's got your back:

    :: forall r a
     . Member (Lift IO) r
    => (∀ x. Semantic r x -> IO x)
    -> Semantic (Resource ': r) a
    -> Semantic r a
runResource finish = interpret $ \case

makes the helpful suggestion:

    • 'Resource' is higher-order, but 'interpret' can help only
      with first-order effects.
        use 'interpretH' instead.
    • In the expression:
          $ \case

Likewise it will give you tips on what to do if you forget a TypeApplication or forget to handle an effect.

Don't like helpful errors? That's OK too --- just flip the error-messages flag and enjoy the raw, unadulterated fury of the typesystem.

Necessary Language Extensions

You're going to want to stick all of this into your package.yaml file.

  ghc-options: -O2 -flate-specialise -fspecialise-aggressively
    - DataKinds
    - FlexibleContexts
    - GADTs
    - LambdaCase
    - PolyKinds
    - RankNTypes
    - ScopedTypeVariables
    - TypeApplications
    - TypeOperators
    - TypeFamilies