attemptTap (#3459)

* attemptTap

* add to typeclass

* Add attemptTap example

* Fix doc

core/src/main/scala/cats/MonadError.scala

@@ -77,6 +77,33 @@ trait MonadError[F[_], E] extends ApplicativeError[F, E] with Monad[F] {
   def redeemWith[A, B](fa: F[A])(recover: E => F[B], bind: A => F[B]): F[B] =
     flatMap(attempt(fa))(_.fold(recover, bind))
 
+  /**
+   * Reifies the value or error of the source and performs an effect on the result,
+   * then recovers the original value or error back into `F`.
+   *
+   * Note that if the effect returned by `f` fails, the resulting effect will fail too.
+   *
+   * Alias for `fa.attempt.flatTap(f).rethrow` for convenience.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.implicits._
+   * scala> import scala.util.{Try, Success, Failure}
+   *
+   * scala> def checkError(result: Either[Throwable, Int]): Try[String] = result.fold(_ => Failure(new java.lang.Exception), _ => Success("success"))
+   *
+   * scala> val a: Try[Int] = Failure(new Throwable("failed"))
+   * scala> a.attemptTap(checkError)
+   * res0: scala.util.Try[Int] = Failure(java.lang.Exception)
+   *
+   * scala> val b: Try[Int] = Success(1)
+   * scala> b.attemptTap(checkError)
+   * res1: scala.util.Try[Int] = Success(1)
+   * }}}
+   */
+  def attemptTap[A, B](fa: F[A])(f: Either[E, A] => F[B]): F[A] =
+    rethrow(flatTap(attempt(fa))(f))
+
   override def adaptError[A](fa: F[A])(pf: PartialFunction[E, E]): F[A] =
     recoverWith(fa)(pf.andThen(raiseError[A] _))
 }

core/src/main/scala/cats/syntax/monadError.scala

@@ -32,6 +32,9 @@ final class MonadErrorOps[F[_], E, A](private val fa: F[A]) extends AnyVal {
 
   def redeemWith[B](recover: E => F[B], bind: A => F[B])(implicit F: MonadError[F, E]): F[B] =
     F.redeemWith[A, B](fa)(recover, bind)
+
+  def attemptTap[B](f: Either[E, A] => F[B])(implicit F: MonadError[F, E]): F[A] =
+    F.attemptTap(fa)(f)
 }
 
 final class MonadErrorRethrowOps[F[_], E, A](private val fea: F[Either[E, A]]) extends AnyVal {