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

package/README.md

@@ -16,15 +16,16 @@
 - [Why create-request](#why-create-request)
 - [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)
@@ -310,44 +311,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 +381,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 +457,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 +486,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 +590,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 +637,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 +771,7 @@ const asyncData = await create
   .getJson();
 ```
 
-## Request Cancellation
+### Request Cancellation
 
 ```typescript
 const controller = new AbortController();
@@ -829,32 +797,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 +839,7 @@ try {
 }
 ```
 
-## TypeScript Support
+### TypeScript Support
 
 ```typescript
 interface User {
@@ -942,7 +885,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 +929,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:

package/dist/library/RequestError.d.ts

@@ -10,6 +10,7 @@ export declare class RequestError extends Error {
         response?: Response;
         isTimeout?: boolean;
         isAborted?: boolean;
+        cause?: Error;
     });
     /**
      * Static methods for creating specific types of RequestError

package/dist/library/ResponseWrapper.d.ts

@@ -3,16 +3,25 @@ import type { GraphQLOptions } from "./types.js";
  * Wrapper for HTTP responses with methods to transform the response data
  */
 export declare class ResponseWrapper {
-    private readonly response;
     readonly url?: string;
     readonly method?: string;
+    private readonly response;
     private graphQLOptions?;
+    private cachedBlob?;
+    private cachedText?;
+    private cachedJson?;
+    private cachedArrayBuffer?;
     constructor(response: Response, url?: string, method?: string, graphQLOptions?: GraphQLOptions);
     get status(): number;
     get statusText(): string;
     get headers(): Headers;
     get ok(): boolean;
     get raw(): Response;
+    /**
+     * Check if the response body has already been consumed and throw an error if so
+     * @throws RequestError if the body has already been consumed
+     */
+    private checkBodyNotConsumed;
     /**
      * Check for GraphQL errors and throw if throwOnError is enabled
      * @param data - The parsed JSON data
@@ -21,11 +30,10 @@ export declare class ResponseWrapper {
     private checkGraphQLErrors;
     /**
      * Parse the response body as JSON
-     * Note: This consumes the response body and can only be called once.
      * If GraphQL options are set with throwOnError=true, will check for GraphQL errors and throw.
      *
      * @returns The parsed JSON data
-     * @throws {RequestError} When the request fails, JSON parsing fails, GraphQL errors occur (if throwOnError enabled), or body is already consumed
+     * @throws {RequestError} When the request fails, JSON parsing fails, or GraphQL errors occur (if throwOnError enabled).
      *
      * @example
      * const data = await response.getJson();
@@ -44,10 +52,9 @@ export declare class ResponseWrapper {
     getJson<T = unknown>(): Promise<T>;
     /**
      * Get the response body as text
-     * Note: This consumes the response body and can only be called once.
      *
      * @returns The response text
-     * @throws {RequestError} When reading fails or the response has already been consumed
+     * @throws {RequestError} When reading fails
      *
      * @example
      * const text = await response.getText();
@@ -55,10 +62,9 @@ export declare class ResponseWrapper {
     getText(): Promise<string>;
     /**
      * Get the response body as a Blob
-     * Note: This consumes the response body and can only be called once.
      *
      * @returns The response as a Blob
-     * @throws {RequestError} When reading fails or the response has already been consumed
+     * @throws {RequestError} When reading fails
      *
      * @example
      * const blob = await response.getBlob();
@@ -67,10 +73,9 @@ export declare class ResponseWrapper {
     getBlob(): Promise<Blob>;
     /**
      * Get the response body as an ArrayBuffer
-     * Note: This consumes the response body and can only be called once.
      *
      * @returns The response as an ArrayBuffer
-     * @throws {RequestError} When reading fails or the response has already been consumed
+     * @throws {RequestError} When reading fails
      *
      * @example
      * const buffer = await response.getArrayBuffer();
@@ -80,6 +85,7 @@ export declare class ResponseWrapper {
     /**
      * Get the raw response body as a ReadableStream
      * Note: This consumes the response body and should only be called once.
+     * Unlike other methods, streams cannot be cached, so this will throw if the body is already consumed.
      *
      * @returns The response body as a ReadableStream or null
      * @throws {RequestError} When the response body has already been consumed

package/dist/library/apiBuilder.d.ts

@@ -20,8 +20,6 @@ interface ApiBuilderRequestMethods {
     withCookie(name: string, value: string | CookieOptions): ApiBuilder;
     withRequestInterceptor(interceptor: RequestInterceptor): ApiBuilder;
     withResponseInterceptor(interceptor: ResponseInterceptor): ApiBuilder;
-    withQueryParam(key: string, value: string | string[] | number | boolean | null | undefined): ApiBuilder;
-    withQueryParams(params: Record<string, string | string[] | number | boolean | null | undefined>): ApiBuilder;
 }
 /**
  * API builder for creating configured API instances with default settings.