@fgrzl/fetch 1.1.0-alpha.3 → 1.1.0-alpha.8

package/dist/middleware/authentication/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Authentication middleware types and configuration.
+ */
+/**
+ * Authentication token provider function.
+ * Should return the current auth token or empty string if not available.
+ */
+export type AuthTokenProvider = () => string | Promise<string>;
+/**
+ * Authentication configuration options - optimized for "pit of success".
+ *
+ * Smart defaults:
+ * - Uses standard Authorization header with Bearer token
+ * - Applies to all requests by default
+ * - Graceful handling when token is unavailable
+ */
+export interface AuthenticationOptions {
+    /**
+     * Function to get the current authentication token.
+     * Can be synchronous or asynchronous.
+     *
+     * @returns The auth token or empty string if not available
+     *
+     * @example Token from localStorage:
+     * ```typescript
+     * const getToken = () => localStorage.getItem('auth-token') || '';
+     * ```
+     *
+     * @example Async token refresh:
+     * ```typescript
+     * const getToken = async () => {
+     *   const token = localStorage.getItem('auth-token');
+     *   if (!token || isExpired(token)) {
+     *     return await refreshToken();
+     *   }
+     *   return token;
+     * };
+     * ```
+     */
+    tokenProvider: AuthTokenProvider;
+    /**
+     * Header name for the authentication token (default: 'Authorization')
+     * The token will be prefixed with the tokenType
+     */
+    headerName?: string;
+    /**
+     * Token type prefix (default: 'Bearer')
+     * Common alternatives: 'Token', 'JWT', 'ApiKey'
+     */
+    tokenType?: string;
+    /**
+     * Skip authentication for requests matching these URL patterns
+     * Useful for public endpoints that don't need auth
+     *
+     * @example
+     * ```typescript
+     * skipPatterns: [/^\/public\//, '/health', '/login']
+     * ```
+     */
+    skipPatterns?: (RegExp | string)[];
+    /**
+     * Only apply authentication to requests matching these patterns
+     * If specified, only these patterns will get auth headers
+     *
+     * @example
+     * ```typescript
+     * includePatterns: [/^\/api\//, '/graphql']
+     * ```
+     */
+    includePatterns?: (RegExp | string)[];
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/middleware/authentication/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/middleware/authentication/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,aAAa,EAAE,iBAAiB,CAAC;IAEjC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAEnC;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CACvC;AAGD,OAAO,EAAE,CAAC"}

package/dist/middleware/authentication/types.js

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Authentication middleware types and configuration.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/middleware/authentication/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/middleware/authentication/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/middleware/authorization/authorization.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Authorization middleware implementation.
+ */
+import type { FetchMiddleware } from '../../client/fetch-client';
+import type { AuthorizationOptions } from './types';
+/**
+ * Creates authorization middleware with smart defaults.
+ * Handles 401/403 responses by calling configured handlers.
+ *
+ * @param options - Authorization configuration options
+ * @returns Authorization middleware for use with FetchClient
+ *
+ * @example Basic redirect on 401:
+ * ```typescript
+ * const authzClient = useAuthorization(client, {
+ *   onUnauthorized: () => window.location.href = '/login'
+ * });
+ * ```
+ *
+ * @example Handle both 401 and 403:
+ * ```typescript
+ * const authzClient = useAuthorization(client, {
+ *   onUnauthorized: () => redirectToLogin(),
+ *   onForbidden: () => showAccessDeniedMessage(),
+ *   statusCodes: [401, 403]
+ * });
+ * ```
+ */
+export declare function createAuthorizationMiddleware(options: AuthorizationOptions): FetchMiddleware;
+//# sourceMappingURL=authorization.d.ts.map

package/dist/middleware/authorization/authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../../../src/middleware/authorization/authorization.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAyBpD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,oBAAoB,GAC5B,eAAe,CAuCjB"}

package/dist/middleware/authorization/authorization.js

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Authorization middleware implementation.
+ */
+/**
+ * Checks if a URL should skip authorization handling based on configured patterns.
+ */
+function shouldSkipAuth(url, skipPatterns = []) {
+    // Extract pathname from URL for pattern matching
+    let pathname;
+    try {
+        pathname = new URL(url).pathname;
+    }
+    catch {
+        pathname = url; // fallback if not a valid URL
+    }
+    return skipPatterns.some((pattern) => {
+        if (typeof pattern === 'string') {
+            return pathname.includes(pattern);
+        }
+        return pattern.test(pathname);
+    });
+}
+/**
+ * Creates authorization middleware with smart defaults.
+ * Handles 401/403 responses by calling configured handlers.
+ *
+ * @param options - Authorization configuration options
+ * @returns Authorization middleware for use with FetchClient
+ *
+ * @example Basic redirect on 401:
+ * ```typescript
+ * const authzClient = useAuthorization(client, {
+ *   onUnauthorized: () => window.location.href = '/login'
+ * });
+ * ```
+ *
+ * @example Handle both 401 and 403:
+ * ```typescript
+ * const authzClient = useAuthorization(client, {
+ *   onUnauthorized: () => redirectToLogin(),
+ *   onForbidden: () => showAccessDeniedMessage(),
+ *   statusCodes: [401, 403]
+ * });
+ * ```
+ */
+export function createAuthorizationMiddleware(options) {
+    const { onUnauthorized, onForbidden, skipPatterns = [], statusCodes = [401], } = options;
+    return async (request, next) => {
+        const url = request.url || '';
+        // Skip authorization handling if URL matches skip patterns
+        if (shouldSkipAuth(url, skipPatterns)) {
+            return next(request);
+        }
+        // Execute the request
+        const response = await next(request);
+        // Check if response status requires handling
+        if (statusCodes.includes(response.status)) {
+            try {
+                if (response.status === 401 && onUnauthorized) {
+                    await onUnauthorized(response, request);
+                }
+                else if (response.status === 403 && onForbidden) {
+                    await onForbidden(response, request);
+                }
+                else if (onUnauthorized) {
+                    // For any other configured status codes, use the first available handler
+                    await onUnauthorized(response, request);
+                }
+            }
+            catch (error) {
+                // If handler fails, log but don't break the response chain
+                // eslint-disable-next-line no-console
+                console.warn('Authorization handler failed:', error);
+            }
+        }
+        return response;
+    };
+}
+//# sourceMappingURL=authorization.js.map

package/dist/middleware/authorization/authorization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.js","sourceRoot":"","sources":["../../../src/middleware/authorization/authorization.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;GAEG;AACH,SAAS,cAAc,CACrB,GAAW,EACX,eAAoC,EAAE;IAEtC,iDAAiD;IACjD,IAAI,QAAgB,CAAC;IACrB,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,QAAQ,GAAG,GAAG,CAAC,CAAC,8BAA8B;IAChD,CAAC;IAED,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;QACnC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,OAAO,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC;QACD,OAAO,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,6BAA6B,CAC3C,OAA6B;IAE7B,MAAM,EACJ,cAAc,EACd,WAAW,EACX,YAAY,GAAG,EAAE,EACjB,WAAW,GAAG,CAAC,GAAG,CAAC,GACpB,GAAG,OAAO,CAAC;IAEZ,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC;QAE9B,2DAA2D;QAC3D,IAAI,cAAc,CAAC,GAAG,EAAE,YAAY,CAAC,EAAE,CAAC;YACtC,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;QAED,sBAAsB;QACtB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;QAErC,6CAA6C;QAC7C,IAAI,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1C,IAAI,CAAC;gBACH,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,cAAc,EAAE,CAAC;oBAC9C,MAAM,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;gBAC1C,CAAC;qBAAM,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC;oBAClD,MAAM,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;gBACvC,CAAC;qBAAM,IAAI,cAAc,EAAE,CAAC;oBAC1B,yEAAyE;oBACzE,MAAM,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;gBAC1C,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,2DAA2D;gBAC3D,sCAAsC;gBACtC,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE,KAAK,CAAC,CAAC;YACvD,CAAC;QACH,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware/authorization/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Authorization middleware - "pit of success" API.
+ */
+import type { FetchClient } from '../../client/fetch-client';
+import type { AuthorizationOptions } from './types';
+export type { AuthorizationOptions, UnauthorizedHandler } from './types';
+export { createAuthorizationMiddleware } from './authorization';
+/**
+ * "Pit of success" API for adding authorization handling to a FetchClient.
+ * Automatically handles 401 Unauthorized responses.
+ *
+ * @param client - The FetchClient to add authorization handling to
+ * @param options - Authorization configuration
+ * @returns A new FetchClient with authorization middleware
+ *
+ * @example Basic redirect on 401:
+ * ```typescript
+ * const authzClient = useAuthorization(client, {
+ *   onUnauthorized: () => {
+ *     localStorage.removeItem('auth-token');
+ *     window.location.href = '/login';
+ *   }
+ * });
+ * ```
+ *
+ * @example Handle multiple status codes:
+ * ```typescript
+ * const authzClient = useAuthorization(client, {
+ *   onUnauthorized: () => redirectToLogin(),
+ *   onForbidden: () => showAccessDenied(),
+ *   statusCodes: [401, 403]
+ * });
+ * ```
+ */
+export declare function useAuthorization(client: FetchClient, options: AuthorizationOptions): FetchClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/middleware/authorization/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/middleware/authorization/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAIpD,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACzE,OAAO,EAAE,6BAA6B,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,oBAAoB,GAC5B,WAAW,CAEb"}

package/dist/middleware/authorization/index.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Authorization middleware - "pit of success" API.
+ */
+import { createAuthorizationMiddleware } from './authorization';
+export { createAuthorizationMiddleware } from './authorization';
+/**
+ * "Pit of success" API for adding authorization handling to a FetchClient.
+ * Automatically handles 401 Unauthorized responses.
+ *
+ * @param client - The FetchClient to add authorization handling to
+ * @param options - Authorization configuration
+ * @returns A new FetchClient with authorization middleware
+ *
+ * @example Basic redirect on 401:
+ * ```typescript
+ * const authzClient = useAuthorization(client, {
+ *   onUnauthorized: () => {
+ *     localStorage.removeItem('auth-token');
+ *     window.location.href = '/login';
+ *   }
+ * });
+ * ```
+ *
+ * @example Handle multiple status codes:
+ * ```typescript
+ * const authzClient = useAuthorization(client, {
+ *   onUnauthorized: () => redirectToLogin(),
+ *   onForbidden: () => showAccessDenied(),
+ *   statusCodes: [401, 403]
+ * });
+ * ```
+ */
+export function useAuthorization(client, options) {
+    return client.use(createAuthorizationMiddleware(options));
+}
+//# sourceMappingURL=index.js.map

package/dist/middleware/authorization/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/middleware/authorization/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,6BAA6B,EAAE,MAAM,iBAAiB,CAAC;AAIhE,OAAO,EAAE,6BAA6B,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAmB,EACnB,OAA6B;IAE7B,OAAO,MAAM,CAAC,GAAG,CAAC,6BAA6B,CAAC,OAAO,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/dist/middleware/authorization/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Authorization middleware types and configuration.
+ */
+import type { FetchResponse } from '../../client/types';
+/**
+ * Handler function for unauthorized/forbidden responses.
+ */
+export type UnauthorizedHandler = (response: FetchResponse<unknown>, request: RequestInit & {
+    url?: string;
+}) => void | Promise<void>;
+/**
+ * Authorization configuration options - optimized for "pit of success".
+ *
+ * Smart defaults:
+ * - Handles 401 Unauthorized responses
+ * - Optionally handles 403 Forbidden responses
+ * - Graceful error handling
+ */
+export interface AuthorizationOptions {
+    /**
+     * Handler called when 401 Unauthorized response is received.
+     *
+     * @param response - The 401 response object
+     * @param request - The original request that was unauthorized
+     *
+     * @example Redirect to login:
+     * ```typescript
+     * onUnauthorized: () => {
+     *   window.location.href = '/login';
+     * }
+     * ```
+     *
+     * @example Clear token and reload:
+     * ```typescript
+     * onUnauthorized: () => {
+     *   localStorage.removeItem('auth-token');
+     *   window.location.reload();
+     * }
+     * ```
+     */
+    onUnauthorized: UnauthorizedHandler;
+    /**
+     * Handler called when 403 Forbidden response is received.
+     * Optional - if not provided, 403 responses are ignored.
+     *
+     * @param response - The 403 response object
+     * @param request - The original request that was forbidden
+     */
+    onForbidden?: UnauthorizedHandler;
+    /**
+     * Skip authorization handling for requests matching these URL patterns
+     * Useful for login/public endpoints where 401 is expected
+     *
+     * @example
+     * ```typescript
+     * skipPatterns: ['/login', '/register', /^\/public\//]
+     * ```
+     */
+    skipPatterns?: (RegExp | string)[];
+    /**
+     * Status codes to handle (default: [401])
+     * You can add 403 if you want to handle forbidden responses
+     */
+    statusCodes?: number[];
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/middleware/authorization/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/middleware/authorization/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,EAChC,OAAO,EAAE,WAAW,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,KACpC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,cAAc,EAAE,mBAAmB,CAAC;IAEpC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAElC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAEnC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAGD,OAAO,EAAE,CAAC"}

package/dist/middleware/authorization/types.js

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Authorization middleware types and configuration.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/middleware/authorization/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/middleware/authorization/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/middleware/cache/cache.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Cache middleware implementation.
+ */
+import type { FetchMiddleware } from '../../client/fetch-client';
+import type { CacheOptions, CacheStorage, CacheEntry } from './types';
+/**
+ * Default in-memory cache storage implementation.
+ */
+export declare class MemoryStorage implements CacheStorage {
+    private cache;
+    get(key: string): Promise<CacheEntry | null>;
+    getWithExpiry(key: string): Promise<{
+        entry: CacheEntry | null;
+        isExpired: boolean;
+    }>;
+    set(key: string, entry: CacheEntry): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Creates cache middleware with smart defaults.
+ * Caches GET responses for faster subsequent requests.
+ *
+ * @param options - Cache configuration options
+ * @returns Cache middleware for use with FetchClient
+ *
+ * @example Basic caching:
+ * ```typescript
+ * const cachedClient = useCache(client);
+ * // GET requests will be cached for 5 minutes
+ * ```
+ *
+ * @example Custom TTL:
+ * ```typescript
+ * const cachedClient = useCache(client, {
+ *   ttl: 10 * 60 * 1000 // 10 minutes
+ * });
+ * ```
+ */
+export declare function createCacheMiddleware(options?: CacheOptions): FetchMiddleware;
+//# sourceMappingURL=cache.d.ts.map

package/dist/middleware/cache/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/middleware/cache/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,EAEX,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,qBAAa,aAAc,YAAW,YAAY;IAChD,OAAO,CAAC,KAAK,CAAiC;IAExC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAe5C,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IAWrF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AA2BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,YAAiB,GACzB,eAAe,CA0HjB"}

package/dist/middleware/cache/cache.js

@@ -0,0 +1,186 @@
+/**
+ * @fileoverview Cache middleware implementation.
+ */
+/**
+ * Default in-memory cache storage implementation.
+ */
+export class MemoryStorage {
+    constructor() {
+        this.cache = new Map();
+    }
+    async get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return null;
+        }
+        // Check if expired
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry;
+    }
+    async getWithExpiry(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return { entry: null, isExpired: false };
+        }
+        const isExpired = Date.now() > entry.expiresAt;
+        // Don't delete expired entries when using getWithExpiry - let the caller decide
+        return { entry, isExpired };
+    }
+    async set(key, entry) {
+        this.cache.set(key, entry);
+    }
+    async delete(key) {
+        this.cache.delete(key);
+    }
+    async clear() {
+        this.cache.clear();
+    }
+}
+/**
+ * Default cache key generator.
+ */
+const defaultKeyGenerator = (request) => {
+    const url = request.url || '';
+    const method = request.method || 'GET';
+    const headers = request.headers ? JSON.stringify(request.headers) : '';
+    return `${method}:${url}:${headers}`;
+};
+/**
+ * Checks if a URL should skip caching based on configured patterns.
+ */
+function shouldSkipCache(url, skipPatterns = []) {
+    return skipPatterns.some((pattern) => {
+        if (typeof pattern === 'string') {
+            return url.includes(pattern);
+        }
+        return pattern.test(url);
+    });
+}
+/**
+ * Creates cache middleware with smart defaults.
+ * Caches GET responses for faster subsequent requests.
+ *
+ * @param options - Cache configuration options
+ * @returns Cache middleware for use with FetchClient
+ *
+ * @example Basic caching:
+ * ```typescript
+ * const cachedClient = useCache(client);
+ * // GET requests will be cached for 5 minutes
+ * ```
+ *
+ * @example Custom TTL:
+ * ```typescript
+ * const cachedClient = useCache(client, {
+ *   ttl: 10 * 60 * 1000 // 10 minutes
+ * });
+ * ```
+ */
+export function createCacheMiddleware(options = {}) {
+    const { ttl = 5 * 60 * 1000, // 5 minutes
+    methods = ['GET'], storage = new MemoryStorage(), keyGenerator = defaultKeyGenerator, skipPatterns = [], staleWhileRevalidate = false, } = options;
+    return async (request, next) => {
+        const method = (request.method || 'GET').toUpperCase();
+        const url = request.url || '';
+        // Skip caching if:
+        // 1. Method is not in cached methods list
+        // 2. URL matches a skip pattern
+        if (!methods.includes(method) || shouldSkipCache(url, skipPatterns)) {
+            return next(request);
+        }
+        const cacheKey = keyGenerator(request);
+        try {
+            // Try to get cached response with expiry info
+            const { entry: cached, isExpired } = storage.getWithExpiry
+                ? await storage.getWithExpiry(cacheKey)
+                : await (async () => {
+                    const entry = await storage.get(cacheKey);
+                    return { entry, isExpired: false };
+                })();
+            if (cached && !isExpired) {
+                // Return fresh cached response
+                return {
+                    ...cached.response,
+                    headers: new Headers(cached.response.headers),
+                    data: cached.response.data,
+                };
+            }
+            // If stale-while-revalidate and we have cached data (even expired), return it immediately
+            // and update in background
+            if (cached && staleWhileRevalidate) {
+                // Return cached data immediately (even if stale)
+                const cachedResponse = {
+                    ...cached.response,
+                    headers: new Headers(cached.response.headers),
+                    data: cached.response.data,
+                };
+                // Update cache in background if expired
+                if (isExpired) {
+                    next(request)
+                        .then(async (freshResponse) => {
+                        const headersObj = {};
+                        freshResponse.headers.forEach((value, key) => {
+                            headersObj[key] = value;
+                        });
+                        const cacheEntry = {
+                            response: {
+                                status: freshResponse.status,
+                                statusText: freshResponse.statusText,
+                                headers: headersObj,
+                                data: freshResponse.data,
+                            },
+                            timestamp: Date.now(),
+                            expiresAt: Date.now() + ttl,
+                        };
+                        await storage.set(cacheKey, cacheEntry);
+                    })
+                        .catch(() => {
+                        // Ignore background update errors
+                    });
+                }
+                return cachedResponse;
+            }
+            // No cached data or not using stale-while-revalidate
+            const response = await next(request);
+            // Cache successful responses
+            if (response.ok) {
+                try {
+                    const headersObj = {};
+                    response.headers.forEach((value, key) => {
+                        headersObj[key] = value;
+                    });
+                    const cacheEntry = {
+                        response: {
+                            status: response.status,
+                            statusText: response.statusText,
+                            headers: headersObj,
+                            data: response.data,
+                        },
+                        timestamp: Date.now(),
+                        expiresAt: Date.now() + ttl,
+                    };
+                    await storage.set(cacheKey, cacheEntry);
+                }
+                catch {
+                    // Ignore cache storage errors, but still return the response
+                }
+            }
+            return response;
+        }
+        catch (error) {
+            // Only catch cache retrieval errors, let network errors through
+            if (error && typeof error === 'object' && 'message' in error) {
+                const errorMessage = error.message;
+                if (errorMessage.includes('Network') || errorMessage.includes('fetch')) {
+                    throw error; // Re-throw network errors
+                }
+            }
+            // If cache retrieval fails, just proceed with the request
+            return next(request);
+        }
+    };
+}
+//# sourceMappingURL=cache.js.map

package/dist/middleware/cache/cache.js.map

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

package/dist/middleware/cache/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Cache middleware - "pit of success" API.
+ */
+import type { FetchClient } from '../../client/fetch-client';
+import type { CacheOptions } from './types';
+export type { CacheOptions, CacheStorage, CacheEntry, CacheKeyGenerator, } from './types';
+export { createCacheMiddleware, MemoryStorage } from './cache';
+/**
+ * "Pit of success" API for adding response caching to a FetchClient.
+ * Caches GET responses for faster subsequent requests.
+ *
+ * @param client - The FetchClient to add caching to
+ * @param options - Cache configuration options
+ * @returns A new FetchClient with cache middleware
+ *
+ * @example Basic caching (5 minute TTL):
+ * ```typescript
+ * const cachedClient = useCache(client);
+ *
+ * // First call hits the network
+ * await cachedClient.get('/api/data');
+ *
+ * // Second call returns cached data
+ * await cachedClient.get('/api/data');
+ * ```
+ *
+ * @example Custom TTL and methods:
+ * ```typescript
+ * const cachedClient = useCache(client, {
+ *   ttl: 10 * 60 * 1000, // 10 minutes
+ *   methods: ['GET', 'HEAD']
+ * });
+ * ```
+ *
+ * @example Stale-while-revalidate:
+ * ```typescript
+ * const cachedClient = useCache(client, {
+ *   staleWhileRevalidate: true
+ * });
+ * // Returns stale data immediately, updates cache in background
+ * ```
+ */
+export declare function useCache(client: FetchClient, options?: CacheOptions): FetchClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/middleware/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/middleware/cache/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI5C,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,iBAAiB,GAClB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,YAAiB,GACzB,WAAW,CAEb"}