search

rescript-association / reasonml.org

Deprecated in favor of rescript-lang.org
MIT License
125 stars 33 forks source link

Introduction to the Js module, including information about data-first vs. data-last #87

Closed cknitt closed 4 years ago

cknitt commented 4 years ago

(Also cleaned up/unified some minor things with the Belt introduction I wrote previously.)

I hope that the information regarding the Js.Xxx -> Js.Xxx2 migration is accurate, as I have not received any answer to my questions in https://github.com/BuckleScript/bucklescript/issues/2975#issuecomment-542549940.

@ryyppy In the JS docs, the style is currently somewhat broken as the headlines (h2) are invisible.

ryyppy commented 4 years ago

I will discuss this with Cheng today, since there are a lot of open questions on what is officially on the plan. A few things (especially the topic Pipe First vs Pipe Last) feel like they should belong to the Reason language docs (which will hopefully be added as soon as we aligned plans).

cknitt commented 4 years ago

@ryyppy True, there should be a section about Pipe First vs. Pipe Last in a more general place in the docs. We can reference that from the Belt and Js docs then.

Nonetheless, we need to explain in the context of the Js namespace why there are currently both Js.Array and Js.Array2 etc. and what the plan is going forward.

nikgraf commented 4 years ago

@cknitt Patrick and I had two separate calls with Cheng the last two weeks. He explained that Js.Xxx2 was never supposed to be public and we should not promote it. This was rather something they need for some reason internally.

Personally I have mixed feeling about it, but I suggest we keep aligned with the core team. Consistent messaging is more important.

Proposal:

What do you think? @cknitt @ryyppy

cknitt commented 4 years ago

@nikgraf @ryyppy I do not like this at all.

First of all, the biggest question is what is the roadmap? Is it still planned to make all the Js APIs data-first eventually (like Belt already is)? I would strongly suggest to do so, the current mish-mash of data-first and data-last APIs is very confusing for newcomers.

If so, the next question is what to do while this migration to data-first APIs is in progress. Using a data-last API like Js.String with pipe first and the _ functionality feels awkward to me. Personally I'd rather use data-first APIs with the pipe first operator and data-last APIs with the pipe last operator.

MoOx commented 4 years ago

Same feeling here, I hope we could quickly have a better situation on this data-first/last. I definitely thing we should go data-first as the pipe first operator is better (from my experience) for inference (I started reason using pipe-last |> but got plenty of situation where the inference was not good and switching to Belt + data-first solved all this kind of problem).

ryyppy commented 4 years ago

There is a plan to make it data first. Everything will be data first, afaik. The only thing we should accept right now is that there are currently two ways on how to do it:

We could state that xxx2 modules exist and explain how they work, but that they are non-public API. Users can decide if they are taking the risk of breaking changes. I guess for many, they see more value in consistent APIs and will take the cost for refactoring later on (which hopefully won't be too much effort anyways).

There's not much we can 100% recommend, we can only state what's the situation and let ppl know about it. What we can definitely tell is that data-first is here to stay.

cknitt commented 4 years ago

There is a plan to make it data first. Everything will be data first, afaik.

🎉 🎉 🎉

The only thing we should accept right now is that there are currently two ways on how to do it: ...

Ok, will try to update the PR accordingly.

ryyppy commented 4 years ago

84 changed the file structure, please merge current master, i think it should merge cleanly