@foundatiofx/fetchclient 1.0.1 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foundatiofx/fetchclient",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "A typed JSON fetch client with middleware support for Deno, Node and the browser.",
   "keywords": [
     "Fetch",
@@ -35,6 +35,16 @@
         "types": "./types/mod.d.ts",
         "default": "./script/mod.js"
       }
+    },
+    "./mocks": {
+      "import": {
+        "types": "./types/src/mocks/mod.d.ts",
+        "default": "./esm/src/mocks/mod.js"
+      },
+      "require": {
+        "types": "./types/src/mocks/mod.d.ts",
+        "default": "./script/src/mocks/mod.js"
+      }
     }
   },
   "scripts": {
@@ -43,7 +53,7 @@
   "devDependencies": {
     "@types/node": "^20.9.0",
     "picocolors": "^1.0.0",
-    "zod": "^4.1.11",
+    "zod": "^4.3.6",
     "@deno/shim-deno": "~0.18.0"
   },
   "_generatedBy": "dnt@dev"

package/readme.md

@@ -7,7 +7,21 @@
 [![Discord](https://img.shields.io/discord/715744504891703319)](https://discord.gg/6HxgFCx)
 
 FetchClient is a tiny, typed wrapper around `fetch` with JSON helpers, caching,
-middleware, rate limiting, timeouts, and friendly error handling.
+middleware, rate limiting, circuit breaker, timeouts, and friendly error
+handling.
+
+## Features
+
+- **Typed JSON helpers** - `getJSON`, `postJSON`, `putJSON`, `patchJSON`,
+  `deleteJSON`
+- **Two API styles** - Functional or class-based - your choice
+- **Response caching** - TTL-based caching with tags for grouped invalidation
+- **Middleware** - Intercept requests/responses for logging, auth, transforms
+- **Rate limiting** - Per-domain rate limits with automatic header detection
+- **Circuit breaker** - Prevent cascading failures when services go down
+- **Timeouts** - Request timeouts with AbortSignal support
+- **Error handling** - RFC 7807 Problem Details support
+- **Testing** - MockRegistry for mocking HTTP in tests
 
 ## Install
 
@@ -17,23 +31,119 @@ npm install @foundatiofx/fetchclient
 
 ## Quick Example
 
+FetchClient works two ways - pick whichever style you prefer:
+
+### Functional API
+
+```ts
+import { getJSON, postJSON, setBaseUrl } from "@foundatiofx/fetchclient";
+
+setBaseUrl("https://api.example.com");
+
+const { data: users } = await getJSON<User[]>("/users");
+const { data: created } = await postJSON<User>("/users", { name: "Alice" });
+```
+
+Or use `getFetchClient()` to avoid multiple imports:
+
+```ts
+import { getFetchClient, setBaseUrl } from "@foundatiofx/fetchclient";
+
+setBaseUrl("https://api.example.com");
+
+const client = getFetchClient();
+const { data: users } = await client.getJSON<User[]>("/users");
+const { data: created } = await client.postJSON<User>("/users", {
+  name: "Alice",
+});
+```
+
+### Class-Based API
+
 ```ts
 import { FetchClient } from "@foundatiofx/fetchclient";
 
-type Products = { products: Array<{ id: number; name: string }> };
+const client = new FetchClient({ baseUrl: "https://api.example.com" });
+const { data } = await client.getJSON<User[]>("/users");
+```
+
+## Caching
+
+```ts
+const response = await client.getJSON<User>("/api/users/1", {
+  cacheKey: ["users", "1"],
+  cacheDuration: 60000, // 1 minute
+  cacheTags: ["users"],
+});
+
+// Invalidate by tag
+client.cache.deleteByTag("users");
+```
+
+## Middleware
+
+```ts
+import { useMiddleware } from "@foundatiofx/fetchclient";
+
+useMiddleware(async (ctx, next) => {
+  console.log("Request:", ctx.request.url);
+  await next();
+  console.log("Response:", ctx.response?.status);
+});
+```
+
+## Rate Limiting
+
+```ts
+import { usePerDomainRateLimit } from "@foundatiofx/fetchclient";
+
+usePerDomainRateLimit({
+  maxRequests: 100,
+  windowSeconds: 60,
+  updateFromHeaders: true, // Respect API rate limit headers
+});
+```
+
+## Circuit Breaker
+
+```ts
+import { useCircuitBreaker } from "@foundatiofx/fetchclient";
+
+useCircuitBreaker({
+  failureThreshold: 5,
+  openDurationMs: 30000,
+});
+
+// When API fails repeatedly, circuit opens
+// Requests return 503 immediately without hitting the API
+```
+
+## Testing
+
+```ts
+import { FetchClientProvider } from "@foundatiofx/fetchclient";
+import { MockRegistry } from "@foundatiofx/fetchclient/mocks";
+
+const mocks = new MockRegistry();
+mocks.onGet("/api/users").reply(200, [{ id: 1, name: "Alice" }]);
 
 const client = new FetchClient();
-const { data } = await client.getJSON<Products>(
-  `https://dummyjson.com/products/search?q=iphone&limit=10`,
-);
+mocks.install(client);
 
-console.log(data?.products.length);
+const { data } = await client.getJSON("/api/users");
+// data = [{ id: 1, name: "Alice" }]
 ```
 
 ## Documentation
 
 - Guide & Examples: <https://fetchclient.foundatio.dev>
-  - Getting Started, Usage Examples, Contributing
+  - [Getting Started](https://fetchclient.foundatio.dev/guide/getting-started)
+  - [Caching](https://fetchclient.foundatio.dev/guide/caching)
+  - [Middleware](https://fetchclient.foundatio.dev/guide/middleware)
+  - [Rate Limiting](https://fetchclient.foundatio.dev/guide/rate-limiting)
+  - [Circuit Breaker](https://fetchclient.foundatio.dev/guide/circuit-breaker)
+  - [Error Handling](https://fetchclient.foundatio.dev/guide/error-handling)
+  - [Testing](https://fetchclient.foundatio.dev/guide/testing)
 - API Reference: <https://jsr.io/@foundatiofx/fetchclient/doc>
 
 ---

package/script/mod.js

@@ -14,7 +14,7 @@ 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.FetchClientProvider = exports.defaultProviderInstance = exports.FetchClientCache = exports.ProblemDetails = exports.FetchClient = void 0;
+exports.createPerDomainCircuitBreakerMiddleware = exports.createCircuitBreakerMiddleware = exports.CircuitOpenError = exports.CircuitBreakerMiddleware = exports.circuitBreakerGroupByDomain = exports.CircuitBreaker = exports.FetchClientProvider = exports.defaultProviderInstance = exports.FetchClientCache = exports.ProblemDetails = 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 ProblemDetails_js_1 = require("./src/ProblemDetails.js");
@@ -25,3 +25,11 @@ var FetchClientProvider_js_1 = require("./src/FetchClientProvider.js");
 Object.defineProperty(exports, "defaultProviderInstance", { enumerable: true, get: function () { return FetchClientProvider_js_1.defaultInstance; } });
 Object.defineProperty(exports, "FetchClientProvider", { enumerable: true, get: function () { return FetchClientProvider_js_1.FetchClientProvider; } });
 __exportStar(require("./src/DefaultHelpers.js"), exports);
+var CircuitBreaker_js_1 = require("./src/CircuitBreaker.js");
+Object.defineProperty(exports, "CircuitBreaker", { enumerable: true, get: function () { return CircuitBreaker_js_1.CircuitBreaker; } });
+Object.defineProperty(exports, "circuitBreakerGroupByDomain", { enumerable: true, get: function () { return CircuitBreaker_js_1.groupByDomain; } });
+var CircuitBreakerMiddleware_js_1 = require("./src/CircuitBreakerMiddleware.js");
+Object.defineProperty(exports, "CircuitBreakerMiddleware", { enumerable: true, get: function () { return CircuitBreakerMiddleware_js_1.CircuitBreakerMiddleware; } });
+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; } });

package/script/src/CircuitBreaker.js

@@ -0,0 +1,361 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreaker = void 0;
+exports.groupByDomain = groupByDomain;
+/**
+ * Circuit breaker for preventing cascading failures.
+ *
+ * When a service starts failing (returning 5xx errors, timing out, etc.),
+ * the circuit breaker "opens" and blocks further requests for a period,
+ * allowing the service time to recover.
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 5,    // Open after 5 failures
+ *   openDurationMs: 30000,  // Stay open for 30 seconds
+ *   successThreshold: 2,    // Close after 2 successes in HALF_OPEN
+ * });
+ *
+ * // Before making a request
+ * if (!breaker.isAllowed(url)) {
+ *   // Circuit is open, don't make request
+ *   return;
+ * }
+ *
+ * // After getting a response
+ * if (response.status >= 500) {
+ *   breaker.recordFailure(url);
+ * } else {
+ *   breaker.recordSuccess(url);
+ * }
+ * ```
+ */
+class CircuitBreaker {
+    #buckets = new Map();
+    #groupOptions = new Map();
+    #options;
+    #onOpen;
+    #onClose;
+    #onHalfOpen;
+    constructor(options) {
+        this.#options = {
+            failureThreshold: options?.failureThreshold ?? 5,
+            failureWindowMs: options?.failureWindowMs ?? 60000,
+            openDurationMs: options?.openDurationMs ?? 30000,
+            successThreshold: options?.successThreshold ?? 2,
+            halfOpenMaxAttempts: options?.halfOpenMaxAttempts ?? 1,
+            getGroupFunc: options?.getGroupFunc ?? (() => "global"),
+            onStateChange: options?.onStateChange,
+        };
+        this.#onOpen = options?.onOpen;
+        this.#onClose = options?.onClose;
+        this.#onHalfOpen = options?.onHalfOpen;
+        // Initialize per-group options
+        if (options?.groups) {
+            for (const [group, groupOpts] of Object.entries(options.groups)) {
+                this.#groupOptions.set(group, groupOpts);
+            }
+        }
+    }
+    /**
+     * Gets the effective options for a group.
+     */
+    #getOptions(group) {
+        const groupOpts = this.#groupOptions.get(group);
+        return {
+            failureThreshold: groupOpts?.failureThreshold ??
+                this.#options.failureThreshold,
+            failureWindowMs: groupOpts?.failureWindowMs ??
+                this.#options.failureWindowMs,
+            openDurationMs: groupOpts?.openDurationMs ?? this.#options.openDurationMs,
+            successThreshold: groupOpts?.successThreshold ??
+                this.#options.successThreshold,
+            halfOpenMaxAttempts: groupOpts?.halfOpenMaxAttempts ??
+                this.#options.halfOpenMaxAttempts,
+            onStateChange: groupOpts?.onStateChange ?? this.#options.onStateChange,
+        };
+    }
+    /**
+     * Gets or creates a bucket for the given group.
+     */
+    #getBucket(group) {
+        let bucket = this.#buckets.get(group);
+        if (!bucket) {
+            bucket = {
+                state: "CLOSED",
+                failures: [],
+                successCount: 0,
+                openedAt: null,
+                halfOpenAttempts: 0,
+            };
+            this.#buckets.set(group, bucket);
+        }
+        return bucket;
+    }
+    /**
+     * Transitions the circuit to a new state.
+     */
+    #transitionTo(group, bucket, newState) {
+        const oldState = bucket.state;
+        if (oldState === newState)
+            return;
+        bucket.state = newState;
+        // Reset state-specific counters
+        if (newState === "OPEN") {
+            bucket.openedAt = Date.now();
+            bucket.successCount = 0;
+            bucket.halfOpenAttempts = 0;
+        }
+        else if (newState === "HALF_OPEN") {
+            bucket.successCount = 0;
+            bucket.halfOpenAttempts = 0;
+        }
+        else if (newState === "CLOSED") {
+            bucket.failures = [];
+            bucket.openedAt = null;
+            bucket.successCount = 0;
+            bucket.halfOpenAttempts = 0;
+        }
+        // Trigger callbacks
+        const opts = this.#getOptions(group);
+        opts.onStateChange?.(oldState, newState);
+        if (newState === "OPEN") {
+            this.#onOpen?.(group);
+        }
+        else if (newState === "CLOSED") {
+            this.#onClose?.(group);
+        }
+        else if (newState === "HALF_OPEN") {
+            this.#onHalfOpen?.(group);
+        }
+    }
+    /**
+     * Cleans up old failures outside the time window.
+     */
+    #cleanupFailures(bucket, windowMs) {
+        const cutoff = Date.now() - windowMs;
+        bucket.failures = bucket.failures.filter((t) => t > cutoff);
+    }
+    /**
+     * Checks if a request to the given URL is allowed.
+     * Call this before making a request.
+     *
+     * @param url - The URL being requested
+     * @returns true if the request is allowed, false if circuit is open
+     */
+    isAllowed(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#getBucket(group);
+        const opts = this.#getOptions(group);
+        switch (bucket.state) {
+            case "CLOSED":
+                return true;
+            case "OPEN": {
+                // Check if enough time has passed to try HALF_OPEN
+                const elapsed = Date.now() - (bucket.openedAt ?? 0);
+                if (elapsed >= opts.openDurationMs) {
+                    this.#transitionTo(group, bucket, "HALF_OPEN");
+                    // Fall through to HALF_OPEN logic
+                }
+                else {
+                    return false;
+                }
+            }
+            // falls through
+            case "HALF_OPEN": {
+                // Allow limited requests in HALF_OPEN
+                if (bucket.halfOpenAttempts < opts.halfOpenMaxAttempts) {
+                    bucket.halfOpenAttempts++;
+                    return true;
+                }
+                return false;
+            }
+        }
+    }
+    /**
+     * Records a successful response.
+     * Call this after receiving a successful (non-failure) response.
+     *
+     * @param url - The URL that was requested
+     */
+    recordSuccess(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#getBucket(group);
+        const opts = this.#getOptions(group);
+        switch (bucket.state) {
+            case "CLOSED":
+                // Success in CLOSED state - nothing special to do
+                // Optionally could reset failure count, but we use time-based cleanup
+                break;
+            case "HALF_OPEN":
+                // Decrement in-flight counter
+                bucket.halfOpenAttempts = Math.max(0, bucket.halfOpenAttempts - 1);
+                bucket.successCount++;
+                // Check if we've had enough successes to close
+                if (bucket.successCount >= opts.successThreshold) {
+                    this.#transitionTo(group, bucket, "CLOSED");
+                }
+                break;
+            case "OPEN":
+                // Shouldn't happen - requests blocked in OPEN
+                break;
+        }
+    }
+    /**
+     * Records a failed response.
+     * Call this after receiving a failure response (5xx, timeout, network error).
+     *
+     * @param url - The URL that was requested
+     */
+    recordFailure(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#getBucket(group);
+        const opts = this.#getOptions(group);
+        switch (bucket.state) {
+            case "CLOSED":
+                // Clean up old failures
+                this.#cleanupFailures(bucket, opts.failureWindowMs);
+                // Record new failure
+                bucket.failures.push(Date.now());
+                // Check if we've hit the threshold
+                if (bucket.failures.length >= opts.failureThreshold) {
+                    this.#transitionTo(group, bucket, "OPEN");
+                }
+                break;
+            case "HALF_OPEN":
+                // Failure in HALF_OPEN - back to OPEN
+                bucket.halfOpenAttempts = Math.max(0, bucket.halfOpenAttempts - 1);
+                this.#transitionTo(group, bucket, "OPEN");
+                break;
+            case "OPEN":
+                // Shouldn't happen - requests blocked in OPEN
+                break;
+        }
+    }
+    /**
+     * Gets the current state of the circuit for a URL.
+     *
+     * @param url - The URL to check
+     * @returns The current circuit state
+     */
+    getState(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#buckets.get(group);
+        if (!bucket)
+            return "CLOSED";
+        // Check for automatic transition to HALF_OPEN
+        if (bucket.state === "OPEN") {
+            const opts = this.#getOptions(group);
+            const elapsed = Date.now() - (bucket.openedAt ?? 0);
+            if (elapsed >= opts.openDurationMs) {
+                return "HALF_OPEN";
+            }
+        }
+        return bucket.state;
+    }
+    /**
+     * Gets the number of failures in the current window for a URL.
+     *
+     * @param url - The URL to check
+     * @returns The failure count
+     */
+    getFailureCount(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#buckets.get(group);
+        if (!bucket)
+            return 0;
+        const opts = this.#getOptions(group);
+        this.#cleanupFailures(bucket, opts.failureWindowMs);
+        return bucket.failures.length;
+    }
+    /**
+     * Gets the time since the circuit opened for a URL.
+     *
+     * @param url - The URL to check
+     * @returns Time in ms since circuit opened, or null if not open
+     */
+    getTimeSinceOpen(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#buckets.get(group);
+        if (!bucket || bucket.openedAt === null)
+            return null;
+        return Date.now() - bucket.openedAt;
+    }
+    /**
+     * Gets the time remaining before the circuit transitions to HALF_OPEN.
+     *
+     * @param url - The URL to check
+     * @returns Time in ms until HALF_OPEN, or null if not applicable
+     */
+    getTimeUntilHalfOpen(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#buckets.get(group);
+        if (!bucket || bucket.state !== "OPEN" || bucket.openedAt === null) {
+            return null;
+        }
+        const opts = this.#getOptions(group);
+        const elapsed = Date.now() - bucket.openedAt;
+        const remaining = opts.openDurationMs - elapsed;
+        return remaining > 0 ? remaining : 0;
+    }
+    /**
+     * Manually resets (closes) the circuit for a URL or all circuits.
+     *
+     * @param url - Optional URL to reset. If omitted, resets all circuits.
+     */
+    reset(url) {
+        if (url !== undefined) {
+            const group = this.#options.getGroupFunc(url);
+            const bucket = this.#buckets.get(group);
+            if (bucket) {
+                this.#transitionTo(group, bucket, "CLOSED");
+            }
+        }
+        else {
+            // Reset all
+            for (const [group, bucket] of this.#buckets) {
+                this.#transitionTo(group, bucket, "CLOSED");
+            }
+        }
+    }
+    /**
+     * Manually trips (opens) the circuit for a URL.
+     *
+     * @param url - The URL to trip the circuit for
+     */
+    trip(url) {
+        const group = this.#options.getGroupFunc(url);
+        const bucket = this.#getBucket(group);
+        this.#transitionTo(group, bucket, "OPEN");
+    }
+    /**
+     * Sets options for a specific group.
+     *
+     * @param group - The group name
+     * @param options - The options to set
+     */
+    setGroupOptions(group, options) {
+        this.#groupOptions.set(group, options);
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;
+/**
+ * Groups URLs by their domain (hostname).
+ * Useful for per-domain circuit breakers.
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   getGroupFunc: groupByDomain,
+ * });
+ * ```
+ */
+function groupByDomain(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return "unknown";
+    }
+}