introduce Option::ensure(), Result::ensure()

Author: someniatko

src/Error.php

@@ -52,4 +52,9 @@ public function getOrThrow(\Throwable $e)
     {
         throw $e;
     }
+
+    public function ensure(callable $condition, $else): ResultInterface
+    {
+        return $this;
+    }
 }

src/None.php

@@ -34,4 +34,9 @@ public function getOrThrow(\Throwable $e)
     {
         throw $e;
     }
+
+    public function ensure(callable $condition): Option
+    {
+        return $this;
+    }
 }

src/Option.php

@@ -14,6 +14,7 @@ abstract class Option
     private static ?None $none = null;
 
     /**
+     * @psalm-pure
      * @template TNew
      * @param TNew $value
      * @return Some<TNew>
@@ -24,10 +25,12 @@ public static function some($value): Some
     }
 
     /**
+     * @psalm-pure
      * @return None
      */
     public static function none(): None
     {
+        /** @psalm-suppress ImpureStaticProperty */
         return self::$none ??= new None();
     }
 
@@ -113,6 +116,16 @@ abstract public function getOrElse($else);
      */
     abstract public function getOrThrow(\Throwable $e);
 
+    /**
+     * Ensures that Some value also validates against the given condition,
+     * Otherwise returns None.
+     *
+     * @return Option<TValue>
+     *
+     * @param callable(TValue):bool $condition
+     */
+    abstract public function ensure(callable $condition): Option;
+
     /**
      * @template TElse
      * @param TElse $else

src/Result.php

@@ -13,6 +13,7 @@
 abstract class Result implements ResultInterface
 {
     /**
+     * @psalm-pure
      * @template T
      * @param T $value
      * @return Success<T>
@@ -23,6 +24,7 @@ public static function success($value): Success
     }
 
     /**
+     * @psalm-pure
      * @template T
      * @param T $value
      * @return Error<T>

src/ResultInterface.php

@@ -78,4 +78,18 @@ public function getOr(callable $map);
      * @return TSuccess|never-return
      */
     public function getOrThrow(\Throwable $e);
+
+    /**
+     * Ensures that the Success value also validates against the given condition,
+     * Otherwise returns an Error with a given value.
+     *
+     * If this Result is already an Error, nothing will change.
+     *
+     * @template TNewError
+     *
+     * @param callable(TSuccess):bool $condition
+     * @param TNewError $else
+     * @return ResultInterface<TSuccess, TError|TNewError>
+     */
+    public function ensure(callable $condition, $else): self;
 }

src/Some.php

@@ -46,4 +46,11 @@ public function getOrThrow(\Throwable $e)
     {
         return $this->value;
     }
+
+    public function ensure(callable $condition): Option
+    {
+        return $condition($this->value)
+            ? $this
+            : Option::none();
+    }
 }

src/Success.php

@@ -51,4 +51,11 @@ public function getOrThrow(\Throwable $e)
     {
         return $this->value;
     }
+
+    public function ensure(callable $condition, $else): ResultInterface
+    {
+        return $condition($this->value)
+            ? $this
+            : Result::error($else);
+    }
 }

test/OptionTest.php

@@ -124,4 +124,26 @@ public function testToNullableNone(): void
         $nullable = $option->toNullable();
         self::assertNull($nullable);
     }
+
+    public function testEnsureSomeReturningTrue(): void
+    {
+        $option = Option::some(111);
+        $ensured = $option->ensure(fn (int $i) => $i > 100);
+        self::assertEquals(111, $ensured->getOrElse(null));
+    }
+
+    public function testEnsureSomeReturningFalse(): void
+    {
+        $option = Option::some(111);
+        $ensured = $option->ensure(fn (int $i) => $i < 100);
+        self::assertEquals(null, $ensured->getOrElse(null));
+    }
+
+    public function testEnsureNone(): void
+    {
+        /** @var Option<int> $option */
+        $option = Option::none();
+        $ensured = $option->ensure(fn (int $i) => $i > 100);
+        self::assertEquals(null, $ensured->getOrElse(null));
+    }
 }

test/ResultTest.php

@@ -173,4 +173,25 @@ public function testErrors(): void
 
         self::assertEquals([ 3, 5 ], Result::extractErrors($results));
     }
+
+    public function testEnsureSuccessReturningTrue(): void
+    {
+        $result = Result::success(123);
+        $ensured = $result->ensure(fn(int $i) => $i > 100, 'failed');
+        self::assertEquals(123, $ensured->get());
+    }
+
+    public function testEnsureSuccessReturningFalse(): void
+    {
+        $result = Result::success(123);
+        $ensured = $result->ensure(fn(int $i) => $i < 100, 'failed');
+        self::assertEquals('failed', $ensured->get());
+    }
+
+    public function testEnsureErrorDoesNotChangePreviousError(): void
+    {
+        $result = Result::error('old error');
+        $ensured = $result->ensure(fn(int $i) => $i > 100, 'new error');
+        self::assertEquals('old error', $ensured->get());
+    }
 }