create-request 1.5.4 → 1.6.0

package/README.md

@@ -25,6 +25,7 @@
   - [Automatic Retries with Delay](#automatic-retries-with-delay)
   - [Interceptors](#interceptors)
   - [Request Cancellation](#request-cancellation)
+  - [Custom Fetch Injection](#custom-fetch-injection)
   - [Data Selection](#data-selection)
   - [TypeScript Support](#typescript-support)
   - [CSRF Protection](#csrf-protection)
@@ -51,6 +52,7 @@
 - 🏗️ **API Builder** - Create configured API instances with reusable default settings
 - 🛑 **Request Cancellation** - Abort requests on demand with AbortController integration
 - 🔌 **Interceptors** - Global and per-request interceptors for requests, responses, and errors
+- 🧩 **Custom Fetch** - Inject any fetch-compatible function for testing, undici agents, or Next.js caching
 - 🔷 **GraphQL Support** - Built-in GraphQL query and mutation helpers
 
 ## Why create-request?
@@ -635,6 +637,7 @@ try {
   console.log(error.method); // HTTP method
   console.log(error.isTimeout); // Whether it was a timeout
   console.log(error.isAborted); // Whether it was aborted/cancelled
+  console.log(error.body); // Raw response body as text (if available)
 
   // Access the original response if available
   if (error.response) {
@@ -644,6 +647,32 @@ try {
 }
 ```
 
+#### Error Response Body
+
+When a request fails with an HTTP error (e.g., 400, 404, 500), the response body is automatically captured and available directly on the error - no need to read it from `error.response` manually:
+
+```typescript
+try {
+  await create.post("https://api.example.com/users").withBody(newUser).getJson();
+} catch (error) {
+  // Raw body as text (undefined for network errors, timeouts, and aborts)
+  console.log(error.body); // '{"message":"Email already taken","code":"DUPLICATE_EMAIL"}'
+
+  // Body parsed as JSON - never throws, returns undefined if the body isn't valid JSON
+  const details = error.getJson<{ message: string; code: string }>();
+  if (details) {
+    showToast(details.message);
+  }
+}
+```
+
+Notes on the captured body:
+
+- `error.body` contains the raw body text whenever a response was received (HTTP errors, JSON parsing errors, GraphQL errors with `throwOnError`). For errors without a response (network failures, timeouts, aborts) it's `undefined`.
+- `error.getJson()` lazily parses `error.body` as JSON and caches the result. It never throws - it returns `undefined` when there's no body or the body isn't valid JSON.
+- The body is captured from a clone of the response, so `error.response` remains fully readable for backward compatibility.
+- The captured body is also available in retry callbacks (`onRetry`, `delay`) and error interceptors.
+
 ## URL Handling
 
 The library handles both absolute and relative URLs, and automatically merges query parameters:
@@ -923,7 +952,11 @@ const request4 = create.get("https://api.example.com/data").withRetries({
     if (error.status === 429) {
       // Check Retry-After header if available
       const retryAfter = error.response?.headers.get("Retry-After");
-      return retryAfter ? parseInt(retryAfter) * 1000 : 5000;
+      if (retryAfter) return parseInt(retryAfter) * 1000;
+
+      // Or read the delay from the error response body
+      const details = error.getJson<{ retryAfterMs?: number }>();
+      return details?.retryAfterMs ?? 5000;
     }
     return 1000; // Default delay
   },
@@ -1090,6 +1123,54 @@ try {
 }
 ```
 
+### Custom Fetch Injection
+
+By default, requests run through the global `fetch`. With `withFetch` you can inject any fetch-compatible function — per request or for a whole API instance. This unlocks testing without global mocks, custom undici agents/dispatchers in Node.js, and framework-patched fetch features like Next.js caching.
+
+```typescript
+import create, { createApi } from "create-request";
+import type { FetchFunction } from "create-request";
+
+// Testing: inject a stub instead of monkey-patching globalThis.fetch
+const stubFetch: FetchFunction = async () =>
+  new Response(JSON.stringify({ id: 1 }), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+
+const user = await create.get("/api/users/1").withFetch(stubFetch).getJson();
+```
+
+```typescript
+// Node.js: route requests through a custom undici Agent (proxies, keep-alive tuning, mTLS, ...)
+import { fetch as undiciFetch, Agent } from "undici";
+
+const agent = new Agent({ keepAliveTimeout: 30_000, connections: 10 });
+
+const api = createApi()
+  .withBaseURL("https://api.example.com")
+  .withFetch((url, init) => undiciFetch(url, { ...init, dispatcher: agent }));
+
+const users = await api.get("/users").getJson();
+```
+
+```typescript
+// Next.js: pass caching hints through to the framework's patched fetch
+const revalidatingFetch: FetchFunction = (url, init) =>
+  fetch(url, { ...init, next: { revalidate: 60 } });
+
+const posts = await create
+  .get("https://api.example.com/posts")
+  .withFetch(revalidatingFetch)
+  .getJson();
+```
+
+Notes:
+
+- The custom function receives the final URL and `RequestInit` after query params, headers, and request interceptors have been applied, and it is called once per attempt when retries are configured.
+- It should honor `init.signal`, otherwise `withTimeout` and `withAbortController` cannot cancel the underlying work.
+- A per-request `withFetch` overrides one set on an API builder.
+
 ### Data Selection
 
 The `getData` method provides a powerful way to extract and transform specific data from API responses:

package/dist/library/BaseRequest.d.ts

@@ -1,5 +1,5 @@
 import { type HttpMethod, RedirectMode, RequestMode, RequestPriority, ReferrerPolicy, CredentialsPolicy } from "./enums.js";
-import type { RetryConfig, RetryCallback, CookiesRecord, CookieOptions, RequestOptions, GraphQLOptions, ErrorInterceptor, RequestInterceptor, ResponseInterceptor } from "./types.js";
+import type { RetryConfig, RetryCallback, CookiesRecord, CookieOptions, FetchFunction, RequestOptions, GraphQLOptions, ErrorInterceptor, RequestInterceptor, ResponseInterceptor } from "./types.js";
 import { ResponseWrapper } from "./ResponseWrapper.js";
 /**
  * Base class with common functionality for all request types
@@ -10,6 +10,7 @@ export declare abstract class BaseRequest {
     protected url: string;
     protected requestOptions: RequestOptions;
     protected abortController?: AbortController;
+    protected customFetch?: FetchFunction;
     protected queryParams: URLSearchParams;
     protected autoApplyCsrfProtection: boolean;
     private requestInterceptors;
@@ -165,6 +166,36 @@ export declare abstract class BaseRequest {
      * controller.abort();
      */
     withAbortController(controller: AbortController): this;
+    /**
+     * Sets a custom fetch implementation used to execute this request.
+     * By default, requests use the global `fetch`. Injecting a custom function unlocks
+     * testing without global mocks, custom undici dispatchers/agents in Node.js,
+     * and framework-specific fetch extensions (e.g. Next.js caching options).
+     *
+     * The provided function receives the final URL and `RequestInit` (after interceptors)
+     * and must return a `Promise<Response>`. It should honor `init.signal` so that
+     * `withTimeout` and `withAbortController` keep working.
+     *
+     * @param fetchFn - A fetch-compatible function
+     * @returns The request instance for chaining
+     * @throws {RequestError} If fetchFn is not a function
+     *
+     * @example
+     * // Testing: inject a stub instead of mocking the global fetch
+     * const stubFetch: FetchFunction = async () => new Response('{"ok":true}');
+     * const data = await create.get('/api/users').withFetch(stubFetch).getJson();
+     *
+     * @example
+     * // Node.js: route through a custom undici agent (proxy, keep-alive tuning, ...)
+     * import { fetch as undiciFetch, Agent } from 'undici';
+     * const agent = new Agent({ keepAliveTimeout: 30_000 });
+     * request.withFetch((url, init) => undiciFetch(url, { ...init, dispatcher: agent }));
+     *
+     * @example
+     * // Next.js: pass caching hints through to the framework's patched fetch
+     * request.withFetch((url, init) => fetch(url, { ...init, next: { revalidate: 60 } }));
+     */
+    withFetch(fetchFn: FetchFunction): this;
     /**
      * Sets the referrer URL for the request. The referrer is the URL of the page that initiated the request.
      * This can be used to override the default referrer that the browser would normally send.

package/dist/library/RequestError.d.ts

@@ -11,6 +11,8 @@
  *    console.log(`URL: ${error.url}`);
  *    console.log(`Method: ${error.method}`);
  *    console.log(`Status: ${error.status}`);
+ *    console.log(`Body: ${error.body}`); // Raw response body (if available)
+ *    console.log(error.getJson()); // Body parsed as JSON (or undefined)
  *    console.log(`Is timeout: ${error.isTimeout}`);
  *    console.log(`Is aborted: ${error.isAborted}`);
  * }
@@ -21,6 +23,12 @@ export declare class RequestError extends Error {
     readonly status?: number;
     /** The Response object if the request received a response before failing */
     readonly response?: Response;
+    /**
+     * The raw response body as text, if a response was received and its body could be read.
+     * `undefined` for errors without a response (network errors, timeouts, aborts)
+     * or when the body could not be read.
+     */
+    readonly body?: string;
     /** The URL that was requested */
     readonly url: string;
     /** The HTTP method that was used (e.g., 'GET', 'POST') */
@@ -29,6 +37,8 @@ export declare class RequestError extends Error {
     readonly isTimeout: boolean;
     /** Whether the request was aborted (cancelled) */
     readonly isAborted: boolean;
+    /** Cached result of parsing `body` as JSON (lazily populated by getJson) */
+    private parsedBody?;
     /**
      * Creates a new RequestError instance.
      *
@@ -38,6 +48,7 @@ export declare class RequestError extends Error {
      * @param options - Additional error context
      * @param options.status - HTTP status code if available
      * @param options.response - The Response object if available
+     * @param options.body - The raw response body as text, 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
@@ -45,10 +56,48 @@ export declare class RequestError extends Error {
     constructor(message: string, url: string, method: string, options?: {
         status?: number;
         response?: Response;
+        body?: string;
         isTimeout?: boolean;
         isAborted?: boolean;
         cause?: Error;
     });
+    /**
+     * Parses the captured response body (`body`) as JSON.
+     * The result is cached, so repeated calls don't re-parse.
+     * This method never throws - it returns `undefined` when there is no body
+     * or the body is not valid JSON, making it safe to use in error handlers.
+     *
+     * @returns The parsed JSON body, or `undefined` if no body was captured or it isn't valid JSON
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await create.post('/api/users').withBody(user).getJson();
+     * } catch (error) {
+     *   if (error instanceof RequestError) {
+     *     const details = error.getJson<{ message: string; code: string }>();
+     *     console.log(details?.message ?? error.body ?? error.message);
+     *   }
+     * }
+     * ```
+     */
+    getJson<T = unknown>(): T | undefined;
+    /**
+     * Safely reads the body of a Response as text without consuming it.
+     * The response is cloned before reading, so the original body remains readable.
+     * Never throws - returns `undefined` if the body is unavailable or cannot be read
+     * (e.g., already consumed, locked stream, or read failure).
+     *
+     * @param response - The Response to read the body from
+     * @returns The body as text, or `undefined` if it could not be read
+     *
+     * @example
+     * ```typescript
+     * const body = await RequestError.captureBody(response);
+     * throw RequestError.fromResponse(response, url, 'GET', body);
+     * ```
+     */
+    static captureBody(response: Response): Promise<string | undefined>;
     /**
      * Creates a RequestError for a timeout failure.
      *
@@ -70,17 +119,19 @@ export declare class RequestError extends Error {
      * @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
+     * @param body - The response body as text, if already read (see {@link RequestError.captureBody})
+     * @returns A RequestError with the status code, response object, and body (if provided)
      *
      * @example
      * ```typescript
      * const response = await fetch('/api/users');
      * if (!response.ok) {
-     *   throw RequestError.fromResponse(response, '/api/users', 'GET');
+     *   const body = await RequestError.captureBody(response);
+     *   throw RequestError.fromResponse(response, '/api/users', 'GET', body);
      * }
      * ```
      */
-    static fromResponse(response: Response, url: string, method: string): RequestError;
+    static fromResponse(response: Response, url: string, method: string, body?: string): RequestError;
     /**
      * Creates a RequestError from a network-level error.
      * Automatically detects and categorizes common network errors (timeouts, DNS errors, connection errors).

package/dist/library/apiBuilder.d.ts

@@ -1,5 +1,5 @@
 import { GetRequest, PostRequest, PutRequest, DeleteRequest, PatchRequest, HeadRequest, OptionsRequest } from "./requestMethods.js";
-import type { RetryConfig, RetryCallback, CookiesRecord, CookieOptions, RequestInterceptor, ResponseInterceptor, ErrorInterceptor } from "./types.js";
+import type { RetryConfig, RetryCallback, CookiesRecord, CookieOptions, FetchFunction, RequestInterceptor, ResponseInterceptor, ErrorInterceptor } from "./types.js";
 import type { CredentialsPolicy, RedirectMode, RequestPriority, ReferrerPolicy, RequestMode } from "./enums.js";
 /**
  * API Builder for creating configured API instances with reusable default settings.
@@ -263,6 +263,25 @@ type ApiBuilder = {
      * ```
      */
     withCache(cache: RequestCache): ApiBuilder;
+    /**
+     * Sets a custom fetch implementation for all requests created through this API instance.
+     * Useful for injecting test stubs, undici agents/dispatchers, or framework-patched
+     * fetch functions (e.g. Next.js caching options). Individual requests can still
+     * override it with their own `withFetch` call.
+     *
+     * @param fetchFn - A fetch-compatible function
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * import { fetch as undiciFetch, Agent } from 'undici';
+     * const agent = new Agent({ connections: 10 });
+     * const api = createApi()
+     *   .withBaseURL('https://api.example.com')
+     *   .withFetch((url, init) => undiciFetch(url, { ...init, dispatcher: agent }));
+     * ```
+     */
+    withFetch(fetchFn: FetchFunction): ApiBuilder;
     /**
      * Set the request mode.
      * Controls CORS behavior and what types of responses are allowed.

package/dist/library/index.cjs

@@ -108,6 +108,8 @@ exports.CacheMode = void 0;
  *    console.log(`URL: ${error.url}`);
  *    console.log(`Method: ${error.method}`);
  *    console.log(`Status: ${error.status}`);
+ *    console.log(`Body: ${error.body}`); // Raw response body (if available)
+ *    console.log(error.getJson()); // Body parsed as JSON (or undefined)
  *    console.log(`Is timeout: ${error.isTimeout}`);
  *    console.log(`Is aborted: ${error.isAborted}`);
  * }
@@ -118,6 +120,12 @@ class RequestError extends Error {
     status;
     /** The Response object if the request received a response before failing */
     response;
+    /**
+     * The raw response body as text, if a response was received and its body could be read.
+     * `undefined` for errors without a response (network errors, timeouts, aborts)
+     * or when the body could not be read.
+     */
+    body;
     /** The URL that was requested */
     url;
     /** The HTTP method that was used (e.g., 'GET', 'POST') */
@@ -126,6 +134,8 @@ class RequestError extends Error {
     isTimeout;
     /** Whether the request was aborted (cancelled) */
     isAborted;
+    /** Cached result of parsing `body` as JSON (lazily populated by getJson) */
+    parsedBody;
     /**
      * Creates a new RequestError instance.
      *
@@ -135,6 +145,7 @@ class RequestError extends Error {
      * @param options - Additional error context
      * @param options.status - HTTP status code if available
      * @param options.response - The Response object if available
+     * @param options.body - The raw response body as text, 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
@@ -146,6 +157,7 @@ class RequestError extends Error {
         this.method = method;
         this.status = options.status;
         this.response = options.response;
+        this.body = options.body;
         this.isTimeout = !!options.isTimeout;
         this.isAborted = !!options.isAborted;
         // For better stack traces in modern environments
@@ -155,6 +167,62 @@ class RequestError extends Error {
         // Maintains proper prototype chain for instanceof checks
         Object.setPrototypeOf(this, RequestError.prototype);
     }
+    /**
+     * Parses the captured response body (`body`) as JSON.
+     * The result is cached, so repeated calls don't re-parse.
+     * This method never throws - it returns `undefined` when there is no body
+     * or the body is not valid JSON, making it safe to use in error handlers.
+     *
+     * @returns The parsed JSON body, or `undefined` if no body was captured or it isn't valid JSON
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await create.post('/api/users').withBody(user).getJson();
+     * } catch (error) {
+     *   if (error instanceof RequestError) {
+     *     const details = error.getJson<{ message: string; code: string }>();
+     *     console.log(details?.message ?? error.body ?? error.message);
+     *   }
+     * }
+     * ```
+     */
+    getJson() {
+        if (this.parsedBody === undefined && this.body) {
+            try {
+                this.parsedBody = JSON.parse(this.body);
+            }
+            catch {
+                // Body is not valid JSON - leave parsedBody undefined
+            }
+        }
+        return this.parsedBody;
+    }
+    /**
+     * Safely reads the body of a Response as text without consuming it.
+     * The response is cloned before reading, so the original body remains readable.
+     * Never throws - returns `undefined` if the body is unavailable or cannot be read
+     * (e.g., already consumed, locked stream, or read failure).
+     *
+     * @param response - The Response to read the body from
+     * @returns The body as text, or `undefined` if it could not be read
+     *
+     * @example
+     * ```typescript
+     * const body = await RequestError.captureBody(response);
+     * throw RequestError.fromResponse(response, url, 'GET', body);
+     * ```
+     */
+    static async captureBody(response) {
+        try {
+            if (!response.bodyUsed)
+                return await response.clone().text();
+        }
+        catch {
+            // Body could not be read (e.g., locked stream or read failure)
+        }
+        return undefined;
+    }
     /**
      * Creates a RequestError for a timeout failure.
      *
@@ -180,20 +248,23 @@ class RequestError extends Error {
      * @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
+     * @param body - The response body as text, if already read (see {@link RequestError.captureBody})
+     * @returns A RequestError with the status code, response object, and body (if provided)
      *
      * @example
      * ```typescript
      * const response = await fetch('/api/users');
      * if (!response.ok) {
-     *   throw RequestError.fromResponse(response, '/api/users', 'GET');
+     *   const body = await RequestError.captureBody(response);
+     *   throw RequestError.fromResponse(response, '/api/users', 'GET', body);
      * }
      * ```
      */
-    static fromResponse(response, url, method) {
+    static fromResponse(response, url, method, body) {
         return new RequestError(`HTTP ${response.status}`, url, method, {
             status: response.status,
             response,
+            body,
         });
     }
     /**
@@ -412,6 +483,7 @@ class ResponseWrapper {
         throw new RequestError(`GQL: ${errorMessage}`, this.url || "", this.method || "", {
             status: this.response.status,
             response: this.response,
+            body: this.cachedText,
         });
     }
     /**
@@ -472,6 +544,7 @@ class ResponseWrapper {
             throw new RequestError(`Bad JSON: ${error instanceof Error ? error.message : String(error)}`, this.url || "", this.method || "", {
                 status: this.response.status,
                 response: this.response,
+                body: this.cachedText,
             });
         }
     }
@@ -637,6 +710,7 @@ class ResponseWrapper {
                 throw new RequestError(`Selector: ${error instanceof Error ? error.message : String(error)}`, this.url || "", this.method || "", {
                     status: this.response.status,
                     response: this.response,
+                    body: this.cachedText,
                 });
             }
             // If we get here and it's not a RequestError, wrap it
@@ -1043,6 +1117,7 @@ class BaseRequest {
         headers: {},
     };
     abortController;
+    customFetch;
     queryParams = new URLSearchParams();
     autoApplyCsrfProtection = true;
     // Per-request interceptors
@@ -1288,6 +1363,41 @@ class BaseRequest {
         this.abortController = controller;
         return this;
     }
+    /**
+     * Sets a custom fetch implementation used to execute this request.
+     * By default, requests use the global `fetch`. Injecting a custom function unlocks
+     * testing without global mocks, custom undici dispatchers/agents in Node.js,
+     * and framework-specific fetch extensions (e.g. Next.js caching options).
+     *
+     * The provided function receives the final URL and `RequestInit` (after interceptors)
+     * and must return a `Promise<Response>`. It should honor `init.signal` so that
+     * `withTimeout` and `withAbortController` keep working.
+     *
+     * @param fetchFn - A fetch-compatible function
+     * @returns The request instance for chaining
+     * @throws {RequestError} If fetchFn is not a function
+     *
+     * @example
+     * // Testing: inject a stub instead of mocking the global fetch
+     * const stubFetch: FetchFunction = async () => new Response('{"ok":true}');
+     * const data = await create.get('/api/users').withFetch(stubFetch).getJson();
+     *
+     * @example
+     * // Node.js: route through a custom undici agent (proxy, keep-alive tuning, ...)
+     * import { fetch as undiciFetch, Agent } from 'undici';
+     * const agent = new Agent({ keepAliveTimeout: 30_000 });
+     * request.withFetch((url, init) => undiciFetch(url, { ...init, dispatcher: agent }));
+     *
+     * @example
+     * // Next.js: pass caching hints through to the framework's patched fetch
+     * request.withFetch((url, init) => fetch(url, { ...init, next: { revalidate: 60 } }));
+     */
+    withFetch(fetchFn) {
+        if (typeof fetchFn !== "function")
+            throw new RequestError("Bad fetch", this.url, this.method);
+        this.customFetch = fetchFn;
+        return this;
+    }
     /**
      * Sets the referrer URL for the request. The referrer is the URL of the page that initiated the request.
      * This can be used to override the default referrer that the browser would normally send.
@@ -2225,6 +2335,7 @@ class BaseRequest {
                         currentError = new RequestError(`ErrI${i + 1}: ${em}`, currentError.url, currentError.method, {
                             status: currentError.status,
                             response: currentError.response,
+                            body: currentError.body,
                         });
                     }
                     else {
@@ -2369,10 +2480,11 @@ class BaseRequest {
             if (abortSignal.signal) {
                 fetchOptions.signal = abortSignal.signal;
             }
-            // Execute fetch
+            // Execute fetch (custom implementation if provided, global fetch otherwise)
+            const fetchFn = this.customFetch ?? globalThis.fetch;
             let response;
             try {
-                response = await fetch(url, fetchOptions);
+                response = await fetchFn(url, fetchOptions);
             }
             catch (error) {
                 const errorObj = error instanceof Error ? error : new Error(String(error));
@@ -2405,7 +2517,9 @@ class BaseRequest {
                 throw RequestError.networkError(url, method, new Error("Failed with status 0 (network error or CORS blocked)"));
             }
             if (!response.ok) {
-                throw RequestError.fromResponse(response, url, method);
+                // Capture the response body so it's available on the error object
+                // (reads from a clone, so error.response remains readable)
+                throw RequestError.fromResponse(response, url, method, await RequestError.captureBody(response));
             }
             const graphQLOptions = this.getGraphQLOptions();
             const wrappedResponse = new ResponseWrapper(response, url, method, graphQLOptions);