create-request 0.0.1-beta.9 → 1.1.0

package/dist/library/BaseRequest.d.ts

@@ -1,28 +1,105 @@
-import { type HttpMethod, type RedirectMode, type RequestMode, type RequestPriority, CredentialsPolicy } from "./enums";
-import { type ResponsePromise } from "./ResponseWrapper";
-import type { RequestOptions, RetryCallback, CookiesRecord, CookieOptions } from "./types";
-import type { CacheOptions } from "./types/cache";
-import { CacheManager } from "./utils/CacheManager";
+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 { ResponseWrapper } from "./ResponseWrapper.js";
+/**
+ * Base class with common functionality for all request types
+ * Provides the core request building and execution capabilities.
+ */
 export declare abstract class BaseRequest {
     protected abstract method: HttpMethod;
+    protected url: string;
     protected requestOptions: RequestOptions;
     protected abortController?: AbortController;
     protected queryParams: URLSearchParams;
     protected autoApplyCsrfProtection: boolean;
-    protected cacheManager?: CacheManager;
-    protected cacheEnabled: boolean;
-    constructor();
+    private requestInterceptors;
+    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
+     */
+    private createFluentSetter;
+    private validateUrl;
+    /**
+     * Add multiple HTTP headers to the request
+     *
+     * @param headers - Key-value pairs of header names and values
+     * @returns The request instance for chaining
+     *
+     * @example
+     * request.withHeaders({
+     *   'Accept': 'application/json',
+     *   'X-Custom-Header': 'value'
+     * });
+     */
     withHeaders(headers: Record<string, string>): this;
+    /**
+     * Add a single HTTP header to the request
+     *
+     * @param key - The header name
+     * @param value - The header value
+     * @returns The request instance for chaining
+     *
+     * @example
+     * request.withHeader('Accept', 'application/json');
+     */
     withHeader(key: string, value: string): this;
+    /**
+     * Set a timeout for the request
+     * If the request takes longer than the specified timeout, it will be aborted.
+     *
+     * @param timeout - The timeout in milliseconds
+     * @returns The request instance for chaining
+     * @throws RequestError if timeout is not a positive number
+     *
+     * @example
+     * request.withTimeout(5000); // 5 seconds timeout
+     */
     withTimeout(timeout: number): this;
+    /**
+     * Configure automatic retry behavior for failed requests
+     *
+     * @param retries - Number of retry attempts before failing
+     * @returns The request instance for chaining
+     * @throws RequestError if retries is not a non-negative integer
+     *
+     * @example
+     * request.withRetries(3); // Retry up to 3 times
+     */
     withRetries(retries: number): this;
+    /**
+     * Set a callback to be invoked before each retry attempt
+     * Useful for implementing backoff strategies or logging retry attempts.
+     *
+     * @param callback - Function to call before retrying
+     * @returns The request instance for chaining
+     *
+     * @example
+     * request.onRetry(({ attempt, error }) => {
+     *   console.log(`Retry attempt ${attempt} after error: ${error.message}`);
+     *   return new Promise(resolve => setTimeout(resolve, attempt * 1000));
+     * });
+     */
     onRetry(callback: RetryCallback): this;
     /**
-     * Sets the credentials policy for the request
-     * @param credentialsPolicy - Can be 'omit', 'same-origin', or 'include'
-     * @returns The instance for chaining
+     * Sets credentials policy - supports both direct call and fluent API
+     * @example
+     * request.withCredentials("include")
+     * request.withCredentials(CredentialsPolicy.INCLUDE)
+     * request.withCredentials.INCLUDE()
      */
-    withCredentials(credentialsPolicy?: CredentialsPolicy): this;
+    get withCredentials(): ((credentialsPolicy: CredentialsPolicy | string) => BaseRequest) & {
+        INCLUDE: () => BaseRequest;
+        OMIT: () => BaseRequest;
+        SAME_ORIGIN: () => BaseRequest;
+    };
     /**
      * Allows providing an external AbortController to cancel the request
      * @param controller - The AbortController to use for this request
@@ -36,17 +113,34 @@ export declare abstract class BaseRequest {
      */
     withReferrer(referrer: string): this;
     /**
-     * Sets the referrer policy for the request
-     * @param policy - The referrer policy to use
-     * @returns The instance for chaining
+     * Sets referrer policy - supports both direct call and fluent API
+     * @example
+     * request.withReferrerPolicy("no-referrer")
+     * request.withReferrerPolicy(ReferrerPolicy.NO_REFERRER)
+     * request.withReferrerPolicy.NO_REFERRER()
      */
-    withReferrerPolicy(policy: ReferrerPolicy): this;
+    get withReferrerPolicy(): ((policy: ReferrerPolicy | string) => BaseRequest) & {
+        ORIGIN: () => BaseRequest;
+        UNSAFE_URL: () => BaseRequest;
+        SAME_ORIGIN: () => BaseRequest;
+        NO_REFERRER: () => BaseRequest;
+        STRICT_ORIGIN: () => BaseRequest;
+        ORIGIN_WHEN_CROSS_ORIGIN: () => BaseRequest;
+        NO_REFERRER_WHEN_DOWNGRADE: () => BaseRequest;
+        STRICT_ORIGIN_WHEN_CROSS_ORIGIN: () => BaseRequest;
+    };
     /**
-     * Sets the redirect policy for the request
-     * @param redirect - Can be 'follow', 'error', or 'manual'
-     * @returns The instance for chaining
+     * Sets redirect mode - supports both direct call and fluent API
+     * @example
+     * request.withRedirect("follow")
+     * request.withRedirect(RedirectMode.FOLLOW)
+     * request.withRedirect.FOLLOW()
      */
-    withRedirect(redirect: RedirectMode): this;
+    get withRedirect(): ((redirect: RedirectMode | string) => BaseRequest) & {
+        FOLLOW: () => BaseRequest;
+        ERROR: () => BaseRequest;
+        MANUAL: () => BaseRequest;
+    };
     /**
      * Sets the keepalive flag for the request
      * @param keepalive - Whether to allow the request to outlive the page
@@ -54,11 +148,17 @@ export declare abstract class BaseRequest {
      */
     withKeepAlive(keepalive: boolean): this;
     /**
-     * Sets the priority of the request
-     * @param priority - Can be 'high', 'low', or 'auto'
-     * @returns The instance for chaining
+     * Sets request priority - supports both direct call and fluent API
+     * @example
+     * request.withPriority("high")
+     * request.withPriority(RequestPriority.HIGH)
+     * request.withPriority.HIGH()
      */
-    withPriority(priority: RequestPriority): this;
+    get withPriority(): ((priority: RequestPriority | string) => BaseRequest) & {
+        HIGH: () => BaseRequest;
+        LOW: () => BaseRequest;
+        AUTO: () => BaseRequest;
+    };
     /**
      * Adds query parameters to the request URL
      * @param params - An object containing the query parameters
@@ -73,11 +173,18 @@ export declare abstract class BaseRequest {
      */
     withQueryParam(key: string, value: string | string[] | number | boolean | null | undefined): this;
     /**
-     * Sets the mode of the request
-     * @param mode - The mode for the request (cors, no-cors, same-origin, navigate)
-     * @returns The instance for chaining
+     * Sets request mode - supports both direct call and fluent API
+     * @example
+     * request.withMode("cors")
+     * request.withMode(RequestMode.CORS)
+     * request.withMode.CORS()
      */
-    withMode(mode: RequestMode): this;
+    get withMode(): ((mode: RequestMode | string) => BaseRequest) & {
+        CORS: () => BaseRequest;
+        NO_CORS: () => BaseRequest;
+        SAME_ORIGIN: () => BaseRequest;
+        NAVIGATE: () => BaseRequest;
+    };
     /**
      * Shorthand for setting the Content-Type header
      * @param contentType - The content type
@@ -108,9 +215,13 @@ export declare abstract class BaseRequest {
      * @returns The instance for chaining
      */
     withBearerToken(token: string): this;
+    /**
+     * Safely get headers as a Record<string, string>
+     * @returns The headers object
+     */
+    private getHeadersRecord;
     /**
      * Helper function to check for header presence in a case-insensitive way
-     * @param headers Headers object
      * @param headerName Header name to check
      * @returns Boolean indicating if the header exists (case-insensitive)
      */
@@ -147,16 +258,135 @@ export declare abstract class BaseRequest {
      */
     withAntiCsrfHeaders(): this;
     /**
-     * Enables caching for the request with the specified options
-     * @param options The cache configuration options
+     * Add a request interceptor for this specific request
+     * Request interceptors can modify the request configuration or return an early response
+     *
+     * @param interceptor - The request interceptor function
      * @returns The instance for chaining
+     *
+     * @example
+     * request.withRequestInterceptor((config) => {
+     *   config.headers['X-Custom'] = 'value';
+     *   return config;
+     * });
      */
-    withCache(options?: CacheOptions): this;
+    withRequestInterceptor(interceptor: RequestInterceptor): this;
     /**
-     * Send the request to the specified URL
-     * @param url The URL to send the request to
+     * Add a response interceptor for this specific request
+     * Response interceptors can transform the response
+     *
+     * @param interceptor - The response interceptor function
+     * @returns The instance for chaining
+     *
+     * @example
+     * request.withResponseInterceptor((response) => {
+     *   console.log('Status:', response.status);
+     *   return response;
+     * });
+     */
+    withResponseInterceptor(interceptor: ResponseInterceptor): this;
+    /**
+     * Add an error interceptor for this specific request
+     * Error interceptors can handle or transform errors
+     *
+     * @param interceptor - The error interceptor function
+     * @returns The instance for chaining
+     *
+     * @example
+     * request.withErrorInterceptor((error) => {
+     *   console.error('Request failed:', error);
+     *   throw error;
+     * });
      */
-    sendTo(url: string): ResponsePromise;
+    withErrorInterceptor(interceptor: ErrorInterceptor): this;
+    /**
+     * Execute the request and return the ResponseWrapper
+     * This is the base method for getting the full response.
+     *
+     * @returns A promise that resolves to the ResponseWrapper
+     *
+     * @example
+     * const response = await request.getResponse();
+     * console.log(response.status);
+     */
+    getResponse(): Promise<ResponseWrapper>;
+    /**
+     * 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>;
+    /**
+     * Execute the request and get the response as text
+     *
+     * @returns A promise that resolves to the response text
+     *
+     * @example
+     * const text = await request.getText();
+     */
+    getText(): Promise<string>;
+    /**
+     * Execute the request and get the response as a Blob
+     *
+     * @returns A promise that resolves to the response Blob
+     *
+     * @example
+     * const blob = await request.getBlob();
+     */
+    getBlob(): Promise<Blob>;
+    /**
+     * Execute the request and get the response body as a ReadableStream
+     *
+     * @returns A promise that resolves to the response body stream
+     *
+     * @example
+     * const stream = await request.getBody();
+     */
+    getBody(): Promise<ReadableStream<Uint8Array> | null>;
+    /**
+     * Execute the request and extract specific data using a selector function
+     * If no selector is provided, returns the full JSON response.
+     *
+     * @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
+     * const data = await request.getData();
+     *
+     * // 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>;
+    /**
+     * Apply CSRF protection headers based on configuration
+     */
+    private applyCsrfProtection;
     /**
      * Formats the URL with any query parameters
      * @param url The base URL
@@ -168,14 +398,44 @@ export declare abstract class BaseRequest {
      * @param url The formatted URL to send the request to
      * @param fetchOptions The fetch options to use
      * @returns A wrapped response object
+     * @throws RequestError if the request fails after all retries
      */
     private executeWithRetries;
-    private executeRequest;
     /**
-     * Executes a request using cache when possible
-     * @param url The formatted URL to send the request to
-     * @param fetchOptions The fetch options to use
-     * @param cacheKey The cache key for this request
+     * Run request interceptors in order: global interceptors first, then per-request
+     * @param configParam - The request configuration
+     * @returns Modified config or a Response to short-circuit
      */
-    private executeWithCache;
+    private runRequestInterceptors;
+    /**
+     * Run response interceptors in reverse order: per-request interceptors first, then global in reverse
+     * @param response - The response wrapper
+     * @returns Modified response wrapper
+     */
+    private runResponseInterceptors;
+    /**
+     * Run error interceptors in reverse order: per-request interceptors first, then global in reverse
+     * @param error - The error that occurred
+     * @returns Modified error or a ResponseWrapper to recover
+     */
+    private runErrorInterceptors;
+    /**
+     * Helper to create an abort signal with timeout support
+     * Handles various AbortSignal API levels gracefully
+     */
+    private createAbortSignal;
+    /**
+     * Manually combine two abort signals for older environments
+     * Returns the first signal and listens to the second
+     */
+    private combineSignalsManually;
+    /**
+     * Convert fetchOptions to RequestConfig with proper typing
+     */
+    private createRequestConfig;
+    /**
+     * Apply interceptor results back to fetchOptions
+     */
+    private applyRequestConfig;
+    private executeRequest;
 }

package/dist/library/BodyRequest.d.ts

@@ -1,20 +1,55 @@
-import { BaseRequest } from "./BaseRequest";
-import type { Body } from "./types";
+import { BaseRequest } from "./BaseRequest.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)
  */
 export declare abstract class BodyRequest extends BaseRequest {
     protected body?: Body;
     private bodyType?;
+    private graphQLOptions;
+    constructor(url: string);
     /**
      * Sets the body of the request
      * @param body - The request body
      */
     withBody(body: Body): this;
+    /**
+     * Sets a GraphQL query or mutation as the request body
+     * Automatically formats the body as JSON and sets Content-Type to application/json
+     *
+     * @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
+     * const request = new PostRequest('/graphql')
+     *   .withGraphQL('query { user(id: $id) { name email } }', { id: '123' });
+     *
+     * @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>, options?: GraphQLOptions): this;
+    /**
+     * Check if Content-Type header is already set (case-insensitive)
+     */
+    private hasContentType;
     private setContentTypeIfNeeded;
     /**
-     * Send the request to the specified URL
+     * 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
      */
-    sendTo(url: string): ReturnType<BaseRequest["sendTo"]>;
+    getResponse(): Promise<ResponseWrapper>;
 }

package/dist/library/RequestError.d.ts

@@ -3,11 +3,13 @@ export declare class RequestError extends Error {
     readonly response?: Response;
     readonly url: string;
     readonly method: string;
-    readonly timeoutError?: boolean;
+    readonly isTimeout?: boolean;
+    readonly isAborted?: boolean;
     constructor(message: string, url: string, method: string, options?: {
         status?: number;
         response?: Response;
-        timeoutError?: boolean;
+        isTimeout?: boolean;
+        isAborted?: boolean;
     });
     /**
      * Static methods for creating specific types of RequestError
@@ -15,4 +17,5 @@ export declare class RequestError extends Error {
     static timeout(url: string, method: string, timeoutMs: number): RequestError;
     static fromResponse(response: Response, url: string, method: string): RequestError;
     static networkError(url: string, method: string, originalError: Error): RequestError;
+    static abortError(url: string, method: string): RequestError;
 }

package/dist/library/ResponseWrapper.d.ts

@@ -1,33 +1,116 @@
+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.
  */
 export declare class ResponseWrapper {
     private readonly response;
+    readonly url?: string;
+    readonly method?: string;
     private textCache;
     private jsonCache;
     private blobCache;
-    private arrayBufferCache;
     private bodyUsed;
-    constructor(response: Response);
+    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 {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>;
+    /**
+     * Get the response body as text
+     * Caches the result for subsequent calls. Attempts to convert from JSON or Blob
+     * if the body has already been consumed in those formats.
+     *
+     * @returns The response text
+     * @throws {RequestError} When reading fails or the response has already been consumed in an incompatible format
+     *
+     * @example
+     * const text = await response.getText();
+     */
     getText(): Promise<string>;
+    /**
+     * Get the response body as a Blob
+     * Caches the result for subsequent calls. Attempts to convert from text
+     * if the body has already been consumed as text.
+     *
+     * @returns The response as a Blob
+     * @throws {RequestError} When reading fails or the response has already been consumed in an incompatible format
+     *
+     * @example
+     * const blob = await response.getBlob();
+     * const url = URL.createObjectURL(blob);
+     */
     getBlob(): Promise<Blob>;
-    getArrayBuffer(): Promise<ArrayBuffer>;
+    /**
+     * Get the raw response body as a ReadableStream
+     * This method consumes the body and should only be called once.
+     *
+     * @returns The response body as a ReadableStream or null
+     * @throws {RequestError} When the response body has already been consumed
+     *
+     * @example
+     * const stream = response.getBody();
+     * if (stream) {
+     *   const reader = stream.getReader();
+     *   // Process the stream
+     * }
+     */
     getBody(): ReadableStream<Uint8Array> | null;
-}
-/**
- * Type for Promise with response data transformation methods
- */
-export interface ResponsePromise<T = ResponseWrapper> extends Promise<T> {
-    getJson<R = unknown>(): Promise<R>;
-    getText(): Promise<string>;
-    getBlob(): Promise<Blob>;
-    getArrayBuffer(): Promise<ArrayBuffer>;
-    getBody(): Promise<ReadableStream<Uint8Array> | null>;
+    /**
+     * Extract specific data using a selector function
+     * If no selector is provided, returns the full JSON response.
+     *
+     * @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
+     * const data = await response.getData();
+     *
+     * // 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

@@ -43,17 +43,6 @@ export declare enum RedirectMode {
     FOLLOW = "follow",
     MANUAL = "manual"
 }
-/**
- * Enum for cache modes
- */
-export declare enum CacheMode {
-    DEFAULT = "default",
-    RELOAD = "reload",
-    NO_STORE = "no-store",
-    NO_CACHE = "no-cache",
-    FORCE_CACHE = "force-cache",
-    ONLY_IF_CACHED = "only-if-cached"
-}
 /**
  * Enum for cookie SameSite policies
  */