{"id":13687007,"url":"https://github.com/haskell-effectful/effectful","last_synced_at":"2025-10-19T19:46:42.167Z","repository":{"id":42687397,"uuid":"376006550","full_name":"haskell-effectful/effectful","owner":"haskell-effectful","description":"An easy to use, fast extensible effects library with seamless integration with the existing Haskell ecosystem.","archived":false,"fork":false,"pushed_at":"2025-08-30T03:42:39.000Z","size":4063,"stargazers_count":435,"open_issues_count":8,"forks_count":34,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-08-30T05:29:18.420Z","etag":null,"topics":["effect-system","haskell"],"latest_commit_sha":null,"homepage":"https://haskell-effectful.github.io","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/haskell-effectful.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-06-11T11:43:45.000Z","updated_at":"2025-08-30T03:42:42.000Z","dependencies_parsed_at":"2023-10-04T02:23:25.902Z","dependency_job_id":"bedc76e2-23e6-45ef-bb3e-997bb05ba2ec","html_url":"https://github.com/haskell-effectful/effectful","commit_stats":null,"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"purl":"pkg:github/haskell-effectful/effectful","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haskell-effectful%2Feffectful","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haskell-effectful%2Feffectful/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haskell-effectful%2Feffectful/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haskell-effectful%2Feffectful/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haskell-effectful","download_url":"https://codeload.github.com/haskell-effectful/effectful/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haskell-effectful%2Feffectful/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001462,"owners_count":26083102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["effect-system","haskell"],"created_at":"2024-08-02T15:00:46.159Z","updated_at":"2025-10-09T13:45:38.840Z","avatar_url":"https://github.com/haskell-effectful.png","language":"Haskell","readme":"# effectful\n\n[![CI](https://github.com/haskell-effectful/effectful/actions/workflows/haskell-ci.yml/badge.svg?branch=master)](https://github.com/haskell-effectful/effectful/actions/workflows/haskell-ci.yml)\n[![Hackage](https://img.shields.io/hackage/v/effectful.svg)](https://hackage.haskell.org/package/effectful)\n[![Stackage LTS](https://www.stackage.org/package/effectful/badge/lts)](https://www.stackage.org/lts/package/effectful)\n[![Stackage Nightly](https://www.stackage.org/package/effectful/badge/nightly)](https://www.stackage.org/nightly/package/effectful)\n\n\n\u003cimg src=\"https://raw.githubusercontent.com/haskell-effectful/effectful/master/logo.svg\" width=\"150\"\u003e\n\nAn easy to use, fast extensible effects library with seamless integration with\nthe existing Haskell ecosystem.\n\nMain features:\n\n1. Very fast\n   ([benchmarks](https://github.com/haskell-effectful/effectful/tree/master/benchmarks/README.md)).\n\n2. Easy to use API (comparable with usage of the [MonadUnliftIO](https://hackage.haskell.org/package/unliftio-core/docs/Control-Monad-IO-Unlift.html#t:MonadUnliftIO) class).\n\n3. Correct semantics in presence of runtime exceptions (no more discarded state\n   updates).\n\n4. Seamless integration with the existing ecosystem (`exceptions`,\n   `monad-control`, `unliftio-core`, `resourcet` etc.).\n\n5. Support for thread local and shared state (e.g. `StateT` provides a thread\n   local state, while `MVar` holds a shared state, both approaches have their\n   merits).\n\n6. Support for statically (implementation determined at compile time) and\n   dynamically (implementation determined at run time) dispatched effects.\n\n## Motivation\n\nDo we really need yet another library for handling effects? There's\n[freer-simple](https://hackage.haskell.org/package/freer-simple),\n[fused-effects](https://hackage.haskell.org/package/fused-effects),\n[polysemy](https://hackage.haskell.org/package/polysemy),\n[eff](https://github.com/lexi-lambda/eff) and probably a few more.\n\nIt needs to be noted that of all of them only the work-in-progress `eff` library\nis a promising proposition because of reasonable performance characteristics\n(see the talk [Effects for Less](https://www.youtube.com/watch?v=0jI-AlWEwYI)\nfor more information) and potential for good interoperability with the existing\necosystem.\n\nThe second point is arguably the most important, because it allows focusing on\nthings that matter instead of reinventing all kinds of wheels, hence being a\nnecessary condition for broader adoption of the library.\n\nUnfortunately, the development of `eff` has stalled due to a\n[few](https://github.com/hasura/eff/issues/13)\n[subtle](https://github.com/hasura/eff/issues/7)\n[issues](https://github.com/hasura/eff/issues/12) related to its use of\ndelimited continuations underneath.\n\n### What about `mtl`?\n\nIt's true that its \"effects as classes\" approach is widely known and used often.\n\nHowever:\n\n- `mtl` style effects are\n  [slow](https://github.com/haskell-effectful/effectful/tree/master/benchmarks/README.md).\n\n- The majority of popular monad transformers (except `ReaderT`) used for effect\n  implementations are rife with [subtle\n  issues](https://github.com/haskell-effectful/effectful/tree/master/transformers.md).\n\nThese are problematic enough that the [ReaderT design\npattern](https://www.fpcomplete.com/blog/2017/06/readert-design-pattern/) was\ninvented. Its fundamentals are solid, but it's not an effect system.\n\nA solution? Use the `ReaderT` pattern as a base and build around it to make an\nextensible effects library! This is where `effectful` comes in. The `Eff` monad\nit uses is essentially a `ReaderT` over `IO` on steroids, allowing us to extend\nits environment with data types representing effects.\n\nThis concept is quite simple, so:\n\n- It's reasonably easy to understand what is going on under the hood.\n\n- The `Eff` monad being a reader allows for seamless interoperability with\n  ubiquitous classes such as `MonadBaseControl` and `MonadUnliftIO` and solves\n  [issues](https://github.com/haskell-effectful/effectful/tree/master/transformers.md)\n  of monad transformers mentioned above.\n\nWhat is more, the `Eff` monad is concrete, so GHC has many possibilities for\noptimization, which results in a very fast code at a default optimization\nlevel. There is no need to explicitly mark functions with `INLINE` pragmas or\nenable additional optimization passes, it just works.\n\n### Any downsides?\n\nAs always, there's no free lunch. The `Eff` monad doesn't support effect\nhandlers that require the ability to suspend or capture the rest of the\ncomputation and resume it later (potentially multiple times). This prevents\n`effectful` from providing (in particular):\n\n- A `NonDet` effect handler that executes multiple\n[`Alternative`](https://hackage.haskell.org/package/base/docs/Control-Applicative.html#t:Alternative)\nbranches and collects their results.\n\n- A `Coroutine` effect.\n\nIt needs to be noted however that such `NonDet` effect handler in existing\nlibraries is\n[broken](https://github.com/lexi-lambda/eff/blob/8c4df4bf54faf22456354be18095b14825be5e85/notes/semantics-zoo.md)\nand none of the ones with support for higher order effects provide the\n`Coroutine` effect, so arguably it's not a big loss.\n\nIf you need such capability in your application, there are well established\nlibraries such as [conduit](https://hackage.haskell.org/package/conduit) or\n[list-t](https://hackage.haskell.org/package/list-t) that can be used with\n`effectful` without any hassle.\n\n### Summary\n\n`effectful` is an extensible effects library that aims to be the replacement\nfor:\n\n- The bare `ReaderT` pattern by being essentially its enriched version.\n\n- Monad transformer stacks typically encountered in the wild (i.e. consisting of\n  a dozen of newtype'd `ExceptT`, `ReaderT`, `StateT` and `WriterT` transformers\n  and their derivatives) by providing equivalent effects with improved\n  semantics, performance, usability and making it easy to reuse them for your\n  own effects.\n\nIt doesn't try to make monad transformers obsolete, so you're free to\nuse it with `ConduitT`, `ContT`, `ListT` etc. when necessary.\n\n## Package structure\n\nThe library is split among several packages:\n\n- The [`effectful-core`](https://hackage.haskell.org/package/effectful-core)\n  package contains the core of the library along with basic effects. It aims for\n  a small dependency footprint and provides building blocks for more advanced\n  effects.\n\n- The [`effectful-plugin`](https://hackage.haskell.org/package/effectful-plugin)\n  package provides an optional GHC plugin for improving disambiguation of\n  effects (see\n  [here](https://github.com/haskell-effectful/effectful/blob/master/effectful-plugin/README.md)\n  for more information).\n\n- The [`effectful-th`](https://hackage.haskell.org/package/effectful-th) package\n  provides utilities for generating bits of effect-related boilerplate via\n  Template Haskell.\n\n- The [`effectful`](https://hackage.haskell.org/package/effectful) package\n  re-exports public modules of `effectful-core` and additionally provides most\n  features of the [`unliftio`](https://hackage.haskell.org/package/unliftio)\n  package divided into appropriate effects.\n\n## Examples\n\nFor the examples see the *Introduction* sections of\n[`Effectful.Dispatch.Dynamic`](https://hackage.haskell.org/package/effectful-core/docs/Effectful-Dispatch-Dynamic.html)\nand\n[`Effectful.Dispatch.Static`](https://hackage.haskell.org/package/effectful-core/docs/Effectful-Dispatch-Static.html)\n(when in doubt, start with dynamic dispatch).\n\n## Acknowledgements\n\nTo all contributors of existing effect libraries - thank you for putting the\ntime and effort to explore the space. In particular, conversations in issue\ntrackers of `cleff`, `eff`, `freer-simple`, `fused-effects` and `polysemy`\nrepositories were invaluable in helping me discover and understand challenges in\nthe space.\n\n### Resources\n\nResources that inspired the rise of this library and had a lot of impact on its\ndesign.\n\nTalks:\n\n* [Effects for Less](https://www.youtube.com/watch?v=0jI-AlWEwYI) by Alexis King.\n\n* [Monad Transformer State](https://www.youtube.com/watch?v=KZIN9f9rI34) by Michael Snoyman.\n\nBlog posts:\n\n* [ReaderT design pattern](https://www.fpcomplete.com/blog/2017/06/readert-design-pattern/) by Michael Snoyman.\n\n* [Exceptions Best Practices](https://www.fpcomplete.com/blog/2016/11/exceptions-best-practices-haskell/) by Michael Snoyman.\n\n----------------------------------------\n\n\u003cdiv\u003eIcons made by \u003ca href=\"https://www.freepik.com\" title=\"Freepik\"\u003eFreepik\u003c/a\u003e from \u003ca href=\"https://www.flaticon.com/\" title=\"Flaticon\"\u003ewww.flaticon.com\u003c/a\u003e\u003c/div\u003e\n","funding_links":[],"categories":["Haskell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaskell-effectful%2Feffectful","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaskell-effectful%2Feffectful","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaskell-effectful%2Feffectful/lists"}