FastFetch API Enhancer

FastFetch is a production-grade, enterprise-ready HTTP client built around the native fetch API. It transforms simple HTTP requests into robust network architecture by introducing advanced resilience patterns, high-concurrency request management, and real-time streaming capabilities without excessive boilerplate.

Architecture & Features

FastFetch v2 provides seven core execution pipelines directly into your fetch workflow:

• Strict Typed Error Hierarchy: Explicit errors for TimeoutError, NetworkError, HttpError, and CircuitOpenError enabling robust try/catch control flow.
• Koa-Style Middleware Pipeline: A powerful .use(async (ctx, next) => {}) onion-model interceptor architecture for modifying request metadata or observing response execution duration.
• Finite State Machine Circuit Breaker: Stops cascading failures to downstream services by automatically failing fast when failure thresholds are breached, entering a HALF_OPEN state after the configured timeout.
• Priority-Aware Concurrency Queue: Protects API rate limits by enforcing a strict maxConcurrent ceiling across all ongoing requests while maintaining execution priority.
• Offline Mutation Buffering: Automatically buffers mutating requests (POST, PUT, PATCH, DELETE) internally if the browser detects an offline state, sequentially replaying them upon reconnection.
• Real-Time Telemetry & Metrics: Maintains rolling windows on p50, p95, and p99 latency percentiles alongside exact endpoint success and failure ratios.
• Server-Sent Events (SSE) Native Streaming: A built-in high-performance stream consumer utilizing api.stream() for interacting with AI models and event-driven backends natively over HTTP.

Installation

npm install fastfetch-api-fetch-enhancer

Basic Usage

A minimal example utilizing the createClient factory method:

import { createClient } from 'fastfetch-api-fetch-enhancer';

// Instantiate your global HTTP client
const api = createClient({
  baseURL: 'https://api.example.com/v1',
  headers: { 'Authorization': 'Bearer <token>' },
  timeout: 10000,
  retries: 3,
  retryDelay: 1000,
  maxConcurrent: 50,
  circuitBreaker: {
    threshold: 5,
    timeout: 30000
  }
});

// Koa-style middleware injection
api.use(async (ctx, next) => {
  ctx.init.headers['X-Request-Id'] = crypto.randomUUID();
  await next();
  console.log(`[HTTP ${ctx.response?.status}] ${ctx.method} ${ctx.url} - ${ctx.duration}ms`);
});

// Start making requests
async function execute() {
  try {
    // Standard JSON shorthand
    const user = await api.json('/users/me');
    
    // Auto-serialization for payload delivery
    await api.post('/events', { action: 'login', timestamp: Date.now() });
    
  } catch (error) {
    // Typed catch boundaries
    if (error instanceof HttpError) {
      console.error('API Rejected Request:', error.status);
    } else if (error instanceof TimeoutError) {
      console.error('Request timed out at:', error.timeout);
    } else {
      console.error('Catastrophic failure:', error);
    }
  }
}

Advanced Streaming (SSE)

Consume AI generation pipelines directly over HTTP using the stream handler:

const signal = new AbortController();

await api.stream(
  '/ai/generate-text',
  (event) => {
    process.stdout.write(event.data);
  },
  { signal: signal.signal }
);

Monitoring & Telemetry

Evaluate application stability at any time by accessing the built-in system telemetry map:

const telemetry = api.metrics.snapshot();
console.table(telemetry.byEndpoint);
console.log('p99 global latency:', telemetry.globalLatencies.p99);

License

FastFetch is open-source software licensed under the MIT License.