Add comprehensive type annotations and improve type safety across async interfaces

Author: rcalicdan

src/Async/Handlers/AsyncExecutionHandler.php

@@ -4,6 +4,7 @@
 
 use Fiber;
 use Rcalicdan\FiberAsync\EventLoop\EventLoop;
+use Rcalicdan\FiberAsync\Promise\Interfaces\PromiseInterface;
 use Rcalicdan\FiberAsync\Promise\Promise;
 use Throwable;
 
@@ -22,13 +23,13 @@
      * The returned function, when called, will execute the original function
      * inside a Fiber and return a Promise that resolves with the result.
      *
-     * @param  callable  $asyncFunction  The function to make asynchronous
-     * @return callable A function that returns a Promise when called
+     * @param callable $asyncFunction The function to make asynchronous.
+     * @return callable(...mixed): PromiseInterface<mixed> A function that returns a Promise when called.
      */
     public function async(callable $asyncFunction): callable
     {
-        return function (...$args) use ($asyncFunction) {
-            return new Promise(function ($resolve, $reject) use ($asyncFunction, $args) {
+        return function (...$args) use ($asyncFunction): PromiseInterface {
+            return new Promise(function (callable $resolve, callable $reject) use ($asyncFunction, $args) {
                 $fiber = new Fiber(function () use ($asyncFunction, $args, $resolve, $reject) {
                     try {
                         $result = $asyncFunction(...$args);
@@ -42,4 +43,4 @@ public function async(callable $asyncFunction): callable
             });
         };
     }
-}
+}

src/Async/Interfaces/AsyncOperationsInterface.php

@@ -3,6 +3,7 @@
 namespace Rcalicdan\FiberAsync\Async\Interfaces;
 
 use Rcalicdan\FiberAsync\Promise\Interfaces\PromiseInterface;
+use Throwable;
 
 /**
  * Provides core asynchronous operations for fiber-based async programming.
@@ -15,23 +16,24 @@ interface AsyncOperationsInterface
     /**
      * Checks if the current execution context is within a fiber.
      *
-     * @return bool True if executing within a fiber, false otherwise
+     * @return bool True if executing within a fiber, false otherwise.
      */
     public function inFiber(): bool;
 
     /**
      * Creates a resolved promise with the given value.
      *
-     * @param  mixed  $value  The value to resolve the promise with
-     * @return PromiseInterface A promise resolved with the provided value
+     * @template T
+     * @param T $value The value to resolve the promise with.
+     * @return PromiseInterface<T> A promise resolved with the provided value.
      */
     public function resolve(mixed $value): PromiseInterface;
 
     /**
      * Creates a rejected promise with the given reason.
      *
-     * @param  mixed  $reason  The reason for rejection (typically an exception or error message)
-     * @return PromiseInterface A promise rejected with the provided reason
+     * @param mixed $reason The reason for rejection (typically an exception or error message).
+     * @return PromiseInterface<mixed> A promise rejected with the provided reason.
      */
     public function reject(mixed $reason): PromiseInterface;
 
@@ -41,8 +43,8 @@ public function reject(mixed $reason): PromiseInterface;
      * The returned callable will execute the original function within a fiber
      * and return a promise that resolves with the function's result.
      *
-     * @param  callable  $asyncFunction  The function to wrap asynchronously
-     * @return callable A callable that returns a PromiseInterface
+     * @param callable $asyncFunction The function to wrap asynchronously.
+     * @return callable(): PromiseInterface<mixed> A callable that returns a PromiseInterface.
      */
     public function async(callable $asyncFunction): callable;
 
@@ -52,18 +54,18 @@ public function async(callable $asyncFunction): callable;
      * This method should only be called within a fiber context.
      * It will yield control back to the event loop until the promise settles.
      *
-     * @param  PromiseInterface  $promise  The promise to await
-     * @return mixed The resolved value of the promise
-     *
-     * @throws mixed The rejection reason if the promise is rejected
+     * @template T
+     * @param PromiseInterface<T> $promise The promise to await.
+     * @return T The resolved value of the promise.
+     * @throws Throwable The rejection reason if the promise is rejected.
      */
     public function await(PromiseInterface $promise): mixed;
 
     /**
-     * Creates a promise that resolves after the specified delay.
+     * Creates a promise that resolves with null after the specified delay.
      *
-     * @param  float  $seconds  The delay in seconds (supports fractions for milliseconds)
-     * @return PromiseInterface A promise that resolves after the delay
+     * @param float $seconds The delay in seconds (supports fractions for milliseconds).
+     * @return PromiseInterface<null> A promise that resolves with null after the delay.
      */
     public function delay(float $seconds): PromiseInterface;
 
@@ -73,8 +75,8 @@ public function delay(float $seconds): PromiseInterface;
      * Returns a promise that resolves with an array of all resolved values
      * in the same order as the input promises, or rejects with the first rejection.
      *
-     * @param  array  $promises  Array of PromiseInterface instances
-     * @return PromiseInterface A promise that resolves with an array of results
+     * @param array<PromiseInterface<mixed>> $promises Array of PromiseInterface instances.
+     * @return PromiseInterface<array<mixed>> A promise that resolves with an array of results.
      */
     public function all(array $promises): PromiseInterface;
 
@@ -84,8 +86,8 @@ public function all(array $promises): PromiseInterface;
      * The returned promise will resolve or reject with the value/reason
      * of whichever input promise settles first.
      *
-     * @param  array  $promises  Array of PromiseInterface instances
-     * @return PromiseInterface A promise that settles with the first settled promise
+     * @param array<PromiseInterface<mixed>> $promises Array of PromiseInterface instances.
+     * @return PromiseInterface<mixed> A promise that settles with the first settled promise.
      */
     public function race(array $promises): PromiseInterface;
 
@@ -95,9 +97,9 @@ public function race(array $promises): PromiseInterface;
      * Limits the number of simultaneously executing tasks while ensuring
      * all tasks eventually complete.
      *
-     * @param  array  $tasks  Array of callable tasks that return promises
-     * @param  int  $concurrency  Maximum number of concurrent executions (default: 10)
-     * @return PromiseInterface A promise that resolves when all tasks complete
+     * @param array<callable(): PromiseInterface<mixed>> $tasks Array of callable tasks that return promises.
+     * @param int $concurrency Maximum number of concurrent executions (default: 10).
+     * @return PromiseInterface<array<mixed>> A promise that resolves with an array of all results when all tasks complete.
      */
     public function concurrent(array $tasks, int $concurrency = 10): PromiseInterface;
 
@@ -107,10 +109,10 @@ public function concurrent(array $tasks, int $concurrency = 10): PromiseInterfac
      * This method processes tasks in smaller batches, allowing for
      * controlled concurrency and resource management.
      *
-     * @param  array  $tasks  Array of tasks (callables or promises) to execute
-     * @param  int  $batchSize  Size of each batch to process concurrently
-     * @param  int  $concurrency  Maximum number of concurrent executions per batch
-     * @return PromiseInterface A promise that resolves with all results
+     * @param array<callable(): PromiseInterface<mixed>> $tasks Array of tasks (callables that return promises) to execute.
+     * @param int $batchSize Size of each batch to process concurrently.
+     * @param int|null $concurrency Maximum number of concurrent executions per batch.
+     * @return PromiseInterface<array<mixed>> A promise that resolves with all results.
      */
     public function batch(array $tasks, int $batchSize = 10, ?int $concurrency = null): PromiseInterface;
-}
+}

src/Promise/Interfaces/PromiseInterface.php

@@ -2,6 +2,8 @@
 
 namespace Rcalicdan\FiberAsync\Promise\Interfaces;
 
+use LogicException;
+
 /**
  * Represents the eventual result of an asynchronous operation.
  *
@@ -18,7 +20,8 @@ interface PromiseInterface
      * Once resolved, the promise cannot be resolved or rejected again.
      * All attached fulfillment handlers will be called with the value.
      *
-     * @param  mixed  $value  The value to resolve the promise with
+     * @param TValue $value The value to resolve the promise with.
+     * @return void
      */
     public function resolve(mixed $value): void;
 
@@ -28,21 +31,22 @@ public function resolve(mixed $value): void;
      * Once rejected, the promise cannot be resolved or rejected again.
      * All attached rejection handlers will be called with the reason.
      *
-     * @param  mixed  $reason  The reason for rejection (typically an exception or error message)
+     * @param mixed $reason The reason for rejection (typically an exception or error message).
+     * @return void
      */
     public function reject(mixed $reason): void;
 
     /**
      * Attaches handlers for promise fulfillment and/or rejection.
      *
      * Returns a new promise that will be resolved or rejected based on
-     * the return value of the executed handler.
+     * the return value of the executed handler. This allows for chaining and
+     * transforming values.
      *
-     * @param  callable|null  $onFulfilled  Handler for successful resolution with signature:
-     *                                      function(mixed $value): mixed
-     * @param  callable|null  $onRejected  Handler for rejection with signature:
-     *                                     function(mixed $reason): mixed
-     * @return PromiseInterface A new promise for method chaining
+     * @template TResult
+     * @param callable(TValue): (TResult|PromiseInterface<TResult>) $onFulfilled Handler for successful resolution.
+     * @param callable(mixed): (TResult|PromiseInterface<TResult>) $onRejected Handler for rejection.
+     * @return PromiseInterface<TResult> A new promise for method chaining.
      */
     public function then(?callable $onFulfilled = null, ?callable $onRejected = null): PromiseInterface;
 
@@ -51,9 +55,9 @@ public function then(?callable $onFulfilled = null, ?callable $onRejected = null
      *
      * Equivalent to calling then(null, $onRejected).
      *
-     * @param  callable  $onRejected  Handler for rejection with signature:
-     *                                function(mixed $reason): mixed
-     * @return PromiseInterface A new promise for method chaining
+     * @template TResult
+     * @param callable(mixed): (TResult|PromiseInterface<TResult>) $onRejected Handler for rejection.
+     * @return PromiseInterface<TResult> A new promise for method chaining.
      */
     public function catch(callable $onRejected): PromiseInterface;
 
@@ -63,30 +67,28 @@ public function catch(callable $onRejected): PromiseInterface;
      * The finally handler receives no arguments and its return value
      * does not affect the promise chain unless it throws an exception.
      *
-     * @param  callable  $onFinally  Handler to execute after settlement with signature:
-     *                               function(): mixed
-     * @return PromiseInterface A new promise for method chaining
+     * @return PromiseInterface<TValue> A new promise that will settle with the same outcome as the original.
      */
     public function finally(callable $onFinally): PromiseInterface;
 
     /**
      * Checks if the promise has been resolved with a value.
      *
-     * @return bool True if resolved, false otherwise
+     * @return bool True if resolved, false otherwise.
      */
     public function isResolved(): bool;
 
     /**
      * Checks if the promise has been rejected with a reason.
      *
-     * @return bool True if rejected, false otherwise
+     * @return bool True if rejected, false otherwise.
      */
     public function isRejected(): bool;
 
     /**
      * Checks if the promise is still pending (neither resolved nor rejected).
      *
-     * @return bool True if pending, false otherwise
+     * @return bool True if pending, false otherwise.
      */
     public function isPending(): bool;
 
@@ -96,9 +98,8 @@ public function isPending(): bool;
      * This method should only be called after confirming the promise
      * is resolved using isResolved().
      *
-     * @return mixed The resolved value
-     *
-     * @throws \LogicException If called on a non-resolved promise
+     * @return TValue The resolved value.
+     * @throws LogicException If called on a non-resolved promise.
      */
     public function getValue(): mixed;
 
@@ -108,9 +109,8 @@ public function getValue(): mixed;
      * This method should only be called after confirming the promise
      * is rejected using isRejected().
      *
-     * @return mixed The rejection reason
-     *
-     * @throws \LogicException If called on a non-rejected promise
+     * @return mixed The rejection reason.
+     * @throws LogicException If called on a non-rejected promise.
      */
     public function getReason(): mixed;
 }