Feature/implement aggregated exception handling for invariant violations

Author: othercodes

src/Exceptions/InvariantViolation.php

@@ -4,17 +4,16 @@
 
 namespace ComplexHeart\Domain\Model\Exceptions;
 
+use ComplexHeart\Domain\Model\Contracts\Aggregatable;
 use Exception;
 
 /**
  * Class InvariantViolation
  *
- * Exception thrown when one or more invariants are violated.
- *
  * @author Unay Santisteban <usantisteban@othercode.io>
  * @package ComplexHeart\Domain\Model\Exceptions
  */
-class InvariantViolation extends Exception
+class InvariantViolation extends Exception implements Aggregatable
 {
     /**
      * @var array<int, string> List of all violation messages

src/IsModel.php

@@ -143,7 +143,7 @@ private static function validateConstructorParameters(
                 // Union type (e.g., int|float|string)
                 $isValid = self::validateUnionType($value, $type);
                 $expectedTypes = implode('|', array_map(
-                    fn($t) => $t instanceof ReflectionNamedType ? $t->getName() : 'mixed',
+                    fn ($t) => $t instanceof ReflectionNamedType ? $t->getName() : 'mixed',
                     $type->getTypes()
                 ));
             } else {

src/Traits/HasInvariants.php

@@ -4,6 +4,7 @@
 
 namespace ComplexHeart\Domain\Model\Traits;
 
+use ComplexHeart\Domain\Model\Contracts\Aggregatable;
 use ComplexHeart\Domain\Model\Exceptions\InvariantViolation;
 use Throwable;
 
@@ -110,6 +111,15 @@ private function computeInvariantViolations(string $exception): array
         return $violations;
     }
 
+    /**
+     * Compute the invariant handler function.
+     *
+     * The handler is responsible for throwing exceptions (single or aggregated).
+     *
+     * @param  string|callable  $handlerFn
+     * @param  string  $exception
+     * @return callable
+     */
     private function computeInvariantHandler(string|callable $handlerFn, string $exception): callable
     {
         if (!is_string($handlerFn)) {
@@ -121,24 +131,45 @@ private function computeInvariantHandler(string|callable $handlerFn, string $exc
                 $this->{$handlerFn}($violations, $exception);
             }
         : function (array $violations) use ($exception): void {
-            // Always aggregate violations for InvariantViolation
-            if ($exception === InvariantViolation::class) {
-                $messages = map(fn (Throwable $e): string => $e->getMessage(), $violations);
-                throw InvariantViolation::fromViolations(array_values($messages));
-            }
+            $this->throwInvariantViolations($violations, $exception);
+        };
+    }
 
-            // Legacy behavior for custom exception classes
-            if (count($violations) === 1) {
-                throw array_shift($violations);
+    /**
+     * Throw invariant violations (single or aggregated).
+     *
+     * Responsible for all exception throwing logic:
+     * - Non-aggregatable exceptions: throw the first one immediately
+     * - Aggregatable exceptions: aggregate and throw as InvariantViolation
+     *
+     * @param array<string, Throwable> $violations
+     * @param string $exception
+     * @return void
+     * @throws Throwable
+     */
+    private function throwInvariantViolations(array $violations, string $exception): void
+    {
+        // Separate aggregatable from non-aggregatable violations
+        $aggregatable = [];
+        $nonAggregatable = [];
+
+        foreach ($violations as $key => $violation) {
+            if ($violation instanceof Aggregatable) {
+                $aggregatable[$key] = $violation;
+            } else {
+                $nonAggregatable[$key] = $violation;
             }
+        }
 
-            throw new $exception( // @phpstan-ignore-line
-                sprintf(
-                    "Unable to create %s due: %s",
-                    basename(str_replace('\\', '/', static::class)),
-                    implode(", ", map(fn (Throwable $e): string => $e->getMessage(), $violations)),
-                )
-            );
-        };
+        // If there are non-aggregatable exceptions, throw the first one immediately
+        if (!empty($nonAggregatable)) {
+            throw array_shift($nonAggregatable);
+        }
+
+        // All violations are aggregatable - aggregate them
+        if (!empty($aggregatable)) {
+            $messages = map(fn (Throwable $e): string => $e->getMessage(), $aggregatable);
+            throw InvariantViolation::fromViolations(array_values($messages));
+        }
     }
 }

tests/TraitsTest.php

@@ -2,6 +2,7 @@
 
 declare(strict_types=1);
 
+use ComplexHeart\Domain\Model\Contracts\Aggregatable;
 use ComplexHeart\Domain\Model\Errors\ImmutabilityError;
 use ComplexHeart\Domain\Model\Exceptions\InvariantViolation;
 use ComplexHeart\Domain\Model\Test\Fixtures\OrderManagement\Domain\Errors\InvalidPriceError;
@@ -17,17 +18,17 @@
 
 test('Object with HasImmutability should expose primitive values.', function () {
     $price = new Price(100.0, 'EUR');
-    expect($price->amount)->toBeFloat();
-    expect($price->currency)->toBeString();
+    expect($price->amount)->toBeFloat()
+        ->and($price->currency)->toBeString();
 })
     ->group('Unit');
 
 test('Object with HasImmutability should return new instance with override values.', function () {
     $price = new Price(100.0, 'EUR');
     $newPrice = $price->applyDiscount(10.0);
 
-    expect($newPrice)->toBeInstanceOf(Price::class);
-    expect($newPrice->amount)->toBe(90.0);
+    expect($newPrice)->toBeInstanceOf(Price::class)
+        ->and($newPrice->amount)->toBe(90.0);
 })
     ->group('Unit');
 
@@ -165,3 +166,112 @@ protected function invariantSingleFailure(): bool
         ->and($exception->getMessage())->toBe('Single error message');
 })
     ->group('Unit');
+
+test('Custom non-aggregatable exception should be thrown immediately', function () {
+    new class () {
+        use HasInvariants;
+
+        public function __construct()
+        {
+            $this->check();
+        }
+
+        protected function invariantCustomError(): bool
+        {
+            throw new DomainException('Custom domain error');
+        }
+    };
+})
+    ->group('Unit')
+    ->throws(DomainException::class, 'Custom domain error');
+
+test('Custom non-aggregatable exception stops invariant checking', function () {
+    new class () {
+        use HasInvariants;
+
+        public function __construct()
+        {
+            $this->check();
+        }
+
+        protected function invariantFirstCheck(): bool
+        {
+            // This should throw immediately
+            throw new RuntimeException('First error');
+        }
+
+        protected function invariantSecondCheck(): bool
+        {
+            // This should NEVER be reached
+            throw new DomainException('Second error - should not be reached');
+        }
+    };
+})
+    ->group('Unit')
+    ->throws(RuntimeException::class, 'First error');
+
+test('Custom aggregatable exception should be aggregated', function () {
+    try {
+        new class () {
+            use HasInvariants;
+
+            public function __construct()
+            {
+                $this->check();
+            }
+
+            protected function invariantFirst(): bool
+            {
+                // Create aggregatable exception inline
+                $exception = new class ('Aggregatable error') extends \Exception implements Aggregatable {};
+                throw $exception;
+            }
+
+            protected function invariantSecond(): bool
+            {
+                return false; // Regular InvariantViolation
+            }
+        };
+    } catch (InvariantViolation $e) {
+        expect($e->hasMultipleViolations())->toBeTrue()
+            ->and($e->getViolationCount())->toBe(2)
+            ->and($e->getViolations())->toContain('Aggregatable error')
+            ->and($e->getViolations())->toContain('second');
+    }
+})
+    ->group('Unit');
+
+test('InvariantViolation implements Aggregatable', function () {
+    $exception = InvariantViolation::fromViolations(['Test']);
+
+    expect($exception)->toBeInstanceOf(Aggregatable::class);
+})
+    ->group('Unit');
+
+test('Mix of custom non-aggregatable throws immediately before aggregation', function () {
+    new class () {
+        use HasInvariants;
+
+        public function __construct()
+        {
+            $this->check();
+        }
+
+        protected function invariantFirstAggregatable(): bool
+        {
+            return false; // InvariantViolation
+        }
+
+        protected function invariantCustomNonAggregatable(): bool
+        {
+            throw new RuntimeException('Non-aggregatable error');
+        }
+
+        protected function invariantThirdAggregatable(): bool
+        {
+            return false; // Should not be reached
+        }
+    };
+})
+    ->group('Unit')
+    ->throws(RuntimeException::class, 'Non-aggregatable error');

tests/ValueObjectsTest.php

@@ -55,7 +55,7 @@
         protected string $_pattern = '[a-z]';
     };
 })
-    ->throws(InvariantViolation::class)
+    ->throws(InvalidArgumentException::class) // Non-aggregatable, thrown immediately
     ->group('Unit');
 
 test('BooleanValue should create a valid BooleanValue Object.', function () {