add option-type approach for result handling

composer.json

@@ -23,7 +23,8 @@
         "php": ">=8.2",
         "psr/container": "^2.0",
         "psr/log": "^3.0",
-        "symfony/service-contracts": "^3.4"
+        "symfony/service-contracts": "^3.4",
+        "yceruto/option-type": "^1.0"
     },
     "require-dev": {
         "vimeo/psalm": "^5.0",

src/Envelope/Envelope.php

@@ -15,6 +15,9 @@
 
 use OpenSolid\Bus\Envelope\Stamp\HandledStamp;
 use OpenSolid\Bus\Envelope\Stamp\Stamps;
+use Std\Type\None;
+use Std\Type\Option;
+use Std\Type\Some;
 
 /**
  * A message envelope that wraps a message and its stamps.
@@ -33,16 +36,17 @@ public static function wrap(Message $message, array $stamps = []): self
         return new self($message, $stamps);
     }
 
-    public function unwrap(): mixed
+    public function unwrap(): Option
     {
         $results = $this->stamps
             ->filter(HandledStamp::class, fn (HandledStamp $stamp): bool => null !== $stamp->result)
-            ->map(HandledStamp::class, fn (HandledStamp $stamp): mixed => $stamp->result);
+            ->map(HandledStamp::class, fn (HandledStamp $stamp): mixed => $stamp->result)
+        ;
 
         return match (\count($results)) {
-            0 => null,
-            1 => $results[0],
-            default => $results,
+            0 => new None(),
+            1 => new Some($results[0]),
+            default => new Some($results),
         };
     }
 

src/Envelope/Stamp/Stamps.php

@@ -13,6 +13,11 @@
 
 namespace OpenSolid\Bus\Envelope\Stamp;
 
+use Std\Type\None;
+use Std\Type\Option;
+use Std\Type\OptionFactory;
+use Std\Type\Some;
+
 /**
  * A collection of stamps.
  *
@@ -53,25 +58,25 @@ public function has(string $class): bool
     /**
      * @param class-string<T> $class
      *
-     * @return T|null
+     * @return None|Some<T>
      */
-    public function first(string $class): ?Stamp
+    public function first(string $class): None|Some
     {
-        return $this->collection[$class][0] ?? null;
+        return OptionFactory::from($this->collection[$class][0] ?? null);
     }
 
     /**
      * @param class-string<T> $class
      *
-     * @return T|null
+     * @return None|Some<T>
      */
-    public function last(string $class): ?Stamp
+    public function last(string $class): Option
     {
         if ([] === $stamps = $this->collection[$class] ?? []) {
-            return null;
+            return new None();
         }
 
-        return $this->collection[$class][\count($stamps) - 1];
+        return new Some($this->collection[$class][\count($stamps) - 1]);
     }
 
     /**

src/LazyMessageBus.php

@@ -14,12 +14,13 @@
 namespace OpenSolid\Bus;
 
 use OpenSolid\Bus\Envelope\Message;
+use Std\Type\None;
 
 /**
  * A bus responsible for dispatching messages lazily to their handlers.
  * The messages are stored in an internal queue and dispatched when the bus is flushed.
  */
 interface LazyMessageBus extends MessageBus, FlushableMessageBus
 {
-    public function dispatch(Message $message): null;
+    public function dispatch(Message $message): None;
 }

src/MessageBus.php

@@ -14,12 +14,13 @@
 namespace OpenSolid\Bus;
 
 use OpenSolid\Bus\Envelope\Message;
+use Std\Type\Option;
 
 /**
  * A bus responsible for dispatching messages to their handlers
  * and returning a result.
  */
 interface MessageBus
 {
-    public function dispatch(Message $message): mixed;
+    public function dispatch(Message $message): Option;
 }

src/NativeLazyMessageBus.php

@@ -14,6 +14,7 @@
 namespace OpenSolid\Bus;
 
 use OpenSolid\Bus\Envelope\Message;
+use Std\Type\None;
 use Symfony\Contracts\Service\ResetInterface;
 
 final class NativeLazyMessageBus implements LazyMessageBus, ResetInterface
@@ -25,11 +26,11 @@ public function __construct(
     ) {
     }
 
-    public function dispatch(Message $message): null
+    public function dispatch(Message $message): None
     {
         $this->messages[] = $message;
 
-        return null;
+        return new None();
     }
 
     public function flush(): void

src/NativeMessageBus.php

@@ -17,6 +17,7 @@
 use OpenSolid\Bus\Envelope\Message;
 use OpenSolid\Bus\Middleware\Middleware;
 use OpenSolid\Bus\Middleware\MiddlewareStack;
+use Std\Type\Option;
 
 final readonly class NativeMessageBus implements MessageBus
 {
@@ -30,7 +31,7 @@ public function __construct(iterable $middlewares)
         $this->middlewares = new MiddlewareStack($middlewares);
     }
 
-    public function dispatch(Message $message): mixed
+    public function dispatch(Message $message): Option
     {
         $envelope = Envelope::wrap($message);
 

tests/Bridge/Symfony/DependencyInjection/CompilerPass/MessageHandlersLocatorPassTest.php

@@ -43,8 +43,8 @@ public function testMultipleMessageHandlingProcess(): void
         $middleware = $container->get('handling_middleware');
         $middleware->handle($envelope, new NoneMiddleware());
 
-        $this->assertIsArray($envelope->unwrap());
-        $this->assertCount(2, $envelope->unwrap());
+        $this->assertTrue($envelope->unwrap()->isSome());
+        $this->assertCount(2, $envelope->unwrap()->unwrap());
     }
 
     public function testInvalidSingleMessageHandlingProcess(): void

tests/Envelope/EnvelopeTest.php

@@ -31,25 +31,29 @@ public function testNullResult(): void
     {
         $envelope = Envelope::wrap(new MyMessage());
 
-        $this->assertNull($envelope->unwrap());
+        $result = $envelope->unwrap();
+
+        $this->assertTrue($result->isNone());
     }
 
     public function testSingleResult(): void
     {
         $envelope = Envelope::wrap(new MyMessage());
-
         $envelope->stamps->add(new HandledStamp(true));
 
-        $this->assertTrue($envelope->unwrap());
+        $result = $envelope->unwrap();
+
+        $this->assertTrue($result->isSome());
     }
 
     public function testMultipleResults(): void
     {
         $envelope = Envelope::wrap(new MyMessage());
-
         $envelope->stamps->add(new HandledStamp(true));
         $envelope->stamps->add(new HandledStamp(false));
 
-        $this->assertSame([true, false], $envelope->unwrap());
+        $result = $envelope->unwrap();
+
+        $this->assertSame([true, false], $result->unwrap());
     }
 }

tests/Envelope/Stamp/StampsTest.php

@@ -50,8 +50,8 @@ public function testFirst(): void
 
         $first = $stamps->first(HandledStamp::class);
 
-        $this->assertNotNull($first);
-        $this->assertTrue($first->result);
+        $this->assertNotNull($first->unwrap());
+        $this->assertTrue($first->unwrap()->result);
     }
 
     public function testLast(): void
@@ -63,8 +63,8 @@ public function testLast(): void
 
         $last = $stamps->last(HandledStamp::class);
 
-        $this->assertNotNull($last);
-        $this->assertFalse($last->result);
+        $this->assertNotNull($last->unwrap());
+        $this->assertFalse($last->unwrap()->result);
     }
 
     public function testFilter(): void

tests/Middleware/HandlingMiddlewareTest.php

@@ -35,7 +35,9 @@ public function testHandle(): void
         $envelop = Envelope::wrap($message);
         $middleware->handle($envelop, new NoneMiddleware());
 
-        $this->assertSame($message, $envelop->unwrap());
+        $result = $envelop->unwrap();
+
+        $this->assertSame($message, $result->unwrap());
     }
 
     public function testNoHandlerForObject(): void

tests/Middleware/MiddlewareStackTest.php

@@ -50,6 +50,8 @@ public function handle(Envelope $envelope, NextMiddleware $next): void
         $envelope = Envelope::wrap(new MyMessage());
         $stack->handle($envelope);
 
-        $this->assertSame(['1', '2', '3'], $envelope->unwrap());
+        $result = $envelope->unwrap();
+
+        $this->assertSame(['1', '2', '3'], $result->unwrap());
     }
 }

tests/NativeLazyMessageBusTest.php

@@ -28,7 +28,9 @@ public function testLazyDispatchingDoNotHandleImmediately(): void
 
         $bus = new NativeLazyMessageBus(new NativeMessageBus([$middleware]));
 
-        $this->assertNull($bus->dispatch(new MyMessage()));
+        $result = $bus->dispatch(new MyMessage());
+
+        $this->assertTrue($result->isNone());
     }
 
     public function testLazyDispatchingHandleWhenFlush(): void

tests/NativeMessageBusTest.php

@@ -31,6 +31,9 @@ public function testDispatch(): void
         ]);
         $message = new MyMessage();
 
-        $this->assertSame($message, $bus->dispatch($message));
+        $result = $bus->dispatch($message);
+
+        $this->assertTrue($result->isSome());
+        $this->assertSame($message, $result->unwrap());
     }
 }