create-request 0.0.1-beta.2 → 0.0.1-beta.20

package/dist/library/BaseRequest.d.ts

@@ -1,15 +1,81 @@
 import { type HttpMethod, type RedirectMode, type RequestMode, type RequestPriority, CredentialsPolicy } from "./enums";
+import type { RequestOptions, RetryCallback, CookiesRecord, CookieOptions } from "./types";
 import { type ResponsePromise } from "./ResponseWrapper";
-import type { RequestOptions, RetryCallback } from "./types";
+import type { CacheOptions } from "./types/cache";
+import { CacheManager } from "./utils/CacheManager";
+/**
+ * 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 requestOptions: RequestOptions;
     protected abortController?: AbortController;
     protected queryParams: URLSearchParams;
+    protected autoApplyCsrfProtection: boolean;
+    protected cacheManager?: CacheManager;
+    protected cacheEnabled: boolean;
     constructor();
+    /**
+     * 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 Error 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 Error 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
@@ -29,6 +95,12 @@ export declare abstract class BaseRequest {
      * @returns The instance for chaining
      */
     withReferrer(referrer: string): this;
+    /**
+     * Sets the referrer policy for the request
+     * @param policy - The referrer policy to use
+     * @returns The instance for chaining
+     */
+    withReferrerPolicy(policy: ReferrerPolicy): this;
     /**
      * Sets the redirect policy for the request
      * @param redirect - Can be 'follow', 'error', or 'manual'
@@ -56,10 +128,10 @@ export declare abstract class BaseRequest {
     /**
      * Adds a single query parameter
      * @param key - The parameter name
-     * @param value - The parameter value
+     * @param value - The parameter value, can be a single value or array of values
      * @returns The instance for chaining
      */
-    withQueryParam(key: string, value: string | number | boolean | null | undefined): this;
+    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)
@@ -85,21 +157,80 @@ export declare abstract class BaseRequest {
      * @returns The instance for chaining
      */
     withBasicAuth(username: string, password: string): this;
+    /**
+     * Cross-environment base64 encoding
+     * Works in both browser and Node.js environments
+     */
+    private encodeBase64;
     /**
      * Sets the bearer token for authentication
      * @param token - The bearer token
      * @returns The instance for chaining
      */
     withBearerToken(token: string): this;
+    /**
+     * 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)
+     */
+    private hasHeader;
     /**
      * Sets cookies for the request
-     * @param cookies - An object containing cookie name-value pairs
+     * @param cookies Object containing cookie name-value pairs or cookie options
      * @returns The instance for chaining
      */
-    withCookies(cookies: Record<string, string>): this;
+    withCookies(cookies: CookiesRecord): this;
+    /**
+     * Set a single cookie
+     * @param name Cookie name
+     * @param value Cookie value or options object
+     * @returns The instance for chaining
+     */
+    withCookie(name: string, value: string | CookieOptions): this;
+    /**
+     * Sets a CSRF token in the request headers
+     * @param token The CSRF token
+     * @param headerName The name of the header to use (default: X-CSRF-Token)
+     * @returns The instance for chaining
+     */
+    withCsrfToken(token: string, headerName?: string): this;
+    /**
+     * Disables automatic anti-CSRF protection.
+     * By default, X-Requested-With: XMLHttpRequest header is sent with all requests.
+     * @returns The instance for chaining
+     */
+    withoutCsrfProtection(): this;
+    /**
+     * Sets common security headers to help prevent CSRF attacks
+     * @returns The instance for chaining
+     */
+    withAntiCsrfHeaders(): this;
+    /**
+     * Configure request caching behavior
+     * When enabled, responses will be cached and reused for subsequent identical requests.
+     *
+     * @param options - Cache configuration options
+     * @returns The request instance for chaining
+     *
+     * @example
+     * request.withCache({
+     *   ttl: 60000, // Cache for 1 minute
+     *   maxEntries: 100,
+     *   storage: localStorage
+     * });
+     */
+    withCache(options?: CacheOptions): this;
     /**
      * Send the request to the specified URL
-     * @param url The URL to send the request to
+     * This is the final method in the chain that executes the request.
+     *
+     * @param url - The URL to send the request to
+     * @returns A promise with additional methods for processing the response
+     *
+     * @example
+     * const response = await request.sendTo('/api/users');
+     * const data = await response.getJson();
      */
     sendTo(url: string): ResponsePromise;
     /**
@@ -113,7 +244,15 @@ 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
+     */
+    private executeWithCache;
 }

package/dist/library/BodyRequest.d.ts

@@ -1,8 +1,20 @@
 import { BaseRequest } from "./BaseRequest";
 import type { Body } from "./types";
+/**
+ * Base class for requests that can have a body (POST, PUT, PATCH)
+ */
 export declare abstract class BodyRequest extends BaseRequest {
+    protected body?: Body;
+    private bodyType?;
     /**
-     * Sets the request body with appropriate content type handling
+     * Sets the body of the request
+     * @param body - The request body
      */
     withBody(body: Body): this;
+    private setContentTypeIfNeeded;
+    /**
+     * Send the request to the specified URL
+     * Overrides the base implementation to add body handling
+     */
+    sendTo(url: string): ReturnType<BaseRequest["sendTo"]>;
 }

package/dist/library/ResponseWrapper.d.ts

@@ -1,54 +1,93 @@
 /**
  * Wrapper for HTTP responses with methods to transform the response data
+ * Provides caching and conversion between different response formats.
  */
 export declare class ResponseWrapper {
-    readonly ok: boolean;
-    private response;
+    private readonly response;
+    private textCache;
+    private jsonCache;
+    private blobCache;
+    private arrayBufferCache;
+    private bodyUsed;
     constructor(response: Response);
-    /**
-     * Get the raw Response object
-     */
-    get raw(): Response;
-    /**
-     * Get the HTTP status code
-     */
     get status(): number;
-    /**
-     * Get the HTTP status text
-     */
     get statusText(): string;
-    /**
-     * Get response headers
-     */
     get headers(): Headers;
+    get ok(): boolean;
+    get raw(): Response;
     /**
-     * Parse response as JSON
+     * Parse the response body as JSON
+     * Caches the result for subsequent calls.
+     *
+     * @returns The parsed JSON data
+     * @throws Error if the response has already been consumed in a different format
+     *
+     * @example
+     * const data = await response.getJson();
+     * console.log(data.items);
      */
-    json<T = unknown>(): Promise<T>;
+    getJson<T = unknown>(): Promise<T>;
     /**
-     * Get response as text
+     * 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 Error if the response has already been consumed in an incompatible format
+     *
+     * @example
+     * const text = await response.getText();
      */
-    text(): Promise<string>;
+    getText(): Promise<string>;
     /**
-     * Get response as Blob
+     * 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 Error if the response has already been consumed in an incompatible format
+     *
+     * @example
+     * const blob = await response.getBlob();
+     * const url = URL.createObjectURL(blob);
      */
-    blob(): Promise<Blob>;
+    getBlob(): Promise<Blob>;
     /**
-     * Get response as ArrayBuffer
+     * Get the response body as an ArrayBuffer
+     * Caches the result for subsequent calls. Attempts to convert from text or Blob
+     * if the body has already been consumed in those formats.
+     *
+     * @returns The response as an ArrayBuffer
+     * @throws Error if the response has already been consumed in an incompatible format
+     *
+     * @example
+     * const buffer = await response.getArrayBuffer();
      */
-    arrayBuffer(): Promise<ArrayBuffer>;
+    getArrayBuffer(): Promise<ArrayBuffer>;
     /**
-     * Get response as ReadableStream
+     * 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 Error if the response body has already been consumed
+     *
+     * @example
+     * const stream = response.getBody();
+     * if (stream) {
+     *   const reader = stream.getReader();
+     *   // Process the stream
+     * }
      */
-    body(): ReadableStream<Uint8Array> | null;
+    getBody(): ReadableStream<Uint8Array> | null;
 }
 /**
  * Type for Promise with response data transformation methods
  */
 export interface ResponsePromise<T = ResponseWrapper> extends Promise<T> {
-    json<R = unknown>(): Promise<R>;
-    text(): Promise<string>;
-    blob(): Promise<Blob>;
-    arrayBuffer(): Promise<ArrayBuffer>;
-    body(): Promise<ReadableStream<Uint8Array> | null>;
+    getJson<R = unknown>(): Promise<R>;
+    getText(): Promise<string>;
+    getBlob(): Promise<Blob>;
+    getArrayBuffer(): Promise<ArrayBuffer>;
+    getBody(): Promise<ReadableStream<Uint8Array> | null>;
+    getData<T = unknown, R = T>(selector?: (data: T) => R): Promise<T | R>;
 }

package/dist/library/enums.d.ts

@@ -3,28 +3,28 @@
  */
 export declare enum HttpMethod {
     GET = "GET",
-    POST = "POST",
     PUT = "PUT",
-    DELETE = "DELETE",
-    PATCH = "PATCH",
+    POST = "POST",
     HEAD = "HEAD",
+    PATCH = "PATCH",
+    DELETE = "DELETE",
     OPTIONS = "OPTIONS"
 }
 /**
  * Enum for request priorities
  */
 export declare enum RequestPriority {
-    HIGH = "high",
     LOW = "low",
+    HIGH = "high",
     AUTO = "auto"
 }
 /**
  * Enum for credentials policies
  */
 export declare enum CredentialsPolicy {
+    OMIT = "omit",
     INCLUDE = "include",
-    SAME_ORIGIN = "same-origin",
-    OMIT = "omit"
+    SAME_ORIGIN = "same-origin"
 }
 /**
  * Enum for request modes
@@ -39,8 +39,8 @@ export declare enum RequestMode {
  * Enum for redirect modes
  */
 export declare enum RedirectMode {
-    FOLLOW = "follow",
     ERROR = "error",
+    FOLLOW = "follow",
     MANUAL = "manual"
 }
 /**
@@ -48,9 +48,38 @@ export declare enum RedirectMode {
  */
 export declare enum CacheMode {
     DEFAULT = "default",
-    NO_STORE = "no-store",
     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
+ */
+export declare enum SameSitePolicy {
+    LAX = "Lax",
+    NONE = "None",
+    STRICT = "Strict"
+}
+/**
+ * Enum for body types
+ */
+export declare enum BodyType {
+    JSON = "json",
+    STRING = "string",
+    BINARY = "binary"
+}
+/**
+ * Referrer policies for fetch requests
+ */
+export declare enum ReferrerPolicy {
+    ORIGIN = "origin",
+    UNSAFE_URL = "unsafe-url",
+    SAME_ORIGIN = "same-origin",
+    NO_REFERRER = "no-referrer",
+    STRICT_ORIGIN = "strict-origin",
+    ORIGIN_WHEN_CROSS_ORIGIN = "origin-when-cross-origin",
+    NO_REFERRER_WHEN_DOWNGRADE = "no-referrer-when-downgrade",
+    STRICT_ORIGIN_WHEN_CROSS_ORIGIN = "strict-origin-when-cross-origin"
+}

package/dist/library/index.d.ts

@@ -1,9 +1,19 @@
 import { get, put, head, post, patch, del, options } from "./requestFactories";
-export { HttpMethod, RequestPriority, CredentialsPolicy, RequestMode, RedirectMode, CacheMode, } from "./enums";
-export type { RetryCallback, RequestOptions } from "./types";
-export { RequestError } from "./RequestError";
+import { Config } from "./utils/Config";
+export { HttpMethod, RequestPriority, CredentialsPolicy, RequestMode, RedirectMode, CacheMode, SameSitePolicy, ReferrerPolicy } from "./enums";
+export type { RetryCallback, RequestOptions, CookiesRecord, CookieOptions } from "./types";
+export type { StorageProvider } from "./utils/StorageProvider";
+export type { CacheOptions } from "./types/cache";
 export { ResponseWrapper } from "./ResponseWrapper";
-export { GetRequest, PostRequest, PutRequest, DeleteRequest, PatchRequest, HeadRequest, OptionsRequest, } from "./requestMethods";
+export { CookieUtils } from "./utils/CookieUtils";
+export { RequestError } from "./RequestError";
+export { GetRequest, PostRequest, PutRequest, DeleteRequest, PatchRequest, HeadRequest, OptionsRequest } from "./requestMethods";
+export { createMemoryStorage, createLocalStorageStorage, createSessionStorageStorage } from "./utils/CacheStorage";
+export { CacheManager } from "./utils/CacheManager";
+/**
+ * Main API object for creating HTTP requests
+ * Provides factory methods for all HTTP methods and access to global configuration.
+ */
 declare const create: {
     readonly get: typeof get;
     readonly post: typeof post;
@@ -12,5 +22,6 @@ declare const create: {
     readonly patch: typeof patch;
     readonly head: typeof head;
     readonly options: typeof options;
+    readonly config: Config;
 };
 export default create;