@ndriadev/futurable 2.3.3 → 3.0.0

package/dist/index.d.ts

@@ -1,69 +1,187 @@
-export interface FuturableLike<T> {
+/**
+ * Result type for safe operations that may succeed or fail.
+ * Provides a discriminated union for type-safe error handling without try-catch.
+ *
+ * @template T - The type of the success value
+ * @template E - The type of the error (defaults to Error)
+ */
+type SafeResult<T, E = Error> = {
+    success: true;
+    data: T;
+    error: null;
+} | {
+    success: false;
+    data: null;
+    error: E;
+};
+/**
+* A thenable-like interface that represents a value that may be available now, in the future, or never.
+* Compatible with both Promises and Futurables, allowing for flexible composition.
+*
+* @template T - The type of the value that will be resolved
+*/
+interface FuturableLike<T> {
     /**
-     * Attaches callbacks for the resolution and/or rejection of the Futurable.
-     * @param onfulfilled The callback to execute when the Futurable is resolved.
-     * @param onrejected The callback to execute when the Futurable is rejected.
-     * @returns A Futurable for the completion of which ever callback is executed.
-     */
+    * Attaches callbacks for the resolution and/or rejection of the Futurable.
+    *
+    * @template TResult1 - The type returned by the fulfillment callback
+    * @template TResult2 - The type returned by the rejection callback
+    * @param onfulfilled - The callback to execute when the Futurable is resolved
+    * @param onrejected - The callback to execute when the Futurable is rejected
+    * @returns A new Futurable for the completion of whichever callback is executed
+    */
     then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1> | FuturableLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2> | FuturableLike<TResult2>) | undefined | null): FuturableLike<TResult1 | TResult2>;
 }
-export interface FuturableResolve<T> {
+/**
+* Function signature for resolving a Futurable with a value.
+* Accepts a direct value, a Promise, or another Futurable.
+*
+* @template T - The type of the value to resolve with
+* @param value - The value, Promise, or Futurable to resolve with
+*/
+interface FuturableResolve<T> {
     (value: T | FuturableLike<T> | PromiseLike<T>): void;
 }
-export interface FuturableReject {
+/**
+* Function signature for rejecting a Futurable with a reason.
+*
+* @param reason - The reason for rejection (typically an Error)
+*/
+interface FuturableReject {
     (reason?: any): void;
 }
-export interface FuturableUtils<T> {
+/**
+* Utility methods and properties available within a Futurable executor.
+* Provides advanced features like cancellation, delays, HTTP fetching, and signal management.
+*
+* @template T - The type of value the Futurable will resolve to
+*/
+interface FuturableUtils<T> {
     /**
-     * Internal futurable signal
-     */
+    * Internal AbortSignal for cancellation support.
+    * This signal is aborted when the Futurable is cancelled.
+    */
     signal: AbortSignal;
     /**
-     * Cancel the futurable if it is to be executed or if it is still executing.
-     */
+    * Cancels the Futurable if it is pending or currently executing.
+    * Triggers the abort signal and executes any registered onCancel callbacks.
+    */
     cancel: () => void;
     /**
-     * Executes the callback passed as a parameter when the futurable is cancelled.
-     * @param cb: callback
-     */
+    * Registers a callback to be executed when the Futurable is cancelled.
+    * Multiple callbacks can be registered and will be executed in order.
+    *
+    * @param cb - The callback function to execute on cancellation
+    */
     onCancel: (cb: () => void) => void;
     /**
-     * Waits for timer, then executes callback with the futurable value and returns the result obtained from the invocation.
-     * @param cb: callback executed after timer
-     * @param timer: timer to wait (in milliseconds)
-     */
-    delay: <TResult = T, TResult2 = never>(cb: () => TResult, timer: number) => FuturableLike<TResult | TResult2>;
+    * Waits for a specified duration, then executes a callback and returns the result.
+    * The delay is cancellable via the Futurable's signal.
+    *
+    * @template TResult - The type returned by the callback
+    * @template TResult2 - The type in case of rejection (defaults to never)
+    * @param cb - The callback to execute after the timer expires
+    * @param timer - The delay duration in milliseconds
+    * @returns A new Futurable that resolves with the callback's result
+    */
+    delay: <TResult = T, TResult2 = never>(cb: () => TResult, timer: number) => Futurable<TResult | TResult2>;
     /**
-     * Waits for timer parameter (in milliseconds) before returning the value.
-     * @param timer: timer to wait (in milliseconds)
-     */
-    sleep: (timer: number) => FuturableLike<void>;
+    * Pauses execution for a specified duration.
+    * Equivalent to delay with an empty callback.
+    *
+    * @param timer - The duration to wait in milliseconds
+    * @returns A Futurable that resolves after the timer expires
+    */
+    sleep: (timer: number) => Futurable<void>;
     /**
-     * Extension of the fetch API with cancellation support. Url parameter can be a string or a function with receive value from futurable chaining as paremeter.
-     * @param url: url to fetch
-     * @param opts: fetch options
-     */
+    * Extension of the native Fetch API with automatic cancellation support.
+    * The request is automatically cancelled if the Futurable is cancelled.
+    *
+    * @param url - The URL to fetch
+    * @param opts - Optional Fetch API options (signal will be automatically provided)
+    * @returns A Futurable that resolves with the Response object
+    */
     fetch: (url: string, opts?: RequestInit) => Futurable<Response>;
     /**
-     * Takes a promise and transforms it into a futurizable. Promise can be also a function that receives value from futurable chaining as parameter.
-     * @param promise: Promise to futurize
-     */
+    * Converts a standard Promise into a Futurable with cancellation support.
+    * The original Promise cannot be cancelled, but the Futurable wrapper can be.
+    *
+    * @template TResult - The type the Promise resolves to
+    * @param promise - The Promise to convert
+    * @returns A Futurable wrapping the Promise
+    */
     futurizable: <TResult = any>(promise: Promise<TResult>) => Futurable<TResult>;
 }
-export type FuturableExecutor<T> = (resolve: FuturableResolve<T>, reject: FuturableReject, 
 /**
- * Object containing implemented functionalities.
- */
-utils: FuturableUtils<T>) => void;
-export type FuturableIterable<T = any> = Iterable<FuturableLike<T> | PromiseLike<T> | T>;
+* Executor function signature for creating a new Futurable.
+* Similar to the Promise executor, but with additional utilities for cancellation and async operations.
+*
+* @template T - The type of value the Futurable will resolve to
+* @param resolve - Function to resolve the Futurable with a value
+* @param reject - Function to reject the Futurable with a reason
+* @param utils - Utility object containing cancellation and async helpers
+*/
+type FuturableExecutor<T> = (resolve: FuturableResolve<T>, reject: FuturableReject, utils: FuturableUtils<T>) => void;
+/**
+* An iterable collection of values that can be Futurables, Promises, or plain values.
+* Used by static methods like Futurable.all(), Futurable.race(), etc.
+*
+* @template T - The type of values in the iterable
+*/
+type FuturableIterable<T = any> = Iterable<FuturableLike<T> | PromiseLike<T> | T>;
+/**
+* Return type of Futurable.withResolvers() static method.
+* Provides direct access to the Futurable and its control functions.
+*
+* @template T - The type of value the Futurable will resolve to
+*/
 interface FuturableWithResolvers<T> {
+    /** The created Futurable or Promise instance */
     promise: Futurable<T> | Promise<T>;
+    /** Function to resolve the Futurable with a value */
     resolve: (value: T | PromiseLike<T> | FuturableLike<T>) => void;
+    /** Function to reject the Futurable with a reason */
     reject: (reason?: any) => void;
+    /** Function to cancel the Futurable */
     cancel: () => void;
+    /** Utility object with advanced Futurable features */
     utils: FuturableUtils<T>;
 }
-export declare class Futurable<T> extends Promise<T> {
+/**
+* Return type of Futurable.polling() static method.
+* Provides controls for a polling operation.
+*/
+interface FuturablePollingController {
+    /** Stops the polling and cancels any pending operations */
+    cancel: () => void;
+    /** Registers an error handler for polling operations */
+    catch: (onrejected: (reason: unknown) => void) => void;
+}
+/**
+* A cancellable Promise implementation with extended async utilities.
+*
+* Futurable extends the native Promise API with:
+* - Built-in cancellation via AbortSignal
+* - Chainable delay and sleep operations
+* - Integrated fetch with automatic cancellation
+* - Polling capabilities
+* - Promise-to-Futurable conversion
+*
+* @template T - The type of value this Futurable will resolve to
+*
+* @example
+* ```typescript
+* // Basic usage with cancellation
+* const futurable = new Futurable((resolve, reject, { signal }) => {
+*   const timeoutId = setTimeout(() => resolve('done'), 5000);
+*   signal.addEventListener('abort', () => clearTimeout(timeoutId));
+* });
+*
+* // Cancel after 1 second
+* setTimeout(() => futurable.cancel(), 1000);
+* ```
+*/
+declare class Futurable<T> extends Promise<T> {
     private controller;
     private internalSignal;
     private idsTimeout;
@@ -71,184 +189,2839 @@ export declare class Futurable<T> extends Promise<T> {
     static get [Symbol.species](): typeof Futurable;
     get [Symbol.toStringTag](): string;
     /**
-     * Return internal futurable signal
-     * @returns {AbortSignal}
-     */
+    * Returns the internal AbortSignal used for cancellation.
+    * This signal is aborted when cancel() is called.
+    *
+    * @returns The internal AbortSignal
+    */
     get signal(): AbortSignal;
     private clearTimeout;
     /**
-     * Attaches callbacks for the resolution and/or rejection of the Futurable.
-     * @param {((value: T) => TResult1 | PromiseLike<TResult1> | FuturableLike<TResult1>) | undefined | null} onfulfilled
-     * @param {((reason: any) => TResult2 | PromiseLike<TResult2> | FuturableLike<TResult2>) | undefined | null} onrejected
-     * @returns {Futurable<TResult1 | TResult2>}
-     */
+    * Attaches callbacks for the resolution and/or rejection of the Futurable.
+    * Chainable method that returns a new Futurable.
+    *
+    * @template TResult1 - Type returned by the fulfillment callback
+    * @template TResult2 - Type returned by the rejection callback
+    * @param onfulfilled - Callback executed when the Futurable is resolved
+    * @param onrejected - Callback executed when the Futurable is rejected
+    * @returns A new Futurable for the completion of the callback
+    */
     then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1> | FuturableLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2> | FuturableLike<TResult2>) | undefined | null): Futurable<TResult1 | TResult2>;
     /**
-     * Attaches a callback for only the rejection of the Futurable.
-     * @param {((reason: any) => TResult2 | PromiseLike<TResult2> | FuturableLike<TResult2>) | undefined | null} onRejected
-     * @returns {Futurable<T | TResult2>}
-     */
+    * Attaches a callback for only the rejection of the Futurable.
+    *
+    * @template TResult2 - Type returned by the rejection callback
+    * @param onRejected - Callback executed when the Futurable is rejected
+    * @returns A new Futurable
+    */
     catch<TResult2 = never>(onRejected: ((reason: any) => TResult2 | PromiseLike<TResult2> | FuturableLike<TResult2>) | undefined | null): Futurable<T | TResult2>;
     /**
-     * Attaches a callback that is invoked when the Futurable is settled (fulfilled or rejected).
-     * The resolved value cannot be modified from the callback.
-     * @param {() => void | undefined | null} onfinally
-     * @returns {Futurable<T>}
-     */
+    * Attaches a callback that is invoked when the Futurable is settled (fulfilled or rejected).
+    * The resolved value cannot be modified from the callback.
+    *
+    * @param onfinally - Callback executed when the Futurable settles
+    * @returns A new Futurable with the same value
+    */
     finally(onfinally: () => void | undefined | null): Futurable<T>;
     /**
-     * Cancel the futurable if it is to be executed or if it is still executing.
-     */
+    * Cancels the Futurable if it is pending or currently executing.
+    * Aborts the internal signal and triggers all registered onCancel callbacks.
+    *
+    * @example
+    * ```typescript
+    * const futurable = new Futurable((resolve) => {
+    *   setTimeout(() => resolve('done'), 5000);
+    * });
+    * futurable.cancel(); // Cancels the operation
+    * ```
+    */
     cancel(): void;
     /**
-     * Waits for timer, then executes callback with the futurable value and returns the result obtained from the invocation.
-     * @param {(val: T) => TResult1 | PromiseLike<TResult1> | FuturableLike<TResult1>} cb - callback executed after timer with futurable chain value as parameter
-     * @param {number} timer - timer to wait (in milliseconds)
-     */
+    * Waits for a specified duration, then executes a callback with the Futurable's value.
+    * The delay is cancellable via the Futurable's signal.
+    *
+    * @template TResult1 - Type returned by the callback
+    * @template TResult2 - Type in case of rejection
+    * @param cb - Callback executed after the delay, receives the resolved value
+    * @param timer - Delay duration in milliseconds
+    * @returns A new Futurable that resolves with the callback's result
+    *
+    * @example
+    * ```typescript
+    * Futurable.resolve(5)
+    *   .delay(val => val * 2, 1000) // Wait 1s, then multiply by 2
+    *   .then(result => console.log(result)); // Logs: 10
+    * ```
+    */
     delay<TResult1 = T, TResult2 = never>(cb: (val: T) => TResult1 | PromiseLike<TResult1> | FuturableLike<TResult1>, timer: number): Futurable<TResult1 | TResult2>;
     /**
-     * Waits for timer parameter (in milliseconds) before returning the value.
-     * @param {number} timer - timer to wait (in milliseconds)
-     * @returns {Futurable<T>}
-     */
+    * Pauses execution for a specified duration before passing through the value.
+    * Equivalent to delay with an identity callback.
+    *
+    * @param timer - Duration to wait in milliseconds
+    * @returns A new Futurable that resolves with the same value after the delay
+    *
+    * @example
+    * ```typescript
+    * Futurable.resolve('hello')
+    *   .sleep(2000) // Wait 2 seconds
+    *   .then(val => console.log(val)); // Logs: "hello" after 2s
+    * ```
+    */
     sleep(timer: number): Futurable<T>;
     /**
-     * Extension of the fetch API with cancellation support. Url parameter can be a string or a function with receive value from futurable chaining as paremeter.
-     * @param {string| ((val?:T)=>string)} url - url to fetch or function with futurable chaining value that returns url to fetch
-     * @param {object | RequestInit | ((val?: T) => RequestInit)} opts - fetch options or function with futurable chaining value that return fetch options
-     * @returns {Futurable<Response>}
-     */
-    fetch(url: string | ((val?: T) => string), opts?: object | RequestInit | ((val?: T) => RequestInit)): Futurable<Response>;
+    * Performs an HTTP fetch operation with automatic cancellation support.
+    * The request is automatically cancelled if the Futurable is cancelled.
+    *
+    * @param url - URL to fetch, or a function that receives the Futurable's value and returns a URL
+    * @param opts - Fetch options, or a function that receives the Futurable's value and returns fetch options
+    * @returns A new Futurable that resolves with the Response object
+    *
+    * @example
+    * ```typescript
+    * Futurable.resolve('users')
+    *   .fetch(endpoint => `https://api.example.com/${endpoint}`)
+    *   .then(response => response.json())
+    *   .then(data => console.log(data));
+    * ```
+    */
+    fetch(url: string | ((val: T) => string), opts?: object | RequestInit | ((val: T) => RequestInit)): Futurable<Response>;
     /**
-     * Executes the callback passed as a parameter when the futurable is cancelled.
-     * @param {()=>void} cb
-     * @returns {Futurable<TResult1 | TResult2>}
-     */
+    * Registers a callback to be executed when the Futurable is cancelled.
+    * Useful for cleanup operations or aborting dependent async tasks.
+    *
+    * @template TResult1 - Type in case of resolution
+    * @template TResult2 - Type in case of rejection
+    * @param cb - Callback executed on cancellation
+    * @returns A new Futurable
+    *
+    * @example
+    * ```typescript
+    * const futurable = new Futurable((resolve) => {
+    *   const task = startLongTask();
+    *   setTimeout(() => resolve('done'), 5000);
+    * }).onCancel(() => {
+    *   console.log('Operation cancelled, cleaning up...');
+    * });
+    * ```
+    */
     onCancel<TResult1 = void, TResult2 = never>(cb: () => void): Futurable<TResult1 | TResult2>;
     /**
-     * Takes a promise and transforms it into a futurizable. Promise can be also a function that receives value from futurable chaining as parameter.
-     * @param {Promise<TResult1> | ((val?: T) => Promise<TResult1>)} promise - Promise to futurize or function that return promise with futurable chaining value as parameter
-     * @returns {Futurable<TResult1 | TResult2>}
-     */
+    * Converts a Promise into a Futurable with cancellation support.
+    * The Promise can be provided directly or via a function that receives the current value.
+    *
+    * @template TResult1 - Type the Promise resolves to
+    * @template TResult2 - Type in case of rejection
+    * @param promise - Promise to convert, or a function that receives the Futurable's value and returns a Promise
+    * @returns A new Futurable wrapping the Promise
+    *
+    * @example
+    * ```typescript
+    * Futurable.resolve(123)
+    *   .futurizable(val => fetch(`/api/${val}`).then(r => r.json()))
+    *   .then(data => console.log(data));
+    * ```
+    */
     futurizable<TResult1 = T, TResult2 = never>(promise: Promise<TResult1> | ((val?: T) => Promise<TResult1>)): Futurable<TResult1 | TResult2>;
     /**
-     * Creates a new resolved futurable. Creates a new resolved futurable for the provided value.
-     * @returns {Futurable<void>}
+     * Wraps the Futurable in a safe execution context that never throws.
+     * Returns a result object containing either the resolved value or the error,
+     * eliminating the need for try-catch blocks or .catch() handlers.
+     *
+     * This method is particularly useful in async/await contexts where you want
+     * to handle errors explicitly without wrapping code in try-catch blocks.
+     *
+     * @template TError - The type of the error (defaults to unknown)
+     * @returns A Futurable that resolves to a SafeResult containing either data or error
+     *
+     * @example
+     * ```typescript
+     * // Instead of try-catch:
+     * const result = await Futurable.fetch('/api/data')
+     *   .then(r => r.json())
+     *   .safe();
+     *
+     * if (result.success) {
+     *   console.log('Data:', result.data);
+     * } else {
+     *   console.error('Error:', result.error);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Chaining multiple operations safely:
+     * const result = await Futurable.resolve(5)
+     *   .delay(val => val * 2, 1000)
+     *   .fetch(val => `/api/item/${val}`)
+     *   .futurizable(r => r.json())
+     *   .safe();
+     *
+     * if (result.success) {
+     *   // TypeScript knows result.data is the JSON response
+     *   processData(result.data);
+     * } else {
+     *   // TypeScript knows result.error exists
+     *   logError(result.error);
+     * }
+     * ```
      */
+    safe<TError = unknown>(): Futurable<SafeResult<T, TError>>;
+    /**
+    * Creates a new resolved Futurable without a value (resolves to void).
+    *
+    * @returns A Futurable that immediately resolves to void
+    *
+    * @example
+    * ```typescript
+    * Futurable.resolve()
+    *   .delay(() => 'hello', 1000)
+    *   .then(val => console.log(val)); // Logs: "hello" after 1s
+    * ```
+    */
     static resolve(): Futurable<void>;
     /**
-     * @param {T | PromiseLike<T> | FuturableLike<T>} value
-     * @param {AbortSignal} [signal]
-     * @returns {Futurable<T>}
-     */
+    * Creates a new resolved Futurable for the provided value.
+    *
+    * @template T - Type of the value to resolve with
+    * @param value - The value, Promise, or Futurable to resolve with
+    * @param signal - Optional AbortSignal for cancellation coordination
+    * @returns A Futurable that immediately resolves with the value
+    *
+    * @example
+    * ```typescript
+    * Futurable.resolve(42)
+    *   .then(val => console.log(val)); // Logs: 42
+    * ```
+    */
     static resolve<T = any>(value: T | PromiseLike<T> | FuturableLike<T>, signal?: AbortSignal): Futurable<T>;
     /**
-     * Creates a new rejected futurable for the provided reason.
-     * @param {any} [reason]
-     * @param {AbortSignal} [signal]
-     * @returns {Futurable<T>}
-     */
+    * Creates a new rejected Futurable for the provided reason.
+    *
+    * @template T - Type of value (never used for rejected Futurables)
+    * @param reason - The reason for rejection (typically an Error)
+    * @param signal - Optional AbortSignal for cancellation coordination
+    * @returns A Futurable that immediately rejects with the reason
+    *
+    * @example
+    * ```typescript
+    * Futurable.reject(new Error('Failed'))
+    *   .catch(err => console.error(err)); // Logs the error
+    * ```
+    */
     static reject<T = never>(reason?: any, signal?: AbortSignal): Futurable<T>;
     /**
-     * OnCancel static method. It accepts a callback or a object with cb property and an optional signal.
-     * @param {{cb: () => T, signal: AbortSignal|undefined}} options
-     * @returns {Futurable<T>}
- */
+    * Creates a Futurable that resolves when cancelled.
+    * Useful for creating cancellation-aware cleanup logic.
+    *
+    * @template T - Type returned by the callback
+    * @param options - Configuration object
+    * @param options.cb - Callback executed on cancellation
+    * @param options.signal - Optional external AbortSignal
+    * @returns A Futurable that resolves with the callback's result when cancelled
+    *
+    * @example
+    * ```typescript
+    * const cleanup = Futurable.onCancel({
+    *   cb: () => console.log('Cleanup performed')
+    * });
+    * cleanup.cancel(); // Triggers the callback
+    * ```
+    */
     static onCancel<T = void>({ cb, signal }: {
         cb: () => T;
         signal?: AbortSignal;
     }): Futurable<T>;
     /**
-     * Delay static method. It accepts a object with timer and cb properties and an optional signal property.
-     * @param {{cb: () => T, timer: number, signal: AbortSignal|undefined}} options
-     * @returns {Futurable<T|TResult2>}
-     */
+    * Creates a Futurable that executes a callback after a specified delay.
+    *
+    * @template T - Type returned by the callback
+    * @template TResult2 - Type in case of rejection
+    * @param options - Configuration object
+    * @param options.cb - Callback to execute after the delay
+    * @param options.timer - Delay duration in milliseconds
+    * @param options.signal - Optional AbortSignal for cancellation
+    * @returns A Futurable that resolves with the callback's result after the delay
+    *
+    * @example
+    * ```typescript
+    * Futurable.delay({
+    *   cb: () => 'Hello after delay',
+    *   timer: 2000
+    * }).then(msg => console.log(msg)); // Logs after 2s
+    * ```
+    */
     static delay<T = any, TResult2 = never>({ cb, timer, signal }: {
         cb: () => T;
         timer: number;
         signal?: AbortSignal;
     }): Futurable<T | TResult2>;
     /**
-     * Sleep static method. It accepts a timer or a object with timer property and an optional signal.
-     * @param {{timer: number, signal: AbortSignal|undefined}} options
-     * @returns {Futurable<void>}
-     */
+    * Creates a Futurable that resolves after a specified delay.
+    * Equivalent to delay with an empty callback.
+    *
+    * @param options - Configuration object
+    * @param options.timer - Duration to wait in milliseconds
+    * @param options.signal - Optional AbortSignal for cancellation
+    * @returns A Futurable that resolves after the delay
+    *
+    * @example
+    * ```typescript
+    * Futurable.sleep({ timer: 3000 })
+    *   .then(() => console.log('3 seconds passed'));
+    * ```
+    */
     static sleep({ timer, signal }: {
         timer: number;
         signal?: AbortSignal;
     }): Futurable<void>;
     /**
-     * Fetch static method.
-     * @param {string} url
-     * @param {RequestInit} [opts]
-     * @returns {Futurable<Response>}
-     */
+    * Performs an HTTP fetch operation with cancellation support.
+    *
+    * @param url - The URL to fetch
+    * @param opts - Optional Fetch API options (if signal is provided, it overrides the internal one)
+    * @returns A Futurable that resolves with the Response object
+    *
+    * @example
+    * ```typescript
+    * Futurable.fetch('https://api.example.com/data')
+    *   .then(response => response.json())
+    *   .then(data => console.log(data));
+    * ```
+    */
     static fetch(url: string, opts?: RequestInit): Futurable<Response>;
     /**
-     * Futurizable static method.
-     * @param {{promise: Promise<TResult1>, signal: AbortSignal|undefined}} options
-     * @returns {Futurable<TResult1 | TResult2>}
-     */
+    * Converts a Promise into a Futurable with cancellation support.
+    * Note: The original Promise cannot be cancelled, but the Futurable wrapper can be.
+    *
+    * @template TResult1 - Type the Promise resolves to
+    * @template TResult2 - Type in case of rejection
+    * @param options - Configuration object
+    * @param options.promise - The Promise to convert
+    * @param options.signal - Optional AbortSignal for cancellation
+    * @returns A Futurable wrapping the Promise
+    *
+    * @example
+    * ```typescript
+    * const promise = fetch('/api/data').then(r => r.json());
+    * Futurable.futurizable({ promise })
+    *   .then(data => console.log(data));
+    * ```
+    */
     static futurizable<TResult1 = any, TResult2 = never>({ promise, signal }: {
         promise: Promise<TResult1>;
         signal?: AbortSignal;
     }): Futurable<TResult1 | TResult2>;
     private static handleValues;
     /**
-     * Creates a Futurable with cancellation support that is resolved with an array of results when all of the provided Futurables resolve, or rejected when any Futurable is rejected.
-     * @param {T} values
-     * @param {AbortSignal} [signal]
-     * @returns {Futurable<{ -readonly [P in keyof T]: Awaited<T[P]>; }>}
-     */
+    * Creates a Futurable that resolves when all provided Futurables/Promises resolve,
+    * or rejects when any of them rejects. Supports cancellation of all pending operations.
+    *
+    * @template T - Tuple type of input values
+    * @param values - Array of Futurables, Promises, or plain values
+    * @param signal - Optional AbortSignal that cancels all operations when aborted
+    * @returns A Futurable that resolves with an array of all resolved values
+    *
+    * @example
+    * ```typescript
+    * const all = Futurable.all([
+    *   Futurable.delay({ cb: () => 1, timer: 100 }),
+    *   Futurable.delay({ cb: () => 2, timer: 200 }),
+    *   Promise.resolve(3)
+    * ]);
+    * all.then(results => console.log(results)); // [1, 2, 3]
+    * ```
+    */
     static all<T extends readonly unknown[] | []>(values: T, signal?: AbortSignal): Futurable<{
         -readonly [P in keyof T]: Awaited<T[P]>;
     }>;
     /**
-     * Creates a Futurable with cancellation support that is resolved with an array of results when all of the provided Futurables resolve or reject.
-     * @param {T} values
-     * @param {AbortSignal} [signal]
-     * @returns {Futurable<{ -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>> }>}
-     */
+    * Creates a Futurable that resolves when all provided Futurables/Promises settle
+    * (either resolve or reject). Returns an array of result objects indicating the outcome.
+    *
+    * @template T - Tuple type of input values
+    * @param values - Array of Futurables, Promises, or plain values
+    * @param signal - Optional AbortSignal for cancellation
+    * @returns A Futurable that resolves with an array of PromiseSettledResult objects
+    *
+    * @example
+    * ```typescript
+    * Futurable.allSettled([
+    *   Futurable.resolve(1),
+    *   Futurable.reject('error'),
+    *   Promise.resolve(3)
+    * ]).then(results => {
+    *   // results[0]: { status: 'fulfilled', value: 1 }
+    *   // results[1]: { status: 'rejected', reason: 'error' }
+    *   // results[2]: { status: 'fulfilled', value: 3 }
+    * });
+    * ```
+    */
     static allSettled<T extends readonly unknown[] | []>(values: T, signal?: AbortSignal): Futurable<{
         -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>>;
     }>;
     /**
-     * Creates a Futurable with cancellation support that is resolved or rejected when any of the provided Futurables are resolved or rejected.
-     * @param {T} values
-     * @param {AbortSignal} [signal]
-     * @returns {Futurable<Awaited<T[number]>>}
-     */
+    * Creates a Futurable that resolves or rejects as soon as any of the provided
+    * Futurables/Promises resolves or rejects. Cancels all other pending operations.
+    *
+    * @template T - Tuple type of input values
+    * @param values - Array of Futurables, Promises, or plain values
+    * @param signal - Optional AbortSignal for cancellation
+    * @returns A Futurable that settles with the first settled value/reason
+    *
+    * @example
+    * ```typescript
+    * Futurable.race([
+    *   Futurable.delay({ cb: () => 'slow', timer: 2000 }),
+    *   Futurable.delay({ cb: () => 'fast', timer: 100 })
+    * ]).then(result => console.log(result)); // 'fast'
+    * ```
+    */
     static race<T extends readonly unknown[] | []>(values: T, signal?: AbortSignal): Futurable<Awaited<T[number]>>;
     /**
-     * The any function returns a futurable with cancellation support that is fulfilled by the first given futurable to be fulfilled,
-     * or rejected with an AggregateError containing an array of rejection reasons if all of the
-     * given futurables are rejected. It resolves all elements of the passed iterable to futurables as
-     * it runs this algorithm.
-     * @param {T} values
-     * @param {AbortSignal} [signal]
-     * @returns {Futurable<Awaited<T[number]>>}
-     */
+    * Creates a Futurable that resolves as soon as any of the provided Futurables/Promises
+    * successfully resolves. Rejects with an AggregateError if all of them reject.
+    *
+    * @template T - Tuple type of input values
+    * @param values - Array of Futurables, Promises, or plain values
+    * @param signal - Optional AbortSignal for cancellation
+    * @returns A Futurable that resolves with the first successful value
+    *
+    * @example
+    * ```typescript
+    * Futurable.any([
+    *   Futurable.reject('error1'),
+    *   Futurable.delay({ cb: () => 'success', timer: 100 }),
+    *   Futurable.reject('error2')
+    * ]).then(result => console.log(result)); // 'success'
+    * ```
+    */
     static any<T extends readonly unknown[] | []>(values: T, signal?: AbortSignal): Futurable<Awaited<T[number]>>;
     /**
-     * Creates a polling service with cancellation support and possibility to handle error. An optional param __immediate__ can be set _true_ if __fun__ must to be invoke immediatly.
-     * @param {()=> Futurable<T>} fun
-     * @param {{interval: number, signal?: AbortSignal, immediate?: boolean}} options
-     * @returns {{cancel: () => void, catch: (onrejected:(reason: unknown)=>void)=>void }}
-     */
+    * Creates a polling service that repeatedly executes a function at regular intervals.
+    * Supports cancellation and error handling.
+    *
+    * @template T - Type returned by the polling function
+    * @param fun - Function to execute on each poll (can return a Futurable, Promise, or plain value)
+    * @param options - Configuration object
+    * @param options.interval - Interval between polls in milliseconds
+    * @param options.signal - Optional AbortSignal to stop polling
+    * @param options.immediate - If true, executes the function immediately before starting the interval
+    * @returns A controller object with cancel() and catch() methods
+    *
+    * @example
+    * ```typescript
+    * const polling = Futurable.polling(
+    *   () => fetch('/api/status').then(r => r.json()),
+    *   { interval: 5000, immediate: true }
+    * );
+    *
+    * polling.catch(err => console.error('Polling error:', err));
+    *
+    * // Stop polling after 30 seconds
+    * setTimeout(() => polling.cancel(), 30000);
+    * ```
+    */
     static polling<T>(fun: () => Futurable<T> | Promise<T> | T, { interval, signal, immediate }: {
         interval: number;
         signal?: AbortSignal;
         immediate?: boolean;
-    }): {
-        cancel: () => void;
-        catch: (onrejected: (reason: unknown) => void) => void;
-    };
+    }): FuturablePollingController;
     /**
-     * Extension of _Promise.withResolvers_ static method. Creates a new Futurable and returns it in an object, along with its resolve, reject and cancel functions and utils object.
-     * @param {AbortSignal} [signal]
-     * @returns {{ resolve: null | FuturableResolve<T>, reject: null | FuturableReject, utils: null | FuturableUtils<T>, futurable: Futurable<T>, cancel: null | (() => void) }}
-     */
+    * Creates a new Futurable and returns it along with its control functions.
+    * Extension of the Promise.withResolvers() static method with cancellation support.
+    *
+    * @template T - Type of value the Futurable will resolve to
+    * @param signal - Optional AbortSignal for cancellation
+    * @returns An object containing the Futurable and its control functions
+    *
+    * @example
+    * ```typescript
+    * const { promise, resolve, reject, cancel } = Futurable.withResolvers<number>();
+    *
+    * // Resolve from elsewhere
+    * setTimeout(() => resolve(42), 1000);
+    *
+    * // Or cancel
+    * cancel();
+    *
+    * promise.then(val => console.log(val));
+    * ```
+    */
     static withResolvers<T>(signal?: AbortSignal): FuturableWithResolvers<T>;
+    /**
+     * Creates a Futurable that wraps an executor in a safe execution context.
+     * The resulting Futurable never rejects - instead, it resolves with a result
+     * object containing either the success value or the error.
+     *
+     * This is useful when you want to create a Futurable that handles its own errors
+     * internally and always resolves with a discriminated result type.
+     *
+     * @template T - The type of the success value
+     * @template E - The type of the error (defaults to unknown)
+     * @param executor - The Futurable executor function
+     * @param signal - Optional AbortSignal for cancellation coordination
+     * @returns A Futurable that always resolves to a SafeResult
+     *
+     * @example
+     * ```typescript
+     * const result = await Futurable.safe<number>(
+     *   (resolve, reject, { fetch }) => {
+     *     fetch('/api/data')
+     *       .then(r => r.json())
+     *       .then(data => resolve(data.value))
+     *       .catch(reject);
+     *   }
+     * );
+     *
+     * if (result.success) {
+     *   console.log('Value:', result.data);
+     * } else {
+     *   console.error('Failed:', result.error);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With custom error type:
+     * interface ApiError {
+     *   code: string;
+     *   message: string;
+     * }
+     *
+     * const result = await Futurable.safe<User, ApiError>(
+     *   (resolve, reject, { fetch }) => {
+     *     fetch('/api/user')
+     *       .then(r => r.ok ? r.json() : reject({ code: 'HTTP_ERROR', message: r.statusText }))
+     *       .then(resolve)
+     *       .catch(err => reject({ code: 'NETWORK_ERROR', message: err.message }));
+     *   }
+     * );
+     *
+     * if (!result.success) {
+     *   switch (result.error.code) {
+     *     case 'HTTP_ERROR':
+     *       // Handle HTTP errors
+     *       break;
+     *     case 'NETWORK_ERROR':
+     *       // Handle network errors
+     *       break;
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Combining with cancellation:
+     * const controller = new AbortController();
+     *
+     * const result = await Futurable.safe<string>(
+     *   (resolve, reject, { signal, fetch }) => {
+     *     fetch('/api/slow-endpoint')
+     *       .then(r => r.text())
+     *       .then(resolve)
+     *       .catch(reject);
+     *   },
+     *   controller.signal
+     * );
+     *
+     * // Cancel after 5 seconds
+     * setTimeout(() => controller.abort(), 5000);
+     * ```
+     */
+    static safe<T, E = unknown>(executor: FuturableExecutor<T>, signal?: AbortSignal): Futurable<SafeResult<T, E>>;
+}
+
+/**
+ * Configuration options for memoization behavior.
+ *
+ * @template T - The type of value being memoized
+ *
+ * @property enabled - Whether memoization is active
+ * @property catchErrors - If true, caches the result even when the execution rejects
+ * @property instance - The cached Futurable instance (if memoization is active)
+ */
+type MemoizeOptions<T> = {
+    enabled: boolean;
+    catchErrors?: boolean;
+    instance?: Futurable<T>;
+};
+/**
+ * Event hooks for monitoring task limiter lifecycle.
+ * All hooks are optional and provide insight into task execution flow.
+ *
+ * @property onActive - Called when a task starts executing
+ * @property onCompleted - Called when a task completes successfully with its result
+ * @property onError - Called when a task fails with an error
+ * @property onIdle - Called when all tasks have completed and the queue is empty
+ *
+ * @example
+ * ```typescript
+ * const events: LimiterEvents = {
+ *   onActive: (task) => console.log('Task started:', task),
+ *   onCompleted: (result) => console.log('Task completed:', result),
+ *   onError: (error) => console.error('Task failed:', error),
+ *   onIdle: () => console.log('All tasks finished')
+ * };
+ * ```
+ */
+interface LimiterEvents {
+    onActive?: (task: any) => void;
+    onCompleted?: (result: any) => void;
+    onError?: (error: any) => void;
+    onIdle?: () => void;
+}
+/**
+ * A higher-order function that wraps tasks with concurrency limiting.
+ *
+ * Acts as both a function and an object with readonly properties.
+ * The function takes a task and returns a new task that respects the concurrency limit.
+ *
+ * @property activeCount - Number of tasks currently executing
+ * @property pendingCount - Number of tasks waiting in the queue
+ * @property concurrency - Maximum number of concurrent tasks allowed
+ *
+ * @example
+ * ```typescript
+ * const limiter = FuturableTask.createLimiter(2);
+ *
+ * console.log(limiter.concurrency); // 2
+ * console.log(limiter.activeCount);  // 0
+ * console.log(limiter.pendingCount); // 0
+ *
+ * const limitedTask = limiter(myTask);
+ * ```
+ */
+type FuturableTaskLimiter = (<T>(task: FuturableTask<T>) => FuturableTask<T>) & {
+    readonly activeCount: number;
+    readonly pendingCount: number;
+    readonly concurrency: number;
+};
+/**
+ * Lazy computation wrapper for deferred execution.
+ *
+ * Unlike Futurable (which extends Promise and is eager), FuturableTask is lazy:
+ * - Creation doesn't trigger execution
+ * - Can be composed without side effects
+ * - Execution happens only when run() is called
+ * - Can be run multiple times (each run is independent)
+ * - Provides functional composition methods
+ * - Supports cancellation at both task and execution level
+ *
+ * @template T - The type of value this task will eventually produce
+ *
+ * @example
+ * ```typescript
+ * // Creating a task doesn't execute it
+ * const task = FuturableTask.of(() => {
+ *   console.log('Executing!');
+ *   return fetch('/api/data');
+ * });
+ * // Nothing logged yet
+ *
+ * const result1 = await task.run(); // Logs: "Executing!" and fetches
+ * const result2 = await task.run(); // Logs: "Executing!" again (independent execution)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Functional composition without execution
+ * const pipeline = FuturableTask
+ *   .of(() => fetch('/users'))
+ *   .map(res => res.json())
+ *   .map(users => users.filter(u => u.active))
+ *   .retry(3)
+ *   .timeout(5000);
+ *
+ * // Only now does execution happen
+ * const activeUsers = await pipeline.run();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Cancellation support
+ * const task = FuturableTask.of(() => longOperation())
+ *   .onCancel(() => console.log('Cleanup'));
+ *
+ * const run = task.run();
+ * task.cancel(); // Logs: "Cleanup", cancels the operation
+ * ```
+ */
+declare class FuturableTask<T> {
+    private readonly executor;
+    /**
+     * Internal AbortController that manages task cancellation.
+     * Created in the constructor and used to abort all executions of this task.
+     *
+     * @private
+     * @readonly
+     */
+    private readonly controller;
+    /**
+     * Array of callbacks to execute when the task is cancelled.
+     * These callbacks are executed eagerly (even if the task was never run).
+     *
+     * @private
+     * @readonly
+     */
+    private readonly cancelCallbacks;
+    /**
+     * Configuration object for memoization behavior.
+     * When enabled, caches the first execution result and reuses it.
+     *
+     * @private
+     * @readonly
+     */
+    private readonly memoizeOptions;
+    /**
+     * Reference to the source task (if this task is debounced).
+     * When calling debounce() on an already debounced task, this points to the original source.
+     *
+     * @private
+     */
+    private sourceTask?;
+    /**
+     * Creates a new FuturableTask.
+     *
+     * The executor function is NOT invoked until run() is called.
+     * If an external signal is provided, aborting it will also cancel this task.
+     *
+     * @param executor - The executor function that defines the computation.
+     *                   Receives resolve, reject, and utils (with signal, onCancel, delay, sleep, fetch, etc.)
+     * @param externalSignal - Optional AbortSignal that will cancel this task when aborted.
+     *                         Useful for coordinating cancellation with parent operations.
+     *
+     * @example
+     * ```typescript
+     * // Basic task
+     * const task = new FuturableTask((resolve, reject, utils) => {
+     *   setTimeout(() => resolve('done'), 1000);
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With cancellation support
+     * const task = new FuturableTask((resolve, reject, utils) => {
+     *   const timeoutId = setTimeout(() => resolve('done'), 5000);
+     *
+     *   utils.onCancel(() => {
+     *     console.log('Cancelled!');
+     *     clearTimeout(timeoutId);
+     *   });
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With external signal
+     * const controller = new AbortController();
+     * const task = new FuturableTask((res) => {
+     *   res('value');
+     * }, controller.signal);
+     *
+     * controller.abort(); // Cancels the task
+     * ```
+     */
+    constructor(executor: FuturableExecutor<T>, externalSignal?: AbortSignal);
+    /**
+     * Returns the internal AbortSignal for this task.
+     *
+     * This signal is aborted when cancel() is called on the task.
+     * All executions created by run() will listen to this signal.
+     *
+     * @returns The internal AbortSignal
+     *
+     * @example
+     * ```typescript
+     * const task = FuturableTask.of(() => fetch('/api/data'));
+     *
+     * console.log(task.signal.aborted); // false
+     * task.cancel();
+     * console.log(task.signal.aborted); // true
+     * ```
+     */
+    get signal(): AbortSignal;
+    /**
+     * Cancels all running and future executions of this task.
+     *
+     * This will:
+     * 1. Abort the internal signal
+     * 2. Execute all registered task-level onCancel callbacks
+     * 3. Cancel all Futurables created by run() that haven't completed yet
+     * 4. Prevent new executions from starting (they will be pending)
+     *
+     * Note: This is idempotent - calling it multiple times has no additional effect.
+     *
+     * @example
+     * ```typescript
+     * const task = FuturableTask.of(() => longRunningOperation());
+     * const run1 = task.run();
+     * const run2 = task.run();
+     *
+     * task.cancel(); // Cancels both run1 and run2
+     *
+     * const run3 = task.run(); // This will be pending (never resolves)
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const task = FuturableTask.of(() => fetch('/api'))
+     *   .onCancel(() => console.log('Task cancelled'));
+     *
+     * task.cancel(); // Logs: "Task cancelled"
+     * task.cancel(); // Does nothing (already cancelled)
+     * ```
+     */
+    cancel(): void;
+    /**
+     * Registers a callback to be executed when the task is cancelled.
+     *
+     * IMPORTANT: This is an eager callback - it executes when task.cancel() is called,
+     * even if the task has never been run. This is different from registering callbacks
+     * inside the executor with utils.onCancel, which are only called if the task was
+     * actively running when cancelled.
+     *
+     * Multiple callbacks can be registered and will execute in order.
+     *
+     * @param cb - Callback to execute on cancellation
+     * @returns The same FuturableTask instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const task = FuturableTask.of(() => fetch('/api/data'))
+     *   .onCancel(() => console.log('Task cancelled'))
+     *   .onCancel(() => console.log('Cleanup complete'));
+     *
+     * task.cancel();
+     * // Logs: "Task cancelled"
+     * // Logs: "Cleanup complete"
+     * // (even without calling run())
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Cleanup external resources
+     * const ws = new WebSocket('ws://...');
+     *
+     * const task = FuturableTask.of(() => fetchFromWebSocket(ws))
+     *   .onCancel(() => {
+     *     console.log('Closing WebSocket');
+     *     ws.close();
+     *   });
+     *
+     * task.cancel(); // Closes WebSocket even if never run
+     * ```
+     */
+    onCancel(cb: () => void): this;
+    /**
+     * Executes the task and returns a Futurable.
+     *
+     * Each call to run() creates a new independent execution. The returned Futurable
+     * can be cancelled in two ways:
+     * 1. By calling task.cancel() - cancels all running executions
+     * 2. By calling futurable.cancel() - cancels only this specific execution
+     * 3. By aborting the overrideSignal - cancels only this specific execution
+     *
+     * The execution uses a composite signal that listens to:
+     * - The task's internal signal (from task.cancel())
+     * - The overrideSignal (if provided)
+     *
+     * If the task is already cancelled, the returned Futurable will be pending (never resolves).
+     *
+     * @param overrideSignal - Optional signal to override/supplement the task's default signal.
+     *                         Useful for adding execution-specific cancellation.
+     * @returns A Futurable representing this execution
+     *
+     * @example
+     * ```typescript
+     * const task = FuturableTask.of(() => fetch('/data'));
+     *
+     * const run1 = task.run(); // Can be cancelled by task.cancel() or run1.cancel()
+     * const run2 = task.run(); // Independent execution
+     *
+     * task.cancel(); // Cancels both run1 and run2
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With override signal
+     * const task = FuturableTask.of(() => fetch('/data'));
+     * const controller = new AbortController();
+     *
+     * const run = task.run(controller.signal);
+     *
+     * controller.abort(); // Cancels only this execution
+     * // task itself is NOT cancelled, can still run() again
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Cancelled task produces pending Futurables
+     * const task = FuturableTask.of(() => fetch('/data'));
+     * task.cancel();
+     *
+     * const run = task.run(); // Never resolves or rejects (pending)
+     * ```
+     */
+    run(overrideSignal?: AbortSignal): Futurable<T>;
+    /**
+     * Executes the task and returns a SafeResult instead of throwing errors.
+     *
+     * This method wraps the task execution in a try-catch pattern that returns
+     * a discriminated union type, making error handling explicit and type-safe.
+     *
+     * The returned Futurable resolves to a SafeResult object that contains either:
+     * - `{ success: true, data: T, error: null }` on success
+     * - `{ success: false, data: null, error: E }` on failure
+     *
+     * This pattern eliminates the need for try-catch blocks and makes error
+     * handling explicit at the type level, similar to Rust's Result type.
+     *
+     * @template E - The type of error (defaults to unknown)
+     * @param overrideSignal - Optional signal to override/supplement the task's default signal
+     * @returns A Futurable that always resolves with a SafeResult (never rejects)
+     *
+     * @example
+     * ```typescript
+     * const task = FuturableTask.of(() => riskyOperation());
+     * const result = await task.runSafe();
+     *
+     * if (result.success) {
+     *   console.log('Success:', result.data);
+     *   // TypeScript knows result.data is T
+     * } else {
+     *   console.error('Error:', result.error);
+     *   // TypeScript knows result.error is E
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Chaining multiple safe operations
+     * const result1 = await task1.runSafe();
+     * if (!result1.success) return result1.error;
+     *
+     * const result2 = await task2.runSafe();
+     * if (!result2.success) return result2.error;
+     *
+     * return { data1: result1.data, data2: result2.data };
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With explicit error type
+     * const task = FuturableTask.of(() => fetchUser(id));
+     * const result = await task.runSafe<ApiError>();
+     *
+     * if (!result.success) {
+     *   // result.error is typed as ApiError
+     *   console.error('API Error:', result.error.statusCode);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Functional error handling without exceptions
+     * const results = await Promise.all([
+     *   task1.runSafe(),
+     *   task2.runSafe(),
+     *   task3.runSafe()
+     * ]);
+     *
+     * const errors = results.filter(r => !r.success);
+     * const successes = results.filter(r => r.success);
+     *
+     * console.log(`${successes.length} succeeded, ${errors.length} failed`);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With cancellation support
+     * const controller = new AbortController();
+     * const result = await task.runSafe(controller.signal);
+     *
+     * // Can be cancelled externally
+     * controller.abort();
+     * ```
+     */
+    runSafe<E = unknown>(overrideSignal?: AbortSignal): Futurable<SafeResult<T, E>>;
+    /**
+     * Caches the result of the first execution and reuses it for subsequent runs.
+     *
+     * All calls to run() after the first will return the same cached Futurable.
+     * This is useful for expensive computations that should only run once.
+     *
+     * IMPORTANT: The cached result is shared across all calls. If you need independent
+     * executions, don't use memoize() or create a new memoized task for each use case.
+     *
+     * Returns a NEW FuturableTask (does not mutate the original).
+     *
+     * @param catchErrors - If true, caches the result even when the execution rejects.
+     *                      If false (default), a rejection clears the cache and the next
+     *                      run() will retry the operation.
+     * @returns A new FuturableTask that caches its result
+     *
+     * @example
+     * ```typescript
+     * const expensiveTask = FuturableTask.of(() => {
+     *   console.log('Computing...');
+     *   return complexCalculation();
+     * }).memoize();
+     *
+     * await expensiveTask.run(); // Logs "Computing..." and calculates
+     * await expensiveTask.run(); // Returns cached result immediately (no log)
+     * await expensiveTask.run(); // Returns cached result immediately (no log)
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Without catchErrors (default) - retries on failure
+     * const task = FuturableTask.of(() => riskyOperation()).memoize();
+     *
+     * try {
+     *   await task.run(); // Fails
+     * } catch (err) {}
+     *
+     * await task.run(); // Retries (not cached because it failed)
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With catchErrors - caches failures too
+     * const task = FuturableTask.of(() => riskyOperation()).memoize(true);
+     *
+     * try {
+     *   await task.run(); // Fails
+     * } catch (err) {}
+     *
+     * try {
+     *   await task.run(); // Returns cached error (doesn't retry)
+     * } catch (err) {}
+     * ```
+     */
+    memoize(catchErrors?: boolean): FuturableTask<T>;
+    /**
+     * Transforms the task's result value using a mapping function.
+     *
+     * The transformation is lazy and won't execute until run() is called.
+     * The mapping function receives the resolved value and optionally the abort signal
+     * to check if the operation was cancelled.
+     *
+     * This is the basic building block for transforming task results.
+     *
+     * @template U - The type of the transformed value
+     * @param fn - Function to transform the value. Can be sync or async.
+     *             Receives the value and optionally the signal.
+     * @returns A new FuturableTask with the transformed value
+     *
+     * @example
+     * ```typescript
+     * const doubleTask = FuturableTask.resolve(5)
+     *   .map(x => x * 2);
+     *
+     * await doubleTask.run(); // 10
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Async transformation
+     * const task = FuturableTask.of(() => fetch('/users'))
+     *   .map(async res => await res.json())
+     *   .map(users => users.filter(u => u.active));
+     *
+     * const activeUsers = await task.run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Using the signal parameter
+     * const task = FuturableTask.of(() => fetchData())
+     *   .map((data, signal) => {
+     *     if (signal?.aborted) {
+     *       console.log('Mapping cancelled');
+     *       return null;
+     *     }
+     *     return expensiveTransformation(data);
+     *   });
+     * ```
+     */
+    map<U>(fn: (data: T, signal?: AbortSignal) => U | Promise<U>): FuturableTask<U>;
+    /**
+     * Chains this task with another task, creating a sequential composition.
+     *
+     * Also known as "bind" or "chain" in functional programming.
+     * The function receives the resolved value and must return a new FuturableTask.
+     *
+     * This allows you to create dependent computations where the next task
+     * depends on the result of the previous one.
+     *
+     * @template U - The type of value the chained task produces
+     * @param fn - Function that receives the value and returns a new FuturableTask
+     * @returns A new FuturableTask representing the chained computation
+     *
+     * @example
+     * ```typescript
+     * const getUserTask = FuturableTask.of(() => fetch('/user/1').then(r => r.json()));
+     * const getPostsTask = (user) => FuturableTask.of(() =>
+     *   fetch(`/users/${user.id}/posts`).then(r => r.json())
+     * );
+     *
+     * const userPosts = getUserTask.flatMap(getPostsTask);
+     * const posts = await userPosts.run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Chaining multiple dependent operations
+     * const result = await FuturableTask.of(() => readConfig())
+     *   .flatMap(config => FuturableTask.of(() => connectToDb(config)))
+     *   .flatMap(db => FuturableTask.of(() => db.query('SELECT * FROM users')))
+     *   .run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Error handling in chains
+     * const result = await FuturableTask.of(() => mayFail())
+     *   .flatMap(val => {
+     *     if (val < 0) {
+     *       return FuturableTask.reject(new Error('Negative value'));
+     *     }
+     *     return FuturableTask.resolve(val * 2);
+     *   })
+     *   .run();
+     * ```
+     */
+    flatMap<U>(fn: (data: T) => FuturableTask<U>): FuturableTask<U>;
+    /**
+     * Sequences this task with another task, discarding the first result.
+     *
+     * Executes the current task, waits for it to complete, then executes the next task.
+     * The result of the current task is ignored - only the next task's result is returned.
+     *
+     * Useful for sequencing side effects or setup operations before the main computation.
+     *
+     * @template U - The type of value the next task produces
+     * @param nextTask - The task to execute after this one
+     * @returns A new FuturableTask that produces the next task's result
+     *
+     * @example
+     * ```typescript
+     * const setupTask = FuturableTask.of(() => initializeApp());
+     * const mainTask = FuturableTask.of(() => fetchData());
+     *
+     * const result = await setupTask.andThen(mainTask).run();
+     * // setupTask runs first, then mainTask, result is from mainTask
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Chaining multiple sequential tasks
+     * await FuturableTask.of(() => clearCache())
+     *   .andThen(FuturableTask.of(() => warmupCache()))
+     *   .andThen(FuturableTask.of(() => startServer()))
+     *   .run();
+     * ```
+     */
+    andThen<U>(nextTask: FuturableTask<U>): FuturableTask<U>;
+    /**
+     * Executes a side-effect function with the task's value without modifying it.
+     *
+     * The value passes through unchanged. Useful for logging, debugging, or
+     * triggering actions based on the value without affecting the result.
+     *
+     * If the side-effect function throws or rejects, the error is propagated.
+     *
+     * @param fn - Side-effect function that receives the value. Can be sync or async.
+     * @returns A new FuturableTask that passes through the original value
+     *
+     * @example
+     * ```typescript
+     * const task = FuturableTask.of(() => fetchUser())
+     *   .tap(user => console.log('Fetched user:', user.id))
+     *   .map(user => user.name);
+     *
+     * const name = await task.run(); // Logs, then returns name
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Multiple taps for debugging
+     * const result = await FuturableTask.of(() => calculateResult())
+     *   .tap(val => console.log('Initial:', val))
+     *   .map(val => val * 2)
+     *   .tap(val => console.log('After doubling:', val))
+     *   .map(val => val + 10)
+     *   .tap(val => console.log('Final:', val))
+     *   .run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Side effects with external systems
+     * await FuturableTask.of(() => processData())
+     *   .tap(async data => {
+     *     await logToAnalytics('data_processed', data);
+     *   })
+     *   .run();
+     * ```
+     */
+    tap(fn: (data: T) => any): FuturableTask<T>;
+    /**
+     * Executes a side effect only if this task fails.
+     *
+     * The error is still propagated after the side effect executes.
+     * Useful for error logging or monitoring without handling the error.
+     *
+     * If the side-effect function itself throws, that error is logged to console
+     * but the original error is still propagated.
+     *
+     * @param fn - Function to execute on error. Can be sync or async.
+     * @returns A new FuturableTask that passes through the original error
+     *
+     * @example
+     * ```typescript
+     * await apiTask
+     *   .tapError(error => logger.error('API failed', error))
+     *   .tapError(error => sendToSentry(error))
+     *   .catch(handleError);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Log errors without stopping propagation
+     * try {
+     *   await FuturableTask.of(() => riskyOperation())
+     *     .tapError(err => console.error('Operation failed:', err))
+     *     .run();
+     * } catch (err) {
+     *   // err is the original error
+     *   console.log('Caught:', err);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const result = await FuturableTask.of(() => mayFail())
+     *   .tapError(err => analytics.trackError(err))
+     *   .orElse(err => FuturableTask.resolve(defaultValue))
+     *   .run();
+     * ```
+     */
+    tapError(fn: (error: any) => any): FuturableTask<T>;
+    /**
+     * Handles errors from the task execution by providing a fallback task.
+     *
+     * If the task succeeds, the result passes through unchanged.
+     * If the task fails, the fallback function is called with the error
+     * and must return a new FuturableTask to execute instead.
+     *
+     * The fallback task can return a different type, allowing for type transformations
+     * during error fallbackToy.
+     *
+     * @template U - The type of the fallbackToy value
+     * @param fallbackTask - Function that receives the error and returns a FuturableTask
+     * @returns A new FuturableTask with error handling
+     *
+     * @example
+     * ```typescript
+     * const task = FuturableTask.of(() => fetchFromPrimary())
+     *   .catchError(err => {
+     *     console.error('Primary failed:', err);
+     *     return FuturableTask.of(() => fetchFromBackup());
+     *   });
+     *
+     * const data = await task.run(); // Falls back to backup on error
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Retry with exponential backoff
+     * const task = FuturableTask.of(() => unstableOperation())
+     *   .catchError(err =>
+     *     FuturableTask.delay(1000)
+     *       .flatMap(() => FuturableTask.of(() => unstableOperation()))
+     *   );
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Type transformation on error
+     * const task: FuturableTask<User> = fetchUser()
+     *   .catchError((err): FuturableTask<User | null> => {
+     *     if (err.status === 404) {
+     *       return FuturableTask.resolve(null);
+     *     }
+     *     return FuturableTask.reject(err);
+     *   });
+     * ```
+     */
+    catchError<U>(fallbackTask: (err: any) => FuturableTask<U>): FuturableTask<T | U>;
+    /**
+     * Provides an alternative FuturableTask to execute if the current one fails.
+     *
+     * Similar to catchError, but ensures the result type remains consistent (type T).
+     * This is used for fallback logic like using cache if API fails.
+     *
+     * If the task succeeds, the result passes through unchanged.
+     * If the task fails, the fallback function is called with the error.
+     *
+     * @param fallbackTask - A function that receives the error and returns a fallback FuturableTask
+     * @returns A new FuturableTask that will attempt the alternative on failure
+     *
+     * @example
+     * ```typescript
+     * const task = FuturableTask.of(() => readLocalConfig())
+     *   .orElse(err => {
+     *     console.warn('Local config not found, loading default...');
+     *     return FuturableTask.of(() => readDefaultConfig());
+     *   });
+     *
+     * const config = await task.run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Cache fallback
+     * const task = FuturableTask.of(() => fetch('/api/data'))
+     *   .orElse(() => FuturableTask.of(() => loadFromCache()));
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Multiple fallbacks
+     * const task = FuturableTask.of(() => fetchFromPrimary())
+     *   .orElse(() => FuturableTask.of(() => fetchFromSecondary()))
+     *   .orElse(() => FuturableTask.of(() => fetchFromTertiary()));
+     * ```
+     */
+    orElse<U>(fallbackTask: (err: any) => FuturableTask<T | U>): FuturableTask<T | U>;
+    /**
+     * Provides a default value if the task fails.
+     *
+     * Simpler alternative to orElse when you just want to return a static value on failure.
+     * The fallback value is wrapped in a resolved task automatically.
+     *
+     * @param fallback - The default value to use if the task fails
+     * @returns A new FuturableTask that won't fail (returns fallback instead)
+     *
+     * @example
+     * ```typescript
+     * const data = await FuturableTask.of(() => fetchData())
+     *   .fallbackTo([])
+     *   .run();
+     * // Always succeeds, returns [] if fetch fails
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Configuration with defaults
+     * const config = await FuturableTask.of(() => loadUserConfig())
+     *   .fallbackTo(DEFAULT_CONFIG)
+     *   .run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Nullish values
+     * const user = await FuturableTask.of(() => fetchUser(id))
+     *   .fallbackTo(null)
+     *   .run();
+     * // Returns null instead of throwing on error
+     * ```
+     */
+    fallbackTo<U>(fallback: U): FuturableTask<T | U>;
+    /**
+     * Conditional branching based on the task's result.
+     *
+     * Evaluates a condition with the resolved value and executes one of two alternative
+     * tasks based on the result. Both branches must return tasks of the same type.
+     *
+     * The condition can be async, allowing for asynchronous decision-making.
+     *
+     * @template U - The type returned by both branches
+     * @param condition - Predicate function to evaluate (can be async)
+     * @param onTrue - Task to execute if condition is true
+     * @param onFalse - Task to execute if condition is false
+     * @returns A new FuturableTask with conditional execution
+     *
+     * @example
+     * ```typescript
+     * const result = await userTask.ifElse(
+     *   user => user.isPremium,
+     *   user => FuturableTask.of(() => loadPremiumContent(user)),
+     *   user => FuturableTask.of(() => loadBasicContent(user))
+     * ).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Async condition
+     * const task = FuturableTask.of(() => getUser())
+     *   .ifElse(
+     *     async user => await hasPermission(user, 'admin'),
+     *     user => FuturableTask.of(() => adminDashboard(user)),
+     *     user => FuturableTask.of(() => userDashboard(user))
+     *   );
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Validation with branching
+     * const processed = await FuturableTask.of(() => parseInput(data))
+     *   .ifElse(
+     *     parsed => parsed.isValid,
+     *     parsed => FuturableTask.of(() => processValidData(parsed)),
+     *     parsed => FuturableTask.reject(new Error('Invalid data'))
+     *   )
+     *   .run();
+     * ```
+     */
+    ifElse<U>(condition: (value: T) => boolean | Promise<boolean>, onTrue: (value: T) => FuturableTask<U>, onFalse: (value: T) => FuturableTask<U>): FuturableTask<U>;
+    /**
+     * Folds the result of the task execution into a single value by applying
+     * the appropriate transformation function.
+     *
+     * This is a catamorphism - it handles both success and failure cases uniformly,
+     * mapping them both to the same result type. Both transformation functions must
+     * return tasks of the same type.
+     *
+     * Useful when you want to treat success and failure symmetrically.
+     *
+     * @template U - The return type produced by the fold transformation
+     * @param onFailure - Transformation function applied if the promise rejects
+     * @param onSuccess - Transformation function applied if the promise resolves
+     * @returns A new FuturableTask that resolves to the transformation result
+     *
+     * @example
+     * ```typescript
+     * const message = await FuturableTask.of(() => fetchData())
+     *   .fold(
+     *     error => FuturableTask.resolve(`Error: ${error.message}`),
+     *     data => FuturableTask.resolve(`Success: ${data.length} items`)
+     *   )
+     *   .run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Result type for API responses
+     * type Result<T> = { success: true; data: T } | { success: false; error: string };
+     *
+     * const result: Result<User> = await fetchUser()
+     *   .fold(
+     *     error => FuturableTask.resolve({ success: false, error: error.message }),
+     *     user => FuturableTask.resolve({ success: true, data: user })
+     *   )
+     *   .run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Logging both outcomes
+     * await task.fold(
+     *   err => FuturableTask.of(() => logError(err)).map(() => 0),
+     *   val => FuturableTask.of(() => logSuccess(val)).map(() => val)
+     * ).run();
+     * ```
+     */
+    fold<U>(onFailure: (err: any) => FuturableTask<U>, onSuccess: (value: T) => FuturableTask<U>): FuturableTask<U>;
+    /**
+     * Registers a callback that runs when the task completes (success or failure).
+     *
+     * Similar to Promise.finally(). The callback cannot modify the result or error,
+     * but is useful for cleanup operations like closing connections or hiding spinners.
+     *
+     * If the callback throws or rejects, that error is propagated.
+     *
+     * @param callback - Function to execute on completion (can be async)
+     * @returns A new FuturableTask with the finally handler
+     *
+     * @example
+     * ```typescript
+     * const task = FuturableTask.of(() => fetchData())
+     *   .finally(() => {
+     *     console.log('Fetch completed');
+     *     hideSpinner();
+     *   });
+     *
+     * await task.run(); // Always hides spinner, even on error
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Cleanup resources
+     * const result = await FuturableTask.of(() => {
+     *   const connection = openConnection();
+     *   return processData(connection);
+     * })
+     * .finally(() => connection.close())
+     * .run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Multiple cleanup operations
+     * await task
+     *   .finally(() => releaseResource1())
+     *   .finally(() => releaseResource2())
+     *   .finally(() => console.log('All cleanup done'))
+     *   .run();
+     * ```
+     */
+    finally(callback: () => any): FuturableTask<T>;
+    /**
+     * Adds a timeout to the task execution.
+     *
+     * If the task doesn't complete within the specified time, it's cancelled
+     * and the task rejects with the provided reason.
+     *
+     * The timeout only applies when the task is run, not when it's created.
+     *
+     * @param ms - Timeout duration in milliseconds
+     * @param reason - Rejection reason (default: "TimeoutExceeded")
+     * @returns A new FuturableTask with timeout enforcement
+     *
+     * @example
+     * ```typescript
+     * const task = FuturableTask.of(() => fetch('/slow-api'))
+     *   .timeout(5000, new Error('Request timed out after 5s'));
+     *
+     * try {
+     *   await task.run();
+     * } catch (err) {
+     *   console.error(err); // "Request timed out after 5s"
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Timeout with default reason
+     * await FuturableTask.of(() => longOperation())
+     *   .timeout(3000)
+     *   .run(); // Rejects with "TimeoutExceeded" after 3s
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Chaining with retry
+     * const result = await FuturableTask.of(() => fetchData())
+     *   .timeout(5000)
+     *   .retry(3)
+     *   .run();
+     * // Each attempt has a 5s timeout
+     * ```
+     */
+    timeout(ms: number, reason?: any): FuturableTask<T>;
+    /**
+     * Delays the execution of the task by a specified duration.
+     *
+     * The timer starts when run() is called, not when delay() is called.
+     * The task waits for the specified duration before executing.
+     *
+     * Useful for rate limiting, debouncing, or implementing backoff strategies.
+     *
+     * @param ms - Delay duration in milliseconds
+     * @returns A new FuturableTask with the delay
+     *
+     * @example
+     * ```typescript
+     * const delayedTask = FuturableTask.of(() => sendEmail())
+     *   .delay(5000); // Wait 5 seconds before sending
+     *
+     * await delayedTask.run(); // Starts after 5s
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Progressive delays
+     * await FuturableTask.of(() => step1())
+     *   .andThen(FuturableTask.of(() => step2()).delay(1000))
+     *   .andThen(FuturableTask.of(() => step3()).delay(2000))
+     *   .run();
+     * // step1 immediately, step2 after 1s, step3 after 2s
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Cancellable delay
+     * const task = FuturableTask.of(() => operation()).delay(10000);
+     * const run = task.run();
+     * task.cancel(); // Cancels before the delay completes
+     * ```
+     */
+    delay(ms: number): FuturableTask<T>;
+    /**
+     * Retries the task up to n times on failure.
+     *
+     * Each retry is an independent execution of the original task.
+     * If all attempts fail, the last error is propagated.
+     *
+     * An optional delay can be added between retries for exponential backoff patterns.
+     *
+     * @param retries - Maximum number of retry attempts (0 means 1 total attempt)
+     * @param delayMs - Optional delay between retries in milliseconds (default: 0)
+     * @returns A new FuturableTask with retry logic
+     *
+     * @example
+     * ```typescript
+     * const unreliableTask = FuturableTask.of(() => fetch('/flaky-api'))
+     *   .retry(3); // Will try up to 4 times total (initial + 3 retries)
+     *
+     * const data = await unreliableTask.run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With delay between retries
+     * await FuturableTask.of(() => connectToService())
+     *   .retry(5, 1000) // Retry 5 times with 1s between attempts
+     *   .run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Exponential backoff (manual)
+     * let attempt = 0;
+     * const task = FuturableTask.of(() => fetch('/api'))
+     *   .tapError(() => attempt++)
+     *   .retry(3, Math.pow(2, attempt) * 1000);
+     * ```
+     */
+    retry(retries: number, delayMs?: number): FuturableTask<T>;
+    /**
+     * Creates a new Task that delays the execution of the original task with debounce logic.
+     *
+     * This method implements "smart debounce":
+     * - If called on a regular Task, it wraps it with a delay
+     * - If called on an already debounced Task (e.g., `.debounce(200).debounce(300)`),
+     *   it overrides the previous delay instead of nesting, ensuring only the
+     *   latest delay is applied to the source task
+     *
+     * Multiple calls to run() within the debounce window will cancel previous
+     * pending executions and restart the timer.
+     *
+     * Perfect for scenarios like search-as-you-type where you want to wait for
+     * user input to stabilize before executing.
+     *
+     * @param ms - The debounce delay in milliseconds
+     * @returns A new Task instance that manages the debounced execution
+     *
+     * @example
+     * ```typescript
+     * const searchTask = FuturableTask.of(() => searchAPI(query))
+     *   .debounce(300);
+     *
+     * // Rapidly calling run() multiple times:
+     * searchTask.run(); // Cancelled
+     * searchTask.run(); // Cancelled
+     * searchTask.run(); // This one executes after 300ms
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Smart debounce - latest delay wins
+     * const task = FuturableTask.of(() => operation())
+     *   .debounce(200)
+     *   .debounce(500); // Uses 500ms, not 200ms + 500ms
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Cancelling a debounced task
+     * const task = FuturableTask.of(() => saveData()).debounce(1000);
+     * task.run();
+     * task.cancel(); // Cancels the pending execution
+     * ```
+     */
+    debounce(ms: number): FuturableTask<T>;
+    /**
+     * Creates a new Task that limits the execution rate to once every 'ms' milliseconds.
+     *
+     * Unlike debounce, throttle ensures the task runs at a steady maximum rate.
+     * The first call executes immediately, and subsequent calls within the throttle
+     * window will return the result of the previous execution.
+     *
+     * Perfect for performance-heavy operations that need to run consistently
+     * during continuous events like scrolling, resizing, or mouse movement.
+     *
+     * @param ms - The throttle interval in milliseconds
+     * @returns A new Task instance with throttling logic
+     *
+     * @example
+     * ```typescript
+     * const scrollTask = FuturableTask.of(() => updateScrollPosition())
+     *   .throttle(100);
+     *
+     * window.addEventListener('scroll', () => {
+     *   scrollTask.run(); // Runs at most once per 100ms
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // API rate limiting
+     * const apiTask = FuturableTask.of(() => fetch('/api/data'))
+     *   .throttle(1000);
+     *
+     * // Rapid clicks will reuse the same result within 1s window
+     * button.addEventListener('click', () => {
+     *   apiTask.run().then(data => updateUI(data));
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Performance monitoring
+     * const monitor = FuturableTask.of(() => collectMetrics())
+     *   .throttle(5000);
+     *
+     * setInterval(() => monitor.run(), 100); // Collects every 5s despite 100ms interval
+     * ```
+     */
+    throttle(ms: number): FuturableTask<T>;
+    /**
+     * Combines this task with another task into a tuple of both results.
+     *
+     * Both tasks execute in parallel and the result is a tuple [T, U].
+     * If either task fails, the combined task fails.
+     *
+     * This is useful for combining independent operations that you need to perform together.
+     *
+     * @template U - The type of value the other task produces
+     * @param other - The task to combine with this one
+     * @returns A new FuturableTask that resolves with a tuple of both results
+     *
+     * @example
+     * ```typescript
+     * const userTask = FuturableTask.of(() => fetchUser());
+     * const postsTask = FuturableTask.of(() => fetchPosts());
+     *
+     * const [user, posts] = await userTask.zip(postsTask).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Combining multiple independent operations
+     * const combined = taskA
+     *   .zip(taskB)
+     *   .zip(taskC)
+     *   .run(); // [[A, B], C]
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Error handling - any failure cancels all
+     * try {
+     *   const [result1, result2] = await task1.zip(task2).run();
+     * } catch (err) {
+     *   // Either task1 or task2 failed
+     * }
+     * ```
+     */
+    zip<U>(other: FuturableTask<U>): FuturableTask<[T, U]>;
+    /**
+     * Combines this task with another task and applies a combining function.
+     *
+     * Similar to zip, but instead of returning a tuple, it applies a function
+     * to both results to produce a single combined value.
+     *
+     * Both tasks execute in parallel.
+     *
+     * @template U - The type of value the other task produces
+     * @template R - The type of the combined result
+     * @param other - The task to combine with this one
+     * @param fn - Function to combine both results
+     * @returns A new FuturableTask with the combined result
+     *
+     * @example
+     * ```typescript
+     * const sum = await taskA.zipWith(taskB, (a, b) => a + b).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Combining user data
+     * const fullProfile = await basicInfoTask.zipWith(
+     *   preferencesTask,
+     *   (basic, prefs) => ({ ...basic, preferences: prefs })
+     * ).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Computing derived values
+     * const average = await minTask.zipWith(
+     *   maxTask,
+     *   (min, max) => (min + max) / 2
+     * ).run();
+     * ```
+     */
+    zipWith<U, R>(other: FuturableTask<U>, fn: (a: T, b: U) => R): FuturableTask<R>;
+    /**
+     * Maps both success and error outcomes to new values.
+     *
+     * Applies different transformation functions depending on whether the task
+     * succeeds or fails. Unlike fold, the transformations are synchronous and
+     * don't return tasks.
+     *
+     * Useful for normalizing success and error cases into a consistent format.
+     *
+     * @template U - The type of the transformed success value
+     * @template V - The type of the transformed error value
+     * @param onSuccess - Function to transform the success value
+     * @param onError - Function to transform the error
+     * @returns A new FuturableTask with transformed success/error
+     *
+     * @example
+     * ```typescript
+     * const task = FuturableTask.of(() => riskyOperation())
+     *   .bimap(
+     *     result => `Success: ${result}`,
+     *     error => new CustomError(error.message)
+     *   );
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Normalizing API responses
+     * const normalized = await fetchData()
+     *   .bimap(
+     *     data => ({ status: 'ok', data }),
+     *     err => ({ status: 'error', message: err.message })
+     *   )
+     *   .run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Adding context to errors
+     * await task.bimap(
+     *   val => val,
+     *   err => new Error(`Operation failed: ${err.message}`)
+     * ).run();
+     * ```
+     */
+    bimap<U, V>(onSuccess: (value: T) => U, onError: (error: any) => V): FuturableTask<U>;
+    /**
+     * Repeats this task n times, collecting all results.
+     *
+     * Each execution is independent. If any execution fails, the entire
+     * repeat operation fails.
+     *
+     * Executes sequentially, not in parallel.
+     *
+     * @param n - Number of times to repeat (must be >= 0)
+     * @returns A new FuturableTask that resolves with an array of all results
+     *
+     * @example
+     * ```typescript
+     * const results = await task.repeat(3).run(); // [result1, result2, result3]
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Collecting multiple samples
+     * const measurements = await FuturableTask.of(() => takeMeasurement())
+     *   .repeat(10)
+     *   .map(samples => average(samples))
+     *   .run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Batch operations
+     * const created = await FuturableTask.of(() => createRecord())
+     *   .repeat(5)
+     *   .run();
+     * ```
+     */
+    repeat(n: number): FuturableTask<T[]>;
+    /**
+     * Composes multiple transformation functions in sequence.
+     *
+     * Applies transformations from left to right, passing the result of each
+     * transformation to the next. Type-safe for up to 9 transformations.
+     *
+     * This is a powerful way to build complex task pipelines in a readable way.
+     *
+     * @param fns - Transformation functions to apply in order
+     * @returns The result of applying all transformations
+     *
+     * @example
+     * ```typescript
+     * const addRetry = (task) => task.retry(3);
+     * const addTimeout = (task) => task.timeout(5000);
+     * const addLogging = (task) => task.tap(x => console.log(x));
+     *
+     * const enhanced = baseTask.pipe(addRetry, addTimeout, addLogging);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Building a processing pipeline
+     * const processData = (task: FuturableTask<string>) => task
+     *   .pipe(
+     *     t => t.map(s => s.trim()),
+     *     t => t.map(s => s.toLowerCase()),
+     *     t => t.map(s => s.split(',')),
+     *     t => t.map(arr => arr.map(s => s.trim()))
+     *   );
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Reusable middleware
+     * const withErrorHandling = (task) => task.tapError(logError);
+     * const withRetry = (task) => task.retry(3, 1000);
+     * const withTimeout = (task) => task.timeout(10000);
+     *
+     * const robustTask = apiTask.pipe(
+     *   withErrorHandling,
+     *   withRetry,
+     *   withTimeout
+     * );
+     * ```
+     */
+    pipe<A>(f1: (t: FuturableTask<T>) => A): A;
+    pipe<A, B>(f1: (t: FuturableTask<T>) => A, f2: (a: A) => B): B;
+    pipe<A, B, C>(f1: (t: FuturableTask<T>) => A, f2: (a: A) => B, f3: (b: B) => C): C;
+    pipe<A, B, C, D>(f1: (t: FuturableTask<T>) => A, f2: (a: A) => B, f3: (b: B) => C, f4: (c: C) => D): D;
+    pipe<A, B, C, D, E>(f1: (t: FuturableTask<T>) => A, f2: (a: A) => B, f3: (b: B) => C, f4: (c: C) => D, f5: (d: D) => E): E;
+    pipe<A, B, C, D, E, F>(f1: (t: FuturableTask<T>) => A, f2: (a: A) => B, f3: (b: B) => C, f4: (c: C) => D, f5: (d: D) => E, f6: (e: E) => F): F;
+    pipe<A, B, C, D, E, F, G>(f1: (t: FuturableTask<T>) => A, f2: (a: A) => B, f3: (b: B) => C, f4: (c: C) => D, f5: (d: D) => E, f6: (e: E) => F, f7: (f: F) => G): G;
+    pipe<A, B, C, D, E, F, G, H>(f1: (t: FuturableTask<T>) => A, f2: (a: A) => B, f3: (b: B) => C, f4: (c: C) => D, f5: (d: D) => E, f6: (e: E) => F, f7: (f: F) => G, f8: (g: G) => H): H;
+    pipe<A, B, C, D, E, F, G, H, I>(f1: (t: FuturableTask<T>) => A, f2: (a: A) => B, f3: (b: B) => C, f4: (c: C) => D, f5: (d: D) => E, f6: (e: E) => F, f7: (f: F) => G, f8: (g: G) => H, f9: (h: H) => I): I;
+    /**
+     * Creates a new FuturableTask that performs an HTTP fetch when executed.
+     *
+     * @param url - URL to fetch, or a function receiving the task's value
+     * @param opts - Fetch options, or a function receiving the task's value
+     * @returns A new FuturableTask that resolves with the Response
+     *
+     * @example
+     * ```typescript
+     * const fetchTask = FuturableTask.resolve('users')
+     *   .fetch(endpoint => `https://api.example.com/${endpoint}`);
+     *
+     * const response = await fetchTask.run();
+     * const data = await response.json();
+     * ```
+     */
+    fetch(url: string | ((val: T) => string), opts?: RequestInit | ((val: T) => RequestInit)): FuturableTask<Response>;
+    /**
+     * Creates a FuturableTask from various input types.
+     *
+     * Accepts:
+     * - Plain values: Wraps in a task that resolves immediately
+     * - Functions: Creates a task that executes the function
+     *
+     * Functions receive FuturableUtils with signal, onCancel, delay, sleep, fetch, etc.
+     *
+     * @template U - Type of the value
+     * @param input - A value or a function that returns a value/Promise
+     * @param signal - Optional AbortSignal for the task
+     * @returns A new FuturableTask
+     *
+     * @example
+     * ```typescript
+     * // From a value
+     * const task1 = FuturableTask.of(42);
+     * await task1.run(); // 42
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // From a function
+     * const task2 = FuturableTask.of(() => fetch('/api').then(r => r.json()));
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With utils
+     * const task3 = FuturableTask.of(async (utils) => {
+     *   const response = await utils.fetch('/api/data');
+     *   return response.json();
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With external signal
+     * const controller = new AbortController();
+     * const task = FuturableTask.of(() => operation(), controller.signal);
+     * ```
+     */
+    static of<U>(input: U | ((utils: FuturableUtils<U>) => Promise<U>), signal?: AbortSignal): FuturableTask<U>;
+    /**
+     * Creates a FuturableTask that immediately resolves with the given value.
+     *
+     * Alias for FuturableTask.of() when passing a plain value.
+     * Useful for lifting values into the Task context.
+     *
+     * @template U - Type of the value
+     * @param v - The value to resolve with
+     * @param signal - Optional AbortSignal for the task
+     * @returns A FuturableTask that resolves to the value
+     *
+     * @example
+     * ```typescript
+     * const task = FuturableTask.resolve(42)
+     *   .map(x => x * 2);
+     *
+     * await task.run(); // 84
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Creating task chains
+     * const pipeline = FuturableTask.resolve(data)
+     *   .map(d => transform(d))
+     *   .flatMap(t => FuturableTask.of(() => save(t)));
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Default values
+     * const task = condition
+     *   ? FuturableTask.of(() => fetchData())
+     *   : FuturableTask.resolve(defaultData);
+     * ```
+     */
+    static resolve<U = any>(v: U, signal?: AbortSignal): FuturableTask<U>;
+    /**
+     * Creates a FuturableTask that immediately rejects with the given reason.
+     *
+     * Useful for creating tasks that represent known failures,
+     * or for testing error handling logic.
+     *
+     * @param reason - The rejection reason (typically an Error)
+     * @param signal - Optional AbortSignal for the task
+     * @returns A FuturableTask that rejects with the reason
+     *
+     * @example
+     * ```typescript
+     * const task = FuturableTask.reject(new Error('Not implemented'))
+     *   .orElse(() => FuturableTask.of(() => fallbackImplementation()));
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Conditional errors
+     * const task = value < 0
+     *   ? FuturableTask.reject(new Error('Value must be positive'))
+     *   : FuturableTask.of(() => process(value));
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Testing error handlers
+     * const testTask = FuturableTask.reject(new Error('Test error'))
+     *   .tapError(err => assert(err.message === 'Test error'));
+     * ```
+     */
+    static reject<U = never>(reason: any, signal?: AbortSignal): FuturableTask<U>;
+    /**
+     * Executes all tasks in parallel and resolves when all complete.
+     *
+     * All tasks run concurrently. If any task fails, the combined task
+     * fails immediately and all running tasks are cancelled.
+     *
+     * Returns an array of results in the same order as the input tasks.
+     *
+     * @template T - Type of values the tasks produce
+     * @param tasks - Array of FuturableTasks to execute in parallel
+     * @param signal - Optional AbortSignal for the combined task
+     * @returns A FuturableTask that resolves with an array of all results
+     *
+     * @example
+     * ```typescript
+     * const tasks = [
+     *   FuturableTask.of(() => fetch('/api/users')),
+     *   FuturableTask.of(() => fetch('/api/posts')),
+     *   FuturableTask.of(() => fetch('/api/comments'))
+     * ];
+     *
+     * const [users, posts, comments] = await FuturableTask.all(tasks).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With error handling
+     * try {
+     *   const results = await FuturableTask.all([task1, task2, task3]).run();
+     * } catch (err) {
+     *   // One of the tasks failed, others were cancelled
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Dynamic task lists
+     * const userIds = [1, 2, 3, 4, 5];
+     * const tasks = userIds.map(id =>
+     *   FuturableTask.of(() => fetchUser(id))
+     * );
+     * const users = await FuturableTask.all(tasks).run();
+     * ```
+     */
+    static all<T>(tasks: FuturableTask<T>[], signal?: AbortSignal): FuturableTask<T[]>;
+    /**
+     * Executes all tasks in parallel and waits for all to settle (resolve or reject).
+     *
+     * Never rejects. Returns an array of result objects indicating the outcome
+     * of each task. Each result has a status ('fulfilled' or 'rejected') and
+     * either a value or reason.
+     *
+     * Useful when you want to attempt multiple operations and handle failures individually.
+     *
+     * @template T - Type of values the tasks produce
+     * @param tasks - Array of FuturableTasks to execute
+     * @param signal - Optional AbortSignal for the combined task
+     * @returns A FuturableTask that resolves with an array of PromiseSettledResult objects
+     *
+     * @example
+     * ```typescript
+     * const results = await FuturableTask.allSettled([
+     *   FuturableTask.resolve(1),
+     *   FuturableTask.reject('error'),
+     *   FuturableTask.resolve(3)
+     * ]).run();
+     *
+     * results.forEach(result => {
+     *   if (result.status === 'fulfilled') {
+     *     console.log('Success:', result.value);
+     *   } else {
+     *     console.log('Failed:', result.reason);
+     *   }
+     * });
+     * // Success: 1
+     * // Failed: error
+     * // Success: 3
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Batch operations with individual error handling
+     * const results = await FuturableTask.allSettled(
+     *   userIds.map(id => FuturableTask.of(() => deleteUser(id)))
+     * ).run();
+     *
+     * const succeeded = results.filter(r => r.status === 'fulfilled').length;
+     * const failed = results.filter(r => r.status === 'rejected').length;
+     * console.log(`Deleted ${succeeded}, failed ${failed}`);
+     * ```
+     */
+    static allSettled<T>(tasks: FuturableTask<T>[], signal?: AbortSignal): FuturableTask<PromiseSettledResult<T>[]>;
+    /**
+     * Executes all tasks in parallel and resolves/rejects with the first to settle.
+     *
+     * Once one task settles (successfully or with error), all other tasks are cancelled.
+     * The result matches the first settled task - success or failure.
+     *
+     * Useful for timeout patterns or racing multiple data sources.
+     *
+     * @template T - Type of values the tasks produce
+     * @param tasks - Array of FuturableTasks to race
+     * @param signal - Optional AbortSignal for the combined task
+     * @returns A FuturableTask that settles with the first task's result
+     *
+     * @example
+     * ```typescript
+     * const fastest = await FuturableTask.race([
+     *   FuturableTask.of(() => fetchFromCDN1()),
+     *   FuturableTask.of(() => fetchFromCDN2()),
+     *   FuturableTask.of(() => fetchFromCDN3())
+     * ]).run();
+     *
+     * console.log('Fastest CDN responded with:', fastest);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Timeout pattern
+     * const result = await FuturableTask.race([
+     *   FuturableTask.of(() => slowOperation()),
+     *   FuturableTask.delay(5000).flatMap(() =>
+     *     FuturableTask.reject(new Error('Timeout'))
+     *   )
+     * ]).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // First successful response wins
+     * const data = await FuturableTask.race([
+     *   cacheTask,
+     *   apiTask
+     * ]).run(); // Uses cache if available, API otherwise
+     * ```
+     */
+    static race<T>(tasks: FuturableTask<T>[], signal?: AbortSignal): FuturableTask<T>;
+    /**
+     * Executes all tasks in parallel and resolves with the first successful result.
+     *
+     * Ignores failures and only resolves when at least one task succeeds.
+     * Only rejects if ALL tasks fail (with an AggregateError containing all errors).
+     *
+     * Perfect for fallback scenarios with multiple alternatives.
+     *
+     * @template T - Type of values the tasks produce
+     * @param tasks - Array of FuturableTasks to execute
+     * @param signal - Optional AbortSignal for the combined task
+     * @returns A FuturableTask that resolves with the first success
+     *
+     * @example
+     * ```typescript
+     * const data = await FuturableTask.any([
+     *   FuturableTask.of(() => fetchFromPrimaryServer()),
+     *   FuturableTask.of(() => fetchFromBackupServer1()),
+     *   FuturableTask.of(() => fetchFromBackupServer2())
+     * ]).run();
+     *
+     * // Returns data from whichever server responds successfully first
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Multiple fallback sources
+     * const config = await FuturableTask.any([
+     *   FuturableTask.of(() => loadFromEnv()),
+     *   FuturableTask.of(() => loadFromFile()),
+     *   FuturableTask.of(() => loadDefaults())
+     * ]).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // All fail case
+     * try {
+     *   await FuturableTask.any([
+     *     FuturableTask.reject('error1'),
+     *     FuturableTask.reject('error2')
+     *   ]).run();
+     * } catch (err) {
+     *   console.log(err.errors); // ['error1', 'error2']
+     * }
+     * ```
+     */
+    static any<T>(tasks: FuturableTask<T>[], signal?: AbortSignal): FuturableTask<T>;
+    /**
+     * Creates a FuturableTask that resolves after a specified delay.
+     *
+     * The delay is lazy - it only starts when run() is called.
+     * The task resolves with void (no value).
+     *
+     * Useful for adding delays in task chains or implementing backoff strategies.
+     *
+     * @param ms - Delay duration in milliseconds
+     * @param signal - Optional AbortSignal for the task
+     * @returns A FuturableTask that resolves after the delay
+     *
+     * @example
+     * ```typescript
+     * await FuturableTask.delay(2000).run(); // Waits 2 seconds
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Chaining with delays
+     * await FuturableTask.resolve('Starting...')
+     *   .tap(console.log)
+     *   .andThen(FuturableTask.delay(1000))
+     *   .andThen(FuturableTask.resolve('Done!'))
+     *   .tap(console.log)
+     *   .run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Cancellable delay
+     * const delayTask = FuturableTask.delay(5000);
+     * delayTask.run();
+     * delayTask.cancel(); // Cancels the delay
+     * ```
+     */
+    static delay(ms: number, signal?: AbortSignal): FuturableTask<void>;
+    /**
+     * Creates a FuturableTask from an event listener on a given target.
+     *
+     * The listener is only attached when run() is called, and automatically
+     * unsubscribes after the first occurrence to maintain single-value semantics.
+     *
+     * If the task is cancelled before the event fires, the listener is properly
+     * removed to prevent memory leaks.
+     *
+     * @template E - The type of the Event object
+     * @param target - The DOM element, Window, or event target
+     * @param name - The name of the event to listen for (e.g., 'click', 'message')
+     * @param opts - Standard listener options like capture, passive, or once
+     * @param signal - Optional AbortSignal for the task
+     * @returns A new FuturableTask that resolves with the Event object
+     *
+     * @example
+     * ```typescript
+     * // Listen for a one-time click
+     * const clickTask = FuturableTask.fromEvent(
+     *   document.getElementById('myBtn'),
+     *   'click',
+     *   { passive: true }
+     * );
+     *
+     * const event = await clickTask.run();
+     * console.log('Button clicked at:', event.timeStamp);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With timeout
+     * try {
+     *   const event = await FuturableTask
+     *     .fromEvent(button, 'click')
+     *     .timeout(5000, new Error('No click within 5 seconds'))
+     *     .run();
+     * } catch (err) {
+     *   console.log('Timed out waiting for click');
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Cancellable event listener
+     * const task = FuturableTask.fromEvent(window, 'resize');
+     * task.run();
+     * // ... later
+     * task.cancel(); // Removes the listener
+     * ```
+     */
+    static fromEvent<E extends Event>(target: EventTarget, name: string, opts?: AddEventListenerOptions, signal?: AbortSignal): FuturableTask<E>;
+    /**
+     * Executes an array of tasks sequentially, one after another.
+     *
+     * Each task waits for the previous one to complete before starting.
+     * If any task fails, the sequence stops and the error is propagated.
+     *
+     * Returns an array of all results in order.
+     *
+     * @template T - Type of values the tasks produce
+     * @param tasks - Array of FuturableTasks to execute in sequence
+     * @param signal - Optional AbortSignal for the combined task
+     * @returns A FuturableTask that resolves with an array of all results
+     *
+     * @example
+     * ```typescript
+     * const tasks = [
+     *   FuturableTask.of(() => step1()),
+     *   FuturableTask.of(() => step2()),
+     *   FuturableTask.of(() => step3())
+     * ];
+     *
+     * const results = await FuturableTask.sequence(tasks).run();
+     * // step1 completes, then step2, then step3
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Database migrations in order
+     * const migrations = [
+     *   FuturableTask.of(() => createUsersTable()),
+     *   FuturableTask.of(() => createPostsTable()),
+     *   FuturableTask.of(() => addForeignKeys())
+     * ];
+     * await FuturableTask.sequence(migrations).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With delays between steps
+     * const steps = [
+     *   FuturableTask.of(() => init()),
+     *   FuturableTask.delay(1000).andThen(FuturableTask.of(() => warmup())),
+     *   FuturableTask.delay(2000).andThen(FuturableTask.of(() => start()))
+     * ];
+     * await FuturableTask.sequence(steps).run();
+     * ```
+     */
+    static sequence<T>(tasks: FuturableTask<T>[], signal?: AbortSignal): FuturableTask<T[]>;
+    /**
+     * Executes tasks in parallel with a concurrency limit.
+     *
+     * Limits the number of tasks running simultaneously. When a task completes,
+     * the next queued task starts. If any task fails, all running tasks are
+     * cancelled and the error is propagated.
+     *
+     * Returns results in the same order as input tasks.
+     *
+     * @template T - Type of value the tasks produce
+     * @param tasks - Array of FuturableTasks
+     * @param limit - Maximum number of concurrent executions (default: 5)
+     * @param signal - Optional AbortSignal for the combined task
+     * @returns A FuturableTask that resolves with an array of all results
+     *
+     * @example
+     * ```typescript
+     * // Process 100 items with max 5 concurrent operations
+     * const tasks = items.map(item =>
+     *   FuturableTask.of(() => processItem(item))
+     * );
+     *
+     * const results = await FuturableTask.parallel(tasks, 5).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // API rate limiting - max 3 concurrent requests
+     * const userTasks = userIds.map(id =>
+     *   FuturableTask.of(() => fetch(`/api/users/${id}`))
+     * );
+     *
+     * const users = await FuturableTask.parallel(userTasks, 3).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With error handling
+     * try {
+     *   const results = await FuturableTask.parallel(tasks, 10).run();
+     * } catch (err) {
+     *   // One task failed, all running tasks were cancelled
+     * }
+     * ```
+     */
+    static parallel<T>(tasks: FuturableTask<T>[], limit?: number, signal?: AbortSignal): FuturableTask<T[]>;
+    /**
+     * Creates a higher-order function (limiter) to control the maximum number
+     * of concurrent executions for a set of Tasks.
+     *
+     * Tasks do not enter the queue or increment the running counter until
+     * their .run() method is explicitly called. Tasks are processed FIFO.
+     *
+     * Optional event hooks allow tracking active tasks, completions, errors, and idle states.
+     *
+     * The returned limiter function wraps tasks and includes readonly properties
+     * for monitoring (activeCount, pendingCount, concurrency).
+     *
+     * @param concurrency - Maximum number of tasks allowed to run simultaneously (must be >= 1)
+     * @param events - Optional lifecycle hooks for monitoring
+     * @param signal - Optional AbortSignal for the limiter
+     * @returns A decorator function that limits task concurrency
+     *
+     * @example
+     * ```typescript
+     * const limiter = FuturableTask.createLimiter(2, {
+     *   onActive: (task) => console.log('Task started'),
+     *   onCompleted: (result) => console.log('Task completed:', result),
+     *   onIdle: () => console.log('All tasks finished!')
+     * });
+     *
+     * // Wrap your original tasks
+     * const tasks = [1,2,3,4,5].map(i => limiter(
+     *   FuturableTask.of(async () => {
+     *     await delay(1000);
+     *     return i;
+     *   })
+     * ));
+     *
+     * // Execution starts here, respects limit of 2
+     * const results = await FuturableTask.all(tasks).run();
+     * console.log(results); // [1, 2, 3, 4, 5]
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Monitoring limiter state
+     * const limiter = FuturableTask.createLimiter(3);
+     *
+     * console.log(limiter.concurrency);  // 3
+     * console.log(limiter.activeCount);  // 0
+     * console.log(limiter.pendingCount); // 0
+     *
+     * const task = limiter(FuturableTask.of(() => operation()));
+     * task.run();
+     *
+     * console.log(limiter.activeCount);  // 1
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // API rate limiting
+     * const apiLimiter = FuturableTask.createLimiter(5, {
+     *   onError: (err) => logger.error('API call failed', err)
+     * });
+     *
+     * const fetchUser = (id) => apiLimiter(
+     *   FuturableTask.of(() => fetch(`/api/users/${id}`))
+     * );
+     *
+     * const users = await FuturableTask.all(
+     *   userIds.map(fetchUser)
+     * ).run();
+     * ```
+     */
+    static createLimiter(concurrency: number, events?: LimiterEvents, signal?: AbortSignal): FuturableTaskLimiter;
+    /**
+     * Composes a FuturableTask through a sequence of transformation operators.
+     *
+     * Applies operators from left to right, similar to pipe but starting with
+     * an initial task. Type-safe composition ensures each operator's output
+     * matches the next operator's input.
+     *
+     * Useful for building reusable task pipelines.
+     *
+     * @template T - The type of the value produced by the initial task
+     * @template R - The type of the value produced by the final task
+     * @param initial - The starting FuturableTask to transform
+     * @param operators - Variadic list of transformation functions
+     * @returns A new FuturableTask representing the composed operations
+     *
+     * @example
+     * ```typescript
+     * // Linear composition
+     * const finalTask = FuturableTask.compose(
+     *   FuturableTask.of(() => fetchUser(1)),
+     *   (t) => t.retry(3),
+     *   (t) => t.timeout(5000),
+     *   (t) => t.map(user => user.name)
+     * );
+     *
+     * const name = await finalTask.run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Building reusable pipelines
+     * const robustAPI = <T>(task: FuturableTask<T>) =>
+     *   FuturableTask.compose(
+     *     task,
+     *     t => t.retry(3, 1000),
+     *     t => t.timeout(10000),
+     *     t => t.tapError(err => logger.error(err))
+     *   );
+     *
+     * const userData = await robustAPI(
+     *   FuturableTask.of(() => fetch('/api/user'))
+     * ).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Data processing pipeline
+     * const processData = FuturableTask.compose(
+     *   FuturableTask.of(() => loadRawData()),
+     *   t => t.map(data => validate(data)),
+     *   t => t.map(data => transform(data)),
+     *   t => t.flatMap(data => FuturableTask.of(() => save(data)))
+     * );
+     * ```
+     */
+    static compose<T, R>(initial: FuturableTask<T>, ...operators: Array<(t: FuturableTask<any>) => FuturableTask<any>>): FuturableTask<R>;
+    /**
+     * Filters an array of tasks based on a predicate.
+     *
+     * Executes all tasks sequentially, then applies the predicate to each result.
+     * Only values that pass the predicate are included in the final array.
+     *
+     * The predicate can be async, allowing for asynchronous filtering logic.
+     *
+     * @template T - Type of values the tasks produce
+     * @param tasks - Array of tasks to filter
+     * @param predicate - Function to test each value (can be async)
+     * @param signal - Optional AbortSignal for the combined task
+     * @returns A FuturableTask that resolves with filtered values
+     *
+     * @example
+     * ```typescript
+     * const tasks = [
+     *   FuturableTask.resolve(1),
+     *   FuturableTask.resolve(2),
+     *   FuturableTask.resolve(3),
+     *   FuturableTask.resolve(4)
+     * ];
+     *
+     * const evenNumbers = await FuturableTask
+     *   .filter(tasks, n => n % 2 === 0)
+     *   .run(); // [2, 4]
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Async filtering
+     * const userTasks = ids.map(id => FuturableTask.of(() => fetchUser(id)));
+     *
+     * const activeUsers = await FuturableTask.filter(
+     *   userTasks,
+     *   async user => await isActive(user.id)
+     * ).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filtering with validation
+     * const results = await FuturableTask.filter(
+     *   dataTasks,
+     *   data => data.isValid && data.score > 0.5
+     * ).run();
+     * ```
+     */
+    static filter<T>(tasks: FuturableTask<T>[], predicate: (value: T) => boolean | Promise<boolean>, signal?: AbortSignal): FuturableTask<T[]>;
+    /**
+     * Reduces an array of tasks to a single value.
+     *
+     * Executes tasks sequentially, accumulating a result by applying the reducer
+     * function to each task's value. The reducer receives the accumulator, current
+     * value, and index.
+     *
+     * The reducer can be async.
+     *
+     * @template T - Type of values the tasks produce
+     * @template U - Type of the accumulated result
+     * @param tasks - Array of tasks to reduce
+     * @param reducer - Function to accumulate results (can be async)
+     * @param initialValue - Initial value for the accumulator
+     * @param signal - Optional AbortSignal for the combined task
+     * @returns A FuturableTask that resolves with the final accumulated value
+     *
+     * @example
+     * ```typescript
+     * const tasks = [
+     *   FuturableTask.resolve(1),
+     *   FuturableTask.resolve(2),
+     *   FuturableTask.resolve(3)
+     * ];
+     *
+     * const sum = await FuturableTask
+     *   .reduce(tasks, (acc, n) => acc + n, 0)
+     *   .run(); // 6
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Building an object from tasks
+     * const userTasks = ids.map(id => FuturableTask.of(() => fetchUser(id)));
+     *
+     * const userMap = await FuturableTask.reduce(
+     *   userTasks,
+     *   (map, user) => ({ ...map, [user.id]: user }),
+     *   {}
+     * ).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Async reducer
+     * const total = await FuturableTask.reduce(
+     *   tasks,
+     *   async (acc, value) => {
+     *     const processed = await processValue(value);
+     *     return acc + processed;
+     *   },
+     *   0
+     * ).run();
+     * ```
+     */
+    static reduce<T, U>(tasks: FuturableTask<T>[], reducer: (acc: U, value: T, index: number) => U | Promise<U>, initialValue: U, signal?: AbortSignal): FuturableTask<U>;
+    /**
+     * Repeatedly executes a task while a condition is true.
+     *
+     * Evaluates the condition before each execution. Stops when the condition
+     * returns false or the task fails. Returns an array of all results.
+     *
+     * The condition can be async.
+     *
+     * @template T - Type of value the task produces
+     * @param condition - Predicate evaluated before each execution (can be async)
+     * @param task - The task to execute repeatedly
+     * @param signal - Optional AbortSignal for the combined task
+     * @returns A FuturableTask that resolves with an array of all results
+     *
+     * @example
+     * ```typescript
+     * let counter = 0;
+     * const incrementTask = FuturableTask.of(() => ++counter);
+     *
+     * const results = await FuturableTask
+     *   .whilst(() => counter < 5, incrementTask)
+     *   .run(); // [1, 2, 3, 4, 5]
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Async condition
+     * const results = await FuturableTask.whilst(
+     *   async () => await hasMoreData(),
+     *   FuturableTask.of(() => fetchNextBatch())
+     * ).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Paginated fetching
+     * let page = 1;
+     * let hasMore = true;
+     *
+     * const allData = await FuturableTask.whilst(
+     *   () => hasMore,
+     *   FuturableTask.of(async () => {
+     *     const response = await fetchPage(page++);
+     *     hasMore = response.hasMore;
+     *     return response.data;
+     *   })
+     * ).run();
+     * ```
+     */
+    static whilst<T>(condition: () => boolean | Promise<boolean>, task: FuturableTask<T>, signal?: AbortSignal): FuturableTask<T[]>;
+    /**
+     * Repeatedly executes a task until a condition becomes true.
+     *
+     * Opposite of whilst - executes while the condition is false.
+     * Evaluates the condition before each execution.
+     *
+     * The condition can be async.
+     *
+     * @template T - Type of value the task produces
+     * @param condition - Predicate that stops execution when true (can be async)
+     * @param task - The task to execute repeatedly
+     * @param signal - Optional AbortSignal for the combined task
+     * @returns A FuturableTask that resolves with an array of all results
+     *
+     * @example
+     * ```typescript
+     * let counter = 0;
+     * const incrementTask = FuturableTask.of(() => ++counter);
+     *
+     * const results = await FuturableTask
+     *   .until(() => counter >= 5, incrementTask)
+     *   .run(); // [1, 2, 3, 4, 5]
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Polling until success
+     * const results = await FuturableTask.until(
+     *   async () => await isReady(),
+     *   FuturableTask.of(() => checkStatus()).delay(1000)
+     * ).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Retry until success or limit reached
+     * let attempts = 0;
+     * const MAX_ATTEMPTS = 10;
+     *
+     * await FuturableTask.until(
+     *   () => attempts >= MAX_ATTEMPTS,
+     *   FuturableTask.of(async () => {
+     *     attempts++;
+     *     return await tryOperation();
+     *   }).orElse(() => FuturableTask.resolve(null))
+     * ).run();
+     * ```
+     */
+    static until<T>(condition: () => boolean | Promise<boolean>, task: FuturableTask<T>, signal?: AbortSignal): FuturableTask<T[]>;
+    /**
+     * Executes a task factory n times, collecting all results.
+     *
+     * The factory receives the current index (0 to n-1) and returns a task.
+     * Executes sequentially. If any execution fails, the entire operation fails.
+     *
+     * @template T - Type of value the tasks produce
+     * @param n - Number of times to execute (must be >= 0)
+     * @param taskFactory - Function that creates a task for each iteration
+     * @param signal - Optional AbortSignal for the combined task
+     * @returns A FuturableTask that resolves with an array of all results
+     *
+     * @example
+     * ```typescript
+     * const results = await FuturableTask
+     *   .times(5, i => FuturableTask.resolve(i * 2))
+     *   .run(); // [0, 2, 4, 6, 8]
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Fetch multiple pages
+     * const pages = await FuturableTask.times(
+     *   10,
+     *   i => FuturableTask.of(() => fetch(`/api/data?page=${i}`))
+     * ).run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Create test data
+     * const users = await FuturableTask.times(
+     *   100,
+     *   i => FuturableTask.of(() => createUser({
+     *     name: `User ${i}`,
+     *     email: `user${i}@example.com`
+     *   }))
+     * ).run();
+     * ```
+     */
+    static times<T>(n: number, taskFactory: (index: number) => FuturableTask<T>, signal?: AbortSignal): FuturableTask<T[]>;
+    /**
+     * Maps an array of values to tasks and executes them in sequence.
+     *
+     * Combines map and sequence - applies a function to each value to create a task,
+     * then executes all tasks sequentially.
+     *
+     * The mapping function receives both the value and its index.
+     *
+     * @template T - Type of input values
+     * @template U - Type of values the tasks produce
+     * @param values - Array of values to map
+     * @param fn - Function that maps each value to a task
+     * @param signal - Optional AbortSignal for the combined task
+     * @returns A FuturableTask that resolves with an array of all results
+     *
+     * @example
+     * ```typescript
+     * const userIds = [1, 2, 3, 4, 5];
+     * const users = await FuturableTask
+     *   .traverse(userIds, id => FuturableTask.of(() => fetchUser(id)))
+     *   .run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With index
+     * const results = await FuturableTask.traverse(
+     *   ['a', 'b', 'c'],
+     *   (letter, index) => FuturableTask.of(() => `${index}: ${letter}`)
+     * ).run(); // ['0: a', '1: b', '2: c']
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Processing files sequentially
+     * const processed = await FuturableTask.traverse(
+     *   filePaths,
+     *   path => FuturableTask.of(() => processFile(path))
+     * ).run();
+     * ```
+     */
+    static traverse<T, U>(values: T[], fn: (value: T, index: number) => FuturableTask<U>, signal?: AbortSignal): FuturableTask<U[]>;
+    /**
+ * Static method to create a fetch task directly.
+ *
+ * @param url - The URL to fetch
+ * @param opts - Optional Fetch API options
+ * @param signal - Optional AbortSignal for the task
+ * @returns A FuturableTask that resolves with the Response
+ *
+ * @example
+ * ```typescript
+ * const task = FuturableTask.fetch('https://api.example.com/data')
+ *   .map(res => res.json())
+ *   .retry(3);
+ *
+ * const data = await task.run();
+ * ```
+ */
+    static fetch(url: string, opts?: RequestInit, signal?: AbortSignal): FuturableTask<Response>;
 }
-export {};
-//# sourceMappingURL=index.d.ts.map
+
+export { Futurable, FuturableTask };
+export type { FuturableExecutor, FuturableIterable, FuturableLike, FuturablePollingController, FuturableReject, FuturableResolve, FuturableTaskLimiter, FuturableUtils, FuturableWithResolvers, LimiterEvents, MemoizeOptions, SafeResult };