add more examples

Author: epic-31

README.md

@@ -96,7 +96,7 @@ function isValidEmail(mixed $email): bool
         && filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
 }
 
-$validEmail = Box::of($input)->assert(isValidEmail(...))->unbox();
+$validEmail = Box::of($input)->assertGet(isValidEmail(...));
 ```
 
 # Type Safety

src/Box.php

@@ -100,6 +100,20 @@ public function assert(mixed $check): Box
         return $this;
     }
 
+    /**
+     * Run an assertion against the value and return it.
+     *
+     * @template U
+     * @param U|callable(T):bool $check
+     * @return T
+     */
+    public function assertGet(mixed $check): mixed
+    {
+        $this->assert($check);
+
+        return $this->unbox();
+    }
+
     /**
      * Dump the value to the console.
      *

tests/Unit/BoxTest.php

@@ -60,6 +60,16 @@
     expect($result->number)->toBe(5);
 });
 
+test('assertGet returns the value when the assertion passes', function () {
+    $result = Box::of(5)->assertGet(5);
+
+    expect($result)->toBe(5);
+});
+
+test('assertGet throws an exception when the assertion fails', function () {
+    expect(fn() => Box::of(5)->assertGet(6))->toThrow(LogicException::class);
+});
+
 // This test is not here to "lock in" desired behavior. It is here to document a pitfall.
 test('performing a mutation on an object using map() will produce side effects', function () {
     $object = (object)['number' => 5];