fetch-with-proxy3

A robust, TypeScript-first HTTP client built on top of Axios with comprehensive proxy support and automatic retry logic. Designed for reliable network operations in unstable environments.

Features

🔄 Automatic Retry Logic: Configurable retry attempts with customizable delays
🌐 Comprehensive Proxy Support: HTTP, HTTPS, SOCKS4, and SOCKS5 proxies
🔒 Type-Safe: Full TypeScript support with comprehensive type definitions
⚡ Modern: Uses AbortController for request cancellation (no deprecated APIs)
🛡️ Reliable: Built-in error handling and timeout management
📦 Zero Config: Works out of the box with sensible defaults
🎯 Flexible: Highly configurable for various use cases

Installation

npm install fetch-with-proxy3

yarn add fetch-with-proxy3

pnpm add fetch-with-proxy3

Quick Start

Basic Usage (No Proxy)

import { fetchWithProxy } from 'fetch-with-proxy3';

const response = await fetchWithProxy('https://api.example.com/data', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your-token'
  }
});

if (response.ok) {
  console.log('Success:', response.data);
} else {
  console.error('Error:', response.error);
}

With HTTP/HTTPS Proxy

import { fetchWithProxy, PROXY_PROTOCOL } from 'fetch-with-proxy3';

const proxies = [{
  host: 'proxy.example.com',
  port: 8080,
  protocol: PROXY_PROTOCOL.http,
  username: 'your-username', // optional
  password: 'your-password'  // optional
}];

const response = await fetchWithProxy(
  'https://api.example.com/data',
  {
    method: 'POST',
    data: { key: 'value' },
    headers: { 'Content-Type': 'application/json' }
  },
  proxies,
  3,     // retry attempts
  1500,  // delay between retries (ms)
  30000  // timeout (ms)
);

With SOCKS Proxy

import { fetchWithProxy, PROXY_PROTOCOL } from 'fetch-with-proxy3';

const socksProxy = [{
  host: 'socks-proxy.example.com',
  port: 1080,
  protocol: PROXY_PROTOCOL.socks5,
  username: 'user',
  password: 'pass'
}];

const response = await fetchWithProxy(
  'https://api.example.com/secure-endpoint',
  { method: 'GET' },
  socksProxy
);

Multiple Proxies (Failover)

import { fetchWithProxy, PROXY_PROTOCOL } from 'fetch-with-proxy3';

const proxies = [
  {
    host: 'primary-proxy.com',
    port: 8080,
    protocol: PROXY_PROTOCOL.http
  },
  {
    host: 'backup-proxy.com',
    port: 3128,
    protocol: PROXY_PROTOCOL.https
  },
  {
    host: 'socks-proxy.com',
    port: 1080,
    protocol: PROXY_PROTOCOL.socks5
  }
];

// Will try each proxy in order until one succeeds
const response = await fetchWithProxy(
  'https://api.example.com/data',
  { method: 'GET' },
  proxies
);

API Reference

fetchWithProxy

function fetchWithProxy<T = any, D = any>(
  url: string,
  options?: AxiosRequestConfig<D>,
  proxies?: Proxy[],
  attempts?: number,
  delay?: number,
  timeout?: number
): Promise<AxiosResponse<T> & { ok: boolean; error?: Error }>

Parameters

Parameter	Type	Default	Description
`url`	`string`	-	The URL to request
`options`	`AxiosRequestConfig<D>`	`{}`	Axios request configuration
`proxies`	`Proxy[]`	`[]`	Array of proxy configurations
`attempts`	`number`	`3`	Number of retry attempts
`delay`	`number`	`1500`	Delay between retries (milliseconds)
`timeout`	`number`	`30000`	Request timeout (milliseconds)

Returns

Promise resolving to an enhanced Axios response with:

ok: Boolean indicating success (status 200-299)
error: Error object if request failed
All standard Axios response properties

fetchWithRetry

function fetchWithRetry<T = any, D = any>(
  url: string,
  options?: AxiosRequestConfig<D>,
  attempts?: number,
  delay?: number,
  timeout?: number
): Promise<AxiosResponse<T> & { ok: boolean; error?: Error }>

Direct retry functionality without proxy support.

Proxy Configuration

interface Proxy {
  host: string;
  port: number;
  protocol: PROXY_PROTOCOL;
  username?: string;
  password?: string;
}

enum PROXY_PROTOCOL {
  http = "http",
  https = "https",
  socks4 = "socks4",
  socks5 = "socks5",
  unknown = "unknown"
}

Error Handling

The library provides comprehensive error handling:

const response = await fetchWithProxy('https://api.example.com/data');

if (response.ok) {
  // Success - status code 200-299
  console.log(response.data);
} else {
  // Handle different error scenarios
  if (response.status === 404) {
    console.log('Resource not found');
  } else if (response.error) {
    console.error('Request failed:', response.error.message);
  }
}

Advanced Configuration

Custom Timeout and Retries

const response = await fetchWithProxy(
  'https://slow-api.example.com/data',
  { method: 'GET' },
  [], // no proxies
  5,     // 5 retry attempts
  2000,  // 2 second delay between retries
  60000  // 60 second timeout
);

Request Interceptors

Since this library is built on Axios, you can use Axios interceptors:

import axios from 'axios';

// Add request interceptor
axios.interceptors.request.use(config => {
  config.headers['X-Custom-Header'] = 'value';
  return config;
});

// Then use fetchWithProxy normally
const response = await fetchWithProxy('https://api.example.com/data');

TypeScript Support

Full TypeScript support with generic types:

interface ApiResponse {
  id: number;
  name: string;
  email: string;
}

interface RequestPayload {
  name: string;
  email: string;
}

const response = await fetchWithProxy<ApiResponse, RequestPayload>(
  'https://api.example.com/users',
  {
    method: 'POST',
    data: {
      name: 'John Doe',
      email: 'john@example.com'
    }
  }
);

// response.data is now typed as ApiResponse
console.log(response.data.name); // TypeScript knows this is a string

Testing

The library includes comprehensive tests. Run them with:

npm test

For coverage report:

npm run test:coverage

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

v1.0.4

Updated lint-staged to latest version (16.2.1)
Applied consistent code formatting with double quotes
Maintained 100% type safety and test coverage
Zero security vulnerabilities
Professional code quality assurance

v1.0.3

Updated all dependencies to latest versions
Replaced deprecated CancelToken with AbortController
Improved TypeScript type safety
Enhanced error handling
Added comprehensive test suite
Updated documentation

v1.0.2

Initial stable release with proxy support

Support

📧 Email: dmitrii.selikhov@gmail.com
🐛 Issues: GitHub Issues
💼 LinkedIn: Dmitrii Selikhov

Made with ❤️ by Dmitrii Selikhov

idimetrix / fetch-with-proxy