create-request 1.3.0 → 1.4.0

package/README.md

@@ -1,9 +1,12 @@
 # create-request
 
-[![npm version](https://img.shields.io/npm/v/create-request.svg)](https://www.npmjs.com/package/create-request)
 [![License](https://img.shields.io/npm/l/create-request.svg)](https://github.com/DanielAmenou/create-request/blob/main/LICENSE)
+[![codecov](https://codecov.io/github/danielamenou/create-request/graph/badge.svg?token=OUBR6RNXZO)](https://codecov.io/github/danielamenou/create-request)
+[![npm downloads](https://img.shields.io/npm/dt/create-request.svg)](https://www.npmjs.com/package/create-request)
+[![npm version](https://img.shields.io/npm/v/create-request.svg)](https://www.npmjs.com/package/create-request)
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/create-request)](https://bundlephobia.com/package/create-request)
 [![TypeScript](https://img.shields.io/badge/TypeScript-4.7%2B-blue)](https://www.typescriptlang.org/)
+[![Known Vulnerabilities](https://snyk.io/test/github/DanielAmenou/create-request/badge.svg)](https://snyk.io/test/github/DanielAmenou/create-request)
 
 `create-request` is a modern TypeScript library that transforms how you make API calls. Built as an elegant wrapper around the native Fetch API, it provides a chainable, fluent interface that dramatically reduces boilerplate while adding powerful features like automatic retries, timeout handling, and comprehensive error management.
 
@@ -143,6 +146,8 @@ const request = create
 
   // Automatic retry configuration
   .withRetries(3) // Retry up to 3 times on failure
+  // Or use a config object with delay support:
+  .withRetries({ attempts: 3, delay: 1000 }) // Retry 3 times with 1 second delay between attempts
   .onRetry(({ attempt, error }) => {
     console.log(`Attempt ${attempt} failed: ${error.message}. Retrying...`);
   })
@@ -229,24 +234,17 @@ The library provides built-in support for GraphQL queries and mutations:
 
 ```typescript
 // GraphQL query without variables
+const userQuery = "query { users { id name email } }";
 const users = await create
   .post("https://api.example.com/graphql")
-  .withGraphQL("query { users { id name email } }")
+  .withGraphQL(userQuery)
   .getJson();
 
 // GraphQL query with variables
+const userQuery = "query GetUser($id: ID!) { user(id: $id) { name email } }";
 const user = await create
   .post("https://api.example.com/graphql")
-  .withGraphQL("query GetUser($id: ID!) { user(id: $id) { name email } }", { id: "123" })
-  .getJson();
-
-// GraphQL mutation
-const result = await create
-  .post("https://api.example.com/graphql")
-  .withGraphQL(
-    "mutation CreateUser($name: String!) { createUser(name: $name) { id name } }",
-    { name: "John Doe" }
-  )
+  .withGraphQL(userQuery, { id: "123" })
   .getJson();
 ```
 
@@ -256,14 +254,11 @@ GraphQL errors do not cause exceptions by default. Use the `throwOnError` option
 
 ```typescript
 // Throw an error if the GraphQL response contains errors
+const userQuery = "query GetUser($id: ID!) { user(id: $id) { name email } }";
 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 }
-    )
+    .withGraphQL(userQuery, { id: "123" }, { throwOnError: true })
     .getJson();
 } catch (error) {
   console.error(error.message);
@@ -421,6 +416,53 @@ try {
 
 ## Advanced Usage
 
+### Automatic Retries with Delay
+
+The `withRetries()` method supports both simple number-based retries and object-based configuration with customizable delays:
+
+```typescript
+// Simple number
+const request1 = create.get("https://api.example.com/data").withRetries(3);
+
+// With fixed delay between retries
+const request2 = create
+  .get("https://api.example.com/data")
+  .withRetries({ attempts: 3, delay: 1000 }); // Wait 1 second between retries
+
+// With exponential backoff function
+const request3 = create.get("https://api.example.com/data").withRetries({
+  attempts: 5,
+  delay: ({ attempt }) => Math.min(1000 * Math.pow(2, attempt - 1), 10000), // Exponential backoff capped at 10s
+});
+
+// With error-aware delay (e.g., longer delay for rate limits)
+const request4 = create.get("https://api.example.com/data").withRetries({
+  attempts: 3,
+  delay: ({ attempt, error }) => {
+    if (error.status === 429) {
+      return 5000; // Wait 5 seconds for rate limit errors
+    }
+    return attempt * 1000; // Linear backoff for other errors
+  },
+});
+```
+
+**Rate Limit Aware:**
+
+```typescript
+.withRetries({
+  attempts: 3,
+  delay: ({ error }) => {
+    if (error.status === 429) {
+      // Check Retry-After header if available
+      const retryAfter = error.response?.headers.get("Retry-After");
+      return retryAfter ? parseInt(retryAfter) * 1000 : 5000;
+    }
+    return 1000; // Default delay
+  },
+})
+```
+
 ### 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.

package/dist/library/BaseRequest.d.ts

@@ -1,5 +1,5 @@
 import { type HttpMethod, RedirectMode, RequestMode, RequestPriority, ReferrerPolicy, CredentialsPolicy } from "./enums.js";
-import type { RetryCallback, CookiesRecord, CookieOptions, RequestOptions, GraphQLOptions, ErrorInterceptor, RequestInterceptor, ResponseInterceptor } from "./types.js";
+import type { RetryConfig, 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
@@ -66,14 +66,36 @@ export declare abstract class BaseRequest {
     /**
      * Configure automatic retry behavior for failed requests
      *
-     * @param retries - Number of retry attempts before failing
+     * @param retries - Number of retry attempts before failing, or a configuration object
      * @returns The request instance for chaining
-     * @throws RequestError if retries is not a non-negative integer
+     * @throws RequestError if retries is not a non-negative integer or invalid config
      *
      * @example
+     * // Simple number (backward compatible)
      * request.withRetries(3); // Retry up to 3 times
+     *
+     * @example
+     * // With fixed delay
+     * request.withRetries({ attempts: 3, delay: 1000 }); // Retry 3 times with 1 second delay
+     *
+     * @example
+     * // With exponential backoff function
+     * request.withRetries({
+     *   attempts: 3,
+     *   delay: ({ attempt }) => Math.min(1000 * Math.pow(2, attempt - 1), 10000)
+     * });
+     *
+     * @example
+     * // With delay function based on error
+     * request.withRetries({
+     *   attempts: 3,
+     *   delay: ({ attempt, error }) => {
+     *     if (error.status === 429) return 5000; // Rate limited, wait longer
+     *     return attempt * 1000; // Exponential backoff
+     *   }
+     * });
      */
-    withRetries(retries: number): this;
+    withRetries(retries: number | RetryConfig): this;
     /**
      * Set a callback to be invoked before each retry attempt
      * Useful for implementing backoff strategies or logging retry attempts.
@@ -89,10 +111,26 @@ export declare abstract class BaseRequest {
      */
     onRetry(callback: RetryCallback): this;
     /**
-     * Sets credentials policy - supports both direct call and fluent API
+     * Sets the credentials policy for the request, controlling whether cookies and authentication
+     * headers are sent with cross-origin requests.
+     *
+     * @param credentialsPolicy - The credentials policy to use:
+     *   - `"include"` or `CredentialsPolicy.INCLUDE`: Always send credentials (cookies, authorization headers) with the request, even for cross-origin requests.
+     *   - `"omit"` or `CredentialsPolicy.OMIT`: Never send credentials, even for same-origin requests.
+     *   - `"same-origin"` or `CredentialsPolicy.SAME_ORIGIN`: Only send credentials for same-origin requests (default behavior in most browsers).
+     *
+     * @returns The request instance for chaining
+     *
      * @example
+     * // Using string values
      * request.withCredentials("include")
+     *
+     * @example
+     * // Using enum values
      * request.withCredentials(CredentialsPolicy.INCLUDE)
+     *
+     * @example
+     * // Using fluent API
      * request.withCredentials.INCLUDE()
      */
     get withCredentials(): ((credentialsPolicy: CredentialsPolicy | string) => BaseRequest) & {
@@ -101,22 +139,77 @@ export declare abstract class BaseRequest {
         SAME_ORIGIN: () => BaseRequest;
     };
     /**
-     * Allows providing an external AbortController to cancel the request
-     * @param controller - The AbortController to use for this request
-     * @returns The instance for chaining
+     * Allows providing an external AbortController to cancel the request.
+     * This is useful when you need to cancel a request from outside the request chain,
+     *
+     * @param controller - The AbortController to use for this request. When `controller.abort()` is called,
+     *   the request will be cancelled and throw an abort error.
+     *
+     * @returns The request instance for chaining
+     *
+     * @example
+     * const controller = new AbortController();
+     * const request = createRequest('/api/data')
+     *   .withAbortController(controller)
+     *   .getJson();
+     *
+     * // Later, cancel the request
+     * controller.abort();
+     *
+     * @example
+     * // Share abort controller across multiple requests
+     * const controller = new AbortController();
+     * request1.withAbortController(controller).getJson();
+     * request2.withAbortController(controller).getJson();
+     * // Aborting will cancel both requests
+     * controller.abort();
      */
     withAbortController(controller: AbortController): this;
     /**
-     * Sets the referrer for the request
-     * @param referrer - The referrer URL or policy
-     * @returns The instance for chaining
+     * Sets the referrer URL for the request. The referrer is the URL of the page that initiated the request.
+     * This can be used to override the default referrer that the browser would normally send.
+     *
+     * @param referrer - The referrer URL to send with the request. Can be:
+     *   - A full URL (e.g., "https://example.com/page")
+     *   - An empty string to omit the referrer
+     *   - A relative URL (will be resolved relative to the current page)
+     *
+     * @returns The request instance for chaining
+     *
+     * @example
+     * request.withReferrer("https://example.com/previous-page")
+     *
+     * @example
+     * // Omit referrer
+     * request.withReferrer("")
      */
     withReferrer(referrer: string): this;
     /**
-     * Sets referrer policy - supports both direct call and fluent API
+     * Sets the referrer policy for the request, controlling how much referrer information
+     * is sent with the request. This helps balance privacy and functionality.
+     *
+     * @param policy - The referrer policy to use:
+     *   - `"no-referrer"` or `ReferrerPolicy.NO_REFERRER`: Never send the referrer header.
+     *   - `"no-referrer-when-downgrade"` or `ReferrerPolicy.NO_REFERRER_WHEN_DOWNGRADE`: Send full referrer for same-origin or HTTPS→HTTPS, omit for HTTPS→HTTP (default in most browsers).
+     *   - `"origin"` or `ReferrerPolicy.ORIGIN`: Only send the origin (scheme, host, port), not the full URL.
+     *   - `"origin-when-cross-origin"` or `ReferrerPolicy.ORIGIN_WHEN_CROSS_ORIGIN`: Send full referrer for same-origin, only origin for cross-origin.
+     *   - `"same-origin"` or `ReferrerPolicy.SAME_ORIGIN`: Send full referrer for same-origin requests only, omit for cross-origin.
+     *   - `"strict-origin"` or `ReferrerPolicy.STRICT_ORIGIN`: Send origin for HTTPS→HTTPS or HTTP→HTTP, omit for HTTPS→HTTP.
+     *   - `"strict-origin-when-cross-origin"` or `ReferrerPolicy.STRICT_ORIGIN_WHEN_CROSS_ORIGIN`: Send full referrer for same-origin, origin for cross-origin HTTPS→HTTPS, omit for HTTPS→HTTP.
+     *   - `"unsafe-url"` or `ReferrerPolicy.UNSAFE_URL`: Always send the full referrer URL (may leak sensitive information).
+     *
+     * @returns The request instance for chaining
+     *
      * @example
+     * // Using string values
      * request.withReferrerPolicy("no-referrer")
+     *
+     * @example
+     * // Using enum values
      * request.withReferrerPolicy(ReferrerPolicy.NO_REFERRER)
+     *
+     * @example
+     * // Using fluent API
      * request.withReferrerPolicy.NO_REFERRER()
      */
     get withReferrerPolicy(): ((policy: ReferrerPolicy | string) => BaseRequest) & {
@@ -130,11 +223,30 @@ export declare abstract class BaseRequest {
         STRICT_ORIGIN_WHEN_CROSS_ORIGIN: () => BaseRequest;
     };
     /**
-     * Sets redirect mode - supports both direct call and fluent API
+     * Sets how the request handles HTTP redirects (3xx status codes).
+     *
+     * @param redirect - The redirect handling mode:
+     *   - `"follow"` or `RedirectMode.FOLLOW`: Automatically follow redirects. The fetch will transparently follow redirects and return the final response (default behavior).
+     *   - `"error"` or `RedirectMode.ERROR`: Treat redirects as errors. If a redirect occurs, the request will fail with an error.
+     *   - `"manual"` or `RedirectMode.MANUAL`: Return the redirect response without following it. The response will have a `type` of "opaqueredirect" and you can manually handle the redirect.
+     *
+     * @returns The request instance for chaining
+     *
      * @example
+     * // Using string values
      * request.withRedirect("follow")
+     *
+     * @example
+     * // Using enum values
      * request.withRedirect(RedirectMode.FOLLOW)
+     *
+     * @example
+     * // Using fluent API
      * request.withRedirect.FOLLOW()
+     *
+     * @example
+     * // Fail on redirects
+     * request.withRedirect.ERROR()
      */
     get withRedirect(): ((redirect: RedirectMode | string) => BaseRequest) & {
         FOLLOW: () => BaseRequest;
@@ -142,17 +254,47 @@ export declare abstract class BaseRequest {
         MANUAL: () => BaseRequest;
     };
     /**
-     * Sets the keepalive flag for the request
-     * @param keepalive - Whether to allow the request to outlive the page
-     * @returns The instance for chaining
+     * Sets the keepalive flag for the request. When enabled, the request can continue
+     * even after the page that initiated it is closed. This is useful for analytics,
+     * logging, or other background requests that should complete even if the user navigates away.
+     *
+     * @param keepalive - Whether to allow the request to outlive the page:
+     *   - `true`: The request will continue even if the page is closed or navigated away.
+     *   - `false`: The request will be cancelled if the page is closed (default).
+     *
+     * @returns The request instance for chaining
+     *
+     * @example
+     * // Send analytics event that should complete even if user navigates away
+     * request.withKeepAlive(true)
      */
     withKeepAlive(keepalive: boolean): this;
     /**
-     * Sets request priority - supports both direct call and fluent API
+     * Sets the priority hint for the request, indicating to the browser how important
+     * this request is relative to other requests. This helps the browser optimize resource loading.
+     *
+     * @param priority - The request priority:
+     *   - `"high"` or `RequestPriority.HIGH`: High priority - the browser should prioritize this request.
+     *   - `"low"` or `RequestPriority.LOW`: Low priority - the browser can defer this request if needed.
+     *   - `"auto"` or `RequestPriority.AUTO`: Automatic priority based on the request type (default).
+     *
+     * @returns The request instance for chaining
+     *
      * @example
+     * // Using string values
      * request.withPriority("high")
+     *
+     * @example
+     * // Using enum values
      * request.withPriority(RequestPriority.HIGH)
+     *
+     * @example
+     * // Using fluent API
      * request.withPriority.HIGH()
+     *
+     * @example
+     * // Low priority for non-critical requests
+     * request.withPriority.LOW()
      */
     get withPriority(): ((priority: RequestPriority | string) => BaseRequest) & {
         HIGH: () => BaseRequest;
@@ -160,19 +302,59 @@ export declare abstract class 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
+     * Sets the integrity hash for Subresource Integrity (SRI) verification.
+     * This allows the browser to verify that the fetched resource hasn't been tampered with
+     * by comparing its hash against the provided value. If the hashes don't match, the request fails.
+     *
+     * @param integrity - The integrity hash string in the format `"algorithm-hash"`:
+     *   - Example: `"sha256-abcdef1234567890..."` (SHA-256 hash)
+     *   - Example: `"sha384-abcdef1234567890..."` (SHA-384 hash)
+     *   - Example: `"sha512-abcdef1234567890..."` (SHA-512 hash)
+     *   - Multiple hashes can be separated by spaces: `"sha256-... sha384-..."`
+     *
+     * @returns The request instance for chaining
+     *
      * @example
      * request.withIntegrity("sha256-abcdef1234567890...")
+     *
+     * @example
+     * // Multiple algorithms for better compatibility
+     * request.withIntegrity("sha256-... sha384-...")
      */
     withIntegrity(integrity: string): this;
     /**
-     * Sets cache mode - supports both direct call and fluent API
+     * Sets the cache mode for the request, controlling how the browser's HTTP cache
+     * is used for this request.
+     *
+     * @param cache - The cache mode:
+     *   - `"default"` or `CacheMode.DEFAULT`: Use the browser's default cache behavior. The browser will check the cache and use it if valid, otherwise fetch from network.
+     *   - `"no-store"` or `CacheMode.NO_STORE`: Never use the cache and don't store the response in cache. Always fetch from network.
+     *   - `"reload"` or `CacheMode.RELOAD`: Bypass the cache but store the response. Always fetch from network, ignoring cached responses.
+     *   - `"no-cache"` or `CacheMode.NO_CACHE`: Check the cache but revalidate with the server. Use cached response only if server confirms it's still valid.
+     *   - `"force-cache"` or `CacheMode.FORCE_CACHE`: Use the cache if available, even if stale. Only fetch from network if not in cache.
+     *   - `"only-if-cached"` or `CacheMode.ONLY_IF_CACHED`: Only use the cache. If not in cache, return an error. Never fetch from network.
+     *
+     * @returns The request instance for chaining
+     *
      * @example
+     * // Using string values
      * request.withCache("no-cache")
+     *
+     * @example
+     * // Using enum values
      * request.withCache(CacheMode.NO_CACHE)
+     *
+     * @example
+     * // Using fluent API
      * request.withCache.NO_CACHE()
+     *
+     * @example
+     * // Always fetch fresh data
+     * request.withCache.RELOAD()
+     *
+     * @example
+     * // Use cache only, fail if not cached
+     * request.withCache.ONLY_IF_CACHED()
      */
     get withCache(): ((cache: string) => BaseRequest) & {
         DEFAULT: () => BaseRequest;
@@ -196,11 +378,32 @@ export declare abstract class BaseRequest {
      */
     withQueryParam(key: string, value: string | string[] | number | boolean | null | undefined): this;
     /**
-     * Sets request mode - supports both direct call and fluent API
+     * Sets the request mode, which determines the CORS (Cross-Origin Resource Sharing) behavior
+     * for the request. This controls how the browser handles cross-origin requests.
+     *
+     * @param mode - The request mode:
+     *   - `"cors"` or `RequestMode.CORS`: Enable CORS. The browser will send CORS headers and enforce CORS rules. This is the default for most cross-origin requests.
+     *   - `"no-cors"` or `RequestMode.NO_CORS`: Disable CORS. The request is sent as a "simple" request without CORS headers. The response will be opaque (you can't read it).
+     *   - `"same-origin"` or `RequestMode.SAME_ORIGIN`: Only allow same-origin requests. Cross-origin requests will fail.
+     *   - `"navigate"` or `RequestMode.NAVIGATE`: Used for navigation requests (typically only used by the browser itself).
+     *
+     * @returns The request instance for chaining
+     *
      * @example
+     * // Using string values
      * request.withMode("cors")
+     *
+     * @example
+     * // Using enum values
      * request.withMode(RequestMode.CORS)
+     *
+     * @example
+     * // Using fluent API
      * request.withMode.CORS()
+     *
+     * @example
+     * // Restrict to same-origin only
+     * request.withMode.SAME_ORIGIN()
      */
     get withMode(): ((mode: RequestMode | string) => BaseRequest) & {
         CORS: () => BaseRequest;