effectful-core
An easy to use, performant extensible effects library.
| LTS Haskell 24.16: | 2.6.1.0 |
| Stackage Nightly 2025-10-24: | 2.6.1.0 |
| Latest on Hackage: | 2.6.1.0 |
effectful-core-2.6.1.0@sha256:329f7bd7319217b668ca00331b31f683af93ba18423462918217b2becec3d6f0,4359Module documentation for 2.6.1.0
- Effectful
- Effectful.Dispatch
- Effectful.Error
- Effectful.Exception
- Effectful.Fail
- Effectful.Internal
- Effectful.Labeled
- Effectful.NonDet
- Effectful.Prim
- Effectful.Provider
- Effectful.Reader
- Effectful.State
- Effectful.State.Dynamic
- Effectful.State.Static
- Effectful.Writer
- Effectful.Writer.Dynamic
- Effectful.Writer.Static
effectful
An easy to use, fast extensible effects library with seamless integration with the existing Haskell ecosystem.
Main features:
-
Very fast (benchmarks).
-
Easy to use API (comparable with usage of the MonadUnliftIO class).
-
Correct semantics in presence of runtime exceptions (no more discarded state updates).
-
Seamless integration with the existing ecosystem (
exceptions,monad-control,unliftio-core,resourcetetc.). -
Support for thread local and shared state (e.g.
StateTprovides a thread local state, whileMVarholds a shared state, both approaches have their merits). -
Support for statically (implementation determined at compile time) and dynamically (implementation determined at run time) dispatched effects.
Motivation
Do we really need yet another library for handling effects? There’s freer-simple, fused-effects, polysemy, eff and probably a few more.
It needs to be noted that of all of them only the work-in-progress eff library
is a promising proposition because of reasonable performance characteristics
(see the talk Effects for Less
for more information) and potential for good interoperability with the existing
ecosystem.
The second point is arguably the most important, because it allows focusing on things that matter instead of reinventing all kinds of wheels, hence being a necessary condition for broader adoption of the library.
Unfortunately, the development of eff has stalled due to a
few
subtle
issues related to its use of
delimited continuations underneath.
What about mtl?
It’s true that its “effects as classes” approach is widely known and used often.
However:
-
mtlstyle effects are slow. -
The majority of popular monad transformers (except
ReaderT) used for effect implementations are rife with subtle issues.
These are problematic enough that the ReaderT design pattern was invented. Its fundamentals are solid, but it’s not an effect system.
A solution? Use the ReaderT pattern as a base and build around it to make an
extensible effects library! This is where effectful comes in. The Eff monad
it uses is essentially a ReaderT over IO on steroids, allowing us to extend
its environment with data types representing effects.
This concept is quite simple, so:
-
It’s reasonably easy to understand what is going on under the hood.
-
The
Effmonad being a reader allows for seamless interoperability with ubiquitous classes such asMonadBaseControlandMonadUnliftIOand solves issues of monad transformers mentioned above.
What is more, the Eff monad is concrete, so GHC has many possibilities for
optimization, which results in a very fast code at a default optimization
level. There is no need to explicitly mark functions with INLINE pragmas or
enable additional optimization passes, it just works.
Any downsides?
As always, there’s no free lunch. The Eff monad doesn’t support effect
handlers that require the ability to suspend or capture the rest of the
computation and resume it later (potentially multiple times). This prevents
effectful from providing (in particular):
-
A
NonDeteffect handler that executes multipleAlternativebranches and collects their results. -
A
Coroutineeffect.
It needs to be noted however that such NonDet effect handler in existing
libraries is
broken
and none of the ones with support for higher order effects provide the
Coroutine effect, so arguably it’s not a big loss.
If you need such capability in your application, there are well established
libraries such as conduit or
list-t that can be used with
effectful without any hassle.
Summary
effectful is an extensible effects library that aims to be the replacement
for:
-
The bare
ReaderTpattern by being essentially its enriched version. -
Monad transformer stacks typically encountered in the wild (i.e. consisting of a dozen of newtype’d
ExceptT,ReaderT,StateTandWriterTtransformers and their derivatives) by providing equivalent effects with improved semantics, performance, usability and making it easy to reuse them for your own effects.
It doesn’t try to make monad transformers obsolete, so you’re free to
use it with ConduitT, ContT, ListT etc. when necessary.
Package structure
The library is split among several packages:
-
The
effectful-corepackage contains the core of the library along with basic effects. It aims for a small dependency footprint and provides building blocks for more advanced effects. -
The
effectful-pluginpackage provides an optional GHC plugin for improving disambiguation of effects (see here for more information). -
The
effectful-thpackage provides utilities for generating bits of effect-related boilerplate via Template Haskell. -
The
effectfulpackage re-exports public modules ofeffectful-coreand additionally provides most features of theunliftiopackage divided into appropriate effects.
Examples
For the examples see the Introduction sections of
Effectful.Dispatch.Dynamic
and
Effectful.Dispatch.Static
(when in doubt, start with dynamic dispatch).
Acknowledgements
To all contributors of existing effect libraries - thank you for putting the
time and effort to explore the space. In particular, conversations in issue
trackers of cleff, eff, freer-simple, fused-effects and polysemy
repositories were invaluable in helping me discover and understand challenges in
the space.
Resources
Resources that inspired the rise of this library and had a lot of impact on its design.
Talks:
-
Effects for Less by Alexis King.
-
Monad Transformer State by Michael Snoyman.
Blog posts:
-
ReaderT design pattern by Michael Snoyman.
-
Exceptions Best Practices by Michael Snoyman.