add more examples

Author: epic-31

README.md

@@ -84,24 +84,28 @@ $user = Box::of($inputEmail)
     ->get(fn($it) => $userRepository->create(['email' => $it]));
 ```
 
-Or make it shorter by using higher abstraction levels:
-
+Using flatMap, you can compose presets of operations on boxes:
 ```php
-// potentially defined elsewhere
-function isValidEmail(mixed $email): bool
+/** @throws LogicException */
+function assertEmail(Box $box): Box
 {
-    return is_string($email) 
-        && strlen($email) > 0
-        && strlen($email) < 256
-        && filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
+    return $box
+        ->assert(fn($x)        => is_string($x), 'Not a string')
+        ->assert(fn(string $x) => strlen($x) > 0, 'Too short')
+        ->assert(fn(string $x) => strlen($x) < 256, 'Too long')
+        ->assert(fn(string $x) => filter_var($x, FILTER_VALIDATE_EMAIL), 'Not an email');
 }
 
-$validEmail = Box::of('john.doe@example.org')->assertGet(isValidEmail(...));
-// $validEmail === 'john.doe@example.org'
+$validEmail = Box::of('')->flatMap(assertEmail(...))->unbox();
+// throws LogicException: "Value is too short"
 
-$validEmail2 = Box::of('asdf')->assertGet(isValidEmail(...));
-// throws LogicException
+$user = Box::of('john@example.org')
+    ->flatMap(fn($box) => assertEmail($box))
+    ->get(fn($email) => $userRepository->create(['email' => $email]));
 ```
+Note, in this example we still have 4 separate assertions and error messages.
+Using flatMap is the key here. Unlike map(), which transforms the value inside the Box,
+flatMap() transforms the Box itself. This allows us to compose behavior in a more functional way.
 
 # Type Safety
 Thanks to meticulously crafted PHPDoc annotations, this class is type safe if you use PHPStan for static analysis.

src/Box.php

@@ -45,6 +45,20 @@ public function map(callable $callback): Box
         return new self($callback($this->value));
     }
 
+    /**
+     * Apply a transformation function to the box itself
+     *
+     * This method will always return a new instance of Box, even for objects.
+     *
+     * @template U
+     * @param callable(self<T>): Box<U> $callback
+     * @return Box<U>
+     */
+    public function flatMap(callable $callback): Box
+    {
+        return $callback($this);
+    }
+
     /**
      * Unwrap the value and apply a final transformation on it.
      * Can be used instead of `unbox` to terminate the sequence.
@@ -77,7 +91,7 @@ public function unbox()
      * @param U|callable(T):bool $check
      * @return Box<T>
      */
-    public function assert(mixed $check): Box
+    public function assert(mixed $check, string $message = ''): Box
     {
         $isClosure = is_callable($check);
 
@@ -86,15 +100,19 @@ public function assert(mixed $check): Box
             : $this->value === $check;
 
         if (! $pass) {
-            $message = $isClosure
+            $report = $isClosure
                 ? 'Value did not pass the callback check.'
                 : sprintf(
                     'Failed asserting that two values are the same. Expected %s, got %s.',
                     var_export($check, true),
                     var_export($this->value, true)
                 );
 
-            throw new LogicException($message);
+            if ($message !== '') {
+                $report = $message . ' | ' . $report;
+            }
+
+            throw new LogicException($report);
         }
 
         return $this;

tests/Unit/BoxTest.php

@@ -70,6 +70,27 @@
     expect(fn() => Box::of(5)->assertGet(6))->toThrow(LogicException::class);
 });
 
+test('flatMap allows us to replace the box itself', function () {
+    $result = Box::of(5)
+        ->flatMap(fn(Box $x) => $x->assert(5)->map(fn($x) => $x + 1))
+        ->unbox();
+
+    expect($result)->toBe(6);
+});
+
+test('use flatMap to compose actions', function () {
+    $isValidEmail = function (Box $box) {
+        return $box
+            ->assert(fn(mixed $x)  => is_string($x), 'Not a string')
+            ->assert(fn(string $x) => strlen($x) > 0, 'Too short')
+            ->assert(fn(string $x) => strlen($x) < 256, 'Too long')
+            ->assert(fn(string $x) => filter_var($x, FILTER_VALIDATE_EMAIL), 'Not an email');
+    };
+
+    expect(fn() => Box::of('asdf')->flatMap($isValidEmail)->unbox())
+        ->toThrow(LogicException::class, 'Not an email | Value did not pass the callback check.');
+});
+
 // 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];