create-request 0.0.1-beta.5 → 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;
@@ -57,10 +61,10 @@ export declare abstract class BaseRequest {
     /**
      * Adds a single query parameter
      * @param key - The parameter name
-     * @param value - The parameter value
+     * @param value - The parameter value, can be a single value or array of values
      * @returns The instance for chaining
      */
-    withQueryParam(key: string, value: string | number | boolean | null | undefined): this;
+    withQueryParam(key: string, value: string | string[] | number | boolean | null | undefined): this;
     /**
      * Sets the mode of the request
      * @param mode - The mode for the request (cors, no-cors, same-origin, navigate)
@@ -86,12 +90,24 @@ export declare abstract class BaseRequest {
      * @returns The instance for chaining
      */
     withBasicAuth(username: string, password: string): this;
+    /**
+     * Cross-environment base64 encoding
+     * Works in both browser and Node.js environments
+     */
+    private encodeBase64;
     /**
      * Sets the bearer token for authentication
      * @param token - The bearer token
      * @returns The instance for chaining
      */
     withBearerToken(token: string): this;
+    /**
+     * Helper function to check for header presence in a case-insensitive way
+     * @param headers Headers object
+     * @param headerName Header name to check
+     * @returns Boolean indicating if the header exists (case-insensitive)
+     */
+    private hasHeader;
     /**
      * Sets cookies for the request
      * @param cookies Object containing cookie name-value pairs or cookie options
@@ -123,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
@@ -142,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/BodyRequest.d.ts

@@ -5,7 +5,6 @@ import type { Body } from "./types";
  */
 export declare abstract class BodyRequest extends BaseRequest {
     protected body?: Body;
-    private bodyProcessed;
     private bodyType?;
     /**
      * Sets the body of the request

package/dist/library/ResponseWrapper.d.ts

@@ -2,55 +2,22 @@
  * Wrapper for HTTP responses with methods to transform the response data
  */
 export declare class ResponseWrapper {
-    readonly ok: boolean;
-    private response;
+    private readonly response;
+    private textCache;
+    private jsonCache;
+    private blobCache;
+    private arrayBufferCache;
+    private bodyUsed;
     constructor(response: Response);
-    /**
-     * Get the raw Response object
-     */
-    get raw(): Response;
-    /**
-     * Get the HTTP status code
-     */
     get status(): number;
-    /**
-     * Get the HTTP status text
-     */
     get statusText(): string;
-    /**
-     * Get response headers
-     */
     get headers(): Headers;
-    /**
-     * Parse response as JSON
-     */
+    get ok(): boolean;
+    get raw(): Response;
     getJson<T = unknown>(): Promise<T>;
-    /**
-     * Get response as text
-     */
     getText(): Promise<string>;
-    /**
-     * Get response as Blob
-     */
     getBlob(): Promise<Blob>;
-    /**
-     * Get response as ArrayBuffer
-     */
     getArrayBuffer(): Promise<ArrayBuffer>;
-    /**
-     * Get response as ReadableStream for true streaming consumption.
-     * This allows you to process data incrementally as it arrives.
-     *
-     * @example
-     * const stream = await request.sendTo('https://example.com/large-file').getBody();
-     * const reader = stream.getReader();
-     *
-     * while (true) {
-     *   const { done, value } = await reader.read();
-     *   if (done) break;
-     *   // Process chunk of data in 'value'
-     * }
-     */
     getBody(): ReadableStream<Uint8Array> | null;
 }
 /**

package/dist/library/index.d.ts

@@ -1,11 +1,15 @@
 import { get, put, head, post, patch, del, options } from "./requestFactories";
 import { Config } from "./utils/Config";
-export { HttpMethod, RequestPriority, CredentialsPolicy, RequestMode, RedirectMode, CacheMode, SameSitePolicy, } from "./enums";
+export { HttpMethod, RequestPriority, CredentialsPolicy, RequestMode, RedirectMode, CacheMode, SameSitePolicy } from "./enums";
 export type { RetryCallback, RequestOptions, CookieOptions, CookiesRecord } from "./types";
 export { RequestError } from "./RequestError";
 export { ResponseWrapper } from "./ResponseWrapper";
 export { CookieUtils } from "./utils/CookieUtils";
-export { GetRequest, PostRequest, PutRequest, DeleteRequest, PatchRequest, HeadRequest, OptionsRequest, } from "./requestMethods";
+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;