create-request 1.4.3-rc.1 → 1.4.3-rc.3

package/README.md

@@ -14,17 +14,19 @@
 
 - [Core Features](#core-features)
 - [Why create-request](#why-create-request)
+- [Mental Model](#mental-model)
 - [Installation](#installation)
 - [Basic Usage](#basic-usage)
-- [API Builder](#api-builder)
-- [Automatic Retries with Delay](#automatic-retries-with-delay)
-- [Interceptors](#interceptors)
-- [Request Cancellation](#request-cancellation)
 - [URL Handling](#url-handling)
-- [Data Selection](#data-selection)
-- [GraphQL Support](#graphql-requests)
-- [TypeScript Support](#typescript-support)
-- [CSRF Protection](#csrf-protection)
+- [Advanced Usage](#advanced-usage)
+  - [API Builder](#api-builder)
+  - [Automatic Retries with Delay](#automatic-retries-with-delay)
+  - [Interceptors](#interceptors)
+  - [Request Cancellation](#request-cancellation)
+  - [Data Selection](#data-selection)
+  - [TypeScript Support](#typescript-support)
+  - [CSRF Protection](#csrf-protection)
+  - [Subresource Integrity and Cache Control](#subresource-integrity-and-cache-control)
 - [Performance Considerations](#performance-considerations)
 - [Browser Support](#browser-support)
 - [Comparison of JavaScript HTTP Client Libraries](#comparison-of-javascript-http-client-libraries)
@@ -42,6 +44,7 @@
 - 🔁 **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
+- 🏗️ **API Builder** - Create configured API instances with reusable default settings
 - 🛑 **Request Cancellation** - Abort requests on demand with AbortController integration
 - 🔌 **Interceptors** - Global and per-request interceptors for requests, responses, and errors
 - 🔷 **GraphQL Support** - Built-in GraphQL query and mutation helpers
@@ -94,6 +97,127 @@ function createUser(userData) {
 }
 ```
 
+## Mental Model
+
+### 1. **Separation of Building and Execution**
+
+Requests are built first, then executed. This separation allows you to:
+
+- Configure requests incrementally
+- Reuse request configurations
+- Pass requests around before executing them
+- Chain configuration methods fluently
+
+```typescript
+// Building phase: configure the request
+const request = create
+  .get("https://api.example.com/users")
+  .withBearerToken(token)
+  .withTimeout(5000);
+
+// Execution phase: actually make the HTTP call
+const data = await request.getJson();
+```
+
+### 2. **Fluent Chainable Interface**
+
+Every configuration method returns the request instance, enabling method chaining. This creates a readable, declarative API that reads like a sentence:
+
+```typescript
+// Reads like: "Create a POST request to users endpoint, with auth, body, and timeout, then get JSON"
+const user = await create
+  .post("https://api.example.com/users")
+  .withBearerToken(token)
+  .withBody(userData)
+  .withTimeout(3000)
+  .getJson();
+```
+
+### 3. **Configuration Layers**
+
+Configuration follows a layered approach, with more specific settings overriding general ones:
+
+1. **Global Configuration** (via `create.config`) - Applies to all requests
+2. **API Builder Defaults** (via `create.api()`) - Applies to requests from that API instance
+3. **Per-Request Configuration** - Specific to individual requests
+
+```typescript
+// Global: all requests get this
+create.config.setCsrfToken("global-token");
+
+// API instance: requests from this API get these defaults
+const api = create
+  .api()
+  .withBaseURL("https://api.example.com")
+  .withBearerToken("default-token");
+
+// Per-request: this specific request overrides the default token
+const user = await api
+  .get("/users")
+  .withBearerToken("specific-token") // Overrides default-token
+  .getJson();
+```
+
+### 4. **Request Definition with `with...` Functions**
+
+All request configuration is done through methods that start with `with...`. This consistent naming convention makes it immediately clear which methods are used for configuration:
+
+```typescript
+// All configuration uses 'with...' prefix
+const request = create
+  .get("https://api.example.com/users")
+  .withHeaders({ "X-API-Key": "abc123" })
+  .withBearerToken("token")
+  .withTimeout(5000)
+  .withRetries(3)
+  .withQueryParams({ page: 1 })
+  .withCookie("session", "abc123");
+```
+
+This pattern makes the API self-documenting - any method starting with `with...` is a configuration method that returns the request instance for chaining.
+
+### 5. **Request Lifecycle**
+
+The typical request lifecycle follows this pattern:
+
+```
+Build → Configure → Execute → Transform → Handle
+```
+
+1. **Build**: Create a request with a method and URL (`create.get(url)`)
+2. **Configure**: Chain configuration methods using `with...` functions (`.withHeaders()`, `.withTimeout()`, etc.)
+3. **Execute**: Call an execution method (`.getJson()`, `.getData()`, etc.)
+4. **Transform**: Optionally transform the response (via `.getData()` selector or interceptors)
+5. **Handle**: Process the result or catch errors
+
+### 6. **Promise-Based Execution**
+
+All execution methods return Promises, making the library compatible with:
+
+- `async/await` syntax (recommended)
+- `.then()/.catch()` chains
+- Promise utilities like `Promise.all()`, `Promise.race()`, etc.
+
+```typescript
+// All of these work:
+const data1 = await request.getJson();
+
+request.getJson().then(data => console.log(data));
+
+const results = await Promise.all([
+  create.get("/users").getJson(),
+  create.get("/posts").getJson(),
+]);
+```
+
+### 7. **Comprehensive JSDoc Documentation**
+
+The library includes extensive JSDoc documentation throughout the codebase. This documentation is valuable for developers of all levels:
+
+- **For Junior Developers**: JSDoc provides clear explanations of what each method does, parameter types, return values, and usage examples directly in your IDE. This helps with learning and understanding the API without constantly referring to external documentation.
+
+- **For Senior Developers**: JSDoc offers detailed type information, edge cases, and implementation details that enable deeper understanding and more advanced usage patterns. The type definitions help with TypeScript inference and ensure type safety.
+
 ## Installation
 
 ```bash
@@ -310,44 +434,6 @@ const merged = create
   .withQueryParams({ new: "param" }); // Both existing and new params included
 ```
 
-### Subresource Integrity and Cache Control
-
-The library supports subresource integrity verification and cache control options:
-
-```typescript
-// Subresource Integrity - ensures the fetched resource hasn't been tampered with
-const secureRequest = create
-  .get("https://cdn.example.com/script.js")
-  .withIntegrity("sha256-abcdef1234567890..."); // Browser will verify the hash
-
-// Cache Control - supports all cache modes via fluent API or string values
-const cachedRequest = create.get("https://api.example.com/data").withCache("no-cache"); // Direct string value
-
-// Using fluent API for cache modes
-const fluentCache = create.get("https://api.example.com/data").withCache.NO_CACHE(); // Fluent API method
-
-// All available cache modes:
-create
-  .get("https://api.example.com/data")
-  .withCache.DEFAULT() // Default cache behavior
-  .withCache.NO_STORE() // Don't store in cache
-  .withCache.RELOAD() // Reload from server
-  .withCache.NO_CACHE() // Validate with server before using cache
-  .withCache.FORCE_CACHE() // Use cache even if stale
-  .withCache.ONLY_IF_CACHED(); // Only use cache, don't fetch from server
-
-// Using enum values (import from create-request)
-import { CacheMode } from "create-request";
-
-const enumCache = create.get("https://api.example.com/data").withCache(CacheMode.NO_CACHE);
-
-// Combining integrity and cache
-const secureCached = create
-  .get("https://cdn.example.com/resource.js")
-  .withIntegrity("sha256-abcdef1234567890...")
-  .withCache("no-store"); // Ensure no caching for sensitive resources
-```
-
 ### Executing Requests
 
 ```typescript
@@ -418,7 +504,34 @@ try {
 }
 ```
 
-## API Builder
+## URL Handling
+
+The library handles both absolute and relative URLs, and automatically merges query parameters:
+
+```typescript
+// Relative URLs (preserved as-is)
+const relative = await create.get("/api/users").getJson();
+
+// Absolute URLs
+const absolute = await create.get("https://api.example.com/users").getJson();
+
+// Merging query params with existing URL params
+const merged = await create
+  .get("https://api.example.com/users?page=1")
+  .withQueryParams({ limit: 20, sort: "name" })
+  .getJson();
+// Result: https://api.example.com/users?page=1&limit=20&sort=name
+
+// Special characters and unicode are properly encoded
+const encoded = await create
+  .get("https://api.example.com/search")
+  .withQueryParams({ name: "用户名", filter: "status:active" })
+  .getJson();
+```
+
+## Advanced Usage
+
+### API Builder
 
 The API builder allows you to create configured API instances with default settings that can be reused across your application. This is perfect for setting up a base URL, default headers, timeout values, and other request configurations once and using them for all requests.
 
@@ -467,8 +580,6 @@ The API builder provides access to all request configuration methods from `BaseR
 - `withReferrer(referrer)` - Set default referrer
 - `withKeepAlive(keepalive)` - Configure keep-alive
 - `withIntegrity(integrity)` - Set integrity check
-- `withQueryParams(params)` - Add default query parameters
-- `withQueryParam(key, value)` - Add a single default query parameter
 
 **CSRF Protection:**
 
@@ -498,26 +609,6 @@ await api.get("/users").getJson();
 await api.post("/posts").withBody({ title: "Hello" }).getJson();
 ```
 
-#### Methods NOT Available on API Builder
-
-The following methods are **not available** on the API builder because they are request-specific and don't make sense as defaults:
-
-- **`withAbortController(controller)`** - AbortController is per-request, not a default
-- **`withBody(body)`** - Request bodies are different for each request
-- **`withGraphQL(query, variables, options)`** - GraphQL queries are request-specific
-
-These methods should be called directly on individual request instances:
-
-```typescript
-const api = create.api().withBaseURL("https://api.example.com");
-
-// ✅ Good: Use withBody on individual requests
-await api.post("/users").withBody({ name: "John" }).getJson();
-
-// ❌ Bad: withBody is not available on the API builder
-// api.withBody({ name: "John" }); // This will be undefined
-```
-
 #### URL Resolution
 
 The API builder intelligently resolves URLs:
@@ -622,7 +713,7 @@ async function deleteUser(id: string) {
 }
 ```
 
-## Automatic Retries with Delay
+### Automatic Retries with Delay
 
 The `withRetries()` method supports both simple number-based retries and object-based configuration with customizable delays:
 
@@ -669,7 +760,7 @@ const request4 = create.get("https://api.example.com/data").withRetries({
 })
 ```
 
-## Interceptors
+### Interceptors
 
 Interceptors allow you to modify requests, transform responses, or handle errors globally or per-request. This is perfect for adding authentication tokens, logging, error recovery, and more.
 
@@ -803,7 +894,7 @@ const asyncData = await create
   .getJson();
 ```
 
-## Request Cancellation
+### Request Cancellation
 
 ```typescript
 const controller = new AbortController();
@@ -829,32 +920,7 @@ try {
 }
 ```
 
-## URL Handling
-
-The library handles both absolute and relative URLs, and automatically merges query parameters:
-
-```typescript
-// Relative URLs (preserved as-is)
-const relative = await create.get("/api/users").getJson();
-
-// Absolute URLs
-const absolute = await create.get("https://api.example.com/users").getJson();
-
-// Merging query params with existing URL params
-const merged = await create
-  .get("https://api.example.com/users?page=1")
-  .withQueryParams({ limit: 20, sort: "name" })
-  .getJson();
-// Result: https://api.example.com/users?page=1&limit=20&sort=name
-
-// Special characters and unicode are properly encoded
-const encoded = await create
-  .get("https://api.example.com/search")
-  .withQueryParams({ name: "用户名", filter: "status:active" })
-  .getJson();
-```
-
-## Data Selection
+### Data Selection
 
 The `getData` method provides a powerful way to extract and transform specific data from API responses:
 
@@ -896,7 +962,7 @@ try {
 }
 ```
 
-## TypeScript Support
+### TypeScript Support
 
 ```typescript
 interface User {
@@ -942,7 +1008,7 @@ async function getUserById(id: number): Promise<User> {
 }
 ```
 
-## CSRF Protection
+### 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.
 
@@ -986,6 +1052,44 @@ const request = create
   .withoutCsrfProtection(); // Or disable all automatic CSRF protection
 ```
 
+### Subresource Integrity and Cache Control
+
+The library supports subresource integrity verification and cache control options:
+
+```typescript
+// Subresource Integrity - ensures the fetched resource hasn't been tampered with
+const secureRequest = create
+  .get("https://cdn.example.com/script.js")
+  .withIntegrity("sha256-abcdef1234567890..."); // Browser will verify the hash
+
+// Cache Control - supports all cache modes via fluent API or string values
+const cachedRequest = create.get("https://api.example.com/data").withCache("no-cache"); // Direct string value
+
+// Using fluent API for cache modes
+const fluentCache = create.get("https://api.example.com/data").withCache.NO_CACHE(); // Fluent API method
+
+// All available cache modes:
+create
+  .get("https://api.example.com/data")
+  .withCache.DEFAULT() // Default cache behavior
+  .withCache.NO_STORE() // Don't store in cache
+  .withCache.RELOAD() // Reload from server
+  .withCache.NO_CACHE() // Validate with server before using cache
+  .withCache.FORCE_CACHE() // Use cache even if stale
+  .withCache.ONLY_IF_CACHED(); // Only use cache, don't fetch from server
+
+// Using enum values (import from create-request)
+import { CacheMode } from "create-request";
+
+const enumCache = create.get("https://api.example.com/data").withCache(CacheMode.NO_CACHE);
+
+// Combining integrity and cache
+const secureCached = create
+  .get("https://cdn.example.com/resource.js")
+  .withIntegrity("sha256-abcdef1234567890...")
+  .withCache("no-store"); // Ensure no caching for sensitive resources
+```
+
 ## Performance Considerations
 
 create-request is designed to be lightweight and efficient:
@@ -1008,26 +1112,27 @@ This library works with all browsers that support the Fetch API:
 
 ## Comparison of JavaScript HTTP Client Libraries
 
-| Feature             | create-request | Fetch  | Axios   | SuperAgent | Got     | Ky     | node-fetch | Redaxios |
-| ------------------- | -------------- | ------ | ------- | ---------- | ------- | ------ | ---------- | -------- |
-| **Size (min+gzip)** | ~5.8KB         | 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**    | ✅             | ✅     | ✅      | ✅         | ✅      | ✅     | ✅         | ✅       |
-| **Auto JSON**       | ✅             | ❌     | ✅      | ✅         | ✅      | ✅     | ❌         | ✅       |
-| **Timeout**         | ✅             | ❌     | ✅      | ✅         | ✅      | ✅     | ✅         | ✅       |
-| **TypeScript**      | ✅             | ✅     | ✅      | ✅         | ✅      | ✅     | ✅         | ✅       |
-| **Streaming**       | ✅             | ✅     | ✅      | ✅         | ✅      | ✅     | ✅         | ❌       |
-| **Progress**        | ❌             | ❌     | ✅      | ✅         | ✅      | ✅     | ❌         | ❌       |
-| **Cookies**         | ✅             | ✅     | 🛠️      | ✅         | ✅      | ❌     | ❌         | ❌       |
-| **Pagination API**  | ❌             | ❌     | ❌      | ❌         | ✅      | ❌     | ❌         | ❌       |
-| **Zero Deps**       | ✅             | ✅     | ❌      | ❌         | ❌      | ✅     | ✅         | ✅       |
-| **Chainable API**   | ✅             | ❌     | ❌      | ✅         | ✅      | ✅     | ❌         | ❌       |
-| **CSRF Protection** | ✅             | ❌     | ✅      | ❌         | ❌      | ❌     | ❌         | ❌       |
-| **GraphQL Support** | ✅             | ❌     | ❌      | ❌         | ❌      | ❌     | ❌         | ❌       |
-| **Interceptors**    | ✅             | ❌     | ✅      | ✅         | ✅      | ✅     | ❌         | ❌       |
+| Feature               | create-request | Fetch  | Axios   | SuperAgent | Got     | Ky     | node-fetch | Redaxios |
+| --------------------- | -------------- | ------ | ------- | ---------- | ------- | ------ | ---------- | -------- |
+| **Size (min+gzip)**   | ~6.3KB         | 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**      | ✅             | ✅     | ✅      | ✅         | ✅      | ✅     | ✅         | ✅       |
+| **Auto JSON**         | ✅             | ❌     | ✅      | ✅         | ✅      | ✅     | ❌         | ✅       |
+| **Timeout**           | ✅             | ❌     | ✅      | ✅         | ✅      | ✅     | ✅         | ✅       |
+| **TypeScript**        | ✅             | ✅     | ✅      | ✅         | ✅      | ✅     | ✅         | ✅       |
+| **Streaming**         | ✅             | ✅     | ✅      | ✅         | ✅      | ✅     | ✅         | ❌       |
+| **Progress**          | ❌             | ❌     | ✅      | ✅         | ✅      | ✅     | ❌         | ❌       |
+| **Cookies**           | ✅             | ✅     | 🛠️      | ✅         | ✅      | ❌     | ❌         | ❌       |
+| **Pagination API**    | ❌             | ❌     | ❌      | ❌         | ✅      | ❌     | ❌         | ❌       |
+| **Zero Deps**         | ✅             | ✅     | ❌      | ❌         | ❌      | ✅     | ✅         | ✅       |
+| **Chainable API**     | ✅             | ❌     | ❌      | ✅         | ✅      | ✅     | ❌         | ❌       |
+| **CSRF Protection**   | ✅             | ❌     | ✅      | ❌         | ❌      | ❌     | ❌         | ❌       |
+| **GraphQL Support**   | ✅             | ❌     | ❌      | ❌         | ❌      | ❌     | ❌         | ❌       |
+| **Interceptors**      | ✅             | ❌     | ✅      | ✅         | ✅      | ✅     | ❌         | ❌       |
+| **Instance Creation** | ✅             | ❌     | ✅      | ✅         | ✅      | ✅     | ❌         | ❌       |
 
 **Notes:**
 
@@ -1037,3 +1142,9 @@ This library works with all browsers that support the Fetch API:
 ## License
 
 MIT
+
+---
+
+## Website
+
+Visit [create-request.com](https://create-request.com) for documentation, examples, and more resources.