create-request 1.0.0 → 1.2.0

package/README.md

@@ -14,7 +14,7 @@
 - [Installation](#installation)
 - [Basic Usage](#basic-usage)
 - [Advanced Usage](#advanced-usage)
-- [GraphQL Support](#graphql-support)
+- [GraphQL Support](#graphql-requests)
 - [Interceptors](#interceptors)
 - [TypeScript Support](#typescript-support)
 - [CSRF Protection](#csrf-protection)
@@ -247,13 +247,33 @@ const result = await create
   .getJson();
 ```
 
+#### GraphQL Error Handling
+
+GraphQL errors do not cause exceptions by default. Use the `throwOnError` option to make them throw exceptions:
+
+```typescript
+// Throw an error if the GraphQL response contains errors
+try {
+  const user = await create
+    .post("https://api.example.com/graphql")
+    .withGraphQL(
+      "query GetUser($id: ID!) { user(id: $id) { name email } }",
+      { id: "123" },
+      { throwOnError: true }
+    )
+    .getJson();
+} catch (error) {
+  console.error(error.message);
+}
+```
+
 The `withGraphQL` method automatically:
 
 - Formats the body as JSON with `query` and optional `variables` properties
 - Sets `Content-Type` to `application/json`
-- Trims whitespace from the query string
 - Validates the query is non-empty
 - Validates variables are a plain object (not arrays or null)
+- Optionally throws errors when GraphQL response contains errors (with `throwOnError: true`)
 
 ### Query Parameters Advanced Features
 
@@ -358,52 +378,6 @@ try {
 
 ## Advanced Usage
 
-### GraphQL Support
-
-`create-request` provides first-class support for GraphQL with the `withGraphQL` method:
-
-```typescript
-// Simple query
-const query = "query { user { name email } }";
-const data = await create
-  .post("https://api.example.com/graphql")
-  .withGraphQL(query)
-  .getJson();
-
-// Query with variables
-const queryWithVars = "query GetUser($id: ID!) { user(id: $id) { name email } }";
-const user = await create
-  .post("https://api.example.com/graphql")
-  .withGraphQL(queryWithVars, { id: "123" })
-  .getJson();
-
-// Mutation
-const mutation =
-  "mutation CreateUser($name: String!) { createUser(name: $name) { id name } }";
-const result = await create
-  .post("https://api.example.com/graphql")
-  .withGraphQL(mutation, { name: "John Doe" })
-  .getJson();
-
-// Complex variables with nested objects
-const complexQuery =
-  "query SearchUsers($filters: UserFilters!) { users(filters: $filters) { id name } }";
-const results = await create
-  .post("https://api.example.com/graphql")
-  .withGraphQL(complexQuery, {
-    filters: {
-      name: "John",
-      age: 30,
-      tags: ["active", "verified"],
-      metadata: {
-        source: "web",
-        verified: true,
-      },
-    },
-  })
-  .getJson();
-```
-
 ### 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.
@@ -745,7 +719,7 @@ This library works with all browsers that support the Fetch API:
 
 | Feature             | create-request | Fetch  | Axios   | SuperAgent | Got     | Ky     | node-fetch | Redaxios |
 | ------------------- | -------------- | ------ | ------- | ---------- | ------- | ------ | ---------- | -------- |
-| **Size (min+gzip)** | ~5.5KB         | Native | ~13.6KB | ~17.8KB    | ~17.8KB | ~3.4KB | ~7.7KB     | ~1KB     |
+| **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**          | ✅             | ✅     | ✅      | ✅         | ✅      | ✅     | ❌         | ❌       |

package/dist/library/BaseRequest.d.ts

@@ -1,5 +1,5 @@
 import { type HttpMethod, RedirectMode, RequestMode, RequestPriority, ReferrerPolicy, CredentialsPolicy } from "./enums.js";
-import type { RequestOptions, RetryCallback, CookiesRecord, CookieOptions, RequestInterceptor, ResponseInterceptor, ErrorInterceptor } from "./types.js";
+import type { RetryCallback, CookiesRecord, CookieOptions, RequestOptions, GraphQLOptions, ErrorInterceptor, RequestInterceptor, ResponseInterceptor } from "./types.js";
 import { ResponseWrapper } from "./ResponseWrapper.js";
 /**
  * Base class with common functionality for all request types
@@ -16,6 +16,11 @@ export declare abstract class BaseRequest {
     private responseInterceptors;
     private errorInterceptors;
     constructor(url: string);
+    /**
+     * Get GraphQL options if set (only for BodyRequest subclasses)
+     * @returns GraphQL options or undefined
+     */
+    protected getGraphQLOptions(): GraphQLOptions | undefined;
     /**
      * Creates a fluent API for setting enum-based options
      * Combines direct setter with convenience methods
@@ -52,7 +57,7 @@ export declare abstract class BaseRequest {
      *
      * @param timeout - The timeout in milliseconds
      * @returns The request instance for chaining
-     * @throws Error if timeout is not a positive number
+     * @throws RequestError if timeout is not a positive number
      *
      * @example
      * request.withTimeout(5000); // 5 seconds timeout
@@ -63,7 +68,7 @@ export declare abstract class BaseRequest {
      *
      * @param retries - Number of retry attempts before failing
      * @returns The request instance for chaining
-     * @throws Error if retries is not a non-negative integer
+     * @throws RequestError if retries is not a non-negative integer
      *
      * @example
      * request.withRetries(3); // Retry up to 3 times
@@ -154,6 +159,29 @@ export declare abstract class BaseRequest {
         LOW: () => BaseRequest;
         AUTO: () => BaseRequest;
     };
+    /**
+     * Sets the integrity hash for subresource integrity verification
+     * @param integrity - The integrity hash string (e.g., "sha256-...")
+     * @returns The instance for chaining
+     * @example
+     * request.withIntegrity("sha256-abcdef1234567890...")
+     */
+    withIntegrity(integrity: string): this;
+    /**
+     * Sets cache mode - supports both direct call and fluent API
+     * @example
+     * request.withCache("no-cache")
+     * request.withCache(CacheMode.NO_CACHE)
+     * request.withCache.NO_CACHE()
+     */
+    get withCache(): ((cache: string) => BaseRequest) & {
+        DEFAULT: () => BaseRequest;
+        NO_STORE: () => BaseRequest;
+        RELOAD: () => BaseRequest;
+        NO_CACHE: () => BaseRequest;
+        FORCE_CACHE: () => BaseRequest;
+        ONLY_IF_CACHED: () => BaseRequest;
+    };
     /**
      * Adds query parameters to the request URL
      * @param params - An object containing the query parameters
@@ -309,9 +337,20 @@ export declare abstract class BaseRequest {
      * Execute the request and parse the response as JSON
      *
      * @returns A promise that resolves to the parsed JSON data
+     * @throws {RequestError} When the request fails, JSON parsing fails, GraphQL errors occur (if throwOnError enabled), or body is already consumed
      *
      * @example
      * const users = await request.getJson<User[]>();
+     *
+     * @example
+     * // Error handling - errors are always RequestError
+     * try {
+     *   const data = await request.getJson();
+     * } catch (error) {
+     *   if (error instanceof RequestError) {
+     *     console.log(error.status, error.url, error.method);
+     *   }
+     * }
      */
     getJson<T = unknown>(): Promise<T>;
     /**
@@ -347,6 +386,7 @@ export declare abstract class BaseRequest {
      *
      * @param selector - Optional function to extract and transform data
      * @returns A promise that resolves to the selected data
+     * @throws {RequestError} When the request fails, JSON parsing fails, or the selector throws an error
      *
      * @example
      * // Get full response
@@ -354,6 +394,16 @@ export declare abstract class BaseRequest {
      *
      * // Extract specific data
      * const users = await request.getData(data => data.results.users);
+     *
+     * @example
+     * // Error handling - errors are always RequestError
+     * try {
+     *   const data = await request.getData();
+     * } catch (error) {
+     *   if (error instanceof RequestError) {
+     *     console.log(error.status, error.url, error.method);
+     *   }
+     * }
      */
     getData<T = unknown, R = T>(selector?: (data: T) => R): Promise<T | R>;
     /**

package/dist/library/BodyRequest.d.ts

@@ -1,5 +1,5 @@
 import { BaseRequest } from "./BaseRequest.js";
-import type { Body } from "./types.js";
+import type { Body, GraphQLOptions } from "./types.js";
 import type { ResponseWrapper } from "./ResponseWrapper.js";
 /**
  * Base class for requests that can have a body (POST, PUT, PATCH)
@@ -7,6 +7,7 @@ import type { ResponseWrapper } from "./ResponseWrapper.js";
 export declare abstract class BodyRequest extends BaseRequest {
     protected body?: Body;
     private bodyType?;
+    private graphQLOptions;
     constructor(url: string);
     /**
      * Sets the body of the request
@@ -19,6 +20,7 @@ export declare abstract class BodyRequest extends BaseRequest {
      *
      * @param query - The GraphQL query or mutation string
      * @param variables - Optional variables object to pass with the query
+     * @param options - Optional GraphQL-specific options
      * @returns The request instance for chaining
      *
      * @example
@@ -28,13 +30,23 @@ export declare abstract class BodyRequest extends BaseRequest {
      * @example
      * const request = new PostRequest('/graphql')
      *   .withGraphQL('mutation { createUser(name: $name) { id } }', { name: 'John' });
+     *
+     * @example
+     * // Throw an error if the GraphQL response contains errors
+     * const request = new PostRequest('/graphql')
+     *   .withGraphQL('query { user { id } }', undefined, { throwOnError: true });
      */
-    withGraphQL(query: string, variables?: Record<string, unknown>): this;
+    withGraphQL(query: string, variables?: Record<string, unknown>, options?: GraphQLOptions): this;
     /**
      * Check if Content-Type header is already set (case-insensitive)
      */
     private hasContentType;
     private setContentTypeIfNeeded;
+    /**
+     * Get the GraphQL options if set
+     * @returns The GraphQL options or undefined
+     */
+    protected getGraphQLOptions(): GraphQLOptions | undefined;
     /**
      * Execute the request and return the ResponseWrapper
      * Overrides the base implementation to add body handling

package/dist/library/ResponseWrapper.d.ts

@@ -1,3 +1,4 @@
+import type { GraphQLOptions } from "./types.js";
 /**
  * Wrapper for HTTP responses with methods to transform the response data
  * Provides caching and conversion between different response formats.
@@ -10,22 +11,40 @@ export declare class ResponseWrapper {
     private jsonCache;
     private blobCache;
     private bodyUsed;
-    constructor(response: Response, url?: string, method?: string);
+    private graphQLOptions?;
+    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 for GraphQL errors and throw if throwOnError is enabled
+     * @param data - The parsed JSON data
+     * @throws RequestError if GraphQL response contains errors and throwOnError is enabled
+     */
+    private checkGraphQLErrors;
     /**
      * Parse the response body as JSON
      * Caches the result for subsequent calls.
+     * If GraphQL options are set with throwOnError=true, will check for GraphQL errors and throw.
      *
      * @returns The parsed JSON data
-     * @throws Error if the response has already been consumed in a different format
+     * @throws {RequestError} When the request fails, JSON parsing fails, GraphQL errors occur (if throwOnError enabled), or body is already consumed
      *
      * @example
      * const data = await response.getJson();
      * console.log(data.items);
+     *
+     * @example
+     * // Error handling - errors are always RequestError
+     * try {
+     *   const data = await response.getJson();
+     * } catch (error) {
+     *   if (error instanceof RequestError) {
+     *     console.log(error.status, error.url, error.method);
+     *   }
+     * }
      */
     getJson<T = unknown>(): Promise<T>;
     /**
@@ -34,7 +53,7 @@ export declare class ResponseWrapper {
      * if the body has already been consumed in those formats.
      *
      * @returns The response text
-     * @throws Error if the response has already been consumed in an incompatible format
+     * @throws {RequestError} When reading fails or the response has already been consumed in an incompatible format
      *
      * @example
      * const text = await response.getText();
@@ -46,7 +65,7 @@ export declare class ResponseWrapper {
      * if the body has already been consumed as text.
      *
      * @returns The response as a Blob
-     * @throws Error if the response has already been consumed in an incompatible format
+     * @throws {RequestError} When reading fails or the response has already been consumed in an incompatible format
      *
      * @example
      * const blob = await response.getBlob();
@@ -58,7 +77,7 @@ export declare class ResponseWrapper {
      * This method consumes the body and should only be called once.
      *
      * @returns The response body as a ReadableStream or null
-     * @throws Error if the response body has already been consumed
+     * @throws {RequestError} When the response body has already been consumed
      *
      * @example
      * const stream = response.getBody();
@@ -74,6 +93,7 @@ export declare class ResponseWrapper {
      *
      * @param selector - Optional function to extract and transform data
      * @returns A promise that resolves to the selected data
+     * @throws {RequestError} When the request fails, JSON parsing fails, or the selector throws an error
      *
      * @example
      * // Get full response
@@ -81,6 +101,16 @@ export declare class ResponseWrapper {
      *
      * // Extract specific data
      * const users = await response.getData(data => data.results.users);
+     *
+     * @example
+     * // Error handling - errors are always RequestError
+     * try {
+     *   const data = await response.getData();
+     * } catch (error) {
+     *   if (error instanceof RequestError) {
+     *     console.log(error.status, error.url, error.method);
+     *   }
+     * }
      */
     getData<T = unknown, R = T>(selector?: (data: T) => R): Promise<T | R>;
 }

package/dist/library/enums.d.ts

@@ -72,3 +72,14 @@ export declare enum ReferrerPolicy {
     NO_REFERRER_WHEN_DOWNGRADE = "no-referrer-when-downgrade",
     STRICT_ORIGIN_WHEN_CROSS_ORIGIN = "strict-origin-when-cross-origin"
 }
+/**
+ * Cache modes for fetch requests
+ */
+export declare enum CacheMode {
+    RELOAD = "reload",
+    DEFAULT = "default",
+    NO_CACHE = "no-cache",
+    NO_STORE = "no-store",
+    FORCE_CACHE = "force-cache",
+    ONLY_IF_CACHED = "only-if-cached"
+}