make Promise use template for exception

in httplug, we have documentation text that formulates that only
specific exceptions may be used for the callback. the change in 1.2.0 to
allow any Throwable was incorrect.

Author: dbu

.github/workflows/tests.yml

@@ -69,6 +69,9 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v3
 
+      - name: Remove phpspec
+        run: composer remove --dev friends-of-phpspec/phpspec-code-coverage phpspec/phpspec
+
       - name: PHPStan
         uses: OskarStark/phpstan-ga@0.12.32
         env:

CHANGELOG.md

@@ -1,8 +1,14 @@
 # Change Log
 
-## 1.2.1
+## 1.2.2 - unreleased
 
-### Added - 2023-11-08
+### Fixed
+
+- Changed `Promise` to use a template for the exception class that is allowed.
+
+## 1.2.1 - 2023-11-08
+
+### Fixed
 
 - Fixed PHPDoc for `wait()` and `then()`'s `onRejected` callable
 

src/FulfilledPromise.php

@@ -9,7 +9,7 @@
  *
  * @template-covariant T
  *
- * @implements Promise<T>
+ * @implements Promise<T, \Throwable>
  */
 final class FulfilledPromise implements Promise
 {
@@ -26,9 +26,6 @@ public function __construct($result)
         $this->result = $result;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function then(callable $onFulfilled = null, callable $onRejected = null)
     {
         if (null === $onFulfilled) {
@@ -37,28 +34,22 @@ public function then(callable $onFulfilled = null, callable $onRejected = null)
 
         try {
             return new self($onFulfilled($this->result));
-        } catch (\Exception $e) {
+        } catch (\Throwable $e) {
             return new RejectedPromise($e);
         }
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function getState()
     {
         return Promise::FULFILLED;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function wait($unwrap = true)
     {
         if ($unwrap) {
             return $this->result;
         }
 
-        return;
+        return null;
     }
 }

src/Promise.php

@@ -14,6 +14,8 @@
  * @author Márk Sági-Kazár <mark.sagikazar@gmail.com>
  *
  * @template-covariant T
+ *
+ * @template E of \Throwable
  */
 interface Promise
 {
@@ -38,10 +40,10 @@ interface Promise
      * If you do not care about one of the cases, you can set the corresponding callable to null
      * The callback will be called when the value arrived and never more than once.
      *
-     * @param callable(T): V|null          $onFulfilled called when a response will be available
-     * @param callable(\Throwable): V|null $onRejected  called when an exception occurs
+     * @param callable(T): V|null $onFulfilled called when a response will be available
+     * @param callable(E): V|null $onRejected  called when an exception occurs
      *
-     * @return Promise<V> a new resolved promise with value of the executed callback (onFulfilled / onRejected)
+     * @return Promise<V, E> a new resolved promise with value of the executed callback (onFulfilled / onRejected)
      *
      * @template V
      */
@@ -67,7 +69,7 @@ public function getState();
      *
      * @return ($unwrap is true ? T : null) Resolved value, null if $unwrap is set to false
      *
-     * @throws \Exception the rejection reason if $unwrap is set to true and the request failed
+     * @throws E the rejection reason if $unwrap is set to true and the request failed
      */
     public function wait($unwrap = true);
 }

src/RejectedPromise.php

@@ -9,23 +9,20 @@
  *
  * @template-covariant T
  *
- * @implements Promise<T>
+ * @implements Promise<T, \Throwable>
  */
 final class RejectedPromise implements Promise
 {
     /**
-     * @var \Exception
+     * @var \Throwable
      */
     private $exception;
 
-    public function __construct(\Exception $exception)
+    public function __construct(\Throwable $exception)
     {
         $this->exception = $exception;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function then(callable $onFulfilled = null, callable $onRejected = null)
     {
         if (null === $onRejected) {
@@ -34,28 +31,22 @@ public function then(callable $onFulfilled = null, callable $onRejected = null)
 
         try {
             return new FulfilledPromise($onRejected($this->exception));
-        } catch (\Exception $e) {
+        } catch (\Throwable $e) {
             return new self($e);
         }
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function getState()
     {
         return Promise::REJECTED;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function wait($unwrap = true)
     {
         if ($unwrap) {
             throw $this->exception;
         }
 
-        return;
+        return null;
     }
 }