feature: Add Result\ify()

src/functions/result.php

@@ -94,6 +94,57 @@ function trap(callable $callback, string $exceptionClass = \Exception::class): R
     }
 }
 
+/**
+ * Wrap a callable into one that transforms its returned value or thrown exception
+ * into a `Result` like `Result\trap()` does.
+ *
+ * # Examples
+ *
+ * Successful execution:
+ *
+ * ```
+ * self::assertEq(Result\ok(3), Result\ify(fn () => 3)());
+ * ```
+ *
+ * Checked exception:
+ *
+ * ```
+ * $x = Result\ify(fn () => new \DateTimeImmutable("2020-30-30 UTC"))();
+ * self::assertTrue($x->isErr());
+ * $x->unwrap();
+ * // @throws Exception Failed to parse time string (2020-30-30 UTC) at position 6 (0): Unexpected character
+ * ```
+ *
+ * Unchecked exception:
+ *
+ * ```
+ * Result\ify(fn () => 1/0)();
+ * // @throws DivisionByZeroError Division by zero
+ * ```
+ *
+ * @template U
+ * @param callable(...mixed):U $callback
+ * @return \Closure(...mixed): Result<U,\Throwable>
+ * @throws \Throwable
+ */
+#[ExamplesSetup(IgnoreUnusedResults::class)]
+function ify(callable $callback, string $exceptionClass = \Exception::class): \Closure
+{
+    return static function (...$args) use ($callback, $exceptionClass): Result
+    {
+        try {
+            /** @var Result<U,\Throwable> */
+            return Result\ok($callback(...$args));
+        } catch (\Throwable $th) {
+            if (\is_a($th, $exceptionClass)) {
+                return Result\err($th);
+            }
+
+            throw $th;
+        }
+    };
+}
+
 /**
  * Converts from `Result<Result<T, E>, E>` to `Result<T, E>`.
  *

tests/Unit/Result/IfyTest.php

@@ -0,0 +1,48 @@
+<?php declare(strict_types=1);
+
+namespace TH\Maybe\Tests\Unit\Result;
+
+use PHPUnit\Framework\TestCase;
+use TH\Maybe\Result;
+use TH\Maybe\Tests\Assert;
+use TH\Maybe\Tests\Provider;
+
+final class IfyTest extends TestCase
+{
+    use Provider\Values;
+
+    /**
+     * @dataProvider values
+     */
+    public function testIfyOk(mixed $value): void
+    {
+        $callback = static fn () => $value;
+
+        Assert::assertEquals($value, Result\ify($callback)()->unwrap());
+    }
+
+    public function testIfyCheckedException(): void
+    {
+        Assert::assertEquals(
+            new \Exception(
+                "Failed to parse time string (nope) at position 0 (n): The timezone could not be found in the database",
+            ),
+            // @phpstan-ignore-next-line
+            Result\ify(static fn () => new \DateTimeImmutable("nope"))()->unwrapErr(),
+        );
+    }
+
+    public function testIfyUncheckedException(): void
+    {
+        try {
+            // @phpstan-ignore-next-line
+            Result\ify(static fn () => 1 / 0)();
+            Assert::fail("An exception should have been thrown");
+        } catch (\DivisionByZeroError $ex) {
+            Assert::assertEquals(
+                "Division by zero",
+                $ex->getMessage(),
+            );
+        }
+    }
+}