• Stars
    star
    547
  • Rank 81,254 (Top 2 %)
  • Language
    Haskell
  • License
    ISC License
  • Created about 5 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

🚧 a work in progress effect system for Haskell 🚧

eff β€” screaming fast extensible effects for less Build Status Documentation

🚧 This library is currently under construction. 🚧

eff is a work-in-progress implementation of an extensible effect system for Haskell, a general-purpose solution for tracking effects at the type level and handling them in flexible ways. Compared to other effect systems currently available, eff differentiates itself in the following respects:

  • eff is really fast. Built on top of low-level primitives added to the GHC RTS to support capturing slices of the call stack, eff is performant by design. Using a direct implementation of delimited control allows it to be fast without relying on fickle compiler optimizations to eliminate indirection.

    Traditional effect system microbenchmarks fail to capture the performance of real code, as they are so small that GHC often ends up inlining everything. In real programs, GHC compiles most effect-polymorphic code via dictionary passing, not specialization, causing the performance of other effect systems to degrade beyond what microbenchmarks would imply. eff takes care to allow GHC to generate efficient code without the need for whole-program specialization.

  • eff is low-boilerplate and easy to use, even without Template Haskell or any generic programming. eff’s interface is comparable to freer-simple and polysemy, but writing new effect handlers is made even simpler thanks to a small set of highly expressive core operations.

  • eff is expressive, providing support for both first-order/algebraic effects and higher-order/scoped effects, like fused-effects and polysemy (but unlike freer-simple).

  • eff’s semantics is precise and easy to reason about, based on models of delimited control. Other approaches to scoped operations (including those taken in mtl, fused-effects, and polysemy) have behavior that changes depending on handler order, and some combinations can lead to nonsensical results. eff’s semantics is consistent regardless of handler order, and scoped operations compose in predictable ways.

eff in action

To illustrate just how easy it is to define and handle effects in eff, the following code example includes 100% of the code necessary to define a custom FileSystem effect and two handlers, one that runs in IO and another that uses an in-memory virtual file system:

import qualified System.IO as IO
import Prelude hiding (readFile, writeFile)
import Control.Effect

-- -----------------------------------------------------------------------------
-- effect definition

data FileSystem :: Effect where
  ReadFile :: FilePath -> FileSystem m String
  WriteFile :: FilePath -> String -> FileSystem m ()

readFile :: FileSystem :< effs => FilePath -> Eff effs String
readFile = send . ReadFile

writeFile :: FileSystem :< effs => FilePath -> String -> Eff effs ()
writeFile a b = send $ WriteFile a b

-- -----------------------------------------------------------------------------
-- IO handler

runFileSystemIO :: IOE :< effs => Eff (FileSystem ': effs) a -> Eff effs a
runFileSystemIO = interpret \case
  ReadFile path -> liftIO $ IO.readFile path
  WriteFile path contents -> liftIO $ IO.writeFile path contents

-- -----------------------------------------------------------------------------
-- pure handler

runFileSystemPure :: Error String :< effs => Eff (FileSystem ': effs) a -> Eff effs a
runFileSystemPure = lift
  >>> interpret \case
        ReadFile path -> do
          fileSystem <- get
          case lookup path fileSystem of
            Just contents -> pure contents
            Nothing       -> throw ("readFile: no such file " <> path)
        WriteFile path contents -> do
          fileSystem <- get
          -- add the new file and remove an old file with the same name, if it exists
          put ((path, contents) : filter ((/= path) . fst) fileSystem)
  >>> evalState @[(FilePath, String)] []

That’s it. For a thorough explanation of how the above example works, see the eff documentation.

Implementation status

eff is a work in progress, and since it requires changes to the GHC RTS, you cannot use it yet on any released version of GHC. If there is interest, I can try to provide builds of GHC with the necessary changes to use eff, but otherwise you will need to wait for them to be merged into GHC proper before using eff yourself. There is currently an open GHC proposal to add the necessary operations, and the work-in-progress implementation branch is available here.

Looking beyond that, many things are still not yet implemented. More work needs to be done to properly interoperate with IO exceptions, and the set of built-in effects currently provided is very small. However, all the existing functionality works, and it has been designed to support extensions, so I do not anticipate any difficulty supporting them.

This library is also sorely lacking a benchmark suite. I have a small set of microbenchmarks I have been using to test out various scenarios and edge cases of different effect libraries, but they need to be cleaned up and added to this repository, and a set of less synthetic benchmarks are also important to assess real-world performance. If you have a small but non-trivial program where differences in effect system performance are significant, I would be much obliged if you could share it to build a more realistic set of effect system benchmarks.

Acknowledgements, citations, and related work

All code in eff is original in the sense that it was not taken directly from other libraries, but much of it is directly inspired by the existing work of many others. The following is a non-exhaustive list of people and works that have had a significant impact, directly or indirectly, on eff’s design and implementation:

More Repositories

1

graphql-engine

Blazing fast, instant realtime GraphQL APIs on your DB with fine grained access control, also trigger webhooks on database events.
TypeScript
31,162
star
2

gitkube

Build and deploy docker images to Kubernetes using git push
Go
3,805
star
3

graphqurl

curl for GraphQL with autocomplete, subscriptions and GraphiQL. Also a dead-simple universal javascript GraphQL client.
JavaScript
3,339
star
4

skor

Now part of Hasura GraphQL Engine. Listen to postgres events and forward them as JSON payloads to a webhook
C
1,246
star
5

learn-graphql

Real world GraphQL tutorials for frontend developers with deadlines!
JavaScript
1,177
star
6

gatsby-gitbook-starter

Generate GitBook style modern docs/tutorial websites using Gatsby + MDX
JavaScript
985
star
7

awesome-react-graphql

A curated collection of resources, clients and tools that make working with `GraphQL and React/React Native` awesome
738
star
8

react-check-auth

Add auth protection anywhere in your react/react-native app
JavaScript
530
star
9

3factor-example

Canonical example of building a 3factor app : a food ordering application
JavaScript
458
star
10

awesome-live-reloading

A curated collection of live-reloading / hot-reloading / watch-reloading tools for different languages and frameworks.
435
star
11

ra-data-hasura

react-admin data provider for Hasura GraphQL Engine
TypeScript
335
star
12

awesome-vue-graphql

A curated collection of resources, clients and tools that make working with `GraphQL and Vue.js` awesome
302
star
13

graphql-bench

A super simple tool to benchmark GraphQL queries
TSQL
263
star
14

hasura-ecommerce

TypeScript
246
star
15

pgdeltastream

Streaming Postgres logical replication changes atleast-once over websockets
Go
244
star
16

graphql-engine-heroku

Blazing fast, instant realtime GraphQL APIs on Postgres with fine grained access control, also trigger webhooks on database events.
Dockerfile
231
star
17

graphql2chartjs

graphql2chartjs reshapes your GraphQL data as per the ChartJS API.
JavaScript
222
star
18

hasura-aws-stack

A complete production ready 100% serverless stack on AWS with Hasura
JavaScript
215
star
19

json2graphql

From a JSON file to postgres-backed realtime GraphQL
JavaScript
200
star
20

3factor

3factor app is an architecture pattern for modern fullstack apps. 3factor apps are fast to build and are highly scalable.
SCSS
181
star
21

client-side-graphql

147
star
22

hasura-k8s-stack

A feature-complete Hasura stack on Kubernetes
JavaScript
138
star
23

hasura-actions-examples

Examples of handling custom business logic with Hasura Actions
JavaScript
135
star
24

awesome-angular-graphql

A curated collection of resources, clients and tools that make working with `GraphQL and Angular` awesome
132
star
25

gqless-movies-demo

A movies app using Hasura and gqless
TypeScript
127
star
26

awesome-fluent-graphql

Awesome list of fluent GraphQL clients & examples
TypeScript
106
star
27

graphiql-online

Explore your GraphQL APIs with headers
JavaScript
90
star
28

kubeformation

Create declarative cluster specifications for your managed Kubernetes vendor (GKE, AKS)
Go
86
star
29

data-dictionary

TypeScript
85
star
30

firebase2graphql

Move from Firebase realtime db to instant GraphQL APIs on Postgres
JavaScript
81
star
31

jwt-guide

TypeScript
79
star
32

nodejs-graphql-subscriptions-boilerplate

Boilerplate to setup GraphQL subscriptions in your nodejs code
JavaScript
78
star
33

pacha

Connect your private data to LLMs
PLpgSQL
74
star
34

graphql-serverless

Example boilerplates for GraphQL backends hosted on serverless platforms
Go
71
star
35

graphql-parser-hs

A GraphQL query parser for Haskell
Haskell
59
star
36

sphinx-graphiql

Sphinx plugin that adds a GraphiQL directive so that you can embed an interactive GraphQL query explorer in your docs
JavaScript
57
star
37

kriti-lang

A minimal JSON templating language
Haskell
55
star
38

schema-stitching-examples

JavaScript
44
star
39

gitkube-example

An example repo to be used with gitkube: git push to deploy on to Kubernetes
HTML
43
star
40

graphql-backend-benchmarks

GraphQL performance benchmarks across Hasura, Postgraphile and Prisma
Shell
42
star
41

comment-progress

Notify progress by commenting on GitHub issues, pull requests, and commits :octocat: πŸ’¬
JavaScript
42
star
42

local-development

[Deprecated] Run Hasura locally on your computer
37
star
43

rxdb-hasura-demo

An Offline first todo app
JavaScript
37
star
44

monad-validate

(NOTE: REPOSITORY MOVED TO NEW OWNER: https://github.com/lexi-lambda/monad-validate) A Haskell monad transformer library for data validation
Haskell
32
star
45

pod42

Python
31
star
46

gitlab-graphql

Install gitlab and expose the gitlab api's over GraphQL
JavaScript
29
star
47

codegen-assets

TypeScript
27
star
48

ndc-hub

Go
26
star
49

data-hub

Explore data sources from a native GraphQL API, database schemas to custom code contributed by the community.
PLpgSQL
26
star
50

pg-client-hs

A low level Haskell library to connect to postgres
Haskell
25
star
51

yelp-clone-react

A Yelp clone built using React + GraphQL + Hasura
JavaScript
24
star
52

github-integration-starter

Try out Hasura's GitHub Integration on Cloud Projects using the examples in this repo.
24
star
53

template-gallery

Repository containing schema sharing packages.
PLpgSQL
24
star
54

authz-workshop

TSQL
23
star
55

hasura-cloud-preview-apps

TypeScript
22
star
56

graphql-schema-stitching-demo

Schema Stitching Example with Hasura GraphQL + MetaWeather API
JavaScript
22
star
57

hasura-discord-docs-bot

PLpgSQL
21
star
58

ndc-typescript-deno

Instant Hasura Native Data Connector by writing Typescript Functions
TypeScript
21
star
59

ndc-spec

NDC Specification and Reference Implementation
Rust
20
star
60

issues

Dump and sync org wide issues into postgres and visualise with metabase.
Python
19
star
61

realm-pg-sync

The realm-pg-sync microservice
JavaScript
18
star
62

graphql-data-specification

A specification for Data APIs with GraphQL
Haskell
18
star
63

imad-app

Base repository for IMAD course application.
JavaScript
18
star
64

ndc-postgres

Hasura v3 Data Connector for PostgreSQL
Rust
18
star
65

react-apollo-todo

A todo app with react, apollo demonstrating graphql queries, mutations and subscriptions.
CSS
17
star
66

architect-graphql-workshop

JavaScript
16
star
67

continuous-backup

Postgres wal-e continuous backup system
Shell
16
star
68

preview-actions

Starter kit to try out actions
JavaScript
16
star
69

auth-ui-kit

Web UI Kit for Hasura Authentication
JavaScript
15
star
70

graphql-example-apps

PLpgSQL
14
star
71

smooth-checkout-buildkite-plugin

All the things you need during a Buildkite checkout 🧈 πŸͺ
Shell
14
star
72

js-sdk

JavaScript
14
star
73

cloud-functions-boilerplates

Boilerplates for cloud functions (AWS Lambda, Google Cloud Functions, Azure Cloud Functions, Zeit, etc.) that work in conjunction with Hasura GraphQL Engine's event triggers
JavaScript
14
star
74

graphql-subscriptions-benchmark

TypeScript
13
star
75

sample-apps

TypeScript
12
star
76

demo-apps

Config to deploy Hasura demo apps using Docker Compose
HTML
12
star
77

github-bot

Hasura's own GitHub bot πŸ€–
JavaScript
11
star
78

generator-hasura-web

JavaScript
11
star
79

open-data-domain-specification

Rust
11
star
80

sqlite-dataconnector-agent

SQLite Data Connector Agent for Hasura GQL Engine. Please note that this repository is a mirror. We will still accept PRs, but will have to mirror them to our upstream repo.
TypeScript
11
star
81

ndc-sdk-typescript

NDC SDK for TypeScript
TypeScript
11
star
82

smooth-secrets-buildkite-plugin

A buildkite plugin to setup ssh keys and env secrets for your pipelines 🧈 πŸ”’
Shell
11
star
83

chat-app-android

Java
10
star
84

custom-resolvers-boilerplate

A boilerplate for writing custom resolvers with Hasura GraphQL Engine
JavaScript
10
star
85

reactathon-workshop

10
star
86

go-buildkite-dsl

Write Buildkite configs in Go πŸͺ πŸ“
Go
9
star
87

android-sdk

The Android SDK for Hasura
Java
9
star
88

sample-auth-webhook

Sample auth webhooks for the Hasura GraphQL engine
JavaScript
9
star
89

generator-hasura-node

JavaScript
9
star
90

graphql-asia-workshop

JavaScript
9
star
91

supergraph-io

Content for the supergraph.io website
HTML
8
star
92

graphql-on-various-pg

Hasura's GraphQL engine on various Postgres systems/providers
Shell
8
star
93

cli-plugins-index

Shell
8
star
94

graphql-weather-api

A simple GraphQL express weather api server boilerplate
JavaScript
8
star
95

supergraph-top-n-challenge

JavaScript
8
star
96

ddn-sample-app

TypeScript
8
star
97

ndc-nodejs-lambda

Write NodeJS TypeScript functions and easily expose them in your Hasura DDN project
TypeScript
7
star
98

haskell-docker-builder

Package haskell binaries as docker images
Makefile
7
star
99

graphql-engine-install-manifests

Various installation manifests for Hasura's GraphQL Engine
Shell
7
star
100

laravel-todo-hge

A sample Laravel app with an auth webhook
PHP
7
star