Add and document {Async,}Callback.debounce

See #967 for motivation

Author: japgolly

callback/src/main/scala-2/japgolly/scalajs/react/callback/AsyncCallback.scala

@@ -299,6 +299,27 @@ object AsyncCallback {
     }
   }
 
+  /** Creates an debounce boundary.
+    *
+    * Save it as a `val` somewhere because it relies on internal state that must be reused.
+    */
+  @inline def debounce(delay: Duration): AsyncCallback[Unit] =
+    unit.debounce(delay)
+
+  /** Creates an debounce boundary.
+    *
+    * Save it as a `val` somewhere because it relies on internal state that must be reused.
+    */
+  @inline def debounce(delay: FiniteDuration): AsyncCallback[Unit] =
+    unit.debounce(delay)
+
+  /** Creates an debounce boundary.
+    *
+    * Save it as a `val` somewhere because it relies on internal state that must be reused.
+    */
+  @inline def debounceMs(delayMs: Long): AsyncCallback[Unit] =
+    unit.debounceMs(delayMs)
+
   def awaitAll(as: AsyncCallback[Any]*): AsyncCallback[Unit] =
     if (as.isEmpty)
       unit
@@ -864,12 +885,24 @@ final class AsyncCallback[+A] private[AsyncCallback] (val underlyingRepr: AsyncC
       }
     }
 
+  /** Creates an debounce boundary over the underlying computation.
+    *
+    * Save the result of this as a `val` somewhere because it relies on internal state that must be reused.
+    */
   def debounce(delay: Duration): AsyncCallback[A] =
     debounceMs(delay.toMillis)
 
+  /** Creates an debounce boundary over the underlying computation.
+    *
+    * Save the result of this as a `val` somewhere because it relies on internal state that must be reused.
+    */
   def debounce(delay: FiniteDuration): AsyncCallback[A] =
     debounceMs(delay.toMillis)
 
+  /** Creates an debounce boundary over the underlying computation.
+    *
+    * Save the result of this as a `val` somewhere because it relies on internal state that must be reused.
+    */
   def debounceMs(delayMs: Long): AsyncCallback[A] =
     AsyncCallback.debounce(delayMs, this)
 

callback/src/main/scala-2/japgolly/scalajs/react/callback/Callback.scala

@@ -1,8 +1,10 @@
 package japgolly.scalajs.react.callback
 
 import japgolly.scalajs.react.util.Util.identityFn
+import java.time.Duration
 import org.scalajs.dom.{console, window}
 import scala.annotation.implicitNotFound
+import scala.concurrent.duration.FiniteDuration
 import scala.concurrent.{ExecutionContext, Future}
 import scala.scalajs.js
 import scala.scalajs.js.timers.{RawTimers, SetIntervalHandle, SetTimeoutHandle}
@@ -124,6 +126,27 @@ object Callback {
   def sequenceOption[A](oca: => Option[CallbackTo[A]]): Callback =
     traverseOption(oca)(identityFn)
 
+  /** Creates an debounce boundary.
+    *
+    * Save it as a `val` somewhere because it relies on internal state that must be reused.
+    */
+  @inline def debounce(delay: Duration): Callback =
+    empty.debounce(delay)
+
+  /** Creates an debounce boundary.
+    *
+    * Save it as a `val` somewhere because it relies on internal state that must be reused.
+    */
+  @inline def debounce(delay: FiniteDuration): Callback =
+    empty.debounce(delay)
+
+  /** Creates an debounce boundary.
+    *
+    * Save it as a `val` somewhere because it relies on internal state that must be reused.
+    */
+  @inline def debounceMs(delayMs: Long): Callback =
+    empty.debounceMs(delayMs)
+
   /** Run all given callbacks.
     *
     * All results are discarded.

callback/src/main/scala-2/japgolly/scalajs/react/callback/CallbackTo.scala

@@ -486,12 +486,24 @@ final class CallbackTo[+A] private[react] (private[CallbackTo] val trampoline: T
         windowMs = windowMs,
       ))
 
+  /** Creates an debounce boundary over the underlying computation.
+    *
+    * Save the result of this as a `val` somewhere because it relies on internal state that must be reused.
+    */
   def debounce(delay: Duration): Callback =
     _debounceMs(delay.toMillis)
 
+  /** Creates an debounce boundary over the underlying computation.
+    *
+    * Save the result of this as a `val` somewhere because it relies on internal state that must be reused.
+    */
   def debounce(delay: FiniteDuration): Callback =
     _debounceMs(delay.toMillis)
 
+  /** Creates an debounce boundary over the underlying computation.
+    *
+    * Save the result of this as a `val` somewhere because it relies on internal state that must be reused.
+    */
   def debounceMs(delayMs: Long): Callback =
     _debounceMs(delayMs)
 

callback/src/main/scala-3/japgolly/scalajs/react/callback/AsyncCallback.scala

@@ -300,6 +300,28 @@ object AsyncCallback {
     }
   }
 
+
+  /** Creates an debounce boundary.
+    *
+    * Save it as a `val` somewhere because it relies on internal state that must be reused.
+    */
+  inline def debounce(delay: Duration): AsyncCallback[Unit] =
+    unit.debounce(delay)
+
+  /** Creates an debounce boundary.
+    *
+    * Save it as a `val` somewhere because it relies on internal state that must be reused.
+    */
+  inline def debounce(delay: FiniteDuration): AsyncCallback[Unit] =
+    unit.debounce(delay)
+
+  /** Creates an debounce boundary.
+    *
+    * Save it as a `val` somewhere because it relies on internal state that must be reused.
+    */
+  inline def debounceMs(delayMs: Long): AsyncCallback[Unit] =
+    unit.debounceMs(delayMs)
+
   def awaitAll(as: AsyncCallback[Any]*): AsyncCallback[Unit] =
     if (as.isEmpty)
       unit
@@ -874,12 +896,24 @@ final class AsyncCallback[+A] private[AsyncCallback] (val underlyingRepr: AsyncC
       }
     }
 
+  /** Creates an debounce boundary over the underlying computation.
+    *
+    * Save the result of this as a `val` somewhere because it relies on internal state that must be reused.
+    */
   inline def debounce(inline delay: Duration): AsyncCallback[A] =
     debounceMs(delay.toMillis)
 
+  /** Creates an debounce boundary over the underlying computation.
+    *
+    * Save the result of this as a `val` somewhere because it relies on internal state that must be reused.
+    */
   inline def debounce(inline delay: FiniteDuration): AsyncCallback[A] =
     debounceMs(delay.toMillis)
 
+  /** Creates an debounce boundary over the underlying computation.
+    *
+    * Save the result of this as a `val` somewhere because it relies on internal state that must be reused.
+    */
   def debounceMs(delayMs: Long): AsyncCallback[A] =
     AsyncCallback.debounce(delayMs, this)
 

callback/src/main/scala-3/japgolly/scalajs/react/callback/Callback.scala

@@ -1,8 +1,10 @@
 package japgolly.scalajs.react.callback
 
 import japgolly.scalajs.react.util.Util.identityFn
+import java.time.Duration
 import org.scalajs.dom.{console, window}
 import scala.annotation.implicitNotFound
+import scala.concurrent.duration.FiniteDuration
 import scala.concurrent.{ExecutionContext, Future}
 import scala.language.`3.0`
 import scala.scalajs.js
@@ -125,6 +127,27 @@ object Callback {
   inline def sequenceOption[A](inline oca: Option[CallbackTo[A]]): Callback =
     traverseOption(oca)(identityFn)
 
+  /** Creates an debounce boundary.
+    *
+    * Save it as a `val` somewhere because it relies on internal state that must be reused.
+    */
+  inline def debounce(delay: Duration): Callback =
+    empty.debounce(delay)
+
+  /** Creates an debounce boundary.
+    *
+    * Save it as a `val` somewhere because it relies on internal state that must be reused.
+    */
+  inline def debounce(delay: FiniteDuration): Callback =
+    empty.debounce(delay)
+
+  /** Creates an debounce boundary.
+    *
+    * Save it as a `val` somewhere because it relies on internal state that must be reused.
+    */
+  inline def debounceMs(delayMs: Long): Callback =
+    empty.debounceMs(delayMs)
+
   /** Run all given callbacks.
     *
     * All results are discarded.

callback/src/main/scala-3/japgolly/scalajs/react/callback/CallbackTo.scala

@@ -524,12 +524,24 @@ final class CallbackTo[+A] /*private[react]*/ (private[CallbackTo] val trampolin
         windowMs = windowMs,
       ))
 
+  /** Creates an debounce boundary over the underlying computation.
+    *
+    * Save the result of this as a `val` somewhere because it relies on internal state that must be reused.
+    */
   inline def debounce(inline delay: Duration): Callback =
     __debounceMs(delay.toMillis)
 
+  /** Creates an debounce boundary over the underlying computation.
+    *
+    * Save the result of this as a `val` somewhere because it relies on internal state that must be reused.
+    */
   inline def debounce(inline delay: FiniteDuration): Callback =
     __debounceMs(delay.toMillis)
 
+  /** Creates an debounce boundary over the underlying computation.
+    *
+    * Save the result of this as a `val` somewhere because it relies on internal state that must be reused.
+    */
   inline def debounceMs(inline delayMs: Long): Callback =
     __debounceMs(delayMs)
 

doc/changelog/2.0.0.md

@@ -351,6 +351,16 @@ You can run the script in the Migration section at the bottom of the page to aut
   * UnivEq to 1.6.0
 
 
+# Changes in RC4
+
+* Document existing `debounce` methods to clarify you need to save them as a `val` and reuse them
+* Add:
+  * `AsyncCallback.debounce(duration): AsyncCallback[Unit]`
+  * `Callback.debounce(duration): Callback`
+* Upgrade deps
+  * Cats-effect to 3.2.3
+
+
 # Thanks
 
 A lot of this was kindly sponsored by [Gemini](https://www.gemini.edu/)/[NOIRLab](https://nationalastro.org/)/[AURA](https://www.aura-astronomy.org/).