@foundatiofx/fetchclient 1.0.1 → 1.1.0

package/script/src/CircuitBreakerMiddleware.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreakerMiddleware = exports.CircuitOpenError = void 0;
+exports.createCircuitBreakerMiddleware = createCircuitBreakerMiddleware;
+exports.createPerDomainCircuitBreakerMiddleware = createPerDomainCircuitBreakerMiddleware;
+const CircuitBreaker_js_1 = require("./CircuitBreaker.js");
+const ProblemDetails_js_1 = require("./ProblemDetails.js");
+/**
+ * Error thrown when a request is blocked due to an open circuit.
+ */
+class CircuitOpenError extends Error {
+    /** The group whose circuit is open */
+    group;
+    /** The current circuit state */
+    state;
+    /** When the circuit was opened (timestamp) */
+    openedAt;
+    /** Suggested retry time in seconds */
+    retryAfter;
+    constructor(group, state, openedAt, retryAfter, message) {
+        super(message ?? `Circuit breaker is open for ${group}`);
+        this.name = "CircuitOpenError";
+        this.group = group;
+        this.state = state;
+        this.openedAt = openedAt;
+        this.retryAfter = retryAfter;
+    }
+}
+exports.CircuitOpenError = CircuitOpenError;
+/**
+ * Default function to determine if a response is a failure.
+ * Returns true for 5xx server errors and 429 rate limit responses.
+ */
+function defaultIsFailure(response) {
+    return response.status >= 500 || response.status === 429;
+}
+/**
+ * Middleware that implements the circuit breaker pattern.
+ *
+ * When a service starts failing (5xx errors, timeouts, network errors),
+ * the circuit breaker opens and blocks further requests for a period,
+ * returning 503 Service Unavailable immediately without hitting the API.
+ *
+ * @example
+ * ```typescript
+ * const middleware = new CircuitBreakerMiddleware({
+ *   failureThreshold: 5,
+ *   openDurationMs: 30000,
+ * });
+ *
+ * provider.useMiddleware(middleware.middleware());
+ * ```
+ */
+class CircuitBreakerMiddleware {
+    #circuitBreaker;
+    #throwOnOpen;
+    #errorMessage;
+    #isFailure;
+    #getGroupFunc;
+    #openDurationMs;
+    constructor(options) {
+        this.#circuitBreaker = new CircuitBreaker_js_1.CircuitBreaker(options);
+        this.#throwOnOpen = options?.throwOnOpen ?? false;
+        this.#errorMessage = options?.errorMessage;
+        this.#isFailure = options?.isFailure ?? defaultIsFailure;
+        this.#getGroupFunc = options?.getGroupFunc ?? (() => "global");
+        this.#openDurationMs = options?.openDurationMs ?? 30000;
+    }
+    /**
+     * Gets the underlying circuit breaker instance.
+     */
+    get circuitBreaker() {
+        return this.#circuitBreaker;
+    }
+    /**
+     * Creates the middleware function for use with FetchClient.
+     *
+     * @returns The middleware function
+     */
+    middleware() {
+        return async (ctx, next) => {
+            const url = ctx.request.url;
+            const group = this.#getGroupFunc(url);
+            // PRE-REQUEST: Check if circuit allows the request
+            if (!this.#circuitBreaker.isAllowed(url)) {
+                const timeSinceOpen = this.#circuitBreaker.getTimeSinceOpen(url) ?? 0;
+                const retryAfterMs = Math.max(0, this.#openDurationMs - timeSinceOpen);
+                const retryAfterSeconds = Math.ceil(retryAfterMs / 1000);
+                if (this.#throwOnOpen) {
+                    throw new CircuitOpenError(group, this.#circuitBreaker.getState(url), Date.now() - timeSinceOpen, retryAfterSeconds, this.#errorMessage);
+                }
+                // Return synthetic 503 response
+                const problem = new ProblemDetails_js_1.ProblemDetails();
+                problem.status = 503;
+                problem.title = "Service Unavailable";
+                problem.detail = this.#errorMessage ??
+                    `Circuit breaker is open for ${group}. Service may be experiencing issues.`;
+                const headers = new Headers({
+                    "Content-Type": "application/problem+json",
+                    "Retry-After": String(retryAfterSeconds),
+                });
+                const response = new Response(JSON.stringify(problem), {
+                    status: 503,
+                    statusText: "Service Unavailable",
+                    headers,
+                });
+                // Attach problem details like FetchClient does
+                Object.assign(response, { problem, data: null });
+                ctx.response = response;
+                return;
+            }
+            // EXECUTE REQUEST
+            let isNetworkError = false;
+            try {
+                await next();
+            }
+            catch (error) {
+                // Network errors count as failures
+                isNetworkError = true;
+                this.#circuitBreaker.recordFailure(url);
+                throw error;
+            }
+            // POST-RESPONSE: Record result
+            if (!isNetworkError && ctx.response) {
+                if (this.#isFailure(ctx.response)) {
+                    this.#circuitBreaker.recordFailure(url);
+                }
+                else {
+                    this.#circuitBreaker.recordSuccess(url);
+                }
+            }
+        };
+    }
+}
+exports.CircuitBreakerMiddleware = CircuitBreakerMiddleware;
+/**
+ * Creates a circuit breaker middleware with the given options.
+ *
+ * @param options - Circuit breaker configuration
+ * @returns The middleware function
+ *
+ * @example
+ * ```typescript
+ * provider.useMiddleware(createCircuitBreakerMiddleware({
+ *   failureThreshold: 5,
+ *   openDurationMs: 30000,
+ * }));
+ * ```
+ */
+function createCircuitBreakerMiddleware(options) {
+    const middleware = new CircuitBreakerMiddleware(options);
+    return middleware.middleware();
+}
+/**
+ * Creates a per-domain circuit breaker middleware.
+ * Each domain gets its own circuit breaker.
+ *
+ * @param options - Circuit breaker configuration
+ * @returns The middleware function
+ *
+ * @example
+ * ```typescript
+ * provider.useMiddleware(createPerDomainCircuitBreakerMiddleware({
+ *   failureThreshold: 5,
+ *   openDurationMs: 30000,
+ * }));
+ * ```
+ */
+function createPerDomainCircuitBreakerMiddleware(options) {
+    return createCircuitBreakerMiddleware({
+        ...options,
+        getGroupFunc: CircuitBreaker_js_1.groupByDomain,
+    });
+}

package/script/src/DefaultHelpers.js

@@ -15,6 +15,8 @@ exports.useMiddleware = useMiddleware;
 exports.setRequestOptions = setRequestOptions;
 exports.useRateLimit = useRateLimit;
 exports.usePerDomainRateLimit = usePerDomainRateLimit;
+exports.useCircuitBreaker = useCircuitBreaker;
+exports.usePerDomainCircuitBreaker = usePerDomainCircuitBreaker;
 const FetchClientProvider_js_1 = require("./FetchClientProvider.js");
 let getCurrentProviderFunc = () => null;
 /**
@@ -147,3 +149,19 @@ function useRateLimit(options) {
 function usePerDomainRateLimit(options) {
     getCurrentProvider().usePerDomainRateLimit(options);
 }
+/**
+ * Enables circuit breaker for any FetchClient instances created by the current provider.
+ * The circuit breaker monitors failures and blocks requests when a service is failing.
+ * @param options - The circuit breaker configuration options.
+ */
+function useCircuitBreaker(options) {
+    getCurrentProvider().useCircuitBreaker(options);
+}
+/**
+ * Enables per-domain circuit breaker for any FetchClient instances created by the current provider.
+ * Each domain gets its own circuit breaker, so failures on one domain don't affect others.
+ * @param options - The circuit breaker configuration options.
+ */
+function usePerDomainCircuitBreaker(options) {
+    getCurrentProvider().usePerDomainCircuitBreaker(options);
+}

package/script/src/FetchClient.js

@@ -298,7 +298,7 @@ class FetchClient {
                     links: (0, LinkHeader_js_1.parseLinkHeader)(response.headers.get("Link")) || {},
                 };
                 if (getOptions?.cacheKey) {
-                    this.cache.set(getOptions.cacheKey, ctx.response, getOptions.cacheDuration);
+                    this.cache.set(getOptions.cacheKey, ctx.response, getOptions.cacheDuration, getOptions.cacheTags);
                 }
             }
             catch (error) {

package/script/src/FetchClientCache.js

@@ -6,19 +6,36 @@ exports.FetchClientCache = void 0;
  */
 class FetchClientCache {
     cache = new Map();
+    tagIndex = new Map();
     /**
      * Sets a response in the cache with the specified key.
      * @param key - The cache key.
      * @param response - The response to be cached.
      * @param cacheDuration - The duration for which the response should be cached (in milliseconds).
+     * @param tags - Optional tags for grouping and invalidating cache entries.
      */
-    set(key, response, cacheDuration) {
-        this.cache.set(this.getHash(key), {
+    set(key, response, cacheDuration, tags) {
+        const hash = this.getHash(key);
+        const normalizedTags = tags ?? [];
+        // Remove old tag associations if entry exists
+        const existingEntry = this.cache.get(hash);
+        if (existingEntry) {
+            this.removeTagAssociations(hash, existingEntry.tags);
+        }
+        this.cache.set(hash, {
             key,
+            tags: normalizedTags,
             lastAccess: new Date(),
             expires: new Date(Date.now() + (cacheDuration ?? 60000)),
             response,
         });
+        // Add new tag associations
+        for (const tag of normalizedTags) {
+            if (!this.tagIndex.has(tag)) {
+                this.tagIndex.set(tag, new Set());
+            }
+            this.tagIndex.get(tag).add(hash);
+        }
     }
     /**
      * Retrieves a response from the cache with the specified key.
@@ -26,12 +43,14 @@ class FetchClientCache {
      * @returns The cached response, or null if the response is not found or has expired.
      */
     get(key) {
-        const cacheEntry = this.cache.get(this.getHash(key));
+        const hash = this.getHash(key);
+        const cacheEntry = this.cache.get(hash);
         if (!cacheEntry) {
             return null;
         }
         if (cacheEntry.expires < new Date()) {
-            this.cache.delete(this.getHash(key));
+            this.removeTagAssociations(hash, cacheEntry.tags);
+            this.cache.delete(hash);
             return null;
         }
         cacheEntry.lastAccess = new Date();
@@ -43,7 +62,12 @@ class FetchClientCache {
      * @returns True if the response was successfully deleted, false otherwise.
      */
     delete(key) {
-        return this.cache.delete(this.getHash(key));
+        const hash = this.getHash(key);
+        const entry = this.cache.get(hash);
+        if (entry) {
+            this.removeTagAssociations(hash, entry.tags);
+        }
+        return this.cache.delete(hash);
     }
     /**
      * Deletes all responses from the cache that have keys beginning with the specified key.
@@ -52,15 +76,56 @@ class FetchClientCache {
      */
     deleteAll(prefix) {
         let count = 0;
-        for (const key of this.cache.keys()) {
-            if (key.startsWith(this.getHash(prefix))) {
-                if (this.cache.delete(key)) {
+        const prefixHash = this.getHash(prefix);
+        for (const [hash, entry] of this.cache.entries()) {
+            if (hash.startsWith(prefixHash)) {
+                this.removeTagAssociations(hash, entry.tags);
+                if (this.cache.delete(hash)) {
+                    count++;
+                }
+            }
+        }
+        return count;
+    }
+    /**
+     * Deletes all responses from the cache that have the specified tag.
+     * @param tag - The cache tag.
+     * @returns The number of responses that were deleted.
+     */
+    deleteByTag(tag) {
+        const hashes = this.tagIndex.get(tag);
+        if (!hashes) {
+            return 0;
+        }
+        let count = 0;
+        for (const hash of hashes) {
+            const entry = this.cache.get(hash);
+            if (entry) {
+                // Remove this entry's associations from all its tags
+                this.removeTagAssociations(hash, entry.tags);
+                if (this.cache.delete(hash)) {
                     count++;
                 }
             }
         }
         return count;
     }
+    /**
+     * Gets all tags currently in use in the cache.
+     * @returns An array of all cache tags.
+     */
+    getTags() {
+        return Array.from(this.tagIndex.keys()).filter((tag) => this.tagIndex.get(tag).size > 0);
+    }
+    /**
+     * Gets the tags associated with a cache entry.
+     * @param key - The cache key.
+     * @returns The tags associated with the entry, or an empty array if not found.
+     */
+    getEntryTags(key) {
+        const entry = this.cache.get(this.getHash(key));
+        return entry?.tags ?? [];
+    }
     /**
      * Checks if a response exists in the cache with the specified key.
      * @param key - The cache key.
@@ -81,6 +146,7 @@ class FetchClientCache {
      */
     clear() {
         this.cache.clear();
+        this.tagIndex.clear();
     }
     getHash(key) {
         if (key instanceof Array) {
@@ -88,5 +154,16 @@ class FetchClientCache {
         }
         return key;
     }
+    removeTagAssociations(hash, tags) {
+        for (const tag of tags) {
+            const hashes = this.tagIndex.get(tag);
+            if (hashes) {
+                hashes.delete(hash);
+                if (hashes.size === 0) {
+                    this.tagIndex.delete(tag);
+                }
+            }
+        }
+    }
 }
 exports.FetchClientCache = FetchClientCache;

package/script/src/FetchClientProvider.js

@@ -7,6 +7,8 @@ const FetchClientCache_js_1 = require("./FetchClientCache.js");
 const ObjectEvent_js_1 = require("./ObjectEvent.js");
 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");
 /**
  * Represents a provider for creating instances of the FetchClient class with shared default options and cache.
  */
@@ -15,6 +17,9 @@ class FetchClientProvider {
     #fetch;
     #cache;
     #rateLimitMiddleware;
+    #rateLimitMiddlewareFunc;
+    #circuitBreakerMiddleware;
+    #circuitBreakerMiddlewareFunc;
     #counter = new Counter_js_1.Counter();
     #onLoading = new ObjectEvent_js_1.ObjectEvent();
     /**
@@ -171,7 +176,8 @@ class FetchClientProvider {
      */
     useRateLimit(options) {
         this.#rateLimitMiddleware = new RateLimitMiddleware_js_1.RateLimitMiddleware(options);
-        this.useMiddleware(this.#rateLimitMiddleware.middleware());
+        this.#rateLimitMiddlewareFunc = this.#rateLimitMiddleware.middleware();
+        this.useMiddleware(this.#rateLimitMiddlewareFunc);
     }
     /**
      * Enables rate limiting for all FetchClient instances created by this provider.
@@ -182,7 +188,8 @@ class FetchClientProvider {
             ...options,
             getGroupFunc: RateLimiter_js_1.groupByDomain,
         });
-        this.useMiddleware(this.#rateLimitMiddleware.middleware());
+        this.#rateLimitMiddlewareFunc = this.#rateLimitMiddleware.middleware();
+        this.useMiddleware(this.#rateLimitMiddlewareFunc);
     }
     /**
      * Gets the rate limiter instance used for rate limiting.
@@ -195,8 +202,56 @@ class FetchClientProvider {
      * Removes the rate limiting middleware from all FetchClient instances created by this provider.
      */
     removeRateLimit() {
+        const middlewareFunc = this.#rateLimitMiddlewareFunc;
         this.#rateLimitMiddleware = undefined;
-        this.#options.middleware = this.#options.middleware?.filter((m) => !(m instanceof RateLimitMiddleware_js_1.RateLimitMiddleware));
+        this.#rateLimitMiddlewareFunc = undefined;
+        if (middlewareFunc) {
+            this.#options.middleware = this.#options.middleware?.filter((m) => m !== middlewareFunc);
+        }
+    }
+    /**
+     * Enables circuit breaker for all FetchClient instances created by this provider.
+     * The circuit breaker monitors failures and blocks requests when a service is failing,
+     * allowing time for recovery.
+     * @param options - The circuit breaker configuration options.
+     */
+    useCircuitBreaker(options) {
+        this.#circuitBreakerMiddleware = new CircuitBreakerMiddleware_js_1.CircuitBreakerMiddleware(options);
+        this.#circuitBreakerMiddlewareFunc = this.#circuitBreakerMiddleware
+            .middleware();
+        this.useMiddleware(this.#circuitBreakerMiddlewareFunc);
+    }
+    /**
+     * Enables per-domain circuit breaker for all FetchClient instances created by this provider.
+     * Each domain gets its own circuit breaker, so failures on one domain don't affect others.
+     * @param options - The circuit breaker configuration options.
+     */
+    usePerDomainCircuitBreaker(options) {
+        this.#circuitBreakerMiddleware = new CircuitBreakerMiddleware_js_1.CircuitBreakerMiddleware({
+            ...options,
+            getGroupFunc: CircuitBreaker_js_1.groupByDomain,
+        });
+        this.#circuitBreakerMiddlewareFunc = this.#circuitBreakerMiddleware
+            .middleware();
+        this.useMiddleware(this.#circuitBreakerMiddlewareFunc);
+    }
+    /**
+     * Gets the circuit breaker instance.
+     * @returns The circuit breaker instance, or undefined if not enabled.
+     */
+    get circuitBreaker() {
+        return this.#circuitBreakerMiddleware?.circuitBreaker;
+    }
+    /**
+     * Removes the circuit breaker middleware from all FetchClient instances created by this provider.
+     */
+    removeCircuitBreaker() {
+        const middlewareFunc = this.#circuitBreakerMiddlewareFunc;
+        this.#circuitBreakerMiddleware = undefined;
+        this.#circuitBreakerMiddlewareFunc = undefined;
+        if (middlewareFunc) {
+            this.#options.middleware = this.#options.middleware?.filter((m) => m !== middlewareFunc);
+        }
     }
 }
 exports.FetchClientProvider = FetchClientProvider;

package/script/src/mocks/MockHistory.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MockHistoryImpl = void 0;
+/**
+ * Implementation of MockHistory that tracks recorded requests.
+ */
+class MockHistoryImpl {
+    #get = [];
+    #post = [];
+    #put = [];
+    #patch = [];
+    #delete = [];
+    #all = [];
+    get get() {
+        return [...this.#get];
+    }
+    get post() {
+        return [...this.#post];
+    }
+    get put() {
+        return [...this.#put];
+    }
+    get patch() {
+        return [...this.#patch];
+    }
+    get delete() {
+        return [...this.#delete];
+    }
+    get all() {
+        return [...this.#all];
+    }
+    /**
+     * Records a request in the history.
+     */
+    record(request) {
+        this.#all.push(request);
+        switch (request.method.toUpperCase()) {
+            case "GET":
+                this.#get.push(request);
+                break;
+            case "POST":
+                this.#post.push(request);
+                break;
+            case "PUT":
+                this.#put.push(request);
+                break;
+            case "PATCH":
+                this.#patch.push(request);
+                break;
+            case "DELETE":
+                this.#delete.push(request);
+                break;
+        }
+    }
+    /**
+     * Clears all recorded history.
+     */
+    clear() {
+        this.#get = [];
+        this.#post = [];
+        this.#put = [];
+        this.#patch = [];
+        this.#delete = [];
+        this.#all = [];
+    }
+}
+exports.MockHistoryImpl = MockHistoryImpl;