@indra211/httpease 1.0.0

package/src/HttpEase.js

@@ -0,0 +1,372 @@
+const InterceptorManager = require('./interceptors/InterceptorManager');
+const HttpError = require('./errors/HttpError');
+const {
+    mergeConfig,
+    buildURL,
+    sleep,
+    calculateBackoff,
+    isObject
+} = require('./utils/helpers');
+const { transformRequest, transformResponse } = require('./utils/transformers');
+const { wrapBodyWithProgress, readBodyWithProgress } = require('./utils/progress');
+
+/**
+ * HttpEase - A powerful HTTP client built on fetch
+ * Supports TypeScript, interceptors, retry, timeout and progress tracking.
+ */
+class HttpEase {
+    constructor(config = {}) {
+        // Default configuration
+        this.defaults = {
+            baseURL: '',
+            timeout: 30000,
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            retries: 0,
+            retryDelay: 1000,
+            retryCondition: this.defaultRetryCondition,
+            transformRequest: [...transformRequest],
+            transformResponse: [...transformResponse],
+            validateStatus: (status) => status >= 200 && status < 300,
+            maxRedirects: 5,
+            withCredentials: false,
+            ...config
+        };
+
+        // Initialize interceptors
+        this.interceptors = {
+            request: new InterceptorManager(),
+            response: new InterceptorManager()
+        };
+    }
+
+    /**
+     * Default retry condition
+     */
+    defaultRetryCondition(error, attempt) {
+        // Don't retry if we have a response (server responded)
+        if (error.response) {
+            const status = error.response.status;
+            // Retry on 5xx errors and 429 (rate limit)
+            return status >= 500 || status === 429 || status === 408;
+        }
+        // Retry on network errors (no response)
+        return true;
+    }
+
+    /**
+     * Apply request transformers
+     */
+    transformRequestData(data, headers) {
+        let result = data;
+
+        for (const transformer of this.defaults.transformRequest) {
+            result = transformer(result, headers);
+        }
+
+        return result;
+    }
+
+    /**
+     * Apply response transformers to already-consumed body text.
+     * Used by the download-progress path, which has already read and
+     * collected all bytes from the response stream.
+     *
+     * The built-in default transformer at index 0 expects a raw `Response`
+     * object, so we skip it here and do our own JSON parsing inline.
+     * Any user-added transformers (added after the default) are run normally
+     * because they receive already-parsed data in both code paths.
+     *
+     * @param {string} rawText - Raw body text already read from the stream
+     * @param {string | null} contentType - Content-Type header value
+     */
+    async transformResponseText(rawText, contentType) {
+        // Inline JSON parsing (matches what the default transformer does)
+        let parsed = rawText;
+        if (contentType && contentType.includes('application/json') && typeof rawText === 'string') {
+            try {
+                parsed = JSON.parse(rawText);
+            } catch (_) {
+                parsed = rawText;
+            }
+        }
+
+        // Run user-added transformers only (skip index 0 — the built-in default
+        // which expects a Response object, not pre-parsed data).
+        let result = parsed;
+        const userTransformers = this.defaults.transformResponse.slice(1);
+        for (const transformer of userTransformers) {
+            result = await transformer(result);
+        }
+
+        return result;
+    }
+
+    /**
+     * Apply response transformers (original path — via Response clone)
+     */
+    async transformResponseData(response) {
+        let result = response;
+
+        for (const transformer of this.defaults.transformResponse) {
+            result = await transformer(result);
+        }
+
+        return result;
+    }
+
+    /**
+     * Core request method with retry logic and optional progress tracking.
+     */
+    async request(config = {}) {
+        // Merge configurations
+        const finalConfig = mergeConfig(this.defaults, config);
+
+        // Build full URL
+        const url = buildURL(
+            finalConfig.baseURL + finalConfig.url,
+            finalConfig.params
+        );
+
+        const maxRetries = finalConfig.retries;
+        let lastError;
+
+        // Retry loop
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                // Apply request interceptors
+                let requestConfig = { ...finalConfig, url };
+                requestConfig = await this.interceptors.request.forEach(requestConfig);
+
+                // Transform request data
+                const headers = { ...requestConfig.headers };
+                let body = requestConfig.data
+                    ? this.transformRequestData(requestConfig.data, headers)
+                    : undefined;
+
+                // ── Upload Progress ──────────────────────────────────────────
+                let duplex;
+                if (body !== undefined && requestConfig.onUploadProgress) {
+                    const wrapped = wrapBodyWithProgress(body, requestConfig.onUploadProgress);
+                    body = wrapped.body;
+                    duplex = wrapped.duplex;
+                }
+
+                // Setup abort controller for timeout
+                const controller = new AbortController();
+                const timeoutId = setTimeout(
+                    () => controller.abort(),
+                    requestConfig.timeout
+                );
+
+                // Build fetch options
+                let fetchOptions = {
+                    method: requestConfig.method?.toUpperCase() || 'GET',
+                    headers,
+                    body,
+                    signal: controller.signal,
+                    credentials: requestConfig.withCredentials ? 'include' : 'same-origin'
+                };
+
+                // Required by the Fetch spec when sending a ReadableStream body
+                if (duplex) {
+                    fetchOptions.duplex = duplex;
+                }
+
+                // Make the fetch request
+                const startTime = Date.now();
+                const response = await fetch(requestConfig.url, fetchOptions);
+                clearTimeout(timeoutId);
+
+                // ── Download Progress ────────────────────────────────────────
+                let responseData;
+                if (requestConfig.onDownloadProgress) {
+                    // Stream the body through progress tracking, then parse
+                    const rawText = await readBodyWithProgress(
+                        response,
+                        requestConfig.onDownloadProgress
+                    );
+                    responseData = await this.transformResponseText(
+                        rawText,
+                        response.headers.get('content-type')
+                    );
+                } else {
+                    // Standard path — clone & transform via default transformers
+                    responseData = await this.transformResponseData(response.clone());
+                }
+
+                // Build response object
+                let responseObj = {
+                    data: responseData,
+                    status: response.status,
+                    statusText: response.statusText,
+                    headers: this.parseHeaders(response.headers),
+                    config: requestConfig,
+                    request: {
+                        url: requestConfig.url,
+                        method: requestConfig.method
+                    },
+                    duration: Date.now() - startTime
+                };
+
+                // Check if status is valid
+                const isValid = requestConfig.validateStatus(response.status);
+
+                if (!isValid) {
+                    const error = new HttpError(
+                        `Request failed with status code ${response.status}`,
+                        requestConfig,
+                        null,
+                        fetchOptions,
+                        responseObj
+                    );
+                    throw error;
+                }
+
+                // Apply response interceptors
+                responseObj = await this.interceptors.response.forEach(responseObj);
+
+                return responseObj;
+
+            } catch (error) {
+                lastError = error;
+
+                // Handle abort/timeout
+                if (error.name === 'AbortError') {
+                    const timeoutError = new HttpError(
+                        `Request timeout after ${finalConfig.timeout}ms`,
+                        finalConfig,
+                        'ETIMEDOUT',
+                        null,
+                        null
+                    );
+                    lastError = timeoutError;
+                }
+
+                // Check if we should retry
+                const shouldRetry = attempt < maxRetries &&
+                    finalConfig.retryCondition(lastError, attempt + 1);
+
+                if (shouldRetry) {
+                    const delay = typeof finalConfig.retryDelay === 'function'
+                        ? finalConfig.retryDelay(attempt + 1)
+                        : calculateBackoff(attempt + 1, finalConfig.retryDelay);
+
+                    if (finalConfig.onRetry) {
+                        finalConfig.onRetry(attempt + 1, delay, lastError);
+                    }
+
+                    await sleep(delay);
+                    continue; // Try again
+                }
+
+                // No more retries
+                throw lastError;
+            }
+        }
+
+        throw lastError;
+    }
+
+    /**
+     * Parse response headers into a plain object
+     */
+    parseHeaders(headers) {
+        const parsed = {};
+        headers.forEach((value, key) => {
+            parsed[key] = value;
+        });
+        return parsed;
+    }
+
+    /**
+     * GET request
+     */
+    get(url, config = {}) {
+        return this.request({
+            ...config,
+            method: 'GET',
+            url
+        });
+    }
+
+    /**
+     * DELETE request
+     */
+    delete(url, config = {}) {
+        return this.request({
+            ...config,
+            method: 'DELETE',
+            url
+        });
+    }
+
+    /**
+     * HEAD request
+     */
+    head(url, config = {}) {
+        return this.request({
+            ...config,
+            method: 'HEAD',
+            url
+        });
+    }
+
+    /**
+     * OPTIONS request
+     */
+    options(url, config = {}) {
+        return this.request({
+            ...config,
+            method: 'OPTIONS',
+            url
+        });
+    }
+
+    /**
+     * POST request
+     */
+    post(url, data, config = {}) {
+        return this.request({
+            ...config,
+            method: 'POST',
+            url,
+            data
+        });
+    }
+
+    /**
+     * PUT request
+     */
+    put(url, data, config = {}) {
+        return this.request({
+            ...config,
+            method: 'PUT',
+            url,
+            data
+        });
+    }
+
+    /**
+     * PATCH request
+     */
+    patch(url, data, config = {}) {
+        return this.request({
+            ...config,
+            method: 'PATCH',
+            url,
+            data
+        });
+    }
+
+    /**
+     * Get URI for request (without making it)
+     */
+    getUri(config = {}) {
+        const finalConfig = mergeConfig(this.defaults, config);
+        return buildURL(finalConfig.baseURL + finalConfig.url, finalConfig.params);
+    }
+}
+
+module.exports = HttpEase;

package/src/errors/HttpError.js

@@ -0,0 +1,27 @@
+/**
+ * Custom HTTP Error class with detailed information
+ */
+class HttpError extends Error {
+    constructor(message, config, code, request, response) {
+        super(message);
+        this.name = 'HttpError';
+        this.config = config;
+        this.code = code;
+        this.request = request;
+        this.response = response;
+        this.isHttpError = true;
+    }
+
+    toJSON() {
+        return {
+            message: this.message,
+            name: this.name,
+            code: this.code,
+            status: this.response?.status,
+            statusText: this.response?.statusText,
+            config: this.config
+        };
+    }
+}
+
+module.exports = HttpError;

package/src/index.js

@@ -0,0 +1,19 @@
+const HttpEase = require('./HttpEase');
+
+/**
+ * Create a new instance of HttpEase
+ */
+function create(config) {
+    return new HttpEase(config);
+}
+
+// Create default instance
+const httpEase = new HttpEase();
+
+// Export
+module.exports = httpEase;
+module.exports.HttpEase = HttpEase;
+module.exports.create = create;
+
+// Expose error class
+module.exports.HttpError = require('./errors/HttpError');

package/src/interceptors/InterceptorManager.js

@@ -0,0 +1,67 @@
+/**
+ * Interceptor Manager - handles request and response interceptors
+ */
+class InterceptorManager {
+    constructor() {
+        this.handlers = [];
+    }
+
+    /**
+     * Add a new interceptor
+     * @param {Function} fulfilled - Success handler
+     * @param {Function} rejected - Error handler
+     * @returns {Number} - ID for removing the interceptor
+     */
+    use(fulfilled, rejected) {
+        this.handlers.push({
+            fulfilled,
+            rejected
+        });
+        return this.handlers.length - 1;
+    }
+
+    /**
+     * Remove an interceptor by ID
+     * @param {Number} id - Interceptor ID
+     */
+    eject(id) {
+        if (this.handlers[id]) {
+            this.handlers[id] = null;
+        }
+    }
+
+    /**
+     * Clear all interceptors
+     */
+    clear() {
+        this.handlers = [];
+    }
+
+    /**
+     * Execute all interceptors
+     * @param {*} data - Data to pass through interceptors
+     */
+    async forEach(data) {
+        let result = data;
+
+        for (const handler of this.handlers) {
+            if (handler === null) continue;
+
+            try {
+                if (handler.fulfilled) {
+                    result = await handler.fulfilled(result);
+                }
+            } catch (error) {
+                if (handler.rejected) {
+                    result = await handler.rejected(error);
+                } else {
+                    throw error;
+                }
+            }
+        }
+
+        return result;
+    }
+}
+
+module.exports = InterceptorManager;

package/src/types/index.d.ts

@@ -0,0 +1,221 @@
+// ============================================================
+// HttpEase — TypeScript Type Definitions
+// ============================================================
+
+export interface ProgressEvent {
+  /** Bytes transferred so far */
+  loaded: number;
+  /** Total bytes (0 if unknown, e.g. no Content-Length header) */
+  total: number;
+  /** Progress percentage 0–100 (0 if total is unknown) */
+  percentage: number;
+}
+
+export type TransformRequestFn = (data: unknown, headers: Record<string, string>) => unknown;
+export type TransformResponseFn = (data: unknown) => unknown | Promise<unknown>;
+
+export interface HttpEaseConfig {
+  /** Base URL prepended to every request URL */
+  baseURL?: string;
+
+  /** Request URL (relative or absolute) */
+  url?: string;
+
+  /** HTTP method */
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | string;
+
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number;
+
+  /** Custom request headers */
+  headers?: Record<string, string>;
+
+  /** Query parameters appended to the URL */
+  params?: Record<string, string | number | boolean | string[] | number[] | null | undefined>;
+
+  /** Request body data */
+  data?: unknown;
+
+  /** Number of retry attempts on failure (default: 0) */
+  retries?: number;
+
+  /**
+   * Delay between retries in ms, or a function returning the delay.
+   * @example 1000
+   * @example (attempt) => Math.pow(2, attempt - 1) * 1000
+   */
+  retryDelay?: number | ((attempt: number) => number);
+
+  /**
+   * Custom condition to decide whether to retry.
+   * Return `true` to retry, `false` to stop.
+   */
+  retryCondition?: (error: HttpEaseError, attempt: number) => boolean;
+
+  /** Callback fired before each retry */
+  onRetry?: (attempt: number, delay: number, error: HttpEaseError) => void;
+
+  /**
+   * Validate whether a given HTTP status code should resolve or reject.
+   * Default: `status >= 200 && status < 300`
+   */
+  validateStatus?: (status: number) => boolean;
+
+  /** Send cookies with cross-origin requests (default: false) */
+  withCredentials?: boolean;
+
+  /** Transform request data before sending */
+  transformRequest?: TransformRequestFn[];
+
+  /** Transform response data after receiving */
+  transformResponse?: TransformResponseFn[];
+
+  /**
+   * Callback fired during upload progress.
+   * Works with string/Buffer/Uint8Array bodies in Node.js 18+ and modern browsers.
+   */
+  onUploadProgress?: (event: ProgressEvent) => void;
+
+  /**
+   * Callback fired during download progress.
+   * Requires the server to send a `content-length` header for percentage to work.
+   */
+  onDownloadProgress?: (event: ProgressEvent) => void;
+}
+
+export interface HttpEaseResponse<T = unknown> {
+  /** Parsed response data */
+  data: T;
+  /** HTTP status code */
+  status: number;
+  /** HTTP status text */
+  statusText: string;
+  /** Response headers as a plain object */
+  headers: Record<string, string>;
+  /** The config used for this request */
+  config: HttpEaseConfig;
+  /** Request info (url, method) */
+  request: { url: string; method: string };
+  /** Round-trip duration in milliseconds */
+  duration: number;
+}
+
+export declare class HttpEaseError extends Error {
+  name: 'HttpError';
+  /** Error code, e.g. `'ETIMEDOUT'` */
+  code: string | null;
+  /** Config used for this request */
+  config: HttpEaseConfig;
+  /** The fetch options used */
+  request: RequestInit | null;
+  /** The parsed response object (if server responded) */
+  response: HttpEaseResponse | null;
+  /** Always true — use to narrow error types */
+  isHttpError: true;
+
+  toJSON(): {
+    message: string;
+    name: string;
+    code: string | null;
+    status: number | undefined;
+    statusText: string | undefined;
+    config: HttpEaseConfig;
+  };
+}
+
+export interface InterceptorManager<T> {
+  /**
+   * Register an interceptor.
+   * @returns Interceptor ID (use with `eject`)
+   */
+  use(
+    onFulfilled?: (value: T) => T | Promise<T>,
+    onRejected?: (error: HttpEaseError) => T | Promise<T>
+  ): number;
+
+  /** Remove an interceptor by ID */
+  eject(id: number): void;
+
+  /** Remove all interceptors */
+  clear(): void;
+}
+
+export interface HttpEaseInstance {
+  /** Default configuration for this instance */
+  defaults: HttpEaseConfig;
+
+  /** Request and response interceptors */
+  interceptors: {
+    request: InterceptorManager<HttpEaseConfig>;
+    response: InterceptorManager<HttpEaseResponse>;
+  };
+
+  /** Core request method */
+  request<T = unknown>(config: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+
+  /** GET request */
+  get<T = unknown>(url: string, config?: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+
+  /** DELETE request */
+  delete<T = unknown>(url: string, config?: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+
+  /** HEAD request */
+  head<T = unknown>(url: string, config?: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+
+  /** OPTIONS request */
+  options<T = unknown>(url: string, config?: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+
+  /** POST request */
+  post<T = unknown>(url: string, data?: unknown, config?: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+
+  /** PUT request */
+  put<T = unknown>(url: string, data?: unknown, config?: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+
+  /** PATCH request */
+  patch<T = unknown>(url: string, data?: unknown, config?: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+
+  /** Resolve the full URI for a config without making a request */
+  getUri(config?: HttpEaseConfig): string;
+}
+
+/**
+ * Create a new HttpEase instance with custom defaults.
+ *
+ * @example
+ * ```ts
+ * import { create } from 'httpease';
+ *
+ * const api = create({
+ *   baseURL: 'https://api.example.com',
+ *   timeout: 10000,
+ *   headers: { Authorization: 'Bearer TOKEN' },
+ * });
+ *
+ * const res = await api.get<User[]>('/users');
+ * console.log(res.data);
+ * ```
+ */
+export declare function create(config?: HttpEaseConfig): HttpEaseInstance;
+
+/** The `HttpEase` class for extending */
+export declare class HttpEase implements HttpEaseInstance {
+  constructor(config?: HttpEaseConfig);
+  defaults: HttpEaseConfig;
+  interceptors: {
+    request: InterceptorManager<HttpEaseConfig>;
+    response: InterceptorManager<HttpEaseResponse>;
+  };
+  request<T = unknown>(config: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+  get<T = unknown>(url: string, config?: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+  delete<T = unknown>(url: string, config?: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+  head<T = unknown>(url: string, config?: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+  options<T = unknown>(url: string, config?: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+  post<T = unknown>(url: string, data?: unknown, config?: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+  put<T = unknown>(url: string, data?: unknown, config?: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+  patch<T = unknown>(url: string, data?: unknown, config?: HttpEaseConfig): Promise<HttpEaseResponse<T>>;
+  getUri(config?: HttpEaseConfig): string;
+}
+
+/** The default HttpEase instance */
+declare const httpEase: HttpEaseInstance;
+export default httpEase;