Add conversions between Callback and Future

Closes #216

Author: japgolly

core/src/main/scala/japgolly/scalajs/react/Callback.scala

@@ -2,7 +2,7 @@ package japgolly.scalajs.react
 
 import org.scalajs.dom.console
 import scala.annotation.implicitNotFound
-import scala.concurrent.{Future, Promise}
+import scala.concurrent.{ExecutionContext, Future, Promise}
 import scala.concurrent.duration.{FiniteDuration, MILLISECONDS}
 import scala.scalajs.js
 import js.{undefined, UndefOr, Function0 => JFn0, Function1 => JFn1}
@@ -52,6 +52,17 @@ object Callback {
   @inline def byName(f: => Callback): Callback =
     CallbackTo(f.runNow())
 
+  /**
+   * Wraps a [[Future]] so that it is repeatable, and so that its inner callback is run when the future completes.
+   *
+   * The result is discarded. To retain it, use [[CallbackTo.future)]] instead.
+   *
+   * WARNING: Futures are scheduled to run as soon as they're created. Ensure that the argument you provide creates a
+   * new [[Future]]; don't reference an existing one.
+   */
+  def future[A](f: => Future[CallbackTo[A]])(implicit ec: ExecutionContext): Callback =
+    CallbackTo.future(f).voidExplicit[Future[A]]
+
   /**
    * Convenience for applying a condition to a callback, and returning `Callback.empty` when the condition isn't
    * satisfied.
@@ -143,6 +154,15 @@ object CallbackTo {
   @inline def byName[A](f: => CallbackTo[A]): CallbackTo[A] =
     CallbackTo(f.runNow())
 
+  /**
+   * Wraps a [[Future]] so that it is repeatable, and so that its inner callback is run when the future completes.
+   *
+   * WARNING: Futures are scheduled to run as soon as they're created. Ensure that the argument you provide creates a
+   * new [[Future]]; don't reference an existing one.
+   */
+  def future[A](f: => Future[CallbackTo[A]])(implicit ec: ExecutionContext): CallbackTo[Future[A]] =
+    CallbackTo(f.map(_.runNow()))
+
   /**
    * Serves as a temporary placeholder for a callback until you supply a real implementation.
    *
@@ -164,6 +184,18 @@ object CallbackTo {
   @deprecated("", "not really deprecated")
   def TODO[A](result: => A, reason: => String): CallbackTo[A] =
     Callback.todoImpl(Some(() => reason)) >> CallbackTo(result)
+
+  final class ReactExt_CallbackToFuture[A](private val _c: () => Future[A]) extends AnyVal {
+    @inline private def c = new CallbackTo(_c)
+
+    /**
+     * Turns a `CallbackTo[Future[A]]` into a `Future[A]`.
+     *
+     * WARNING: This will trigger the execution of the [[Callback]].
+     */
+    def toFlatFuture(implicit ec: ExecutionContext): Future[A] =
+      c.toFuture.flatMap(identity)
+  }
 }
 
 // =====================================================================================================================
@@ -268,6 +300,14 @@ final class CallbackTo[A] private[react] (private[CallbackTo] val f: () => A) ex
   def void: Callback =
     ret(())
 
+  /**
+   * Discard the value produced by this callback.
+   *
+   * This method allows you to be explicit about the type you're discarding (which may change in future).
+   */
+  @inline def voidExplicit[B](implicit ev: A =:= B): Callback =
+    void
+
   def conditionally(cond: => Boolean): CallbackTo[Option[A]] =
     CallbackTo(if (cond) Some(f()) else None)
 
@@ -394,6 +434,12 @@ final class CallbackTo[A] private[react] (private[CallbackTo] val f: () => A) ex
       p.future
     }
 
+  /**
+   * Schedules an instance of this callback to run asynchronously.
+   */
+  def toFuture(implicit ec: ExecutionContext): Future[A] =
+    Future(runNow())
+
   /**
    * Record the duration of this callback's execution.
    */
@@ -459,7 +505,7 @@ final class CallbackTo[A] private[react] (private[CallbackTo] val f: () => A) ex
     bool2(b)(_() || _())
 
   /**
-   * Negates the callback result (so long as its boolean).
+   * Negates the callback result (so long as it's boolean).
    */
   def !(implicit ev: ThisIsBool): CallbackB =
     ev(this).map(!_)

core/src/main/scala/japgolly/scalajs/react/package.scala

@@ -1,6 +1,7 @@
 package japgolly.scalajs
 
 import org.scalajs.dom, dom.html
+import scala.concurrent.{ExecutionContext, Future}
 import scala.scalajs.js
 import js.{Dynamic, Object, Any => JAny, Function => JFn}
 
@@ -205,4 +206,8 @@ package object react extends ReactEventAliases {
     @inline def only: Option[ReactNode] =
       try { Some(React.Children.only(c))} catch { case t: Throwable => None}
   }
+
+  @inline implicit def ReactExt_CallbackToFuture[A](c: CallbackTo[Future[A]]) =
+    new CallbackTo.ReactExt_CallbackToFuture(() => c.runNow())
+
 }

doc/CHANGELOG-0.10.md

@@ -1,8 +1,48 @@
 # 0.10.1 (unreleased)
 
-* Upgrade Scala.JS to 0.6.5.
+* Added conversions between `Callback` and `Future`.
+
+  | Input                      | Method                 | Output                  |
+  | -------------------------- | ---------------------- | ----------------------- |
+  | `CallbackTo[A]`            | `cb.toFuture`          | `Future[A]`             |
+  | `CallbackTo[Future[A]]`    | `cb.toFlatFuture`      | `Future[A]`             |
+  | `=> Future[A]`             | `CallbackTo(f)`        | `CallbackTo[Future[A]]` |
+  | `=> Future[CallbackTo[A]]` | `Callback.future(f)`   | `Callback`              |
+  | `=> Future[CallbackTo[A]]` | `CallbackTo.future(f)` | `CallbackTo[Future[A]]` |
+
+  **NOTE:** It's important that when going from `Future` to `Callback`, you're aware of when the `Future` is instantiated.
+
+  ```scala
+  def queryServer: Future[Data] = ???
+
+  def updateComponent: Future[Callback] =
+    queryServer.map($ setState _)
+
+  // This is GOOD because the callback wraps the updateComponent *function*, not an instance.
+  Callback.future(updateComponent)
+
+  // This is BAD because the callback wraps a single instance of updateComponent.
+  // 1) The server will be contacted immediately instead of when the callback executes.
+  // 2) If the callback is execute more than once, the future and old result will be reused.
+  val f = updateComponent
+  Callback.future(f)
+
+  // This is BAD because the callback wraps a single instance of updateComponent.
+  // 1) The server will be contacted immediately instead of when the callback executes.
+  // 2) If the callback is execute more than once, the future and old result will be reused.
+
+  // This is GOOD too because the future is created inside the callback.
+  Callback.future {
+    val f = updateComponent
+    f.onComplete(???)
+    f
+  }
+  ```
+
 * Add `React.Children.toArray`.
 
+* Upgrade Scala.JS to 0.6.5.
+
 ---
 
 # 0.10.0 ([commit log](https://github.com/japgolly/scalajs-react/compare/v0.9.2...v0.10.0))

test/src/test/scala/japgolly/scalajs/react/CallbackTest.scala

@@ -1,5 +1,8 @@
 package japgolly.scalajs.react
 
+import scala.concurrent._
+import scala.concurrent.duration._
+import scala.scalajs.concurrent.JSExecutionContext.Implicits.runNow
 import utest._
 
 object CallbackTest extends TestSuite {
@@ -32,9 +35,32 @@ object CallbackTest extends TestSuite {
       "Callback(Callback)"   - assertFails(compileError("Callback(cb)"))
       "Callback(CallbackTo)" - assertFails(compileError("Callback(cbI)"))
     }
+
     'lazily -
       testEvalStrategy(Callback lazily _, 0, 1, 1)
+
     'byName -
       testEvalStrategy(Callback byName _, 0, 1, 2)
+
+    'future {
+      'repeatable {
+        var runs = 0
+        def modState = Callback(runs += 1)
+        def f = Future(modState)
+        val c = Callback.future(f)
+        assert(runs == 0)
+        c.runNow()
+        c.runNow()
+        assert(runs == 2)
+      }
+
+      'toFlatFuture {
+        val c = CallbackTo(Future(666))
+        val f = c.toFlatFuture
+        var i = 0
+        f.map(i = _)
+        assert(i == 666)
+      }
+    }
   }
 }