document semantics

[safareli]

Intro

It would be great if there was a section or separate doc documenting the semantics of Aff and it's execution model. for example, this is not written down nor in readme nor in Aff module documentation; Semantics section of this issue is not quite documented (if it's still true); results of this and this discussion/changes would be a good fit for such document/section as well.

Why this is useful?

It would help folks already using Aff to better understand it and reason about code written in Aff, as well as help them author safer/performant/correct software. It would also help new PureScript developers who are just starting in utilizing powers of Aff and get up to speed much faster.

It would also be useful to better understand the implications of changes made on Aff going forward.

Also for other non-JS backends having semantics clearly represented as text will guide them in implementing a version of Aff which is matching in semantics of JS version, which will potentially increas code portability.

What efforts should be taken to achieve this?

I have no understanding of internal machinery of Aff but folks who do could dump some topic which should be covered in this doc/section so we have some kind of plan/outline.
Once that's clear, others can volunteer, including me, on filling some details.

Another approach would be to go through tests and extract out information from there.
Ideally, statements in the will have links to supporting tests.

---

Would like to hear what people think. Are gains of achieving this worth the effort?

[natefaubion]

I think most questions around Aff behavior are "what should happen when I do __ while in __ state". It would be helpful to have a working PureScript reference implementation in terms of specific state transitions so that one could construct a Fiber state, apply the transition, and see what you get out of it. I'm not sure if that's exactly what you might want for "semantics" but it at least can give you a clear answer.

[natefaubion]

I started this a while back, and then abandoned it because it requires non-trivial existential encodings in PureScript, and I think that it loses a lot of clarity and loses safety if you want it to be usable (since I think a reference implementation should be usable). One option is to implement it in Haskell, but then it's not something you can actually use, or to wait until we have better language support.

[safareli]

I don't quite see what PureScript reference implementation in terms of specific state transition could be, if you have some sketch of high-level functions/types can you post that, or some example of similar thing done somewhere else? If it's supposed to be used when someone has the question then why wouldn't a Haskell version be usable? I'm asking because we can write CLI wrapper over that and distribute using npm, so it can be used by non haskellers, but I guess i'm missing something.