@fetchkit/ffetch

@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.

ffetch uses a plugin architecture for optional features, so you only include what you need.

Key Features:

• Timeouts – per-request or global
• Retries – exponential backoff + jitter
• Abort-aware retries – aborting during backoff cancels immediately
• Plugin architecture – extensible lifecycle-based plugins for optional behavior
• 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
• Circuit breaker plugin (optional, prebuilt) – automatic failure protection
• Deduplication plugin (optional, prebuilt) – automatic deduping of in-flight identical requests

Quick Start

Install

npm install @fetchkit/ffetch

Basic Usage

import { createClient } from '@fetchkit/ffetch'
import { dedupePlugin } from '@fetchkit/ffetch/plugins/dedupe'

// Create a client with timeout, retries, and deduplication plugin
const api = createClient({
  timeout: 5000,
  retries: 3,
  plugins: [dedupePlugin()],
  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
import { createClient } from '@fetchkit/ffetch'
import { dedupePlugin } from '@fetchkit/ffetch/plugins/dedupe'
import { circuitPlugin } from '@fetchkit/ffetch/plugins/circuit'

const client = createClient({
  timeout: 10000,
  retries: 2,
  fetchHandler: fetch, // Use custom fetch if needed
  plugins: [
    dedupePlugin({
      hashFn: (params) => `${params.method}|${params.url}|${params.body}`,
      ttl: 30_000,
      sweepInterval: 5_000,
    }),
    circuitPlugin({
      threshold: 5,
      reset: 30_000,
      onCircuitOpen: (req) => console.warn('Circuit opened due to:', req.url),
      onCircuitClose: (req) => console.info('Circuit closed after:', req.url),
    }),
  ],
  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')
  }
}

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
Plugin Architecture	Plugin lifecycle, custom plugin authoring, and integration patterns
Deduplication	How deduplication works, hash config, optional TTL cleanup, 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 works best with native AbortSignal.any support:

• Node.js 20.6+ (native AbortSignal.any)
• Modern browsers with AbortSignal.any (for example: Chrome 117+, Firefox 117+, Safari 17+, Edge 117+)

If your environment does not support AbortSignal.any (Node.js < 20.6, older browsers), you can still use ffetch by installing an AbortSignal.any polyfill. AbortSignal.timeout is optional because ffetch includes an internal timeout fallback. 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 plugins: [dedupePlugin()].
• The default hash function is dedupeRequestHash, which handles common body types and skips deduplication for streams and FormData.
• Optional stale-entry cleanup: dedupePlugin({ ttl, sweepInterval }) enables map-entry eviction. TTL eviction only removes dedupe keys; it does not reject already in-flight promises.
• 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
Plugin Architecture	❌ Not available	⚠️ Interceptors only	✅ First-class plugin pipeline (optional built-in + custom plugins)
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