index.md

Documentation Index

Documentation Structure

Quick Start

• README.md - Installation, basic usage, and overview

API Reference

• api.md - Complete API documentation
  • createClient() options and return types
  • Configuration parameters and defaults
  • TypeScript interfaces and types

Plugin Architecture

• plugins.md - Plugin lifecycle, ordering, custom plugin authoring
  • Built-in feature plugins (bulkhead, dedupe, circuit, request-shortcuts, response-shortcuts)
  • Writing and registering custom plugins
  • Public plugin types and extension patterns

Getting Started

• migration.md - Migration guide from native fetch to ffetch
  • Drop-in replacement patterns
  • Error handling differences
  • v4 -> v5 plugin migration (dedupe/circuit flags -> plugins)
  • New capabilities and features
  • TypeScript migration tips

Advanced Features

• advanced.md - Advanced patterns and features

  • Per-request overrides
  • Pending requests monitoring
  • Retry strategies and circuit breakers
  • Custom error handling

• hedging.md - Reduce tail latency by racing parallel attempts

  • Hedging plugin configuration and behavior
  • Delay strategies and max hedges
  • Integration with retries and circuit breakers
  • Performance tuning for high-latency endpoints

• bulkhead.md - Isolate concurrency and apply queue backpressure

  • Bulkhead plugin configuration and defaults
  • Queue overflow handling and rejection strategy
  • Abort behavior for queued requests
  • Integration with dedupe, retries, and circuit breaker

• production-operations.md - Canonical production runbook and checklist

  • Pre-deployment configuration checklist
  • Metrics and alerting baseline
  • Incident playbook for circuit, latency, and rate-limit failures
  • Recommended baseline configurations

Hooks & Transformation

• hooks.md - Lifecycle hooks and request/response transformation
  • All available hooks (before, after, onError, etc.)
  • Request and response transformation
  • Authentication, logging, and caching patterns

Usage Examples

• examples.md - Real-world examples and patterns
  • REST API clients
  • Microservices integration
  • GraphQL clients
  • File uploads and polling
  • Error handling strategies

Compatibility Guide

• compatibility.md - Browser and Node.js compatibility
  • Environment requirements
  • Polyfills and fallbacks
  • Framework integration (React, Vue, Svelte)
  • Troubleshooting common issues

Getting Started

1. Start with the README for installation and basic usage
2. If migrating from v4, read migration.md before applying v5 examples
3. Check compatibility.md to ensure your environment is supported
4. Explore examples.md for concrete patterns you can adapt quickly
5. Read hooks.md for auth, logging, request/response transforms, and caching
6. Read api.md for full option and plugin reference details
7. Read plugins.md to understand lifecycle, ordering, and custom plugins
8. Dive into advanced.md for retry strategy, circuit behavior, and production patterns
9. Use production-operations.md when preparing rollout, alerts, and incident response

Alternative Learning Paths

• Concept-first path: README -> compatibility -> plugins -> api -> examples -> advanced
• Example-first path: README -> examples -> hooks -> api -> plugins -> advanced

Finding What You Need

I want to...

Goal	Documentation
Get started quickly	README.md
Error handling	errorhandling.md
Deduplicate requests (with optional TTL cleanup)	deduplication.md
Migrate from native fetch	migration.md
Understand plugin architecture	plugins.md
Write a custom plugin	plugins.md
See all configuration options	api.md
Handle errors gracefully	advanced.md
Add authentication to requests	hooks.md
Build a REST API client	examples.md
Monitor active requests	advanced.md
Implement retry logic	advanced.md
Use with React/Vue/Svelte	compatibility.md
Debug connection issues	compatibility.md
Transform requests/responses	hooks.md
Handle rate limiting	examples.md
Cache responses	examples.md
Use client.get() / client.post() shortcuts	api.md
Use client(url).json() style shortcuts	api.md
Reduce tail latency with parallel attempts	hedging.md
Cap concurrency with queue backpressure	bulkhead.md
Operate ffetch safely in production	production-operations.md

Key Concepts

Core Features

• Timeouts: Per-request or global timeout configuration
• Retries: Exponential backoff with jitter and custom retry logic
• Plugin-based optional features: Bulkhead, circuit breaker, dedupe, and third-party plugins
• Hooks: Lifecycle events for logging, auth, and transformation
• Pending Requests: Real-time monitoring of active requests
• Custom fetch wrapping: Pluggable fetch implementation for SSR, node-fetch, undici, and framework-provided fetch

Error Handling

• Custom error types (TimeoutError, RetryLimitError, etc.)
• Graceful degradation patterns
• Circuit breaker for service protection
• Comprehensive error context

Flexibility

• Per-request option overrides
• Pluggable retry and timeout strategies
• Request/response transformation
• Universal compatibility (Node.js, browsers, workers)

Common Patterns

Basic HTTP Client

import { createClient } from '@fetchkit/ffetch'

const api = createClient({
  timeout: 5000,
  retries: 2,
})

const data = await api('/api/users').then((r) => r.json())

With Error Handling

try {
  const response = await api('/api/data')
  return await response.json()
} catch (err) {
  if (err instanceof TimeoutError) {
    // Handle timeout
  } else if (err instanceof RetryLimitError) {
    // Handle retry exhaustion
  }
  throw err
}

With Authentication

const api = createClient({
  hooks: {
    transformRequest: async (req) => {
      return new Request(req, {
        headers: {
          ...Object.fromEntries(req.headers),
          Authorization: `Bearer ${getToken()}`,
        },
      })
    },
  },
})

Contributing

Found an issue or want to improve the documentation?

• Issues: GitHub Issues
• Pull Requests: GitHub PRs
• Discussions: GitHub Discussions

License

MIT © 2025 gkoos