create-request 0.0.1-beta.2 → 0.0.1-beta.20

package/README.md

@@ -1,467 +1,590 @@
 # create-request
 
 [![npm version](https://img.shields.io/npm/v/create-request.svg)](https://www.npmjs.com/package/create-request)
-[![License](https://img.shields.io/npm/l/create-request.svg)](https://github.com/yourusername/create-request/blob/main/LICENSE)
+[![License](https://img.shields.io/npm/l/create-request.svg)](https://github.com/DanielAmenou/create-request/blob/main/LICENSE)
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/create-request)](https://bundlephobia.com/package/create-request)
+[![TypeScript](https://img.shields.io/badge/TypeScript-4.7%2B-blue)](https://www.typescriptlang.org/)
 
 `create-request` is a modern TypeScript library that transforms how you make API calls. Built as an elegant wrapper around the native Fetch API, it provides a chainable, fluent interface that dramatically reduces boilerplate while adding powerful features like automatic retries, timeout handling, and comprehensive error management.
 
-With first-class TypeScript support, built-in response parsing, and intuitive authentication helpers, `create-request` makes your API code more readable, more reliable, and fully type-safe—all with zero dependencies and a tiny footprint.
+## Table of Contents
+
+- [Core Features](#core-features)
+- [Why create-request](#why-create-request)
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+- [Advanced Usage](#advanced-usage)
+- [TypeScript Support](#typescript-support)
+- [CSRF Protection](#csrf-protection)
+- [Performance Considerations](#performance-considerations)
+- [Browser Support](#browser-support)
+- [Comparison of JavaScript HTTP Client Libraries](#comparison-of-javascript-http-client-libraries)
+- [License](#license)
+
+## Core Features
+
+- 🚀 **Performance** - Tiny bundle size with zero dependencies
+- 🚧 **Error Handling** - Detailed error info with custom error class
+- ⛓️ **Chainable API** - Build and execute requests with a fluent interface
+- ⏱️ **Timeout Support** - Set timeouts for requests with automatic aborts
+- 🛡️ **Type Safety** - Full TypeScript support with intelligent type inference
+- 🔐 **Auth Helpers** - Simple methods for common authentication patterns
+- 🔍 **Data Selection** - Extract and transform specific data from responses
+- 🔁 **Automatic Retries** - Retry failed requests with customizable settings
+- 📉 **Reduced Boilerplate** - Write 60% less code for common API operations
+- 🔒 **CSRF Protection** - Built-in safeguards against cross-site request forgery
+- 📝 **Response Caching** - Flexible caching system with multiple storage options
+- 🛑 **Request Cancellation** - Abort requests on demand with AbortController integration
 
 ## Why create-request?
 
-**You've probably been here before:** writing boilerplate fetch code, handling retries manually, struggling with timeouts, or wrestling with TypeScript types for your API responses. `create-request` solves all of that with an elegant, chainable API:
+**API interactions often require repetitive code patterns** - handling HTTP status checks, parsing responses, managing errors, and dealing with TypeScript types. `create-request` provides a clean, efficient solution with an elegant API that separates request building from execution:
+
+### With Regular Fetch
 
 ```typescript
-// Instead of verbose fetch code with manual JSON parsing, error handling, etc.
-// You get a clean, intuitive API that just works
-const users = await create.get()
-  .withTimeout(5000)
-  .withRetries(3)
-  .withBearerToken('your-token')
-  .sendTo('https://api.example.com/users')
-  .json<User[]>(); // Fully typed response!
+async function createUser(userData) {
+  try {
+    const response = await fetch("https://api.example.com/users", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: "Basic " + btoa("username:password"),
+      },
+      body: JSON.stringify(userData),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+    const data = await response.json();
+    return data;
+  } catch (error) {
+    console.error("Fetch error:", error);
+    throw error;
+  }
+}
 ```
 
-## 🚀 Designed for Developer Happiness
-
-- **Write Less Code** - Accomplish in one line what might take dozens with raw fetch
-- **Fewer Bugs** - Strong typing and smart defaults prevent common API bugs
-- **Self-Documenting** - Chainable API clearly expresses intent for easier code reviews
-- **Universal** - Works the same in browser and Node.js environments
-
-## Overview
+### With create-request
 
-`create-request` provides a chainable, fluent API for making HTTP requests with built-in solutions for the most common API challenges. It's designed for developers who value clean code, type safety, and robust error handling.
-
-## Features
-
-- 🔄 **Fully Typed** - Complete TypeScript support with accurate type definitions
-- 🔗 **Chainable API** - Fluent interface for building requests
-- ⏱️ **Timeout Support** - Set timeouts for any request (no more hanging requests!)
-- 🔁 **Automatic Retries** - Smart retry mechanism with customizable strategies
-- 🔒 **Auth Helpers** - One-liner methods for common auth patterns
-- 🧩 **Query Parameter Management** - Easy query parameter handling with arrays support
-- 📦 **Response Transformations** - Parse responses as JSON, text, blob, etc.
-- 🚫 **Robust Error Handling** - Detailed error information with custom error class
-- 🔌 **Zero Dependencies** - Built on the native Fetch API with no external baggage
-- 🌐 **Universal** - Works exactly the same in all modern browsers and Node.js
-- 🧠 **Smart Content-Type** - Automatic content type detection for request bodies
-- 🏷️ **Type Safety** - Enums for all string constants to prevent typos
+```typescript
+import create from "create-request";
+
+function createUser(userData) {
+  return create
+    .post()
+    .withBasicAuth("username", "password")
+    .withBody(userData) // Content-Type automatically set to application/json
+    .sendTo("https://api.example.com/users")
+    .getData<User>() // Type-safe response handling
+    .catch(error => {
+      console.error("Fetch error:", error);
+      throw error;
+    });
+}
+```
 
 ## Installation
 
 ```bash
+# npm
 npm install create-request
-```
 
-Or with yarn:
-
-```bash
+# yarn
 yarn add create-request
+
+# pnpm
+pnpm add create-request
 ```
 
-## See the Difference: How create-request Transforms API Calls
+## Basic Usage
 
-### 1. Simplified Error Handling
+### Creating Requests
 
 ```typescript
-create.get()
-  .sendTo('https://api.example.com/data')
-  .json()
-  .then(data => {
-    // Process successful response
-    console.log(data);
-  })
-  .catch(error => {
-    if (error instanceof RequestError) {
-      // Rich error details that fetch doesn't provide:
-      console.log(`${error.status} error from ${error.method} ${error.url}`);
-      console.log(`Was it a timeout? ${error.timeoutError}`);
-
-      // Original error data still available:
-      console.log(error.response);
-    }
-  });
+import create from "create-request";
+
+// Create different request types
+const getRequest = create.get(); // GET
+const putRequest = create.put(); // PUT
+const postRequest = create.post(); // POST
+const patchRequest = create.patch(); // PATCH
+const deleteRequest = create.del(); // DELETE
+const headRequest = create.head(); // HEAD
+const optionsRequest = create.options(); // OPTIONS
 ```
 
-### 2. Type-Safe API Responses
-
-```typescript
-interface User {
-  id: number;
-  name: string;
-  email: string;
-}
+### Request Configuration
 
-// TypeScript knows exactly what you're getting back!
-const users = await create.get()
-  .sendTo('https://api.example.com/users')
-  .json<User[]>();
+The library provides a comprehensive set of configuration methods that can be chained together to customize your requests:
 
-// No more type casting or guessing - your IDE autocomplete works perfectly
-users.forEach(user => console.log(user.name));
-```
+```typescript
+import create, {
+  RequestPriority,
+  CredentialsPolicy,
+  RequestMode,
+  RedirectMode,
+  ReferrerPolicy,
+} from "create-request";
+
+// Configure request options
+const request = create
+  .get()
+  // Basic headers
+  .withHeaders({ "X-API-Key": "abc123", "Accept-Language": "en-US" })
+  .withHeader("Custom-Header", "value") // Add a single header
+
+  // Timeout settings
+  .withTimeout(5000) // Request will abort after 5 seconds
+
+  // Automatic retry configuration
+  .withRetries(3) // Retry up to 3 times on failure
+  .onRetry(({ attempt, error }) => {
+    console.log(`Attempt ${attempt} failed: ${error.message}. Retrying...`);
+    // You can implement backoff strategy here
+    return new Promise(resolve => setTimeout(resolve, attempt * 1000));
+  })
 
-### 3. Request Retries Made Simple
+  // Authentication methods
+  .withBearerToken("your-token") // Adds Authorization: Bearer your-token
+  .withBasicAuth("username", "password") // HTTP Basic Authentication
+  .withAuthorization("auth-scheme value") // Custom authorization header
 
-```typescript
-// Without create-request: Pages of manual retry logic with delay calculations
-// With create-request: One line
+  // Add a single cookie
+  .withCookie("language", "en-US")
 
-const data = await create.get()
-  .withRetries(3)
-  .onRetry(({ retryCount, error }) => {
-    console.log(`Retry ${retryCount} after ${error.message}`);
+  // Add multiple cookies
+  .withCookies({
+    sessionId: "abc123",
+    preferences: { value: "dark-mode", secure: true },
+    tracking: { value: "enabled", sameSite: SameSitePolicy.STRICT },
   })
-  .sendTo('https://api.example.com/flaky-endpoint')
-  .json();
+
+  // URL parameters
+  .withQueryParams({ search: "term", page: 1, limit: 20 })
+  .withQueryParam("filter", "active") // Add a single query parameter
+
+  // Request body configuration (for POST/PUT/PATCH)
+  .withContentType("application/json") // Set specific content type
+
+  // Fetch API options
+  .withCredentials(CredentialsPolicy.INCLUDE) // Includes cookies with cross-origin requests
+  .withMode(RequestMode.CORS) // Controls CORS behavior
+  .withRedirect(RedirectMode.FOLLOW) // Controls redirect behavior (follow, error, manual)
+  .withReferrer("https://example.com") // Sets request referrer
+  .withReferrerPolicy(ReferrerPolicy.NO_REFERRER_WHEN_DOWNGRADE) // Controls referrer policy
+  .withPriority(RequestPriority.HIGH) // Sets request priority
+  .withKeepAlive(true); // Keeps connection alive after the page is unloaded
 ```
 
-## Basic Usage
+Each configuration method returns the request object, allowing for a fluent interface where methods can be chained together. You can configure only what you need for a specific request:
 
 ```typescript
-import create from 'create-request';
-
-// Simple GET request with chained response parsing
-const users = await create.get()
-  .withTimeout(5000)
-  .sendTo('https://api.example.com/users')
-  .json(); // Parse response directly
-
-// POST request with JSON body
-const newUser = await create.post()
-  .withBody({ name: 'Daniel Amenou', email: 'daniel@example.com' })
-  .withBearerToken('your-token-here')
-  .sendTo('https://api.example.com/users')
-  .json();
+// Simple example with just what's needed
+const searchUsers = create
+  .get()
+  .withBearerToken(userToken)
+  .withQueryParams({ q: searchTerm, limit: 20 })
+  .withTimeout(3000);
+
+// Now execute the request
+const users = await searchUsers.sendTo("https://api.example.com/users").getData();
 ```
 
-## API Reference
-
-### Request Creation
-
-Create requests using the appropriate factory method:
+You can also create reusable base requests with common settings:
 
 ```typescript
-// Methods without body
-create.get()
-create.del()
-create.head()
-create.options()
-
-// Methods with body
-create.put()
-create.post()
-create.patch()
-```
-
-### Request Configuration
+// Create base authenticated request
+const apiBase = create
+  .get()
+  .withHeaders({
+    "X-API-Version": "1.2",
+    "Accept-Language": "en-US",
+  })
+  .withBearerToken(authToken)
+  .withTimeout(5000)
+  .withRetries(2);
 
-All requests support these configuration methods:
+// Use the base request for different endpoints
+const users = await apiBase.sendTo("https://api.example.com/users").getData();
+const products = await apiBase.sendTo("https://api.example.com/products").getData();
+```
 
-#### Common Settings
+### Request Bodies (POST/PUT/PATCH)
 
 ```typescript
-import { RequestPriority, CredentialsPolicy, RequestMode, RedirectMode } from 'create-request';
+// JSON body (Content-Type automatically set to application/json)
+const jsonRequest = create.post().withBody({ name: "John", age: 30 });
 
-// Set request headers
-.withHeaders({ 'X-API-Key': 'abc123' })
+// String body (Content-Type automatically set to text/plain)
+const textRequest = create.post().withBody("Plain text content");
 
-// Set cookies
-.withCookies({
-  sessionId: 'abc123',
-  preference: 'darkMode',
-  region: 'us-east'
-})
+// Form data
+const formData = new FormData();
+formData.append("name", "John");
+formData.append("file", fileBlob);
 
-// Set a single content type header
-.withContentType('application/json')
+const formRequest = create.post().withBody(formData);
 
-// Set request timeout in milliseconds
-.withTimeout(5000)
+// URLSearchParams (typically used for application/x-www-form-urlencoded)
+const params = new URLSearchParams();
+params.append("username", "john");
+params.append("password", "secret");
 
-// Configure retry behavior
-.withRetries(3)
-.onRetry(({ retryCount, error }) => {
-  console.log(`Retry ${retryCount} after error: ${error.message}`);
-})
-
-// Use an external abort controller
-.withAbortController(myAbortController)
-
-// Set credentials policy - uses same-origin by default
-.withCredentials(CredentialsPolicy.INCLUDE)
+const formUrlEncodedRequest = create.post().withBody(params);
+```
 
-// Set redirect behavior
-.withRedirect(RedirectMode.FOLLOW)
+### Executing Requests
 
-// Set request mode
-.withMode(RequestMode.CORS)
+```typescript
+// Simple execution
+const response = await request.sendTo("https://api.example.com/endpoint");
+
+// With direct data extraction
+const jsonData = await request.sendTo("https://api.example.com/endpoint").getJson();
+const textData = await request.sendTo("https://api.example.com/endpoint").getText();
+const blobData = await request.sendTo("https://api.example.com/endpoint").getBlob();
+const bodyStream = await request.sendTo("https://api.example.com/endpoint").getBody();
+const arrayBuffer = await request.sendTo("https://api.example.com/endpoint").getArrayBuffer();
+
+// Using the data selector API to extract specific data
+const userData = await request
+  .sendTo("https://api.example.com/users")
+  .getData(data => data.results.users);
+
+// Using the data selector without a selector function just returns the full JSON response
+const fullData = await request.sendTo("https://api.example.com/data").getData();
+```
 
-// Set referrer
-.withReferrer('https://example.com')
+### Error Handling
 
-// Set keepalive flag (allows request to outlive the page)
-.withKeepAlive(true)
+All errors from requests are instances of `RequestError` with detailed information:
 
-// Set request priority
-.withPriority(RequestPriority.HIGH)
+```typescript
+try {
+  const data = await request.sendTo("https://api.example.com/data").getJson();
+} catch (error) {
+  // error will always be a RequestError
+  console.log(error.message); // Error message
+  console.log(error.status); // HTTP status code (if available)
+  console.log(error.url); // Request URL
+  console.log(error.method); // HTTP method
+  console.log(error.timeoutError); // Whether it was a timeout
+
+  // Access the original response if available
+  if (error.response) {
+    // Raw Response object is available
+    console.log(error.response.status);
+  }
+}
 ```
 
-#### Query Parameters
+### Caching Requests
 
 ```typescript
-// Add multiple query parameters
-.withQueryParams({
-  search: 'keyword',
-  page: 1,
-  filters: ['active', 'verified']
-})
-
-// Add a single query parameter
-.withQueryParam('sort', 'desc')
-
+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");
 ```
 
-#### Authentication
-
-```typescript
-// Basic authentication
-.withBasicAuth('username', 'password')
+## Advanced Usage
 
-// Bearer token
-.withBearerToken('your-jwt-token')
+### Request Reuse
 
-// Custom authorization header
-.withAuthorization('Custom scheme-and-token')
-```
+```typescript
+// Create a base authenticated request
+const authRequest = create.get().withBearerToken("token123").withTimeout(5000).withRetries(2);
 
-### Requests with Body
+// Reuse for different endpoints
+const users = await authRequest.sendTo("https://api.example.com/users").getJson();
+const products = await authRequest.sendTo("https://api.example.com/products").getJson();
 
-For POST, PUT, and PATCH requests, you can set a body:
+// You can also create application-wide base requests
+const apiBase = () =>
+  create
+    .get()
+    .withHeaders({
+      "X-API-Version": "1.2",
+      "Accept-Language": "en-US",
+    })
+    .withBearerToken(getAuthToken()) // Get fresh token each time
+    .withTimeout(5000);
 
-```typescript
-// JSON body (automatically sets Content-Type: application/json)
-.withBody({ name: 'John', age: 30 })
-
-// String body
-.withBody('Plain text content')
-
-// FormData
-const form = new FormData();
-form.append('file', fileBlob);
-.withBody(form)
-
-// Blob body
-const blob = new Blob(['Hello, world!'], { type: 'text/plain' });
-const request = create.post()
-  .withBody(blob)
-  .sendTo('https://api.example.com/upload');
-
-// ArrayBuffer body
-const buffer = new ArrayBuffer(8);
-const request = create.post()
-  .withBody(buffer)
-  .sendTo('https://api.example.com/upload');
-
-// ReadableStream body
-const stream = new ReadableStream();
-const request = create.post()
-  .withBody(stream)
-  .sendTo('https://api.example.com/upload');
+// Use throughout your application
+function getUsers() {
+  return apiBase().sendTo("https://api.example.com/users").getData();
+}
 
+function getProducts() {
+  return apiBase().sendTo("https://api.example.com/products").getData();
+}
 ```
 
-### Response Handling
-
-The library provides convenient methods for handling responses that can be chained directly after `sendTo()`:
+### Request Cancellation
 
 ```typescript
-// Parse as JSON with type inference
-const jsonData = await create.get()
-  .sendTo('https://api.example.com/data')
-  .json<MyDataType>();
-
-// Get as text
-const text = await create.get()
-  .sendTo('https://api.example.com/text')
-  .text();
-
-// Get as blob
-const blob = await create.get()
-  .sendTo('https://api.example.com/file')
-  .blob();
-
-// Get as ArrayBuffer
-const buffer = await create.get()
-  .sendTo('https://api.example.com/binary')
-  .arrayBuffer();
-
-// Get as ReadableStream
-const stream = await create.get()
-  .sendTo('https://api.example.com/stream')
-  .body();
-
-// For more control, you can access the raw response first
-const response = await create.get().sendTo('https://api.example.com/data');
-const status = response.status;
-const headers = response.headers;
-const data = await response.json();
-```
+const controller = new AbortController();
 
-### Error Handling
+const request = create.get().withTimeout(10000).withAbortController(controller);
 
-The library provides a `RequestError` class with details about failed requests:
+// Later, cancel the request if needed
+setTimeout(() => controller.abort(), 2000);
 
-```typescript
 try {
-  const data = await create.get()
-    .sendTo('https://api.example.com/data')
-    .json();
+  const data = await request.sendTo("https://api.example.com/slow-endpoint").getJson();
 } catch (error) {
-  if (error instanceof RequestError) {
-    console.log(error.message);     // Error message
-    console.log(error.status);      // HTTP status code (if available)
-    console.log(error.url);         // Request URL
-    console.log(error.method);      // HTTP method
-    console.log(error.timeoutError); // Whether it was a timeout
-    console.log(error.response);    // Raw response (if available)
+  if (error.name === "AbortError") {
+    console.log("Request was cancelled by user");
+  } else if (error.timeoutError) {
+    console.log("Request timed out");
+  } else {
+    console.log("Other error:", error.message);
   }
 }
 ```
 
-## Advanced Usage
+### Data Selection
 
-### Handling File Downloads
+The `getData` method provides a powerful way to extract and transform specific data from API responses:
 
 ```typescript
-const blob = await create.get()
-  .withHeaders({ Accept: 'application/pdf' })
-  .sendTo('https://api.example.com/reports/123/download')
-  .blob();
-
-const url = window.URL.createObjectURL(blob);
-
-// Create a download link
-const a = document.createElement('a');
-a.href = url;
-a.download = 'report.pdf';
-a.click();
-
-// Clean up
-window.URL.revokeObjectURL(url);
+// Extract specific properties from nested structures
+const posts = await request
+  .sendTo("https://api.example.com/feed")
+  .getData(data => data.feed.posts);
+
+// Transform data in the selector function
+const usernames = await request
+  .sendTo("https://api.example.com/users")
+  .getData(data => data.users.map(user => user.username));
+
+// Apply filtering in the selector
+const activeUsers = await request
+  .sendTo("https://api.example.com/users")
+  .getData(data => data.users.filter(user => user.isActive));
+
+// Combine data from complex nested structures
+const combinedData = await request
+  .sendTo("https://api.example.com/dashboard")
+  .getData(data => ({
+    userCount: data.stats.users.total,
+    recentPosts: data.content.recent.slice(0, 5),
+    notifications: data.user.notifications.unread,
+  }));
 ```
 
-### Working with AbortController
+When a selector fails, the error message will contain the original response data to help diagnose the issue:
 
 ```typescript
-const controller = new AbortController();
-
-// Pass the controller to the request
 try {
-  const data = await create.get()
-    .withAbortController(controller)
-    .sendTo('https://api.example.com/data')
-    .json();
+  // This will fail if the response structure doesn't match expectations
+  const result = await request
+    .sendTo("https://api.example.com/data")
+    .getData(data => data.results.items);
 } catch (error) {
-  // Handle the aborted request
+  console.error(error);
+  // Error message includes the original response data for debugging
 }
-
-// Cancel the request after 2 seconds
-setTimeout(() => controller.abort(), 2000);
 ```
 
-### Request Priority
+### Implementing Custom Storage Providers
+
+You can create your own storage provider by implementing the `StorageProvider` interface:
 
 ```typescript
-import { RequestPriority } from 'create-request';
-
-// High priority for critical resources
-const userProfile = await create.get()
-  .withPriority(RequestPriority.HIGH)
-  .sendTo('https://api.example.com/user/profile')
-  .json();
-
-// Low priority for non-critical resources
-const recommendations = await create.get()
-  .withPriority(RequestPriority.LOW)
-  .sendTo('https://api.example.com/recommendations')
-  .json();
-```
+import { StorageProvider } from "create-request";
 
-### Creating Reusable Request Configurations
+// Create a namespaced storage provider
+export function createNamespacedStorage(namespace: string): StorageProvider {
+  return {
+    get(key: string): string | null {
+      return localStorage.getItem(`${namespace}:${key}`);
+    },
 
-```typescript
-import { RequestPriority, CredentialsPolicy } from 'create-request';
+    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");
+        }
+      }
+    },
 
-function createAuthenticatedRequest(token) {
-  return create.get()
-    .withBearerToken(token)
-    .withHeaders({
-      'X-App-Version': '1.0.0',
-    })
-    .withTimeout(10000)
-    .withRetries(2)
-    .withCredentials(CredentialsPolicy.INCLUDE)
-    .withPriority(RequestPriority.HIGH);
+    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));
+    },
+  };
 }
 
-// Later use the configured request
-const users = await createAuthenticatedRequest(myToken)
-  .sendTo('https://api.example.com/users')
-  .json();
+// Usage:
+const request = create
+  .get()
+  .withCache({
+    storage: createNamespacedStorage("api-cache"),
+    ttl: 24 * 60 * 60 * 1000, // 24 hours
+  })
+  .sendTo("https://api.example.com/data");
 ```
 
-### Cookie Management
+## TypeScript Support
 
 ```typescript
-// Set multiple cookies in a single request
-const response = await create.get()
-  .withCookies({
-    sessionId: 'abc123',
-    theme: 'dark',
-    region: 'us-east',
-    'analytics-opt-in': 'true'
-  })
-  .sendTo('https://api.example.com/dashboard');
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  isActive: boolean;
+}
 
-// Combine with other header settings
-const response = await create.get()
-  .withCookies({ sessionId: 'abc123' })
-  .withBearerToken('your-token-here')
-  .sendTo('https://api.example.com/protected-resource');
+interface ApiResponse<T> {
+  data: T;
+  meta: {
+    total: number;
+    page: number;
+  };
+}
+
+// Type the full response
+const response = await create
+  .get()
+  .sendTo("https://api.example.com/users")
+  .getJson<ApiResponse<User[]>>();
+
+// Or use getData with type parameters
+const users = await create
+  .get()
+  .sendTo("https://api.example.com/users")
+  .getData<ApiResponse<User[]>, User[]>(data => data.data);
+
+// TypeScript knows the types
+users.forEach(user => {
+  console.log(`${user.name} (${user.email}): ${user.isActive ? "Active" : "Inactive"}`);
+});
+
+// Function with proper types
+async function getUserById(id: number): Promise<User> {
+  return create
+    .get()
+    .withQueryParam("id", id)
+    .sendTo("https://api.example.com/users")
+    .getData<ApiResponse<User[]>, User>(data => {
+      const user = data.data[0];
+      if (!user) throw new Error(`User with ID ${id} not found`);
+      return user;
+    });
+}
 ```
 
-## Environment-Specific Limitations
+## CSRF Protection
+
+Cross-Site Request Forgery (CSRF) is a type of security vulnerability where unauthorized commands are executed on behalf of an authenticated user. `create-request` provides built-in protection mechanisms to help prevent CSRF attacks.
 
-### Browser Limitations
+### How CSRF Protection Works
 
-1. **CORS Restrictions** - Browsers enforce Same-Origin Policy and CORS. Requests to different origins must have proper CORS headers set up server-side.
+The library employs multiple strategies to protect against CSRF attacks:
 
-2. **Cookies and Authentication** - Third-party cookies might be blocked depending on browser settings. Use `withCredentials(CredentialsPolicy.INCLUDE)` for cross-origin authenticated requests.
+1. **Automatic X-Requested-With Header**: By default, all requests include the `X-Requested-With: XMLHttpRequest` header, which helps servers identify legitimate AJAX requests.
 
-3. **Mixed Content** - Browsers block HTTP requests from HTTPS pages. Always use HTTPS endpoints in production.
+2. **CSRF Token Support**: The library can automatically include CSRF tokens in request headers, which servers can validate to ensure the request came from your application.
 
-4. **Content Security Policy (CSP)** - If your application uses CSP, you must configure it to allow connections to your API endpoints.
+3. **XSRF Cookie Reading**: For frameworks that use the double-submit cookie pattern (like Laravel, Rails, or Django), the library can automatically read XSRF tokens from cookies and include them in request headers.
 
-5. **Priority Hints** - The `withPriority` feature is only supported in some modern browsers and may be ignored in others.
+### Global CSRF Configuration
 
-6. **KeepAlive** - The `withKeepAlive` feature allows requests to outlive the page but has varying support across browsers.
+You can configure CSRF settings globally for all requests:
 
-### Server-Side (Node.js) Limitations
+```typescript
+// Configure CSRF settings for all requests
+create.config.setCsrfToken("your-csrf-token");
+create.config.setCsrfHeaderName("X-CSRF-Token"); // Default header name
+create.config.setXsrfCookieName("XSRF-TOKEN"); // Default cookie name
+create.config.setEnableAntiCsrf(true); // Enable/disable X-Requested-With header
+create.config.setEnableAutoXsrf(true); // Enable/disable automatic cookie-to-header token
+```
 
-1. **Missing Node.js Fetch** - Prior to Node 18, the Fetch API isn't available natively.
+### Per-Request CSRF Settings
 
-2. **Self-signed Certificates** - Node.js rejects self-signed certificates by default. You may need additional configuration for development environments.
+You can also configure CSRF protection on individual requests:
 
-3. **Memory Management** - When downloading large files or processing large responses, be mindful of memory consumption, especially when using `arrayBuffer()` or `blob()`.
+```typescript
+// Configure CSRF for a specific request
+const request = create
+  .post()
+  .withCsrfToken("request-specific-token") // Set a specific token
+  .withAntiCsrfHeaders() // Explicitly add X-Requested-With header
+  .withoutCsrfProtection(); // Or disable all automatic CSRF protection
+```
 
-4. **Proxy Support** - Additional configuration may be needed to work with HTTP proxies in Node.js.
+### Integrating with Backend Frameworks
 
-5. **Limited Feature Support** - Features like `withKeepAlive` and `withPriority` might not be relevant or fully supported in Node.js environments.
+Most modern frameworks support CSRF protection out of the box. The library works seamlessly with:
 
-## Browser Compatibility
+- **Laravel**: Automatically reads XSRF-TOKEN cookie and sends X-XSRF-TOKEN header
+- **Rails**: Works with the Rails CSRF token system
+- **Django**: Compatible with Django's CSRF middleware
+- **Express.js + csurf**: Works with the csurf middleware token pattern
+
+## Performance Considerations
+
+create-request is designed to be lightweight and efficient:
+
+- **Zero Dependencies**: No extra libraries to load
+- **Tree-Shakable**: Only import what you need
+- **Minimal Overhead**: Thin wrapper around the native Fetch API
+- **Memory Efficient**: Doesn't create unnecessary objects
+- **Cache Management**: Configurable caching to reduce network requests
+
+## Browser Support
 
 This library works with all browsers that support the Fetch API:
 
@@ -471,104 +594,33 @@ This library works with all browsers that support the Fetch API:
 - Edge 14+
 - Opera 29+
 
-## Comparison with Other Libraries
-
-| Feature | create-request | axios | fetch |
-|---------|---------------|-------|-------|
-| Bundle Size | Small (~2KB) | Medium (~14KB) | Smallest (built-in) |
-| TypeScript Support | Full with type inference | Partial | Manual |
-| Type Safety | Enums for constants | Limited | None |
-| Chainable API | ✅ Yes | ❌ No | ❌ No |
-| Request Cancellation | ✅ Yes (AbortController) | ✅ Yes | ✅ Yes (manual) |
-| Auto JSON | ✅ Yes | ✅ Yes | ❌ No |
-| Timeout | ✅ Yes | ✅ Yes | ❌ No (manual) |
-| Retries | ✅ Yes | ❌ No (needs addon) | ❌ No (manual) |
-| Query params with arrays | ✅ Yes | ✅ Yes | ❌ No (manual) |
-| Request Priority | ✅ Yes (simple API) | ❌ No | ✅ Yes (via options) |
-| KeepAlive | ✅ Yes (simple API) | ❌ No | ✅ Yes (via options) |
-| Learning Curve | Low | Medium | Medium |
-
-### Why Not Just Use fetch?
-like JSON parsing
-The native Fetch API is powerful but low-level, requiring you to:ing
-- Write boilerplate for common tasks like JSON parsing
-- Manually implement timeout handlingeps
-- Create your own retry mechanisms- Parse non-2xx responses manually
-- Handle errors across multiple steps
-- Parse non-2xx responses manually`create-request` gives you all these features with a cleaner API that's designed specifically for modern TypeScript applications.
-
-`create-request` gives you all these features with a cleaner API that's designed specifically for modern TypeScript applications.### Why Not axios?
-
-### Why Not axios?est` offers:
-
-While axios is popular, `create-request` offers:er)
-- Smaller bundle size (~85% smaller)n
-- More complete TypeScript integration
-- Built-in retries without addons- Modern features like priority hints
-- Modern features like priority hintsainable API
-- A more intuitive, chainable API
-
-## Real-world Examples
-t for Authentication
-### API Client for Authentication
-
-```typescripta reusable authentication client
-// Create a reusable authentication client
-function createAuthClient(baseUrl) {
-  return {{
-    login: async (email, password) => {
-      return create.post()
-        .withBody({ email, password })eout(3000)
-        .withTimeout(3000)  .sendTo(`${baseUrl}/auth/login`)
-        .sendTo(`${baseUrl}/auth/login`)        .json();
-        .json();
-    },
-en) => {
-    refreshToken: async (refreshToken) => {t()
-      return create.post()
-        .withBody({ refreshToken })ries(2)
-        .withRetries(2)   .sendTo(`${baseUrl}/auth/refresh`)
-        .sendTo(`${baseUrl}/auth/refresh`)    .json();
-        .json();   }
-    }  };
-  };
-}
-
-// Use it in your applicationst authClient = createAuthClient('https://api.example.com');
-const authClient = createAuthClient('https://api.example.com');const { token, user } = await authClient.login('user@example.com', 'password');
-const { token, user } = await authClient.login('user@example.com', 'password');
-```
-ad with Progress
-### File Upload with Progress
-
-```typescript
-// Upload a file with abort capabilityconst uploadFile = async (file, onProgress) => {
-const uploadFile = async (file, onProgress) => {Controller();
-  const controller = new AbortController();
-  const form = new FormData();
-  const form = new FormData();append('file', file);
-  form.append('file', file);
-
-  try {
-    return await create.post()
-      .withBody(form)oller(controller)
-      .withAbortController(controller)or large files
-      .withTimeout(60000) // 1 minute timeout for large filesries(2)
-      .withRetries(2)s://api.example.com/upload')
-      .sendTo('https://api.example.com/upload')
-      .json();
-  } catch (error) {f (error instanceof RequestError) {
-    if (error instanceof RequestError) {ror(`Upload failed: ${error.message}`);
-      console.error(`Upload failed: ${error.message}`); }
-    }    throw error;
-    throw error;
-  }
-turn {
-  return {  abort: () => controller.abort()
-    abort: () => controller.abort();
-  };};
-};
-```
+## Comparison of JavaScript HTTP Client Libraries
+
+| Feature             | create-request | Fetch  | Axios   | SuperAgent | Got     | Ky     | node-fetch | Redaxios |
+| ------------------- | -------------- | ------ | ------- | ---------- | ------- | ------ | ---------- | -------- |
+| **Size (min+gzip)** | ~5.1KB         | Native | ~13.6KB | ~17.8KB    | ~17.8KB | ~3.4KB | ~7.7KB     | ~1KB     |
+| **Browser**         | Modern         | Modern | IE11+   | IE9+       | ❌ No   | Modern | ❌ No      | Modern   |
+| **Node.js**         | ✅             | ✅     | ✅      | ✅         | ✅      | ✅     | ✅         | ✅       |
+| **HTTP/2**          | ✅             | ✅     | ✅      | ✅         | ✅      | ✅     | ❌         | ❌       |
+| **Auto Retries**    | ✅             | ❌     | 🛠️      | ✅         | ✅      | ✅     | ❌         | ❌       |
+| **Cancellation**    | ✅             | ✅     | ✅      | ✅         | ✅      | ✅     | ✅         | ✅       |
+| **Caching**         | ✅             | ❌     | ❌      | ✅         | ✅      | ❌     | ❌         | ❌       |
+| **Auto JSON**       | ✅             | ❌     | ✅      | ✅         | ✅      | ✅     | ❌         | ✅       |
+| **Timeout**         | ✅             | ❌     | ✅      | ✅         | ✅      | ✅     | ✅         | ✅       |
+| **TypeScript**      | ✅             | ✅     | ✅      | ✅         | ✅      | ✅     | ✅         | ✅       |
+| **Streaming**       | ✅             | ✅     | ✅      | ✅         | ✅      | ✅     | ✅         | ❌       |
+| **Progress**        | ❌             | ❌     | ✅      | ✅         | ✅      | ✅     | ❌         | ❌       |
+| **Middleware**      | ❌             | ❌     | ✅      | ✅         | ✅      | ✅     | ❌         | ❌       |
+| **Cookies**         | ✅             | ✅     | 🛠️      | ✅         | ✅      | ❌     | ❌         | ❌       |
+| **Pagination API**  | ❌             | ❌     | ❌      | ❌         | ✅      | ❌     | ❌         | ❌       |
+| **Zero Deps**       | ✅             | ✅     | ❌      | ❌         | ❌      | ✅     | ✅         | ✅       |
+| **Chainable API**   | ✅             | ❌     | ❌      | ✅         | ✅      | ✅     | ❌         | ❌       |
+| **CSRF Protection** | ✅             | ❌     | ✅      | ❌         | ❌      | ❌     | ❌         | ❌       |
+
+**Notes:**
+
+- "Modern" browser support: Chrome 42+, Firefox 39+, Safari 10.1+, Edge 14+, Opera 29+
+- 🛠️ Feature requires additional plugins or adapters (not available out-of-the-box)
 
 ## License