README Effect and Aff #211
Conversation
README.md
Outdated
|
|
||
| `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. |
There was a problem hiding this comment.
| `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 😄.
README.md
Outdated
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
EffectorAff?
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?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I deleted the reasons why Effect is in core instead of Aff.
There was a problem hiding this comment.
( 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 )
|
I think this top-level README should also mention one more important fact about the |
New README section: Effect and Aff