@gkoos/ffetch

@gkoos/ffetch

A production-ready TypeScript-first drop-in replacement for native fetch.

Key Features:

• Timeouts – per-request or global
• Retries – exponential backoff + jitter
• Circuit breaker – automatic failure protection
• Hooks – logging, auth, metrics, request/response transformation
• Pending requests – real-time monitoring of active requests
• Per-request overrides – customize behavior on a per-request basis
• Universal – Node.js, Browser, Cloudflare Workers, React Native
• Zero runtime deps – ships as dual ESM/CJS

Quick Start

Install

npm install @gkoos/ffetch

Basic Usage

import createClient from '@gkoos/ffetch'

// Create a client with timeout and retries
const api = createClient({
  timeout: 5000,
  retries: 3,
  retryDelay: ({ attempt }) => 2 ** attempt * 100 + Math.random() * 100,
})

// Make requests
const response = await api('https://api.example.com/users')
const data = await response.json()

Advanced Example

// Production-ready client with error handling and monitoring
const client = createClient({
  timeout: 10000,
  retries: 2,
  circuit: { threshold: 5, reset: 30000 },
  hooks: {
    before: async (req) => console.log('→', req.url),
    after: async (req, res) => console.log('←', res.status),
    onError: async (req, err) => console.error('Error:', err.message),
  },
})

try {
  const response = await client('/api/data')

  // Check HTTP status manually (like native fetch)
  if (!response.ok) {
    console.log('HTTP error:', response.status)
    return
  }

  const data = await response.json()
  console.log('Active requests:', client.pendingRequests.length)
} catch (err) {
  if (err instanceof TimeoutError) {
    console.log('Request timed out')
  } else if (err instanceof RetryLimitError) {
    console.log('Request failed after retries')
  }
}

Documentation

Topic	Description
Complete Documentation	Start here - Documentation index and overview
API Reference	Complete API documentation and configuration options
Advanced Features	Per-request overrides, pending requests, circuit breakers, custom errors
Hooks & Transformation	Lifecycle hooks, authentication, logging, request/response transformation
Usage Examples	Real-world patterns: REST clients, GraphQL, file uploads, microservices
Compatibility	Browser/Node.js support, polyfills, framework integration

Environment Requirements

ffetch requires modern AbortSignal APIs:

• Node.js 18.8+ (or polyfill for older versions)
• Modern browsers (Chrome 88+, Firefox 89+, Safari 15.4+, Edge 88+)

For older environments, see the compatibility guide.

CDN Usage

<script type="module">
  import createClient from 'https://unpkg.com/@gkoos/ffetch/dist/index.min.js'

  const api = createClient({ timeout: 5000 })
  const data = await api('/api/data').then((r) => r.json())
</script>

Fetch vs. Axios vs. ffetch

Feature	Native Fetch	Axios	ffetch
Timeouts	❌ Manual AbortController	✅ Built-in	✅ Built-in with fallbacks
Retries	❌ Manual implementation	❌ Manual or plugins	✅ Smart exponential backoff
Circuit Breaker	❌ Not available	❌ Manual or plugins	✅ Automatic failure protection
Request Monitoring	❌ Manual tracking	❌ Manual tracking	✅ Built-in pending requests
Error Types	❌ Generic errors	⚠️ HTTP errors only	✅ Specific error classes
TypeScript	⚠️ Basic types	⚠️ Basic types	✅ Full type safety
Hooks/Middleware	❌ Not available	✅ Interceptors	✅ Comprehensive lifecycle hooks
Bundle Size	✅ Native (0kb)	❌ ~13kb minified	✅ ~3kb minified
Modern APIs	✅ Web standards	❌ XMLHttpRequest	✅ Fetch + modern features

Contributing

• Issues: GitHub Issues
• Pull Requests: GitHub PRs
• Documentation: Found in ./docs/ - PRs welcome!

License

MIT © 2025 gkoos

Changelog

2.0.0

Major Changes

• 854591c: Added

  • tracking of pending requests

  Changed

  • AbortSignal.any fallback fixed
  • timeout(0) properly handled (no timeout)
  • signal combining fixed

  Docs

  • documentation refactored and expanded
  • migration guide added