create-request 1.5.4 → 1.6.1

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,32 +1,33 @@
 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
  * Provides the core request building and execution capabilities.
  */
 export declare abstract class BaseRequest {
-    protected abstract method: HttpMethod;
-    protected url: string;
-    protected requestOptions: RequestOptions;
-    protected abortController?: AbortController;
-    protected queryParams: URLSearchParams;
-    protected autoApplyCsrfProtection: boolean;
-    private requestInterceptors;
-    private responseInterceptors;
-    private errorInterceptors;
+    protected abstract _method: HttpMethod;
+    protected _url: string;
+    protected _opts: RequestOptions;
+    protected _ctrl?: AbortController;
+    protected _fetch?: FetchFunction;
+    protected _query: URLSearchParams;
+    protected _autoCsrf: boolean;
+    private _reqI;
+    private _resI;
+    private _errI;
     constructor(url: string);
     /**
      * Get GraphQL options if set (only for BodyRequest subclasses)
      * @returns GraphQL options or undefined
      */
-    protected getGraphQLOptions(): GraphQLOptions | undefined;
+    protected _gql(): GraphQLOptions | undefined;
     /**
      * Creates a fluent API for setting enum-based options
      * Combines direct setter with convenience methods
      */
-    private createFluentSetter;
-    private validateUrl;
+    private _fluent;
+    private _validateUrl;
     /**
      * Add multiple HTTP headers to the request
      *
@@ -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.
@@ -507,7 +538,7 @@ export declare abstract class BaseRequest {
      * Cross-environment base64 encoding
      * Works in both browser and Node.js environments
      */
-    private encodeBase64;
+    private _b64;
     /**
      * Sets a Bearer token for authentication.
      * Shorthand for `withAuthorization('Bearer ' + token)`.
@@ -526,13 +557,13 @@ export declare abstract class BaseRequest {
      * Safely get headers as a Record<string, string>
      * @returns The headers object
      */
-    private getHeadersRecord;
+    private _headers;
     /**
      * Helper function to check for header presence in a case-insensitive way
      * @param headerName Header name to check
      * @returns Boolean indicating if the header exists (case-insensitive)
      */
-    private hasHeader;
+    private _hasHeader;
     /**
      * Sets cookies for the request.
      * Cookies are sent in the Cookie header. Multiple calls will merge cookies.
@@ -784,13 +815,13 @@ export declare abstract class BaseRequest {
     /**
      * Apply CSRF protection headers based on configuration
      */
-    private applyCsrfProtection;
+    private _applyCsrf;
     /**
      * Formats the URL with any query parameters
      * @param url The base URL
      * @returns The URL with query parameters appended
      */
-    private formatUrlWithQueryParams;
+    private _fullUrl;
     /**
      * Executes a request with configured retry logic
      * @param url The formatted URL to send the request to
@@ -798,42 +829,42 @@ export declare abstract class BaseRequest {
      * @returns A wrapped response object
      * @throws RequestError if the request fails after all retries
      */
-    private executeWithRetries;
+    private _retry;
     /**
      * Run request interceptors in order: global interceptors first, then per-request
      * @param configParam - The request configuration
      * @returns Modified config or a Response to short-circuit
      */
-    private runRequestInterceptors;
+    private _runReqI;
     /**
      * Run response interceptors in reverse order: per-request interceptors first, then global in reverse
      * @param response - The response wrapper
      * @returns Modified response wrapper
      */
-    private runResponseInterceptors;
+    private _runResI;
     /**
      * Run error interceptors in reverse order: per-request interceptors first, then global in reverse
      * @param error - The error that occurred
      * @returns Modified error or a ResponseWrapper to recover
      */
-    private runErrorInterceptors;
+    private _runErrI;
     /**
      * Helper to create an abort signal with timeout support
      * Handles various AbortSignal API levels gracefully
      */
-    private createAbortSignal;
+    private _signal;
     /**
      * Manually combine two abort signals for older environments
      * Returns the first signal and listens to the second
      */
-    private combineSignalsManually;
+    private _combine;
     /**
      * Convert fetchOptions to RequestConfig with proper typing
      */
-    private createRequestConfig;
+    private _config;
     /**
      * Apply interceptor results back to fetchOptions
      */
-    private applyRequestConfig;
-    private executeRequest;
+    private _applyConfig;
+    private _run;
 }

package/dist/library/BodyRequest.d.ts

@@ -5,10 +5,9 @@ import type { ResponseWrapper } from "./ResponseWrapper.js";
  * Base class for requests that can have a body (POST, PUT, PATCH)
  */
 export declare abstract class BodyRequest extends BaseRequest {
-    protected body?: Body;
-    private bodyType?;
-    private graphQLOptions;
-    constructor(url: string);
+    protected _body?: Body;
+    private _bodyType?;
+    private _gqlOpts;
     /**
      * 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.
@@ -86,13 +85,13 @@ export declare abstract class BodyRequest extends BaseRequest {
     /**
      * Check if Content-Type header is already set (case-insensitive)
      */
-    private hasContentType;
-    private setContentTypeIfNeeded;
+    private _hasCT;
+    private _setCT;
     /**
      * Get the GraphQL options if set
      * @returns The GraphQL options or undefined
      */
-    protected getGraphQLOptions(): GraphQLOptions | undefined;
+    protected _gql(): GraphQLOptions | undefined;
     /**
      * Execute the request and return the ResponseWrapper
      * Overrides the base implementation to add body handling

package/dist/library/RequestError.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Extract a message from an unknown thrown value
+ * @internal
+ */
+export declare const errorMessage: (e: unknown) => string;
+/**
+ * Coerce an unknown thrown value to an Error
+ * @internal
+ */
+export declare const toError: (e: unknown) => Error;
 /**
  * Error class for HTTP request failures.
  * Extends the standard Error class with additional context about the failed request.
@@ -11,6 +21,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 +33,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 +47,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 _parsed?;
     /**
      * Creates a new RequestError instance.
      *
@@ -38,6 +58,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 +66,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 +129,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/ResponseWrapper.d.ts

@@ -18,12 +18,12 @@ export declare class ResponseWrapper {
     readonly url?: string;
     /** The HTTP method that was used (if available) */
     readonly method?: string;
-    private readonly response;
-    private graphQLOptions?;
-    private cachedBlob?;
-    private cachedText?;
-    private cachedJson?;
-    private cachedArrayBuffer?;
+    private readonly _res;
+    private _gqlOpts?;
+    private _blob?;
+    private _text?;
+    private _json?;
+    private _buf?;
     constructor(response: Response, url?: string, method?: string, graphQLOptions?: GraphQLOptions);
     /**
      * HTTP status code (e.g., 200, 404, 500)
@@ -46,17 +46,28 @@ export declare class ResponseWrapper {
      * Use this if you need direct access to the underlying Response.
      */
     get raw(): Response;
+    /**
+     * Create a RequestError carrying this response's context
+     * @param message - The error message
+     * @param withBody - Whether to attach the cached body text to the error
+     */
+    private _err;
+    /**
+     * Read the response body via the given reader, wrapping failures in a RequestError
+     * @throws RequestError if the body has already been consumed or reading fails
+     */
+    private _read;
     /**
      * Check if the response body has already been consumed and throw an error if so
      * @throws RequestError if the body has already been consumed
      */
-    private checkBodyNotConsumed;
+    private _checkUsed;
     /**
      * Check for GraphQL errors and throw if throwOnError is enabled
      * @param data - The parsed JSON data
      * @throws RequestError if GraphQL response contains errors and throwOnError is enabled
      */
-    private checkGraphQLErrors;
+    private _checkGql;
     /**
      * Parse the response body as JSON
      * If GraphQL options are set with throwOnError=true, will check for GraphQL errors and throw.

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.