@foundatiofx/fetchclient

!Foundatio
!Foundatio


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

``bash
npm install @foundatiofx/fetchclient
`

Quick Example

FetchClient works two ways - pick whichever style you prefer:

$3

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

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

const { data: users } = await getJSON("/users");
const { data: created } = await postJSON("/users", { name: "Alice" });
`

Or use getFetchClient() to avoid multiple imports:

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

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

const client = getFetchClient();
const { data: users } = await client.getJSON("/users");
const { data: created } = await client.postJSON("/users", {
name: "Alice",
});
`

$3

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

const client = new FetchClient({ baseUrl: "https://api.example.com" });
const { data } = await client.getJSON("/users");
`

Caching

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

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

Middleware

`ts
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

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

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

Circuit Breaker

`ts
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

`ts
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:
- Getting Started
- Caching
- Middleware
- Rate Limiting
- Circuit Breaker
- Error Handling
- Testing
- API Reference:

---

MIT © Foundatio