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

package/dist/library/index.esm.js

@@ -93,13 +93,50 @@ var CacheMode;
     CacheMode["ONLY_IF_CACHED"] = "only-if-cached";
 })(CacheMode || (CacheMode = {}));
 
+/**
+ * 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}`);
+ * }
+ * ```
+ */
 class RequestError extends Error {
+    /** HTTP status code if the request received a response (e.g., 404, 500) */
     status;
+    /** The Response object if the request received a response before failing */
     response;
+    /** The URL that was requested */
     url;
+    /** The HTTP method that was used (e.g., 'GET', 'POST') */
     method;
+    /** Whether the request failed due to a timeout */
     isTimeout;
+    /** Whether the request was aborted (cancelled) */
     isAborted;
+    /**
+     * 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, url, method, options = {}) {
         super(message, { cause: options.cause });
         this.name = "RequestError";
@@ -117,19 +154,66 @@ class RequestError extends Error {
         Object.setPrototypeOf(this, RequestError.prototype);
     }
     /**
-     * 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, method, timeoutMs) {
         return new RequestError(`Timeout ${timeoutMs}ms`, url, method, {
             isTimeout: true,
         });
     }
+    /**
+     * 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, url, method) {
         return new RequestError(`HTTP ${response.status}`, url, method, {
             status: response.status,
             response,
         });
     }
+    /**
+     * 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, method, originalError) {
         // Provide more descriptive error messages for common network errors
         let message = originalError.message;
@@ -187,6 +271,20 @@ class RequestError extends Error {
         }
         return error;
     }
+    /**
+     * 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, method) {
         return new RequestError("Aborted", url, method, {
             isAborted: true,
@@ -195,10 +293,23 @@ class RequestError extends Error {
 }
 
 /**
- * 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();
+ * ```
  */
 class ResponseWrapper {
+    /** The URL that was requested (if available) */
     url;
+    /** The HTTP method that was used (if available) */
     method;
     response;
     graphQLOptions;
@@ -217,19 +328,34 @@ class ResponseWrapper {
             };
         }
     }
-    // Wrapper properties
+    /**
+     * HTTP status code (e.g., 200, 404, 500)
+     */
     get status() {
         return this.response.status;
     }
+    /**
+     * HTTP status text (e.g., "OK", "Not Found", "Internal Server Error")
+     */
     get statusText() {
         return this.response.statusText;
     }
+    /**
+     * Response headers as a Headers object
+     */
     get headers() {
         return this.response.headers;
     }
+    /**
+     * Whether the response status is in the 200-299 range (successful)
+     */
     get ok() {
         return this.response.ok;
     }
+    /**
+     * The raw Response object from the fetch API.
+     * Use this if you need direct access to the underlying Response.
+     */
     get raw() {
         return this.response;
     }
@@ -257,7 +383,29 @@ class ResponseWrapper {
         if (!Array.isArray(responseData.errors) || responseData.errors.length === 0)
             return;
         const errors = responseData.errors;
-        const errorMessages = errors.map(x => typeof x === "string" ? x : x && typeof x === "object" && "message" in x ? String(x.message || "Unknown error") : String(x));
+        const errorMessages = errors.map(x => {
+            if (typeof x === "string")
+                return x;
+            if (x && typeof x === "object" && "message" in x) {
+                const message = x.message;
+                if (message == null)
+                    return "Unknown error";
+                if (typeof message === "string")
+                    return message;
+                if (typeof message === "object") {
+                    try {
+                        return JSON.stringify(message);
+                    }
+                    catch {
+                        return "Unknown error";
+                    }
+                }
+                // For primitives (number, boolean, etc.), safe to convert
+                // eslint-disable-next-line @typescript-eslint/no-base-to-string
+                return String(message);
+            }
+            return String(x);
+        });
         const errorMessage = errorMessages.join(", ");
         throw new RequestError(`GraphQL errors: ${errorMessage}`, this.url || "", this.method || "", {
             status: this.response.status,
@@ -307,13 +455,17 @@ class ResponseWrapper {
         }
     }
     /**
-     * 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!"
+     * ```
      */
     async getText() {
         if (this.cachedText !== undefined)
@@ -333,14 +485,19 @@ class ResponseWrapper {
         }
     }
     /**
-     * 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
+     * ```
      */
     async getBlob() {
         if (this.cachedBlob !== undefined)
@@ -360,14 +517,19 @@ class ResponseWrapper {
         }
     }
     /**
-     * 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
+     * ```
      */
     async getArrayBuffer() {
         if (this.cachedArrayBuffer !== undefined) {
@@ -1319,9 +1481,34 @@ class BaseRequest {
         return this.createFluentSetter("cache", cacheOptions);
     }
     /**
-     * Adds query parameters to the request URL
-     * @param params - An object containing the query parameters
-     * @returns The instance for chaining
+     * Adds query parameters to the request URL.
+     * Multiple calls will append parameters. Array values will create multiple query parameters with the same key.
+     * Null and undefined values are ignored.
+     *
+     * @param params - An object containing query parameter key-value pairs.
+     *   Values can be strings, numbers, booleans, arrays (for multiple values), or null/undefined (ignored).
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * // Simple parameters
+     * request.withQueryParams({ page: 1, limit: 10, active: true });
+     * // Results in: ?page=1&limit=10&active=true
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Array values create multiple parameters
+     * request.withQueryParams({ tags: ['js', 'ts', 'node'] });
+     * // Results in: ?tags=js&tags=ts&tags=node
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Null/undefined values are ignored
+     * request.withQueryParams({ page: 1, filter: null, sort: undefined });
+     * // Results in: ?page=1
+     * ```
      */
     withQueryParams(params) {
         Object.entries(params).forEach(([key, value]) => {
@@ -1339,10 +1526,25 @@ class BaseRequest {
         return this;
     }
     /**
-     * Adds a single query parameter
-     * @param key - The parameter name
-     * @param value - The parameter value, can be a single value or array of values
-     * @returns The instance for chaining
+     * Adds a single query parameter to the request URL.
+     * Convenience method for adding one parameter at a time.
+     *
+     * @param key - The query parameter name
+     * @param value - The query parameter value. Can be a string, number, boolean, array (for multiple values), or null/undefined (ignored).
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withQueryParam('page', 1).withQueryParam('limit', 10);
+     * // Results in: ?page=1&limit=10
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Array values create multiple parameters
+     * request.withQueryParam('tags', ['js', 'ts']);
+     * // Results in: ?tags=js&tags=ts
+     * ```
      */
     withQueryParam(key, value) {
         return this.withQueryParams({ [key]: value });
@@ -1384,26 +1586,59 @@ class BaseRequest {
         });
     }
     /**
-     * Shorthand for setting the Content-Type header
-     * @param contentType - The content type
-     * @returns The instance for chaining
+     * Sets the Content-Type header for the request.
+     * Shorthand for `withHeader('Content-Type', contentType)`.
+     *
+     * @param contentType - The MIME type (e.g., `'application/json'`, `'text/plain'`, `'multipart/form-data'`)
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withContentType('application/json');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * request.withContentType('application/xml');
+     * ```
      */
     withContentType(contentType) {
         return this.withHeader("Content-Type", contentType);
     }
     /**
-     * Shorthand for setting the Authorization header
-     * @param authValue - The authorization value
-     * @returns The instance for chaining
+     * Sets the Authorization header for the request.
+     * Shorthand for `withHeader('Authorization', authValue)`.
+     * For Bearer tokens, use `withBearerToken()` instead. For Basic auth, use `withBasicAuth()`.
+     *
+     * @param authValue - The full authorization header value (e.g., `'Bearer token123'`, `'Basic base64string'`)
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withAuthorization('Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * request.withAuthorization('CustomScheme customToken');
+     * ```
      */
     withAuthorization(authValue) {
         return this.withHeader("Authorization", authValue);
     }
     /**
-     * Shorthand for setting up Basic authentication
-     * @param username - The username
-     * @param password - The password
-     * @returns The instance for chaining
+     * Sets up HTTP Basic Authentication.
+     * Encodes the username and password in base64 and sets the Authorization header.
+     *
+     * @param username - The username for Basic authentication
+     * @param password - The password for Basic authentication
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withBasicAuth('myuser', 'mypassword');
+     * // Sets: Authorization: Basic bXl1c2VyOm15cGFzc3dvcmQ=
+     * ```
      */
     withBasicAuth(username, password) {
         const credentials = this.encodeBase64(`${username}:${password}`);
@@ -1430,9 +1665,17 @@ class BaseRequest {
         throw new RequestError("Encoding not supported", this.url, this.method);
     }
     /**
-     * Sets the bearer token for authentication
-     * @param token - The bearer token
-     * @returns The instance for chaining
+     * Sets a Bearer token for authentication.
+     * Shorthand for `withAuthorization('Bearer ' + token)`.
+     *
+     * @param token - The Bearer token (JWT, OAuth token, etc.)
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withBearerToken('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
+     * // Sets: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+     * ```
      */
     withBearerToken(token) {
         return this.withAuthorization(`Bearer ${token}`);
@@ -1457,9 +1700,29 @@ class BaseRequest {
         return Object.keys(headers).some(key => key.toLowerCase() === headerName.toLowerCase());
     }
     /**
-     * Sets cookies for the request
-     * @param cookies Object containing cookie name-value pairs or cookie options
-     * @returns The instance for chaining
+     * Sets cookies for the request.
+     * Cookies are sent in the Cookie header. Multiple calls will merge cookies.
+     * Cookie values can be simple strings or objects with additional cookie options.
+     *
+     * @param cookies - An object where keys are cookie names and values are either:
+     *   - A string (the cookie value)
+     *   - A CookieOptions object with `value` and optional properties (secure, httpOnly, sameSite, expires, path, domain, maxAge)
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * // Simple string cookies
+     * request.withCookies({ sessionId: 'abc123', userId: '456' });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Cookies with options (note: options are for documentation only in request cookies)
+     * request.withCookies({
+     *   sessionId: 'abc123',
+     *   token: { value: 'xyz789', secure: true }
+     * });
+     * ```
      */
     withCookies(cookies) {
         const cookieEntries = Object.entries(cookies || {});
@@ -1497,19 +1760,45 @@ class BaseRequest {
         return this;
     }
     /**
-     * Set a single cookie
-     * @param name Cookie name
-     * @param value Cookie value or options object
-     * @returns The instance for chaining
+     * Sets a single cookie for the request.
+     * Convenience method for adding one cookie at a time.
+     *
+     * @param name - The cookie name
+     * @param value - The cookie value as a string, or a CookieOptions object with `value` and optional properties
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withCookie('sessionId', 'abc123');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * request.withCookie('token', { value: 'xyz789', secure: true });
+     * ```
      */
     withCookie(name, value) {
         return this.withCookies({ [name]: value });
     }
     /**
-     * Sets a CSRF token in the request headers
-     * @param token The CSRF token
-     * @param headerName The name of the header to use (default: X-CSRF-Token)
-     * @returns The instance for chaining
+     * Sets a CSRF (Cross-Site Request Forgery) token in the request headers.
+     * This is commonly used to protect against CSRF attacks in web applications.
+     *
+     * @param token - The CSRF token value
+     * @param headerName - The name of the header to use. Defaults to `'X-CSRF-Token'`.
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withCsrfToken('csrf-token-123');
+     * // Sets: X-CSRF-Token: csrf-token-123
+     * ```
+     *
+     * @example
+     * ```typescript
+     * request.withCsrfToken('token', 'X-Custom-CSRF-Header');
+     * // Sets: X-Custom-CSRF-Header: token
+     * ```
      */
     withCsrfToken(token, headerName = "X-CSRF-Token") {
         return this.withHeader(headerName, token);
@@ -1624,36 +1913,54 @@ class BaseRequest {
         return response.getJson();
     }
     /**
-     * Execute the request and get the response as text
+     * Execute the request and get the response body as text.
      *
-     * @returns A promise that resolves to the response text
+     * @returns A promise that resolves to the response body as a string
+     * @throws {RequestError} When the request fails or reading the response fails
      *
      * @example
+     * ```typescript
      * const text = await request.getText();
+     * console.log(text); // "Hello, world!"
+     * ```
      */
     async getText() {
         const response = await this.getResponse();
         return response.getText();
     }
     /**
-     * Execute the request and get the response as a Blob
+     * Execute the request and get the response body as a Blob.
+     * Useful for downloading files or handling binary data.
      *
-     * @returns A promise that resolves to the response Blob
+     * @returns A promise that resolves to the response body as a Blob
+     * @throws {RequestError} When the request fails or reading the response fails
      *
      * @example
+     * ```typescript
      * const blob = await request.getBlob();
+     * const url = URL.createObjectURL(blob);
+     * // Use the blob URL (e.g., for downloading or displaying)
+     * ```
      */
     async getBlob() {
         const response = await this.getResponse();
         return response.getBlob();
     }
     /**
-     * Execute the request and get the response body as a ReadableStream
+     * Execute the request and get the response body as a ReadableStream.
+     * Note: Unlike other methods, streams cannot be cached. The body can only be consumed once.
      *
-     * @returns A promise that resolves to the response body stream
+     * @returns A promise that resolves to the response body as a ReadableStream, or `null` if the body is not available
+     * @throws {RequestError} When the request fails or the body has already been consumed
      *
      * @example
+     * ```typescript
      * const stream = await request.getBody();
+     * if (stream) {
+     *   const reader = stream.getReader();
+     *   // Process the stream chunk by chunk
+     * }
+     * ```
      */
     async getBody() {
         const response = await this.getResponse();
@@ -1739,7 +2046,7 @@ class BaseRequest {
             });
             return urlObj.toString();
         }
-        catch (error) {
+        catch (_error) {
             // Handle relative URLs
             const hasExistingParams = url.includes("?");
             const separator = hasExistingParams ? "&" : "?";
@@ -2083,8 +2390,39 @@ class BodyRequest extends BaseRequest {
         super(url);
     }
     /**
-     * Sets the body of the request
-     * @param body - The request body
+     * Sets the request body. Automatically detects the body type and sets appropriate Content-Type header.
+     * Supports JSON objects/arrays, strings, FormData, Blob, ArrayBuffer, URLSearchParams, and ReadableStream.
+     *
+     * @param body - The request body. Can be:
+     *   - A JSON-serializable object or array (automatically stringified)
+     *   - A string (sets Content-Type to `text/plain` if not already set)
+     *   - FormData, Blob, File, ArrayBuffer, TypedArray, URLSearchParams, or ReadableStream
+     * @returns The request instance for chaining
+     * @throws {RequestError} If the body is a JSON object that cannot be stringified
+     *
+     * @example
+     * ```typescript
+     * // JSON object (automatically stringified)
+     * request.withBody({ name: 'John', age: 30 });
+     *
+     * @example
+     * // JSON array
+     * request.withBody([1, 2, 3]);
+     *
+     * @example
+     * // String
+     * request.withBody('plain text');
+     *
+     * @example
+     * // FormData
+     * const formData = new FormData();
+     * formData.append('file', fileBlob);
+     * request.withBody(formData);
+     *
+     * @example
+     * // Blob
+     * request.withBody(new Blob(['content'], { type: 'text/plain' }));
+     * ```
      */
     withBody(body) {
         this.body = body;
@@ -2119,26 +2457,41 @@ class BodyRequest extends BaseRequest {
         return this;
     }
     /**
-     * Sets a GraphQL query or mutation as the request body
-     * Automatically formats the body as JSON and sets Content-Type to application/json
+     * Sets a GraphQL query or mutation as the request body.
+     * Automatically formats the body as JSON and sets Content-Type to `application/json`.
+     * If `throwOnError` is enabled in options, the response will be checked for GraphQL errors
+     * and a RequestError will be thrown if any are found.
      *
-     * @param query - The GraphQL query or mutation string
-     * @param variables - Optional variables object to pass with the query
+     * @param query - The GraphQL query or mutation string (e.g., `'query { user { id } }'`)
+     * @param variables - Optional variables object to pass with the query. Must be a plain object.
      * @param options - Optional GraphQL-specific options
+     * @param options.throwOnError - If `true`, throws a RequestError when the GraphQL response contains errors
      * @returns The request instance for chaining
+     * @throws {RequestError} If the query is empty, variables is invalid, or JSON stringification fails
      *
      * @example
-     * const request = new PostRequest('/graphql')
+     * ```typescript
+     * // Simple query with variables
+     * const request = create.post('/graphql')
      *   .withGraphQL('query { user(id: $id) { name email } }', { id: '123' });
+     * const data = await request.getJson();
+     * ```
      *
      * @example
-     * const request = new PostRequest('/graphql')
+     * ```typescript
+     * // Mutation with variables
+     * const request = create.post('/graphql')
      *   .withGraphQL('mutation { createUser(name: $name) { id } }', { name: 'John' });
+     * ```
      *
      * @example
-     * // Throw an error if the GraphQL response contains errors
-     * const request = new PostRequest('/graphql')
+     * ```typescript
+     * // Throw error if GraphQL response contains errors
+     * const request = create.post('/graphql')
      *   .withGraphQL('query { user { id } }', undefined, { throwOnError: true });
+     * // If the response has errors, this will throw a RequestError
+     * const data = await request.getJson();
+     * ```
      */
     withGraphQL(query, variables, options) {
         if (typeof query !== "string" || query.length === 0) {
@@ -2694,8 +3047,28 @@ function api() {
 }
 
 /**
- * Main API object for creating HTTP requests
+ * Main API object for creating HTTP requests.
  * Provides factory methods for all HTTP methods and access to global configuration.
+ *
+ * @example
+ * ```typescript
+ * import create from 'create-request';
+ *
+ * // Simple GET request
+ * const users = await create.get('/api/users').getJson();
+ *
+ * // POST request with body
+ * const newUser = await create.post('/api/users')
+ *   .withJson({ name: 'John', email: 'john@example.com' })
+ *   .getJson();
+ *
+ * // Configure API instance with defaults
+ * const api = create.api()
+ *   .withBaseURL('https://api.example.com')
+ *   .withBearerToken('token123');
+ *
+ * const data = await api.get('/users').getJson();
+ * ```
  */
 const create = {
     api,