@foundatiofx/fetchclient 1.0.1 → 1.1.1

package/types/src/CircuitBreaker.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Circuit breaker state.
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Circuit tripped, requests blocked
+ * - HALF_OPEN: Testing if service recovered
+ */
+export type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+/**
+ * Options for configuring a circuit breaker group.
+ */
+export interface GroupCircuitBreakerOptions {
+    /** Number of failures before opening the circuit (default: 5) */
+    failureThreshold?: number;
+    /** Time window in ms for counting failures (default: 60000) */
+    failureWindowMs?: number;
+    /** Time in ms to stay OPEN before trying HALF_OPEN (default: 30000) */
+    openDurationMs?: number;
+    /** Number of successes in HALF_OPEN to close circuit (default: 2) */
+    successThreshold?: number;
+    /** Max concurrent requests allowed in HALF_OPEN state (default: 1) */
+    halfOpenMaxAttempts?: number;
+    /** Callback when circuit state changes */
+    onStateChange?: (from: CircuitState, to: CircuitState) => void;
+}
+/**
+ * Options for configuring the circuit breaker.
+ */
+export interface CircuitBreakerOptions extends GroupCircuitBreakerOptions {
+    /** Function to determine which group a URL belongs to (default: returns "global") */
+    getGroupFunc?: (url: string) => string;
+    /** Per-group configuration overrides */
+    groups?: Record<string, GroupCircuitBreakerOptions>;
+    /** Callback when any circuit opens */
+    onOpen?: (group: string) => void;
+    /** Callback when any circuit closes */
+    onClose?: (group: string) => void;
+    /** Callback when any circuit enters half-open */
+    onHalfOpen?: (group: string) => void;
+}
+/**
+ * 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);
+ * }
+ * ```
+ */
+export declare class CircuitBreaker {
+    #private;
+    constructor(options?: CircuitBreakerOptions);
+    /**
+     * 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: string): boolean;
+    /**
+     * Records a successful response.
+     * Call this after receiving a successful (non-failure) response.
+     *
+     * @param url - The URL that was requested
+     */
+    recordSuccess(url: string): void;
+    /**
+     * Records a failed response.
+     * Call this after receiving a failure response (5xx, timeout, network error).
+     *
+     * @param url - The URL that was requested
+     */
+    recordFailure(url: string): void;
+    /**
+     * Gets the current state of the circuit for a URL.
+     *
+     * @param url - The URL to check
+     * @returns The current circuit state
+     */
+    getState(url: string): CircuitState;
+    /**
+     * Gets the number of failures in the current window for a URL.
+     *
+     * @param url - The URL to check
+     * @returns The failure count
+     */
+    getFailureCount(url: string): number;
+    /**
+     * 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: string): number | null;
+    /**
+     * 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: string): number | null;
+    /**
+     * Manually resets (closes) the circuit for a URL or all circuits.
+     *
+     * @param url - Optional URL to reset. If omitted, resets all circuits.
+     */
+    reset(url?: string): void;
+    /**
+     * Manually trips (opens) the circuit for a URL.
+     *
+     * @param url - The URL to trip the circuit for
+     */
+    trip(url: string): void;
+    /**
+     * Sets options for a specific group.
+     *
+     * @param group - The group name
+     * @param options - The options to set
+     */
+    setGroupOptions(group: string, options: GroupCircuitBreakerOptions): void;
+}
+/**
+ * Groups URLs by their domain (hostname).
+ * Useful for per-domain circuit breakers.
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   getGroupFunc: groupByDomain,
+ * });
+ * ```
+ */
+export declare function groupByDomain(url: string): string;
+//# sourceMappingURL=CircuitBreaker.d.ts.map

package/types/src/CircuitBreaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CircuitBreaker.d.ts","sourceRoot":"","sources":["../../src/src/CircuitBreaker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,0CAA0C;IAC1C,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,YAAY,KAAK,IAAI,CAAC;CAChE;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,0BAA0B;IACvE,qFAAqF;IACrF,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IACvC,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;IACpD,sCAAsC;IACtC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,uCAAuC;IACvC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,iDAAiD;IACjD,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,cAAc;;gBAQb,OAAO,CAAC,EAAE,qBAAqB;IAiH3C;;;;;;OAMG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAgC/B;;;;;OAKG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IA4BhC;;;;;OAKG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IA+BhC;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY;IAiBnC;;;;;OAKG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAUpC;;;;;OAKG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAO5C;;;;;OAKG;IACH,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAahD;;;;OAIG;IACH,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAezB;;;;OAIG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAMvB;;;;;OAKG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B,GAAG,IAAI;CAG1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMjD"}

package/types/src/CircuitBreakerMiddleware.d.ts

@@ -0,0 +1,93 @@
+import { CircuitBreaker, type CircuitBreakerOptions, type CircuitState } from "./CircuitBreaker.js";
+import type { FetchClientMiddleware } from "./FetchClientMiddleware.js";
+/**
+ * Options for the circuit breaker middleware.
+ */
+export interface CircuitBreakerMiddlewareOptions extends CircuitBreakerOptions {
+    /** Whether to throw CircuitOpenError instead of returning 503 (default: false) */
+    throwOnOpen?: boolean;
+    /** Custom error message when circuit is open */
+    errorMessage?: string;
+    /**
+     * Function to determine if a response is a failure.
+     * Default: status >= 500 or status === 429
+     */
+    isFailure?: (response: Response) => boolean;
+}
+/**
+ * Error thrown when a request is blocked due to an open circuit.
+ */
+export declare class CircuitOpenError extends Error {
+    /** The group whose circuit is open */
+    readonly group: string;
+    /** The current circuit state */
+    readonly state: CircuitState;
+    /** When the circuit was opened (timestamp) */
+    readonly openedAt: number;
+    /** Suggested retry time in seconds */
+    readonly retryAfter: number;
+    constructor(group: string, state: CircuitState, openedAt: number, retryAfter: number, message?: string);
+}
+/**
+ * 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());
+ * ```
+ */
+export declare class CircuitBreakerMiddleware {
+    #private;
+    constructor(options?: CircuitBreakerMiddlewareOptions);
+    /**
+     * Gets the underlying circuit breaker instance.
+     */
+    get circuitBreaker(): CircuitBreaker;
+    /**
+     * Creates the middleware function for use with FetchClient.
+     *
+     * @returns The middleware function
+     */
+    middleware(): FetchClientMiddleware;
+}
+/**
+ * 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,
+ * }));
+ * ```
+ */
+export declare function createCircuitBreakerMiddleware(options?: CircuitBreakerMiddlewareOptions): FetchClientMiddleware;
+/**
+ * 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,
+ * }));
+ * ```
+ */
+export declare function createPerDomainCircuitBreakerMiddleware(options?: Omit<CircuitBreakerMiddlewareOptions, "getGroupFunc">): FetchClientMiddleware;
+//# sourceMappingURL=CircuitBreakerMiddleware.d.ts.map

package/types/src/CircuitBreakerMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CircuitBreakerMiddleware.d.ts","sourceRoot":"","sources":["../../src/src/CircuitBreakerMiddleware.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EAElB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGxE;;GAEG;AACH,MAAM,WAAW,+BAAgC,SAAQ,qBAAqB;IAC5E,kFAAkF;IAClF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC;CAC7C;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAG1B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM;CASnB;AAUD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,wBAAwB;;gBAQvB,OAAO,CAAC,EAAE,+BAA+B;IASrD;;OAEG;IACH,IAAI,cAAc,IAAI,cAAc,CAEnC;IAED;;;;OAIG;IACH,UAAU,IAAI,qBAAqB;CAmEpC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,CAAC,EAAE,+BAA+B,GACxC,qBAAqB,CAGvB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uCAAuC,CACrD,OAAO,CAAC,EAAE,IAAI,CAAC,+BAA+B,EAAE,cAAc,CAAC,GAC9D,qBAAqB,CAKvB"}

package/types/src/DefaultHelpers.d.ts

@@ -1,10 +1,12 @@
 import type { FetchClient } from "./FetchClient.js";
+import type { FetchClientCache } from "./FetchClientCache.js";
 import type { FetchClientMiddleware } from "./FetchClientMiddleware.js";
 import type { FetchClientOptions } from "./FetchClientOptions.js";
 import { type FetchClientProvider } from "./FetchClientProvider.js";
 import type { FetchClientResponse } from "./FetchClientResponse.js";
 import type { ProblemDetails } from "./ProblemDetails.js";
 import type { RateLimitMiddlewareOptions } from "./RateLimitMiddleware.js";
+import type { CircuitBreakerMiddlewareOptions } from "./CircuitBreakerMiddleware.js";
 import type { GetRequestOptions, RequestOptions } from "./RequestOptions.js";
 /**
  * Gets a FetchClient instance from the current provider.
@@ -62,6 +64,11 @@ export declare function deleteJSON<T>(url: string, options?: RequestOptions): Pr
  * @returns The current FetchClientProvider.
  */
 export declare function getCurrentProvider(): FetchClientProvider;
+/**
+ * Gets the cache from the current provider.
+ * @returns The FetchClientCache instance.
+ */
+export declare function getCache(): FetchClientCache;
 /**
  * Sets the function that retrieves the current FetchClientProvider using whatever scoping mechanism is available.
  * @param getProviderFunc - The function that retrieves the current FetchClientProvider.
@@ -103,4 +110,16 @@ export declare function useRateLimit(options: RateLimitMiddlewareOptions): void;
  * @param options - The rate limiting configuration options.
  */
 export declare function usePerDomainRateLimit(options: Omit<RateLimitMiddlewareOptions, "getGroupFunc">): void;
+/**
+ * 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.
+ */
+export declare function useCircuitBreaker(options?: CircuitBreakerMiddlewareOptions): void;
+/**
+ * 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.
+ */
+export declare function usePerDomainCircuitBreaker(options?: Omit<CircuitBreakerMiddlewareOptions, "getGroupFunc">): void;
 //# sourceMappingURL=DefaultHelpers.d.ts.map

package/types/src/DefaultHelpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DefaultHelpers.d.ts","sourceRoot":"","sources":["../../src/src/DefaultHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI7E;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,WAAW,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAEjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,EACjC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAEjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAEjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAEjC;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAEjC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,mBAAmB,CAMxD;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,MAAM,mBAAmB,GAAG,IAAI,QAGlD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,QAEzC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,eAAe,EAAE,MAAM,MAAM,GAAG,IAAI,QAGrC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,QAGnE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,qBAAqB,QAE9D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,QAExD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,0BAA0B,QAGpC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,IAAI,CAAC,0BAA0B,EAAE,cAAc,CAAC,QAG1D"}
+{"version":3,"file":"DefaultHelpers.d.ts","sourceRoot":"","sources":["../../src/src/DefaultHelpers.ts"],"names":[],"mappings":"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"}

package/types/src/FetchClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FetchClient.d.ts","sourceRoot":"","sources":["../../src/src/FetchClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"FetchClient.d.ts","sourceRoot":"","sources":["../../src/src/FetchClient.ts"],"names":[],"mappings":"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"}

package/types/src/FetchClientCache.d.ts

@@ -2,11 +2,16 @@
  * Represents a cache key used in the FetchClientCache.
  */
 export type CacheKey = string[] | string;
+/**
+ * Represents a cache tag used for grouping and invalidating cache entries.
+ */
+export type CacheTag = string;
 /**
  * Represents an entry in the FetchClientCache.
  */
 type CacheEntry = {
     key: CacheKey;
+    tags: CacheTag[];
     lastAccess: Date;
     expires: Date;
     response: Response;
@@ -16,13 +21,15 @@ type CacheEntry = {
  */
 export declare class FetchClientCache {
     private cache;
+    private tagIndex;
     /**
      * 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: CacheKey, response: Response, cacheDuration?: number): void;
+    set(key: CacheKey, response: Response, cacheDuration?: number, tags?: CacheTag[]): void;
     /**
      * Retrieves a response from the cache with the specified key.
      * @param key - The cache key.
@@ -41,6 +48,23 @@ export declare class FetchClientCache {
      * @returns The number of responses that were deleted.
      */
     deleteAll(prefix: CacheKey): number;
+    /**
+     * 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: CacheTag): number;
+    /**
+     * Gets all tags currently in use in the cache.
+     * @returns An array of all cache tags.
+     */
+    getTags(): CacheTag[];
+    /**
+     * 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: CacheKey): CacheTag[];
     /**
      * Checks if a response exists in the cache with the specified key.
      * @param key - The cache key.
@@ -57,6 +81,7 @@ export declare class FetchClientCache {
      */
     clear(): void;
     private getHash;
+    private removeTagAssociations;
 }
 export {};
 //# sourceMappingURL=FetchClientCache.d.ts.map

package/types/src/FetchClientCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FetchClientCache.d.ts","sourceRoot":"","sources":["../../src/src/FetchClientCache.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC;AAEzC;;GAEG;AACH,KAAK,UAAU,GAAG;IAChB,GAAG,EAAE,QAAQ,CAAC;IACd,UAAU,EAAE,IAAI,CAAC;IACjB,OAAO,EAAE,IAAI,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAAiC;IAE9C;;;;;OAKG;IACI,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAS3E;;;;OAIG;IACI,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI;IAgB1C;;;;OAIG;IACI,MAAM,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO;IAIrC;;;;OAIG;IACI,SAAS,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM;IAc1C;;;;OAIG;IACI,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO;IAIlC;;;OAGG;IACI,MAAM,IAAI,gBAAgB,CAAC,UAAU,CAAC;IAI7C;;OAEG;IACI,KAAK,IAAI,IAAI;IAIpB,OAAO,CAAC,OAAO;CAOhB"}
+{"version":3,"file":"FetchClientCache.d.ts","sourceRoot":"","sources":["../../src/src/FetchClientCache.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC;AAEzC;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B;;GAEG;AACH,KAAK,UAAU,GAAG;IAChB,GAAG,EAAE,QAAQ,CAAC;IACd,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,UAAU,EAAE,IAAI,CAAC;IACjB,OAAO,EAAE,IAAI,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,QAAQ,CAAoC;IAEpD;;;;;;OAMG;IACI,GAAG,CACR,GAAG,EAAE,QAAQ,EACb,QAAQ,EAAE,QAAQ,EAClB,aAAa,CAAC,EAAE,MAAM,EACtB,IAAI,CAAC,EAAE,QAAQ,EAAE,GAChB,IAAI;IA2BP;;;;OAIG;IACI,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI;IAkB1C;;;;OAIG;IACI,MAAM,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO;IAWrC;;;;OAIG;IACI,SAAS,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM;IAgB1C;;;;OAIG;IACI,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM;IAqBzC;;;OAGG;IACI,OAAO,IAAI,QAAQ,EAAE;IAM5B;;;;OAIG;IACI,YAAY,CAAC,GAAG,EAAE,QAAQ,GAAG,QAAQ,EAAE;IAK9C;;;;OAIG;IACI,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO;IAIlC;;;OAGG;IACI,MAAM,IAAI,gBAAgB,CAAC,UAAU,CAAC;IAI7C;;OAEG;IACI,KAAK,IAAI,IAAI;IAKpB,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,qBAAqB;CAW9B"}

package/types/src/FetchClientProvider.d.ts

@@ -7,6 +7,8 @@ import type { FetchClientOptions } from "./FetchClientOptions.js";
 import { type IObjectEvent } from "./ObjectEvent.js";
 import { type RateLimitMiddlewareOptions } from "./RateLimitMiddleware.js";
 import { type RateLimiter } from "./RateLimiter.js";
+import { type CircuitBreakerMiddlewareOptions } from "./CircuitBreakerMiddleware.js";
+import { type CircuitBreaker } from "./CircuitBreaker.js";
 type Fetch = typeof globalThis.fetch;
 /**
  * Represents a provider for creating instances of the FetchClient class with shared default options and cache.
@@ -103,6 +105,28 @@ export declare class FetchClientProvider {
      * Removes the rate limiting middleware from all FetchClient instances created by this provider.
      */
     removeRateLimit(): void;
+    /**
+     * 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?: CircuitBreakerMiddlewareOptions): void;
+    /**
+     * 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?: Omit<CircuitBreakerMiddlewareOptions, "getGroupFunc">): void;
+    /**
+     * Gets the circuit breaker instance.
+     * @returns The circuit breaker instance, or undefined if not enabled.
+     */
+    get circuitBreaker(): CircuitBreaker | undefined;
+    /**
+     * Removes the circuit breaker middleware from all FetchClient instances created by this provider.
+     */
+    removeCircuitBreaker(): void;
 }
 export declare const defaultInstance: FetchClientProvider;
 export {};

package/types/src/FetchClientProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FetchClientProvider.d.ts","sourceRoot":"","sources":["../../src/src/FetchClientProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,KAAK,YAAY,EAAe,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEnE,KAAK,KAAK,GAAG,OAAO,UAAU,CAAC,KAAK,CAAC;AAErC;;GAEG;AACH,qBAAa,mBAAmB;;IAQ9B;;;OAGG;gBACS,KAAK,CAAC,EAAE,KAAK;IAyBzB;;OAEG;IACH,IAAW,KAAK,IAAI,KAAK,GAAG,SAAS,CAEpC;IAED;;OAEG;IACH,IAAW,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,EAExC;IAED;;OAEG;IACH,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED;;OAEG;IACH,IAAW,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,CAE1C;IAED;;OAEG;IACH,IAAW,YAAY,IAAI,MAAM,CAEhC;IAED;;OAEG;IACH,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED;;OAEG;IACH,IAAW,OAAO,IAAI,kBAAkB,CAEvC;IAED;;OAEG;IACH,IAAW,OAAO,CAAC,KAAK,EAAE,kBAAkB,EAE3C;IAED;;OAEG;IACH,IAAW,KAAK,IAAI,gBAAgB,CAEnC;IAED;;;;OAIG;IACI,cAAc,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,WAAW;IAchE;;OAEG;IACI,YAAY,CAAC,OAAO,EAAE,kBAAkB;IAO/C;;;OAGG;IACI,kBAAkB,CAAC,eAAe,EAAE,MAAM,MAAM,GAAG,IAAI;IAO9D;;;OAGG;IACI,iBAAiB,CACtB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAQpE;;;OAGG;IACI,UAAU,CAAC,GAAG,EAAE,MAAM;IAO7B;;;OAGG;IACI,aAAa,CAAC,UAAU,EAAE,qBAAqB;IAUtD;;;OAGG;IACI,YAAY,CAAC,OAAO,EAAE,0BAA0B;IAKvD;;;OAGG;IACI,qBAAqB,CAC1B,OAAO,EAAE,IAAI,CAAC,0BAA0B,EAAE,cAAc,CAAC;IAS3D;;;OAGG;IACH,IAAW,WAAW,IAAI,WAAW,GAAG,SAAS,CAEhD;IAED;;OAEG;IACI,eAAe;CAMvB;AAGD,eAAO,MAAM,eAAe,EAAE,mBAA8B,CAAC"}
+{"version":3,"file":"FetchClientProvider.d.ts","sourceRoot":"","sources":["../../src/src/FetchClientProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,KAAK,YAAY,EAAe,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,qBAAqB,CAAC;AAE7B,KAAK,KAAK,GAAG,OAAO,UAAU,CAAC,KAAK,CAAC;AAErC;;GAEG;AACH,qBAAa,mBAAmB;;IAW9B;;;OAGG;gBACS,KAAK,CAAC,EAAE,KAAK;IAyBzB;;OAEG;IACH,IAAW,KAAK,IAAI,KAAK,GAAG,SAAS,CAEpC;IAED;;OAEG;IACH,IAAW,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,EAExC;IAED;;OAEG;IACH,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED;;OAEG;IACH,IAAW,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,CAE1C;IAED;;OAEG;IACH,IAAW,YAAY,IAAI,MAAM,CAEhC;IAED;;OAEG;IACH,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED;;OAEG;IACH,IAAW,OAAO,IAAI,kBAAkB,CAEvC;IAED;;OAEG;IACH,IAAW,OAAO,CAAC,KAAK,EAAE,kBAAkB,EAE3C;IAED;;OAEG;IACH,IAAW,KAAK,IAAI,gBAAgB,CAEnC;IAED;;;;OAIG;IACI,cAAc,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,WAAW;IAchE;;OAEG;IACI,YAAY,CAAC,OAAO,EAAE,kBAAkB;IAO/C;;;OAGG;IACI,kBAAkB,CAAC,eAAe,EAAE,MAAM,MAAM,GAAG,IAAI;IAO9D;;;OAGG;IACI,iBAAiB,CACtB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAQpE;;;OAGG;IACI,UAAU,CAAC,GAAG,EAAE,MAAM;IAO7B;;;OAGG;IACI,aAAa,CAAC,UAAU,EAAE,qBAAqB;IAUtD;;;OAGG;IACI,YAAY,CAAC,OAAO,EAAE,0BAA0B;IAMvD;;;OAGG;IACI,qBAAqB,CAC1B,OAAO,EAAE,IAAI,CAAC,0BAA0B,EAAE,cAAc,CAAC;IAU3D;;;OAGG;IACH,IAAW,WAAW,IAAI,WAAW,GAAG,SAAS,CAEhD;IAED;;OAEG;IACI,eAAe;IAWtB;;;;;OAKG;IACI,iBAAiB,CAAC,OAAO,CAAC,EAAE,+BAA+B;IAOlE;;;;OAIG;IACI,0BAA0B,CAC/B,OAAO,CAAC,EAAE,IAAI,CAAC,+BAA+B,EAAE,cAAc,CAAC;IAWjE;;;OAGG;IACH,IAAW,cAAc,IAAI,cAAc,GAAG,SAAS,CAEtD;IAED;;OAEG;IACI,oBAAoB;CAU5B;AAGD,eAAO,MAAM,eAAe,EAAE,mBAA8B,CAAC"}

package/types/src/RequestOptions.d.ts

@@ -1,4 +1,4 @@
-import type { CacheKey } from "./FetchClientCache.js";
+import type { CacheKey, CacheTag } from "./FetchClientCache.js";
 import type { FetchClientResponse } from "./FetchClientResponse.js";
 /**
  * Represents the options for making a request using the FetchClient.
@@ -60,5 +60,10 @@ export type GetRequestOptions = RequestOptions & {
      * The duration for which the response should be cached, in milliseconds.
      */
     cacheDuration?: number;
+    /**
+     * Tags for grouping and invalidating cache entries. Multiple entries can share
+     * the same tag, allowing bulk invalidation via `cache.deleteByTag(tag)`.
+     */
+    cacheTags?: CacheTag[];
 };
 //# sourceMappingURL=RequestOptions.d.ts.map

package/types/src/RequestOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RequestOptions.d.ts","sourceRoot":"","sources":["../../src/src/RequestOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjC;;OAEG;IACH,kCAAkC,CAAC,EAAE,OAAO,CAAC;IAE7C;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE/B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,CAAC,OAAO,CAAC,KAAK,OAAO,GAAG,IAAI,CAAC;IAExE;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;OAEG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACnE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG;IAC/C;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC"}
+{"version":3,"file":"RequestOptions.d.ts","sourceRoot":"","sources":["../../src/src/RequestOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjC;;OAEG;IACH,kCAAkC,CAAC,EAAE,OAAO,CAAC;IAE7C;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE/B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,CAAC,OAAO,CAAC,KAAK,OAAO,GAAG,IAAI,CAAC;IAExE;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;OAEG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACnE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG;IAC/C;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;CACxB,CAAC"}

package/types/src/mocks/MockHistory.d.ts

@@ -0,0 +1,22 @@
+import type { MockHistory } from "./types.js";
+/**
+ * Implementation of MockHistory that tracks recorded requests.
+ */
+export declare class MockHistoryImpl implements MockHistory {
+    #private;
+    get get(): Request[];
+    get post(): Request[];
+    get put(): Request[];
+    get patch(): Request[];
+    get delete(): Request[];
+    get all(): Request[];
+    /**
+     * Records a request in the history.
+     */
+    record(request: Request): void;
+    /**
+     * Clears all recorded history.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=MockHistory.d.ts.map

package/types/src/mocks/MockHistory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MockHistory.d.ts","sourceRoot":"","sources":["../../../src/src/mocks/MockHistory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;GAEG;AACH,qBAAa,eAAgB,YAAW,WAAW;;IAQjD,IAAI,GAAG,IAAI,OAAO,EAAE,CAEnB;IAED,IAAI,IAAI,IAAI,OAAO,EAAE,CAEpB;IAED,IAAI,GAAG,IAAI,OAAO,EAAE,CAEnB;IAED,IAAI,KAAK,IAAI,OAAO,EAAE,CAErB;IAED,IAAI,MAAM,IAAI,OAAO,EAAE,CAEtB;IAED,IAAI,GAAG,IAAI,OAAO,EAAE,CAEnB;IAED;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAsB9B;;OAEG;IACH,KAAK,IAAI,IAAI;CAQd"}

package/types/src/mocks/MockRegistry.d.ts

@@ -0,0 +1,113 @@
+import type { FetchClient } from "../FetchClient.js";
+import type { FetchClientProvider } from "../FetchClientProvider.js";
+import { MockResponseBuilder } from "./MockResponseBuilder.js";
+import type { MockHistory } from "./types.js";
+type Fetch = typeof globalThis.fetch;
+/**
+ * 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 declare class MockRegistry {
+    #private;
+    /**
+     * Creates a mock for GET requests matching the given URL.
+     * @param url - URL string or RegExp to match
+     */
+    onGet(url: string | RegExp): MockResponseBuilder<MockRegistry>;
+    /**
+     * Creates a mock for POST requests matching the given URL.
+     * @param url - URL string or RegExp to match
+     */
+    onPost(url: string | RegExp): MockResponseBuilder<MockRegistry>;
+    /**
+     * Creates a mock for PUT requests matching the given URL.
+     * @param url - URL string or RegExp to match
+     */
+    onPut(url: string | RegExp): MockResponseBuilder<MockRegistry>;
+    /**
+     * Creates a mock for PATCH requests matching the given URL.
+     * @param url - URL string or RegExp to match
+     */
+    onPatch(url: string | RegExp): MockResponseBuilder<MockRegistry>;
+    /**
+     * Creates a mock for DELETE requests matching the given URL.
+     * @param url - URL string or RegExp to match
+     */
+    onDelete(url: string | RegExp): MockResponseBuilder<MockRegistry>;
+    /**
+     * Creates a mock for any HTTP method matching the given URL.
+     * @param url - URL string or RegExp to match
+     */
+    onAny(url: string | RegExp): MockResponseBuilder<MockRegistry>;
+    /**
+     * 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: FetchClientProvider | FetchClient): void;
+    /**
+     * Restores the original fetch implementation.
+     */
+    restore(): void;
+    /**
+     * Gets the recorded request history.
+     */
+    get history(): MockHistory;
+    /**
+     * 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(): Fetch;
+    /**
+     * Clears all mocks and history.
+     */
+    reset(): void;
+    /**
+     * Clears all mocks but keeps history.
+     */
+    resetMocks(): void;
+    /**
+     * Clears history but keeps mocks.
+     */
+    resetHistory(): void;
+}
+export {};
+//# sourceMappingURL=MockRegistry.d.ts.map

package/types/src/mocks/MockRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MockRegistry.d.ts","sourceRoot":"","sources":["../../../src/src/mocks/MockRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAkB,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D,KAAK,KAAK,GAAG,OAAO,UAAU,CAAC,KAAK,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,YAAY;;IAMvB;;;OAGG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,mBAAmB,CAAC,YAAY,CAAC;IAI9D;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,mBAAmB,CAAC,YAAY,CAAC;IAI/D;;;OAGG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,mBAAmB,CAAC,YAAY,CAAC;IAI9D;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,mBAAmB,CAAC,YAAY,CAAC;IAIhE;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,mBAAmB,CAAC,YAAY,CAAC;IAIjE;;;OAGG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,mBAAmB,CAAC,YAAY,CAAC;IAoB9D;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,EAAE,mBAAmB,GAAG,WAAW,GAAG,IAAI;IAyBxD;;OAEG;IACH,OAAO,IAAI,IAAI;IAkIf;;OAEG;IACH,IAAI,OAAO,IAAI,WAAW,CAEzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,IAAI,KAAK,IAAI,KAAK,CAOjB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,YAAY,IAAI,IAAI;CAGrB"}