improve TryBox

Author: epic-31

README.md

@@ -1,13 +1,11 @@
 # Welcome to PhpBox
 
-PhpBox contains exactly one class: `Box`.
-
-You can find it here: [src/Box.php](src/Box.php)
+PhpBox contains two classes:
+- `Box` [src/Box.php](src/Box.php)
+- `TryBox` [src/TryBox.php](src/TryBox.php)
 
 # Installation
-Currently, there is no composer package. 
-
-Simply copy the `Box.php` file to your project and adjust its namespace if needed.
+A composer package is in the works, but I recommend just copying the files into your project for now.
 
 # Requirements
 The only hard requirement is PHP 8.0 or higher.
@@ -23,25 +21,20 @@ You put any value into a box.
 
 Then you can chain map(), dump() and assert() calls on it.
 
-To get the value out of the box, call unbox() or get().
+To get the value out of the box, call value() or get().
 
-## Note
-In an earlier version:
-- map() was called pipe()
-- get() was called pull()
-
-## Examples
+## Box Examples
 
 ```php
 $value = Box::of(5)
     ->map(fn($value) => $value + 1)
     ->map(fn($value) => $value * 2)
-    ->unbox();
+    ->value();
 
 echo $value; // 12
 ```
 
-Use get() to combine map() and unbox() in one call:
+Use get() to combine map() and value() in one call:
 ```php
 $value = Box::of(5)
     ->map(fn($value) => $value + 1)
@@ -57,7 +50,7 @@ $isEven = fn($value) => $value % 2 === 0;
 $value = Box::of(5)
     ->map(fn($it) => $it + 1)->assert(6)
     ->map(fn($it) => $it * 2)->assert($isEven)->dump()
-    ->unbox();
+    ->value();
 
 echo $value; // 12
 ```
@@ -96,14 +89,74 @@ function assertEmail(Box $box): Box
         ->assert(fn(string $x) => filter_var($x, FILTER_VALIDATE_EMAIL), 'Not an email');
 }
 
-$validEmail = Box::of('')->flatMap(assertEmail(...))->unbox();
+$validEmail = Box::of('')->flatMap(assertEmail(...))->value();
 // throws LogicException: "Too short"
 
 $user = Box::of('john@example.org')
     ->mod(fn($box) => assertEmail($box))
     ->get(fn($email) => $userRepository->create(['email' => $email]));
 ```
 
+## TryBox Examples
+
+TryBox works just like Box, except that it catches any and all errors instead of blowing up directly.
+Its value() method has a more complicated return type, which is either T or Throwable.
+- advantage: you can run a chain without risk of blowing up (subsequent map() calls will be skipped),
+and then decide what to do with the error at the end.
+- disadvantage: you have to handle the error case even if you're sure it will never happen.
+
+Let's define a realistic function that sometimes throws an error (like a database call or an API request). In this
+case it either returns whatever was passed in or throws a RuntimeException at random.
+```php
+/**
+  * @template T
+  * @param T $value
+  * @return T
+  *
+  * @throws RuntimeException 
+  */
+function roulette($value)
+{
+    if (random_int(0, 1) === 1) {
+        throw new RuntimeException('boo');
+    }
+    
+    return $value;
+}
+```
+
+Let's use this dangerous function in a TryBox chain:
+```php
+$result = TryBox::of(5)
+    ->map(fn($value) => roulette($value)) // TryBox stores the exception
+    ->map(fn($value) => $value * 2)
+    ->map(fn($value) => $value + 1)
+    ->value();
+
+// type signature is int|Throwable, so we have to handle the error case
+if ($result instanceof Throwable) {
+    echo $result->getMessage(); // boo
+    return;
+}
+
+// if we reach this line, $result is guaranteed to be an int
+$calc = $result + 1;
+echo $calc;
+```
+
+If you are sure the error case will never happen, or simply don't care, you can use rip() instead of value():
+`rip()` will either throw the stored error (if any) or return the value of type T.
+```php
+$result = TryBox::of(5)
+    ->map(fn($value) => roulette($value))
+    ->map(fn($value) => $value * 2)
+    ->map(fn($value) => $value + 1)
+    ->rip(); // The original runtime exception will be thrown here, if present
+
+// if we reach this line, $result is guaranteed to be an int
+$calc = $result + 1;
+```
+
 # Type Safety
 Thanks to meticulously crafted PHPDoc annotations, this class is type safe if you use PHPStan for static analysis.
 

src/Box.php

@@ -118,20 +118,6 @@ public function assert(mixed $check, string $message = ''): 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->value();
-    }
-
     /**
      * Dump the value to the console.
      *

src/TryBox.php

@@ -7,7 +7,8 @@
 
 /**
  * A container that allows chaining transformations and assertions on a value.
- * Will catch exceptions and return them as a value.
+ * value() will return T|Throwable (must be narrowed manually with error handling).
+ * rip() will return T, but throws an exception if there is an error.
  *
  * @template T
  * @template E

tests/Unit/BoxTest.php

@@ -60,16 +60,6 @@
     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);
-});
-
 test('flatMap allows us to replace the box itself', function () {
     $result = Box::of(5)
         ->mod(fn(Box $x) => $x->assert(5)->map(fn($x) => $x + 1))