@hx-cd/fetch-client

A universal HTTP request library based on the Fetch API, with axios-like API design. Zero runtime dependencies.

Installation

pnpm add @hx-cd/fetch-client

Quick Start

import { FetchClient } from "@hx-cd/fetch-client";

const client = new FetchClient({
  baseURL: "https://api.example.com",
  timeout: 30000,
});

// GET request
const response = await client.get("/users", {
  params: { page: 1 },
});

// POST request
const result = await client.post("/users", { name: "John" });

// Interceptors
client.interceptors.request.use((config) => {
  config.headers["Authorization"] = "Bearer token";
  return config;
});

Features

• All HTTP methods (GET, POST, PUT, DELETE, HEAD, PATCH, OPTIONS)
• Request/Response interceptors
• Request cancellation (AbortController)
• Timeout control
• Upload/Download progress tracking
• CSRF token handling
• Retry with backoff strategies (linear/exponential)
• Response caching with TTL
• Fallback URLs for high availability
• Request deduplication for concurrent requests
• XHR fallback for upload progress in browsers
• TypeScript support
• Browser and Node.js support

API

FetchClient Config

| Option | Type | Default | Description | | ---------- | ---------------- | -------------------- | -------------------------------------- | | baseURL | string | '' | Base URL for requests | | timeout | number | 0 | Request timeout in ms (0 = no timeout) | | headers | object | {} | Default headers | | params | object | {} | Default query parameters | | retry | RetryConfig | { count: 0 } | Retry configuration | | cache | CacheConfig | { enabled: false } | Cache configuration | | fallback | FallbackConfig | { baseUrls: [] } | Fallback URLs | | csrf | CSRFConfig | { enabled: false } | CSRF configuration |

RetryConfig

| Option | Type | Default | Description | | ------------- | --------------------------- | ---------- | -------------------------- | | count | number | 0 | Number of retries | | delay | number | 1000 | Base delay in ms | | strategy | 'linear' \| 'exponential' | 'linear' | Backoff strategy | | onRetry | function | - | Callback on each retry | | shouldRetry | function | - | Custom condition for retry |

CacheConfig

| Option | Type | Default | Description | | --------- | -------------------- | -------- | --------------------------- | | enabled | boolean | false | Enable caching | | ttl | number | 300000 | Cache TTL in ms (5 minutes) | | key | string \| function | - | Custom cache key |

FallbackConfig

| Option | Type | Default | Description | | ---------------- | ---------- | ------- | ----------------------------- | | baseUrls | string[] | [] | Fallback base URLs | | shouldFallback | function | - | Custom condition for fallback |

CSRFConfig

| Option | Type | Default | Description | | ------------ | --------- | ---------------- | ----------- | | enabled | boolean | false | Enable CSRF | | cookieName | string | 'XSRF-TOKEN' | Cookie name | | headerName | string | 'X-XSRF-TOKEN' | Header name |

Request Config

| Option | Type | Default | Description | | -------------- | --------------------------------------------- | -------- | ---------------------------- | | params | object | {} | URL query parameters | | headers | object | {} | Request headers | | timeout | number | 0 | Request timeout | | signal | AbortSignal | - | Abort signal | | retry | object \| false | - | Override retry config | | cache | object \| false | - | Override cache config | | dedupe | boolean | false | Enable request deduplication | | responseType | 'json' \| 'text' \| 'blob' \| 'arrayBuffer' | 'json' | Response type |

Package Info

| Field | Value | | ------- | --------------------- | | Name | @hx-cd/fetch-client | | Version | 1.0.0 | | License | MIT | | Main | dist/index.cjs | | Module | dist/index.js | | Types | dist/index.d.ts |

Tests

pnpm test           # All tests (Vitest + MSW)
pnpm test:watch     # Watch mode
pnpm test:coverage  # Coverage report

License

MIT