feat(Result): introduce Result::unwrapOr() (#470)

* feat(Result): introduce `Result::unwrapOr()`

I'd like to introduce a function that allows to get inner value from Result if success and allows to bypass throwing an exception from Failure by providing a default value.

* Update src/Psl/Result/Failure.php

Co-authored-by: Saif Eddin Gmati <29315886+azjezz@users.noreply.github.com>

* Update src/Psl/Result/ResultInterface.php

Co-authored-by: Saif Eddin Gmati <29315886+azjezz@users.noreply.github.com>

* Update src/Psl/Result/Success.php

Co-authored-by: Saif Eddin Gmati <29315886+azjezz@users.noreply.github.com>

* style: fix

---------

Co-authored-by: Saif Eddin Gmati <29315886+azjezz@users.noreply.github.com>

src/Psl/Result/Failure.php

@@ -44,6 +44,20 @@ public function getResult(): void
         throw $this->throwable;
     }
 
+    /**
+     * Unwrap the Result if it is succeeded or return $default value.
+     *
+     * @template D
+     *
+     * @param D $default
+     *
+     * @return D
+     */
+    public function unwrapOr(mixed $default): mixed
+    {
+        return $default;
+    }
+
     /**
      * Since this is a failed result wrapper, this always returns the `Throwable` thrown during the operation.
      *

src/Psl/Result/ResultInterface.php

@@ -95,6 +95,17 @@ public function always(Closure $always): ResultInterface;
      */
     public function getResult();
 
+    /**
+     * Unwrap the Result if it is succeeded or return $default value.
+     *
+     * @template D
+     *
+     * @param D $default
+     *
+     * @return T|D
+     */
+    public function unwrapOr(mixed $default): mixed;
+
     /**
      * Return the underlying throwable, or fail with a invariant violation exception.
      *

src/Psl/Result/Success.php

@@ -44,6 +44,20 @@ public function getResult(): mixed
         return $this->value;
     }
 
+    /**
+     * Unwrap the Result if it is succeeded or return $default value.
+     *
+     * @template D
+     *
+     * @param D $default
+     *
+     * @return T
+     */
+    public function unwrapOr(mixed $default): mixed
+    {
+        return $this->value;
+    }
+
     /**
      * Since this is a successful result wrapper, this always throws a
      * `Psl\Exception\InvariantViolationException` saying that there was no exception thrown from the operation.

tests/unit/Result/FailureTest.php

@@ -33,6 +33,14 @@ public function testGetResult(): void
         $wrapper->getResult();
     }
 
+    public function testUnwrapFailure(): void
+    {
+        $result = new Failure(new Exception());
+        $value = $result->unwrapOr(null);
+
+        static::assertNull($value);
+    }
+
     public function testGetException(): void
     {
         $exception = new Exception('bar');

tests/unit/Result/SuccessTest.php

@@ -31,6 +31,14 @@ public function testGetResult(): void
         static::assertSame('hello', $wrapper->getResult());
     }
 
+    public function testUnwrap(): void
+    {
+        $result = new Success('foo');
+        $value = $result->unwrapOr(null);
+
+        static::assertSame('foo', $value);
+    }
+
     public function testGetException(): void
     {
         $wrapper = new Success('hello');