Create a faq/common-mistakes page

[japgolly]

I think it'd be a great idea to take many common mistakes in the form of code snippets from the community, then I fix them and show a before/after. In so many regards, code will be a clearer form of communication than English. Especially in regard to Callback which I know causes much confusion to those not used to pure side-effects.

(This might be a great way to resolve #410 given that I feel that human language was becoming a real barrier to concensus.)

Let's use this issue to accrue and vote on suggestion. Feel free to post a snippet and a description of what your problem is and/or what you're trying to accomplish, then get the community to vote on it.

Btw, no huge snippets please. Please minimise to just what's relevant.

[ramnivas]

👍 for this. Definitely, at least partially, the problem is communicating through code.

Perhaps for inclusion (if you/others feel the same way):

For me the mental barrier eased a bit when callbacks were named in the form of a noun i.e. xxxHandler instead of a command handleXXX (for example, mouseClickHandler and not handleMouseClick). Then def xHandler = x1Handler >> x2Handler feels right (and def xHandler = x1Handler; x2Handler feels not right much the same way 1 + 1; 3 + 4 wouldn't feel right).

[ramnivas]

Now for a problem/annoyance.

Let's say I want to handle some event whose implementation uses props. Here is how I do:

scope.props.map { props =>
   // do something with props
}

Two lines that I would have liked to avoid, but no biggy.

I also need state, here is the code for this:

(scope.props zip scope.state).map { case (props, state) =>
   // do something with props and state
}

Quite a few extra characters.

Oh, I also need the DOM node:

(scope.props zip scope.state zip scope.getDOMNode).map { case ((props, state), domNode) =>
   // do something with all of those

This along with the dance to get the parenthesis for destructuring right starts to get annoying. Further, during code evolution, when you need to get from one kind of need (some combination of props, state, etc.) to another, the additional ceremony starts to add up.

[ramnivas]

It will be really nice to explain what's the downside of using runNow(). For example, I see that developers in my team run to (no pun intended) runNow() when they face situations described earlier (for example, during code evolution that needs another Callback wrapped object). Generally, there appears no implication of using runNow(), so there is reduced inhibition to using it.

[japgolly]

Hi @ramnivas. I'd probably do something like

for {
  p <- scope.props
  s <- scope.state
  n <- scope.getDOMNode
  ...

Maybe it would be a good idea to have something like:

scope.callback { x => // x is scope but impure
  val p = x.props
  val s = x.state
  val n = x.getDOMNode
  ...

[japgolly]

It will be really nice to explain what's the downside of using runNow().

runNow() is the asInstanceOf of its domain. If you don't use .runNow() then your code is type-safe and when it compiles will work as expected. If you call .runNow() you're telling the compiler "you have to trust me that this is ok, I know what I'm doing" which breaks type-safety, meaning that when it compiles, you don't know for sure (i.e. it's not proven) that it will work correctly.

[ramnivas]

scope.callback { x =>

That will definitely help.

As for using for, I considered it. The usual evolution often starts with needing just the props, so scope.props.map or scope.props.flatMap feels right and sufficient at this stage. Then comes a situation I need state, too. At that time, zip feels like the right choice for an incremental change, and so on.

I think scope.callback (or scope.map and scope.flatMap?) will alleviate these issues to a large extent.

[ramnivas]

runNow() is the asInstanceOf of its domain...

What will really help is a code snippet that shows that using runNow() will not work correctly--especially when it comes to scope.props.runNow(), scope.state.runNow(), and scope.state.getDOMNode.runNow() (I believe not calling runNow() on, say, an event handler is easy to understand and can be explained as "it is equivalent to invoking a function")

[japgolly]

Here's a super quick example of code that compiles ok but is broken at runtime.

class SomeBackend($: BackendScope[Unit, Int]) {

  def squareState: Callback = {
    val state = $.state.runNow()
    val stateSquared = state * state
    $.setState(stateSquared)
  }
  
  val alertUser: Callback =
    Callback.alert("Your state has been updated")
  
  val onButton =
    squareState >> alertUser

  <.button(^.onClick --> onButton, "Update state")

[ramnivas]

This should definitely go into the FAQ with an explanation about why is this so: basically, state is acquired during object initialization since onButton is a val. You could "fix" it by surrounding squareState in a callback (and call runNow() on setState) or making onButton a def but at that point you are swimming upstream.

Basically as I see it:

1. Callbacks protect you against inadvertent early execution. Without callbacks (where you would use functions), you need to ensure that you won't end up executing the function in incorrect places.
2. Callbacks subject you against inadvertent non-execution. With callbacks, you need to ensure that you don't end up not executing a callback (for example using ; where >> would be appropriate).

In the end, there is a choice to be made and scalajs-react has made the choice towards protecting against inadvertent early execution. It is best that the user understands this choice and works with it.

[trepidacious]

I've just updated to 1.1.0 from pre 1.0, and one thing that is really confusing me is types - I've read TYPES.md several times, but I can't work out what to actually do in practice since there are no examples of actual types - even just declaring the types of vals in the examples would be really useful. For example I often used to use ReqProps[P, Unit, Unit, TopNode] to mean "a props-only component" - this might not have been the right thing to do, but it worked ;) I can't work out the new equivalent of this - as soon as I hit a U I'm lost. Weirdly, JsComponent[P, S, CtorType.Props] is pretty much what I want for some S (Unit?), but I need to use this for any component. On this subject, some more about CtorType would be really interesting - why is the CT in all the type signatures so complicated, I don't get this area at all.

Another thing I'd love to see is an example of a facade to a HOC in javascript, e.g. react-sortable-hoc. I had something woring pre 1.0 but I can't port it.

[japgolly]

Closing. Not going to happen. My altruism budget is already maxed out.

[rpiaggio]

@trepidacious Sorry I didn't see your message earlier. I updated react-sortable-hoc to use 1.x and submitted a PR (also added @jsimport's and bumped dependency versions, and cross-compile for Scala 2.12).

trepidacious/scalajs-react-sortable-hoc#1