Be more reassuring about cross-platform semantics

[armanbilge]

(My summary/analysis of this Discord discussion.)

After we've worked so hard to preserve cross-platform semantics, at least I have forgotten that apparently this is surprising for users. When the expectation is that Scala.js support is second-class, users may doubt whether certain things work or various advice applies and look to docs/support to answer their questions.

So, we probably need to be more reassuring and upfront about the fact that everything pretty much works the same. I think for the most part, that unless otherwise noted, basically all the docs apply to both JVM and JS.

I have a bit of this in my feral README. https://github.com/typelevel/feral#why-go-feral

[davesmith00000]

Thanks @armanbilge.

After we've worked so hard to preserve cross-platform semantics, at least I have forgotten that apparently this is surprising for users.

Just to clarify a little (I was the other party in the discussion): It's not surprising that IO itself is semantically the same - that is point after all. 💯 It's surprising (to me at least) that the runtime and invocation of an CE based programme should be expected to be treated the same way. You could expect to run a Node.js app fairly similarly to a JVM app. It's slightly odd (to me) to think of using IOApp for something embedded in a browser page, where the programme / function may for instance be run and re-run from some other bit of JavaScript with data rather than command line-like String arguments. Also IOApp comes with things like keep-alive and a lot of complicated run time set up stuff that probably isn't relevant in a browser context, where something like this is actually sufficient (but not documented).

Hope that helps.

[armanbilge]

Thanks for the helpful clarification @davesmith00000! :)

It's surprising (to me at least) that the runtime and invocation of an CE based programme should be expected to be treated the same way.

Out of curiosity, is it equally surprising to you that you can write a pure Scala.js browser application that does def main(...)? Why/why not?

I think that basically the idea of IOApp is that anywhere you would normally write a main method, you can use IOApp instead. Of course, if you wouldn't write a main method then IOApp is not right for you! Which maybe we need to clarify in the docs :)

where the programme / function may for instance be run and re-run from some other bit of JavaScript with data

I think this is getting at the problem I attempted to capture in https://github.com/typelevel/cats-effect/issues/2929, where you need to run IO outside of the context of an IOApp. This doesn't just affect browsers; feral has this same problem on both JVM and JS since you can't plop a main method in your serverless lambda :) We can definitely improve the docs on this topic.

Also IOApp comes with things like keep-alive and a lot of complicated run time set up stuff that probably isn't relevant in a browser context, where something like this is actually sufficient (but not documented).

Fair, although AFAIK it's not really harmful. My experimental lib could have used IOApp there, and maybe would have if it weren't experimental 😆 IOApp exposes more configuration, although the majority of users don't/won't need that.

BTW another reasonable summary of all this may be that we need docs specifically explaining how to use IO in the browser. Which for whatever reason I think am trying to avoid 😅 arguably, scope-creep and because ... browsers :)

Maybe I'm wrong about that. But something we can definitely do better is drop more hints in the existing docs "this is a good pattern for e.g. browser applications" "this is a useful technique for serverless functions" etc.

[davesmith00000]

Out of curiosity, is it equally surprising to you that you can write a pure Scala.js browser application that does def main(...)?

I'm certainly aware that you can do that, Indigo and Tyrian both worked that way for a long time. In practice I don't know how often you would want to do that. My experience is that you reach a certain level of complexity and you suddenly need more control over how the app starts in the browser than a simple call to main allows.

Fair, although AFAIK it's not really harmful.

Absolutely, but because IOApp has all that stuff in it, trying to read through the IOApp source as a point of reference (in lieu of documentation) to decide what may or may not be important for a custom version is hard going (as a relative new comer with a low patience threshold 😅 ).

Maybe I'm wrong about that. But something we can definitely do better is drop more hints in the existing docs "this is a good pattern for e.g. browser applications" "this is a useful technique for serverless functions" etc.

Yes that sounds very reasonable (sorry I know you're avoiding it!). I think a sort of parallel track for the docs might be aiming towards a degree of practical advice.