Add comprehensive CancellablePromise test suite and update timeout return types

- Add 789-line test suite covering CancellablePromise functionality including state management, cancellation handlers, promise chaining, and real-world usage examples
- Update timeout method return types from PromiseInterface to CancellablePromiseInterface across AsyncOperations, PromiseCollectionHandler, and helper functions
- Add CancellablePromiseInterface import to PromiseCollectionHandler

Author: rcalicdan

src/Async/AsyncOperations.php

@@ -201,9 +201,9 @@ public function any(array $promises): PromiseInterface
 
     /**
      * @param  callable(): PromiseInterface<mixed>|PromiseInterface<mixed>|array<int|string, callable(): PromiseInterface<mixed>|PromiseInterface<mixed>>  $promises
-     * @return PromiseInterface<mixed>
+     * @return CancellablePromiseInterface<mixed>
      */
-    public function timeout(callable|PromiseInterface|array $promises, float $seconds): PromiseInterface
+    public function timeout(callable|PromiseInterface|array $promises, float $seconds): CancellablePromiseInterface
     {
         return $this->collectionHandler->timeout($promises, $seconds);
     }

src/Async/Handlers/PromiseCollectionHandler.php

@@ -5,6 +5,7 @@
 use Exception;
 use InvalidArgumentException;
 use Rcalicdan\FiberAsync\Promise\CancellablePromise;
+use Rcalicdan\FiberAsync\Promise\Interfaces\CancellablePromiseInterface;
 use Rcalicdan\FiberAsync\Promise\Interfaces\PromiseInterface;
 use Rcalicdan\FiberAsync\Promise\Promise;
 use RuntimeException;
@@ -162,7 +163,7 @@ public function race(array $promises): PromiseInterface
     public function timeout(
         callable|PromiseInterface|array $operations,
         float $seconds
-    ): PromiseInterface {
+    ): CancellablePromiseInterface {
         if ($seconds <= 0) {
             throw new InvalidArgumentException('Timeout must be greater than zero');
         }
@@ -180,7 +181,7 @@ public function timeout(
             ->then(fn () => throw new Exception("Operation timed out after {$seconds} seconds"))
         ;
 
-        /** @var array<int|string, callable(): PromiseInterface<mixed>|PromiseInterface<mixed>> $racePromises */
+        /** @var array<int|string, callable(): CancellablePromiseInterface<mixed>|CancellablePromiseInterface<mixed>> $racePromises */
         $racePromises = [...$promises, $timeoutPromise];
 
         return $this->race($racePromises);

src/Helpers/async_helper.php

@@ -164,9 +164,9 @@ function any(array $promises): PromiseInterface
      *
      * @param  callable|PromiseInterface<mixed>|array<PromiseInterface<mixed>>  $promises  Number of seconds to wait before resolving
      * @param  float  $seconds  Number of seconds to wait before resolving
-     * @return PromiseInterface<mixed> A promise that resolves after the delay
+     * @return CancellablePromiseInterface<mixed> A promise that resolves after the delay
      */
-    function timeout(callable|PromiseInterface|array $promises, float $seconds): PromiseInterface
+    function timeout(callable|PromiseInterface|array $promises, float $seconds): CancellablePromiseInterface
     {
         return Promise::timeout($promises, $seconds);
     }