create-request 1.4.2 → 1.4.3-rc.1

package/README.md

@@ -16,9 +16,13 @@
 - [Why create-request](#why-create-request)
 - [Installation](#installation)
 - [Basic Usage](#basic-usage)
-- [Advanced Usage](#advanced-usage)
-- [GraphQL Support](#graphql-requests)
+- [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)
 - [Performance Considerations](#performance-considerations)
@@ -414,9 +418,211 @@ try {
 }
 ```
 
-## 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.
+
+#### Creating an API Instance
+
+```typescript
+import create from "create-request";
+
+// Create a configured API instance
+const api = create.api().withBaseURL("https://api.example.com").withTimeout(20000);
+
+// Use it with relative URLs
+const users = await api.get("/users").getJson();
+
+// Or without URL (uses baseURL)
+const users = await api.get().getJson();
+const newUser = await api.post().withBody({ name: "John" }).getJson();
+```
+
+#### Core API Builder Method
+
+- **`.withBaseURL(baseURL: string)`** - Set the base URL for all requests. Relative URLs will be resolved against this base URL.
+
+#### 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:
+
+**Authentication & Headers:**
+
+- `withHeaders(headers)` - Set default headers for all requests
+- `withHeader(key, value)` - Add a single default header
+- `withAuthorization(authValue)` - Set Authorization header
+- `withBasicAuth(username, password)` - Add Basic Authentication
+- `withBearerToken(token)` - Add Bearer token authentication
+- `withContentType(contentType)` - Set default Content-Type header
+
+**Cookies:**
+
+- `withCookies(cookies)` - Add cookies to all requests
+- `withCookie(name, value)` - Add a single cookie
+
+**Request Configuration:**
+
+- `withTimeout(timeout)` - Set default timeout for all requests
+- `withRetries(retries)` - Configure default retry behavior
+- `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:**
+
+- `withCsrfToken(token, headerName?)` - Set CSRF token
+- `withoutCsrfProtection()` - Disable CSRF protection
+- `withAntiCsrfHeaders()` - Enable anti-CSRF headers
+
+**Interceptors:**
+
+- `withRequestInterceptor(interceptor)` - Add default request interceptor
+- `withResponseInterceptor(interceptor)` - Add default response interceptor
+- `withErrorInterceptor(interceptor)` - Add default error interceptor
+
+These methods can be chained together and will apply to all requests made through the API instance:
+
+```typescript
+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
+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:
+
+```typescript
+const api = create.api().withBaseURL("https://api.example.com");
+
+// Relative URLs are resolved against baseURL
+await api.get("users").getJson(); // → https://api.example.com/users
+await api.get("/users").getJson(); // → https://api.example.com/users
+await api.get("./users").getJson(); // → https://api.example.com/users
+
+// Absolute URLs are used as-is
+await api.get("https://other-api.com/data").getJson(); // → https://other-api.com/data
+
+// No URL uses baseURL directly
+await api.get().getJson(); // → https://api.example.com
+```
+
+#### Overriding Defaults
+
+You can override default settings on individual requests:
+
+```typescript
+const api = create
+  .api()
+  .withBaseURL("https://api.example.com")
+  .withTimeout(5000)
+  .withBearerToken("token123");
+
+// Override timeout for this specific request
+await api.get("/slow-endpoint").withTimeout(30000).getJson();
+
+// Override headers (merges with defaults)
+await api
+  .get("/users")
+  .withBearerToken("newtoken")
+  .withHeaders({ "X-Custom": "value" })
+  .getJson();
+// Result: Authorization: "Bearer newtoken", X-Custom: "value"
+```
+
+#### All HTTP Methods Supported
+
+The API instance supports all HTTP methods:
+
+```typescript
+const api = create.api().withBaseURL("https://api.example.com");
+
+await api.get("/users").getJson();
+await api.post("/users").withBody({ name: "John" }).getJson();
+await api.put("/users/1").withBody({ name: "Jane" }).getJson();
+await api.patch("/users/1").withBody({ status: "active" }).getJson();
+await api.del("/users/1").getJson();
+await api.head("/users").getResponse();
+await api.options("/users").getResponse();
+```
+
+#### Merging Default Headers
+
+Multiple calls to `withHeaders` will merge headers, with later calls taking precedence:
+
+```typescript
+const api = create
+  .api()
+  .withBaseURL("https://api.example.com")
+  .withBearerToken("token123")
+  .withHeaders({ "X-Custom": "value1" })
+  .withHeaders({ "X-Other": "value2" })
+  .withBearerToken("newtoken");
+
+// Result: Authorization: "Bearer newtoken", X-Custom: "value1", X-Other: "value2"
+```
+
+#### Complete Example
+
+```typescript
+// Set up your API once
+const api = create
+  .api()
+  .withBaseURL("https://api.example.com/v1")
+  .withHeaders({ "Content-Type": "application/json" })
+  .withCookies({ session: "abc123" })
+  .withBearerToken("token123")
+  .withTimeout(20000);
+
+// Use throughout your application
+async function getUsers() {
+  return api.get("/users").getJson();
+}
+
+async function createUser(userData: User) {
+  return api.post("/users").withBody(userData).getJson();
+}
+
+async function updateUser(id: string, userData: Partial<User>) {
+  return api.put(`/users/${id}`).withBody(userData).getJson();
+}
+
+async function deleteUser(id: string) {
+  return api.del(`/users/${id}`).getJson();
+}
+```
 
-### Automatic Retries with Delay
+## Automatic Retries with Delay
 
 The `withRetries()` method supports both simple number-based retries and object-based configuration with customizable delays:
 
@@ -463,7 +669,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.
 
@@ -597,7 +803,7 @@ const asyncData = await create
   .getJson();
 ```
 
-### Request Cancellation
+## Request Cancellation
 
 ```typescript
 const controller = new AbortController();
@@ -623,7 +829,7 @@ try {
 }
 ```
 
-### URL Handling
+## URL Handling
 
 The library handles both absolute and relative URLs, and automatically merges query parameters:
 
@@ -648,7 +854,7 @@ const encoded = await create
   .getJson();
 ```
 
-### Data Selection
+## Data Selection
 
 The `getData` method provides a powerful way to extract and transform specific data from API responses:
 
@@ -815,7 +1021,6 @@ This library works with all browsers that support the Fetch API:
 | **TypeScript**      | ✅             | ✅     | ✅      | ✅         | ✅      | ✅     | ✅         | ✅       |
 | **Streaming**       | ✅             | ✅     | ✅      | ✅         | ✅      | ✅     | ✅         | ❌       |
 | **Progress**        | ❌             | ❌     | ✅      | ✅         | ✅      | ✅     | ❌         | ❌       |
-| **Middleware**      | ❌             | ❌     | ✅      | ✅         | ✅      | ✅     | ❌         | ❌       |
 | **Cookies**         | ✅             | ✅     | 🛠️      | ✅         | ✅      | ❌     | ❌         | ❌       |
 | **Pagination API**  | ❌             | ❌     | ❌      | ❌         | ✅      | ❌     | ❌         | ❌       |
 | **Zero Deps**       | ✅             | ✅     | ❌      | ❌         | ❌      | ✅     | ✅         | ✅       |

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

@@ -0,0 +1,182 @@
+import type { CookiesRecord, CookieOptions, RetryConfig, RequestInterceptor, ResponseInterceptor, ErrorInterceptor } from "./types.js";
+import type { GetRequest, PostRequest, PutRequest, DeleteRequest, PatchRequest, HeadRequest, OptionsRequest } from "./requestMethods.js";
+interface ApiBuilderRequestMethods {
+    withoutCsrfProtection(): ApiBuilder;
+    withAntiCsrfHeaders(): ApiBuilder;
+    withTimeout(timeout: number): ApiBuilder;
+    withReferrer(referrer: string): ApiBuilder;
+    withKeepAlive(keepalive: boolean): ApiBuilder;
+    withIntegrity(integrity: string): ApiBuilder;
+    withHeader(key: string, value: string): ApiBuilder;
+    withHeaders(headers: Record<string, string>): ApiBuilder;
+    withRetries(retries: number | RetryConfig): ApiBuilder;
+    withBearerToken(token: string): ApiBuilder;
+    withCookies(cookies: CookiesRecord): ApiBuilder;
+    withContentType(contentType: string): ApiBuilder;
+    withAuthorization(authValue: string): ApiBuilder;
+    withBasicAuth(username: string, password: string): ApiBuilder;
+    withCsrfToken(token: string, headerName?: string): ApiBuilder;
+    withErrorInterceptor(interceptor: ErrorInterceptor): ApiBuilder;
+    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.
+ * Allows you to set default headers, timeouts, authentication, and other options
+ * that will be applied to all requests created through this builder.
+ *
+ * @example
+ * ```typescript
+ * const api = create.api()
+ *   .withBaseURL("https://api.example.com")
+ *   .withBearerToken("token123")
+ *   .withTimeout(5000);
+ *
+ * // All requests will use the base URL, bearer token, and timeout
+ * await api.get("/users").getJson();
+ * await api.post("/posts").withBody({ title: "Hello" }).getJson();
+ * ```
+ */
+export declare class ApiBuilder {
+    private baseURL?;
+    private modifiers?;
+    /**
+     * Sets the base URL for all requests created through this API builder.
+     * Relative URLs will be resolved against this base URL.
+     *
+     * @param baseURL - The base URL to use for all requests
+     * @returns The API builder instance for method chaining
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * await api.get("/users").getJson(); // Requests https://api.example.com/users
+     * ```
+     */
+    withBaseURL(baseURL: string): this;
+    /**
+     * Adds a modifier function that will be applied to all requests created through this builder.
+     *
+     * @private
+     * @param modifier - A function that modifies a request and returns it
+     * @returns The API builder instance for method chaining
+     */
+    private addModifier;
+    /**
+     * Creates a GET request with the configured default settings.
+     *
+     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
+     * @returns A GetRequest instance ready to be executed
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * await api.get("/users").getJson();
+     * await api.get("https://other.com/data").getJson(); // Absolute URL overrides base
+     * ```
+     */
+    get: (url?: string) => GetRequest;
+    /**
+     * Creates a POST request with the configured default settings.
+     *
+     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
+     * @returns A PostRequest instance ready to be executed
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * await api.post("/users").withBody({ name: "John" }).getJson();
+     * ```
+     */
+    post: (url?: string) => PostRequest;
+    /**
+     * Creates a PUT request with the configured default settings.
+     *
+     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
+     * @returns A PutRequest instance ready to be executed
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * await api.put("/users/123").withBody({ name: "Jane" }).getJson();
+     * ```
+     */
+    put: (url?: string) => PutRequest;
+    /**
+     * Creates a DELETE request with the configured default settings.
+     *
+     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
+     * @returns A DeleteRequest instance ready to be executed
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * await api.del("/users/123").getResponse();
+     * ```
+     */
+    del: (url?: string) => DeleteRequest;
+    /**
+     * Creates a PATCH request with the configured default settings.
+     *
+     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
+     * @returns A PatchRequest instance ready to be executed
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * await api.patch("/users/123").withBody({ name: "Updated" }).getJson();
+     * ```
+     */
+    patch: (url?: string) => PatchRequest;
+    /**
+     * Creates a HEAD request with the configured default settings.
+     *
+     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
+     * @returns A HeadRequest instance ready to be executed
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * const response = await api.head("/users").getResponse();
+     * ```
+     */
+    head: (url?: string) => HeadRequest;
+    /**
+     * Creates an OPTIONS request with the configured default settings.
+     *
+     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
+     * @returns An OptionsRequest instance ready to be executed
+     * @example
+     * ```typescript
+     * const api = create.api().withBaseURL("https://api.example.com");
+     * await api.options("/users").getResponse();
+     * ```
+     */
+    options: (url?: string) => OptionsRequest;
+    /**
+     * Creates a new ApiBuilder instance with a Proxy that enables dynamic method forwarding.
+     * The Proxy allows calling any `with*` method from BaseRequest on the API builder,
+     * which will apply that configuration to all requests created through this builder.
+     *
+     * @internal
+     */
+    constructor();
+}
+/**
+ * Creates a new API builder instance for configuring default request settings.
+ * The builder allows you to set base URLs, authentication, headers, timeouts,
+ * and other options that will be applied to all requests created through it.
+ *
+ * @returns A new ApiBuilder instance with all configuration methods available
+ * @example
+ * ```typescript
+ * // Create an API instance with default configuration
+ * const api = create.api()
+ *   .withBaseURL("https://api.example.com")
+ *   .withBearerToken("your-token")
+ *   .withTimeout(5000)
+ *   .withHeaders({ "X-Custom": "value" });
+ *
+ * // All requests will use these defaults
+ * const users = await api.get("/users").getJson();
+ * const newUser = await api.post("/users").withBody({ name: "John" }).getJson();
+ * ```
+ */
+export declare function api(): ApiBuilder & ApiBuilderRequestMethods;
+export {};