Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README Effect and Aff #211

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

README Effect and Aff #211

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a25586b
Update README.md
jamesdbrock Jun 29, 2022
48e4af8
Update README.md
jamesdbrock Jul 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,20 @@ main = launchAff_ do
log response.body
```

## Effect and Aff

`Effect` is a synchronous effect monad. It is used to sequence effectful foreign (JavaScript) code — things like random number generation, reading and writing mutable values, writing to the console and throwing and catching exceptions.[<sup>1</sup>](https://stackoverflow.com/questions/37661391/what-are-eff-and-aff)

`Aff` is an asynchronous effect monad. It can handle and sequence effectful asynchronous code, like AJAX requests, timeouts, and network and file IO.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`Aff` is an asynchronous effect monad. It can handle and sequence effectful asynchronous code, like AJAX requests, timeouts, and network and file IO.
`Aff` is an asynchronous effect monad. It can handle and sequence effectful asynchronous code, like HTTP requests, timeouts, and network and file IO.

I know we have Affjax, but AJAX is just not a term that is used anymore. I think we should keep it in the early 2000s 😄.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lol ok

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

It also provides a nice mechanism for handling errors.

Furthermore, `Aff` can perform synchronous effects by using `liftEffect`. In other words, `Effect` is a special case of `Aff`, for the special case that we expect the effect to complete immediately. `Effect` is in the core libraries instead of `Aff` for two reasons.

1. The implementation of `Effect` is much simpler than `Aff`, which makes a big difference for non-JavaScript backends.
2. `Effect` is much faster than `Aff`, and we expect most effects to complete synchronously, so usually `Effect` will suffice.
Copy link
Collaborator

@natefaubion natefaubion Jun 29, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this reasoning is totally correct, though it may be partially true. It's certainly not nuanced enough, and I'd argue that it is not necessary to document this in the preamble to the README.

Aff isn't designed to be portable (or at least isn't designed well for that purpose). The API is specifically around mapping JS style evented callbacks to a direct style. For many runtimes this is just isn't necessary, because their runtimes already provide it as part of normal Effect machinery. That is, Effect represents the built-in, ambient runtime effects of a backend, and some backends provide concurrency as part of that. JS does not, so Aff is necessary to supplement it and provide that functionality. Yes, some people quip that the FFI is "scary", but that's only to achieve a certain goal of performance and safety on a JS backend. It isn't necessary for another backend to implement it in such a way at all. However, since Aff isn't designed to be portable, there is no specification to state whether that implementation is correct aside from tests (which themselves are arguably not portable).

Aff also isn't necessarily slower than Effect. In alternative runtimes, this is likely the case, yes, if they implemented bindings to Aff. In JS, Aff can beat Effect in some cases depending on how the Effect is constructed and what optimizations the compiler was able to apply.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's certainly not nuanced enough

Right, this section has no nuance at all; the intended audience here is people who are just starting out in PureScript and have never encountered an effect monad before in their life.

I want beginners to be able to read this in less than a minute and then come away with first-approximation answers to the questions:

  • What is an effect monad?
  • Why does this Aff package exist?
  • Why are there two effect monads?
  • Should I use Effect or Aff?

Then they can decide if they want to read about the nuance in the Documentation section which follows.

How do you think we should explain why Aff is not in the core libraries?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It isn’t clear to me that we need to explain that at all here. What does that have to do with when to use Effect or Aff? Do we provide that reason in any other contrib library?

Copy link
Collaborator

@natefaubion natefaubion Jun 30, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe a better way to go around it is answering the question "Why isn't Aff the default effect type?", or "Why isn't Aff the effect type I usually encounter?" I feel like "Why isn't it in core?" is trying to stand-in for that, but I don't think that a complete beginner has any internalized distinction about what core vs contrib even means. If they do, it may not even be accurate since there is no defined policy other than who maintains it (compiler team vs community team). To me, "Why isn't it in core?" is just trivia (and the answer should be nuanced). It's only a question one might ask if you note "Effect is in core. Aff is not." as an important distinction for a beginner, which I don't think is the case. For example, parsing is in contrib also, but we never try to explain or justify that location.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I deleted the reasons why Effect is in core instead of Aff.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

( purerl is an example of a PureScript backend for which Effect is asynchronous http://codeofrob.com/entries/purerl-updates---a-heap-of-ported-modules.html )


Many I/O-related packages in the PureScript ecosystem provide both an asynchronous callback-based `Effect` API and an `Aff` API for the same feature. When you encounter this, you should almost always prefer the `Aff` API. You will find the `Aff` API is much simpler to use correctly.

## Documentation

`aff` documentation is stored in a few places:
Expand Down