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

package/README.md

@@ -8,28 +8,58 @@
 
 ## Core Features
 
-- ⛓️ **Chainable API** - Build and execute requests with a fluent interface
 - ⏱️ **Timeout Support** - Set timeouts for any request
-- 🔁 **Automatic Retries** - Retry failed requests with customizable settings
-- 🔐 **Auth Helpers** - Simple methods for common authentication patterns
-- 📦 **Typed Responses** - Full TypeScript support for response data
+- 🚀 **Performance** - Tiny bundle size with zero dependencies
 - 🚧 **Error Handling** - Detailed error info with custom error class
+- 🔐 **Auth Helpers** - Simple methods for common authentication patterns
+- ⛓️ **Chainable API** - Build and execute requests with a fluent interface
+- 📉 **Reduced Boilerplate** - Write 60% less code for common API operations
+- 🔁 **Automatic Retries** - Retry failed requests with customizable settings
+- 🛡️ **Type Safety** - Full TypeScript support with intelligent type inference
 - 📝 **Response Caching** - Flexible caching system with multiple storage options
 
 ## 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 API that separates request building from execution:
+**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:
 
 ```typescript
-// Create a request
-const usersRequest = create.get()
-  .withTimeout(5000)
-  .withRetries(3)
-  .withBearerToken('your-token');
+// Before: Regular fetch
+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;
+  }
+}
+
+// After: With create-request
+import create from 'create-request';
 
-// Execute the request
-const users = await usersRequest.sendTo('https://api.example.com/users')
-  .getJson<User[]>();
+function createUser(userData) {
+  return create.post()
+    .withBasicAuth('username', 'password')
+    .withBody(userData)
+    .sendTo('https://api.example.com/users')
+    .getData<User>()
+    .catch(error => {
+      console.error('Fetch error:', error);
+      throw error;
+    });
+}
 ```
 
 ## Installation
@@ -44,67 +74,6 @@ Or with yarn:
 yarn add create-request
 ```
 
-## 🔄 Fetch API Comparison
-
-### Fetch API
-
-```typescript
-// Basic GET request with fetch
-try {
-  const response = await fetch('https://api.example.com/users');
-  if (!response.ok) {
-    throw new Error(`HTTP error ${response.status}`);
-  }
-  const users = await response.json();
-  console.log(users);
-} catch (error) {
-  console.error('Error fetching users:', error);
-}
-
-// POST request with fetch
-try {
-  const response = await fetch('https://api.example.com/users', {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'Authorization': 'Bearer token123'
-    },
-    body: JSON.stringify({ name: 'John Doe', email: 'john@example.com' })
-  });
-  if (!response.ok) {
-    throw new Error(`HTTP error ${response.status}`);
-  }
-  const result = await response.json();
-  console.log(result);
-} catch (error) {
-  console.error('Error creating user:', error);
-}
-```
-
-### create-request API
-
-```typescript
-// Basic GET request with create-request
-try {
-  const users = await create.get().sendTo('https://api.example.com/users').getJson();
-  console.log(users);
-} catch (error) {
-  console.error('Error fetching users:', error.message);
-}
-
-// POST request with create-request
-const createUserRequest = create.post()
-  .withBody({ name: 'John Doe', email: 'john@example.com' })
-  .withBearerToken('token123');
-
-try {
-  const result = await createUserRequest.sendTo('https://api.example.com/users').getJson();
-  console.log(result);
-} catch (error) {
-  console.error('Error creating user:', error.message);
-}
-```
-
 ## Basic Usage
 
 ### Creating Requests
@@ -124,30 +93,78 @@ const optionsRequest = create.options();
 
 ### Request Configuration
 
+The library provides a comprehensive set of configuration methods that can be chained together to customize your requests:
+
 ```typescript
-import { RequestPriority, CredentialsPolicy } from 'create-request';
+import create, { RequestPriority, CredentialsPolicy, RequestMode, CachePolicy, RedirectMode, ReferrerPolicy } from 'create-request';
 
 // Configure request options
 const request = create.get()
-  // Headers
-  .withHeaders({ 'X-API-Key': 'abc123' })
-
-  // Timeout and retries
-  .withTimeout(5000)
-  .withRetries(3)
-  .onRetry(({ attempt, error }) => {
-    console.log(`Attempt ${attempt} failed: ${error.message}`);
+  // 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
+  .withRetryDelay(1000) // Wait 1 second between retries
+  .withExponentialBackoff(true) // Use exponential backoff (increases wait time between retries)
+  .onRetry(({ attempt, error, delay }) => {
+    console.log(`Attempt ${attempt} failed: ${error.message}. Retrying in ${delay}ms`);
   })
 
-  // Authentication
-  .withBearerToken('your-token')
+  // Authentication methods
+  .withBearerToken('your-token') // Adds Authorization: Bearer your-token
+  .withBasicAuth('username', 'password') // HTTP Basic Authentication
+
+  // 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
+  .withCache(CachePolicy.NO_STORE) // Controls how request interacts with browser cache
+  .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
+```
 
-  // Query parameters
-  .withQueryParams({ search: 'term', page: 1 })
+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:
 
-  // Advanced options
-  .withCredentials(CredentialsPolicy.INCLUDE)
-  .withPriority(RequestPriority.HIGH);
+```typescript
+// 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();
+```
+
+You can also create reusable base requests with common settings:
+
+```typescript
+// Create base authenticated request
+const apiBase = create.get()
+  .withHeaders({
+    'X-API-Version': '1.2',
+    'Accept-Language': 'en-US'
+  })
+  .withBearerToken(authToken)
+  .withTimeout(5000)
+  .withRetries(2);
+
+// 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();
 ```
 
 ### Request Bodies (POST/PUT/PATCH)
@@ -182,6 +199,58 @@ const textData = await request.sendTo('https://api.example.com/endpoint').getTex
 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();
+```
+
+### Data Selection
+
+The `getData` method provides a powerful way to extract and transform specific data from API responses:
+
+```typescript
+// 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
+  }));
+```
+
+When a selector fails, the error message will contain the original response data to help diagnose the issue:
+
+```typescript
+try {
+  const result = await request
+    .sendTo('https://api.example.com/data')
+    .getData(data => data.results.items); // Will fail if structure is different
+} catch (error) {
+  console.error(error);
+  // Error message includes the original response data:
+  // "Data selector failed: Cannot read properties of undefined (reading 'items').
+  // Original data: { "status": "error", "message": "Invalid request" }"
+}
 ```
 
 ### Error Handling
@@ -285,12 +354,33 @@ interface User {
   email: string;
 }
 
+interface ApiResponse {
+  users: User[];
+  pagination: {
+    total: number;
+    page: number;
+  }
+}
+
 const userRequest = create.get();
-const user = await userRequest.sendTo('https://api.example.com/user/123')
-  .getJson<User>();
 
-// TypeScript knows the type
-console.log(user.name);
+// Type the full response
+const response = await userRequest
+  .sendTo('https://api.example.com/users')
+  .getJson<ApiResponse>();
+
+// Or use getData with type parameters
+const users = await userRequest
+  .sendTo('https://api.example.com/users')
+  .getData<ApiResponse, User[]>(data => data.users);
+
+// Or just get the full typed response
+const fullData = await userRequest
+  .sendTo('https://api.example.com/users')
+  .getData<ApiResponse>();
+
+// TypeScript knows the types
+console.log(users[0].name);
 ```
 
 ### Promise Chaining
@@ -322,15 +412,6 @@ const request = create.get()
     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}`);
   },
@@ -424,24 +505,54 @@ With custom storage providers, you can integrate with any storage system, such a
 
 ## 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.
+
+### How CSRF Protection Works
+
+The library employs multiple strategies to protect against CSRF attacks:
+
+1. **Automatic X-Requested-With Header**: By default, all requests include the `X-Requested-With: XMLHttpRequest` header, which helps servers identify legitimate AJAX requests.
+
+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.
+
+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.
+
 ### Global CSRF Configuration
 
+You can configure CSRF settings globally for all requests:
+
 ```typescript
 // Configure CSRF settings for all requests
 create.config.setCsrfToken('your-csrf-token');
-create.config.setCsrfHeaderName('X-CSRF-Token');
-create.config.setXsrfCookieName('XSRF-TOKEN');
+create.config.setCsrfHeaderName('X-CSRF-Token'); // Default header name
+create.config.setXsrfCookieName('XSRF-TOKEN'); // Default cookie name
+create.config.enableAntiCsrf(true); // Enable/disable X-Requested-With header
+create.config.enableAutoXsrf(true); // Enable/disable automatic cookie-to-header token
 ```
 
 ### Per-Request CSRF Settings
 
+You can also configure CSRF protection on individual requests:
+
 ```typescript
 // Configure CSRF for a specific request
 const request = create.post()
-  .withCsrfToken('request-specific-token')
-  .withoutCsrfProtection(); // Disable automatic CSRF protection
+  .withCsrfToken('request-specific-token') // Set a specific token
+  .withAntiCsrfHeaders() // Explicitly add X-Requested-With header
+  .withoutCsrfProtection(); // Or disable all automatic CSRF protection
 ```
 
+### Integrating with Backend Frameworks
+
+Most modern frameworks support CSRF protection out of the box. The library works seamlessly with:
+
+- **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
+
+When your server sends a CSRF token in a cookie or response header, `create-request` can automatically extract and include it in subsequent requests.
+
 ## Browser Support
 
 This library works with all browsers that support the Fetch API:

package/dist/library/BaseRequest.d.ts

@@ -34,6 +34,12 @@ export declare abstract class BaseRequest {
      * @returns The instance for chaining
      */
     withReferrer(referrer: string): this;
+    /**
+     * Sets the referrer policy for the request
+     * @param policy - The referrer policy to use
+     * @returns The instance for chaining
+     */
+    withReferrerPolicy(policy: ReferrerPolicy): this;
     /**
      * Sets the redirect policy for the request
      * @param redirect - Can be 'follow', 'error', or 'manual'

package/dist/library/ResponseWrapper.d.ts

@@ -29,4 +29,5 @@ export interface ResponsePromise<T = ResponseWrapper> extends Promise<T> {
     getBlob(): Promise<Blob>;
     getArrayBuffer(): Promise<ArrayBuffer>;
     getBody(): Promise<ReadableStream<Uint8Array> | null>;
+    getData<T = unknown, R = T>(selector?: (data: T) => R): Promise<T | R>;
 }

package/dist/library/enums.d.ts

@@ -70,3 +70,16 @@ export declare enum BodyType {
     STRING = "string",
     BINARY = "binary"
 }
+/**
+ * Referrer policies for fetch requests
+ */
+export declare enum ReferrerPolicy {
+    ORIGIN = "origin",
+    UNSAFE_URL = "unsafe-url",
+    SAME_ORIGIN = "same-origin",
+    NO_REFERRER = "no-referrer",
+    STRICT_ORIGIN = "strict-origin",
+    ORIGIN_WHEN_CROSS_ORIGIN = "origin-when-cross-origin",
+    NO_REFERRER_WHEN_DOWNGRADE = "no-referrer-when-downgrade",
+    STRICT_ORIGIN_WHEN_CROSS_ORIGIN = "strict-origin-when-cross-origin"
+}

package/dist/library/index.esm.js

@@ -78,6 +78,20 @@ var BodyType;
     BodyType["STRING"] = "string";
     BodyType["BINARY"] = "binary";
 })(BodyType || (BodyType = {}));
+/**
+ * Referrer policies for fetch requests
+ */
+var ReferrerPolicy;
+(function (ReferrerPolicy) {
+    ReferrerPolicy["ORIGIN"] = "origin";
+    ReferrerPolicy["UNSAFE_URL"] = "unsafe-url";
+    ReferrerPolicy["SAME_ORIGIN"] = "same-origin";
+    ReferrerPolicy["NO_REFERRER"] = "no-referrer";
+    ReferrerPolicy["STRICT_ORIGIN"] = "strict-origin";
+    ReferrerPolicy["ORIGIN_WHEN_CROSS_ORIGIN"] = "origin-when-cross-origin";
+    ReferrerPolicy["NO_REFERRER_WHEN_DOWNGRADE"] = "no-referrer-when-downgrade";
+    ReferrerPolicy["STRICT_ORIGIN_WHEN_CROSS_ORIGIN"] = "strict-origin-when-cross-origin";
+})(ReferrerPolicy || (ReferrerPolicy = {}));
 
 class RequestError extends Error {
     constructor(message, url, method, options = {}) {
@@ -823,6 +837,15 @@ class BaseRequest {
         this.requestOptions.referrer = referrer;
         return this;
     }
+    /**
+     * Sets the referrer policy for the request
+     * @param policy - The referrer policy to use
+     * @returns The instance for chaining
+     */
+    withReferrerPolicy(policy) {
+        this.requestOptions.referrerPolicy = policy;
+        return this;
+    }
     /**
      * Sets the redirect policy for the request
      * @param redirect - Can be 'follow', 'error', or 'manual'
@@ -929,6 +952,12 @@ class BaseRequest {
      * Works in both browser and Node.js environments
      */
     encodeBase64(str) {
+        // Modern approach using TextEncoder (available in both modern browsers and Node.js)
+        if (typeof TextEncoder !== "undefined" && typeof btoa === "function") {
+            const encoder = new TextEncoder();
+            const bytes = encoder.encode(str);
+            return btoa(String.fromCharCode.apply(null, [...new Uint8Array(bytes)]));
+        }
         // Browser environment
         if (typeof btoa === "function")
             return btoa(str);
@@ -1119,6 +1148,25 @@ class BaseRequest {
         responsePromise.getBody = async () => {
             return basePromise.then(response => response.getBody());
         };
+        responsePromise.getData = async (selector) => {
+            try {
+                const data = await basePromise.then(response => response.getJson());
+                // If no selector is provided, return the raw JSON data
+                if (!selector)
+                    return data;
+                // Apply the selector if provided
+                return selector(data);
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    // If selector fails, enhance the error with the original data
+                    const enhancedError = new Error(`Data selector failed: ${error.message}. Original data: ${JSON.stringify(await basePromise.then(response => response.getJson()), null, 2)}`);
+                    enhancedError.stack = error.stack;
+                    throw enhancedError;
+                }
+                throw error;
+            }
+        };
         return responsePromise;
     }
     /**

package/dist/library/index.js

@@ -84,6 +84,20 @@
         BodyType["STRING"] = "string";
         BodyType["BINARY"] = "binary";
     })(BodyType || (BodyType = {}));
+    /**
+     * Referrer policies for fetch requests
+     */
+    var ReferrerPolicy;
+    (function (ReferrerPolicy) {
+        ReferrerPolicy["ORIGIN"] = "origin";
+        ReferrerPolicy["UNSAFE_URL"] = "unsafe-url";
+        ReferrerPolicy["SAME_ORIGIN"] = "same-origin";
+        ReferrerPolicy["NO_REFERRER"] = "no-referrer";
+        ReferrerPolicy["STRICT_ORIGIN"] = "strict-origin";
+        ReferrerPolicy["ORIGIN_WHEN_CROSS_ORIGIN"] = "origin-when-cross-origin";
+        ReferrerPolicy["NO_REFERRER_WHEN_DOWNGRADE"] = "no-referrer-when-downgrade";
+        ReferrerPolicy["STRICT_ORIGIN_WHEN_CROSS_ORIGIN"] = "strict-origin-when-cross-origin";
+    })(ReferrerPolicy || (ReferrerPolicy = {}));
 
     class RequestError extends Error {
         constructor(message, url, method, options = {}) {
@@ -829,6 +843,15 @@
             this.requestOptions.referrer = referrer;
             return this;
         }
+        /**
+         * Sets the referrer policy for the request
+         * @param policy - The referrer policy to use
+         * @returns The instance for chaining
+         */
+        withReferrerPolicy(policy) {
+            this.requestOptions.referrerPolicy = policy;
+            return this;
+        }
         /**
          * Sets the redirect policy for the request
          * @param redirect - Can be 'follow', 'error', or 'manual'
@@ -935,6 +958,12 @@
          * Works in both browser and Node.js environments
          */
         encodeBase64(str) {
+            // Modern approach using TextEncoder (available in both modern browsers and Node.js)
+            if (typeof TextEncoder !== "undefined" && typeof btoa === "function") {
+                const encoder = new TextEncoder();
+                const bytes = encoder.encode(str);
+                return btoa(String.fromCharCode.apply(null, [...new Uint8Array(bytes)]));
+            }
             // Browser environment
             if (typeof btoa === "function")
                 return btoa(str);
@@ -1125,6 +1154,25 @@
             responsePromise.getBody = async () => {
                 return basePromise.then(response => response.getBody());
             };
+            responsePromise.getData = async (selector) => {
+                try {
+                    const data = await basePromise.then(response => response.getJson());
+                    // If no selector is provided, return the raw JSON data
+                    if (!selector)
+                        return data;
+                    // Apply the selector if provided
+                    return selector(data);
+                }
+                catch (error) {
+                    if (error instanceof Error) {
+                        // If selector fails, enhance the error with the original data
+                        const enhancedError = new Error(`Data selector failed: ${error.message}. Original data: ${JSON.stringify(await basePromise.then(response => response.getJson()), null, 2)}`);
+                        enhancedError.stack = error.stack;
+                        throw enhancedError;
+                    }
+                    throw error;
+                }
+            };
             return responsePromise;
         }
         /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-request",
-  "version": "0.0.1-beta.7",
+  "version": "0.0.1-beta.8",
   "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",