@fetchkit/ffetch

A production-ready TypeScript-first drop-in replacement for native fetch, or any fetch-compatible implementation.

ffetch can wrap any fetch-compatible implementation (native fetch, node-fetch, undici, or framework-provided fetch), making it flexible for SSR, edge, and custom environments.

Key Features:

• Timeouts – per-request or global
• Retries – exponential backoff + jitter
• Circuit breaker – automatic failure protection
• Deduplication – automatic deduping of in-flight identical requests
• 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
• Configurable error handling – custom error types and throwOnHttpError flag to throw on HTTP errors

Quick Start

Install

npm install @fetchkit/ffetch

Basic Usage

import createClient from '@fetchkit/ffetch'

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

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

// Deduplication example: these two requests will be deduped
const p1 = api('https://api.example.com/data')
const p2 = api('https://api.example.com/data')
const [r1, r2] = await Promise.all([p1, p2])
// Only one fetch will occur; both promises resolve to the same response

Using a Custom fetchHandler (SSR, metaframeworks, or polyfills)

// Example: SvelteKit, Next.js, Nuxt, or node-fetch
import createClient from '@fetchkit/ffetch'

// Pass your framework's fetch implementation
const api = createClient({
  fetchHandler: fetch, // SvelteKit/Next.js/Nuxt provide their own fetch
  timeout: 5000,
})

// Or use node-fetch/undici in Node.js
import nodeFetch from 'node-fetch'
const apiNode = createClient({ fetchHandler: nodeFetch })

// All ffetch features work identically
const response = await api('/api/data')

Advanced Example

// Production-ready client with error handling and monitoring
const client = createClient({
  timeout: 10000,
  retries: 2,
  dedupe: true,
  dedupeHashFn: (params) => `${params.method}|${params.url}|${params.body}`,
  circuit: { threshold: 5, reset: 30000 },
  fetchHandler: fetch, // Use custom fetch if needed
  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),
    onCircuitOpen: (req) => console.warn('Circuit opened due to:', req.url),
    onCircuitClose: (req) => console.info('Circuit closed after:', req.url),
  },
})

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')
  }
}

Custom Error Handling with throwOnHttpError

Native fetch's controversial behavior of not throwing errors for HTTP error status codes (4xx, 5xx) can lead to overlooked errors in applications. By default, ffetch follows this same pattern, returning a Response object regardless of the HTTP status code. However, with the throwOnHttpError flag, developers can configure ffetch to throw an HttpError for HTTP error responses, making error handling more explicit and robust. Note that this behavior is affected by retries and the circuit breaker - full details are explained in the Error Handling documentation.

Documentation

| Topic | Description | | --------------------------------------------- | ------------------------------------------------------------------------- | | Complete Documentation | Start here - Documentation index and overview | | API Reference | Complete API documentation and configuration options | | Deduplication | How deduplication works, config, custom hash, limitations | | Error Handling | Strategies for managing errors, including throwOnHttpError | | 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 20.6+ (for AbortSignal.any)
• Modern browsers (Chrome 117+, Firefox 117+, Safari 17+, Edge 117+)

If your environment does not support AbortSignal.any (Node.js < 20.6, older browsers), you must install a polyfill before using ffetch. See the compatibility guide for instructions.

Custom fetch support: You can pass any fetch-compatible implementation (native fetch, node-fetch, undici, SvelteKit, Next.js, Nuxt, or a polyfill) via the fetchHandler option. This makes ffetch fully compatible with SSR, edge, metaframework environments, custom backends, and test runners.

"AbortSignal.any is not a function"

Solution: Install a polyfill for AbortSignal.any

npm install abort-controller-x

CDN Usage

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

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

Deduplication Limitations

• Deduplication is off by default. Enable it via the dedupe option.
• The default hash function is dedupeRequestHash, which handles common body types and skips deduplication for streams and FormData.
• Stream bodies (ReadableStream, FormData): Deduplication is skipped for requests with these body types, as they cannot be reliably hashed or replayed.
• Non-idempotent requests: Use deduplication with caution for non-idempotent methods (e.g., POST), as it may suppress multiple intended requests.
• Custom hash function: Ensure your hash function uniquely identifies requests to avoid accidental deduplication.

See deduplication.md for full details.

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 | | Deduplication | ❌ Not available | ❌ Not available | ✅ Automatic deduplication of in-flight identical requests | | 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 | | Custom Fetch Support | ❌ No (global only) | ❌ No | ✅ Yes (wrap any fetch-compatible implementation, including framework or custom fetch) |

Join the Community

Got questions, want to discuss features, or share examples? Join the Fetch-Kit Discord server:

Contributing

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

License

MIT © 2025 gkoos