@foundatiofx/fetchclient 1.1.0 → 1.2.0

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;

package/script/src/FetchClientError.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FetchClientError = void 0;
+/**
+ * Error wrapper for non-2xx responses.
+ * Exposes the underlying response for compatibility and debugging.
+ */
+class FetchClientError extends Error {
+    response;
+    constructor(response, message) {
+        super(message ??
+            response.problem?.title ??
+            `Unexpected status code: ${response.status}`);
+        this.name = "FetchClientError";
+        this.response = response;
+    }
+    get status() {
+        return this.response.status;
+    }
+    get statusText() {
+        return this.response.statusText;
+    }
+    get ok() {
+        return this.response.ok;
+    }
+    get headers() {
+        return this.response.headers;
+    }
+    get url() {
+        return this.response.url;
+    }
+    get redirected() {
+        return this.response.redirected;
+    }
+    get type() {
+        return this.response.type;
+    }
+    get body() {
+        return this.response.body;
+    }
+    get bodyUsed() {
+        return this.response.bodyUsed;
+    }
+    get data() {
+        return this.response.data;
+    }
+    get problem() {
+        return this.response.problem;
+    }
+    get meta() {
+        return this.response.meta;
+    }
+    json() {
+        return this.response.json();
+    }
+    text() {
+        return this.response.text();
+    }
+    arrayBuffer() {
+        return this.response.arrayBuffer();
+    }
+    blob() {
+        return this.response.blob();
+    }
+    formData() {
+        return this.response.formData();
+    }
+    // @ts-ignore: New in Deno 1.44
+    bytes() {
+        // @ts-ignore: New in Deno 1.44
+        return this.response.bytes();
+    }
+    clone() {
+        return this.response.clone();
+    }
+}
+exports.FetchClientError = FetchClientError;

package/script/src/FetchClientProvider.js

@@ -9,6 +9,7 @@ const RateLimitMiddleware_js_1 = require("./RateLimitMiddleware.js");
 const RateLimiter_js_1 = require("./RateLimiter.js");
 const CircuitBreakerMiddleware_js_1 = require("./CircuitBreakerMiddleware.js");
 const CircuitBreaker_js_1 = require("./CircuitBreaker.js");
+const RetryMiddleware_js_1 = require("./RetryMiddleware.js");
 /**
  * Represents a provider for creating instances of the FetchClient class with shared default options and cache.
  */
@@ -20,6 +21,8 @@ class FetchClientProvider {
     #rateLimitMiddlewareFunc;
     #circuitBreakerMiddleware;
     #circuitBreakerMiddlewareFunc;
+    #retryMiddleware;
+    #retryMiddlewareFunc;
     #counter = new Counter_js_1.Counter();
     #onLoading = new ObjectEvent_js_1.ObjectEvent();
     /**
@@ -253,6 +256,27 @@ class FetchClientProvider {
             this.#options.middleware = this.#options.middleware?.filter((m) => m !== middlewareFunc);
         }
     }
+    /**
+     * Enables automatic retry for failed requests.
+     * Retries are performed with exponential backoff and jitter.
+     * @param options - The retry configuration options.
+     */
+    useRetry(options) {
+        this.#retryMiddleware = new RetryMiddleware_js_1.RetryMiddleware(options);
+        this.#retryMiddlewareFunc = this.#retryMiddleware.middleware();
+        this.useMiddleware(this.#retryMiddlewareFunc);
+    }
+    /**
+     * Removes the retry middleware from all FetchClient instances created by this provider.
+     */
+    removeRetry() {
+        const middlewareFunc = this.#retryMiddlewareFunc;
+        this.#retryMiddleware = undefined;
+        this.#retryMiddlewareFunc = undefined;
+        if (middlewareFunc) {
+            this.#options.middleware = this.#options.middleware?.filter((m) => m !== middlewareFunc);
+        }
+    }
 }
 exports.FetchClientProvider = FetchClientProvider;
 const provider = new FetchClientProvider();

package/script/src/RateLimitMiddleware.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RateLimitMiddleware = exports.RateLimitError = void 0;
+exports.createRateLimitMiddleware = createRateLimitMiddleware;
+exports.createPerDomainRateLimitMiddleware = createPerDomainRateLimitMiddleware;
 const ProblemDetails_js_1 = require("./ProblemDetails.js");
 const RateLimiter_js_1 = require("./RateLimiter.js");
 /**
@@ -118,3 +120,37 @@ class RateLimitMiddleware {
     }
 }
 exports.RateLimitMiddleware = RateLimitMiddleware;
+/**
+ * Creates a rate limit middleware with the given options.
+ *
+ * @example
+ * ```typescript
+ * const client = new FetchClient();
+ * client.use(createRateLimitMiddleware({
+ *   maxRequests: 100,
+ *   windowSeconds: 60,
+ * }));
+ * ```
+ */
+function createRateLimitMiddleware(options) {
+    return new RateLimitMiddleware(options).middleware();
+}
+/**
+ * Creates a per-domain rate limit middleware where each domain is tracked separately.
+ *
+ * @example
+ * ```typescript
+ * const client = new FetchClient();
+ * client.use(createPerDomainRateLimitMiddleware({
+ *   maxRequests: 100,
+ *   windowSeconds: 60,
+ * }));
+ * // api.example.com and api.other.com will have separate rate limits
+ * ```
+ */
+function createPerDomainRateLimitMiddleware(options) {
+    return new RateLimitMiddleware({
+        ...options,
+        getGroupFunc: RateLimiter_js_1.groupByDomain,
+    }).middleware();
+}

package/script/src/ResponsePromise.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResponsePromise = void 0;
+/**
+ * A promise that resolves to a FetchClientResponse with additional helper methods
+ * for parsing the response body. This allows for a fluent API similar to ky:
+ *
+ * @example
+ * ```typescript
+ * // Await to get the full response
+ * const response = await client.get("/api/users");
+ *
+ * // Or use helper methods for direct access to parsed body
+ * const users = await client.get("/api/users").json<User[]>();
+ * const html = await client.get("/page").text();
+ * const file = await client.get("/file").blob();
+ * ```
+ */
+class ResponsePromise {
+    #responsePromise;
+    #options;
+    constructor(responsePromise, options) {
+        this.#responsePromise = responsePromise;
+        this.#options = options;
+    }
+    /**
+     * Implements PromiseLike interface so the ResponsePromise can be awaited.
+     */
+    then(onfulfilled, onrejected) {
+        return this.#responsePromise.then(onfulfilled, onrejected);
+    }
+    /**
+     * Catches any errors from the response promise.
+     */
+    catch(onrejected) {
+        return this.#responsePromise.catch(onrejected);
+    }
+    /**
+     * Executes a callback when the promise settles (fulfilled or rejected).
+     */
+    finally(onfinally) {
+        return this.#responsePromise.finally(onfinally);
+    }
+    /**
+     * Parses the response body as JSON.
+     *
+     * If the response was already parsed as JSON (via getJSON, postJSON, etc.),
+     * returns the parsed data directly. Otherwise, parses the response body.
+     *
+     * @template TJson - The expected type of the JSON response
+     * @returns A promise that resolves to the parsed JSON
+     *
+     * @example
+     * ```typescript
+     * const user = await client.get("/api/user/1").json<User>();
+     * ```
+     */
+    async json() {
+        const response = await this.#responsePromise;
+        // If the response already has parsed data (from getJSON, etc.), return it
+        if (response.data !== null && response.data !== undefined) {
+            return response.data;
+        }
+        // Otherwise, parse the response body as JSON
+        const data = await response.json();
+        // Apply reviver and date parsing if options are set
+        if (this.#options?.reviver || this.#options?.shouldParseDates) {
+            return this.#reviveJson(data);
+        }
+        return data;
+    }
+    /**
+     * Returns the response body as text.
+     *
+     * @returns A promise that resolves to the response text
+     *
+     * @example
+     * ```typescript
+     * const html = await client.get("/page").text();
+     * ```
+     */
+    async text() {
+        const response = await this.#responsePromise;
+        return response.text();
+    }
+    /**
+     * Returns the response body as a Blob.
+     *
+     * @returns A promise that resolves to the response as a Blob
+     *
+     * @example
+     * ```typescript
+     * const imageBlob = await client.get("/image.png").blob();
+     * ```
+     */
+    async blob() {
+        const response = await this.#responsePromise;
+        return response.blob();
+    }
+    /**
+     * Returns the response body as an ArrayBuffer.
+     *
+     * @returns A promise that resolves to the response as an ArrayBuffer
+     *
+     * @example
+     * ```typescript
+     * const buffer = await client.get("/file").arrayBuffer();
+     * ```
+     */
+    async arrayBuffer() {
+        const response = await this.#responsePromise;
+        return response.arrayBuffer();
+    }
+    /**
+     * Returns the response body as FormData.
+     *
+     * @returns A promise that resolves to the response as FormData
+     *
+     * @example
+     * ```typescript
+     * const formData = await client.get("/form").formData();
+     * ```
+     */
+    async formData() {
+        const response = await this.#responsePromise;
+        return response.formData();
+    }
+    #reviveJson(data) {
+        if (data === null || data === undefined) {
+            return data;
+        }
+        if (Array.isArray(data)) {
+            return data.map((item) => this.#reviveJson(item));
+        }
+        if (typeof data === "object") {
+            const result = {};
+            for (const [key, value] of Object.entries(data)) {
+                result[key] = this.#reviveValue(key, this.#reviveJson(value));
+            }
+            return result;
+        }
+        return this.#reviveValue("", data);
+    }
+    #reviveValue(key, value) {
+        let revivedValue = value;
+        if (this.#options?.reviver) {
+            revivedValue = this.#options.reviver.call(this, key, revivedValue);
+        }
+        if (this.#options?.shouldParseDates) {
+            revivedValue = this.#tryParseDate(revivedValue);
+        }
+        return revivedValue;
+    }
+    #tryParseDate(value) {
+        if (typeof value !== "string") {
+            return value;
+        }
+        if (/^\d{4}-\d{2}-\d{2}/.test(value)) {
+            const date = new Date(value);
+            if (!isNaN(date.getTime())) {
+                return date;
+            }
+        }
+        return value;
+    }
+}
+exports.ResponsePromise = ResponsePromise;