Expose the setImmediate polyfill so that libraries can use it directly

[japgolly]

I have a bunch of setTimeout(..., 0) calls in scalajs-react and I'd like to replace them using this setImmediate polyfill.

[armanbilge]

Thanks for the PR! I think simply MacrotaskExecutor.execute(...) would fullfill your use-case out-of-the-box, is the concern about overhead?

[japgolly]

Yeah, on one hand I'd like to avoid any overhead, on another using setImmediate is clearer to read. :)

[AlexITC]

on another using setImmediate is clearer to read

Is it? I think that people familiar with Node are likely to know what it is but I think it is a weird name. I'd believe MacrotaskExecutor.execute is a clearer.

[japgolly]

Is it?

Yes, it is. More people in the world know what setImmediate is than know about this custom library.

What's the big deal with making this public?

[armanbilge]

The original goals of this library were to be a drop-in replacement for the global ExecutionContext in Scala.js and have a minimal surface area in terms of API, which is what we have here.

If we were to expose the "raw" setImmediate there's a number of considerations:

1. It would probably be nicer if it was exposed as a method rather than an anonymous function.
2. On MDN and in the original polyfill setImmediate returns a handle. We should probably implement this.
3. Following (2), we should probably also implement clearImmediate.

These changes would increase our API surface area quite a bit based on something which is not standardized and, since this is a polyfill and not a facade, binary-compatibility is a concern. This may or may not be a big deal.

IMHO if we were to move forward with this, I'd like to see (1)-(3) done. But someone with more experience should weigh in.

[armanbilge]

FYI I just proposed that we add a facade for setImmediate to scala-js-dom in scala-js/scala-js-dom#652. This can be used with the original setImmediate polyfill, available on npm and also as a webjar. IMO this makes more sense b/c:

1. A facade can evolve more freely than an API that must maintain binary-compatibility.
2. Many (virtually all?) Scala.js users creating browser apps are already depending on JavaScript artifacts. One more doesn't seem like a big deal.
3. We'll get the handle and clearImmediate implementations for free.
4. As illustrated by @japgolly and @AlexITC, there are different styles of writing Scala.js depending on your background. MacrotaskExecutor and a setImmediate facade will appeal to different users.

[sjrd]

As mentioned earlier in #37 (comment), exposing setImmediate would indeed require quite a bit of polishing for it, and would outgrow the scope of this library.

This library is only about providing an ExecutionContext that uses macrotasks. It is not about providing setImmediate. The fact that it uses setImmediate or a polyfill thereof is an implementation detail of this library, and should not be exposed in the public API. If something is eventually added to the standard that we can use instead, we will, and we must have the freedom to remove all the code related to setImmediate at that point.

[japgolly]

If something is eventually added to the standard that we can use instead, we will, and we must have the freedom to remove all the code related to setImmediate at that point.

So just do it. APIs break. That's why we have versioning strategies.