create-request 0.0.1-beta.6 → 0.0.1-beta.7

package/README.md

@@ -14,6 +14,7 @@
 - 🔐 **Auth Helpers** - Simple methods for common authentication patterns
 - 📦 **Typed Responses** - Full TypeScript support for response data
 - 🚧 **Error Handling** - Detailed error info with custom error class
+- 📝 **Response Caching** - Flexible caching system with multiple storage options
 
 ## Why create-request?
 
@@ -206,6 +207,39 @@ try {
 }
 ```
 
+### Caching Requests
+
+```typescript
+import create, { createMemoryStorage, createLocalStorageStorage, createSessionStorageStorage } from 'create-request';
+
+// Simple in-memory caching
+const request = create.get()
+  .withCache({
+    storage: createMemoryStorage(),
+    ttl: 60000 // 1 minute in milliseconds
+  })
+  .sendTo('https://api.example.com/data');
+
+// Using localStorage storage
+const request = create.get()
+  .withCache({
+    storage: createLocalStorageStorage(),
+    ttl: 5 * 60 * 1000, // 5 minutes
+    maxSize: '1MB',
+    keyPrefix: 'user-data'
+  })
+  .sendTo('https://api.example.com/users');
+
+// Using sessionStorage for per-session caching
+const request = create.get()
+  .withCache({
+    storage: createSessionStorageStorage(),
+    maxEntries: 50,
+    varyByHeaders: ['x-api-version']
+  })
+  .sendTo('https://api.example.com/data');
+```
+
 ## Advanced Usage
 
 ### Request Reuse
@@ -277,6 +311,117 @@ request.sendTo('https://api.example.com/data')
   });
 ```
 
+### Advanced Caching
+
+```typescript
+import create, { createMemoryStorage, StorageProvider } from 'create-request';
+
+// Custom key generation
+const request = create.get()
+  .withCache({
+    storage: createMemoryStorage(),
+    keyGenerator: (url, method, headers) => {
+      // Include user ID from authorization header in the cache key
+      const authHeader = headers?.['Authorization'] || '';
+      const userId = extractUserIdFromToken(authHeader);
+      return `${method}:${url}:${userId}`;
+    }
+  });
+
+// Simple custom storage provider example
+const customStorage: StorageProvider = {
+  get(key: string): string | null {
+    // Get from your custom storage
+    return localStorage.getItem(`my-app:${key}`);
+  },
+  set(key: string, value: string): void {
+    // Set in your custom storage
+    localStorage.setItem(`my-app:${key}`, value);
+  },
+  has(key: string): boolean {
+    // Check if exists in your custom storage
+    return localStorage.getItem(`my-app:${key}`) !== null;
+  },
+  delete(key: string): void {
+    // Remove from your custom storage
+    localStorage.removeItem(`my-app:${key}`);
+  },
+  clear(): void {
+    // Clear all items from your namespace
+    Object.keys(localStorage)
+      .filter(key => key.startsWith('my-app:'))
+      .forEach(key => localStorage.removeItem(key));
+  }
+};
+
+const request = create.get()
+  .withCache({ storage: customStorage })
+  .sendTo('https://api.example.com/data');
+```
+
+### Implementing Custom Storage Providers
+
+You can create your own storage provider by implementing the `StorageProvider` interface:
+
+```typescript
+import { StorageProvider } from 'create-request';
+
+// Create a simple custom storage provider
+export function createNamespacedStorage(namespace: string): StorageProvider {
+  return {
+    get(key: string): string | null {
+      return localStorage.getItem(`${namespace}:${key}`);
+    },
+
+    set(key: string, value: string): void {
+      try {
+        localStorage.setItem(`${namespace}:${key}`, value);
+      } catch (e) {
+        // Handle quota exceeded errors
+        console.warn("Storage quota exceeded, clearing cache");
+        this.clear();
+        try {
+          localStorage.setItem(`${namespace}:${key}`, value);
+        } catch (e) {
+          console.error("Failed to set cache item even after clearing cache");
+        }
+      }
+    },
+
+    has(key: string): boolean {
+      return localStorage.getItem(`${namespace}:${key}`) !== null;
+    },
+
+    delete(key: string): void {
+      localStorage.removeItem(`${namespace}:${key}`);
+    },
+
+    clear(): void {
+      // Only clear items in our namespace
+      Object.keys(localStorage)
+        .filter(key => key.startsWith(`${namespace}:`))
+        .forEach(key => localStorage.removeItem(key));
+    }
+  };
+}
+
+// Usage:
+const request = create.get()
+  .withCache({
+    storage: createNamespacedStorage('api-cache'),
+    ttl: 24 * 60 * 60 * 1000 // 24 hours
+  })
+  .sendTo('https://api.example.com/data');
+```
+
+With custom storage providers, you can integrate with any storage system, such as:
+
+- Custom browser storage solutions
+- Memory caches with expiration policies
+- Session-based storage mechanisms
+- Encrypted storage providers
+- Third-party storage libraries
+
 ## CSRF Protection
 
 ### Global CSRF Configuration

package/dist/library/BaseRequest.d.ts

@@ -1,12 +1,16 @@
 import { type HttpMethod, type RedirectMode, type RequestMode, type RequestPriority, CredentialsPolicy } from "./enums";
 import { type ResponsePromise } from "./ResponseWrapper";
 import type { RequestOptions, RetryCallback, CookiesRecord, CookieOptions } from "./types";
+import type { CacheOptions } from "./types/cache";
+import { CacheManager } from "./utils/CacheManager";
 export declare abstract class BaseRequest {
     protected abstract method: HttpMethod;
     protected requestOptions: RequestOptions;
     protected abortController?: AbortController;
     protected queryParams: URLSearchParams;
     protected autoApplyCsrfProtection: boolean;
+    protected cacheManager?: CacheManager;
+    protected cacheEnabled: boolean;
     constructor();
     withHeaders(headers: Record<string, string>): this;
     withTimeout(timeout: number): this;
@@ -135,6 +139,12 @@ export declare abstract class BaseRequest {
      * @returns The instance for chaining
      */
     withAntiCsrfHeaders(): this;
+    /**
+     * Enables caching for the request with the specified options
+     * @param options The cache configuration options
+     * @returns The instance for chaining
+     */
+    withCache(options?: CacheOptions): this;
     /**
      * Send the request to the specified URL
      * @param url The URL to send the request to
@@ -154,4 +164,11 @@ export declare abstract class BaseRequest {
      */
     private executeWithRetries;
     private executeRequest;
+    /**
+     * Executes a request using cache when possible
+     * @param url The formatted URL to send the request to
+     * @param fetchOptions The fetch options to use
+     * @param cacheKey The cache key for this request
+     */
+    private executeWithCache;
 }

package/dist/library/index.d.ts

@@ -6,6 +6,10 @@ export { RequestError } from "./RequestError";
 export { ResponseWrapper } from "./ResponseWrapper";
 export { CookieUtils } from "./utils/CookieUtils";
 export { GetRequest, PostRequest, PutRequest, DeleteRequest, PatchRequest, HeadRequest, OptionsRequest } from "./requestMethods";
+export { createMemoryStorage, createLocalStorageStorage, createSessionStorageStorage } from "./utils/CacheStorage";
+export { CacheManager } from "./utils/CacheManager";
+export type { CacheOptions } from "./types/cache";
+export type { StorageProvider } from "./utils/StorageProvider";
 declare const create: {
     readonly get: typeof get;
     readonly post: typeof post;

package/dist/library/index.esm.js

@@ -233,6 +233,331 @@ class ResponseWrapper {
     }
 }
 
+/**
+ * Parse size strings like "10MB" into bytes
+ * @param size Size as number or string with units
+ */
+function parseSize(size) {
+    var _a;
+    if (typeof size === "number")
+        return size;
+    const match = size.match(/^(\d+(?:\.\d+)?)\s*(KB|MB|GB)?$/i);
+    if (!match)
+        return 0;
+    const num = parseFloat(match[1]);
+    const unit = (_a = match[2]) === null || _a === void 0 ? void 0 : _a.toUpperCase();
+    switch (unit) {
+        case "KB":
+            return num * 1024;
+        case "MB":
+            return num * 1024 * 1024;
+        case "GB":
+            return num * 1024 * 1024 * 1024;
+        default:
+            return num;
+    }
+}
+/**
+ * Create a memory storage provider using Map
+ */
+function createMemoryStorage() {
+    const store = new Map();
+    return {
+        get(key) {
+            return store.get(key) || null;
+        },
+        set(key, value) {
+            store.set(key, value);
+        },
+        has(key) {
+            return store.has(key);
+        },
+        delete(key) {
+            store.delete(key);
+        },
+        clear() {
+            store.clear();
+        },
+    };
+}
+/**
+ * Create a localStorage-based storage provider
+ */
+function createLocalStorageStorage() {
+    return {
+        get(key) {
+            if (typeof localStorage === "undefined")
+                return null;
+            return localStorage.getItem(key);
+        },
+        set(key, value) {
+            if (typeof localStorage === "undefined")
+                return;
+            try {
+                localStorage.setItem(key, value);
+            }
+            catch (e) {
+                // Handle quota exceeded errors
+                console.warn("Cache storage quota exceeded, clearing cache");
+                void this.clear();
+                try {
+                    localStorage.setItem(key, value);
+                }
+                catch (e) {
+                    console.error("Failed to set cache item even after clearing cache");
+                }
+            }
+        },
+        has(key) {
+            if (typeof localStorage === "undefined")
+                return false;
+            return localStorage.getItem(key) !== null;
+        },
+        delete(key) {
+            if (typeof localStorage === "undefined")
+                return;
+            localStorage.removeItem(key);
+        },
+        clear() {
+            if (typeof localStorage === "undefined")
+                return;
+            localStorage.clear();
+        },
+    };
+}
+/**
+ * Create a sessionStorage-based storage provider
+ */
+function createSessionStorageStorage() {
+    return {
+        get(key) {
+            if (typeof sessionStorage === "undefined")
+                return null;
+            return sessionStorage.getItem(key);
+        },
+        set(key, value) {
+            if (typeof sessionStorage === "undefined")
+                return;
+            try {
+                sessionStorage.setItem(key, value);
+            }
+            catch (e) {
+                // Handle quota exceeded errors
+                console.warn("Cache storage quota exceeded, clearing cache");
+                void this.clear();
+                try {
+                    sessionStorage.setItem(key, value);
+                }
+                catch (e) {
+                    console.error("Failed to set cache item even after clearing cache");
+                }
+            }
+        },
+        has(key) {
+            if (typeof sessionStorage === "undefined")
+                return false;
+            return sessionStorage.getItem(key) !== null;
+        },
+        delete(key) {
+            if (typeof sessionStorage === "undefined")
+                return;
+            sessionStorage.removeItem(key);
+        },
+        clear() {
+            if (typeof sessionStorage === "undefined")
+                return;
+            sessionStorage.clear();
+        },
+    };
+}
+/**
+ * Create a storage provider from a cache options object
+ */
+function createStorageProvider(options) {
+    const { storage } = options || {};
+    if (!storage) {
+        // Default to memory storage
+        return createMemoryStorage();
+    }
+    // Check if storage is already a StorageProvider
+    if (typeof storage.get === "function" && typeof storage.set === "function") {
+        return storage;
+    }
+    // Check if it's localStorage or sessionStorage
+    if (storage === localStorage) {
+        return createLocalStorageStorage();
+    }
+    if (storage === sessionStorage) {
+        return createSessionStorageStorage();
+    }
+    // Check if it's a Map
+    if (storage instanceof Map) {
+        return {
+            get(key) {
+                return storage.get(key) || null;
+            },
+            set(key, value, _ttl) {
+                storage.set(key, value);
+            },
+            has(key) {
+                return storage.has(key);
+            },
+            delete(key) {
+                storage.delete(key);
+            },
+            clear() {
+                storage.clear();
+            },
+        };
+    }
+    // Default to memory storage
+    console.warn("Unsupported storage type, falling back to memory storage");
+    return createMemoryStorage();
+}
+
+/**
+ * Cache manager that handles storage operations
+ */
+class CacheManager {
+    constructor(options = {}) {
+        this.entryCount = 0;
+        this.totalSize = 0;
+        this.options = options;
+        this.storage = createStorageProvider(options);
+    }
+    /**
+     * Generate a cache key based on request details
+     */
+    generateKey(url, method, headers, body) {
+        // Use custom key generator if provided
+        if (this.options.keyGenerator) {
+            const customKey = this.options.keyGenerator(url, method, headers, body);
+            return this.options.keyPrefix ? `${this.options.keyPrefix}:${customKey}` : customKey;
+        }
+        // Default key generation
+        let key = `${method}:${url}`;
+        // Add vary headers to key if specified
+        if (this.options.varyByHeaders && headers) {
+            const varyHeaders = {};
+            this.options.varyByHeaders.forEach(header => {
+                const normalizedHeader = header.toLowerCase();
+                // Find the header in case-insensitive way
+                Object.keys(headers).forEach(h => {
+                    if (h.toLowerCase() === normalizedHeader) {
+                        varyHeaders[normalizedHeader] = headers[h];
+                    }
+                });
+            });
+            if (Object.keys(varyHeaders).length > 0) {
+                key += `:${JSON.stringify(varyHeaders)}`;
+            }
+        }
+        // Include body in cache key for non-GET requests if it's a simple value
+        if (method !== "GET" && body !== undefined && body !== null) {
+            try {
+                if (typeof body === "string" || typeof body === "number" || typeof body === "boolean") {
+                    key += `:${String(body)}`;
+                }
+                else if (typeof body === "object") {
+                    key += `:${JSON.stringify(body)}`;
+                }
+            }
+            catch (e) {
+                console.warn("Failed to stringify request body for cache key");
+            }
+        }
+        // Add prefix if specified
+        return this.options.keyPrefix ? `${this.options.keyPrefix}:${key}` : key;
+    }
+    /**
+     * Get a value from cache
+     */
+    async get(key) {
+        const value = await Promise.resolve(this.storage.get(key));
+        if (!value)
+            return null;
+        try {
+            const entry = JSON.parse(value);
+            // Check if the entry has expired
+            if (entry.expiry && entry.expiry < Date.now()) {
+                await Promise.resolve(this.storage.delete(key));
+                return null;
+            }
+            return entry;
+        }
+        catch (e) {
+            // If we can't parse the cached value, remove it
+            await Promise.resolve(this.storage.delete(key));
+            return null;
+        }
+    }
+    /**
+     * Set a value in cache
+     */
+    async set(key, value, headers) {
+        const now = Date.now();
+        const ttl = this.options.ttl;
+        const entry = {
+            value,
+            timestamp: now,
+            expiry: ttl ? now + ttl : null,
+            headers,
+        };
+        const serialized = JSON.stringify(entry);
+        // Check size constraints if applicable
+        if (this.options.maxSize) {
+            const maxBytes = parseSize(this.options.maxSize);
+            const entrySize = new TextEncoder().encode(serialized).length;
+            // If a single entry exceeds the max size, reject it without clearing the cache
+            if (entrySize > maxBytes) {
+                console.warn(`Cache entry size (${entrySize} bytes) exceeds maximum cache size (${maxBytes} bytes)`);
+                return;
+            }
+            // Only clear if adding this entry would exceed the total limit
+            if (this.totalSize + entrySize > maxBytes) {
+                // Simple strategy: clear everything
+                // A more sophisticated strategy would remove oldest entries first
+                await Promise.resolve(this.storage.clear());
+                this.totalSize = 0;
+                this.entryCount = 0;
+            }
+            this.totalSize += entrySize;
+        }
+        // Check max entries constraint
+        if (this.options.maxEntries) {
+            this.entryCount++;
+            if (this.entryCount > this.options.maxEntries) {
+                // Simple strategy: clear everything
+                // A more sophisticated strategy would use LRU cache
+                await Promise.resolve(this.storage.clear());
+                this.entryCount = 1;
+            }
+        }
+        // Pass ttl to storage provider if available
+        await Promise.resolve(this.storage.set(key, serialized, ttl));
+    }
+    /**
+     * Check if a key exists in the cache
+     */
+    async has(key) {
+        return Promise.resolve(this.storage.has(key));
+    }
+    /**
+     * Delete a key from the cache
+     */
+    async delete(key) {
+        return Promise.resolve(this.storage.delete(key));
+    }
+    /**
+     * Clear the entire cache
+     */
+    async clear() {
+        this.entryCount = 0;
+        this.totalSize = 0;
+        return Promise.resolve(this.storage.clear());
+    }
+}
+
 /**
  * Global configuration for create-request
  */
@@ -446,6 +771,7 @@ class BaseRequest {
         };
         this.queryParams = new URLSearchParams();
         this.autoApplyCsrfProtection = true;
+        this.cacheEnabled = false;
     }
     withHeaders(headers) {
         this.requestOptions.headers = {
@@ -708,6 +1034,16 @@ class BaseRequest {
             "X-Requested-With": "XMLHttpRequest",
         });
     }
+    /**
+     * Enables caching for the request with the specified options
+     * @param options The cache configuration options
+     * @returns The instance for chaining
+     */
+    withCache(options = {}) {
+        this.cacheEnabled = true;
+        this.cacheManager = new CacheManager(options);
+        return this;
+    }
     /**
      * Send the request to the specified URL
      * @param url The URL to send the request to
@@ -757,8 +1093,15 @@ class BaseRequest {
             ...this.requestOptions,
             method: this.method,
         };
-        // Create the base promise
-        const basePromise = !this.requestOptions.retries ? this.executeRequest(url, fetchOptions) : this.executeWithRetries(url, fetchOptions);
+        // Create the base promise - handle caching if enabled
+        let basePromise;
+        if (this.cacheEnabled && this.cacheManager) {
+            const cacheKey = this.cacheManager.generateKey(url, this.method, this.requestOptions.headers, this.requestOptions.body);
+            basePromise = this.executeWithCache(url, fetchOptions, cacheKey);
+        }
+        else {
+            basePromise = !this.requestOptions.retries ? this.executeRequest(url, fetchOptions) : this.executeWithRetries(url, fetchOptions);
+        }
         const responsePromise = basePromise;
         // Attach convenience methods that begin processing immediately
         responsePromise.getJson = async () => {
@@ -897,6 +1240,48 @@ class BaseRequest {
             }
         }
     }
+    /**
+     * Executes a request using cache when possible
+     * @param url The formatted URL to send the request to
+     * @param fetchOptions The fetch options to use
+     * @param cacheKey The cache key for this request
+     */
+    async executeWithCache(url, fetchOptions, cacheKey) {
+        // Try to get from cache first
+        if (this.cacheManager) {
+            const cachedEntry = await this.cacheManager.get(cacheKey);
+            if (cachedEntry) {
+                // Create a synthetic Response object from cached data
+                const cachedResponse = new Response(JSON.stringify(cachedEntry.value), {
+                    status: 200,
+                    headers: new Headers(cachedEntry.headers || {}),
+                });
+                return new ResponseWrapper(cachedResponse);
+            }
+        }
+        // Not in cache, make the actual request
+        const response = await (!this.requestOptions.retries ? this.executeRequest(url, fetchOptions) : this.executeWithRetries(url, fetchOptions));
+        // Cache the successful response if caching is enabled
+        // Only cache successful responses
+        if (response.ok && this.cacheManager) {
+            // Clone the response so we don't consume it
+            try {
+                const responseData = await response.getJson();
+                // Extract headers to store in cache
+                const headers = {};
+                response.headers.forEach((value, key) => {
+                    headers[key] = value;
+                });
+                // Store in cache
+                await this.cacheManager.set(cacheKey, responseData, headers);
+            }
+            catch (error) {
+                // Failed to cache, but we can still return the response
+                console.warn("Failed to cache response:", error);
+            }
+        }
+        return response;
+    }
 }
 
 /**
@@ -1062,4 +1447,4 @@ const create = {
     config: Config.getInstance(),
 };
 
-export { CacheMode, CookieUtils, CredentialsPolicy, DeleteRequest, GetRequest, HeadRequest, HttpMethod, OptionsRequest, PatchRequest, PostRequest, PutRequest, RedirectMode, RequestError, RequestMode, RequestPriority, ResponseWrapper, SameSitePolicy, create as default };
+export { CacheManager, CacheMode, CookieUtils, CredentialsPolicy, DeleteRequest, GetRequest, HeadRequest, HttpMethod, OptionsRequest, PatchRequest, PostRequest, PutRequest, RedirectMode, RequestError, RequestMode, RequestPriority, ResponseWrapper, SameSitePolicy, createLocalStorageStorage, createMemoryStorage, createSessionStorageStorage, create as default };

package/dist/library/index.js

@@ -239,6 +239,331 @@
         }
     }
 
+    /**
+     * Parse size strings like "10MB" into bytes
+     * @param size Size as number or string with units
+     */
+    function parseSize(size) {
+        var _a;
+        if (typeof size === "number")
+            return size;
+        const match = size.match(/^(\d+(?:\.\d+)?)\s*(KB|MB|GB)?$/i);
+        if (!match)
+            return 0;
+        const num = parseFloat(match[1]);
+        const unit = (_a = match[2]) === null || _a === void 0 ? void 0 : _a.toUpperCase();
+        switch (unit) {
+            case "KB":
+                return num * 1024;
+            case "MB":
+                return num * 1024 * 1024;
+            case "GB":
+                return num * 1024 * 1024 * 1024;
+            default:
+                return num;
+        }
+    }
+    /**
+     * Create a memory storage provider using Map
+     */
+    function createMemoryStorage() {
+        const store = new Map();
+        return {
+            get(key) {
+                return store.get(key) || null;
+            },
+            set(key, value) {
+                store.set(key, value);
+            },
+            has(key) {
+                return store.has(key);
+            },
+            delete(key) {
+                store.delete(key);
+            },
+            clear() {
+                store.clear();
+            },
+        };
+    }
+    /**
+     * Create a localStorage-based storage provider
+     */
+    function createLocalStorageStorage() {
+        return {
+            get(key) {
+                if (typeof localStorage === "undefined")
+                    return null;
+                return localStorage.getItem(key);
+            },
+            set(key, value) {
+                if (typeof localStorage === "undefined")
+                    return;
+                try {
+                    localStorage.setItem(key, value);
+                }
+                catch (e) {
+                    // Handle quota exceeded errors
+                    console.warn("Cache storage quota exceeded, clearing cache");
+                    void this.clear();
+                    try {
+                        localStorage.setItem(key, value);
+                    }
+                    catch (e) {
+                        console.error("Failed to set cache item even after clearing cache");
+                    }
+                }
+            },
+            has(key) {
+                if (typeof localStorage === "undefined")
+                    return false;
+                return localStorage.getItem(key) !== null;
+            },
+            delete(key) {
+                if (typeof localStorage === "undefined")
+                    return;
+                localStorage.removeItem(key);
+            },
+            clear() {
+                if (typeof localStorage === "undefined")
+                    return;
+                localStorage.clear();
+            },
+        };
+    }
+    /**
+     * Create a sessionStorage-based storage provider
+     */
+    function createSessionStorageStorage() {
+        return {
+            get(key) {
+                if (typeof sessionStorage === "undefined")
+                    return null;
+                return sessionStorage.getItem(key);
+            },
+            set(key, value) {
+                if (typeof sessionStorage === "undefined")
+                    return;
+                try {
+                    sessionStorage.setItem(key, value);
+                }
+                catch (e) {
+                    // Handle quota exceeded errors
+                    console.warn("Cache storage quota exceeded, clearing cache");
+                    void this.clear();
+                    try {
+                        sessionStorage.setItem(key, value);
+                    }
+                    catch (e) {
+                        console.error("Failed to set cache item even after clearing cache");
+                    }
+                }
+            },
+            has(key) {
+                if (typeof sessionStorage === "undefined")
+                    return false;
+                return sessionStorage.getItem(key) !== null;
+            },
+            delete(key) {
+                if (typeof sessionStorage === "undefined")
+                    return;
+                sessionStorage.removeItem(key);
+            },
+            clear() {
+                if (typeof sessionStorage === "undefined")
+                    return;
+                sessionStorage.clear();
+            },
+        };
+    }
+    /**
+     * Create a storage provider from a cache options object
+     */
+    function createStorageProvider(options) {
+        const { storage } = options || {};
+        if (!storage) {
+            // Default to memory storage
+            return createMemoryStorage();
+        }
+        // Check if storage is already a StorageProvider
+        if (typeof storage.get === "function" && typeof storage.set === "function") {
+            return storage;
+        }
+        // Check if it's localStorage or sessionStorage
+        if (storage === localStorage) {
+            return createLocalStorageStorage();
+        }
+        if (storage === sessionStorage) {
+            return createSessionStorageStorage();
+        }
+        // Check if it's a Map
+        if (storage instanceof Map) {
+            return {
+                get(key) {
+                    return storage.get(key) || null;
+                },
+                set(key, value, _ttl) {
+                    storage.set(key, value);
+                },
+                has(key) {
+                    return storage.has(key);
+                },
+                delete(key) {
+                    storage.delete(key);
+                },
+                clear() {
+                    storage.clear();
+                },
+            };
+        }
+        // Default to memory storage
+        console.warn("Unsupported storage type, falling back to memory storage");
+        return createMemoryStorage();
+    }
+
+    /**
+     * Cache manager that handles storage operations
+     */
+    class CacheManager {
+        constructor(options = {}) {
+            this.entryCount = 0;
+            this.totalSize = 0;
+            this.options = options;
+            this.storage = createStorageProvider(options);
+        }
+        /**
+         * Generate a cache key based on request details
+         */
+        generateKey(url, method, headers, body) {
+            // Use custom key generator if provided
+            if (this.options.keyGenerator) {
+                const customKey = this.options.keyGenerator(url, method, headers, body);
+                return this.options.keyPrefix ? `${this.options.keyPrefix}:${customKey}` : customKey;
+            }
+            // Default key generation
+            let key = `${method}:${url}`;
+            // Add vary headers to key if specified
+            if (this.options.varyByHeaders && headers) {
+                const varyHeaders = {};
+                this.options.varyByHeaders.forEach(header => {
+                    const normalizedHeader = header.toLowerCase();
+                    // Find the header in case-insensitive way
+                    Object.keys(headers).forEach(h => {
+                        if (h.toLowerCase() === normalizedHeader) {
+                            varyHeaders[normalizedHeader] = headers[h];
+                        }
+                    });
+                });
+                if (Object.keys(varyHeaders).length > 0) {
+                    key += `:${JSON.stringify(varyHeaders)}`;
+                }
+            }
+            // Include body in cache key for non-GET requests if it's a simple value
+            if (method !== "GET" && body !== undefined && body !== null) {
+                try {
+                    if (typeof body === "string" || typeof body === "number" || typeof body === "boolean") {
+                        key += `:${String(body)}`;
+                    }
+                    else if (typeof body === "object") {
+                        key += `:${JSON.stringify(body)}`;
+                    }
+                }
+                catch (e) {
+                    console.warn("Failed to stringify request body for cache key");
+                }
+            }
+            // Add prefix if specified
+            return this.options.keyPrefix ? `${this.options.keyPrefix}:${key}` : key;
+        }
+        /**
+         * Get a value from cache
+         */
+        async get(key) {
+            const value = await Promise.resolve(this.storage.get(key));
+            if (!value)
+                return null;
+            try {
+                const entry = JSON.parse(value);
+                // Check if the entry has expired
+                if (entry.expiry && entry.expiry < Date.now()) {
+                    await Promise.resolve(this.storage.delete(key));
+                    return null;
+                }
+                return entry;
+            }
+            catch (e) {
+                // If we can't parse the cached value, remove it
+                await Promise.resolve(this.storage.delete(key));
+                return null;
+            }
+        }
+        /**
+         * Set a value in cache
+         */
+        async set(key, value, headers) {
+            const now = Date.now();
+            const ttl = this.options.ttl;
+            const entry = {
+                value,
+                timestamp: now,
+                expiry: ttl ? now + ttl : null,
+                headers,
+            };
+            const serialized = JSON.stringify(entry);
+            // Check size constraints if applicable
+            if (this.options.maxSize) {
+                const maxBytes = parseSize(this.options.maxSize);
+                const entrySize = new TextEncoder().encode(serialized).length;
+                // If a single entry exceeds the max size, reject it without clearing the cache
+                if (entrySize > maxBytes) {
+                    console.warn(`Cache entry size (${entrySize} bytes) exceeds maximum cache size (${maxBytes} bytes)`);
+                    return;
+                }
+                // Only clear if adding this entry would exceed the total limit
+                if (this.totalSize + entrySize > maxBytes) {
+                    // Simple strategy: clear everything
+                    // A more sophisticated strategy would remove oldest entries first
+                    await Promise.resolve(this.storage.clear());
+                    this.totalSize = 0;
+                    this.entryCount = 0;
+                }
+                this.totalSize += entrySize;
+            }
+            // Check max entries constraint
+            if (this.options.maxEntries) {
+                this.entryCount++;
+                if (this.entryCount > this.options.maxEntries) {
+                    // Simple strategy: clear everything
+                    // A more sophisticated strategy would use LRU cache
+                    await Promise.resolve(this.storage.clear());
+                    this.entryCount = 1;
+                }
+            }
+            // Pass ttl to storage provider if available
+            await Promise.resolve(this.storage.set(key, serialized, ttl));
+        }
+        /**
+         * Check if a key exists in the cache
+         */
+        async has(key) {
+            return Promise.resolve(this.storage.has(key));
+        }
+        /**
+         * Delete a key from the cache
+         */
+        async delete(key) {
+            return Promise.resolve(this.storage.delete(key));
+        }
+        /**
+         * Clear the entire cache
+         */
+        async clear() {
+            this.entryCount = 0;
+            this.totalSize = 0;
+            return Promise.resolve(this.storage.clear());
+        }
+    }
+
     /**
      * Global configuration for create-request
      */
@@ -452,6 +777,7 @@
             };
             this.queryParams = new URLSearchParams();
             this.autoApplyCsrfProtection = true;
+            this.cacheEnabled = false;
         }
         withHeaders(headers) {
             this.requestOptions.headers = {
@@ -714,6 +1040,16 @@
                 "X-Requested-With": "XMLHttpRequest",
             });
         }
+        /**
+         * Enables caching for the request with the specified options
+         * @param options The cache configuration options
+         * @returns The instance for chaining
+         */
+        withCache(options = {}) {
+            this.cacheEnabled = true;
+            this.cacheManager = new CacheManager(options);
+            return this;
+        }
         /**
          * Send the request to the specified URL
          * @param url The URL to send the request to
@@ -763,8 +1099,15 @@
                 ...this.requestOptions,
                 method: this.method,
             };
-            // Create the base promise
-            const basePromise = !this.requestOptions.retries ? this.executeRequest(url, fetchOptions) : this.executeWithRetries(url, fetchOptions);
+            // Create the base promise - handle caching if enabled
+            let basePromise;
+            if (this.cacheEnabled && this.cacheManager) {
+                const cacheKey = this.cacheManager.generateKey(url, this.method, this.requestOptions.headers, this.requestOptions.body);
+                basePromise = this.executeWithCache(url, fetchOptions, cacheKey);
+            }
+            else {
+                basePromise = !this.requestOptions.retries ? this.executeRequest(url, fetchOptions) : this.executeWithRetries(url, fetchOptions);
+            }
             const responsePromise = basePromise;
             // Attach convenience methods that begin processing immediately
             responsePromise.getJson = async () => {
@@ -903,6 +1246,48 @@
                 }
             }
         }
+        /**
+         * Executes a request using cache when possible
+         * @param url The formatted URL to send the request to
+         * @param fetchOptions The fetch options to use
+         * @param cacheKey The cache key for this request
+         */
+        async executeWithCache(url, fetchOptions, cacheKey) {
+            // Try to get from cache first
+            if (this.cacheManager) {
+                const cachedEntry = await this.cacheManager.get(cacheKey);
+                if (cachedEntry) {
+                    // Create a synthetic Response object from cached data
+                    const cachedResponse = new Response(JSON.stringify(cachedEntry.value), {
+                        status: 200,
+                        headers: new Headers(cachedEntry.headers || {}),
+                    });
+                    return new ResponseWrapper(cachedResponse);
+                }
+            }
+            // Not in cache, make the actual request
+            const response = await (!this.requestOptions.retries ? this.executeRequest(url, fetchOptions) : this.executeWithRetries(url, fetchOptions));
+            // Cache the successful response if caching is enabled
+            // Only cache successful responses
+            if (response.ok && this.cacheManager) {
+                // Clone the response so we don't consume it
+                try {
+                    const responseData = await response.getJson();
+                    // Extract headers to store in cache
+                    const headers = {};
+                    response.headers.forEach((value, key) => {
+                        headers[key] = value;
+                    });
+                    // Store in cache
+                    await this.cacheManager.set(cacheKey, responseData, headers);
+                }
+                catch (error) {
+                    // Failed to cache, but we can still return the response
+                    console.warn("Failed to cache response:", error);
+                }
+            }
+            return response;
+        }
     }
 
     /**
@@ -1068,6 +1453,7 @@
         config: Config.getInstance(),
     };
 
+    exports.CacheManager = CacheManager;
     exports.CookieUtils = CookieUtils;
     exports.DeleteRequest = DeleteRequest;
     exports.GetRequest = GetRequest;
@@ -1078,6 +1464,9 @@
     exports.PutRequest = PutRequest;
     exports.RequestError = RequestError;
     exports.ResponseWrapper = ResponseWrapper;
+    exports.createLocalStorageStorage = createLocalStorageStorage;
+    exports.createMemoryStorage = createMemoryStorage;
+    exports.createSessionStorageStorage = createSessionStorageStorage;
     exports["default"] = create;
 
     Object.defineProperty(exports, '__esModule', { value: true });

package/dist/library/types/cache.d.ts

@@ -0,0 +1,62 @@
+import type { StorageProvider } from "../utils/StorageProvider";
+/**
+ * Cache entry with metadata
+ */
+export interface CacheEntry {
+    value: any;
+    expiry: number | null;
+    timestamp: number;
+    headers?: Record<string, string>;
+}
+/**
+ * Options for cache configuration
+ */
+export interface CacheOptions {
+    /**
+     * Storage provider to use for caching
+     * Default is memory cache (new Map())
+     */
+    storage?: StorageProvider | Storage | Map<string, any>;
+    /**
+     * Time to live in milliseconds
+     * Default is no expiration
+     */
+    ttl?: number;
+    /**
+     * Custom key generator function
+     * @param url Request URL
+     * @param method Request method
+     * @param headers Request headers
+     * @param body Request body
+     */
+    keyGenerator?: (url: string, method: string, headers?: Record<string, string>, body?: any) => string;
+    /**
+     * Headers to vary the cache by
+     * If these headers change, a new cache entry will be created
+     */
+    varyByHeaders?: string[];
+    /**
+     * Maximum number of entries in the cache
+     * Only applicable for memory cache (Map)
+     */
+    maxEntries?: number;
+    /**
+     * Maximum size of the cache in bytes or with units (e.g. "10MB")
+     * String format supports KB, MB, GB (case-insensitive)
+     */
+    maxSize?: number | string;
+    /**
+     * Prefix for cache keys
+     * Useful for namespacing cache entries
+     */
+    keyPrefix?: string;
+}
+/**
+ * Type for cacheable response data
+ */
+export type CacheableResponse = {
+    data: any;
+    headers: Record<string, string>;
+    status: number;
+    statusText: string;
+};

package/dist/library/utils/CacheManager.d.ts

@@ -0,0 +1,35 @@
+import type { CacheEntry, CacheOptions } from "../types/cache";
+/**
+ * Cache manager that handles storage operations
+ */
+export declare class CacheManager {
+    private storage;
+    private options;
+    private entryCount;
+    private totalSize;
+    constructor(options?: CacheOptions);
+    /**
+     * Generate a cache key based on request details
+     */
+    generateKey(url: string, method: string, headers?: Record<string, string>, body?: unknown): string;
+    /**
+     * Get a value from cache
+     */
+    get(key: string): Promise<CacheEntry | null>;
+    /**
+     * Set a value in cache
+     */
+    set(key: string, value: unknown, headers?: Record<string, string>): Promise<void>;
+    /**
+     * Check if a key exists in the cache
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Delete a key from the cache
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear the entire cache
+     */
+    clear(): Promise<void>;
+}

package/dist/library/utils/CacheStorage.d.ts

@@ -0,0 +1,57 @@
+import type { CacheEntry, CacheOptions } from "../types/cache";
+import type { StorageProvider } from "./StorageProvider";
+/**
+ * Parse size strings like "10MB" into bytes
+ * @param size Size as number or string with units
+ */
+export declare function parseSize(size: string | number): number;
+/**
+ * Create a memory storage provider using Map
+ */
+export declare function createMemoryStorage(): StorageProvider;
+/**
+ * Create a localStorage-based storage provider
+ */
+export declare function createLocalStorageStorage(): StorageProvider;
+/**
+ * Create a sessionStorage-based storage provider
+ */
+export declare function createSessionStorageStorage(): StorageProvider;
+/**
+ * Create a storage provider from a cache options object
+ */
+export declare function createStorageProvider(options?: CacheOptions): StorageProvider;
+/**
+ * Cache manager that handles storage operations
+ */
+export declare class CacheManager {
+    private storage;
+    private options;
+    private entryCount;
+    private totalSize;
+    constructor(options?: CacheOptions);
+    /**
+     * Generate a cache key based on request details
+     */
+    generateKey(url: string, method: string, headers?: Record<string, string>, body?: any): string;
+    /**
+     * Get a value from cache
+     */
+    get(key: string): Promise<CacheEntry | null>;
+    /**
+     * Set a value in cache
+     */
+    set(key: string, value: unknown, headers?: Record<string, string>): Promise<void>;
+    /**
+     * Check if a key exists in the cache
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Delete a key from the cache
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear the entire cache
+     */
+    clear(): Promise<void>;
+}

package/dist/library/utils/StorageProvider.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Interface for storage providers used by the cache system
+ */
+export interface StorageProvider {
+    /**
+     * Get a value from storage
+     * @param key The key to retrieve
+     * @returns The stored value or null if not found
+     */
+    get(key: string): Promise<string | null> | string | null;
+    /**
+     * Set a value in storage
+     * @param key The key to store
+     * @param value The value to store
+     * @param ttl Optional TTL in milliseconds
+     * @returns Promise or void
+     */
+    set(key: string, value: string, ttl?: number): Promise<void> | void;
+    /**
+     * Check if a key exists in storage
+     * @param key The key to check
+     */
+    has(key: string): Promise<boolean> | boolean;
+    /**
+     * Delete a value from storage
+     * @param key The key to delete
+     */
+    delete(key: string): Promise<void> | void;
+    /**
+     * Clear all values from storage
+     */
+    clear(): Promise<void> | void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-request",
-  "version": "0.0.1-beta.6",
+  "version": "0.0.1-beta.7",
   "description": "A modern, chainable wrapper for fetch with automatic retries, timeouts, comprehensive error handling, and first-class TypeScript support",
   "main": "dist/library/index.js",
   "module": "dist/library/index.esm.js",