create-request 0.0.1-beta.10

package/dist/library/BaseRequest.d.ts

@@ -0,0 +1,257 @@
+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";
+/**
+ * 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
+     * @param credentialsPolicy - Can be 'omit', 'same-origin', or 'include'
+     * @returns The instance for chaining
+     */
+    withCredentials(credentialsPolicy?: CredentialsPolicy): this;
+    /**
+     * Allows providing an external AbortController to cancel the request
+     * @param controller - The AbortController to use for this request
+     * @returns The instance for chaining
+     */
+    withAbortController(controller: AbortController): this;
+    /**
+     * Sets the referrer for the request
+     * @param referrer - The referrer URL or policy
+     * @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'
+     * @returns The instance for chaining
+     */
+    withRedirect(redirect: RedirectMode): this;
+    /**
+     * Sets the keepalive flag for the request
+     * @param keepalive - Whether to allow the request to outlive the page
+     * @returns The instance for chaining
+     */
+    withKeepAlive(keepalive: boolean): this;
+    /**
+     * Sets the priority of the request
+     * @param priority - Can be 'high', 'low', or 'auto'
+     * @returns The instance for chaining
+     */
+    withPriority(priority: RequestPriority): this;
+    /**
+     * Adds query parameters to the request URL
+     * @param params - An object containing the query parameters
+     * @returns The instance for chaining
+     */
+    withQueryParams(params: Record<string, string | string[] | number | boolean | null | undefined>): this;
+    /**
+     * Adds a single query parameter
+     * @param key - The parameter name
+     * @param value - The parameter value, can be a single value or array of values
+     * @returns The instance for chaining
+     */
+    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
+     */
+    withMode(mode: RequestMode): this;
+    /**
+     * Shorthand for setting the Content-Type header
+     * @param contentType - The content type
+     * @returns The instance for chaining
+     */
+    withContentType(contentType: string): this;
+    /**
+     * Shorthand for setting the Authorization header
+     * @param authValue - The authorization value
+     * @returns The instance for chaining
+     */
+    withAuthorization(authValue: string): this;
+    /**
+     * Shorthand for setting up Basic authentication
+     * @param username - The username
+     * @param password - The password
+     * @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 Object containing cookie name-value pairs or cookie options
+     * @returns The instance for chaining
+     */
+    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
+     * 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;
+    /**
+     * Formats the URL with any query parameters
+     * @param url The base URL
+     * @returns The URL with query parameters appended
+     */
+    private formatUrlWithQueryParams;
+    /**
+     * Executes a request with configured retry logic
+     * @param url The formatted URL to send the request to
+     * @param fetchOptions The fetch options to use
+     * @returns A wrapped response object
+     */
+    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

@@ -0,0 +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 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/RequestError.d.ts

@@ -0,0 +1,18 @@
+export declare class RequestError extends Error {
+    readonly status?: number;
+    readonly response?: Response;
+    readonly url: string;
+    readonly method: string;
+    readonly timeoutError?: boolean;
+    constructor(message: string, url: string, method: string, options?: {
+        status?: number;
+        response?: Response;
+        timeoutError?: boolean;
+    });
+    /**
+     * Static methods for creating specific types of RequestError
+     */
+    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;
+}

package/dist/library/ResponseWrapper.d.ts

@@ -0,0 +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 {
+    private readonly response;
+    private textCache;
+    private jsonCache;
+    private blobCache;
+    private arrayBufferCache;
+    private bodyUsed;
+    constructor(response: Response);
+    get status(): number;
+    get statusText(): string;
+    get headers(): Headers;
+    get ok(): boolean;
+    get raw(): Response;
+    /**
+     * 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);
+     */
+    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 Error if 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 Error if the response has already been consumed in an incompatible format
+     *
+     * @example
+     * const blob = await response.getBlob();
+     * const url = URL.createObjectURL(blob);
+     */
+    getBlob(): Promise<Blob>;
+    /**
+     * 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();
+     */
+    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 Error if 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>;
+    getData<T = unknown, R = T>(selector?: (data: T) => R): Promise<T | R>;
+}

package/dist/library/enums.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Enum for HTTP methods
+ */
+export declare enum HttpMethod {
+    GET = "GET",
+    PUT = "PUT",
+    POST = "POST",
+    HEAD = "HEAD",
+    PATCH = "PATCH",
+    DELETE = "DELETE",
+    OPTIONS = "OPTIONS"
+}
+/**
+ * Enum for request priorities
+ */
+export declare enum RequestPriority {
+    LOW = "low",
+    HIGH = "high",
+    AUTO = "auto"
+}
+/**
+ * Enum for credentials policies
+ */
+export declare enum CredentialsPolicy {
+    OMIT = "omit",
+    INCLUDE = "include",
+    SAME_ORIGIN = "same-origin"
+}
+/**
+ * Enum for request modes
+ */
+export declare enum RequestMode {
+    CORS = "cors",
+    NO_CORS = "no-cors",
+    SAME_ORIGIN = "same-origin",
+    NAVIGATE = "navigate"
+}
+/**
+ * Enum for redirect modes
+ */
+export declare enum RedirectMode {
+    ERROR = "error",
+    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
+ */
+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

@@ -0,0 +1,37 @@
+import { get, put, head, post, patch, del, options } from "./requestFactories";
+import { Config } from "./utils/Config";
+export { HttpMethod, RequestPriority, CredentialsPolicy, RequestMode, RedirectMode, CacheMode, SameSitePolicy, ReferrerPolicy } from "./enums";
+export type { RetryCallback, RequestOptions, CookieOptions, CookiesRecord } from "./types";
+export { RequestError } from "./RequestError";
+export { ResponseWrapper } from "./ResponseWrapper";
+export { CookieUtils } from "./utils/CookieUtils";
+export { GetRequest, PostRequest, PutRequest, DeleteRequest, PatchRequest, HeadRequest, OptionsRequest } from "./requestMethods";
+export { createMemoryStorage, createLocalStorageStorage, createSessionStorageStorage } from "./utils/CacheStorage";
+export { CacheManager } from "./utils/CacheManager";
+export type { CacheOptions } from "./types/cache";
+export type { StorageProvider } from "./utils/StorageProvider";
+/**
+ * Main API object for creating HTTP requests
+ * Provides factory methods for all HTTP methods and access to global configuration.
+ *
+ * @example
+ * // Making a GET request
+ * const users = await create.get()
+ *   .withQueryParams({ limit: 10 })
+ *   .sendTo('/api/users')
+ *   .getJson();
+ *
+ * // Configure global settings
+ * create.config.setCsrfToken('token123');
+ */
+declare const create: {
+    readonly get: typeof get;
+    readonly post: typeof post;
+    readonly put: typeof put;
+    readonly del: typeof del;
+    readonly patch: typeof patch;
+    readonly head: typeof head;
+    readonly options: typeof options;
+    readonly config: Config;
+};
+export default create;