@foundatiofx/fetchclient 1.0.1 → 1.1.1

package/esm/src/FetchClientCache.js

@@ -3,19 +3,36 @@
  */
 export 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.
@@ -23,12 +40,14 @@ export 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();
@@ -40,7 +59,12 @@ export 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.
@@ -49,15 +73,56 @@ export 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.
@@ -78,6 +143,7 @@ export class FetchClientCache {
      */
     clear() {
         this.cache.clear();
+        this.tagIndex.clear();
     }
     getHash(key) {
         if (key instanceof Array) {
@@ -85,4 +151,15 @@ export 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);
+                }
+            }
+        }
+    }
 }

package/esm/src/FetchClientProvider.js

@@ -4,6 +4,8 @@ import { FetchClientCache } from "./FetchClientCache.js";
 import { ObjectEvent } from "./ObjectEvent.js";
 import { RateLimitMiddleware, } from "./RateLimitMiddleware.js";
 import { groupByDomain } from "./RateLimiter.js";
+import { CircuitBreakerMiddleware, } from "./CircuitBreakerMiddleware.js";
+import { groupByDomain as circuitBreakerGroupByDomain, } from "./CircuitBreaker.js";
 /**
  * Represents a provider for creating instances of the FetchClient class with shared default options and cache.
  */
@@ -12,6 +14,9 @@ export class FetchClientProvider {
     #fetch;
     #cache;
     #rateLimitMiddleware;
+    #rateLimitMiddlewareFunc;
+    #circuitBreakerMiddleware;
+    #circuitBreakerMiddlewareFunc;
     #counter = new Counter();
     #onLoading = new ObjectEvent();
     /**
@@ -168,7 +173,8 @@ export class FetchClientProvider {
      */
     useRateLimit(options) {
         this.#rateLimitMiddleware = new 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.
@@ -179,7 +185,8 @@ export class FetchClientProvider {
             ...options,
             getGroupFunc: groupByDomain,
         });
-        this.useMiddleware(this.#rateLimitMiddleware.middleware());
+        this.#rateLimitMiddlewareFunc = this.#rateLimitMiddleware.middleware();
+        this.useMiddleware(this.#rateLimitMiddlewareFunc);
     }
     /**
      * Gets the rate limiter instance used for rate limiting.
@@ -192,8 +199,56 @@ export 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));
+        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(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({
+            ...options,
+            getGroupFunc: circuitBreakerGroupByDomain,
+        });
+        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);
+        }
     }
 }
 const provider = new FetchClientProvider();

package/esm/src/mocks/MockHistory.js

@@ -0,0 +1,63 @@
+/**
+ * Implementation of MockHistory that tracks recorded requests.
+ */
+export 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 = [];
+    }
+}

package/esm/src/mocks/MockRegistry.js

@@ -0,0 +1,267 @@
+import { MockHistoryImpl } from "./MockHistory.js";
+import { MockResponseBuilder } from "./MockResponseBuilder.js";
+/**
+ * A registry for defining mock responses that can be installed on a
+ * FetchClient or FetchClientProvider, or used as a standalone fetch replacement.
+ *
+ * @example Install on FetchClientProvider
+ * ```typescript
+ * const mocks = new MockRegistry();
+ * mocks.onGet('/api/users').reply(200, [{ id: 1 }]);
+ *
+ * const provider = new FetchClientProvider();
+ * mocks.install(provider);
+ *
+ * const client = provider.getFetchClient();
+ * const response = await client.getJSON('/api/users');
+ * ```
+ *
+ * @example Use as standalone fetch replacement
+ * ```typescript
+ * const mocks = new MockRegistry();
+ * mocks.onGet('/api/users').reply(200, [{ id: 1 }]);
+ *
+ * // Use directly as fetch
+ * const response = await mocks.fetch('/api/users');
+ *
+ * // Or pass to any library expecting a fetch function
+ * const client = new SomeHttpClient({ fetch: mocks.fetch });
+ * ```
+ */
+export class MockRegistry {
+    #mocks = [];
+    #history = new MockHistoryImpl();
+    #target = null;
+    #originalFetch = undefined;
+    /**
+     * Creates a mock for GET requests matching the given URL.
+     * @param url - URL string or RegExp to match
+     */
+    onGet(url) {
+        return this.#addMock("GET", url);
+    }
+    /**
+     * Creates a mock for POST requests matching the given URL.
+     * @param url - URL string or RegExp to match
+     */
+    onPost(url) {
+        return this.#addMock("POST", url);
+    }
+    /**
+     * Creates a mock for PUT requests matching the given URL.
+     * @param url - URL string or RegExp to match
+     */
+    onPut(url) {
+        return this.#addMock("PUT", url);
+    }
+    /**
+     * Creates a mock for PATCH requests matching the given URL.
+     * @param url - URL string or RegExp to match
+     */
+    onPatch(url) {
+        return this.#addMock("PATCH", url);
+    }
+    /**
+     * Creates a mock for DELETE requests matching the given URL.
+     * @param url - URL string or RegExp to match
+     */
+    onDelete(url) {
+        return this.#addMock("DELETE", url);
+    }
+    /**
+     * Creates a mock for any HTTP method matching the given URL.
+     * @param url - URL string or RegExp to match
+     */
+    onAny(url) {
+        return this.#addMock(null, url);
+    }
+    #addMock(method, url) {
+        const mock = {
+            method,
+            url,
+            status: 200,
+            once: false,
+            passthrough: false,
+            timeout: false,
+        };
+        this.#mocks.push(mock);
+        return new MockResponseBuilder(mock, this);
+    }
+    /**
+     * Installs the mock registry on a FetchClient or FetchClientProvider.
+     * Replaces the fetch implementation to intercept requests.
+     *
+     * @param target - The FetchClient or FetchClientProvider to install on
+     * @throws Error if already installed on another target
+     */
+    install(target) {
+        if (this.#target) {
+            throw new Error("MockRegistry is already installed. Call restore() first.");
+        }
+        // If target is FetchClient, use its provider
+        const provider = "provider" in target && typeof target.provider !== "undefined"
+            ? target.provider
+            : target;
+        this.#target = provider;
+        this.#originalFetch = provider.fetch;
+        // Replace fetch with our mock handler
+        provider.fetch = ((input, init) => {
+            return this.#handleRequest(input, init);
+        });
+    }
+    /**
+     * Restores the original fetch implementation.
+     */
+    restore() {
+        if (!this.#target)
+            return;
+        this.#target.fetch = this.#originalFetch;
+        this.#target = null;
+        this.#originalFetch = undefined;
+    }
+    async #handleRequest(input, init) {
+        const signal = init?.signal;
+        // Check if already aborted
+        if (signal?.aborted) {
+            throw signal.reason;
+        }
+        const request = new Request(input, init);
+        this.#history.record(request);
+        const mock = this.#match(request);
+        if (!mock) {
+            // No mock found - call original fetch or global fetch
+            if (this.#originalFetch) {
+                return this.#originalFetch(input, init);
+            }
+            return fetch(input, init);
+        }
+        if (mock.passthrough) {
+            if (this.#originalFetch) {
+                return this.#originalFetch(input, init);
+            }
+            return fetch(input, init);
+        }
+        if (mock.delay) {
+            await this.#delayWithAbort(mock.delay, signal);
+        }
+        // Check again after delay
+        if (signal?.aborted) {
+            throw signal.reason;
+        }
+        if (mock.networkError) {
+            throw new TypeError(mock.networkError);
+        }
+        if (mock.timeout) {
+            throw new DOMException("The operation was aborted.", "TimeoutError");
+        }
+        // Build mock response
+        const headers = new Headers(mock.headers);
+        if (mock.data !== undefined && !headers.has("Content-Type")) {
+            headers.set("Content-Type", "application/json");
+        }
+        return new Response(mock.data !== undefined ? JSON.stringify(mock.data) : null, { status: mock.status, headers });
+    }
+    /**
+     * Delay that respects abort signals.
+     */
+    #delayWithAbort(ms, signal) {
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(resolve, ms);
+            if (signal) {
+                const abortHandler = () => {
+                    clearTimeout(timeoutId);
+                    reject(signal.reason);
+                };
+                if (signal.aborted) {
+                    clearTimeout(timeoutId);
+                    reject(signal.reason);
+                    return;
+                }
+                signal.addEventListener("abort", abortHandler, { once: true });
+            }
+        });
+    }
+    #match(request) {
+        for (let i = 0; i < this.#mocks.length; i++) {
+            const mock = this.#mocks[i];
+            // Check method
+            if (mock.method && mock.method !== request.method)
+                continue;
+            // Check URL
+            const url = request.url;
+            if (mock.url instanceof RegExp) {
+                if (!mock.url.test(url))
+                    continue;
+            }
+            else {
+                // Match if URL ends with the pattern or contains it
+                if (!url.endsWith(mock.url) && !url.includes(mock.url))
+                    continue;
+            }
+            // Check headers if specified
+            if (mock.headerMatchers) {
+                let headersMatch = true;
+                for (const [key, value] of Object.entries(mock.headerMatchers)) {
+                    if (request.headers.get(key) !== value) {
+                        headersMatch = false;
+                        break;
+                    }
+                }
+                if (!headersMatch)
+                    continue;
+            }
+            // Found a match - remove if once
+            if (mock.once) {
+                this.#mocks.splice(i, 1);
+            }
+            return mock;
+        }
+        return null;
+    }
+    /**
+     * Gets the recorded request history.
+     */
+    get history() {
+        return this.#history;
+    }
+    /**
+     * Gets the mock fetch function for standalone use.
+     * This allows using MockRegistry with any code that accepts a fetch function.
+     *
+     * @example
+     * ```typescript
+     * const mocks = new MockRegistry();
+     * mocks.onGet('/api/data').reply(200, { value: 42 });
+     *
+     * // Use directly
+     * const response = await mocks.fetch('/api/data');
+     *
+     * // Or pass to other libraries
+     * const client = new SomeClient({ fetch: mocks.fetch });
+     * ```
+     */
+    get fetch() {
+        return ((input, init) => {
+            return this.#handleRequest(input, init);
+        });
+    }
+    /**
+     * Clears all mocks and history.
+     */
+    reset() {
+        this.resetMocks();
+        this.resetHistory();
+    }
+    /**
+     * Clears all mocks but keeps history.
+     */
+    resetMocks() {
+        this.#mocks = [];
+    }
+    /**
+     * Clears history but keeps mocks.
+     */
+    resetHistory() {
+        this.#history.clear();
+    }
+}

package/esm/src/mocks/MockResponseBuilder.js

@@ -0,0 +1,88 @@
+/**
+ * Fluent builder for configuring mock responses.
+ * @template T The type of the registry (for chaining)
+ */
+export class MockResponseBuilder {
+    #mock;
+    #registry;
+    constructor(mock, registry) {
+        this.#mock = mock;
+        this.#registry = registry;
+    }
+    /**
+     * Sets the response status, data, and optional headers.
+     * @param status - HTTP status code
+     * @param data - Response data (will be JSON stringified)
+     * @param headers - Optional response headers
+     * @returns The registry for chaining
+     */
+    reply(status, data, headers) {
+        this.#mock.status = status;
+        this.#mock.data = data;
+        this.#mock.headers = headers;
+        return this.#registry;
+    }
+    /**
+     * Sets a one-time response that is removed after the first match.
+     * @param status - HTTP status code
+     * @param data - Response data (will be JSON stringified)
+     * @param headers - Optional response headers
+     * @returns The registry for chaining
+     */
+    replyOnce(status, data, headers) {
+        this.#mock.once = true;
+        return this.reply(status, data, headers);
+    }
+    /**
+     * Simulates a network error by throwing a TypeError.
+     * @param message - Error message (default: "Network error")
+     * @returns The registry for chaining
+     */
+    networkError(message = "Network error") {
+        this.#mock.networkError = message;
+        return this.#registry;
+    }
+    /**
+     * Simulates a timeout by throwing a TimeoutError.
+     * @returns The registry for chaining
+     */
+    timeout() {
+        this.#mock.timeout = true;
+        return this.#registry;
+    }
+    /**
+     * Passes the request through to the real fetch implementation.
+     * @returns The registry for chaining
+     */
+    passthrough() {
+        this.#mock.passthrough = true;
+        return this.#registry;
+    }
+    /**
+     * Adds header matching requirements for this mock.
+     * @param headers - Headers that must be present and match
+     * @returns This builder for further configuration
+     */
+    withHeaders(headers) {
+        this.#mock.headerMatchers = headers;
+        return this;
+    }
+    /**
+     * Adds body matching requirements for this mock.
+     * @param body - Exact body to match, or a predicate function
+     * @returns This builder for further configuration
+     */
+    withBody(body) {
+        this.#mock.bodyMatcher = body;
+        return this;
+    }
+    /**
+     * Adds a delay before returning the response.
+     * @param ms - Delay in milliseconds
+     * @returns This builder for further configuration
+     */
+    delay(ms) {
+        this.#mock.delay = ms;
+        return this;
+    }
+}

package/esm/src/mocks/mod.js

@@ -0,0 +1,24 @@
+/**
+ * Mock utilities for testing FetchClient.
+ *
+ * @example
+ * ```typescript
+ * import { FetchClientProvider } from "@foundatiofx/fetchclient";
+ * import { MockRegistry } from "@foundatiofx/fetchclient/mocks";
+ *
+ * const mocks = new MockRegistry();
+ * mocks.onGet('/api/users').reply(200, [{ id: 1 }]);
+ *
+ * const provider = new FetchClientProvider();
+ * mocks.install(provider);
+ *
+ * const client = provider.getFetchClient();
+ * const response = await client.getJSON('/api/users');
+ *
+ * mocks.restore();
+ * ```
+ *
+ * @module
+ */
+export { MockRegistry } from "./MockRegistry.js";
+export { MockResponseBuilder } from "./MockResponseBuilder.js";

package/esm/src/mocks/types.js

@@ -0,0 +1 @@
+export {};