Add generics for Promise.

docs/class-reference.md

@@ -76,6 +76,8 @@ static function executeQuery(
  * @param array<string, mixed>|null  $variableValues
  * @param array<ValidationRule>|null $validationRules
  *
+ * @return Promise<ExecutionResult>
+ *
  * @api
  */
 static function promiseToExecute(
@@ -1305,6 +1307,8 @@ static function execute(
  * @param mixed                     $contextValue
  * @param array<string, mixed>|null $variableValues
  *
+ * @return Promise<ExecutionResult>
+ *
  * @phpstan-param FieldResolver|null $fieldResolver
  *
  * @api
@@ -1457,7 +1461,11 @@ function isThenable($value): bool
 /**
  * Converts thenable of the underlying platform into GraphQL\Executor\Promise\Promise instance.
  *
- * @param mixed $thenable
+ * @template T
+ *
+ * @param T $thenable
+ *
+ * @return Promise<T>
  *
  * @api
  */
@@ -1466,8 +1474,22 @@ function convertThenable($thenable): GraphQL\Executor\Promise\Promise
 
 ```php
 /**
- * Accepts our Promise wrapper, extracts adopted promise out of it and executes actual `then` logic described
- * in Promises/A+ specs. Then returns new wrapped instance of GraphQL\Executor\Promise\Promise.
+ * Accepts our Promise wrapper, extracts adopted promise out of it and executes actual `then` logic described in Promises/A+ specs.
+ * Then returns new wrapped instance of @see \GraphQL\Executor\Promise\Promise.
+ *
+ * @template T
+ * @template TFulfilled of mixed
+ * @template TRejected of mixed
+ *
+ * @param Promise<T> $promise
+ * @param (callable(T): (Promise<TFulfilled>|TFulfilled))|null $onFulfilled
+ * @param (callable(\Throwable): (Promise<TRejected>|TRejected))|null $onRejected
+ *
+ * @return Promise<(
+ *   $onFulfilled is not null
+ *     ? ($onRejected is not null ? TFulfilled|TRejected : TFulfilled)
+ *     : ($onRejected is not null ? TRejected : T)
+ * )>
  *
  * @api
  */
@@ -1482,7 +1504,11 @@ function then(
 /**
  * Creates a Promise from the given resolver callable.
  *
- * @param callable(callable $resolve, callable $reject): void $resolver
+ * @template V
+ *
+ * @param callable(callable(V): void $resolve, callable(\Throwable): void $reject): void $resolver
+ *
+ * @return Promise<V>
  *
  * @api
  */
@@ -1493,7 +1519,11 @@ function create(callable $resolver): GraphQL\Executor\Promise\Promise
 /**
  * Creates a fulfilled Promise for a value if the value is not a promise.
  *
- * @param mixed $value
+ * @template V
+ *
+ * @param V $value
+ *
+ * @return Promise<V>
  *
  * @api
  */
@@ -1506,6 +1536,8 @@ function createFulfilled($value = null): GraphQL\Executor\Promise\Promise
  *
  * If the provided reason is a promise, then it is returned as-is.
  *
+ * @return Promise<null>
+ *
  * @api
  */
 function createRejected(Throwable $reason): GraphQL\Executor\Promise\Promise
@@ -1516,7 +1548,11 @@ function createRejected(Throwable $reason): GraphQL\Executor\Promise\Promise
  * Given an iterable of promises (or values), returns a promise that is fulfilled when all the
  * items in the iterable are fulfilled.
  *
- * @param iterable<Promise|mixed> $promisesOrValues
+ * @template V
+ *
+ * @param iterable<V> $promisesOrValues
+ *
+ * @return Promise<array<V>>
  *
  * @api
  */
@@ -1874,7 +1910,7 @@ function handleRequest($parsedBody = null): void
  *
  * @param OperationParams|array<OperationParams> $parsedBody
  *
- * @return ExecutionResult|array<int, ExecutionResult>|Promise
+ * @return ExecutionResult|array<ExecutionResult>|Promise<ExecutionResult>|Promise<array<ExecutionResult>>
  *
  * @api
  */
@@ -1888,7 +1924,7 @@ function executeRequest($parsedBody = null)
  * See `executePsrRequest()` if you prefer to create response yourself
  * (e.g. using specific JsonResponse instance of some framework).
  *
- * @return ResponseInterface|Promise
+ * @return ResponseInterface|Promise<ResponseInterface>
  *
  * @api
  */
@@ -1904,7 +1940,7 @@ function processPsrRequest(
  * Executes GraphQL operation and returns execution result
  * (or promise when promise adapter is different from SyncPromiseAdapter).
  *
- * @return ExecutionResult|array<int, ExecutionResult>|Promise
+ * @return ExecutionResult|array<ExecutionResult>|Promise<ExecutionResult>|Promise<array<ExecutionResult>>
  *
  * @api
  */
@@ -2116,7 +2152,7 @@ function validateOperationParams(GraphQL\Server\OperationParams $params): array
  * Executes GraphQL operation with given server configuration and returns execution result
  * (or promise when promise adapter is different from SyncPromiseAdapter).
  *
- * @return ExecutionResult|Promise
+ * @return ExecutionResult|Promise<ExecutionResult>
  *
  * @api
  */
@@ -2130,7 +2166,7 @@ function executeOperation(GraphQL\Server\ServerConfig $config, GraphQL\Server\Op
  *
  * @param array<OperationParams> $operations
  *
- * @return array<int, ExecutionResult>|Promise
+ * @return array<ExecutionResult>|Promise<array<ExecutionResult>>
  *
  * @api
  */
@@ -2141,7 +2177,7 @@ function executeBatch(GraphQL\Server\ServerConfig $config, array $operations)
 /**
  * Send response using standard PHP `header()` and `echo`.
  *
- * @param Promise|ExecutionResult|array<ExecutionResult> $result
+ * @param Promise<ExecutionResult>|Promise<array<ExecutionResult>>|ExecutionResult|array<ExecutionResult> $result
  *
  * @api
  */
@@ -2165,9 +2201,9 @@ function parsePsrRequest(Psr\Http\Message\RequestInterface $request)
 /**
  * Converts query execution result to PSR-7 response.
  *
- * @param Promise|ExecutionResult|array<ExecutionResult> $result
+ * @param Promise<ExecutionResult>|Promise<array<ExecutionResult>>|ExecutionResult|array<ExecutionResult> $result
  *
- * @return Promise|ResponseInterface
+ * @return Promise<ResponseInterface>|ResponseInterface
  *
  * @api
  */

src/Deferred.php

@@ -5,23 +5,21 @@
 use GraphQL\Executor\Promise\Adapter\SyncPromise;
 
 /**
- * @phpstan-import-type Executor from SyncPromise
+ * @template V
+ *
+ * @extends SyncPromise<V>
  */
 class Deferred extends SyncPromise
 {
     /**
-     * @param Executor $executor
+     * @template T
+     *
+     * @param callable(): T $executor
+     *
+     * @return self<T>
      */
     public static function create(callable $executor): self
     {
         return new self($executor);
     }
-
-    /**
-     * @param Executor $executor
-     */
-    public function __construct(callable $executor)
-    {
-        parent::__construct($executor);
-    }
 }

src/Executor/Executor.php

@@ -132,6 +132,8 @@ public static function execute(
      * @param mixed                     $contextValue
      * @param array<string, mixed>|null $variableValues
      *
+     * @return Promise<ExecutionResult>
+     *
      * @phpstan-param FieldResolver|null $fieldResolver
      *
      * @api

src/Executor/ExecutorImplementation.php

@@ -8,6 +8,8 @@ interface ExecutorImplementation
 {
     /**
      * Returns promise of {@link ExecutionResult}. Promise should always resolve, never reject.
+     *
+     * @return Promise<ExecutionResult>
      */
     public function doExecute(): Promise;
 }

src/Executor/Promise/Adapter/SyncPromise.php

@@ -15,7 +15,7 @@
  * The whole point of Deferred is to ensure it never happens and that any resolver creates
  * at least one $executor to start the promise chain.
  *
- * @phpstan-type Executor callable(): mixed
+ * @template V
  */
 class SyncPromise
 {
@@ -34,7 +34,7 @@ class SyncPromise
      * @var array<
      *     int,
      *     array{
-     *         self,
+     *         self<V>,
      *         (callable(mixed): mixed)|null,
      *         (callable(\Throwable): mixed)|null
      *     }
@@ -52,7 +52,7 @@ public static function runQueue(): void
     }
 
     /**
-     * @param Executor|null $executor
+     * @param (callable(): V)|null $executor
      */
     public function __construct(?callable $executor = null)
     {
@@ -71,6 +71,8 @@ public function __construct(?callable $executor = null)
 
     /**
      * @param mixed $value
+     *
+     * @return self<V>
      */
     public function resolve($value): self
     {
@@ -110,6 +112,9 @@ function ($reason): void {
         return $this;
     }
 
+    /**
+     * @return self<null>
+     */
     public function reject(\Throwable $reason): self
     {
         switch ($this->state) {
@@ -175,8 +180,17 @@ public static function getQueue(): \SplQueue
     }
 
     /**
-     * @param (callable(mixed): mixed)|null $onFulfilled
-     * @param (callable(\Throwable): mixed)|null $onRejected
+     * @template VFulfilled
+     * @template VRejected
+     *
+     * @param (callable(V): VFulfilled)|null $onFulfilled
+     * @param (callable(\Throwable): VRejected)|null $onRejected
+     *
+     * @return self<(
+     *   $onFulfilled is not null
+     *     ? ($onRejected is not null ? VFulfilled|VRejected : VFulfilled)
+     *     : ($onRejected is not null ? VRejected : V)
+     * )>
      */
     public function then(?callable $onFulfilled = null, ?callable $onRejected = null): self
     {
@@ -200,6 +214,8 @@ public function then(?callable $onFulfilled = null, ?callable $onRejected = null
 
     /**
      * @param callable(\Throwable): mixed $onRejected
+     *
+     * @return self<null>
      */
     public function catch(callable $onRejected): self
     {

src/Executor/Promise/Adapter/SyncPromiseAdapter.php

@@ -110,7 +110,13 @@ static function ($value) use (&$result, $index, &$count, &$resolveAllWhenFinishe
     /**
      * Synchronously wait when promise completes.
      *
-     * @return mixed
+     * @template V
+     *
+     * @param Promise<V> $promise
+     *
+     * @throws InvariantViolation
+     *
+     * @return V
      */
     public function wait(Promise $promise)
     {
@@ -141,13 +147,17 @@ public function wait(Promise $promise)
 
     /**
      * Execute just before starting to run promise completion.
+     *
+     * @param Promise<mixed> $promise
      */
     protected function beforeWait(Promise $promise): void
     {
     }
 
     /**
      * Execute while running promise completion.
+     *
+     * @param Promise<mixed> $promise
      */
     protected function onWait(Promise $promise): void
     {

src/Executor/Promise/Promise.php

@@ -3,33 +3,43 @@
 namespace GraphQL\Executor\Promise;
 
 use Amp\Promise as AmpPromise;
-use GraphQL\Error\InvariantViolation;
 use GraphQL\Executor\Promise\Adapter\SyncPromise;
 use React\Promise\PromiseInterface as ReactPromise;
 
 /**
  * Convenience wrapper for promises represented by Promise Adapter.
+ *
+ * @template T
  */
 class Promise
 {
-    /** @var SyncPromise|ReactPromise|AmpPromise<mixed> */
+    /** @var SyncPromise<T>|ReactPromise|AmpPromise<T> */
     public $adoptedPromise;
 
     private PromiseAdapter $adapter;
 
     /**
-     * @param mixed $adoptedPromise
+     * @param SyncPromise<T>|ReactPromise|AmpPromise<T> $adoptedPromise
      */
     public function __construct($adoptedPromise, PromiseAdapter $adapter)
     {
-        if ($adoptedPromise instanceof self) {
-            throw new InvariantViolation('Expecting promise from adapted system, got ' . self::class);
-        }
-
         $this->adoptedPromise = $adoptedPromise;
         $this->adapter = $adapter;
     }
 
+    /**
+     * @template TFulfilled
+     * @template TRejected
+     *
+     * @param (callable(T): (Promise<TFulfilled>|TFulfilled))|null $onFulfilled
+     * @param (callable(mixed): (Promise<TRejected>|TRejected))|null $onRejected
+     *
+     * @return Promise<(
+     *   $onFulfilled is not null
+     *     ? ($onRejected is not null ? TFulfilled|TRejected : TFulfilled)
+     *     : ($onRejected is not null ? TRejected : T)
+     * )>
+     */
     public function then(?callable $onFulfilled = null, ?callable $onRejected = null): Promise
     {
         return $this->adapter->then($this, $onFulfilled, $onRejected);