Merge pull request #80 from Innmind/recover-case

Add `Attempt::recoverCase()` and `::mapErrorCase()`

Author: Baptouuuu

CHANGELOG.md

@@ -5,6 +5,8 @@
 ### Added
 
 - `Innmind\Immutable\Validation::attempt()`
+- `Innmind\Immutable\Attempt::mapErrorCase()`
+- `Innmind\Immutable\Attempt::recoverCase()`
 
 ## 6.0.0 - 2026-01-11
 

docs/structures/attempt.md

@@ -139,6 +139,24 @@ $attempt = Attempt::of(static fn() => 1/0)
 
 Here `#!php $attempt` contains an `\Exception` because the first `Attempt` raised a `DivisionByZeroError`.
 
+## `->mapErrorCase()`
+
+This is similar to `mapError` except you can specify the type of error you want to change (like in a `catch` statement).
+
+```php
+$attempt = Attempt::of(static fn() => 1/0)
+    ->mapErrorCase(
+        \DivisionByZeroError::class,
+        static fn(\DivisionByZeroError $e) => new \Exception('Division by zero, fix the code'),
+    )
+    ->mapError(static fn(\Throwable $e) => new \Exception('something bad happened', 0, $e));
+```
+
+!!! warning ""
+    It uses `instanceof` to check the error case. This means the order in which you apply these calls is important!
+
+    This is to match the behaviour of the `catch` statement.
+
 ## `->recover()`
 
 This will allow you to recover in case of a previous error.
@@ -150,6 +168,26 @@ $attempt = Attempt::of(static fn() => 1/0)
 
 Here `#!php $attempt` is `#!php 42` because the first `Attempt` raised a `DivisionByZeroError`.
 
+## `->recoverCase()`
+
+This is similar to `recover` except you can specify the type of error you want to recover (like in a `catch` statement).
+
+```php
+$attempt = Attempt::of(static fn() => 1/0)
+    ->recoverCase(
+        \DivisionByZeroError::class,
+        static fn(\DivisionByZeroError $e) => Attempt::result(0),
+    )
+    ->recover(static fn(\Throwable $e) => Attempt::result(42));
+```
+
+Here `#!php $attempt` is `#!php 0` because the first `Attempt` raised a `DivisionByZeroError`.
+
+!!! warning ""
+    It uses `instanceof` to check the error case. This means the order in which you apply these calls is important!
+
+    This is to match the behaviour of the `catch` statement.
+
 ## `->xrecover()`
 
 This behaves like [`->recover()`](#-recover) except when conjointly used with [`->guard()`](#-guard). Guarded errors can't be recovered.

proofs/attempt.php

@@ -152,6 +152,35 @@ static function($assert, $start, $end, $value) {
         },
     );
 
+    yield proof(
+        'Attempt::mapErrorCase()',
+        given(
+            $exceptions,
+            $exceptions,
+            $exceptions,
+        )->filter(static fn($a, $b, $c) => !($a instanceof $c)),
+        static function($assert, $start, $end, $other) {
+            $assert->same(
+                $end,
+                Attempt::error($start)
+                    ->mapErrorCase($start::class, static fn() => $end)
+                    ->match(
+                        static fn() => null,
+                        static fn($e) => $e,
+                    ),
+            );
+            $assert->same(
+                $start,
+                Attempt::error($start)
+                    ->mapErrorCase($other::class, static fn() => $end)
+                    ->match(
+                        static fn() => null,
+                        static fn($e) => $e,
+                    ),
+            );
+        },
+    );
+
     yield proof(
         'Attempt::recover()',
         given(
@@ -203,6 +232,33 @@ static function($assert, $start, $end, $value) {
         },
     );
 
+    yield proof(
+        'Attempt::recoverCase()',
+        given(
+            $exceptions,
+            $exceptions,
+            $exceptions,
+            Set::type(),
+        )->filter(static fn($a, $b, $c) => !($a instanceof $c)),
+        static function($assert, $start, $end, $other, $value) {
+            $assert->same(
+                $value,
+                Attempt::error($start)
+                    ->recoverCase($start::class, static fn() => Attempt::result($value))
+                    ->unwrap(),
+            );
+            $assert->same(
+                $start,
+                Attempt::error($start)
+                    ->recoverCase($other::class, static fn() => Attempt::result($value))
+                    ->match(
+                        static fn() => null,
+                        static fn($e) => $e,
+                    ),
+            );
+        },
+    );
+
     yield proof(
         'Attempt::maybe()',
         given(

src/Attempt.php

@@ -172,6 +172,23 @@ public function mapError(callable $map): self
         return new self($this->implementation->mapError($map));
     }
 
+    /**
+     * @template E of \Throwable
+     *
+     * @param class-string<E> $case
+     * @param callable(E): \Throwable $map
+     *
+     * @return self<T>
+     */
+    #[\NoDiscard]
+    public function mapErrorCase(string $case, callable $map): self
+    {
+        return $this->mapError(static fn($e) => match (true) {
+            $e instanceof $case => $map($e),
+            default => $e,
+        });
+    }
+
     /**
      * @template U
      *
@@ -188,6 +205,24 @@ public function recover(callable $recover): self
         ));
     }
 
+    /**
+     * @template E of \Throwable
+     * @template U
+     *
+     * @param class-string<E> $case
+     * @param callable(E): self<U> $recover
+     *
+     * @return self<T|U>
+     */
+    #[\NoDiscard]
+    public function recoverCase(string $case, callable $recover): self
+    {
+        return $this->recover(static fn($e) => match (true) {
+            $e instanceof $case => $recover($e),
+            default => self::error($e),
+        });
+    }
+
     /**
      * This prevents guarded errors from being recovered.
      *