create-request 1.3.0 → 1.4.0

package/dist/library/index.cjs

@@ -96,6 +96,12 @@ var CacheMode;
 })(CacheMode || (CacheMode = {}));
 
 class RequestError extends Error {
+    status;
+    response;
+    url;
+    method;
+    isTimeout;
+    isAborted;
     constructor(message, url, method, options = {}) {
         super(message);
         this.name = "RequestError";
@@ -194,6 +200,11 @@ class RequestError extends Error {
  * Wrapper for HTTP responses with methods to transform the response data
  */
 class ResponseWrapper {
+    response;
+    url;
+    method;
+    // GraphQL-specific options
+    graphQLOptions;
     constructor(response, url, method, graphQLOptions) {
         this.response = response;
         this.url = url;
@@ -226,8 +237,7 @@ class ResponseWrapper {
      * @throws RequestError if GraphQL response contains errors and throwOnError is enabled
      */
     checkGraphQLErrors(data) {
-        var _a;
-        if (!((_a = this.graphQLOptions) === null || _a === void 0 ? void 0 : _a.throwOnError) || typeof data !== "object" || data === null)
+        if (!this.graphQLOptions?.throwOnError || typeof data !== "object" || data === null)
             return;
         const responseData = data;
         if (!Array.isArray(responseData.errors) || responseData.errors.length === 0)
@@ -488,7 +498,7 @@ class CsrfUtils {
             return null;
         }
         const meta = document.querySelector(`meta[name="${metaName}"]`);
-        return (meta === null || meta === void 0 ? void 0 : meta.getAttribute("content")) || null;
+        return meta?.getAttribute("content") || null;
     }
     /**
      * Extracts CSRF token from a cookie
@@ -545,20 +555,20 @@ class CsrfUtils {
  * Global configuration for create-request
  */
 class Config {
-    constructor() {
-        // CSRF configuration
-        this.csrfHeaderName = "X-CSRF-Token";
-        this.xsrfCookieName = "XSRF-TOKEN";
-        this.xsrfHeaderName = "X-XSRF-TOKEN";
-        this.csrfToken = null;
-        this.enableAutoXsrf = true;
-        this.enableAntiCsrf = true; // X-Requested-With header
-        // Interceptor configuration
-        this.requestInterceptors = [];
-        this.responseInterceptors = [];
-        this.errorInterceptors = [];
-        this.nextInterceptorId = 1;
-    }
+    static instance;
+    // CSRF configuration
+    csrfHeaderName = "X-CSRF-Token";
+    xsrfCookieName = "XSRF-TOKEN";
+    xsrfHeaderName = "X-XSRF-TOKEN";
+    csrfToken = null;
+    enableAutoXsrf = true;
+    enableAntiCsrf = true; // X-Requested-With header
+    // Interceptor configuration
+    requestInterceptors = [];
+    responseInterceptors = [];
+    errorInterceptors = [];
+    nextInterceptorId = 1;
+    constructor() { }
     /**
      * Get the singleton instance of the Config class
      *
@@ -841,16 +851,18 @@ class Config {
  * Provides the core request building and execution capabilities.
  */
 class BaseRequest {
+    url;
+    requestOptions = {
+        headers: {},
+    };
+    abortController;
+    queryParams = new URLSearchParams();
+    autoApplyCsrfProtection = true;
+    // Per-request interceptors
+    requestInterceptors = [];
+    responseInterceptors = [];
+    errorInterceptors = [];
     constructor(url) {
-        this.requestOptions = {
-            headers: {},
-        };
-        this.queryParams = new URLSearchParams();
-        this.autoApplyCsrfProtection = true;
-        // Per-request interceptors
-        this.requestInterceptors = [];
-        this.responseInterceptors = [];
-        this.errorInterceptors = [];
         this.url = url;
     }
     /**
@@ -881,7 +893,7 @@ class BaseRequest {
         return Object.assign(callable, fluent);
     }
     validateUrl(url) {
-        if (!(url === null || url === void 0 ? void 0 : url.trim()))
+        if (!url?.trim())
             throw new RequestError("URL cannot be empty", url, this.method);
         if (url.includes("\0") || url.includes("\r") || url.includes("\n")) {
             throw new RequestError("Invalid URL (control chars)", url, this.method);
@@ -891,7 +903,7 @@ class BaseRequest {
             try {
                 new URL(trimmed);
             }
-            catch (_a) {
+            catch {
                 throw new RequestError(`Invalid URL: ${trimmed}`, trimmed, this.method);
             }
         }
@@ -959,17 +971,60 @@ 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) {
-        if (!Number.isInteger(retries) || retries < 0)
-            throw new RequestError("Retry count must be a non-negative integer", this.url, this.method);
-        this.requestOptions.retries = retries;
+        if (typeof retries === "number") {
+            if (!Number.isInteger(retries) || retries < 0) {
+                throw new RequestError(`Invalid retries: ${retries}`, this.url, this.method);
+            }
+            this.requestOptions.retries = retries;
+        }
+        else {
+            // Validate RetryConfig
+            if (!Number.isInteger(retries.attempts) || retries.attempts < 0) {
+                throw new RequestError(`Invalid attempts: ${retries.attempts}`, this.url, this.method);
+            }
+            // Validate delay if provided
+            if (retries.delay !== undefined) {
+                if (typeof retries.delay === "number") {
+                    if (!Number.isFinite(retries.delay) || retries.delay < 0) {
+                        throw new RequestError(`Invalid delay: ${retries.delay}`, this.url, this.method);
+                    }
+                }
+                else if (typeof retries.delay !== "function") {
+                    throw new RequestError(`Invalid delay: ${typeof retries.delay}`, this.url, this.method);
+                }
+            }
+            this.requestOptions.retries = retries;
+        }
         return this;
     }
     /**
@@ -990,10 +1045,26 @@ class BaseRequest {
         return 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() {
@@ -1004,28 +1075,83 @@ class 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) {
         this.abortController = controller;
         return 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) {
         this.requestOptions.referrer = referrer;
         return 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() {
@@ -1041,11 +1167,30 @@ class 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() {
         return this.createFluentSetter("redirect", {
@@ -1055,20 +1200,50 @@ class 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) {
         this.requestOptions.keepalive = keepalive;
         return 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() {
         return this.createFluentSetter("priority", {
@@ -1078,22 +1253,62 @@ class 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) {
         this.requestOptions.integrity = integrity;
         return 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() {
         const cacheOptions = {
@@ -1142,11 +1357,32 @@ class BaseRequest {
         return 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() {
         return this.createFluentSetter("mode", {
@@ -1541,7 +1777,8 @@ class BaseRequest {
      * @throws RequestError if the request fails after all retries
      */
     async executeWithRetries(url, fetchOptions) {
-        const maxRetries = this.requestOptions.retries || 0;
+        const retriesConfig = this.requestOptions.retries;
+        const maxRetries = typeof retriesConfig === "number" ? retriesConfig : retriesConfig?.attempts || 0;
         const method = typeof fetchOptions.method === "string" ? fetchOptions.method : "GET";
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
@@ -1551,9 +1788,22 @@ class BaseRequest {
                 const requestError = error instanceof RequestError ? error : RequestError.networkError(url, method, error instanceof Error ? error : new Error(String(error)));
                 if (attempt >= maxRetries)
                     throw requestError;
+                // Call onRetry callback if provided
                 if (this.requestOptions.onRetry) {
                     await this.requestOptions.onRetry({ attempt: attempt + 1, error: requestError });
                 }
+                // Apply delay if configured
+                if (typeof retriesConfig === "object" && retriesConfig.delay !== undefined) {
+                    const delay = typeof retriesConfig.delay === "function" ? retriesConfig.delay({ attempt: attempt + 1, error: requestError }) : retriesConfig.delay;
+                    // Validate delay result
+                    if (typeof delay !== "number" || !Number.isFinite(delay) || delay < 0) {
+                        throw new RequestError(`Invalid retry delay: ${delay}`, url, method);
+                    }
+                    // Wait for the delay
+                    if (delay > 0) {
+                        await new Promise(resolve => setTimeout(resolve, delay));
+                    }
+                }
             }
         }
         // This should never happen but is needed for type safety
@@ -1670,7 +1920,7 @@ class BaseRequest {
         // No timeout - just use external controller
         if (!timeoutMs) {
             return {
-                signal: externalController === null || externalController === void 0 ? void 0 : externalController.signal,
+                signal: externalController?.signal,
                 cleanup: () => { },
                 wasTimeout: () => false,
             };
@@ -1853,9 +2103,11 @@ class BaseRequest {
  * Base class for requests that can have a body (POST, PUT, PATCH)
  */
 class BodyRequest extends BaseRequest {
+    body;
+    bodyType;
+    graphQLOptions = undefined;
     constructor(url) {
         super(url);
-        this.graphQLOptions = undefined;
     }
     /**
      * Sets the body of the request
@@ -1870,7 +2122,13 @@ class BodyRequest extends BaseRequest {
         }
         else if (body !== null &&
             typeof body === "object" &&
-            !(body instanceof FormData || body instanceof Blob || body instanceof ArrayBuffer || body instanceof URLSearchParams || body instanceof ReadableStream)) {
+            !(body instanceof FormData ||
+                body instanceof Blob ||
+                body instanceof File ||
+                body instanceof ArrayBuffer ||
+                ArrayBuffer.isView(body) || // Handles TypedArray and DataView
+                body instanceof URLSearchParams ||
+                body instanceof ReadableStream)) {
             this.bodyType = BodyType.JSON;
             this.setContentTypeIfNeeded("application/json");
             // Validate JSON is stringifiable early
@@ -2000,9 +2258,9 @@ class BodyRequest extends BaseRequest {
  * const data = await request.getData();
  */
 class GetRequest extends BaseRequest {
+    method = exports.HttpMethod.GET;
     constructor(url) {
         super(url);
-        this.method = exports.HttpMethod.GET;
     }
 }
 /**
@@ -2014,9 +2272,9 @@ class GetRequest extends BaseRequest {
  * const response = await request.getResponse();
  */
 class HeadRequest extends BaseRequest {
+    method = exports.HttpMethod.HEAD;
     constructor(url) {
         super(url);
-        this.method = exports.HttpMethod.HEAD;
     }
 }
 /**
@@ -2028,9 +2286,9 @@ class HeadRequest extends BaseRequest {
  * const response = await request.getResponse();
  */
 class OptionsRequest extends BaseRequest {
+    method = exports.HttpMethod.OPTIONS;
     constructor(url) {
         super(url);
-        this.method = exports.HttpMethod.OPTIONS;
     }
 }
 /**
@@ -2042,9 +2300,9 @@ class OptionsRequest extends BaseRequest {
  * await request.getData();
  */
 class DeleteRequest extends BaseRequest {
+    method = exports.HttpMethod.DELETE;
     constructor(url) {
         super(url);
-        this.method = exports.HttpMethod.DELETE;
     }
 }
 /**
@@ -2057,9 +2315,9 @@ class DeleteRequest extends BaseRequest {
  * const data = await request.getData();
  */
 class PostRequest extends BodyRequest {
+    method = exports.HttpMethod.POST;
     constructor(url) {
         super(url);
-        this.method = exports.HttpMethod.POST;
     }
 }
 /**
@@ -2072,9 +2330,9 @@ class PostRequest extends BodyRequest {
  * const data = await request.getData();
  */
 class PutRequest extends BodyRequest {
+    method = exports.HttpMethod.PUT;
     constructor(url) {
         super(url);
-        this.method = exports.HttpMethod.PUT;
     }
 }
 /**
@@ -2087,9 +2345,9 @@ class PutRequest extends BodyRequest {
  * const data = await request.getData();
  */
 class PatchRequest extends BodyRequest {
+    method = exports.HttpMethod.PATCH;
     constructor(url) {
         super(url);
-        this.method = exports.HttpMethod.PATCH;
     }
 }