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,queryJSON,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
- API Reference: https://jsr.io/@foundatiofx/fetchclient/doc
MIT © Foundatio