create-request 1.4.3-rc.2 → 1.4.3-rc.4

package/dist/library/RequestError.d.ts

@@ -1,10 +1,47 @@
+/**
+ * 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;
@@ -13,10 +50,71 @@ export declare class RequestError extends Error {
         cause?: Error;
     });
     /**
-     * Static methods for creating specific types of RequestError
+     * 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;
 }

package/dist/library/ResponseWrapper.d.ts

@@ -1,9 +1,22 @@
 import type { GraphQLOptions } from "./types.js";
 /**
- * Wrapper for HTTP responses with methods to transform the response data
+ * Wrapper for HTTP responses with methods to transform the response data.
+ * Provides convenient methods to parse the response body in different formats.
+ * Response bodies are cached after the first read, so you can call multiple methods
+ * (e.g., `getJson()` and `getText()`) on the same response.
+ *
+ * @example
+ * ```typescript
+ * const response = await create.get('/api/users').getResponse();
+ * console.log(response.status); // 200
+ * console.log(response.ok); // true
+ * const data = await response.getJson();
+ * ```
  */
 export declare class ResponseWrapper {
+    /** The URL that was requested (if available) */
     readonly url?: string;
+    /** The HTTP method that was used (if available) */
     readonly method?: string;
     private readonly response;
     private graphQLOptions?;
@@ -12,10 +25,26 @@ export declare class ResponseWrapper {
     private cachedJson?;
     private cachedArrayBuffer?;
     constructor(response: Response, url?: string, method?: string, graphQLOptions?: GraphQLOptions);
+    /**
+     * HTTP status code (e.g., 200, 404, 500)
+     */
     get status(): number;
+    /**
+     * HTTP status text (e.g., "OK", "Not Found", "Internal Server Error")
+     */
     get statusText(): string;
+    /**
+     * Response headers as a Headers object
+     */
     get headers(): Headers;
+    /**
+     * Whether the response status is in the 200-299 range (successful)
+     */
     get ok(): boolean;
+    /**
+     * The raw Response object from the fetch API.
+     * Use this if you need direct access to the underlying Response.
+     */
     get raw(): Response;
     /**
      * Check if the response body has already been consumed and throw an error if so
@@ -51,35 +80,49 @@ export declare class ResponseWrapper {
      */
     getJson<T = unknown>(): Promise<T>;
     /**
-     * Get the response body as text
+     * Get the response body as text.
+     * The result is cached, so subsequent calls return the same value without re-reading the body.
      *
-     * @returns The response text
-     * @throws {RequestError} When reading fails
+     * @returns A promise that resolves to the response body as a string
+     * @throws {RequestError} When the body has already been consumed or reading fails
      *
      * @example
+     * ```typescript
      * const text = await response.getText();
+     * console.log(text); // "Hello, world!"
+     * ```
      */
     getText(): Promise<string>;
     /**
-     * Get the response body as a Blob
+     * Get the response body as a Blob.
+     * Useful for downloading files or handling binary data.
+     * The result is cached, so subsequent calls return the same value without re-reading the body.
      *
-     * @returns The response as a Blob
-     * @throws {RequestError} When reading fails
+     * @returns A promise that resolves to the response body as a Blob
+     * @throws {RequestError} When the body has already been consumed or reading fails
      *
      * @example
+     * ```typescript
      * const blob = await response.getBlob();
      * const url = URL.createObjectURL(blob);
+     * // Use the blob URL for downloading or displaying
+     * ```
      */
     getBlob(): Promise<Blob>;
     /**
-     * Get the response body as an ArrayBuffer
+     * Get the response body as an ArrayBuffer.
+     * Useful for processing binary data at a low level.
+     * The result is cached, so subsequent calls return the same value without re-reading the body.
      *
-     * @returns The response as an ArrayBuffer
-     * @throws {RequestError} When reading fails
+     * @returns A promise that resolves to the response body as an ArrayBuffer
+     * @throws {RequestError} When the body has already been consumed or reading fails
      *
      * @example
+     * ```typescript
      * const buffer = await response.getArrayBuffer();
      * const uint8Array = new Uint8Array(buffer);
+     * // Process the binary data
+     * ```
      */
     getArrayBuffer(): Promise<ArrayBuffer>;
     /**

package/dist/library/apiBuilder.d.ts

@@ -1,25 +1,25 @@
 import type { CookiesRecord, CookieOptions, RetryConfig, RequestInterceptor, ResponseInterceptor, ErrorInterceptor } from "./types.js";
 import type { GetRequest, PostRequest, PutRequest, DeleteRequest, PatchRequest, HeadRequest, OptionsRequest } from "./requestMethods.js";
 interface ApiBuilderRequestMethods {
-    withoutCsrfProtection(): ApiBuilder;
-    withAntiCsrfHeaders(): ApiBuilder;
-    withTimeout(timeout: number): ApiBuilder;
-    withReferrer(referrer: string): ApiBuilder;
-    withKeepAlive(keepalive: boolean): ApiBuilder;
-    withIntegrity(integrity: string): ApiBuilder;
-    withHeader(key: string, value: string): ApiBuilder;
-    withHeaders(headers: Record<string, string>): ApiBuilder;
-    withRetries(retries: number | RetryConfig): ApiBuilder;
-    withBearerToken(token: string): ApiBuilder;
-    withCookies(cookies: CookiesRecord): ApiBuilder;
-    withContentType(contentType: string): ApiBuilder;
-    withAuthorization(authValue: string): ApiBuilder;
-    withBasicAuth(username: string, password: string): ApiBuilder;
-    withCsrfToken(token: string, headerName?: string): ApiBuilder;
-    withErrorInterceptor(interceptor: ErrorInterceptor): ApiBuilder;
-    withCookie(name: string, value: string | CookieOptions): ApiBuilder;
-    withRequestInterceptor(interceptor: RequestInterceptor): ApiBuilder;
-    withResponseInterceptor(interceptor: ResponseInterceptor): ApiBuilder;
+    withoutCsrfProtection(): ApiBuilder & ApiBuilderRequestMethods;
+    withAntiCsrfHeaders(): ApiBuilder & ApiBuilderRequestMethods;
+    withTimeout(timeout: number): ApiBuilder & ApiBuilderRequestMethods;
+    withReferrer(referrer: string): ApiBuilder & ApiBuilderRequestMethods;
+    withKeepAlive(keepalive: boolean): ApiBuilder & ApiBuilderRequestMethods;
+    withIntegrity(integrity: string): ApiBuilder & ApiBuilderRequestMethods;
+    withHeader(key: string, value: string): ApiBuilder & ApiBuilderRequestMethods;
+    withHeaders(headers: Record<string, string>): ApiBuilder & ApiBuilderRequestMethods;
+    withRetries(retries: number | RetryConfig): ApiBuilder & ApiBuilderRequestMethods;
+    withBearerToken(token: string): ApiBuilder & ApiBuilderRequestMethods;
+    withCookies(cookies: CookiesRecord): ApiBuilder & ApiBuilderRequestMethods;
+    withContentType(contentType: string): ApiBuilder & ApiBuilderRequestMethods;
+    withAuthorization(authValue: string): ApiBuilder & ApiBuilderRequestMethods;
+    withBasicAuth(username: string, password: string): ApiBuilder & ApiBuilderRequestMethods;
+    withCsrfToken(token: string, headerName?: string): ApiBuilder & ApiBuilderRequestMethods;
+    withErrorInterceptor(interceptor: ErrorInterceptor): ApiBuilder & ApiBuilderRequestMethods;
+    withCookie(name: string, value: string | CookieOptions): ApiBuilder & ApiBuilderRequestMethods;
+    withRequestInterceptor(interceptor: RequestInterceptor): ApiBuilder & ApiBuilderRequestMethods;
+    withResponseInterceptor(interceptor: ResponseInterceptor): ApiBuilder & ApiBuilderRequestMethods;
 }
 /**
  * API builder for creating configured API instances with default settings.
@@ -53,7 +53,7 @@ export declare class ApiBuilder {
      * await api.get("/users").getJson(); // Requests https://api.example.com/users
      * ```
      */
-    withBaseURL(baseURL: string): this;
+    withBaseURL(baseURL: string): ApiBuilder & ApiBuilderRequestMethods;
     /**
      * Adds a modifier function that will be applied to all requests created through this builder.
      *