accio-js

Accio-JS

A modern, lightweight HTTP client for Node.js with built-in retry capabilities, timeout handling, and event monitoring. Built on top of Node's native fetch (via undici).

Features

• 🔄 Automatic retries with exponential backoff
• ⏱️ Request timeout support
• 🎯 Configurable retry conditions
• 🎲 Jitter for distributed systems
• 📊 Event-based monitoring
• 💪 Full TypeScript support
• 🪶 Lightweight with minimal dependencies

Quick Start

import { createHttpClient } from 'accio-js';

const client = createHttpClient();

try {
  const response = await client.get('https://api.example.com/data');
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error('Request failed:', error);
}

Configuration

const client = createHttpClient({
  // Default headers for all requests
  headers: {
    'Authorization': 'Bearer token',
  },
  
  // Request timeout in milliseconds
  timeout: 5000,
  
  // Retry configuration
  retry: {
    maxRetries: 3,
    initialDelay: 100,
    maxDelay: 1000,
    jitter: 0.1,
    retryableStatuses: [408, 429, 500, 502, 503, 504],
    shouldRetry: (error, attempt) => true,
  }
});

Configuration Options

Option	Type	Default	Description
headers	Record<string, string>	{}	Default headers for all requests
timeout	number	undefined	Request timeout in milliseconds
retry.maxRetries	number	3	Maximum number of retry attempts
retry.initialDelay	number	100	Initial delay between retries (ms)
retry.maxDelay	number	1000	Maximum delay between retries (ms)
retry.jitter	number	0.1	Random delay factor (0-1)
retry.retryableStatuses	number[]	[408, 429, 500, 502, 503, 504]	HTTP status codes that trigger retries

Event Monitoring

Monitor request lifecycle events:

client.on('request:start', (url, init) => {
  console.log(`Starting request to ${url}`);
});

client.on('request:end', (url, response, duration) => {
  console.log(`Request completed in ${duration}ms`);
});

client.on('request:error', (url, error, attempt) => {
  console.error(`Request failed (attempt ${attempt}):`, error);
});

client.on('request:retry', (url, error, attempt) => {
  console.log(`Retrying request (attempt ${attempt})`);
});

API Reference

HTTP Methods

• client.get(url, init?)
• client.post(url, init?)
• client.put(url, init?)
• client.delete(url, init?)
• client.patch(url, init?)
• client.fetch(url, init?) - Direct fetch with full request options

All methods return a Promise<Response> compatible with the Fetch API.

Events

• request:start - Emitted when a request begins
• request:end - Emitted when a request successfully completes
• request:error - Emitted when a request fails
• request:retry - Emitted before a retry attempt