create-request 1.4.3-rc.4 → 1.5.0

package/README.md

@@ -16,6 +16,8 @@
 - [Why create-request](#why-create-request)
 - [Mental Model](#mental-model)
 - [Installation](#installation)
+- [Named Exports](#named-exports)
+- [Tree-Shaking Guide](#tree-shaking-guide)
 - [Basic Usage](#basic-usage)
 - [URL Handling](#url-handling)
 - [Advanced Usage](#advanced-usage)
@@ -28,7 +30,7 @@
   - [CSRF Protection](#csrf-protection)
   - [Subresource Integrity and Cache Control](#subresource-integrity-and-cache-control)
 - [Performance Considerations](#performance-considerations)
-- [Browser Support](#browser-support)
+- [Browser & Node.js Support](#browser--nodejs-support)
 - [Comparison of JavaScript HTTP Client Libraries](#comparison-of-javascript-http-client-libraries)
 - [License](#license)
 
@@ -97,6 +99,80 @@ function createUser(userData) {
 }
 ```
 
+### Why Not Object-Based Configuration?
+
+Many HTTP client libraries (like Axios, Got, and even the native Fetch API) use object-based configuration where all options are passed in a single configuration object. While this approach works, it creates a poor developer experience:
+
+**The Developer Experience Problem:**
+
+With object-based configuration, you're constantly context-switching between your code and documentation. You need to:
+
+- Remember exact option names and their structure
+- Look up documentation to discover available options
+- Guess at nested object structures
+- Hope your IDE autocomplete works with complex nested types
+
+```typescript
+// Object-based: What options are available? What's the structure? Need to check docs
+axios.post("https://api.example.com/users", userData, {
+  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+  timeout: 5000,
+  params: { validate: true },
+  withCredentials: true,
+});
+```
+
+**Superior Developer Experience with Fluent API:**
+
+`create-request`'s fluent API is designed for an exceptional developer experience. Every method is discoverable, self-documenting, and provides rich IDE support:
+
+#### 1. Intelligent Autocomplete & IntelliSense
+
+As you type, your IDE suggests the exact methods you need. No guessing, no documentation lookup:
+
+```typescript
+// Start typing and see all available methods
+create
+  .post(url)
+  .withBearerToken() // ← IDE suggests: withBearerToken(token: string)
+  .withTimeout() // ← IDE suggests: withTimeout(ms: number)
+  .withRetries(); // ← IDE suggests: withRetries(count: number | RetryConfig)
+```
+
+#### 2. Rich JSDoc Documentation in Your IDE
+
+Hover over any method to see comprehensive documentation, examples, and parameter details - all without leaving your editor:
+
+```typescript
+// Hover over withRetries to see:
+// "Configures automatic retry behavior for failed requests.
+//  @param retries - Number of retry attempts or retry configuration object
+//  @example
+//    .withRetries(3)
+//    .withRetries({ attempts: 3, delay: 1000 })"
+create.get(url).withRetries(3);
+```
+
+#### 3. Discoverability Through Method Chaining
+
+Each method reveals what's available next. Explore the API naturally through autocomplete:
+
+```typescript
+// Discover available options as you chain
+create
+  .post(url)
+  .withHeaders() // ← See all header methods
+  .withBearerToken() // ← See all auth methods
+  .withTimeout() // ← See all timeout/retry methods
+  .withQueryParams(); // ← See all query param methods
+```
+
+#### 4. No Context Switching
+
+Stay in your flow. Everything you need is in your IDE - documentation, types, examples, and autocomplete. No alt-tabbing to documentation websites.
+
+This developer-first approach means you spend less time looking things up and more time writing code that works.
+
 ## Mental Model
 
 ### 1. **Separation of Building and Execution**
@@ -180,7 +256,7 @@ This pattern makes the API self-documenting - any method starting with `with...`
 
 The typical request lifecycle follows this pattern:
 
-```
+```text
 Build → Configure → Execute → Transform → Handle
 ```
 
@@ -231,6 +307,68 @@ yarn add create-request
 pnpm add create-request
 ```
 
+## Named Exports
+
+The library provides both default and named exports:
+
+**Default Export:**
+
+- `create` - Main API object with factory methods (`get`, `post`, `put`, `del`, `patch`, `head`, `options`, `api`) and global `config`
+
+**Named Exports:**
+
+**Enums:**
+
+- `HttpMethod`, `RequestPriority`, `CredentialsPolicy`, `RequestMode`, `RedirectMode`, `SameSitePolicy`, `ReferrerPolicy`, `CacheMode`
+
+**Types:**
+
+- `RetryCallback`, `RetryConfig`, `CookiesRecord`, `CookieOptions`, `RequestConfig`, `GraphQLOptions`, `RequestOptions`, `ErrorInterceptor`, `RequestInterceptor`, `RetryDelayFunction`, `ResponseInterceptor`
+
+**Classes:**
+
+- `ResponseWrapper`, `CookieUtils`, `RequestError`
+
+**Request Classes:**
+
+- `GetRequest`, `PostRequest`, `PutRequest`, `DeleteRequest`, `PatchRequest`, `HeadRequest`, `OptionsRequest`
+
+**Factory Functions:**
+
+- `createGet`, `createPost`, `createPut`, `createDelete`, `createPatch`, `createHead`, `createOptions`, `createApi`
+
+```typescript
+// Default export
+import create from "create-request";
+
+// Named exports
+import { RequestError, CacheMode, createGet } from "create-request";
+```
+
+## Tree-Shaking Guide
+
+All named exports are tree-shakeable. The library is marked with `"sideEffects": false`, enabling bundlers to eliminate unused code.
+
+**Tree-shakeable:**
+
+- ✅ All named exports (enums, types, classes, factory functions)
+- ✅ Individual factory functions (`createGet`, `createPost`, etc.)
+- ✅ Individual request classes (`GetRequest`, `PostRequest`, etc.)
+
+**Not tree-shakeable:**
+
+- Default export (`create`) - imports the entire API object (library is small, so this is usually fine)
+
+**Tip:** For maximum tree-shaking, you can use named exports when you only need specific functionality:
+
+```typescript
+// Tree-shakeable - only imports what you use
+import { createGet } from "create-request";
+
+// Imports entire library (recommended for most use cases)
+import create from "create-request";
+```
+
 ## Basic Usage
 
 ### Creating Requests
@@ -305,15 +443,15 @@ const request = create
 
   // Fetch API options
   // Note: These methods support three styles - Fluent API (shown below), Enum-based (e.g., .withMode(RequestMode.CORS)), or String-based (e.g., .withMode("cors"))
-  .withCredentials.INCLUDE() // Includes cookies with cross-origin requests
+  .withCredentials.INCLUDE() // Includes cookies with cross-origin requests (Fluent API)
   .withMode.CORS() // Controls CORS behavior
-  .withRedirect.FOLLOW() // Controls redirect behavior (follow, error, manual)
+  .withRedirect.FOLLOW() // Controls redirect behavior
   .withReferrer("https://example.com") // Sets request referrer
   .withReferrerPolicy.NO_REFERRER_WHEN_DOWNGRADE() // Controls referrer policy
   .withPriority.HIGH() // Sets request priority
   .withKeepAlive(true) // Keeps connection alive after the page is unloaded
   .withIntegrity("sha256-abcdef1234567890...") // Sets subresource integrity hash
-  .withCache("no-cache"); // Controls cache behavior (or use .withCache.NO_CACHE())
+  .withCache("no-cache"); // Direct string value (or use .withCache.NO_CACHE() for Fluent API)
 ```
 
 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:
@@ -557,7 +695,14 @@ const newUser = await api.post().withBody({ name: "John" }).getJson();
 
 #### Available Request Methods
 
-The API builder provides access to all request configuration methods from `BaseRequest` that can be used as defaults. These methods will apply to all requests made through the API instance:
+The API builder provides access to most request configuration methods from `BaseRequest` that can be used as defaults. These methods will apply to all requests made through the API instance.
+
+**Important limitations:**
+
+- Methods that are request-specific (like `withBody`, `withGraphQL`, `withAbortController`) are not available in ApiBuilder
+- The Fluent API (e.g., `.withCache.NO_STORE()`) is not supported - use direct calls with string or enum values instead
+
+Available methods:
 
 **Authentication & Headers:**
 
@@ -573,13 +718,24 @@ The API builder provides access to all request configuration methods from `BaseR
 - `withCookies(cookies)` - Add cookies to all requests
 - `withCookie(name, value)` - Add a single cookie
 
+**Query Parameters:**
+
+- `withQueryParams(params)` - Add default query parameters to all requests
+- `withQueryParam(key, value)` - Add a single default query parameter
+
 **Request Configuration:**
 
 - `withTimeout(timeout)` - Set default timeout for all requests
 - `withRetries(retries)` - Configure default retry behavior
 - `withReferrer(referrer)` - Set default referrer
+- `withReferrerPolicy(policy)` - Set default referrer policy (use string or enum)
 - `withKeepAlive(keepalive)` - Configure keep-alive
 - `withIntegrity(integrity)` - Set integrity check
+- `withMode(mode)` - Set request mode (use string or enum)
+- `withCredentials(credentials)` - Set credentials policy (use string or enum)
+- `withRedirect(redirect)` - Set redirect behavior (use string or enum)
+- `withPriority(priority)` - Set request priority (use string or enum)
+- `withCache(cache)` - Set cache mode (use string or enum)
 
 **CSRF Protection:**
 
@@ -596,15 +752,23 @@ The API builder provides access to all request configuration methods from `BaseR
 These methods can be chained together and will apply to all requests made through the API instance:
 
 ```typescript
+import { CacheMode, CredentialsPolicy, RequestMode } from "create-request";
+
 const api = create
   .api()
   .withBaseURL("https://api.example.com")
   .withBearerToken("token123")
   .withCookies({ session: "abc123" })
   .withTimeout(5000)
-  .withHeaders({ "X-Custom": "value" });
-
-// All requests will include the Bearer token, cookies, timeout, and headers
+  .withHeaders({ "X-Custom": "value" })
+  .withQueryParams({ apiVersion: "v2" }) // Default query params
+  .withCache("no-store") // Direct string value
+  // Or use enum: .withCache(CacheMode.NO_STORE)
+  .withCredentials("include"); // Direct string value
+// Or use enum: .withCredentials(CredentialsPolicy.INCLUDE)
+// Note: Fluent API like .withCache.NO_STORE() is NOT supported in ApiBuilder
+
+// All requests will include the Bearer token, cookies, timeout, headers, query params, and cache settings
 await api.get("/users").getJson();
 await api.post("/posts").withBody({ title: "Hello" }).getJson();
 ```
@@ -687,13 +851,17 @@ const api = create
 
 ```typescript
 // Set up your API once
+import { CacheMode } from "create-request";
+
 const api = create
   .api()
   .withBaseURL("https://api.example.com/v1")
   .withHeaders({ "Content-Type": "application/json" })
   .withCookies({ session: "abc123" })
   .withBearerToken("token123")
-  .withTimeout(20000);
+  .withTimeout(20000)
+  .withQueryParams({ format: "json" })
+  .withCache(CacheMode.NO_CACHE);
 
 // Use throughout your application
 async function getUsers() {
@@ -1100,7 +1268,7 @@ create-request is designed to be lightweight and efficient:
 - **Memory Efficient**: Doesn't create unnecessary objects
 - **Clean API**: Simple and intuitive interface
 
-## Browser Support
+## Browser & Node.js Support
 
 This library works with all browsers that support the Fetch API:
 
@@ -1110,11 +1278,15 @@ This library works with all browsers that support the Fetch API:
 - Edge 14+
 - Opera 29+
 
+For Node.js:
+
+- Node.js 18.3.0+ (native fetch support required)
+
 ## Comparison of JavaScript HTTP Client Libraries
 
 | 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     |
+| **Size (min+gzip)**   | ~6.4KB         | 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**            | ✅             | ✅     | ✅      | ✅         | ✅      | ✅     | ❌         | ❌       |

package/dist/library/BaseRequest.d.ts

@@ -711,6 +711,21 @@ export declare abstract class BaseRequest {
      * ```
      */
     getBlob(): Promise<Blob>;
+    /**
+     * Execute the request and get the response body as an ArrayBuffer.
+     * Useful for processing binary data at a low level.
+     *
+     * @returns A promise that resolves to the response body as an ArrayBuffer
+     * @throws {RequestError} When the request fails or reading the response fails
+     *
+     * @example
+     * ```typescript
+     * const buffer = await request.getArrayBuffer();
+     * const uint8Array = new Uint8Array(buffer);
+     * // Process the binary data
+     * ```
+     */
+    getArrayBuffer(): Promise<ArrayBuffer>;
     /**
      * 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.

package/dist/library/RequestError.d.ts

@@ -26,9 +26,9 @@ export declare class RequestError extends Error {
     /** The HTTP method that was used (e.g., 'GET', 'POST') */
     readonly method: string;
     /** Whether the request failed due to a timeout */
-    readonly isTimeout?: boolean;
+    readonly isTimeout: boolean;
     /** Whether the request was aborted (cancelled) */
-    readonly isAborted?: boolean;
+    readonly isAborted: boolean;
     /**
      * Creates a new RequestError instance.
      *