create-request 1.4.3-rc.2 → 1.4.3-rc.4

package/README.md

@@ -14,6 +14,7 @@
 
 - [Core Features](#core-features)
 - [Why create-request](#why-create-request)
+- [Mental Model](#mental-model)
 - [Installation](#installation)
 - [Basic Usage](#basic-usage)
 - [URL Handling](#url-handling)
@@ -43,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
@@ -95,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
@@ -989,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:**
 
@@ -1018,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.

package/dist/library/BaseRequest.d.ts

@@ -365,16 +365,56 @@ export declare abstract class BaseRequest {
         ONLY_IF_CACHED: () => BaseRequest;
     };
     /**
-     * Adds query parameters to the request URL
-     * @param params - An object containing the query parameters
-     * @returns The instance for chaining
+     * Adds query parameters to the request URL.
+     * Multiple calls will append parameters. Array values will create multiple query parameters with the same key.
+     * Null and undefined values are ignored.
+     *
+     * @param params - An object containing query parameter key-value pairs.
+     *   Values can be strings, numbers, booleans, arrays (for multiple values), or null/undefined (ignored).
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * // Simple parameters
+     * request.withQueryParams({ page: 1, limit: 10, active: true });
+     * // Results in: ?page=1&limit=10&active=true
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Array values create multiple parameters
+     * request.withQueryParams({ tags: ['js', 'ts', 'node'] });
+     * // Results in: ?tags=js&tags=ts&tags=node
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Null/undefined values are ignored
+     * request.withQueryParams({ page: 1, filter: null, sort: undefined });
+     * // Results in: ?page=1
+     * ```
      */
     withQueryParams(params: Record<string, string | string[] | number | boolean | null | undefined>): this;
     /**
-     * Adds a single query parameter
-     * @param key - The parameter name
-     * @param value - The parameter value, can be a single value or array of values
-     * @returns The instance for chaining
+     * Adds a single query parameter to the request URL.
+     * Convenience method for adding one parameter at a time.
+     *
+     * @param key - The query parameter name
+     * @param value - The query parameter value. Can be a string, number, boolean, array (for multiple values), or null/undefined (ignored).
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withQueryParam('page', 1).withQueryParam('limit', 10);
+     * // Results in: ?page=1&limit=10
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Array values create multiple parameters
+     * request.withQueryParam('tags', ['js', 'ts']);
+     * // Results in: ?tags=js&tags=ts
+     * ```
      */
     withQueryParam(key: string, value: string | string[] | number | boolean | null | undefined): this;
     /**
@@ -412,22 +452,55 @@ export declare abstract class BaseRequest {
         NAVIGATE: () => BaseRequest;
     };
     /**
-     * Shorthand for setting the Content-Type header
-     * @param contentType - The content type
-     * @returns The instance for chaining
+     * Sets the Content-Type header for the request.
+     * Shorthand for `withHeader('Content-Type', contentType)`.
+     *
+     * @param contentType - The MIME type (e.g., `'application/json'`, `'text/plain'`, `'multipart/form-data'`)
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withContentType('application/json');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * request.withContentType('application/xml');
+     * ```
      */
     withContentType(contentType: string): this;
     /**
-     * Shorthand for setting the Authorization header
-     * @param authValue - The authorization value
-     * @returns The instance for chaining
+     * Sets the Authorization header for the request.
+     * Shorthand for `withHeader('Authorization', authValue)`.
+     * For Bearer tokens, use `withBearerToken()` instead. For Basic auth, use `withBasicAuth()`.
+     *
+     * @param authValue - The full authorization header value (e.g., `'Bearer token123'`, `'Basic base64string'`)
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withAuthorization('Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * request.withAuthorization('CustomScheme customToken');
+     * ```
      */
     withAuthorization(authValue: string): this;
     /**
-     * Shorthand for setting up Basic authentication
-     * @param username - The username
-     * @param password - The password
-     * @returns The instance for chaining
+     * Sets up HTTP Basic Authentication.
+     * Encodes the username and password in base64 and sets the Authorization header.
+     *
+     * @param username - The username for Basic authentication
+     * @param password - The password for Basic authentication
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withBasicAuth('myuser', 'mypassword');
+     * // Sets: Authorization: Basic bXl1c2VyOm15cGFzc3dvcmQ=
+     * ```
      */
     withBasicAuth(username: string, password: string): this;
     /**
@@ -436,9 +509,17 @@ export declare abstract class BaseRequest {
      */
     private encodeBase64;
     /**
-     * Sets the bearer token for authentication
-     * @param token - The bearer token
-     * @returns The instance for chaining
+     * Sets a Bearer token for authentication.
+     * Shorthand for `withAuthorization('Bearer ' + token)`.
+     *
+     * @param token - The Bearer token (JWT, OAuth token, etc.)
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withBearerToken('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
+     * // Sets: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+     * ```
      */
     withBearerToken(token: string): this;
     /**
@@ -453,23 +534,69 @@ export declare abstract class BaseRequest {
      */
     private hasHeader;
     /**
-     * Sets cookies for the request
-     * @param cookies Object containing cookie name-value pairs or cookie options
-     * @returns The instance for chaining
+     * Sets cookies for the request.
+     * Cookies are sent in the Cookie header. Multiple calls will merge cookies.
+     * Cookie values can be simple strings or objects with additional cookie options.
+     *
+     * @param cookies - An object where keys are cookie names and values are either:
+     *   - A string (the cookie value)
+     *   - A CookieOptions object with `value` and optional properties (secure, httpOnly, sameSite, expires, path, domain, maxAge)
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * // Simple string cookies
+     * request.withCookies({ sessionId: 'abc123', userId: '456' });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Cookies with options (note: options are for documentation only in request cookies)
+     * request.withCookies({
+     *   sessionId: 'abc123',
+     *   token: { value: 'xyz789', secure: true }
+     * });
+     * ```
      */
     withCookies(cookies: CookiesRecord): this;
     /**
-     * Set a single cookie
-     * @param name Cookie name
-     * @param value Cookie value or options object
-     * @returns The instance for chaining
+     * Sets a single cookie for the request.
+     * Convenience method for adding one cookie at a time.
+     *
+     * @param name - The cookie name
+     * @param value - The cookie value as a string, or a CookieOptions object with `value` and optional properties
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withCookie('sessionId', 'abc123');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * request.withCookie('token', { value: 'xyz789', secure: true });
+     * ```
      */
     withCookie(name: string, value: string | CookieOptions): this;
     /**
-     * Sets a CSRF token in the request headers
-     * @param token The CSRF token
-     * @param headerName The name of the header to use (default: X-CSRF-Token)
-     * @returns The instance for chaining
+     * Sets a CSRF (Cross-Site Request Forgery) token in the request headers.
+     * This is commonly used to protect against CSRF attacks in web applications.
+     *
+     * @param token - The CSRF token value
+     * @param headerName - The name of the header to use. Defaults to `'X-CSRF-Token'`.
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withCsrfToken('csrf-token-123');
+     * // Sets: X-CSRF-Token: csrf-token-123
+     * ```
+     *
+     * @example
+     * ```typescript
+     * request.withCsrfToken('token', 'X-Custom-CSRF-Header');
+     * // Sets: X-Custom-CSRF-Header: token
+     * ```
      */
     withCsrfToken(token: string, headerName?: string): this;
     /**
@@ -557,30 +684,48 @@ export declare abstract class BaseRequest {
      */
     getJson<T = unknown>(): Promise<T>;
     /**
-     * Execute the request and get the response as text
+     * Execute the request and get the response body as text.
      *
-     * @returns A promise that resolves to the response text
+     * @returns A promise that resolves to the response body as a string
+     * @throws {RequestError} When the request fails or reading the response fails
      *
      * @example
+     * ```typescript
      * const text = await request.getText();
+     * console.log(text); // "Hello, world!"
+     * ```
      */
     getText(): Promise<string>;
     /**
-     * Execute the request and get the response as a Blob
+     * Execute the request and get the response body as a Blob.
+     * Useful for downloading files or handling binary data.
      *
-     * @returns A promise that resolves to the response Blob
+     * @returns A promise that resolves to the response body as a Blob
+     * @throws {RequestError} When the request fails or reading the response fails
      *
      * @example
+     * ```typescript
      * const blob = await request.getBlob();
+     * const url = URL.createObjectURL(blob);
+     * // Use the blob URL (e.g., for downloading or displaying)
+     * ```
      */
     getBlob(): Promise<Blob>;
     /**
-     * Execute the request and get the response body as a ReadableStream
+     * Execute the request and get the response body as a ReadableStream.
+     * Note: Unlike other methods, streams cannot be cached. The body can only be consumed once.
      *
-     * @returns A promise that resolves to the response body stream
+     * @returns A promise that resolves to the response body as a ReadableStream, or `null` if the body is not available
+     * @throws {RequestError} When the request fails or the body has already been consumed
      *
      * @example
+     * ```typescript
      * const stream = await request.getBody();
+     * if (stream) {
+     *   const reader = stream.getReader();
+     *   // Process the stream chunk by chunk
+     * }
+     * ```
      */
     getBody(): Promise<ReadableStream<Uint8Array> | null>;
     /**

package/dist/library/BodyRequest.d.ts

@@ -10,31 +10,77 @@ export declare abstract class BodyRequest extends BaseRequest {
     private graphQLOptions;
     constructor(url: string);
     /**
-     * Sets the body of the request
-     * @param body - The request body
+     * Sets the request body. Automatically detects the body type and sets appropriate Content-Type header.
+     * Supports JSON objects/arrays, strings, FormData, Blob, ArrayBuffer, URLSearchParams, and ReadableStream.
+     *
+     * @param body - The request body. Can be:
+     *   - A JSON-serializable object or array (automatically stringified)
+     *   - A string (sets Content-Type to `text/plain` if not already set)
+     *   - FormData, Blob, File, ArrayBuffer, TypedArray, URLSearchParams, or ReadableStream
+     * @returns The request instance for chaining
+     * @throws {RequestError} If the body is a JSON object that cannot be stringified
+     *
+     * @example
+     * ```typescript
+     * // JSON object (automatically stringified)
+     * request.withBody({ name: 'John', age: 30 });
+     *
+     * @example
+     * // JSON array
+     * request.withBody([1, 2, 3]);
+     *
+     * @example
+     * // String
+     * request.withBody('plain text');
+     *
+     * @example
+     * // FormData
+     * const formData = new FormData();
+     * formData.append('file', fileBlob);
+     * request.withBody(formData);
+     *
+     * @example
+     * // Blob
+     * request.withBody(new Blob(['content'], { type: 'text/plain' }));
+     * ```
      */
     withBody(body: Body): this;
     /**
-     * Sets a GraphQL query or mutation as the request body
-     * Automatically formats the body as JSON and sets Content-Type to application/json
+     * Sets a GraphQL query or mutation as the request body.
+     * Automatically formats the body as JSON and sets Content-Type to `application/json`.
+     * If `throwOnError` is enabled in options, the response will be checked for GraphQL errors
+     * and a RequestError will be thrown if any are found.
      *
-     * @param query - The GraphQL query or mutation string
-     * @param variables - Optional variables object to pass with the query
+     * @param query - The GraphQL query or mutation string (e.g., `'query { user { id } }'`)
+     * @param variables - Optional variables object to pass with the query. Must be a plain object.
      * @param options - Optional GraphQL-specific options
+     * @param options.throwOnError - If `true`, throws a RequestError when the GraphQL response contains errors
      * @returns The request instance for chaining
+     * @throws {RequestError} If the query is empty, variables is invalid, or JSON stringification fails
      *
      * @example
-     * const request = new PostRequest('/graphql')
+     * ```typescript
+     * // Simple query with variables
+     * const request = create.post('/graphql')
      *   .withGraphQL('query { user(id: $id) { name email } }', { id: '123' });
+     * const data = await request.getJson();
+     * ```
      *
      * @example
-     * const request = new PostRequest('/graphql')
+     * ```typescript
+     * // Mutation with variables
+     * const request = create.post('/graphql')
      *   .withGraphQL('mutation { createUser(name: $name) { id } }', { name: 'John' });
+     * ```
      *
      * @example
-     * // Throw an error if the GraphQL response contains errors
-     * const request = new PostRequest('/graphql')
+     * ```typescript
+     * // Throw error if GraphQL response contains errors
+     * const request = create.post('/graphql')
      *   .withGraphQL('query { user { id } }', undefined, { throwOnError: true });
+     * // If the response has errors, this will throw a RequestError
+     * const data = await request.getJson();
+     * ```
      */
     withGraphQL(query: string, variables?: Record<string, unknown>, options?: GraphQLOptions): this;
     /**