Every throwable (except InvalidPipe) is converted to InvalidPipeline.

This change is to streamline and better typehint expected exception for projects implementing Pipeline.
- Removed checking container has item before resolving in Pipeline Bridge.

Author: hsehszroc

Src/InvalidPipeline.php

@@ -8,5 +8,18 @@
 namespace TheWebSolver\Codegarage\Lib;
 
 use Exception;
+use Throwable;
 
-class InvalidPipeline extends Exception {}
+class InvalidPipeline extends Exception {
+	public function __construct( Throwable $previous, private readonly mixed $subject = null ) {
+		parent::__construct( $previous->getMessage(), $previous->getCode(), $previous );
+	}
+
+	public function hasSubject(): bool {
+		return isset( $this->subject );
+	}
+
+	public function getSubject(): mixed {
+		return $this->subject;
+	}
+}

Src/Pipeline.php

@@ -5,6 +5,7 @@
  * @package TheWebSolver\Codegarage\Library
  *
  * @phpcs:disable Squiz.Commenting.FunctionComment.ParamNameNoMatch, Squiz.Commenting.FunctionComment.IncorrectTypeHint -- Closure type-hint OK.
+ * @phpcs:disable Squiz.Commenting.FunctionCommentThrowTag.WrongNumber -- Accuracy is deceiving!!!
  */
 
 declare( strict_types = 1 );
@@ -32,7 +33,6 @@ class Pipeline {
 	 * @throws InvalidPipeline When could not determine thrown exception.
 	 * @phpstan-param class-string<Pipe>|Pipe|Closure(mixed $subject, Closure $next, mixed ...$use): mixed $pipe
 	 */
-	// phpcs:ignore Squiz.Commenting.FunctionCommentThrowTag.WrongNumber -- Exactly 2 exception thrown.
 	final public static function resolve( string|Closure|Pipe $pipe ): Closure {
 		$isClassName = is_string( $pipe ) && class_exists( $pipe );
 
@@ -44,7 +44,7 @@ final public static function resolve( string|Closure|Pipe $pipe ): Closure {
 				$pipe instanceof Closure => $pipe,
 			};
 		} catch ( Throwable $e ) {
-			self::throw( $e );
+			throw self::getException( $e );
 		}
 	}
 
@@ -109,16 +109,20 @@ public function pipe( string|Closure|Pipe $pipe ): static {
 	 * @throws InvalidPipe            When pipe type could not be resolved.
 	 * @throws InvalidPipeline When a pipe abrupt the pipeline by throwing an exception & sealWith not used.
 	 */
-	// phpcs:ignore Squiz.Commenting.FunctionCommentThrowTag.Missing -- Doesn't throw throwable.
 	public function then( Closure $return ): mixed {
 		$use     = $this->use ?? array();
 		$pipes   = array_reverse( $this->pipes );
 		$subject = $this->subject;
 
 		try {
 			return array_reduce( $pipes, $this->chain( ... ), $return )( $subject, ...$use );
-		} catch ( Throwable $e ) {
-			return ( $seal = $this->catcher ?? null ) ? $seal( $e, ...$use ) : self::throw( $e );
+		} catch ( InvalidPipe|InvalidPipeline $e ) {
+			if ( ! $sealer = ( $this->catcher ?? null ) ) {
+				throw $e;
+			}
+
+			// "InvalidPipe" is an internal error. Must be fixed and should never be sealed.
+			return $e instanceof InvalidPipe ? throw $e : $sealer( $e, ...$use );
 		}
 	}
 
@@ -134,12 +138,22 @@ public function thenReturn() {
 
 	/** Gets a Closure that wraps current pipe with the next pipe in the pipeline. */
 	protected function chain( Closure $next, string|Closure|Pipe $current ): Closure {
-		return fn ( $subject ) => self::resolve( $current )( $subject, $next, ...( $this->use ?? array() ) );
+		return function ( $subject ) use ( $current, $next ) {
+			try {
+				return self::resolve( $current )( $subject, $next, ...( $this->use ?? array() ) );
+			} catch ( Throwable $e ) {
+				// Here, exception can be anything besides Pipe & Pipeline exception. This exception may be
+				// thrown when pipe is handling the subject. We'll need to convert whatever thrown back to
+				// the InvalidPipeline exception and silently pass the previous subject through this new
+				// InvalidPipeline exception so that it can be consumed and/or handled by the client.
+				throw self::getException( $e, $subject );
+			}
+		};
 	}
 
-	private static function throw( Throwable $e ): never {
-		throw $e instanceof InvalidPipe
-			? $e
-			: new InvalidPipeline( $e->getMessage(), $e->getCode(), $e );
+	private static function getException( Throwable $previous ): InvalidPipe|InvalidPipeline {
+		return ! $previous instanceof InvalidPipe
+			? new InvalidPipeline( $previous, subject: func_num_args() === 2 ? func_get_arg( 1 ) : null )
+			: $previous;
 	}
 }

Src/PipelineBridge.php

@@ -84,14 +84,9 @@ public static function toMiddleware( mixed $middleware ): object {
 			throw $e instanceof InvalidMiddlewareForPipe
 				? $e
 				: ( ! is_string( $middleware )
-					? new InvalidPipeline( $e->getMessage(), $e->getCode(), $e )
-					: new InvalidMiddlewareForPipe(
-						sprintf(
-							'The given middleware classname: "%1$s" must be an instance of "%2$s".',
-							$middleware,
-							$interface
-						)
-					) );
+					? new InvalidPipeline( $e )
+					: new InvalidMiddlewareForPipe( $e->getMessage(), $e->getCode(), $e )
+				);
 		}//end try
 	}
 
@@ -115,7 +110,7 @@ protected static function getPipeHandler( object $with, array $args ) {
 	}
 
 	public static function make( string $className ): object {
-		return isset( static::$container ) && static::$container->has( id: $className )
+		return isset( static::$container )
 			? static::$container->get( id: $className )
 			: new $className();
 	}