Add comprehensive type annotations to AsyncPDO class

- Add generic type parameters and return type annotations for all public methods
- Specify array shapes using PHPDoc syntax for better type safety
- Add template types for callback parameters and return values
- Replace loose array types with specific array<key, value> annotations
- Improve null safety checks and comparisons
- Remove unused PromiseCollectionHandler import and use global functions

Author: rcalicdan

src/Api/AsyncPDO.php

@@ -3,7 +3,6 @@
 namespace Rcalicdan\FiberAsync\Api;
 
 use PDO;
-use Rcalicdan\FiberAsync\Async\Handlers\PromiseCollectionHandler;
 use Rcalicdan\FiberAsync\PDO\AsyncPdoPool;
 use Rcalicdan\FiberAsync\Promise\CancellablePromise;
 use Rcalicdan\FiberAsync\Promise\Interfaces\PromiseInterface;
@@ -30,7 +29,7 @@ final class AsyncPDO
      * This is the single point of configuration and must be called before
      * using any other AsyncPDO methods. Multiple calls are ignored.
      *
-     * @param  array  $dbConfig  Database configuration array containing:
+     * @param  array<string, mixed>  $dbConfig  Database configuration array containing:
      *                           - dsn: Database connection string
      *                           - username: Database username
      *                           - password: Database password
@@ -55,7 +54,7 @@ public static function init(array $dbConfig, int $poolSize = 10): void
      */
     public static function reset(): void
     {
-        if (self::$pool) {
+        if (self::$pool !== null) {
             self::$pool->close();
         }
         self::$pool = null;
@@ -68,23 +67,23 @@ public static function reset(): void
      * Automatically handles connection acquisition and release. The callback
      * receives a PDO instance and can perform any database operations.
      *
-     * @param  callable  $callback  Function that receives PDO instance
-     *                              Signature: function(PDO $pdo): mixed
-     * @return PromiseInterface Promise resolving to callback's return value
+     * @template TResult
+     * @param  callable(PDO): TResult  $callback  Function that receives PDO instance
+     * @return PromiseInterface<TResult> Promise resolving to callback's return value
      *
      * @throws \RuntimeException If AsyncPDO is not initialized
      */
     public static function run(callable $callback): PromiseInterface
     {
-        return Async::async(function () use ($callback) {
+        return Async::async(function () use ($callback): mixed {
             $pdo = null;
 
             try {
                 $pdo = await(self::getPool()->get());
 
                 return $callback($pdo);
             } finally {
-                if ($pdo) {
+                if ($pdo !== null) {
                     self::getPool()->release($pdo);
                 }
             }
@@ -95,15 +94,15 @@ public static function run(callable $callback): PromiseInterface
      * Executes a SELECT query and returns all matching rows.
      *
      * @param  string  $sql  SQL query with optional parameter placeholders
-     * @param  array  $params  Parameter values for prepared statement
-     * @return PromiseInterface Promise resolving to array of associative arrays
+     * @param  array<string|int, mixed>  $params  Parameter values for prepared statement
+     * @return PromiseInterface<array<int, array<string, mixed>>> Promise resolving to array of associative arrays
      *
      * @throws \RuntimeException If AsyncPDO is not initialized
      * @throws \PDOException If query execution fails
      */
     public static function query(string $sql, array $params = []): PromiseInterface
     {
-        return self::run(function (PDO $pdo) use ($sql, $params) {
+        return self::run(function (PDO $pdo) use ($sql, $params): array {
             $stmt = $pdo->prepare($sql);
             $stmt->execute($params);
 
@@ -115,15 +114,15 @@ public static function query(string $sql, array $params = []): PromiseInterface
      * Executes a SELECT query and returns the first matching row.
      *
      * @param  string  $sql  SQL query with optional parameter placeholders
-     * @param  array  $params  Parameter values for prepared statement
-     * @return PromiseInterface Promise resolving to associative array or false if no rows
+     * @param  array<string|int, mixed>  $params  Parameter values for prepared statement
+     * @return PromiseInterface<array<string, mixed>|false> Promise resolving to associative array or false if no rows
      *
      * @throws \RuntimeException If AsyncPDO is not initialized
      * @throws \PDOException If query execution fails
      */
     public static function fetchOne(string $sql, array $params = []): PromiseInterface
     {
-        return self::run(function (PDO $pdo) use ($sql, $params) {
+        return self::run(function (PDO $pdo) use ($sql, $params): array|false {
             $stmt = $pdo->prepare($sql);
             $stmt->execute($params);
 
@@ -135,31 +134,52 @@ public static function fetchOne(string $sql, array $params = []): PromiseInterfa
      * Executes an INSERT, UPDATE, or DELETE statement and returns affected row count.
      *
      * @param  string  $sql  SQL statement with optional parameter placeholders
-     * @param  array  $params  Parameter values for prepared statement
-     * @return PromiseInterface Promise resolving to number of affected rows
+     * @param  array<string|int, mixed>  $params  Parameter values for prepared statement
+     * @return PromiseInterface<int> Promise resolving to number of affected rows
      *
      * @throws \RuntimeException If AsyncPDO is not initialized
      * @throws \PDOException If statement execution fails
      */
     public static function execute(string $sql, array $params = []): PromiseInterface
     {
-        return self::run(function (PDO $pdo) use ($sql, $params) {
+        return self::run(function (PDO $pdo) use ($sql, $params): int {
             $stmt = $pdo->prepare($sql);
             $stmt->execute($params);
 
             return $stmt->rowCount();
         });
     }
 
+    /**
+     * Executes a query and returns a single column value from the first row.
+     *
+     * Useful for queries that return a single scalar value like COUNT, MAX, etc.
+     *
+     * @param  string  $sql  SQL query with optional parameter placeholders
+     * @param  array<string|int, mixed>  $params  Parameter values for prepared statement
+     * @return PromiseInterface<mixed> Promise resolving to scalar value or false if no rows
+     *
+     * @throws \RuntimeException If AsyncPDO is not initialized
+     * @throws \PDOException If query execution fails
+     */
+    public static function fetchValue(string $sql, array $params = []): PromiseInterface
+    {
+        return self::run(function (PDO $pdo) use ($sql, $params): mixed {
+            $stmt = $pdo->prepare($sql);
+            $stmt->execute($params);
+
+            return $stmt->fetch(PDO::FETCH_COLUMN);
+        });
+    }
+
     /**
      * Executes multiple operations within a database transaction.
      *
      * Automatically handles transaction begin/commit/rollback. If the callback
      * throws an exception, the transaction is rolled back automatically.
      *
-     * @param  callable  $callback  Transaction callback receiving PDO instance
-     *                              Signature: function(PDO $pdo): mixed
-     * @return PromiseInterface Promise resolving to callback's return value
+     * @param  callable(PDO): mixed  $callback  Transaction callback receiving PDO instance
+     * @return PromiseInterface<mixed> Promise resolving to callback's return value
      *
      * @throws \RuntimeException If AsyncPDO is not initialized
      * @throws \PDOException If transaction operations fail
@@ -183,47 +203,27 @@ public static function transaction(callable $callback): PromiseInterface
         });
     }
 
-    /**
-     * Executes a query and returns a single column value from the first row.
-     *
-     * Useful for queries that return a single scalar value like COUNT, MAX, etc.
-     *
-     * @param  string  $sql  SQL query with optional parameter placeholders
-     * @param  array  $params  Parameter values for prepared statement
-     * @return PromiseInterface Promise resolving to scalar value or false if no rows
-     *
-     * @throws \RuntimeException If AsyncPDO is not initialized
-     * @throws \PDOException If query execution fails
-     */
-    public static function fetchValue(string $sql, array $params = []): PromiseInterface
-    {
-        return self::run(function (PDO $pdo) use ($sql, $params) {
-            $stmt = $pdo->prepare($sql);
-            $stmt->execute($params);
-
-            return $stmt->fetch(PDO::FETCH_COLUMN);
-        });
-    }
-
     /**
      * Race multiple transactions and commit only the winner, rolling back all others.
      *
      * Executes multiple transactions concurrently and commits the first one to complete
      * successfully while cancelling and rolling back all others. Useful for scenarios
      * like inventory reservation where only one transaction should succeed.
      *
-     * @param  array  $transactions  Array of transaction callbacks
-     *                               Each callback signature: function(PDO $pdo): mixed
-     * @return PromiseInterface Promise that resolves with the winner's result
+     * @param  array<int, callable(PDO): mixed>  $transactions  Array of transaction callbacks
+     * @return PromiseInterface<mixed> Promise that resolves with the winner's result
      *
      * @throws \RuntimeException If AsyncPDO is not initialized
      * @throws Throwable If all transactions fail or system error occurs
      */
     public static function raceTransactions(array $transactions): PromiseInterface
     {
-        return Async::async(function () use ($transactions) {
+        return Async::async(function () use ($transactions): mixed {
+            /** @var array<int, CancellablePromise<array{result: mixed, winner_index: int, success: bool}>> $transactionPromises */
             $transactionPromises = [];
+            /** @var array<int, PDO> $pdoConnections */
             $pdoConnections = [];
+            /** @var array<int, CancellablePromise<array{result: mixed, winner_index: int, success: bool}>> $cancellablePromises */
             $cancellablePromises = [];
 
             foreach ($transactions as $index => $transactionCallback) {
@@ -232,10 +232,9 @@ public static function raceTransactions(array $transactions): PromiseInterface
                 $cancellablePromises[$index] = $cancellablePromise;
             }
 
-            $collectionHandler = new PromiseCollectionHandler;
-
             try {
-                $winnerResult = await($collectionHandler->race($transactionPromises));
+                /** @var array{result: mixed, winner_index: int, success: bool} $winnerResult */
+                $winnerResult = await(race($transactionPromises));
 
                 self::cancelLosingTransactions($cancellablePromises, $winnerResult['winner_index']);
 
@@ -257,16 +256,16 @@ public static function raceTransactions(array $transactions): PromiseInterface
      * Creates a cancellable promise that executes a transaction callback and
      * stores the PDO connection for later cleanup operations.
      *
-     * @param  callable  $transactionCallback  Transaction function to execute
+     * @param  callable(PDO): mixed  $transactionCallback  Transaction function to execute
      * @param  int  $index  Transaction index for identification
-     * @param  array  &$pdoConnections  Reference to array storing PDO connections
-     * @return CancellablePromise Promise that can be cancelled mid-execution
+     * @param  array<int, PDO>  $pdoConnections  Reference to array storing PDO connections
+     * @return CancellablePromise<array{result: mixed, winner_index: int, success: bool}> Promise that can be cancelled mid-execution
      *
      * @internal This method is for internal use by raceTransactions()
      */
     private static function startCancellableRacingTransaction(callable $transactionCallback, int $index, array &$pdoConnections): CancellablePromise
     {
-        $cancellablePromise = new CancellablePromise(function ($resolve, $reject) use ($transactionCallback, $index, &$pdoConnections) {
+        $cancellablePromise = new CancellablePromise(function (callable $resolve, callable $reject) use ($transactionCallback, $index, &$pdoConnections) {
             $pdo = await(self::getPool()->get());
             $pdoConnections[$index] = $pdo;
 
@@ -295,7 +294,7 @@ private static function startCancellableRacingTransaction(callable $transactionC
                     }
                     self::getPool()->release($pdo);
                 } catch (Throwable $e) {
-                    error_log("Failed to cancel transaction {$index}: ".$e->getMessage());
+                    error_log("Failed to cancel transaction {$index}: " . $e->getMessage());
                     self::getPool()->release($pdo);
                 }
             }
@@ -310,7 +309,7 @@ private static function startCancellableRacingTransaction(callable $transactionC
      * Iterates through all racing transactions and cancels those that didn't win,
      * triggering their rollback handlers.
      *
-     * @param  array  $cancellablePromises  Array of CancellablePromise instances
+     * @param  array<int, CancellablePromise<array{result: mixed, winner_index: int, success: bool}>>  $cancellablePromises  Array of CancellablePromise instances
      * @param  int  $winnerIndex  Index of the winning transaction to preserve
      *
      * @internal This method is for internal use by raceTransactions()
@@ -329,7 +328,7 @@ private static function cancelLosingTransactions(array $cancellablePromises, int
      *
      * Emergency cancellation of all racing transactions when a system error occurs.
      *
-     * @param  array  $cancellablePromises  Array of CancellablePromise instances
+     * @param  array<int, CancellablePromise<array{result: mixed, winner_index: int, success: bool}>>  $cancellablePromises  Array of CancellablePromise instances
      *
      * @internal This method is for internal use by raceTransactions()
      */
@@ -348,17 +347,17 @@ private static function cancelAllTransactions(array $cancellablePromises): void
      * Commits the winning transaction and releases its connection back to the pool.
      * Losing transactions should already be cancelled by this point.
      *
-     * @param  array  $pdoConnections  Array of PDO connections indexed by transaction
+     * @param  array<int, PDO>  $pdoConnections  Array of PDO connections indexed by transaction
      * @param  int  $winnerIndex  Index of the winning transaction
-     * @return PromiseInterface Promise that resolves when finalization is complete
+     * @return PromiseInterface<void> Promise that resolves when finalization is complete
      *
      * @throws Throwable If commit fails
      *
      * @internal This method is for internal use by raceTransactions()
      */
     private static function finalizeRacingTransactions(array $pdoConnections, int $winnerIndex): PromiseInterface
     {
-        return Async::async(function () use ($pdoConnections, $winnerIndex) {
+        return Async::async(function () use ($pdoConnections, $winnerIndex): void {
             if (isset($pdoConnections[$winnerIndex])) {
                 $pdo = $pdoConnections[$winnerIndex];
 
@@ -369,7 +368,7 @@ private static function finalizeRacingTransactions(array $pdoConnections, int $w
                     }
                     self::getPool()->release($pdo);
                 } catch (Throwable $e) {
-                    error_log("Failed to commit winner transaction {$winnerIndex}: ".$e->getMessage());
+                    error_log("Failed to commit winner transaction {$winnerIndex}: " . $e->getMessage());
                     $pdo->rollBack();
                     self::getPool()->release($pdo);
 
@@ -385,32 +384,32 @@ private static function finalizeRacingTransactions(array $pdoConnections, int $w
      * Emergency cleanup that rolls back all racing transactions when a system
      * error occurs before a winner can be determined.
      *
-     * @param  array  $pdoConnections  Array of PDO connections to rollback
-     * @return PromiseInterface Promise that resolves when all rollbacks complete
+     * @param  array<int, PDO>  $pdoConnections  Array of PDO connections to rollback
+     * @return PromiseInterface<void> Promise that resolves when all rollbacks complete
      *
      * @internal This method is for internal use by raceTransactions()
      */
     private static function rollbackAllTransactions(array $pdoConnections): PromiseInterface
     {
-        return Async::async(function () use ($pdoConnections) {
+        return Async::async(function () use ($pdoConnections): void {
+            /** @var array<int, PromiseInterface<void>> $rollbackPromises */
             $rollbackPromises = [];
 
             foreach ($pdoConnections as $index => $pdo) {
-                $rollbackPromises[] = Async::async(function () use ($pdo, $index) {
+                $rollbackPromises[] = Async::async(function () use ($pdo, $index): void {
                     try {
                         if ($pdo->inTransaction()) {
                             $pdo->rollBack();
                         }
                         self::getPool()->release($pdo);
                     } catch (Throwable $e) {
-                        error_log("Failed to rollback transaction {$index}: ".$e->getMessage());
+                        error_log("Failed to rollback transaction {$index}: " . $e->getMessage());
                         self::getPool()->release($pdo);
                     }
                 })();
             }
 
-            $collectionHandler = new PromiseCollectionHandler;
-            await($collectionHandler->all($rollbackPromises));
+            await(all($rollbackPromises));
         })();
     }
 
@@ -425,7 +424,7 @@ private static function rollbackAllTransactions(array $pdoConnections): PromiseI
      */
     private static function getPool(): AsyncPdoPool
     {
-        if (! self::$isInitialized) {
+        if (! self::$isInitialized || self::$pool === null) {
             throw new \RuntimeException(
                 'AsyncPDO has not been initialized. Please call AsyncPDO::init() at application startup.'
             );