Refactor: Move / rename CoreOps to MapOps; expand map ops scaladoc (#151)

Author: SgtSwagrid

project/GenerateTupleSignals.scala

@@ -16,7 +16,7 @@ case class GenerateTupleSignals(
     line("package com.raquo.airstream.extensions")
     line()
     line("import com.raquo.airstream.core.Signal")
-    line("import com.raquo.airstream.misc.MapSignal")
+    line("import com.raquo.airstream.map.MapSignal")
     line()
     line("// #Warning do not edit this file directly, it is generated by GenerateTupleSignals.scala")
     line()

project/GenerateTupleStreams.scala

@@ -16,7 +16,8 @@ case class GenerateTupleStreams(
     line("package com.raquo.airstream.extensions")
     line()
     line("import com.raquo.airstream.core.EventStream")
-    line("import com.raquo.airstream.misc.{FilterStream, MapStream}")
+    line("import com.raquo.airstream.map.MapStream")
+    line("import com.raquo.airstream.misc.FilterStream")
     line()
     line("// #Warning do not edit this file directly, it is generated by GenerateTupleStreams.scala")
     line()

src/main/scala/com/raquo/airstream/core/BaseObservable.scala

@@ -3,6 +3,7 @@ package com.raquo.airstream.core
 import com.raquo.airstream.debug.DebugOps
 import com.raquo.airstream.distinct.DistinctOps
 import com.raquo.airstream.flatten.{AllowFlatMap, FlattenStrategy, MergingStrategy, SwitchingStrategy}
+import com.raquo.airstream.map.MapOps
 import com.raquo.airstream.ownership.{Owner, Subscription}
 import com.raquo.airstream.status.{FlatMapStatusObservable, Status}
 import com.raquo.ew.JsArray
@@ -35,7 +36,7 @@ import scala.util.Try
 trait BaseObservable[+Self[+_] <: Observable[_], +A]
 extends Source[A]
 with Named
-with CoreOps[Self, A]
+with MapOps[Self, A]
 with RecoverOps[Self, A]
 with DistinctOps[Self[A], A]
 with DebugOps[Self, A] {

src/main/scala/com/raquo/airstream/core/CoreOps.scala

@@ -11,6 +11,7 @@ import com.raquo.airstream.dynamicImport.{DynamicImportStreamObjectOps, DynamicI
 import com.raquo.airstream.eventbus.EventBus
 import com.raquo.airstream.extensions._
 import com.raquo.airstream.javaflow.FlowPublisherStream
+import com.raquo.airstream.map.{MapOps, MapStream}
 import com.raquo.airstream.misc._
 import com.raquo.airstream.split.SplittableOneStream
 import com.raquo.airstream.status.{AsyncStatusObservable, Status}
@@ -31,7 +32,7 @@ with CombineStreamOps[A] // combineWith, combineWithFn, withCurrentValueOf, samp
 with DynamicImportStreamOps[A] // dynamicImport (Scala 3 only)
 {
 
-  /** See more map-like operators in [[CoreOps]]
+  /** See more map-like operators in [[MapOps]]
     *
     * @param project Note: guarded against exceptions
     */

src/main/scala/com/raquo/airstream/core/EventStream.scala

@@ -9,7 +9,8 @@ import com.raquo.airstream.debug.{Debugger, DebuggerSignal, DebugOps, DebugSigna
 import com.raquo.airstream.distinct.{DistinctOps, DistinctSignal}
 import com.raquo.airstream.dynamicImport.{DynamicImportSignalObjectOps, DynamicImportSignalOps}
 import com.raquo.airstream.extensions._
-import com.raquo.airstream.misc.{MapSignal, ScanLeftSignal, StreamFromSignal}
+import com.raquo.airstream.map.{MapOps, MapSignal}
+import com.raquo.airstream.misc.{ScanLeftSignal, StreamFromSignal}
 import com.raquo.airstream.ownership.Owner
 import com.raquo.airstream.state.{ObservedSignal, OwnedSignal, Val}
 import com.raquo.airstream.timing.JsPromiseSignal
@@ -44,7 +45,7 @@ with DynamicImportSignalOps[A] // dynamicImport (Scala 3 only)
     */
   protected[airstream] def now(): A = tryNow().get
 
-  /** See also various map-like operators methods in [[CoreOps]].
+  /** See also various map-like operators methods in [[MapOps]].
     *
     * @param project Note: guarded against exceptions
     */

src/main/scala/com/raquo/airstream/core/Signal.scala

@@ -1,7 +1,7 @@
 package com.raquo.airstream.extensions
 
 import com.raquo.airstream.core.Signal
-import com.raquo.airstream.misc.MapSignal
+import com.raquo.airstream.map.MapSignal
 
 // #Warning do not edit this file directly, it is generated by GenerateTupleSignals.scala
 

src/main/scala/com/raquo/airstream/extensions/TupleSignals.scala

@@ -1,7 +1,8 @@
 package com.raquo.airstream.extensions
 
 import com.raquo.airstream.core.EventStream
-import com.raquo.airstream.misc.{FilterStream, MapStream}
+import com.raquo.airstream.map.MapStream
+import com.raquo.airstream.misc.FilterStream
 
 // #Warning do not edit this file directly, it is generated by GenerateTupleStreams.scala
 

src/main/scala/com/raquo/airstream/extensions/TupleStreams.scala

@@ -0,0 +1,63 @@
+package com.raquo.airstream.map
+
+import com.raquo.airstream.core.{EventStream, Signal}
+
+/**
+ * A base trait for observables that have mapping operators such as `map` and `mapTo`.
+ * @tparam Self The kind of observable that this is (e.g. [[Signal]] or [[EventStream]]).
+ * @tparam A The type of value emitted by this observable (e.g. [[org.scalajs.dom.MouseEvent]] or [[Int]]).
+ */
+trait MapOps[+Self[+_], +A] {
+
+  /**
+   * Map all events or updates of this observable through a pure transformation `project`.
+   * The resulting observable emits once each time this parent observable emits.
+   *
+   * @param project The transformation to apply, to be called exactly once per event or update.
+   *                Exceptions thrown during evaluation are caught by Airstream (see `recover()`).
+   *
+   * @see [[mapTo]], [[mapToStrict]], [[mapToUnit]], [[tapEach]]
+   */
+  def map[B](project: A => B): Self[B]
+
+  /**
+   * Ignore the current value and take a new value instead.
+   *
+   * @param value The replacement value, evaluated lazily and repeatedly on every event or update.
+   *              Exceptions thrown during evaluation are caught by Airstream (see `recover()`).
+   *
+   * @note Equivalent to `map(_ => value)` if `value` is defined with `def`.
+   * @see [[map]], [[mapToStrict]], [[mapToUnit]], [[tapEach]]
+   */
+  def mapTo[B](value: => B): Self[B] = map(_ => value)
+
+  /**
+   * Ignore the current value and take a new value instead.
+   *
+   * @param value The replacement value, evaluated eagerly and only once.
+   *              Exceptions thrown during evaluation go uncaught in the current call stack.
+   *
+   * @note Equivalent to `map(_ => value)` if `value` is defined with `val`.
+   * @see [[map]], [[mapTo]], [[mapToUnit]], [[tapEach]]
+   */
+  def mapToStrict[B](value: B): Self[B] = map(_ => value)
+
+  /**
+   * Ignore the current value and instead take the value "`()`" (i.e. of type [[Unit]]).
+   *
+   * @note Equivalent to `mapTo(())` or `mapToStrict(())`.
+   * @see [[map]], [[mapTo]], [[mapToStrict]], [[tapEach]]
+   */
+  @inline def mapToUnit: Self[Unit] = map(_ => ())
+
+  /**
+   * Execute a side-effecting callback on every event or update.
+   *
+   * @param callback A callback whose return value is ignored, to be called exactly once per event or update.
+   *                 Exceptions thrown during evaluation are caught by Airstream (see `recover()`).
+   *
+   * @note Will not work if no downstream observable is subscribed to by an observer.
+   * @see [[map]], [[mapTo]], [[mapToStrict]], [[mapToUnit]]
+   */
+  @inline def tapEach[U](callback: A => U): Self[A] = map { v => callback(v); v }
+}

src/main/scala/com/raquo/airstream/map/MapOps.scala

@@ -1,4 +1,4 @@
-package com.raquo.airstream.misc
+package com.raquo.airstream.map
 
 import com.raquo.airstream.common.SingleParentSignal
 import com.raquo.airstream.core.{Protected, Signal, Transaction}