Merge pull request #1005 from japgolly/topic/effectSyntax

Add implicit syntax for generic effects

Author: japgolly

doc/FX_AGNOSTICISM.md

@@ -14,6 +14,7 @@ friends directly, but if you want your library to be effect-agnostic then follow
 * [Producing effects from classes](#producing-effects-from-classes)
 * [Producing effects from traits](#producing-effects-from-traits)
 * [Modifying effects](#modifying-effects)
+* [Implicit syntax/ops](#implicit-syntaxops)
 
 
 # Required sbt changes
@@ -299,8 +300,28 @@ This can be even more abstract if you want, no need to restrict it to only synch
 import japgolly.scalajs.react.util.Effect.Monad
 
 def newWay[F[_], A](f: F[A])(implicit F: Monad[F]): F[Option[A]] = {
-  // no implicit ops lol. This case is rare and I don't want to needlessly add to output JS size
+  // no implicit ops in this example so that it doesn't needlessly add to output JS size.
+  // implicit ops are exactly available though, see the it's section in this doc.
   val fo = F.map(f)(Option(_))
   F.flatmap(fo)(o => F.delay { println("Result is " + o); o })
 }
 ```
+
+
+# Implicit syntax/ops
+
+Implicit ops have now been added to make working with general effects easier.
+
+```scala
+import japgolly.scalajs.react.util.Effect
+import japgolly.scalajs.react.util.syntax._
+
+def example(fi: F[Int])(implicit F: Effect.Sync[F]): F[Int] =
+  for {
+    i <- fi
+    j <- F.delay(123)
+  } yield {
+    println("Re-running fi = " + fi.runSync())
+    i + j
+  }
+```

doc/changelog/2.0.0-RCs.md

@@ -88,7 +88,11 @@ Contents:
   * `CallbackOption#finallyRun[B](runFinally: CallbackOption[B]): CallbackOption[A]`
   * `CallbackOption#when_`
   * `CallbackOption#unless_`
+
 * Add to cats module:
   * Implicit `MonadThrow` instances for scalajs-react effect types
   * Implicit `Monoid` instances for scalajs-react effect types with a monoidal value
+
+* Add ops for working with generic effects via `import japgolly.scalajs.react.util.syntax._`
+
 * Refactoring around internal effect-agnosticism type class definitions

util/src/main/scala/japgolly/scalajs/react/util/EffectSyntax.scala

@@ -0,0 +1,116 @@
+package japgolly.scalajs.react.util
+
+import scala.scalajs.js
+
+trait EffectSyntax
+  extends EffectSyntax.ForAsync
+     with EffectSyntax.ForSync
+
+object EffectSyntax {
+  import Effect._
+
+  trait ForMonad {
+    implicit def sjrEffectMonadOps[F[_], A](fa: F[A])(implicit f: Monad[F]): MonadOps[F, A] =
+      new MonadOps[F, A] {
+        override protected def F = f
+        override protected def self = fa
+      }
+  }
+
+  trait MonadOps[F[_], A] {
+    protected def F: Monad[F]
+    protected def self: F[A]
+
+    def map    [B](f: A => B)   : F[B] = F.map(self)(f)
+    def flatMap[B](f: A => F[B]): F[B] = F.flatMap(self)(f)
+    def >>     [B](fb: F[B])    : F[B] = F.chain(self, fb)
+  }
+
+  // ===================================================================================================================
+
+  trait ForEffect extends ForMonad {
+    implicit def sjrEffectEffectOps[F[_], A](fa: F[A])(implicit f: Effect[F]): EffectOps[F, A] =
+      new EffectOps[F, A] {
+        override protected def F = f
+        override protected def self = fa
+      }
+  }
+
+  trait EffectOps[F[_], A] extends MonadOps[F, A] {
+    override protected def F: Effect[F]
+
+    def finallyRun [B]      (runFinally: => F[B])  : F[A]  = F.finallyRun(self, runFinally)
+    def handleError[AA >: A](f: Throwable => F[AA]): F[AA] = F.handleError[A, AA](self)(f)
+  }
+
+  // ===================================================================================================================
+
+  trait ForDispatch extends ForEffect {
+    implicit def sjrEffectDispatchOps[F[_], A](fa: F[A])(implicit f: Dispatch[F]): DispatchOps[F, A] =
+      new DispatchOps[F, A] {
+        override protected def F = f
+        override protected def self = fa
+      }
+  }
+
+  trait DispatchOps[F[_], A] extends EffectOps[F, A] {
+    override protected def F: Dispatch[F]
+
+    def dispatch()  : Unit               = F.dispatch(self)
+    def toDispatchFn: js.Function0[Unit] = F.dispatchFn(self)
+  }
+
+  // ===================================================================================================================
+
+  trait ForUnsafeSync extends ForDispatch {
+    implicit def sjrEffectUnsafeSyncOps[F[_], A](fa: F[A])(implicit f: UnsafeSync[F]): UnsafeSyncOps[F, A] =
+      new UnsafeSyncOps[F, A] {
+        override protected def F = f
+        override protected def self = fa
+      }
+  }
+
+  trait UnsafeSyncOps[F[_], A] extends DispatchOps[F, A] {
+    override protected def F: UnsafeSync[F]
+
+    def runSync()                : A               = F.runSync(self)
+    def toJsFn                   : js.Function0[A] = F.toJsFn(self)
+    def unless_(cond: => Boolean): F[Unit]         = F.unless_(cond)(self)
+    def when_  (cond: => Boolean): F[Unit]         = F.when_(cond)(self)
+  }
+
+  // ===================================================================================================================
+
+  trait ForSync extends ForUnsafeSync {
+    implicit def sjrEffectSyncOps[F[_], A](fa: F[A])(implicit f: Sync[F]): SyncOps[F, A] =
+      new SyncOps[F, A] {
+        override protected def F = f
+        override protected def self = fa
+      }
+  }
+
+  trait SyncOps[F[_], A] extends UnsafeSyncOps[F, A] {
+    override protected def F: Sync[F]
+
+    def isEmpty: Boolean = F.isEmpty(self)
+    def reset  : F[Unit] = F.reset(self)
+  }
+
+  // ===================================================================================================================
+
+  trait ForAsync extends ForDispatch {
+    implicit def sjrEffectAsyncOps[F[_], A](fa: F[A])(implicit f: Async[F]): AsyncOps[F, A] =
+      new AsyncOps[F, A] {
+        override protected def F = f
+        override protected def self = fa
+      }
+  }
+
+  trait AsyncOps[F[_], A] extends DispatchOps[F, A] {
+    override protected def F: Async[F]
+
+    def runAsync   : Async.Untyped[A]    = F.runAsync(self)
+    def toJsPromise: () => js.Promise[A] = F.toJsPromise(self)
+  }
+
+}

util/src/main/scala/japgolly/scalajs/react/util/syntax/package.scala

@@ -0,0 +1,4 @@
+package japgolly.scalajs.react.util
+
+package object syntax
+  extends japgolly.scalajs.react.util.EffectSyntax

util/src/test/scala/japgolly/scalajs/react/util/SyntaxCompilationTest.scala

@@ -0,0 +1,35 @@
+package japgolly.scalajs.react.util
+
+import japgolly.scalajs.react.util.syntax._
+
+trait SyntaxCompilationTest {
+
+  def sync[F[_]: Effect.Sync](f: F[Int]) =
+    for {
+      i <- f
+      j <- f
+    } yield {
+      f.reset.dispatch()
+      val k = f.runSync()
+      i + j + k
+    }
+
+  def async[F[_]: Effect.Async](f: F[Int]) =
+    for {
+      i <- f
+      j <- f
+    } yield {
+      val _ = f.toJsPromise
+      i + j
+    }
+
+  def dispatch[F[_]: Effect.Dispatch](f: F[Int]) =
+    for {
+      i <- f
+      j <- f
+    } yield {
+      val _ = f.dispatch()
+      i + j
+    }
+
+}