Merge pull request #16 from rcalicdan/more-type-safety

More type safety

Author: rcalicdan

phpstan.neon

@@ -7,4 +7,6 @@ parameters:
         - src
     treatPhpDocTypesAsCertain: false
     excludePaths:
-        - tests/
+        - tests/
+    ignoreErrors:
+        - '#Variable method call on.*#'

src/Api/AsyncFile.php

@@ -6,6 +6,7 @@
 use Rcalicdan\FiberAsync\Http\Request;
 use Rcalicdan\FiberAsync\Http\Response;
 use Rcalicdan\FiberAsync\Http\StreamingResponse;
+use Rcalicdan\FiberAsync\Promise\Interfaces\CancellablePromiseInterface;
 use Rcalicdan\FiberAsync\Promise\Interfaces\PromiseInterface;
 
 /**
@@ -16,13 +17,13 @@
  * underlying handler and event loop management for a more convenient API.
  *
  * @method static Request request() Creates a new fluent request builder.
- * @method static PromiseInterface<Response> get(string $url, array $query = []) Performs a GET request.
- * @method static PromiseInterface<Response> post(string $url, array $data = []) Performs a POST request.
- * @method static PromiseInterface<Response> put(string $url, array $data = []) Performs a PUT request.
+ * @method static PromiseInterface<Response> get(string $url, array<string, mixed> $query = []) Performs a GET request.
+ * @method static PromiseInterface<Response> post(string $url, array<string, mixed> $data = []) Performs a POST request.
+ * @method static PromiseInterface<Response> put(string $url, array<string, mixed> $data = []) Performs a PUT request.
  * @method static PromiseInterface<Response> delete(string $url) Performs a DELETE request.
- * @method static PromiseInterface<Response> fetch(string $url, array $options = []) A flexible, fetch-like request method.
- * @method static PromiseInterface<StreamingResponse> stream(string $url, array $options = [], ?callable $onChunk = null) Streams a response body.
- * @method static PromiseInterface<array{file: string, status: int|null, headers: array}> download(string $url, string $destination, array $options = []) Downloads a file.
+ * @method static PromiseInterface<Response> fetch(string $url, array<int|string, mixed> $options = []) A flexible, fetch-like request method.
+ * @method static PromiseInterface<StreamingResponse> stream(string $url, array<int|string, mixed> $options = [], ?callable $onChunk = null) Streams a response body.
+ * @method static CancellablePromiseInterface<array{file: string, status: int, headers: array<mixed>}> download(string $url, string $destination, array<int|string, mixed> $options = []) Downloads a file.
  */
 class AsyncHttp
 {
@@ -55,7 +56,7 @@ public static function request(): Request
      * Performs a quick, asynchronous GET request.
      *
      * @param  string  $url  The target URL.
-     * @param  array  $query  Optional query parameters.
+     * @param  array<string, mixed>  $query  Optional query parameters.
      * @return PromiseInterface<Response> A promise that resolves with a Response object.
      */
     public static function get(string $url, array $query = []): PromiseInterface
@@ -67,7 +68,7 @@ public static function get(string $url, array $query = []): PromiseInterface
      * Performs a quick, asynchronous POST request with a JSON payload.
      *
      * @param  string  $url  The target URL.
-     * @param  array  $data  Data to be JSON-encoded.
+     * @param  array<string, mixed>  $data  Data to be JSON-encoded.
      * @return PromiseInterface<Response> A promise that resolves with a Response object.
      */
     public static function post(string $url, array $data = []): PromiseInterface
@@ -79,7 +80,7 @@ public static function post(string $url, array $data = []): PromiseInterface
      * Performs a quick, asynchronous PUT request.
      *
      * @param  string  $url  The target URL.
-     * @param  array  $data  Data to be JSON-encoded.
+     * @param  array<string, mixed>  $data  Data to be JSON-encoded.
      * @return PromiseInterface<Response> A promise that resolves with a Response object.
      */
     public static function put(string $url, array $data = []): PromiseInterface
@@ -102,7 +103,7 @@ public static function delete(string $url): PromiseInterface
      * A flexible, fetch-like method for making HTTP requests.
      *
      * @param  string  $url  The target URL.
-     * @param  array  $options  Associative array of request options (method, headers, body, etc.).
+     * @param  array<int|string, mixed>  $options  Associative array of request options (method, headers, body, etc.).
      * @return PromiseInterface<Response> A promise that resolves with a Response object.
      */
     public static function fetch(string $url, array $options = []): PromiseInterface
@@ -114,11 +115,11 @@ public static function fetch(string $url, array $options = []): PromiseInterface
      * Streams an HTTP response, processing it in chunks.
      *
      * @param  string  $url  The URL to stream from.
-     * @param  array  $options  Advanced cURL or request options.
+     * @param  array<int|string, mixed>  $options  Advanced cURL or request options.
      * @param  callable|null  $onChunk  Optional callback for each data chunk.
-     * @return PromiseInterface<StreamingResponse> A promise resolving with a StreamingResponse object.
+     * @return CancellablePromiseInterface<StreamingResponse> A promise resolving with a StreamingResponse object.
      */
-    public static function stream(string $url, array $options = [], ?callable $onChunk = null): PromiseInterface
+    public static function stream(string $url, array $options = [], ?callable $onChunk = null): CancellablePromiseInterface
     {
         return self::getInstance()->stream($url, $options, $onChunk);
     }
@@ -128,10 +129,10 @@ public static function stream(string $url, array $options = [], ?callable $onChu
      *
      * @param  string  $url  The URL of the file to download.
      * @param  string  $destination  The local path to save the file.
-     * @param  array  $options  Advanced cURL or request options.
-     * @return PromiseInterface<array{file: string, status: int|null, headers: array}> A promise resolving with download metadata.
+     * @param  array<int|string, mixed>  $options  Advanced cURL or request options.
+     * @return CancellablePromiseInterface<array{file: string, status: int, headers: array<mixed>}> A promise resolving with download metadata.
      */
-    public static function download(string $url, string $destination, array $options = []): PromiseInterface
+    public static function download(string $url, string $destination, array $options = []): CancellablePromiseInterface
     {
         return self::getInstance()->download($url, $destination, $options);
     }
@@ -158,11 +159,11 @@ public static function setInstance(HttpHandler $handler): void
      * Magic method to handle dynamic static calls and proxy them to the handler instance.
      *
      * @param  string  $method  The method name.
-     * @param  array  $arguments  The arguments to pass to the method.
+     * @param  array<mixed>  $arguments  The arguments to pass to the method.
      * @return mixed The result of the proxied method call.
      */
     public static function __callStatic(string $method, array $arguments)
     {
         return self::getInstance()->{$method}(...$arguments);
     }
-}
+}

src/Api/AsyncHttp.php

@@ -14,22 +14,22 @@
  * and stopping the event loop automatically, making it ideal for simple
  * async workflows and batch processing.
  */
-final class AsyncLoop
+final class Task
 {
     /**
-     * @var AsyncOperations|null Cached instance of core async operations handler
+     * @var AsyncOperations|null Cached instance of core async operations handler.
      */
     private static ?AsyncOperations $asyncOps = null;
 
     /**
-     * @var LoopOperations|null Cached instance of loop operations handler
+     * @var LoopOperations|null Cached instance of loop operations handler.
      */
     private static ?LoopOperations $loopOps = null;
 
     /**
      * Get the singleton instance of AsyncOperations with lazy initialization.
      *
-     * @return AsyncOperations The core async operations handler
+     * @return AsyncOperations The core async operations handler.
      */
     protected static function getAsyncOperations(): AsyncOperations
     {
@@ -43,7 +43,7 @@ protected static function getAsyncOperations(): AsyncOperations
     /**
      * Get the singleton instance of LoopOperations with lazy initialization.
      *
-     * @return LoopOperations The loop operations handler with automatic lifecycle management
+     * @return LoopOperations The loop operations handler with automatic lifecycle management.
      */
     protected static function getLoopOperations(): LoopOperations
     {
@@ -56,6 +56,8 @@ protected static function getLoopOperations(): LoopOperations
 
     /**
      * Reset all cached instances to their initial state.
+     *
+     * @return void
      */
     public static function reset(): void
     {
@@ -66,8 +68,8 @@ public static function reset(): void
     /**
      * Run an async operation with automatic event loop management.
      *
-     * @param  callable|PromiseInterface  $asyncOperation  The operation to execute
-     * @return mixed The result of the async operation
+     * @param callable(): mixed|PromiseInterface<mixed> $asyncOperation The operation to execute.
+     * @return mixed The result of the async operation.
      */
     public static function run(callable|PromiseInterface $asyncOperation): mixed
     {
@@ -77,8 +79,8 @@ public static function run(callable|PromiseInterface $asyncOperation): mixed
     /**
      * Run multiple async operations concurrently with automatic loop management.
      *
-     * @param  array  $asyncOperations  Array of callables or promises to execute
-     * @return array Results of all operations in the same order as input
+     * @param array<int|string, callable(): mixed|PromiseInterface<mixed>> $asyncOperations Array of callables or promises to execute.
+     * @return array<mixed> Results of all operations in the same order as input.
      */
     public static function runAll(array $asyncOperations): array
     {
@@ -88,9 +90,9 @@ public static function runAll(array $asyncOperations): array
     /**
      * Run async operations with concurrency control and automatic loop management.
      *
-     * @param  array  $asyncOperations  Array of operations to execute
-     * @param  int  $concurrency  Maximum number of concurrent operations
-     * @return array Results of all operations
+     * @param array<int|string, callable(): mixed|PromiseInterface<mixed>> $asyncOperations Array of operations to execute.
+     * @param int $concurrency Maximum number of concurrent operations.
+     * @return array<mixed> Results of all operations.
      */
     public static function runConcurrent(array $asyncOperations, int $concurrency = 10): array
     {
@@ -100,11 +102,11 @@ public static function runConcurrent(array $asyncOperations, int $concurrency =
     /**
      * Run an async operation with a timeout constraint and automatic loop management.
      *
-     * @param  callable|PromiseInterface|array  $asyncOperation  The operation to execute
-     * @param  float  $timeout  Maximum time to wait in seconds
-     * @return mixed The result of the operation if completed within timeout
+     * @param callable(): mixed|PromiseInterface<mixed>|array<int|string, callable(): mixed|PromiseInterface<mixed>> $asyncOperation The operation to execute.
+     * @param float $timeout Maximum time to wait in seconds.
+     * @return mixed The result of the operation if completed within timeout.
      *
-     * @throws \Exception If the operation times out
+     * @throws \Exception If the operation times out.
      */
     public static function runWithTimeout(callable|PromiseInterface|array $asyncOperation, float $timeout): mixed
     {
@@ -114,13 +116,13 @@ public static function runWithTimeout(callable|PromiseInterface|array $asyncOper
     /**
      * Run async operations in batches with concurrency control and automatic loop management.
      *
-     * @param  array  $asyncOperations  Array of operations to execute
-     * @param  int  $batch  Number of operations to run in each batch
-     * @param  int|null  $concurrency  Maximum number of concurrent operations per batch
-     * @return array Results of all operations
+     * @param array<int|string, callable(): mixed|PromiseInterface<mixed>> $asyncOperations Array of operations to execute.
+     * @param int $batch Number of operations to run in each batch.
+     * @param int|null $concurrency Maximum number of concurrent operations per batch.
+     * @return array<mixed> Results of all operations.
      */
     public static function runBatch(array $asyncOperations, int $batch, ?int $concurrency = null): array
     {
         return self::getLoopOperations()->runBatch($asyncOperations, $batch, $concurrency);
     }
-}
+}

src/Api/AsyncLoop.php renamed to src/Api/Task.php

@@ -3,7 +3,7 @@
 namespace Rcalicdan\FiberAsync\Api;
 
 use Rcalicdan\FiberAsync\Async\AsyncOperations;
-use Rcalicdan\FiberAsync\Promise\Interfaces\PromiseInterface;
+use Rcalicdan\FiberAsync\Promise\Interfaces\CancellablePromiseInterface;
 
 /**
  * Static API for timer-based asynchronous operations.
@@ -55,9 +55,9 @@ public static function reset(): void
      * in async execution, implementing retry delays, or rate limiting operations.
      *
      * @param  float  $seconds  Number of seconds to delay (supports fractional seconds)
-     * @return PromiseInterface A promise that resolves with null after the delay
+     * @return CancellablePromiseInterface A promise that resolves with null after the delay
      */
-    public static function delay(float $seconds): PromiseInterface
+    public static function delay(float $seconds): CancellablePromiseInterface
     {
         return self::getAsyncOperations()->delay($seconds);
     }

src/Api/Timer.php

@@ -10,6 +10,7 @@
 use Rcalicdan\FiberAsync\Async\Handlers\PromiseHandler;
 use Rcalicdan\FiberAsync\Async\Handlers\TimerHandler;
 use Rcalicdan\FiberAsync\Async\Interfaces\AsyncOperationsInterface;
+use Rcalicdan\FiberAsync\Promise\Interfaces\CancellablePromiseInterface;
 use Rcalicdan\FiberAsync\Promise\Interfaces\PromiseInterface;
 
 /**
@@ -147,9 +148,9 @@ public function await(PromiseInterface $promise): mixed
      * Create a promise that resolves after a specified delay.
      *
      * @param float $seconds Number of seconds to delay
-     * @return PromiseInterface<null> A promise that resolves after the delay
+     * @return CancellablePromiseInterface<null> A promise that resolves after the delay
      */
-    public function delay(float $seconds): PromiseInterface
+    public function delay(float $seconds): CancellablePromiseInterface
     {
         return $this->timerHandler->delay($seconds);
     }

src/Async/AsyncOperations.php

@@ -2,6 +2,7 @@
 
 namespace Rcalicdan\FiberAsync\Async\Interfaces;
 
+use Rcalicdan\FiberAsync\Promise\Interfaces\CancellablePromiseInterface;
 use Rcalicdan\FiberAsync\Promise\Interfaces\PromiseInterface;
 use Throwable;
 
@@ -65,9 +66,9 @@ public function await(PromiseInterface $promise): mixed;
      * Creates a promise that resolves with null after the specified delay.
      *
      * @param float $seconds The delay in seconds (supports fractions for milliseconds).
-     * @return PromiseInterface<null> A promise that resolves with null after the delay.
+     * @return CancellablePromiseInterface<null> A promise that resolves with null after the delay.
      */
-    public function delay(float $seconds): PromiseInterface;
+    public function delay(float $seconds): CancellablePromiseInterface;
 
     /**
      * Waits for all promises to resolve or any to reject.