chore(promise): catch throwable instead of exceptions

Signed-off-by: azjezz <azjezz@protonmail.com>

CHANGELOG.md

@@ -64,3 +64,6 @@
 * introduced `Psl\Password\Algorithm` enum
 * **BC** - all constants of `Psl\Password` component has been removed.
 * **BC** - function `Psl\Password\algorithms()` have been removed.
+* **BC** - `Psl\Result\ResultInterface::getException()` method has been renamed to `Psl\Result\ResultInterface::getThrowable()`
+* **BC** - `Psl\Result\wrap` function now catches all `Throwable`s instead of only `Exception`s
+

src/Psl/Async/Awaitable.php

@@ -5,11 +5,11 @@
 namespace Psl\Async;
 
 use Closure;
-use Exception as RootException;
 use Generator;
 use Psl\Async\Internal\AwaitableIterator;
 use Psl\Async\Internal\State;
 use Psl\Promise\PromiseInterface;
+use Throwable;
 
 use function is_array;
 
@@ -72,9 +72,9 @@ public static function iterate(iterable $awaitables): Generator
 
                     /** @psalm-suppress MissingThrowsDocblock */
                     $iterator->complete();
-                } catch (RootException $exception) {
+                } catch (Throwable $throwable) {
                     /** @psalm-suppress MissingThrowsDocblock */
-                    $iterator->error($exception);
+                    $iterator->error($throwable);
                 }
                 // @codeCoverageIgnoreEnd
             });
@@ -106,12 +106,12 @@ public static function complete(mixed $result): self
     /**
      * @return Awaitable<void>
      */
-    public static function error(RootException $exception): self
+    public static function error(Throwable $throwable): self
     {
         /** @var State<void> $state */
         $state = new State();
         /** @psalm-suppress MissingThrowsDocblock */
-        $state->error($exception);
+        $state->error($throwable);
 
         return new self($state);
     }
@@ -130,8 +130,8 @@ public function isComplete(): bool
      *
      * @template Ts
      *
-     * @param (Closure(T): Ts) $success
-     * @param (Closure(RootException): Ts) $failure
+     * @param Closure(T): Ts $success
+     * @param Closure(Throwable): Ts $failure
      *
      * @return Awaitable<Ts>
      */
@@ -142,15 +142,15 @@ public function then(Closure $success, Closure $failure): Awaitable
 
         $this->state->subscribe(
             /**
-             * @param null|RootException $error
+             * @param null|Throwable $error
              * @param null|T $value
              */
-            static function (?RootException $error, mixed $value) use ($state, $success, $failure): void {
+            static function (?Throwable $error, mixed $value) use ($state, $success, $failure): void {
                 if ($error) {
                     try {
                         $state->complete($failure($error));
-                    } catch (RootException $exception) {
-                        $state->error($exception);
+                    } catch (Throwable $throwable) {
+                        $state->error($throwable);
                     }
 
                     return;
@@ -161,8 +161,8 @@ static function (?RootException $error, mixed $value) use ($state, $success, $fa
                      * @var T $value
                      */
                     $state->complete($success($value));
-                } catch (RootException $exception) {
-                    $state->error($exception);
+                } catch (Throwable $throwable) {
+                    $state->error($throwable);
                 }
             },
         );
@@ -175,21 +175,21 @@ static function (?RootException $error, mixed $value) use ($state, $success, $fa
      *
      * @template Ts
      *
-     * @param (Closure(T): Ts) $success
+     * @param Closure(T): Ts $success
      *
      * @return Awaitable<Ts>
      */
     public function map(Closure $success): Awaitable
     {
-        return $this->then($success, static fn (RootException $exception) => throw $exception);
+        return $this->then($success, static fn (Throwable $throwable) => throw $throwable);
     }
 
     /**
      * {@inheritDoc}
      *
      * @template Ts
      *
-     * @param (Closure(RootException): Ts) $failure
+     * @param Closure(Throwable): Ts $failure
      *
      * @return Awaitable<T|Ts>
      */
@@ -211,7 +211,7 @@ static function (mixed $value): mixed {
     /**
      * {@inheritDoc}
      *
-     * @param (Closure(): void) $always
+     * @param Closure(): void $always
      *
      * @return Awaitable<T>
      */
@@ -220,7 +220,7 @@ public function always(Closure $always): Awaitable
         /** @var State<T> $state */
         $state = new State();
 
-        $this->state->subscribe(static function (?RootException $error, mixed $value) use ($state, $always): void {
+        $this->state->subscribe(static function (?Throwable $error, mixed $value) use ($state, $always): void {
             try {
                 $always();
 
@@ -232,8 +232,8 @@ public function always(Closure $always): Awaitable
                      */
                     $state->complete($value);
                 }
-            } catch (RootException $exception) {
-                $state->error($exception);
+            } catch (Throwable $throwable) {
+                $state->error($throwable);
             }
         });
 
@@ -243,7 +243,7 @@ public function always(Closure $always): Awaitable
     /**
      * Awaits the operation to complete.
      *
-     * Throws an exception if the operation fails.
+     * Throws a `Throwable` if the operation fails.
      *
      * @return T
      */
@@ -253,10 +253,10 @@ public function await(): mixed
 
         $this->state->subscribe(
             /**
-             * @param null|RootException $error
+             * @param null|Throwable $error
              * @param null|T $value
              */
-            static function (?RootException $error, mixed $value) use ($suspension): void {
+            static function (?Throwable $error, mixed $value) use ($suspension): void {
                 if ($error) {
                     $suspension->throw($error);
                 } else {

src/Psl/Async/Deferred.php

@@ -4,8 +4,8 @@
 
 namespace Psl\Async;
 
-use Exception as RootException;
 use Psl;
+use Throwable;
 
 /**
  * The following class was derived from code of Amphp.
@@ -51,13 +51,13 @@ public function complete(mixed $result): void
     /**
      * Marks the operation as failed.
      *
-     * @param RootException $exception Throwable to indicate the error.
+     * @param Throwable $throwable Throwable to indicate the error.
      *
      * @throws Psl\Exception\InvariantViolationException If the operation is no longer pending.
      */
-    public function error(RootException $exception): void
+    public function error(Throwable $throwable): void
     {
-        $this->state->error($exception);
+        $this->state->error($throwable);
     }
 
     /**

src/Psl/Async/Exception/CompositeException.php

@@ -5,8 +5,8 @@
 namespace Psl\Async\Exception;
 
 use Exception;
-use Exception as RootException;
 use Psl\Str;
+use Throwable;
 
 use function count;
 
@@ -15,12 +15,12 @@
 final class CompositeException extends Exception implements ExceptionInterface
 {
     /**
-     * @var non-empty-array<array-key, RootException>
+     * @var non-empty-array<array-key, Throwable>
      */
     private array $reasons;
 
     /**
-     * @param non-empty-array<array-key, RootException> $reasons Array of exceptions.
+     * @param non-empty-array<array-key, Throwable> $reasons Array of exceptions.
      * @param string|null $message Exception message, defaults to message generated from passed exceptions.
      */
     public function __construct(array $reasons, ?string $message = null)
@@ -31,15 +31,15 @@ public function __construct(array $reasons, ?string $message = null)
     }
 
     /**
-     * @return non-empty-array<array-key, RootException>
+     * @return non-empty-array<array-key, Throwable>
      */
     public function getReasons(): array
     {
         return $this->reasons;
     }
 
     /**
-     * @param non-empty-array<array-key, RootException> $reasons
+     * @param non-empty-array<array-key, Throwable> $reasons
      */
     private function generateMessage(array $reasons): string
     {

src/Psl/Async/Exception/UnhandledAwaitableException.php

@@ -4,18 +4,18 @@
 
 namespace Psl\Async\Exception;
 
-use Exception as RootException;
 use Psl\Exception\RuntimeException;
 use Psl\Str;
+use Throwable;
 
 final class UnhandledAwaitableException extends RuntimeException implements ExceptionInterface
 {
-    public static function forException(RootException $exception): UnhandledAwaitableException
+    public static function forThrowable(Throwable $throwable): UnhandledAwaitableException
     {
         return new self(
-            Str\format('Unhandled awaitable error "%s", make sure to call `Awaitable::await()` before the awaitable is destroyed, or call `Awaitable::ignore()` to ignore exceptions.', $exception::class),
-            (int) $exception->getCode(),
-            $exception
+            Str\format('Unhandled awaitable error "%s", make sure to call `Awaitable::await()` before the awaitable is destroyed, or call `Awaitable::ignore()` to ignore exceptions.', $throwable::class),
+            (int) $throwable->getCode(),
+            $throwable
         );
     }
 }

src/Psl/Async/Internal/AwaitableIterator.php

@@ -4,9 +4,9 @@
 
 namespace Psl\Async\Internal;
 
-use Exception as RootException;
 use Psl;
 use Psl\Async\Awaitable;
+use Throwable;
 
 use function array_shift;
 use function count;
@@ -35,7 +35,7 @@ final class AwaitableIterator
     private readonly AwaitableIteratorQueue $queue;
 
     /**
-     * @var null|Awaitable<void>|Awaitable<null>|Awaitable<array{0: Tk, 1: Awaitable<Tv>}>
+     * @var null|Awaitable<void>|Awaitable<null>|Awaitable<array{Tk, Awaitable<Tv>}>
      */
     private ?Awaitable $complete = null;
 
@@ -63,9 +63,9 @@ public function enqueue(State $state, mixed $key, Awaitable $awaitable): void
              * @param Tv|null $_result
              */
             static function (
-                ?RootException $_error,
-                mixed $_result,
-                string $id
+                ?Throwable $_error,
+                mixed      $_result,
+                string     $id
             ) use (
                 $key,
                 $awaitable,
@@ -106,7 +106,7 @@ public function complete(): void
     /**
      * @throws Psl\Exception\InvariantViolationException If the iterator has already been marked as complete.
      */
-    public function error(RootException $exception): void
+    public function error(Throwable $exception): void
     {
         if (null !== $this->complete) {
             Psl\invariant_violation('Iterator has already been marked as complete');
@@ -123,7 +123,7 @@ public function error(RootException $exception): void
     /**
      * @throws Psl\Exception\InvariantViolationException If {@see consume()} is called concurrently.
      *
-     * @return null|array{0: Tk, 1: Awaitable<Tv>}
+     * @return null|array{Tk, Awaitable<Tv>}
      */
     public function consume(): ?array
     {

src/Psl/Async/Internal/State.php

@@ -5,11 +5,11 @@
 namespace Psl\Async\Internal;
 
 use Closure;
-use Exception as RootException;
 use Psl;
 use Psl\Async\Awaitable;
 use Psl\Async\Exception;
 use Psl\Async\Scheduler;
+use Throwable;
 
 /**
  * The following class was derived from code of Amphp.
@@ -36,7 +36,7 @@ final class State
     private bool $handled = false;
 
     /**
-     * @var array<string, (Closure(?RootException, ?T, string): void)>
+     * @var array<string, (Closure(?Throwable, ?T, string): void)>
      */
     private array $callbacks = [];
 
@@ -45,15 +45,15 @@ final class State
      */
     private mixed $result = null;
 
-    private ?RootException $exception = null;
+    private ?Throwable $throwable = null;
 
     /**
      * @throws Exception\UnhandledAwaitableException
      */
     public function __destruct()
     {
-        if ($this->exception && !$this->handled) {
-            throw Exception\UnhandledAwaitableException::forException($this->exception);
+        if ($this->throwable && !$this->handled) {
+            throw Exception\UnhandledAwaitableException::forThrowable($this->throwable);
         }
     }
 
@@ -62,7 +62,7 @@ public function __destruct()
      *
      * The callback is invoked directly from the event loop context, so suspension within the callback is not possible.
      *
-     * @param (Closure(?RootException, ?T, string): void) $callback Callback invoked on completion of the awaitable.
+     * @param Closure(?Throwable, ?T, string): void $callback Callback invoked on completion of the awaitable.
      *
      * @return string Identifier that can be used to cancel interest for this awaitable.
      */
@@ -74,7 +74,7 @@ public function subscribe(Closure $callback): string
         $this->handled = true;
 
         if ($this->complete) {
-            Scheduler::queue(fn() => $callback($this->exception, $this->result, $id));
+            Scheduler::queue(fn() => $callback($this->throwable, $this->result, $id));
         } else {
             $this->callbacks[$id] = $callback;
         }
@@ -121,18 +121,18 @@ public function complete(mixed $result): void
      *
      * @throws Psl\Exception\InvariantViolationException If the operation is no longer pending.
      */
-    public function error(RootException $exception): void
+    public function error(Throwable $throwable): void
     {
         if ($this->complete) {
             Psl\invariant_violation('Operation is no longer pending.');
         }
 
-        $this->exception = $exception;
+        $this->throwable = $throwable;
         $this->invokeCallbacks();
     }
 
     /**
-     * Suppress the exception thrown to the loop error handler if and operation error is not handled by a callback.
+     * Suppress the `Throwable`s thrown to the loop error handler if and operation error is not handled by a callback.
      */
     public function ignore(): void
     {
@@ -152,7 +152,7 @@ private function invokeCallbacks(): void
         $this->complete = true;
 
         foreach ($this->callbacks as $id => $callback) {
-            Scheduler::queue(fn() => $callback($this->exception, $this->result, $id));
+            Scheduler::queue(fn() => $callback($this->throwable, $this->result, $id));
         }
 
         $this->callbacks = [];