FetchClient is a tiny, typed wrapper around fetch with JSON helpers, caching, middleware, rate limiting, circuit breaker, timeouts, and friendly error handling.

Features

• Typed JSON helpers - getJSON, postJSON, putJSON, patchJSON, deleteJSON
• Two API styles - Functional or class-based - your choice
• Response caching - TTL-based caching with tags for grouped invalidation
• Middleware - Intercept requests/responses for logging, auth, transforms
• Rate limiting - Per-domain rate limits with automatic header detection
• Circuit breaker - Prevent cascading failures when services go down
• Timeouts - Request timeouts with AbortSignal support
• Error handling - RFC 7807 Problem Details support
• Testing - MockRegistry for mocking HTTP in tests

Install

npm install @foundatiofx/fetchclient

Quick Example

FetchClient works two ways - pick whichever style you prefer:

Functional API

import { getJSON, postJSON, setBaseUrl } from "@foundatiofx/fetchclient";

setBaseUrl("https://api.example.com");

const { data: users } = await getJSON<User[]>("/users");
const { data: created } = await postJSON<User>("/users", { name: "Alice" });

Or use getFetchClient() to avoid multiple imports:

import { getFetchClient, setBaseUrl } from "@foundatiofx/fetchclient";

setBaseUrl("https://api.example.com");

const client = getFetchClient();
const { data: users } = await client.getJSON<User[]>("/users");
const { data: created } = await client.postJSON<User>("/users", {
  name: "Alice",
});

Class-Based API

import { FetchClient } from "@foundatiofx/fetchclient";

const client = new FetchClient({ baseUrl: "https://api.example.com" });
const { data } = await client.getJSON<User[]>("/users");

Caching

const response = await client.getJSON<User>("/api/users/1", {
  cacheKey: ["users", "1"],
  cacheDuration: 60000, // 1 minute
  cacheTags: ["users"],
});

// Invalidate by tag
client.cache.deleteByTag("users");

Middleware

import { useMiddleware } from "@foundatiofx/fetchclient";

useMiddleware(async (ctx, next) => {
  console.log("Request:", ctx.request.url);
  await next();
  console.log("Response:", ctx.response?.status);
});

Rate Limiting

import { usePerDomainRateLimit } from "@foundatiofx/fetchclient";

usePerDomainRateLimit({
  maxRequests: 100,
  windowSeconds: 60,
  updateFromHeaders: true, // Respect API rate limit headers
});

Circuit Breaker

import { useCircuitBreaker } from "@foundatiofx/fetchclient";

useCircuitBreaker({
  failureThreshold: 5,
  openDurationMs: 30000,
});

// When API fails repeatedly, circuit opens
// Requests return 503 immediately without hitting the API

Testing

import { FetchClientProvider } from "@foundatiofx/fetchclient";
import { MockRegistry } from "@foundatiofx/fetchclient/mocks";

const mocks = new MockRegistry();
mocks.onGet("/api/users").reply(200, [{ id: 1, name: "Alice" }]);

const client = new FetchClient();
mocks.install(client);

const { data } = await client.getJSON("/api/users");
// data = [{ id: 1, name: "Alice" }]

Documentation

• Guide & Examples: https://fetchclient.foundatio.dev
  • Getting Started
  • Caching
  • Middleware
  • Rate Limiting
  • Circuit Breaker
  • Error Handling
  • Testing
• API Reference: https://jsr.io/@foundatiofx/fetchclient/doc

MIT © Foundatio