create-request/dist/library/RequestError.d.ts

A modern, chainable wrapper for fetch with automatic retries, timeouts, comprehensive error handling, and first-class TypeScript support

/**
 * Error class for HTTP request failures.
 * Extends the standard Error class with additional context about the failed request.
 *
 * @example
 * ```typescript
 * try {
 *   await create.get('/api/users').getJson();
 * } catch (error) {
 *    console.log(`Request failed: ${error.message}`);
 *    console.log(`URL: ${error.url}`);
 *    console.log(`Method: ${error.method}`);
 *    console.log(`Status: ${error.status}`);
 *    console.log(`Is timeout: ${error.isTimeout}`);
 *    console.log(`Is aborted: ${error.isAborted}`);
 * }
 * ```
 */
export declare class RequestError extends Error {
    /** HTTP status code if the request received a response (e.g., 404, 500) */
    readonly status?: number;
    /** The Response object if the request received a response before failing */
    readonly response?: Response;
    /** The URL that was requested */
    readonly url: string;
    /** The HTTP method that was used (e.g., 'GET', 'POST') */
    readonly method: string;
    /** Whether the request failed due to a timeout */
    readonly isTimeout: boolean;
    /** Whether the request was aborted (cancelled) */
    readonly isAborted: boolean;
    /**
     * Creates a new RequestError instance.
     *
     * @param message - Error message describing what went wrong
     * @param url - The URL that was requested
     * @param method - The HTTP method that was used
     * @param options - Additional error context
     * @param options.status - HTTP status code if available
     * @param options.response - The Response object if available
     * @param options.isTimeout - Whether this was a timeout error
     * @param options.isAborted - Whether the request was aborted
     * @param options.cause - The underlying error that caused this error
     */
    constructor(message: string, url: string, method: string, options?: {
        status?: number;
        response?: Response;
        isTimeout?: boolean;
        isAborted?: boolean;
        cause?: Error;
    });
    /**
     * Creates a RequestError for a timeout failure.
     *
     * @param url - The URL that timed out
     * @param method - The HTTP method that was used
     * @param timeoutMs - The timeout duration in milliseconds
     * @returns A RequestError with `isTimeout` set to `true`
     *
     * @example
     * ```typescript
     * throw RequestError.timeout('/api/data', 'GET', 5000);
     * ```
     */
    static timeout(url: string, method: string, timeoutMs: number): RequestError;
    /**
     * Creates a RequestError from an HTTP error response.
     * Used when the server returns a non-2xx status code.
     *
     * @param response - The Response object from the failed request
     * @param url - The URL that was requested
     * @param method - The HTTP method that was used
     * @returns A RequestError with the status code and response object
     *
     * @example
     * ```typescript
     * const response = await fetch('/api/users');
     * if (!response.ok) {
     *   throw RequestError.fromResponse(response, '/api/users', 'GET');
     * }
     * ```
     */
    static fromResponse(response: Response, url: string, method: string): RequestError;
    /**
     * Creates a RequestError from a network-level error.
     * Automatically detects and categorizes common network errors (timeouts, DNS errors, connection errors).
     *
     * @param url - The URL that failed
     * @param method - The HTTP method that was used
     * @param originalError - The original error that occurred (e.g., from fetch)
     * @returns A RequestError with enhanced error message and context
     *
     * @example
     * ```typescript
     * try {
     *   await fetch('/api/data');
     * } catch (error) {
     *   if (error instanceof Error) {
     *     throw RequestError.networkError('/api/data', 'GET', error);
     *   }
     * }
     * ```
     */
    static networkError(url: string, method: string, originalError: Error): RequestError;
    /**
     * Creates a RequestError for an aborted (cancelled) request.
     *
     * @param url - The URL that was aborted
     * @param method - The HTTP method that was used
     * @returns A RequestError with `isAborted` set to `true`
     *
     * @example
     * ```typescript
     * const controller = new AbortController();
     * controller.abort();
     * throw RequestError.abortError('/api/data', 'GET');
     * ```
     */
    static abortError(url: string, method: string): RequestError;
}