@foundatiofx/fetchclient 1.1.1 → 1.2.0

package/esm/src/RetryMiddleware.js

@@ -0,0 +1,179 @@
+/**
+ * Default HTTP methods that are eligible for retry.
+ * These are idempotent methods that can be safely retried without side effects.
+ */
+const DEFAULT_RETRY_METHODS = [
+    "GET",
+    "HEAD",
+    "PUT",
+    "DELETE",
+    "OPTIONS",
+    "TRACE",
+];
+/**
+ * Default HTTP status codes that trigger a retry.
+ */
+const DEFAULT_RETRY_STATUS_CODES = [
+    408, // Request Timeout
+    413, // Payload Too Large (rate limiting)
+    429, // Too Many Requests
+    500, // Internal Server Error
+    502, // Bad Gateway
+    503, // Service Unavailable
+    504, // Gateway Timeout
+];
+/**
+ * Retry middleware that automatically retries failed requests with exponential backoff.
+ *
+ * @example
+ * ```typescript
+ * const provider = new FetchClientProvider();
+ * provider.useRetry({
+ *   limit: 3,
+ *   statusCodes: [500, 502, 503, 504],
+ *   jitter: 0.1,
+ * });
+ *
+ * const client = provider.getFetchClient();
+ * const response = await client.getJSON('/api/data');
+ * ```
+ */
+export class RetryMiddleware {
+    #options;
+    constructor(options) {
+        this.#options = {
+            limit: options?.limit ?? 2,
+            methods: (options?.methods ?? DEFAULT_RETRY_METHODS).map((m) => m.toUpperCase()),
+            statusCodes: options?.statusCodes ?? DEFAULT_RETRY_STATUS_CODES,
+            maxRetryAfter: options?.maxRetryAfter ?? Infinity,
+            backoffLimit: options?.backoffLimit ?? 30000,
+            jitter: options?.jitter ?? 0.1,
+            delay: options?.delay,
+            shouldRetry: options?.shouldRetry,
+            onRetry: options?.onRetry,
+        };
+    }
+    /**
+     * Creates the middleware function.
+     * @returns The middleware function
+     */
+    middleware() {
+        return async (context, next) => {
+            const method = context.request.method.toUpperCase();
+            // Check if method is eligible for retry
+            if (!this.#options.methods.includes(method)) {
+                await next();
+                return;
+            }
+            let attemptNumber = 0;
+            while (true) {
+                // Store retry metadata in context for observability
+                if (attemptNumber > 0) {
+                    context.retryAttempt = attemptNumber;
+                }
+                await next();
+                // If no response or we've exhausted retries, stop
+                if (!context.response || attemptNumber >= this.#options.limit) {
+                    break;
+                }
+                const response = context.response;
+                // Check if status code is retryable
+                if (!this.#options.statusCodes.includes(response.status)) {
+                    break;
+                }
+                // Check custom shouldRetry predicate
+                if (this.#options.shouldRetry) {
+                    const shouldRetry = await this.#options.shouldRetry(response, attemptNumber);
+                    if (!shouldRetry) {
+                        break;
+                    }
+                }
+                // Calculate base delay
+                let delay = this.#calculateDelay(attemptNumber, response);
+                // Check Retry-After header
+                const retryAfterDelay = this.#parseRetryAfter(response);
+                if (retryAfterDelay !== null) {
+                    // If Retry-After exceeds maxRetryAfter, don't retry
+                    if (retryAfterDelay > this.#options.maxRetryAfter) {
+                        break;
+                    }
+                    // Use the larger of computed delay or Retry-After
+                    delay = Math.max(delay, retryAfterDelay);
+                }
+                // Invoke onRetry callback
+                this.#options.onRetry?.(attemptNumber, response, delay);
+                // Wait before retry
+                await this.#sleep(delay);
+                // Reset response for next attempt
+                context.response = null;
+                attemptNumber++;
+            }
+        };
+    }
+    /**
+     * Calculates the delay for a given attempt with exponential backoff and jitter.
+     */
+    #calculateDelay(attemptNumber, response) {
+        let baseDelay;
+        if (this.#options.delay) {
+            baseDelay = this.#options.delay(attemptNumber, response);
+        }
+        else {
+            // Default exponential backoff: 1s, 2s, 4s, 8s, ...
+            baseDelay = Math.min(1000 * Math.pow(2, attemptNumber), this.#options.backoffLimit);
+        }
+        // Apply jitter
+        return this.#applyJitter(baseDelay);
+    }
+    /**
+     * Applies jitter to a delay value.
+     */
+    #applyJitter(delay) {
+        if (this.#options.jitter <= 0) {
+            return delay;
+        }
+        const jitterRange = delay * this.#options.jitter;
+        // Random value between -jitterRange and +jitterRange
+        const jitter = (Math.random() * 2 - 1) * jitterRange;
+        return Math.max(0, Math.round(delay + jitter));
+    }
+    /**
+     * Parses the Retry-After header and returns the delay in milliseconds.
+     * Supports both delta-seconds and HTTP-date formats.
+     */
+    #parseRetryAfter(response) {
+        const retryAfter = response.headers.get("Retry-After");
+        if (!retryAfter) {
+            return null;
+        }
+        // Try parsing as seconds (integer)
+        const seconds = parseInt(retryAfter, 10);
+        if (!isNaN(seconds)) {
+            return seconds * 1000;
+        }
+        // Try parsing as HTTP-date
+        const date = Date.parse(retryAfter);
+        if (!isNaN(date)) {
+            return Math.max(0, date - Date.now());
+        }
+        return null;
+    }
+    /**
+     * Sleep for the specified number of milliseconds.
+     */
+    #sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+/**
+ * Creates a retry middleware with the given options.
+ *
+ * @example
+ * ```typescript
+ * const client = new FetchClient();
+ * client.use(createRetryMiddleware({ limit: 3 }));
+ * ```
+ */
+export function createRetryMiddleware(options) {
+    return new RetryMiddleware(options).middleware();
+}

package/esm/src/mocks/MockHistory.js

@@ -3,6 +3,7 @@
  */
 export class MockHistoryImpl {
     #get = [];
+    #head = [];
     #post = [];
     #put = [];
     #patch = [];
@@ -11,6 +12,9 @@ export class MockHistoryImpl {
     get get() {
         return [...this.#get];
     }
+    get head() {
+        return [...this.#head];
+    }
     get post() {
         return [...this.#post];
     }
@@ -35,6 +39,9 @@ export class MockHistoryImpl {
             case "GET":
                 this.#get.push(request);
                 break;
+            case "HEAD":
+                this.#head.push(request);
+                break;
             case "POST":
                 this.#post.push(request);
                 break;
@@ -54,6 +61,7 @@ export class MockHistoryImpl {
      */
     clear() {
         this.#get = [];
+        this.#head = [];
         this.#post = [];
         this.#put = [];
         this.#patch = [];

package/esm/src/mocks/MockRegistry.js

@@ -40,6 +40,13 @@ export class MockRegistry {
     onGet(url) {
         return this.#addMock("GET", url);
     }
+    /**
+     * Creates a mock for HEAD requests matching the given URL.
+     * @param url - URL string or RegExp to match
+     */
+    onHead(url) {
+        return this.#addMock("HEAD", url);
+    }
     /**
      * Creates a mock for POST requests matching the given URL.
      * @param url - URL string or RegExp to match

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foundatiofx/fetchclient",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "A typed JSON fetch client with middleware support for Deno, Node and the browser.",
   "keywords": [
     "Fetch",

package/script/mod.js

@@ -14,9 +14,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createPerDomainCircuitBreakerMiddleware = exports.createCircuitBreakerMiddleware = exports.CircuitOpenError = exports.CircuitBreakerMiddleware = exports.circuitBreakerGroupByDomain = exports.CircuitBreaker = exports.FetchClientProvider = exports.defaultProviderInstance = exports.FetchClientCache = exports.ProblemDetails = exports.FetchClient = void 0;
+exports.middleware = exports.RateLimiter = exports.rateLimiterGroupByDomain = exports.RateLimitMiddleware = exports.RateLimitError = exports.createRateLimitMiddleware = exports.createPerDomainRateLimitMiddleware = exports.RetryMiddleware = exports.createRetryMiddleware = exports.createPerDomainCircuitBreakerMiddleware = exports.createCircuitBreakerMiddleware = exports.CircuitOpenError = exports.CircuitBreakerMiddleware = exports.circuitBreakerGroupByDomain = exports.CircuitBreaker = exports.FetchClientProvider = exports.defaultProviderInstance = exports.FetchClientCache = exports.ProblemDetails = exports.ResponsePromise = exports.FetchClientError = exports.FetchClient = void 0;
 var FetchClient_js_1 = require("./src/FetchClient.js");
 Object.defineProperty(exports, "FetchClient", { enumerable: true, get: function () { return FetchClient_js_1.FetchClient; } });
+var FetchClientError_js_1 = require("./src/FetchClientError.js");
+Object.defineProperty(exports, "FetchClientError", { enumerable: true, get: function () { return FetchClientError_js_1.FetchClientError; } });
+var ResponsePromise_js_1 = require("./src/ResponsePromise.js");
+Object.defineProperty(exports, "ResponsePromise", { enumerable: true, get: function () { return ResponsePromise_js_1.ResponsePromise; } });
 var ProblemDetails_js_1 = require("./src/ProblemDetails.js");
 Object.defineProperty(exports, "ProblemDetails", { enumerable: true, get: function () { return ProblemDetails_js_1.ProblemDetails; } });
 var FetchClientCache_js_1 = require("./src/FetchClientCache.js");
@@ -33,3 +37,92 @@ Object.defineProperty(exports, "CircuitBreakerMiddleware", { enumerable: true, g
 Object.defineProperty(exports, "CircuitOpenError", { enumerable: true, get: function () { return CircuitBreakerMiddleware_js_1.CircuitOpenError; } });
 Object.defineProperty(exports, "createCircuitBreakerMiddleware", { enumerable: true, get: function () { return CircuitBreakerMiddleware_js_1.createCircuitBreakerMiddleware; } });
 Object.defineProperty(exports, "createPerDomainCircuitBreakerMiddleware", { enumerable: true, get: function () { return CircuitBreakerMiddleware_js_1.createPerDomainCircuitBreakerMiddleware; } });
+var RetryMiddleware_js_1 = require("./src/RetryMiddleware.js");
+Object.defineProperty(exports, "createRetryMiddleware", { enumerable: true, get: function () { return RetryMiddleware_js_1.createRetryMiddleware; } });
+Object.defineProperty(exports, "RetryMiddleware", { enumerable: true, get: function () { return RetryMiddleware_js_1.RetryMiddleware; } });
+var RateLimitMiddleware_js_1 = require("./src/RateLimitMiddleware.js");
+Object.defineProperty(exports, "createPerDomainRateLimitMiddleware", { enumerable: true, get: function () { return RateLimitMiddleware_js_1.createPerDomainRateLimitMiddleware; } });
+Object.defineProperty(exports, "createRateLimitMiddleware", { enumerable: true, get: function () { return RateLimitMiddleware_js_1.createRateLimitMiddleware; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return RateLimitMiddleware_js_1.RateLimitError; } });
+Object.defineProperty(exports, "RateLimitMiddleware", { enumerable: true, get: function () { return RateLimitMiddleware_js_1.RateLimitMiddleware; } });
+var RateLimiter_js_1 = require("./src/RateLimiter.js");
+Object.defineProperty(exports, "rateLimiterGroupByDomain", { enumerable: true, get: function () { return RateLimiter_js_1.groupByDomain; } });
+Object.defineProperty(exports, "RateLimiter", { enumerable: true, get: function () { return RateLimiter_js_1.RateLimiter; } });
+const RetryMiddleware_js_2 = require("./src/RetryMiddleware.js");
+const RateLimitMiddleware_js_2 = require("./src/RateLimitMiddleware.js");
+const CircuitBreakerMiddleware_js_2 = require("./src/CircuitBreakerMiddleware.js");
+const DefaultHelpers_js_1 = require("./src/DefaultHelpers.js");
+/**
+ * Convenience middleware factory functions for use with FetchClient.use()
+ *
+ * @example
+ * ```typescript
+ * import { FetchClient, middleware } from "@foundatiofx/fetchclient";
+ *
+ * const client = new FetchClient();
+ * client.use(
+ *   middleware.retry({ limit: 3 }),
+ *   middleware.rateLimit({ maxRequests: 100, windowSeconds: 60 }),
+ *   middleware.circuitBreaker({ failureThreshold: 5 })
+ * );
+ * ```
+ */
+exports.middleware = {
+    /** Retry failed requests with exponential backoff and jitter */
+    retry: RetryMiddleware_js_2.createRetryMiddleware,
+    /** Rate limit requests to prevent overwhelming servers */
+    rateLimit: RateLimitMiddleware_js_2.createRateLimitMiddleware,
+    /** Per-domain rate limit (each domain tracked separately) */
+    perDomainRateLimit: RateLimitMiddleware_js_2.createPerDomainRateLimitMiddleware,
+    /** Circuit breaker for fault tolerance */
+    circuitBreaker: CircuitBreakerMiddleware_js_2.createCircuitBreakerMiddleware,
+    /** Per-domain circuit breaker (each domain tracked separately) */
+    perDomainCircuitBreaker: CircuitBreakerMiddleware_js_2.createPerDomainCircuitBreakerMiddleware,
+};
+/**
+ * Default export for convenient access to all HTTP methods.
+ *
+ * @example
+ * ```typescript
+ * import fc from "@foundatiofx/fetchclient";
+ *
+ * // Configure middleware
+ * fc.use(fc.middleware.retry({ limit: 3 }));
+ *
+ * // Use JSON methods (recommended)
+ * const { data: user } = await fc.getJSON<User>("/api/user/1");
+ * const { data: created } = await fc.postJSON<User>("/api/users", { name: "Alice" });
+ *
+ * // Or use fluent API for other response types
+ * const html = await fc.get("/page").text();
+ * ```
+ */
+const fetchClient = {
+    /** Sends a GET request. Use `.json<T>()` for typed JSON response. */
+    get: (url, options) => (0, DefaultHelpers_js_1.useFetchClient)().get(url, options),
+    /** Sends a POST request. Use `.json<T>()` for typed JSON response. */
+    post: (url, body, options) => (0, DefaultHelpers_js_1.useFetchClient)().post(url, body, options),
+    /** Sends a PUT request. Use `.json<T>()` for typed JSON response. */
+    put: (url, body, options) => (0, DefaultHelpers_js_1.useFetchClient)().put(url, body, options),
+    /** Sends a PATCH request. Use `.json<T>()` for typed JSON response. */
+    patch: (url, body, options) => (0, DefaultHelpers_js_1.useFetchClient)().patch(url, body, options),
+    /** Sends a DELETE request. Use `.json<T>()` for typed JSON response. */
+    delete: (url, options) => (0, DefaultHelpers_js_1.useFetchClient)().delete(url, options),
+    /** Sends a HEAD request. */
+    head: (url, options) => (0, DefaultHelpers_js_1.useFetchClient)().head(url, options),
+    /** Sends a GET request and returns parsed JSON in response.data */
+    getJSON: DefaultHelpers_js_1.getJSON,
+    /** Sends a POST request and returns parsed JSON in response.data */
+    postJSON: DefaultHelpers_js_1.postJSON,
+    /** Sends a PUT request and returns parsed JSON in response.data */
+    putJSON: DefaultHelpers_js_1.putJSON,
+    /** Sends a PATCH request and returns parsed JSON in response.data */
+    patchJSON: DefaultHelpers_js_1.patchJSON,
+    /** Sends a DELETE request and returns parsed JSON in response.data */
+    deleteJSON: DefaultHelpers_js_1.deleteJSON,
+    /** Adds middleware to the default provider */
+    use: DefaultHelpers_js_1.useMiddleware,
+    /** Middleware factory functions */
+    middleware: exports.middleware,
+};
+exports.default = fetchClient;

package/script/src/DefaultHelpers.js

@@ -31,7 +31,7 @@ function useFetchClient(options) {
  * Sends a GET request to the specified URL using the default client and provider and returns the response as JSON.
  * @param url - The URL to send the GET request to.
  * @param options - Optional request options.
- * @returns A promise that resolves to the response as JSON.
+ * @returns A promise that resolves to the response with parsed JSON in `data`.
  */
 function getJSON(url, options) {
     return useFetchClient().getJSON(url, options);
@@ -43,7 +43,7 @@ function getJSON(url, options) {
  * @param {string} url - The URL to send the request to.
  * @param {object | string | FormData} [body] - The JSON payload or form data to send with the request.
  * @param {RequestOptions} [options] - Additional options for the request.
- * @returns {Promise<FetchClientResponse<T>>} - A promise that resolves to the response data.
+ * @returns A promise that resolves to the response with parsed JSON in `data`.
  */
 function postJSON(url, body, options) {
     return useFetchClient().postJSON(url, body, options);
@@ -55,7 +55,7 @@ function postJSON(url, body, options) {
  * @param {string} url - The URL to send the request to.
  * @param {object | string} [body] - The JSON payload to send with the request.
  * @param {RequestOptions} [options] - Additional options for the request.
- * @returns {Promise<FetchClientResponse<T>>} - A promise that resolves to the response data.
+ * @returns A promise that resolves to the response with parsed JSON in `data`.
  */
 function putJSON(url, body, options) {
     return useFetchClient().putJSON(url, body, options);
@@ -67,7 +67,7 @@ function putJSON(url, body, options) {
  * @param {string} url - The URL to send the request to.
  * @param {object | string} [body] - The JSON payload to send with the request.
  * @param {RequestOptions} [options] - Additional options for the request.
- * @returns {Promise<FetchClientResponse<T>>} - A promise that resolves to the response data.
+ * @returns A promise that resolves to the response with parsed JSON in `data`.
  */
 function patchJSON(url, body, options) {
     return useFetchClient().patchJSON(url, body, options);
@@ -78,7 +78,7 @@ function patchJSON(url, body, options) {
  * @template T - The type of the response data.
  * @param {string} url - The URL to send the request to.
  * @param {RequestOptions} [options] - Additional options for the request.
- * @returns {Promise<FetchClientResponse<T>>} - A promise that resolves to the response data.
+ * @returns A promise that resolves to the response with parsed JSON in `data`.
  */
 function deleteJSON(url, options) {
     return useFetchClient().deleteJSON(url, options);

package/script/src/FetchClient.js

@@ -7,6 +7,8 @@ const LinkHeader_js_1 = require("./LinkHeader.js");
 const FetchClientProvider_js_1 = require("./FetchClientProvider.js");
 const DefaultHelpers_js_1 = require("./DefaultHelpers.js");
 const ObjectEvent_js_1 = require("./ObjectEvent.js");
+const ResponsePromise_js_1 = require("./ResponsePromise.js");
+const FetchClientError_js_1 = require("./FetchClientError.js");
 /**
  * Represents a client for making HTTP requests using the Fetch API.
  */
@@ -103,24 +105,27 @@ class FetchClient {
      *
      * @param url - The URL to send the GET request to.
      * @param options - The optional request options.
-     * @returns A promise that resolves to the response of the GET request.
+     * @returns A ResponsePromise that resolves to the response. Can use `.json<T>()` for typed JSON.
      */
-    async get(url, options) {
-        options = {
+    get(url, options) {
+        const mergedOptions = {
             ...this.options.defaultRequestOptions,
             ...options,
         };
-        const response = await this.fetchInternal(url, options, this.buildRequestInit("GET", undefined, options));
-        return response;
+        const responsePromise = this.fetchInternal(url, mergedOptions, this.buildRequestInit("GET", undefined, mergedOptions));
+        return new ResponsePromise_js_1.ResponsePromise(responsePromise, mergedOptions);
     }
     /**
      * Sends a GET request to the specified URL and returns the response as JSON.
+     * The response will have the parsed JSON in `response.data`.
+     *
      * @param url - The URL to send the GET request to.
      * @param options - Optional request options.
-     * @returns A promise that resolves to the response as JSON.
+     * @returns A promise that resolves to the response with parsed JSON in `data`.
      */
-    getJSON(url, options) {
-        return this.get(url, this.buildJsonRequestOptions(options));
+    async getJSON(url, options) {
+        const mergedOptions = this.buildJsonRequestOptions(options);
+        return await this.get(url, mergedOptions);
     }
     /**
      * Sends a POST request to the specified URL.
@@ -128,107 +133,127 @@ class FetchClient {
      * @param url - The URL to send the request to.
      * @param body - The request body, can be an object, a string, or FormData.
      * @param options - Additional options for the request.
-     * @returns A promise that resolves to a FetchClientResponse object.
+     * @returns A ResponsePromise that resolves to the response. Can use `.json<T>()` for typed JSON.
      */
-    async post(url, body, options) {
-        options = {
+    post(url, body, options) {
+        const mergedOptions = {
             ...this.options.defaultRequestOptions,
             ...options,
         };
-        const response = await this.fetchInternal(url, options, this.buildRequestInit("POST", body, options));
-        return response;
+        const responsePromise = this.fetchInternal(url, mergedOptions, this.buildRequestInit("POST", body, mergedOptions));
+        return new ResponsePromise_js_1.ResponsePromise(responsePromise, mergedOptions);
     }
     /**
      * Sends a POST request with JSON payload to the specified URL.
+     * The response will have the parsed JSON in `response.data`.
      *
      * @template T - The type of the response data.
      * @param {string} url - The URL to send the request to.
      * @param {object | string | FormData} [body] - The JSON payload or form data to send with the request.
      * @param {RequestOptions} [options] - Additional options for the request.
-     * @returns {Promise<FetchClientResponse<T>>} - A promise that resolves to the response data.
+     * @returns A promise that resolves to the response with parsed JSON in `data`.
      */
-    postJSON(url, body, options) {
-        return this.post(url, body, this.buildJsonRequestOptions(options));
+    async postJSON(url, body, options) {
+        return await this.post(url, body, this.buildJsonRequestOptions(options));
     }
     /**
      * Sends a PUT request to the specified URL with the given body and options.
      * @param url - The URL to send the request to.
      * @param body - The request body, can be an object, a string, or FormData.
      * @param options - The request options.
-     * @returns A promise that resolves to a FetchClientResponse object.
+     * @returns A ResponsePromise that resolves to the response. Can use `.json<T>()` for typed JSON.
      */
-    async put(url, body, options) {
-        options = {
+    put(url, body, options) {
+        const mergedOptions = {
             ...this.options.defaultRequestOptions,
             ...options,
         };
-        const response = await this.fetchInternal(url, options, this.buildRequestInit("PUT", body, options));
-        return response;
+        const responsePromise = this.fetchInternal(url, mergedOptions, this.buildRequestInit("PUT", body, mergedOptions));
+        return new ResponsePromise_js_1.ResponsePromise(responsePromise, mergedOptions);
     }
     /**
      * Sends a PUT request with JSON payload to the specified URL.
+     * The response will have the parsed JSON in `response.data`.
      *
      * @template T - The type of the response data.
      * @param {string} url - The URL to send the request to.
      * @param {object | string} [body] - The JSON payload to send with the request.
      * @param {RequestOptions} [options] - Additional options for the request.
-     * @returns {Promise<FetchClientResponse<T>>} - A promise that resolves to the response data.
+     * @returns A promise that resolves to the response with parsed JSON in `data`.
      */
-    putJSON(url, body, options) {
-        return this.put(url, body, this.buildJsonRequestOptions(options));
+    async putJSON(url, body, options) {
+        return await this.put(url, body, this.buildJsonRequestOptions(options));
     }
     /**
      * Sends a PATCH request to the specified URL with the provided body and options.
      * @param url - The URL to send the PATCH request to.
      * @param body - The body of the request. It can be an object, a string, or FormData.
      * @param options - The options for the request.
-     * @returns A Promise that resolves to the response of the PATCH request.
+     * @returns A ResponsePromise that resolves to the response. Can use `.json<T>()` for typed JSON.
      */
-    async patch(url, body, options) {
-        options = {
+    patch(url, body, options) {
+        const mergedOptions = {
             ...this.options.defaultRequestOptions,
             ...options,
         };
-        const response = await this.fetchInternal(url, options, this.buildRequestInit("PATCH", body, options));
-        return response;
+        const responsePromise = this.fetchInternal(url, mergedOptions, this.buildRequestInit("PATCH", body, mergedOptions));
+        return new ResponsePromise_js_1.ResponsePromise(responsePromise, mergedOptions);
     }
     /**
      * Sends a PATCH request with JSON payload to the specified URL.
+     * The response will have the parsed JSON in `response.data`.
      *
      * @template T - The type of the response data.
      * @param {string} url - The URL to send the request to.
      * @param {object | string} [body] - The JSON payload to send with the request.
      * @param {RequestOptions} [options] - Additional options for the request.
-     * @returns {Promise<FetchClientResponse<T>>} - A promise that resolves to the response data.
+     * @returns A promise that resolves to the response with parsed JSON in `data`.
      */
-    patchJSON(url, body, options) {
-        return this.patch(url, body, this.buildJsonRequestOptions(options));
+    async patchJSON(url, body, options) {
+        return await this.patch(url, body, this.buildJsonRequestOptions(options));
     }
     /**
      * Sends a DELETE request to the specified URL.
      *
      * @param url - The URL to send the DELETE request to.
      * @param options - The options for the request.
-     * @returns A promise that resolves to a `FetchClientResponse` object.
+     * @returns A ResponsePromise that resolves to the response. Can use `.json<T>()` for typed JSON.
      */
-    async delete(url, options) {
-        options = {
+    delete(url, options) {
+        const mergedOptions = {
             ...this.options.defaultRequestOptions,
             ...options,
         };
-        const response = await this.fetchInternal(url, options, this.buildRequestInit("DELETE", undefined, options));
-        return response;
+        const responsePromise = this.fetchInternal(url, mergedOptions, this.buildRequestInit("DELETE", undefined, mergedOptions));
+        return new ResponsePromise_js_1.ResponsePromise(responsePromise, mergedOptions);
     }
     /**
      * Sends a DELETE request with JSON payload to the specified URL.
+     * The response will have the parsed JSON in `response.data`.
      *
      * @template T - The type of the response data.
      * @param {string} url - The URL to send the request to.
      * @param {RequestOptions} [options] - Additional options for the request.
-     * @returns {Promise<FetchClientResponse<T>>} - A promise that resolves to the response data.
+     * @returns A promise that resolves to the response with parsed JSON in `data`.
      */
-    deleteJSON(url, options) {
-        return this.delete(url, this.buildJsonRequestOptions(options));
+    async deleteJSON(url, options) {
+        return await this.delete(url, this.buildJsonRequestOptions(options));
+    }
+    /**
+     * Sends a HEAD request to the specified URL.
+     * HEAD requests are identical to GET requests but without the response body.
+     *
+     * @param url - The URL to send the HEAD request to.
+     * @param options - The optional request options.
+     * @returns A ResponsePromise that resolves to the response.
+     */
+    head(url, options) {
+        const mergedOptions = {
+            ...this.options.defaultRequestOptions,
+            ...options,
+        };
+        const responsePromise = this.fetchInternal(url, mergedOptions, this.buildRequestInit("HEAD", undefined, mergedOptions));
+        return new ResponsePromise_js_1.ResponsePromise(responsePromise, mergedOptions);
     }
     async validate(data, options) {
         if (typeof data !== "object" ||
@@ -543,7 +568,7 @@ class FetchClient {
         response.problem.status = response.status;
         response.problem.title = `Unexpected status code: ${response.status}`;
         response.problem.setErrorMessage(response.problem.title);
-        throw response;
+        throw new FetchClientError_js_1.FetchClientError(response);
     }
 }
 exports.FetchClient = FetchClient;