enhance tapFailure scala docs add test for fatal exception propagation

Author: halotukozak

core/src/main/scala/com/avsystem/commons/SharedExtensions.scala

@@ -463,9 +463,13 @@ object SharedExtensionsUtils extends SharedExtensions {
       if (tr.isFailure) OptArg.Empty else OptArg(tr.get)
 
     /**
-      * Apply side-effect only if Try is a failure.
+      * Apply side-effect only if Try is a failure. The provided `action` function will be called with the
+      * throwable from the failure case, allowing you to perform operations like logging or error handling.
+      * 
+      * Any exceptions thrown by the `action` function are caught and ignored, ensuring that this method
+      * always returns the original Try instance regardless of what happens in the action.
       *
-      * Don't use .failed projection here, because it unnecessarily creates Exception in case of Success,
+      * Don't use .failed projection, because it unnecessarily creates Exception in case of Success,
       * which is an expensive operation.
       */
     def tapFailure(action: Throwable => Unit): Try[A] = tr match {

core/src/test/scala/com/avsystem/commons/misc/SharedExtensionsTest.scala

@@ -235,4 +235,16 @@ class SharedExtensionsTest extends AnyFunSuite with Matchers {
 
     assert(result === failureTry, "Original Failure should be returned even if action throws")
   }
+
+  test("Try.tapFailure - Fatal exception in action") {
+    val originalException = new RuntimeException("original exception")
+    val fatalException = new OutOfMemoryError("fatal exception")
+    val failureTry = Failure(originalException)
+
+    val thrown = intercept[OutOfMemoryError] {
+      failureTry.tapFailure(_ => throw fatalException)
+    }
+
+    assert(thrown === fatalException, "Fatal exception should propagate out of tapFailure")
+  }
 }