Introduction
Typed HTTP calls for Effect, without the boilerplate.
Effetch is a thin layer over Effect v4's HttpClient for calling REST and
JSON APIs. You give it a path and a schema. It fills in the path, builds the
query, sends the request, checks the status and decodes the response. What
you get back is an Effect that's typed end to end, errors included, so
TypeScript tells you what a call returns and every way it can fail.
This page explains why Effetch exists, what it does and where it fits. To start using it, see Installation.
Release candidate
Effetch is close to its first stable release (0.1.0-rc.N). The API is
settled: release candidates add small, opt-in features and fixes, and the
changelog lists
anything that needs a change in your code.
Why Effetch
Effect gives you two ways to call an HTTP API, and they sit at opposite ends:
HttpClientis low level. For every request you build the URL, check the status and decode the body yourself.HttpApiis contract first. You describe the whole API up front and share it with the server, which is ideal when you own both sides.
Most apps sit in between. They call a backend they don't control, such as their company's REST API or a third-party service, one call at a time. Effetch is made for that. It gives each call the types and error handling of a contract, without you having to write one.
At a glance
Here's the same call written with HttpClient alone, and with Effetch:
import * as Effect from "effect/Effect";
import * as HttpClient from "effect/http/HttpClient";
import * as HttpClientResponse from "effect/http/HttpClientResponse";
import * as HttpIncomingMessage from "effect/http/HttpIncomingMessage";
import * as Schema from "effect/Schema";
import type { Fetch } from "@monarcode/effetch";
declare const api: Fetch.Client;
const Todo = Schema.Struct({ id: Schema.Finite, title: Schema.String });
// With HttpClient alone
export const getTodoByHand = (id: number) =>
Effect.gen(function* () {
const client = yield* HttpClient.HttpClient;
const response = yield* client.get(
`https://api.example.com/todos/${encodeURIComponent(id)}`,
);
const ok = yield* HttpClientResponse.filterStatusOk(response);
return yield* HttpIncomingMessage.schemaBodyJson(Todo)(ok);
});
// With Effetch
export const getTodo = (id: number) =>
api.get("/todos/:id", { params: { id }, output: Todo });Both send the same request and decode the same response. The Effetch version also:
- checks at compile time that every call passes an
id; - fails with
NetworkError,HttpErrororDecodeErrorrather thanHttpClientError | SchemaError, so you can handle each case on its own; - decodes the API's error body onto
HttpError, with a schema you give it; - runs the client's plugins, such as auth, retries, timeouts and logging, on every call.
What you get
- Paths that check themselves. Write
"/users/:id"and TypeScript asks forparams: { id }. No more, no less. - Queries from plain objects.
{ page: 2, tags: ["a", "b"] }becomes?page=2&tags=a&tags=b, andundefinedvalues are left out. - Responses you can trust. Decode the response with a
Schema, and the API's error body with another. The schemas' types become the call's types. - Errors you can catch by name. Three tagged errors,
NetworkError,HttpErrorandDecodeError, plus any your plugins add, all in the type. Turn statuses into your own errors, such as a404intoTodoNotFound, withstatusErrors. - Plugins for the repetitive parts. Auth with token refresh, retries, timeouts and logging are built in, and your own take a few lines. Any call can turn a plugin off or adjust it, and TypeScript checks the names and options.
- Endpoints. Save a route like
"GET /users/:id"with its schemas once, then call it like a function wherever you need it. Share a module's endpoints as a service withFetch.Endpoints. - Streams and pages. Read Server-Sent Events and newline-delimited JSON
as an Effect
Stream, and page through a list withFetch.paginate. - Tests without a network.
FetchTestmakes a typed fake backend from your endpoints, so tests run the real client with its plugins. - Runs anywhere. There are no platform-specific imports or builds: it targets browsers, React Native, Node 20+, Bun and Deno.
Where it fits
- Use Effetch to call REST and JSON APIs that you don't own, or don't share code with.
- Use Effect's
HttpApiwhen you own both the server and the client, and want them to share one contract. - Use
HttpClientdirectly for what Effetch doesn't cover, such as WebSockets or uploads with progress. Every Effetch client gives you its own when you need it.
If you know axios or ky, see Coming from axios or ky for how what you know maps to Effetch.
What's next
- Install Effetch.
- Read the full guide in the README, from your first client to testing.