Add generics for Promise.

docs/class-reference.md

@@ -75,6 +75,7 @@ static function executeQuery(
  * @param mixed                      $context
  * @param array<string, mixed>|null  $variableValues
  * @param array<ValidationRule>|null $validationRules
+ * @return Promise<ExecutionResult>
  *
  * @api
  */
@@ -1305,6 +1306,8 @@ static function execute(
  * @param mixed                     $contextValue
  * @param array<string, mixed>|null $variableValues
  *
+ * @return Promise<ExecutionResult>
+ *
  * @phpstan-param FieldResolver|null $fieldResolver
  *
  * @api
@@ -1471,6 +1474,20 @@ function convertThenable($thenable): 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 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(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)
+ * )>
+ *
  * @api
  */
 function then(
@@ -1484,7 +1501,9 @@ 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
  */
@@ -1495,7 +1514,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
  */
@@ -1518,7 +1541,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<Promise<V>|V> $promisesOrValues
+ *
+ * @return Promise<V[]>
  *
  * @api
  */
@@ -1876,7 +1903,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
  */
@@ -1890,7 +1917,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
  */
@@ -1906,7 +1933,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
  */
@@ -2118,7 +2145,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
  */
@@ -2132,7 +2159,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
  */
@@ -2143,7 +2170,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
  */
@@ -2167,9 +2194,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/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/SyncPromiseAdapter.php

@@ -31,6 +31,21 @@ public function convertThenable($thenable): Promise
         return new Promise($thenable, $this);
     }
 
+    /**
+     * @template T
+     * @template TFulfilled of mixed
+     * @template TRejected of mixed
+     *
+     * @param Promise<T> $promise
+     * @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(Promise $promise, ?callable $onFulfilled = null, ?callable $onRejected = null): Promise
     {
         $adoptedPromise = $promise->adoptedPromise;
@@ -55,20 +70,41 @@ public function create(callable $resolver): Promise
         return new Promise($promise, $this);
     }
 
+    /**
+     * @template V
+     *
+     * @param V $value
+     *
+     * @return Promise<V>
+     */
     public function createFulfilled($value = null): Promise
     {
         $promise = new SyncPromise();
 
         return new Promise($promise->resolve($value), $this);
     }
 
+    /**
+     * @template V of \Throwable
+     *
+     * @param V $reason
+     *
+     * @return Promise<V>
+     */
     public function createRejected(\Throwable $reason): Promise
     {
         $promise = new SyncPromise();
 
         return new Promise($promise->reject($reason), $this);
     }
 
+    /**
+     * @template V
+     *
+     * @param iterable<Promise<V>|V> $promisesOrValues
+     *
+     * @return Promise<V[]>
+     */
     public function all(iterable $promisesOrValues): Promise
     {
         \assert(
@@ -113,7 +149,13 @@ static function ($value) use ($index, &$count, $total, &$result, $all): void {
     /**
      * Synchronously wait when promise completes.
      *
-     * @return mixed
+     * @template V
+     *
+     * @param Promise<V> $promise
+     *
+     * @throws InvariantViolation
+     *
+     * @return V
      */
     public function wait(Promise $promise)
     {
@@ -144,13 +186,21 @@ public function wait(Promise $promise)
 
     /**
      * Execute just before starting to run promise completion.
+     *
+     * @template V
+     *
+     * @param Promise<V> $promise
      */
     protected function beforeWait(Promise $promise): void
     {
     }
 
     /**
      * Execute while running promise completion.
+     *
+     * @template V
+     *
+     * @param Promise<V> $promise
      */
     protected function onWait(Promise $promise): void
     {

src/Executor/Promise/Promise.php

@@ -9,6 +9,8 @@
 
 /**
  * Convenience wrapper for promises represented by Promise Adapter.
+ *
+ * @template T
  */
 class Promise
 {
@@ -30,6 +32,19 @@ public function __construct($adoptedPromise, PromiseAdapter $adapter)
         $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);

src/Executor/Promise/PromiseAdapter.php

@@ -29,14 +29,32 @@ public function convertThenable($thenable): 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 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(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)
+     * )>
+     *
      * @api
      */
     public function then(Promise $promise, ?callable $onFulfilled = null, ?callable $onRejected = null): Promise;
 
     /**
      * 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
      */
@@ -45,7 +63,11 @@ public function create(callable $resolver): 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
      */
@@ -64,7 +86,11 @@ public function createRejected(\Throwable $reason): 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<Promise<V>|V> $promisesOrValues
+     *
+     * @return Promise<V[]>
      *
      * @api
      */