Welcome! I created this course to help you get familiar with the core APIs of Effect's HttpClient module: the toolkit for sending HTTP requests and processing responses in Effect. Each chapter is self-contained with complete, runnable code snippets. You can jump to any chapter that interests you. That said, I'd recommend going through them in sequence, as later chapters build on patterns introduced in earlier ones. This course assumes you have a basic understanding of Effect (error handling, and the `Effect.gen` pattern). If you're new to Effect itself, I'd suggest starting there first. Happy learning! --- import { Note } from "@/components/note"; Let's set up our project with the required dependencies. ## Installing Dependencies Create a new directory and initialize a project: ```bash mkdir effect-http-client cd effect-http-client npm init -y ``` Install the required packages: ```bash npm install effect@4.0.0-beta.6 @effect/platform-node@4.0.0-beta.6 npm install -D typescript tsx @types/node ``` `@effect/platform-node` provides Node.js-specific implementations for Effect's platform services. Effect defines abstract services like `FileSystem` and `Path` that your code uses, and `@effect/platform-node` supplies the concrete Node.js implementations that make them work. We'll need this in a later chapter when we learn to upload files from the local filesystem. In Effect v4, many packages that were previously separate have been consolidated into the core `effect` package. `HttpClient` is one of them. It now lives in effect as an unstable module. This is why our install command only has two packages: `effect` for the core library (which includes `HttpClient`), and `@effect/platform-node` for Node.js-specific services like filesystem access. ## Configuring the Project Add `"type": "module"` to your `package.json` to enable ES modules: ```json title="package.json" {12} { "name": "effect-http-client", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "", "license": "ISC", "type": "module", "dependencies": { "@effect/platform-node": "4.0.0-beta.6", "effect": "4.0.0-beta.6" }, "devDependencies": { "@types/node": "^25.2.3", "tsx": "^4.21.0", "typescript": "^5.9.3" } } ``` Create a `tsconfig.json` in the project root: ```json title="tsconfig.json" { "compilerOptions": { "target": "ES2022", "module": "nodenext", "moduleResolution": "nodenext", "strict": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "outDir": "./dist" }, "include": ["*.ts"] } ``` ## Running TypeScript Files We use `tsx` to run TypeScript files directly without a separate compilation step. Every code snippet in this course is complete and runnable. To try any example, copy the code into a `.ts` file (e.g., `http.ts`) and run it with: ```bash npx tsx http.ts ``` Note that `tsx` does not perform type checking. To catch type errors, run `npx tsc --noEmit` separately. {/* prettier-ignore */} When you copy the code snippets from this course into your editor, you'll see TypeScript errors when accessing properties on data returned from `response.json` (for example, `user.firstName` or `product.title`). This is because `response.json` returns `unknown`, and we access properties without validating the response shape first. This is intentional. Each code snippet is focused on the specific API being discussed, and adding schema validation to every example would distract from the topic at hand. In a real application, you'd use `HttpClientResponse.schemaBodyJson()` to validate and type the response, which is covered in its own chapter. --- `HttpClient` is **Effect's module for sending HTTP requests and handling responses**. It provides a consistent API that works across different JavaScript runtimes: Node.js, browsers, Bun, Deno, and others. Different JavaScript runtimes have different ways of making HTTP requests. Node.js has `http`/`https` modules, browsers have the Fetch API, and other runtimes have their own implementations. `HttpClient` abstracts over these differences. You write your HTTP code once using the `HttpClient` interface, and then provide a platform-specific implementation when you run it. The `effect` package ships with `FetchHttpClient`, which uses the Fetch API available in modern Node.js (v18+) and all browsers. This is why every example in this course provides a `FetchHttpClient.layer`: ```ts Effect.provide(FetchHttpClient.layer); ``` You're telling Effect: "When this code needs an HTTP client, use the Fetch-based implementation." --- import { Note } from "@/components/note"; The most straightforward way to make a `GET` request is using the `HttpClient` service directly. ```ts title="http.ts" {7, 10, 13} import { FetchHttpClient, HttpClient } from "effect/unstable/http"; import { Effect } from "effect"; function fetchUser(userId: number) { return Effect.gen(function* () { // Step 1: Access the HttpClient service from the Effect context const client = yield* HttpClient.HttpClient; // Step 2: Make a GET request const response = yield* client.get(`https://dummyjson.com/users/${userId}`); // Step 3: Parse the response body as JSON const user = yield* response.json; return user; }).pipe( // Step 4: Provide the FetchHttpClient implementation Effect.provide(FetchHttpClient.layer), ); } // Test it Effect.runPromise(fetchUser(1)).then((user) => { console.log("Name:", user.firstName, user.lastName); }); ``` **Output:** ```bash Name: Emily Johnson ``` We import two key modules:`HttpClient` and `FetchHttpClient`. `HttpClient` is the main module for making HTTP requests. `FetchHttpClient` provides an HTTP client implementation using the browser/Node.js Fetch API. Inside the `fetchUser()` function, we first access the `HttpClient` service from the Effect context using `yield* HttpClient.HttpClient`. Next, we call `client.get(url)` to make a `GET` request. We then parse the response body as JSON using `response.json`. Finally, we pipe the result into `Effect.provide(FetchHttpClient.layer)` to provide the actual HTTP implementation to our program. Without it, the program wouldn't know how to make real HTTP requests. --- The **Accessor** API provides a shortcut that skips the manual service access step. Instead of writing `yield* HttpClient.HttpClient` first, you call the method directly on the `HttpClient` module: ```ts title="http.ts" {6} import { FetchHttpClient, HttpClient } from "effect/unstable/http"; import { Effect } from "effect"; function fetchUser(userId: number) { // Using accessor API. No need for Effect.gen to access the client return HttpClient.get(`https://dummyjson.com/users/${userId}`).pipe( Effect.andThen((response) => response.json), Effect.provide(FetchHttpClient.layer), ); } // Test it Effect.runPromise(fetchUser(2)).then((user) => { console.log("Name:", user.firstName, user.lastName); }); ``` **Output:** ```ts bash Name: Michael Williams ``` --- For more control over your requests, you can use `HttpClientRequest` to build a request object first, then execute it. **This is the pattern we'll use throughout the rest of this course** because it composes better and gives you more flexibility. ```ts title="http.ts" {10, 13-15, 18, 21} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchUserWithRequest(userId: number) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; // Step 1: Create a request object const request = HttpClientRequest.get( `https://dummyjson.com/users/${userId}`, ); // Step 2: Execute the request const response = yield* client.execute(request); // Step 3: Parse the response const user = yield* response.json; return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchUserWithRequest(3)).then((user) => { console.log("Name:", user.firstName, user.lastName); }); ``` The `HttpClientRequest` pattern separates request creation from execution: 1. **Create:** `HttpClientRequest.get(url)` creates a request object. 2. **Modify(optional):** Add headers, URL parameters, a request body, and more using `.pipe().` In the example above, we don't customize the request, but you'll see plenty of examples in the upcoming chapters. 3. **Execute:** `client.execute(request)` sends the request. **Output:** ```bash Name: Sophia Brown ``` --- A `POST` request tells the server to **create a new resource**. Unlike `GET`, which only retrieves data, `POST` sends data in the request body for the server to process. ```ts title="http.ts" {12-14} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function addPost(post: { title: string; body: string; userId: number }) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.post( "https://dummyjson.com/posts/add", ).pipe(HttpClientRequest.bodyJsonUnsafe(post)); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise( addPost({ title: "Effect is awesome", body: "A deep dive into the Effect HTTP client module.", userId: 1, }), ).then((data) => { console.log("Created post:", data); }); ``` **Output:** ```bash Created post: { id: 252, title: 'Effect is awesome', body: 'A deep dive into the Effect HTTP client module.', userId: 1 } ``` `HttpClientRequest.post(url)` creates a request with the `POST` method. Unlike `GET` requests, `POST` requests carry data in the request body. This data can be in different formats: JSON, plain text, FormData, or a file stream. In the example above, we're sending JSON using `bodyJsonUnsafe`, which takes a plain JavaScript object and serializes it as JSON, setting the `Content-Type` header automatically. `HttpClient` actually provides three methods for sending JSON data: [bodyJson](sending-json-data/using-body-json), [bodyJsonUnsafe](sending-json-data/using-body-json-unsafe), and [schemaBodyJson](sending-json-data/using-schema-body-json). Each offers a different level of type safety. These are covered in detail in the **Sending JSON Data** chapter. For sending other body types, the **Sending Files** and **Sending Form Data** chapters cover their respective APIs. Note that the dummyJSON API simulates creation. It returns the submitted data with a new id, but doesn't actually store it on the server. --- A `PUT` request tells the server to replace a resource entirely. You send the complete new version of the resource, and the server swaps out the old one. Any fields you don't include are removed or reset to defaults. ```ts title="http.ts" {15-17} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function replaceProduct( productId: number, product: { title: string; price: number; category: string }, ) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.put( `https://dummyjson.com/products/${productId}`, ).pipe(HttpClientRequest.bodyJsonUnsafe(product)); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it — replace product 1 with entirely new data Effect.runPromise( replaceProduct(1, { title: "Mechanical Keyboard", price: 199, category: "electronics", }), ).then((data) => { console.log("Updated product:", data.title, `- $${data.price}`); }); ``` **Output:** ```bash Updated product: Mechanical Keyboard - $199 ``` `HttpClientRequest.put(url)` creates a request with the `PUT` method. The rest of the pattern is identical to `POST`: attach a body and execute. --- A `PATCH` request tells the server to **update specific fields** of a resource, leaving everything else unchanged. You only send the fields you want to modify. ```ts title="http.ts" {13-15} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function updateProductPrice(productId: number, newPrice: number) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; // Only send the field we want to change const request = HttpClientRequest.patch( `https://dummyjson.com/products/${productId}`, ).pipe(HttpClientRequest.bodyJsonUnsafe({ price: newPrice })); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it — update only the price of product 1 Effect.runPromise(updateProductPrice(1, 5.99)).then((data) => { console.log("Product:", data.title); console.log("New price:", `$${data.price}`); }); ``` **Output:** ```bash Product: Essence Mascara Lash Princess New price: $5.99 ``` `HttpClientRequest.patch(url)` creates a request with the `PATCH` method. The body contains only the fields to update. --- A `DELETE` request tells the server to remove a resource. You specify what to delete by URL. No request body is needed. ```ts title="http.ts" {12-14} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function deleteProduct(productId: number) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.del( `https://dummyjson.com/products/${productId}`, ); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(deleteProduct(1)).then((data) => { console.log("Deleted:", data.title); console.log("isDeleted:", data.isDeleted); console.log("deletedOn:", data.deletedOn); }); ``` **Output:** ```bash Deleted: Essence Mascara Lash Princess isDeleted: true deletedOn: 2026-02-18T14:27:54.479Z ``` The method is called `HttpClientRequest.del()` — not `delete` — because `delete` is a reserved keyword in JavaScript. The same applies to the client's shorthand: `client.del(url)` instead of `client.delete(url)`. Note that the dummyJSON API simulates deletion by returning the product data with `isDeleted: true` and a `deletedOn` timestamp. --- `HttpClient.tapRequest()` runs a side effect on the request object before it's sent. This is ideal for logging outgoing requests. ```ts title="http.ts" {11-16} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchUserWithRequestLogging(userId: number) { return Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.tapRequest((request) => Effect.sync(() => { console.log(`[Request] ${request.method} ${request.url}`); console.log(`[Request] Headers:`, request.headers); }), ), ); const request = HttpClientRequest.get( `https://dummyjson.com/users/${userId}`, ).pipe(HttpClientRequest.setHeader("X-Request-Id", "abc-123")); const response = yield* client.execute(request); const user = yield* response.json; return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchUserWithRequestLogging(1)).then((user) => { console.log("User:", user.firstName, user.lastName); }); ``` **Output:** ```bash [Request] GET https://dummyjson.com/users/1 [Request] Headers: { 'x-request-id': 'abc-123' } User: Emily Johnson ``` `tapRequest` receives the fully built `HttpClientRequest` — including any headers, URL params, and body that were added — and runs your side effect before the request is sent. Note that whatever you return from the `tapRequest` callback doesn't modify the request. The request passes through unchanged. Only the side effect (like logging) runs. --- `HttpClient.tap()` runs a side effect after a successful response is received. This is the response-side counterpart to `tapRequest`. ```ts title="http.ts" {11-16} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchUserWithResponseLogging(userId: number) { return Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.tap((response) => Effect.sync(() => { console.log(`[Response] Status: ${response.status}`); console.log(`[Response] Headers:`, response.headers); }), ), ); const request = HttpClientRequest.get( `https://dummyjson.com/users/${userId}`, ); const response = yield* client.execute(request); const user = yield* response.json; return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchUserWithResponseLogging(1)).then((user) => { console.log("User:", user.firstName, user.lastName); }); ``` **Output:** ```bash [Response] Status: 200 [Response] Headers: { 'access-control-allow-origin': '*', 'cf-cache-status': 'DYNAMIC', 'cf-ray': '9d0617b0acc6d43a-SIN', connection: 'keep-alive', 'content-encoding': 'br', 'content-type': 'application/json; charset=utf-8', date: 'Thu, 19 Feb 2026 13:25:51 GMT', etag: 'W/"58f-CoL/KoXlW3x1PtqQr3wqPsXj6DE"', nel: '{"report_to":"cf-nel","success_fraction":0.0,"max_age":604800}', 'report-to': '{"group":"cf-nel","max_age":604800,"endpoints":[{"url":"https://a.nel.cloudflare.com/report/v4?s=2mQIukE1lkEHVqD0dmK%2F4UFc%2B%2FaDuB%2FAkxldT47AFxVSW4kn57D%2BxUr9%2FCi6ZGCIbRvtIfafgQfMZfi3wBrZklxBNYX0R39HUBw4FZsyLaYJQJ8DyJXDt%2FI%3D"}]}', server: 'cloudflare', 'strict-transport-security': 'max-age=15552000; includeSubDomains', 'transfer-encoding': 'chunked', vary: 'Accept-Encoding', 'x-content-type-options': 'nosniff', 'x-dns-prefetch-control': 'off', 'x-download-options': 'noopen', 'x-frame-options': 'SAMEORIGIN', 'x-ratelimit-limit': '100', 'x-ratelimit-remaining': '73', 'x-ratelimit-reset': '1771507553', 'x-xss-protection': '1; mode=block' } User: Emily Johnson ``` `tap` receives the `HttpClientResponse `object. Like `tapRequest`, it's a side effect. The response flows through unchanged. --- As your API integration grows, you'll find yourself adding the same headers, URL parameters, or other request modifications to every call. Instead of repeating that setup, you can bake it into the client using `HttpClient.mapRequest()`. `mapRequest` takes a function that modifies the request, and applies it to every outgoing request. The function is **synchronous**. It receives an `HttpClientRequest` and returns a new `HttpClientRequest`. ```ts title="http.ts" {11-16} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchFromApi() { return Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.mapRequest( HttpClientRequest.prependUrl("https://dummyjson.com"), ), HttpClient.mapRequest( HttpClientRequest.setHeader("X-App-Version", "2.1.0"), ), ); // All requests now have the base URL and version header const response = yield* client.get("/products/1"); const product = yield* response.json; return product; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchFromApi()).then((product) => { console.log("Product:", product.title, `- $${product.price}`); }); ``` **Output:** ```bash Product: Essence Mascara Lash Princess - $9.99 ``` In the example above, we create a client that automatically prepends a base URL and attaches a version header to every outgoing request. When we call `client.get("/products/1")`, the request is sent to `https://dummyjson.com/products/1` with the `X-App-Version` header included, without repeating that setup on every request. Each `mapRequest` call adds a transformation to the client. You can chain as many as you need, and they run in the order they're registered. The first mapRequest prepends the base URL, and the second adds the header. Every request made through this client goes through both transformations. --- Sometimes a request transformation needs to perform an effect: reading from a config service, fetching a token, or generating a unique ID. `HttpClient.mapRequestEffect()` is the effectful counterpart to `mapRequest`. ```ts title="http.ts" {11-22} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchFromApi() { return Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.mapRequestEffect((request) => Effect.gen(function* () { // Simulate fetching a dynamic request ID const requestId = yield* Effect.sync( () => `req-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`, ); return request.pipe( HttpClientRequest.prependUrl("https://dummyjson.com"), HttpClientRequest.setHeader("X-Request-Id", requestId), ); }), ), ); const response = yield* client.get("/users/1"); const user = yield* response.json; return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchFromApi()).then((user) => { console.log("User:", user.firstName, user.lastName); }); ``` **Output:** ```bash User: Emily Johnson ``` The key difference from `mapRequest` is that the callback returns an `Effect` instead of a plain `HttpClientRequest`. This means you can yield effects inside the transformation. You can access services, read config, generate values, or even perform preliminary network calls. If the effectful transform fails, that error gets added to the client's error channel. --- `HttpClient.mapRequestInput()` is similar to `mapRequest`, but it **prepends** the transformation instead of appending it. The difference matters when you stack multiple transforms. Consider this scenario: you have a client with a base URL transform (appended via `mapRequest`), and you want to add another transform that modifies the URL path. The order of execution determines the final URL. ```ts title="http.ts" {28-31} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function demonstrateOrder() { return Effect.gen(function* () { // mapRequest APPENDS — runs after existing transforms const client1 = (yield* HttpClient.HttpClient).pipe( HttpClient.mapRequest( HttpClientRequest.prependUrl("https://dummyjson.com"), ), // This runs AFTER prependUrl, so it sees the full URL HttpClient.mapRequest((request) => { console.log("[mapRequest] URL is:", request.url); return request; }), ); // mapRequestInput PREPENDS — runs before existing transforms const client2 = (yield* HttpClient.HttpClient).pipe( HttpClient.mapRequest( HttpClientRequest.prependUrl("https://dummyjson.com"), ), // This runs BEFORE prependUrl, so it sees only the path HttpClient.mapRequestInput((request) => { console.log("[mapRequestInput] URL is:", request.url); return request; }), ); console.log("--- Using mapRequest ---"); yield* client1.get("/users/1").pipe(Effect.ignore); console.log("\n--- Using mapRequestInput ---"); yield* client2.get("/users/1").pipe(Effect.ignore); }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(demonstrateOrder()); ``` **Output:** ```bash --- Using mapRequest --- [mapRequest] URL is: https://dummyjson.com/users/1 --- Using mapRequestInput --- [mapRequestInput] URL is: /users/1 ``` With `mapRequest`, the log sees the full URL because it runs after `prependUrl`. With `mapRequestInput`, the log sees only `/users/1` because it runs before `prependUrl`. Use `mapRequestInput` when you need a transform to run before all other registered transforms. There's also a `mapRequestInputEffect` variant for effectful prepended transforms. In most cases, `mapRequest` is what you want. Reach for `mapRequestInput` only when execution order matters. --- Just as you can transform outgoing requests, you can also transform the response pipeline. `HttpClient.transformResponse()` wraps the response effect itself, letting you apply Effect combinators to every response. This is useful for cross-cutting response concerns: adding timeouts, retries, or caching behavior to every request made through a client. ```ts title="http.ts" {11-18} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchFromApi() { return Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.transformResponse((responseEffect) => responseEffect.pipe( Effect.tap((response) => Effect.log(`Response received: ${response.status}`), ), Effect.timeout("10 seconds"), ), ), ); const response = yield* client.get("https://dummyjson.com/users/1"); const user = yield* response.json; return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchFromApi()).then((user) => { console.log("User:", user.firstName, user.lastName); }); ``` **Output:** ```bash [12:47:43.151] INFO (#2): Response received: 200 User: Emily Johnson ``` The function passed to `transformResponse` receives the full `Effect`, not just the response, but the effect that produces it. This means you can wrap it with any Effect combinator: `timeout`, `retry`, `tap`, `catchAll`, and so on. Because `transformResponse` replaces the entire response pipeline, any errors or requirements introduced by your transform (like a `TimeoutException` from `Effect.timeout`) become part of the client's error type. --- Sometimes you need to coordinate between the request and the response. For example, you might want to start a timer when the request is built and log the elapsed time when the response arrives. `HttpClient.transform()` gives you access to both. ```ts title="http.ts" {11-23} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchFromApi() { return Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.transform((responseEffect, request) => Effect.gen(function* () { const start = Date.now(); console.log(`--> ${request.method} ${request.url}`); const response = yield* responseEffect; const elapsed = Date.now() - start; console.log(`<-- ${response.status} (${elapsed}ms)`); return response; }), ), ); const response = yield* client.get("https://dummyjson.com/users/1"); const user = yield* response.json; return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchFromApi()).then((user) => { console.log("User:", user.firstName, user.lastName); }); ``` **Output:** ```bash --> GET https://dummyjson.com/users/1 <-- 200 (643ms) User: Emily Johnson ``` The function passed to `transform` receives two arguments: the response effect and the request that triggered it. You `yield*` the response effect to actually execute the request, and you can do work before and after. **You must explicitly yield the response effect, or the request won't be sent at all.** Use `transform` when you need to correlate requests with their responses, like timing, tracing, or conditional retries based on request properties. --- A common need when working with APIs is setting a base URL so you don't repeat the full domain in every request. You can do this by customizing the client with `HttpClient.mapRequest` and `HttpClientRequest.prependUrl`. ```ts title="http.ts" {12-14} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchFromApi() { return Effect.gen(function* () { // Create a client with a base URL baked in const client = (yield* HttpClient.HttpClient).pipe( HttpClient.mapRequest( HttpClientRequest.prependUrl("https://dummyjson.com"), ), ); // Now all requests are relative to the base URL const usersResponse = yield* client.get("/users/1"); const user = yield* usersResponse.json; const productsResponse = yield* client.get("/products/1"); const product = yield* productsResponse.json; return { user, product }; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchFromApi()).then(({ user, product }) => { console.log("User:", user.firstName, user.lastName); console.log("Product:", product.title, `- $${product.price}`); }); ``` **Output:** ```bash User: Emily Johnson Product: Essence Mascara Lash Princess - $9.99 ``` In the example above, we create a client with a base URL baked in using `mapRequest` and `prependUrl`. Every request made through this client only needs a relative path. `"/users/1"` becomes `"https://dummyjson.com/users/1"` automatically. --- To set a single query parameter, use `HttpClientRequest.setUrlParam()`. In the example below, we add a `limit` parameter to restrict the number of users returned by the API. ```ts title="http.ts" {13} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchUsersWithLimit(limit: number) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.get("https://dummyjson.com/users").pipe( HttpClientRequest.setUrlParam("limit", limit.toString()), ); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchUsersWithLimit(3)).then((data) => { console.log("Names:", data.users.map((user) => user.firstName).join(", ")); }); ``` **Output:** ```bash Names: Emily, Michael, Sophia ``` --- To set multiple query parameters, use `HttpClientRequest.setUrlParams()`. In the example below, we add both `limit` and `sortBy` parameters to control how many users are returned and in what order. ```ts title="http.ts" {13-16} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchUsersPaginated(options: { limit: number; sortBy: string }) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.get("https://dummyjson.com/users").pipe( HttpClientRequest.setUrlParams({ limit: options.limit.toString(), sortBy: options.sortBy, }), ); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise( fetchUsersPaginated({ limit: 5, sortBy: "firstName", }), ).then((data) => { data.users.map((user) => { console.log(` ${user.firstName} ${user.lastName}`); }); }); ``` **Output:** ```bash Aaliyah Hanson Aaliyah Martinez Aaron Cook Abigail Rivera Addison Wright ``` --- You can also pass parameters to a request directly when creating the request, using the `Options` object: ```ts title="http.ts" {13-18} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchUsersPaginated(options: { limit: number; sortBy: string }) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; // Pass urlParams directly in the options object const request = HttpClientRequest.get("https://dummyjson.com/users", { urlParams: { limit: options.limit.toString(), sortBy: options.sortBy, }, }); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise( fetchUsersPaginated({ limit: 5, sortBy: "firstName", }), ).then((data) => { data.users.map((user: any) => { console.log(` ${user.firstName} ${user.lastName}`); }); }); ``` **Output:** ```bash Aaliyah Hanson Aaliyah Martinez Aaron Cook Abigail Rivera Addison Wright ``` The `Options` object isn't limited to `urlParams`. You can set headers, accept types, and more, all in one place: ```ts const request = HttpClientRequest.get("https://dummyjson.com/users", { urlParams: { limit: "5", sortBy: "firstName", }, headers: { "X-Request-Source": "effect-course", }, acceptJson: true, }); ``` This is equivalent to chaining `setUrlParams`, `setHeaders`, and `acceptJson` through `.pipe()`. The result is the same, use whichever style you prefer. Here's the full list of properties you can pass in the options object: | Property | Type | Description | | ------------ | ------------------- | -------------------------------------------------------------------------------------- | | `urlParams` | `UrlParams.Input` | Query string parameters to append to the URL endpoint. | | `headers` | `Headers.Input` | Custom HTTP headers to include in the request. | | `body` | `HttpBody.HttpBody` | The payload of the request (e.g., JSON, FormData, Stream). | | `accept` | `string` | Explicitly sets the `Accept` header to a specific media type. | | `acceptJson` | `boolean` | A convenient shorthand to automatically set the `Accept` header to `application/json`. | | `hash` | `string` | The URL fragment identifier (the part of the URL after the `#`). | | `url` | `string \| URL` | The endpoint URL. | | `method` | `HttpMethod` | The specific HTTP method (e.g., `"GET"`, `"POST"`). | Note that while the base `Options` object contains all the properties above, Effect TS uses TypeScript utility types to restrict certain fields depending on _how_ the request is constructed. - **`Options.NoBody`:** When using `HttpClientRequest.get()` or `HttpClientRequest.head()`, the options object **omits** `method`, `url`, and `body`. You cannot pass a body to a `GET` request this way. - **`Options.NoUrl`:** When using `HttpClientRequest.post()`, `HttpClientRequest.put()`, `HttpClientRequest.patch()`, or `HttpClientRequest.del()`, the options object **omits** `method` and `url` (because they are already defined by the constructor and the first argument), but it does allow `body`. These same option variants apply to the [client's shorthand methods](/courses/effect-http-client/making-get-requests/using-httpclient) as well: {/* prettier-ignore */} ```ts const client = yield* HttpClient.HttpClient; // Options passed directly to client.get const response = yield* client.get("https://dummyjson.com/users", { urlParams: { limit: "3" }, acceptJson: true, }); ``` The [`.pipe()` pattern](/courses/effect-http-client/making-get-requests/using-httpclientrequest) and the options object are interchangeable. The `.pipe()` approach is better when you're building requests incrementally or conditionally. The options object is better when you know everything upfront and want it in one place. --- To append several parameters with the same key, use `HttpClientRequest.appendUrlParams()`: ```ts title="http.ts" {17} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchPosts(tags: string[]) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; // Convert array to tuples for duplicate keys const tagTuples: Array<[string, string]> = tags.map((tag) => ["tag", tag]); const request = HttpClientRequest.get("https://dummyjson.com/posts").pipe( HttpClientRequest.setUrlParam("limit", "3"), HttpClientRequest.appendUrlParams(tagTuples), ); console.log("URL Params:", request.urlParams); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchPosts(["love", "history", "mystery"])).then((data) => { data.posts.forEach((post: any) => { console.log(` - "${post.title.slice(0, 40)}..."`); console.log(` Tags: ${post.tags.join(", ")}`); }); }); ``` **Output:** ```bash URL Params: [ [ 'limit', '3' ], [ 'tag', 'love' ], [ 'tag', 'history' ], [ 'tag', 'mystery' ] ] - "His mother had always taught him..." Tags: history, american, crime - "He was an expert but not in a discipline..." Tags: french, fiction, english - "Dave watched as the forest burned up on ..." Tags: magical, history, french ``` Notice the `tagTuples` conversion in the example above. **`appendUrlParams()` expects an array of [key, value] tuples, not an object.** This is what makes duplicate keys possible. An object like `{ tag: "love", tag: "history" }` would silently overwrite earlier values, leaving you with only the last one. Tuples don't have this limitation, so `tags.map((tag) => ["tag", tag])` produces `[["tag", "love"], ["tag", "history"], ["tag", "mystery"]]`, giving each tag its own entry in the query string. --- To set a single header on request, use `HttpClientRequest.setHeader()`. ```ts title="http.ts" {16} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchProducts() { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.get( "https://dummyjson.com/products", ).pipe( HttpClientRequest.setUrlParam("limit", "3"), HttpClientRequest.setHeader("X-Request-Source", "effect-course"), ); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchProducts()).then((data) => { data.products.forEach((product) => { console.log(` - ${product.title}: $${product.price}`); }); }); ``` **Output:** ```bash - Essence Mascara Lash Princess: $9.99 - Eyeshadow Palette with Mirror: $19.99 - Powder Canister: $14.99 ``` In the example above, we add a custom `X-Request-Source` header to our request. `setHeader` takes a key and a value, both strings. It appends the header to the request. If the header already exists, it replaces the previous value. --- To set several headers at once, use `HttpClientRequest.setHeaders()`. Instead of chaining multiple `setHeader` calls, you pass an object with all the headers you need. ```ts title="http.ts" {16-20} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchProducts() { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.get( "https://dummyjson.com/products", ).pipe( HttpClientRequest.setUrlParam("limit", "3"), HttpClientRequest.setHeaders({ "X-Request-Source": "effect-course", "X-Request-Version": "1.0", "Cache-Control": "no-cache", }), ); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchProducts()).then((data) => { data.products.forEach((product) => { console.log(` - ${product.title}: $${product.price}`); }); }); ``` **Output:** ```bash - Essence Mascara Lash Princess: $9.99 - Eyeshadow Palette with Mirror: $19.99 - Powder Canister: $14.99 ``` `setHeaders` takes an object where each key is a header name and each value is the header value. All headers are applied at once, replacing any existing headers with the same names. --- A common header you'll set on almost every API call is `Accept`, which tells the server what content type you expect in the response. `HttpClientRequest` provides a shorthand for this: ```ts title="http.ts" {16} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchProducts() { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.get( "https://dummyjson.com/products", ).pipe( HttpClientRequest.setUrlParam("limit", "3"), HttpClientRequest.accept("application/json"), ); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchProducts()).then((data) => { data.products.forEach((product) => { console.log(` - ${product.title}: $${product.price}`); }); }); ``` **Output:** ```bash - Essence Mascara Lash Princess: $9.99 - Eyeshadow Palette with Mirror: $19.99 - Powder Canister: $14.99 ``` `.accept("application/json")` is equivalent to `setHeader("accept", "application/json")`, just shorter and more expressive. For the very common case of requesting JSON, there's an even shorter version: `HttpClientRequest.acceptJson`. ```ts const request = HttpClientRequest.get("https://dummyjson.com/products").pipe( HttpClientRequest.acceptJson, ); ``` `acceptJson` is not a function call. It's a pre-built transform. You pass it directly to `.pipe()` without parentheses. --- **Bearer token authentication** is the most common auth scheme for modern APIs. The client includes a token — usually obtained by logging in or through an OAuth flow — in the `Authorization` header of every request. The server checks this token to verify who you are. The header format is `Authorization: Bearer `. `HttpClientRequest.bearerToken()` sets this header for you. In the example below, we first log in to get an access token, then use that token to fetch the authenticated user's profile. ```ts title="http.ts" {28} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchAuthenticatedUser() { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; // Step 1: Log in to get a token const loginRequest = HttpClientRequest.post( "https://dummyjson.com/auth/login", ).pipe( HttpClientRequest.bodyJsonUnsafe({ username: "emilys", password: "emilyspass", }), ); const loginResponse = yield* client.execute(loginRequest); const { accessToken } = yield* loginResponse.json; // Step 2: Use the token to fetch the current user's profile const meRequest = HttpClientRequest.get( "https://dummyjson.com/auth/me", ).pipe(HttpClientRequest.bearerToken(accessToken)); const meResponse = yield* client.execute(meRequest); const user = yield* meResponse.json; return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchAuthenticatedUser()).then((user) => { console.log("Authenticated user:", user.firstName, user.lastName); console.log("Email:", user.email); }); ``` **Output:** ```bash Authenticated user: Emily Johnson Email: emily.johnson@x.dummyjson.com ``` `bearerToken(token)` is equivalent to `setHeader("authorization", "Bearer " + token)`. It handles the formatting for you and keeps your code readable. --- **HTTP Basic Authentication** is one of the simplest authentication schemes defined in the HTTP specification. The client sends a username and password, combined and Base64-encoded, in the `Authorization` header. The header format is `Authorization: Basic `. Because the credentials are only encoded (not encrypted), Basic Auth should only be used over HTTPS. `HttpClientRequest.basicAuth()` handles the encoding for you: ```ts title="http.ts" {14} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchWithBasicAuth() { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.get( "https://httpbin.org/basic-auth/admin/secret123", ).pipe(HttpClientRequest.basicAuth("admin", "secret123")); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchWithBasicAuth()).then((data) => { console.log("Auth result:", data); }); ``` **Output:** ```bash Auth result: { authenticated: true, user: 'admin' } ``` `basicAuth(username, password)` Base64-encodes the credentials and sets the `Authorization` header to `Basic `. You never need to handle the encoding yourself. --- When working with tokens and passwords, you often want to prevent them from accidentally appearing in logs or debug output. Effect provides the `Redacted` type for this purpose. Both `bearerToken()` and `basicAuth()` accept `Redacted` values in addition to plain strings: ```ts title="http.ts" {28} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect, Redacted } from "effect"; function fetchAuthenticatedUser(token: Redacted.Redacted) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; // Logging the token won't reveal its value console.log("Token value (safe to log):", token); const request = HttpClientRequest.get("https://dummyjson.com/auth/me").pipe( // bearerToken accepts Redacted directly HttpClientRequest.bearerToken(token), ); const response = yield* client.execute(request); const user = yield* response.json; return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Create a Redacted value from a plain string const sensitiveToken = Redacted.make("your-secret-token-here"); // Test it Effect.runPromise(fetchAuthenticatedUser(sensitiveToken)).then( (user) => { console.log("User:", user.firstName, user.lastName); }, (error) => { console.log("Error (expected with a fake token):", error.message); }, ); ``` **Output:** ```bash Token value (safe to log): User: undefined undefined ``` Notice that logging the `Redacted` value prints `` instead of the actual token. The real value is still there internally — `bearerToken` and `basicAuth` unwrap it when building the header — but it's protected from accidental exposure in logs, error messages, and serialized output. You create a `Redacted` value with `Redacted.make(string)` and, when you truly need the underlying string, you can extract it with `Redacted.value(redacted)`. --- If you want to validate your request body with a Schema before sending it, you can use `HttpClientRequest.schemaBodyJson()`. ```ts title="http.ts" {22} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect, Schema } from "effect"; const AddRecipeBody = Schema.Struct({ name: Schema.String, ingredients: Schema.Array(Schema.String), prepTimeMinutes: Schema.Number, cookTimeMinutes: Schema.Number, servings: Schema.Number, }); function addRecipe(recipe: typeof AddRecipeBody.Type) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = yield* HttpClientRequest.post( "https://dummyjson.com/recipes/add", ).pipe(HttpClientRequest.schemaBodyJson(AddRecipeBody)(recipe)); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise( addRecipe({ name: "Masala Chai", ingredients: ["black tea", "milk", "ginger", "cardamom", "sugar"], prepTimeMinutes: 5, cookTimeMinutes: 10, servings: 2, }), ).then((data) => { console.log("Created recipe:", data); }); ``` **Output:** ```bash Created recipe: { id: 51, name: 'Masala Chai', ingredients: [ 'black tea', 'milk', 'ginger', 'cardamom', 'sugar' ], prepTimeMinutes: 5, cookTimeMinutes: 10, servings: 2 } ``` `schemaBodyJson` is a curried function. You first pass the schema, then the data: ```bash HttpClientRequest.schemaBodyJson(AddRecipeBody)(recipe); // ^^^^^^^^^^^^ ^^^^^^ // schema data ``` This returns an `Effect`, which is why **the request is created with `yield*`** instead of being assigned directly.. Note that the schema validates your data before it's serialized to JSON. If the data doesn't match, you get a `SchemaError` in the error channel. The request is never sent. This catches bugs at the point of construction rather than at the server. --- Every call to `response.json` in this course so far has returned `unknown`. This means TypeScript has no idea what shape the data is, so it can't warn you if you access a property that doesn't exist or if the API changes its response format. `HttpClientResponse.schemaBodyJson()` solves this by validating the response body against a Schema. If the response matches, you get a fully typed value. If it doesn't, you get a typed `SchemaError`. ```ts title="http.ts" {28} import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse, } from "effect/unstable/http"; import { Effect, Schema } from "effect"; const User = Schema.Struct({ id: Schema.Number, firstName: Schema.String, lastName: Schema.String, email: Schema.String, age: Schema.Number, }); function fetchUser(userId: number) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.get( `https://dummyjson.com/users/${userId}`, ); const response = yield* client.execute(request); // Validate the response body against the User schema const user = yield* HttpClientResponse.schemaBodyJson(User)(response); return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchUser(1)).then((user) => { // user is fully typed: { id: number, firstName: string, ... } console.log(`${user.firstName} ${user.lastName}, age ${user.age}`); console.log(`Email: ${user.email}`); }); ``` **Output:** ```bash Emily Johnson, age 29 Email: emily.johnson@x.dummyjson.com ``` `schemaBodyJson` is a curried function. You first pass the schema, then the response: ```bash HttpClientResponse.schemaBodyJson(User)(response); // ^^^^ ^^^^^^^^ // schema response ``` In the example above, the return type is now `{ id: number; firstName: string; lastName: string; email: string; age: number }` instead of `unknown`. TypeScript knows exactly what you're working with. Under the hood, `schemaBodyJson()` calls `response.json` to parse the body, then runs the schema validation. If validation fails, it produces a `SchemaError` in the error channel. Note that `SchemaError` is a schema validation failure, not an HTTP failure. This means it's a separate error type from `HttpClientError`, and you can catch them independently. **By default, schema validation strips unknown properties.** The dummyJSON API returns many more fields (like phone, image, address), but our schema only declares five fields, so those extras are silently dropped. This is a good thing. Your code only depends on the fields you've explicitly declared, making it resilient to upstream API changes. --- Some APIs return their response bodies as URL-encoded form data (`application/x-www-form-urlencoded`) instead of JSON. OAuth token endpoints are the most common example. Instead of returning `{"access_token": "abc123", "token_type": "bearer"}`, they return `access_token=abc123&token_type=bearer&expires_in=3600`. `HttpClientResponse.schemaBodyUrlParams` validates these URL-encoded response bodies against a Schema, just like `schemaBodyJson` does for JSON responses. ```ts title="http.ts" {12} import { HttpClientResponse } from "effect/unstable/http"; import { Schema } from "effect"; const TokenResponse = Schema.Struct({ access_token: Schema.String, token_type: Schema.String, expires_in: Schema.NumberFromString, }); // After executing a request to an OAuth token endpoint: const token = yield * HttpClientResponse.schemaBodyUrlParams(TokenResponse)(response); // token is fully typed: { access_token: string, token_type: string, expires_in: number } console.log(token.access_token); ``` `schemaBodyUrlParams` is curried, following the same pattern as `schemaBodyJson`: ```bash HttpClientResponse.schemaBodyUrlParams(TokenResponse)(response); // ^^^^^^^^^^^^ ^^^^^^^^ // schema response ``` Under the hood, `schemaBodyUrlParams()` reads the response body as URL-encoded params, then validates the key-value pairs against your schema. If a declared field is missing or doesn't match, you get a `SchemaError`. Notice `Schema.NumberFromString` for `expires_in`. URL-encoded data is always strings, so the raw value is `"3600"`. `NumberFromString` converts it to the number `3600` during validation. --- Some APIs return important metadata in response headers — pagination cursors, rate limit info, or cache tokens. You can validate these headers with `HttpClientResponse.schemaHeaders()`. ```ts title="http.ts" {9-13, 23-25} import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse, } from "effect/unstable/http"; import { Effect, Schema } from "effect"; // Define a schema for headers we care about const ResponseHeaders = Schema.Struct({ "content-type": Schema.String, "cache-control": Schema.String, }); function fetchAndInspectHeaders() { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.get("https://dummyjson.com/products/1"); const response = yield* client.execute(request); // Validate response headers against our schema const headers = yield* HttpClientResponse.schemaHeaders(ResponseHeaders)(response); console.log("Content-Type:", headers["content-type"]); console.log("Cache-Control:", headers["cache-control"]); const product = yield* response.json; return product; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchAndInspectHeaders()).then((product) => { console.log("Product:", product.title); }); ``` **Output:** ```bash Content-Type: application/json; charset=utf-8 Cache-Control: no-store Product: Essence Mascara Lash Princess ``` `schemaHeaders` works just like `schemaBodyJson`, but operates on the response headers instead of the body. You define a schema for the header keys you expect, and it validates them. If a declared header is missing or doesn't match, you get a `SchemaError`. Note that header names are always lowercased when accessed through `schemaHeaders`, so use lowercase keys in your schema (e.g., `"content-type"`, not `"Content-Type"`). This is because the HTTP specification treats header names as case-insensitive, and Effect normalizes them to lowercase for consistency. --- In the previous chapters, we validated the body, URL-encoded params, and headers independently. But sometimes the response's meaning depends on all three together. The status code determines the body shape, or you need typed values from both headers and the body. `HttpClientResponse.schemaJson()` validates the response body, status code, and headers as a single structure. You define one schema that describes all three, and the validation happens in one step. ```ts title="http.ts" {34} import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse, } from "effect/unstable/http"; import { Effect, Schema } from "effect"; // Define a schema that validates status, headers, and body together const UserResponse = Schema.Struct({ status: Schema.Literal(200), headers: Schema.Struct({ "content-type": Schema.String, }), body: Schema.Struct({ id: Schema.Number, firstName: Schema.String, lastName: Schema.String, email: Schema.String, }), }); function fetchUser(userId: number) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.get( `https://dummyjson.com/users/${userId}`, ); const response = yield* client.execute(request); // Validate status + headers + body in one step const result = yield* HttpClientResponse.schemaJson(UserResponse)(response); return result; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchUser(1)).then((result) => { console.log("Status:", result.status); console.log("Content-Type:", result.headers["content-type"]); console.log("User:", result.body.firstName, result.body.lastName); console.log("Email:", result.body.email); }); ``` **Output:** ```bash Status: 200 Content-Type: application/json; charset=utf-8 User: Emily Johnson Email: emily.johnson@x.dummyjson.com ``` `schemaJson` is a curried function, just like `schemaBodyJson`. You pass the schema first, then the response: ```bash HttpClientResponse.schemaJson(UserResponse)(response); // ^^^^^^^^^^^^ ^^^^^^^^ // schema response ``` Under the hood, `schemaJson` calls `response.json` to parse the body, then constructs an object with `{ status, headers, body }` and runs the schema validation against it. If any part doesn't match — wrong status code, missing header, or unexpected body shape, you get a `SchemaError`. The key difference from `schemaBodyJson` is scope. `schemaBodyJson` validates only the body. `schemaJson` validates the full response context. --- Some HTTP responses carry meaning entirely through their status code and headers, with no body at all. Examples include a `204 No Content` after a successful delete, a `304 Not Modified` with cache headers, or a `201 Created` with a `Location` header pointing to the new resource. `HttpClientResponse.schemaNoBody()` validates the status code and headers of these bodiless responses against a schema. It never reads the body. ```ts title="http.ts" {29} import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse, } from "effect/unstable/http"; import { Effect, Schema } from "effect"; // A schema for a successful delete response const DeleteResponse = Schema.Struct({ status: Schema.Literal(200), headers: Schema.Struct({ "content-type": Schema.String, }), }); function deleteProduct(productId: number) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.del( `https://dummyjson.com/products/${productId}`, ); const response = yield* client.execute(request); // Validate status + headers without reading the body const validated = yield* HttpClientResponse.schemaNoBody(DeleteResponse)(response); console.log("Status:", validated.status); console.log("Content-Type:", validated.headers["content-type"]); return validated; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(deleteProduct(1)).then( (result) => console.log("Delete confirmed with status", result.status), (error) => console.error("Validation failed:", error.message), ); ``` **Output:** ```bash Status: 200 Content-Type: application/json; charset=utf-8 Delete confirmed with status 200 ``` `schemaNoBody` constructs an object with `{ status, headers }` from the response and validates it against your schema. The body is never touched. This means it works correctly even on responses that have no body at all (where `response.json` would fail with an error). --- When making `POST`, `PUT`, or `PATCH` requests, you typically need to send data in the request body. The simplest way to send a JSON body is `HttpClientRequest.bodyJsonUnsafe()`. ```ts title="http.ts" {18} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function addProduct(product: { title: string; price: number; category: string; }) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.post( "https://dummyjson.com/products/add", ).pipe(HttpClientRequest.bodyJsonUnsafe(product)); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise( addProduct({ title: "Ergonomic Keyboard", price: 149, category: "electronics", }), ).then((data) => { console.log("Created product:", data); }); ``` **Output:** ```bash Created product: { id: 195, title: 'Ergonomic Keyboard', price: 149, category: 'electronics' } ``` `bodyJsonUnsafe` calls `JSON.stringify` internally and sets the `Content-Type` header to `application/json` for you. The word "unsafe" here doesn't mean dangerous. It means the serialization step is **not tracked in the type system**. If `JSON.stringify` were to fail at runtime (e.g., due to circular references in the data), the error would be an untracked exception rather than a typed Effect error. This is the most convenient option when when you _know_ the data is a simple, serializable object, like a hardcoded payload or a plain record you just constructed yourself. --- `HttpClientRequest.bodyJson()` does the same thing as `bodyJsonUnsafe`. It serializes your data to JSON, but it wraps the result in an Effect. This means serialization failures are captured as a typed `HttpBodyError` in the error channel. ```ts title="http.ts" {16} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function addPost(post: { title: string; body: string; userId: number }) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; // bodyJson returns Effect // so we need yield* to unwrap it const request = yield* HttpClientRequest.post( "https://dummyjson.com/posts/add", ).pipe(HttpClientRequest.bodyJson(post)); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise( addPost({ title: "Effect is awesome", body: "A deep dive into the Effect HTTP client module.", userId: 1, }), ).then((data) => { console.log("Created post:", data); }); ``` **Output:** ```bash Created post: { id: 252, title: 'Effect is awesome', body: 'A deep dive into the Effect HTTP client module.', userId: 1 } ``` Because `bodyJson` returns an `Effect` instead of a plain `HttpClientRequest`, we need `yield*` to unwrap it before passing it to `client.execute()`. Use `bodyJson` when you're dealing with data whose shape you don't fully control. User input, data from external sources, or any situation where you want maximum safety. --- `HttpClientRequest.schemaBodyJson()` adds a validation and transformation step before serialization. You define an Effect Schema that describes the shape of your request body, and the API ensures your data conforms to it before sending. ```ts title="http.ts" {22} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect, Schema } from "effect"; const AddRecipeBody = Schema.Struct({ name: Schema.String, ingredients: Schema.Array(Schema.String), prepTimeMinutes: Schema.Number, cookTimeMinutes: Schema.Number, servings: Schema.Number, }); function addRecipe(recipe: typeof AddRecipeBody.Type) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = yield* HttpClientRequest.post( "https://dummyjson.com/recipes/add", ).pipe(HttpClientRequest.schemaBodyJson(AddRecipeBody)(recipe)); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise( addRecipe({ name: "Masala Chai", ingredients: ["black tea", "milk", "ginger", "cardamom", "sugar"], prepTimeMinutes: 5, cookTimeMinutes: 10, servings: 2, }), ).then((data) => { console.log("Created recipe:", data); }); ``` **Output:** ```bash Created recipe: { id: 51, name: 'Masala Chai', ingredients: [ 'black tea', 'milk', 'ginger', 'cardamom', 'sugar' ], prepTimeMinutes: 5, cookTimeMinutes: 10, servings: 2 } ``` `schemaBodyJson` is a curried function. You first pass the schema, then the data: ```bash HttpClientRequest.schemaBodyJson(AddRecipeBody)(recipe); // ^^^^^^^^^^^^ ^^^^^^ // schema data ``` This returns an `Effect`, just like `bodyJson`, so you need `yield*` to unwrap it. --- Before we look at the code, let's understand what "form data" means at the HTTP level. When you fill out a form on a website and hit submit, the browser needs to pack up your inputs and send them to the server. There are two standard ways to do this, and they differ in how the data is encoded in the request body. ## URL-Encoded Form Data The simplest format is URL-encoded form data, also known by its content type: `application/x-www-form-urlencoded`. It encodes key-value pairs the same way URL query parameters work: keys and values are joined with `=`, pairs are separated by `&`, and special characters are percent-encoded. For example, a login form with a username and password gets encoded as: ```bash username=emilys&password=emilys%20pass ``` The `Content-Type` header is set to `application/x-www-form-urlencoded`. This format is compact and simple, but it only supports flat text values. You can't send files or binary data with it. ## Multipart Form Data The second format is **multipart** form data, also known by its content type: `multipart/form-data`. It's designed for more complex payloads, particularly ones that include files alongside regular text fields. Instead of encoding everything into a single string, multipart form data **splits the body into separate parts**, each with its own headers and content. A boundary string separates the parts. It looks something like this under the hood: ```bash --boundary123 Content-Disposition: form-data; name="username" emilys --boundary123 Content-Disposition: form-data; name="avatar"; filename="photo.png" Content-Type: image/png --boundary123-- ``` Each part has a name, and file parts include a filename and their own content type. This is how browsers send file uploads. The `` element always triggers multipart encoding. In modern JavaScript applications, you work with multipart data through the `FormData` API, which is available in both browsers and Node.js (v18+). You'll rarely construct the raw multipart body yourself. ## Which One to Use? Use **URL-encoded** (`bodyUrlParams`) for simple key-value data. Login forms, search queries, filter parameters. It's the lightest option when you're only sending text. Use **multipart** (`bodyFormData`) when you need to send files, or when the API explicitly expects `multipart/form-data`. --- `HttpClientRequest.bodyUrlParams()` sends data as URL-encoded form data (`application/x-www-form-urlencoded`). This is the same format browsers use for simple HTML forms. It's the right choice for login endpoints, search forms, or any API that expects key-value pairs. ```ts title="http.ts" {13-17} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function login(username: string, password: string) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.post("https://httpbin.org/post").pipe( HttpClientRequest.bodyUrlParams({ username, password, grant_type: "password", }), ); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(login("emilys", "secret123")).then((data) => { console.log("Content-Type sent:", data.headers["Content-Type"]); console.log("Form data received:", data.form); }); ``` **Output:** ```bash Content-Type sent: application/x-www-form-urlencoded Form data received: { grant_type: 'password', password: 'secret123', username: 'emilys' } ``` We're using `httpbin.org/post` here because it echoes back everything it receives: the headers, form data, files, and raw body. This lets us verify exactly what was sent. `bodyUrlParams` accepts the same input format as `setUrlParams`: an object, an array of tuples, or a `URLSearchParams` instance. It sets the `Content-Type` header to `application/x-www-form-urlencoded` automatically. --- `HttpClientRequest.bodyFormData()` sends a `FormData` object as the request body. The `Content-Type` is automatically set to `multipart/form-data` with an appropriate boundary string. This is the standard way to send form data in modern JavaScript, and it's what you need when the server expects multipart encoding, especially when files are involved. ```ts title="http.ts" {20} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function submitForm() { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; // Build a FormData object, just like you would in a browser const formData = new FormData(); formData.append("title", "Effect HTTP Guide"); formData.append("author", "Effect Team"); formData.append("tags", "typescript"); formData.append("tags", "effect"); const request = HttpClientRequest.post("https://httpbin.org/post").pipe( HttpClientRequest.bodyFormData(formData), ); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(submitForm()).then((data) => { console.log("Form data received:", data.form); }); ``` **Output:** ```bash Form data received: { author: 'Effect Team', tags: [ 'typescript', 'effect' ], title: 'Effect HTTP Guide' } ``` Notice that `formData.append` was called twice with the same key `"tags"`. Unlike an object (where duplicate keys would overwrite), `FormData` preserves all values, and the server receives them as an array. This is the same behavior as having multiple `` elements with the same `name` attribute in an HTML form. You construct the `FormData` using the standard Web API — `new FormData()`, `.append()`, `.set()`, etc. — and pass it directly to `bodyFormData`. The client handles the multipart encoding and boundary generation. --- Everything we've sent so far — JSON, URL-encoded forms, multipart text fields — has been text data. Text is human-readable, relatively small, and easy to work with. Files are different in several important ways, and understanding those differences will help you choose the right API. ## Binary Data A file on disk is a sequence of bytes — **binary data**. An image, a PDF, a zip archive, or a video are all binary. They aren't structured as key-value pairs or JSON objects. They're just raw bytes that only make sense to software that knows how to interpret them. Some files (like `.txt` or `.csv`) contain text, but even those are binary at the transport level. The HTTP client sends the raw bytes, and the server decides how to interpret them. ## Content-Type (MIME Type) When you send a file over HTTP, the server needs to know what kind of file it is. This is communicated through the `Content-Type` header, using a format called a **MIME type** (Multipurpose Internet Mail Extensions). Some common MIME types: - **`image/png`:** PNG image - **`image/jpeg`:** JPEG image - **`application/pdf`:** PDF document - **`application/octet-stream`:** generic binary (used when the specific type is unknown) - **`text/plain`:** plain text file - **`text/csv`:** CSV file When using `HttpClientRequest`'s file APIs, the content type is either auto-detected or specified by you. ## Streams Small files (a few KB) can be loaded entirely into memory and sent in one go. But large files — a 500MB video, a multi-gigabyte database dump — can't reasonably fit in memory all at once. Streaming solves this by reading and sending the file in small chunks. Instead of loading the whole file into a `Uint8Array`, you create a `Stream` that reads chunks on demand. The HTTP client sends each chunk as it arrives, keeping memory usage low regardless of file size. ## How Files Are Sent in HTTP There are several ways to include a file in an HTTP request: - **As the raw request body:** The file's bytes are the entire body. This is the simplest approach for single-file uploads. The `Content-Type` header indicates the file type. - **Inside multipart form data:** The file is one part of a multipart body, alongside other fields. This is the standard approach for HTML file upload forms, and it's what most API endpoints for file upload expect. - **As a Base64-encoded string in JSON:** Some APIs accept files encoded as text within a JSON payload. This increases size by ~33% but avoids multipart complexity. The `HttpClientRequest` module provides APIs for all of these approaches. --- The simplest way to send binary data is `HttpClientRequest.bodyUint8Array()`. It sets the request body to a raw byte array and optionally sets the `Content-Type` header. This is useful when you already have the file contents in memory as a `Uint8Array`, for example, after reading a file, generating data programmatically, or receiving bytes from another source. ```ts title="http.ts" {17} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function sendBinaryData() { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; // Create some binary data (in practice, this might come from a file) const encoder = new TextEncoder(); const bytes = encoder.encode("Hello from Effect!"); const request = HttpClientRequest.post("https://httpbin.org/post").pipe( HttpClientRequest.bodyUint8Array(bytes, "text/plain"), ); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(sendBinaryData()).then((data) => { console.log("Content-Type sent:", data.headers["Content-Type"]); console.log("Body received:", data.data); }); ``` **Output:** ```bash Content-Type sent: text/plain Body received: Hello from Effect! ``` `bodyUint8Array` takes two arguments: the byte array and an optional content type string. If you omit the content type, it defaults to `application/octet-stream` (generic binary). This API loads the entire payload into memory, so it's best for small-to-medium payloads. For large files, use streaming instead. --- `HttpClientRequest.bodyFile()` reads a file from the local filesystem and streams it as the request body. This is the most straightforward way to upload a file in a Node.js environment. ```ts title="http.ts" {17-19} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { NodeFileSystem } from "@effect/platform-node"; import { Effect } from "effect"; function uploadFile(filePath: string) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; // bodyFile reads the file and streams it as the request body const request = yield* HttpClientRequest.post( "https://httpbin.org/post", ).pipe( HttpClientRequest.bodyFile(filePath, { contentType: "text/plain", }), ); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe( Effect.provide(FetchHttpClient.layer), // bodyFile requires the FileSystem service Effect.provide(NodeFileSystem.layer), ); } // Test it (create a test file first) import { writeFileSync } from "node:fs"; writeFileSync("test-upload.txt", "Hello from a file!"); Effect.runPromise(uploadFile("test-upload.txt")).then((data) => { console.log("Body received:", data.data); }); ``` **Output:** ```bash Body received: Hello from a file! ``` `bodyFile` returns an Effect (not a plain request) because reading from the filesystem is an effectful operation that can fail. This is why we need `yield*` to unwrap it. It also requires the `FileSystem` service in the environment, which is why we provide `NodeFileSystem.layer`. The `contentType` option tells the server what kind of file you're sending. If you omit it, the client will try to detect the content type from the file extension. Under the hood, `bodyFile` streams the file rather than loading it entirely into memory. This means it works well with large files. Only a small buffer is held in memory at any time. --- Most real-world file upload APIs expect the file as part of a multipart form data body, not as the raw request body. This is because the server often needs additional fields alongside the file: a title, a description, access permissions, and so on. You can combine files and text fields using `FormData`: ```ts title="http.ts" {22} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function uploadAvatar(username: string) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; // Create a file (in a browser, this would come from ) const avatarFile = new File([""], "avatar.png", { type: "image/png", }); const formData = new FormData(); formData.append("username", username); formData.append("avatar", avatarFile); const request = HttpClientRequest.post("https://httpbin.org/post").pipe( HttpClientRequest.bodyFormData(formData), ); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(uploadAvatar("emilys")).then((data) => { console.log("Form fields:", data.form); console.log("Files:", Object.keys(data.files)); }); ``` **Output:** ```bash Form fields: { username: 'emilys' } Files: [ 'avatar' ] ``` The server receives both the text field (username) and the file (avatar) in a single request. The multipart encoding keeps them separate, each with their own content type and metadata. --- For large files, loading the entire content into memory isn't practical. `HttpClientRequest.bodyStream()` takes a `Stream` and sends it as the request body, reading and transmitting chunks incrementally. ```ts title="http.ts" {22-25} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect, Stream } from "effect"; function uploadLargeData() { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; // Create a stream that produces chunks of data // In practice, this might come from reading a large file const encoder = new TextEncoder(); const dataStream = Stream.fromIterable([ encoder.encode("chunk 1: Hello "), encoder.encode("chunk 2: from "), encoder.encode("chunk 3: a stream!"), ]); const request = HttpClientRequest.post("https://httpbin.org/post").pipe( HttpClientRequest.bodyStream(dataStream, { contentType: "text/plain", contentLength: 47, }), ); const response = yield* client.execute(request); const data = yield* response.json; return data; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(uploadLargeData()).then((data) => { console.log("Body received:", data.data); }); ``` **Output:** ```bash Body received: chunk 1: Hello chunk 2: from chunk 3: a stream! ``` `bodyStream` takes a `Stream` and an optional options object with `contentType` and `contentLength`. The content length is optional but recommended. Some servers reject requests without a `Content-Length` header, and others use it to show upload progress. The stream is consumed lazily. Each chunk is sent over the network as it's produced, so only one chunk needs to be in memory at a time. This makes it suitable for uploading files of any size. --- **By default, `HttpClient` does not throw an error for non-2xx status codes.** A 404 or 500 response is still a successful HTTP exchange. The server received your request and sent back a response. ```ts title="http.ts" import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchNonExistentUser() { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; // User 9999 doesn't exist. The API returns 404. const request = HttpClientRequest.get("https://dummyjson.com/users/9999"); const response = yield* client.execute(request); // This succeeds! The response object is available. console.log("Status:", response.status); const body = yield* response.json; console.log("Body:", body); return body; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchNonExistentUser()); ``` **Output:** ```bash Status: 404 Body: { message: "User with id '9999' not found" } ``` No error is thrown. The 404 response flows through like any other response. This gives you full control. You can inspect the status code and body, and decide how to handle it yourself. This is different from libraries like Axios, which throw by default on non-2xx responses. Effect's approach is more explicit: a response is always a response, and you opt in to treating certain status codes as errors. --- If you want non-2xx status codes to be treated as errors, use `filterStatusOk` on the client: ```ts title="http.ts" {12} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchUser(userId: number) { return Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( // All requests through this client will fail on non-2xx HttpClient.filterStatusOk, ); const request = HttpClientRequest.get( `https://dummyjson.com/users/${userId}`, ); const response = yield* client.execute(request); const user = yield* response.json; return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test with a valid user Effect.runPromise(fetchUser(1)).then( (user) => console.log("Found:", user.firstName), (error) => console.error("Error:", error.message), ); // Test with an invalid user Effect.runPromise(fetchUser(9999)).then( (user) => console.log("Found:", user.firstName), (error) => console.error("Error:", error.message), ); ``` **Output:** ```bash Error: StatusCode: non 2xx status code (404 GET https://dummyjson.com/users/9999) Found: Emily ``` When `filterStatusOk` rejects a response, it produces an `HttpClientError` with `reason` set to a `StatusCodeError`. The error includes both the original request and the response, so you have full context for debugging or recovery. You can also use `filterStatus` for more control. It takes a predicate that receives the status code: ```bash // Only accept 200 and 201 HttpClient.filterStatus((status) => status === 200 || status === 201); ``` --- When different status codes require different handling, use `HttpClientResponse.matchStatus()`. It lets you branch your logic based on exact status codes or status code ranges. ```ts title="http.ts" {19} import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchUser(userId: number) { return Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.get( `https://dummyjson.com/users/${userId}`, ); const response = yield* client.execute(request); return HttpClientResponse.matchStatus(response, { // Exact status code 200: (response) => Effect.gen(function* () { const user = yield* response.json; return `Found user: ${user.firstName} ${user.lastName}`; }), 404: () => Effect.succeed("User not found"), // Range matchers for status code classes "4xx": (response) => Effect.succeed(`Client error: ${response.status}`), "5xx": (response) => Effect.succeed(`Server error: ${response.status}`), // Catch-all for any other status orElse: (response) => Effect.succeed(`Unexpected status: ${response.status}`), }); }).pipe(Effect.flatten, Effect.provide(FetchHttpClient.layer)); } // Test with different user IDs Effect.runPromise(fetchUser(1)).then(console.log); Effect.runPromise(fetchUser(9999)).then(console.log); ``` **Output:** ```bash User not found Found user: Emily Johnson ``` In the example above, we use `Effect.flatten` because `matchStatus` is a plain function that returns whatever each branch returns, and our branches return Effects. These returned Effects sit inside the outer `Effect.gen`, which wraps them in another Effect layer, giving us `Effect>`. `Effect.flatten` unwraps one layer to give us the `Effect` we need. `matchStatus` checks cases in this order: exact status codes first (like 200, 404), then range matchers ("2xx", "3xx", "4xx", "5xx"), and finally orElse as the fallback. The `orElse` case is **required**. This ensures you always handle every possible status code, even unexpected ones. Exact codes take priority over ranges. In the example above, a 404 response hits the 404 case, not the "4xx" case. --- Both `filterStatusOk` and `filterStatus` only look at the status code, and they always produce an `HttpClientError`. But sometimes you want to filter on other properties of the response — a specific header value, a content type, or a combination of conditions — and produce your own custom error. `HttpClient.filterOrFail()` lets you do exactly that. It takes a predicate over the full response object and an error constructor. If the predicate returns `false`, the error you provide is placed in the error channel. ```ts title="http.ts" {18} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Data, Effect } from "effect"; class UnexpectedContentType extends Data.TaggedError("UnexpectedContentType")<{ readonly expected: string; readonly actual: string | undefined; }> {} function fetchJsonProduct(productId: number) { return Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.filterStatusOk, // Ensure the response is JSON before we try to parse it HttpClient.filterOrFail( (response) => response.headers["content-type"]?.includes("application/json") ?? false, (response) => new UnexpectedContentType({ expected: "application/json", actual: response.headers["content-type"], }), ), ); const request = HttpClientRequest.get( `https://dummyjson.com/products/${productId}`, ); const response = yield* client.execute(request); const product = yield* response.json; return product; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchJsonProduct(1)).then( (product) => console.log("Product:", product.title, `- $${product.price}`), (error) => { if (error._tag === "UnexpectedContentType") { console.error(`Expected ${error.expected}, got ${error.actual}`); } else { console.error("Error:", error.message); } }, ); ``` **Output:** ```bash Product: Essence Mascara Lash Princess - $9.99 ``` The first argument to `filterOrFail` is a predicate that receives the `HttpClientResponse`. If it returns `true`, the response passes through unchanged. If it returns `false`, the second argument — the error constructor — is called with the response, and the resulting error is placed in the error channel. Notice that the error type (`UnexpectedContentType`) is fully custom. It's not an `HttpClientError`. This lets you integrate response filtering into your application's own error hierarchy. `filterOrFail` is useful for hard validation: if the response doesn't meet your criteria, there's no recovery at the client level. The error propagates to the caller. --- `HttpClient.filterOrElse()` is the recovery-oriented counterpart to `filterOrFail`. Instead of producing an error when the predicate fails, it runs an alternative effect that can return a different response. This is useful when you want to transparently handle certain response conditions, like falling back to a cached response, retrying with different parameters, or transforming an unexpected response into an expected one. ```ts title="http.ts" {12} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchProductWithFallback(productId: number) { return Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( // If the response isn't a 200, fall back to product 1 HttpClient.filterOrElse( (response) => response.status === 200, (response) => Effect.gen(function* () { console.log( `Got status ${response.status}, falling back to product 1`, ); const fallbackClient = yield* HttpClient.HttpClient; return yield* fallbackClient.get( "https://dummyjson.com/products/1", ); }), ), ); const request = HttpClientRequest.get( `https://dummyjson.com/products/${productId}`, ); const response = yield* client.execute(request); const product = yield* response.json; return product; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test with a valid product Effect.runPromise(fetchProductWithFallback(1)).then((product) => { console.log("Product:", product.title); }); // Test with an invalid product — falls back to product 1 Effect.runPromise(fetchProductWithFallback(99999)).then((product) => { console.log("Product:", product.title); }); ``` **Output:** ```bash Product: Essence Mascara Lash Princess Got status 404, falling back to product 1 Product: Essence Mascara Lash Princess ``` The first argument is the same predicate as `filterOrFail`. The difference is the second argument: instead of an error constructor, it's a function that returns an `Effect`. This effect can do anything: make another request, return a cached response, or even succeed with the original response after logging. The key distinction between the two: - **`filterOrFail`:** Predicate fails → error in the error channel. The caller must handle it. - **`filterOrElse`:** Predicate fails → alternative effect runs. The caller doesn't know the filter was triggered. Use `filterOrFail` when a bad response is an error your application needs to know about. Use `filterOrElse` when you can transparently recover and the caller doesn't need to care. --- When working with `HttpClient`, you'll encounter a small set of well-defined error types. Understanding them is essential for writing robust error handling code. ## HttpClientError `HttpClientError` is the single error class for all HTTP client errors. Every error from the client is an `HttpClientError` with `_tag: "HttpClientError"`. What varies is the `reason`, which is a union of six tagged types, split into two categories: **request errors** (failures before the server responds) and **response errors** (failures after the server responds). You can check whether an unknown value is an `HttpClientError` using the `isHttpClientError` guard: ```ts import { HttpClientError } from "effect/unstable/http"; HttpClientError.isHttpClientError(someValue); // true or false ``` ## Request Errors Request errors occur **before the server sends a response**. The request either couldn't be built or couldn't be sent. - **`TransportError`:** A network-level failure. The connection timed out, DNS resolution failed, the server refused the connection, or the network is unreachable. - **`EncodeError`:** The request body couldn't be serialized. This typically happens if `bodyJson` encounters data that `JSON.stringify` can't handle. - **`InvalidUrlError`:** The URL couldn't be parsed into a valid URL object. Every request error includes the original request object, so you always know which request failed. ```ts title="http.ts" import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; const program = Effect.gen(function* () { const client = yield* HttpClient.HttpClient; // This will fail with a TransportError (invalid host) const request = HttpClientRequest.get("https://this-does-not-exist.invalid"); const response = yield* client.execute(request); return yield* response.json; }).pipe( Effect.catch((error) => { console.log("Tag:", error._tag); console.log("Reason:", error.reason._tag); console.log("Request:", error.reason.methodAndUrl); console.log("Message:", error.reason.message); return Effect.void; }), Effect.provide(FetchHttpClient.layer), ); // Test it Effect.runPromise(program); ``` **Output:** ```bash Tag: HttpClientError Reason: TransportError Request: GET https://this-does-not-exist.invalid Message: Transport error (GET https://this-does-not-exist.invalid) ``` Notice the structure. The outer `error._tag` is always `"HttpClientError"`. The `error.reason._tag` tells you the specific failure type. Properties like `methodAndUrl` and `message` live on the `reason` object. ## Response Errors Response errors occur **after the server sends a response** but something went wrong when processing it. It has a reason field with these possible values: - **`StatusCodeError`:** The response came back with a status code your code considers unacceptable. For example, a `404` or `500`. This error is produced when you explicitly opt in to status code checking using `filterStatusOk`, `filterStatus`, or similar filters, which are covered in a later chapter. - **`DecodeError`:** The response body couldn't be parsed. For example, calling `response.json` on a response that isn't valid JSON. - **`EmptyBodyError`:** You tried to read a body that doesn't exist (e.g., a 204 No Content response). Every response error includes both the original request and the response, giving you full context. ```ts title="http.ts" import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; const program = Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe(HttpClient.filterStatusOk); // This returns a 404, which filterStatusOk turns into a StatusCodeError const request = HttpClientRequest.get("https://dummyjson.com/users/9999"); const response = yield* client.execute(request); return yield* response.json; }).pipe( Effect.catch((error) => { console.log("Tag:", error._tag); console.log("Reason:", error.reason._tag); if (error.response) { console.log("Status:", error.response.status); } console.log("Request:", error.reason.methodAndUrl); console.log("Message:", error.reason.message); return Effect.void; }), Effect.provide(FetchHttpClient.layer), ); // Test it Effect.runPromise(program); ``` **Output:** ```bash Tag: HttpClientError Reason: StatusCodeError Status: 404 Request: GET https://dummyjson.com/users/9999 Message: StatusCode: non 2xx status code (404 GET https://dummyjson.com/users/9999) ``` ## SchemaError `SchemaError` comes from Effect's `Schema` module, not from `HttpClient` itself. You'll encounter it when using schema-based validation like `HttpClientResponse.schemaBodyJson()` or `HttpClientResponse.schemaHeaders()`. When the response body or headers don't match your schema, the validation step fails with a `SchemaError`. This error is separate from `HttpClientError`. It's a schema validation failure, not an HTTP failure. ```ts title="http.ts" import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse, } from "effect/unstable/http"; import { Effect, Schema } from "effect"; // A schema that expects fields the API doesn't return const WrongSchema = Schema.Struct({ nonExistentField: Schema.String, }); const program = Effect.gen(function* () { const client = yield* HttpClient.HttpClient; const request = HttpClientRequest.get("https://dummyjson.com/users/1"); const response = yield* client.execute(request); // This will fail because the response doesn't match our schema const data = yield* HttpClientResponse.schemaBodyJson(WrongSchema)(response); return data; }).pipe( Effect.catch((error) => { console.log("Tag:", error._tag); console.log("Message:", error.message); return Effect.void; }), Effect.provide(FetchHttpClient.layer), ); // Test it Effect.runPromise(program); ``` **Output:** ```bash Tag: SchemaError Message: Missing key at ["nonExistentField"] ``` --- `HttpClient.catch()` intercepts every error from the client and lets you handle it. You can recover by returning an alternative response, or re-fail with a different error type. In the example below, we catch all errors from the client and re-fail with a domain-specific `UserFetchError`: ```ts title="http.ts" {20} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Data, Effect } from "effect"; class UserFetchError extends Data.TaggedError("UserFetchError")<{ readonly userId: number; }> { get message() { return `Failed to fetch user ${this.userId}`; } } function fetchUser(userId: number) { return Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.filterStatusOk, HttpClient.catch((error) => { return Effect.fail(new UserFetchError({ userId })); }), ); const request = HttpClientRequest.get( `https://dummyjson.com/users/${userId}`, ); const response = yield* client.execute(request); const user = yield* response.json; return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test with a valid user Effect.runPromise(fetchUser(1)).then( (user) => console.log("User:", user.firstName, user.lastName), (error) => console.error(`[${error._tag}] ${error.message}`), ); // Test with an invalid user Effect.runPromise(fetchUser(9999)).then( (user) => console.log("User:", user.firstName, user.lastName), (error) => console.error(`[${error._tag}] ${error.message}`), ); ``` **Output:** ```bash [UserFetchError] Failed to fetch user 9999 User: Emily Johnson ``` `HttpClient.catch` transforms the client itself. Every request made through the resulting client will have this error handling applied. The callback receives the error and returns an Effect. You can recover by returning a replacement response, or re-fail with a different error type, as we do here by mapping `HttpClientError` to a domain-specific `UserFetchError`. --- `HttpClient.catchTag()` catches only errors with a specific `_tag`, letting other error types pass through. This is useful when your client's error channel contains multiple error types. For example, if you use schema validation on responses, the error channel includes both `HttpClientError` (from the HTTP request) and `SchemaError` (from validation). `catchTag` lets you recover from one while letting the other propagate. ```ts title="http.ts" {21} import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse, } from "effect/unstable/http"; import { Effect, Schema } from "effect"; const User = Schema.Struct({ id: Schema.Number, firstName: Schema.String, lastName: Schema.String, }); function fetchUser(userId: number) { return Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.filterStatusOk, // Only catch HttpClientError (network failures, bad status codes, etc.) // SchemaError from validation is NOT caught — it will still propagate HttpClient.catchTag("HttpClientError", (error) => Effect.gen(function* () { console.log(`HTTP error: ${error.message}`); console.log("Falling back to default user..."); const fallbackClient = yield* HttpClient.HttpClient; return yield* fallbackClient.get("https://dummyjson.com/users/1"); }), ), ); const request = HttpClientRequest.get( `https://dummyjson.com/users/${userId}`, ); const response = yield* client.execute(request); // This can fail with SchemaError, which is NOT caught by catchTag above const user = yield* HttpClientResponse.schemaBodyJson(User)(response); return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test with an invalid user — HttpClientError is caught, fallback is used Effect.runPromise(fetchUser(9999)).then( (user) => console.log("User:", user.firstName, user.lastName), (error) => console.error(`[${error._tag}] ${error.message}`), ); ``` **Output:** ```bash HTTP error: StatusCode: non 2xx status code (404 GET https://dummyjson.com/users/9999) Falling back to default user... User: Emily Johnson ``` All HTTP client errors share a single type: `HttpClientError` (with `_tag: "HttpClientError"`). The specific failure kind — transport error, status code error, decode error, etc. — is in the `error.reason._tag` field. This means `catchTag("HttpClientError", ...)` catches all HTTP-related errors. The power of `catchTag` shows when other error types are in the channel. In this example, a `SchemaError` from `schemaBodyJson` would bypass the `catchTag` handler entirely and propagate to the caller. This lets you be precise: recover from HTTP failures (server down, bad status code) while still surfacing data integrity issues (unexpected response shape) as errors that need attention. If your client only produces `HttpClientError` and you want to catch everything, `HttpClient.catch` is simpler. Reach for `catchTag` when multiple error types are in play and you need selective recovery. --- `HttpClient.catchTags()` handles multiple error types in a single call, with a separate handler for each `_tag`. This is the cleanest option when your client's error channel contains several error types and you want distinct recovery strategies for each. ```ts title="http.ts" {19} import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse, } from "effect/unstable/http"; import { Effect, Schema } from "effect"; const User = Schema.Struct({ id: Schema.Number, firstName: Schema.String, lastName: Schema.String, }); function fetchUser(userId: number) { return Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.filterStatusOk, HttpClient.catchTags({ HttpClientError: (error) => Effect.gen(function* () { console.log(`HTTP error: ${error.message}`); console.log("Falling back to default user..."); const fallbackClient = yield* HttpClient.HttpClient; return yield* fallbackClient.get("https://dummyjson.com/users/1"); }), }), ); const request = HttpClientRequest.get( `https://dummyjson.com/users/${userId}`, ); const response = yield* client.execute(request); const user = yield* HttpClientResponse.schemaBodyJson(User)(response); return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test with an invalid user — HttpClientError is caught, fallback is used Effect.runPromise(fetchUser(9999)).then( (user) => console.log("User:", user.firstName, user.lastName), (error) => console.error(`[${error._tag}] ${error.message}`), ); ``` **Output:** ```bash HTTP error: StatusCode: non 2xx status code (404 GET https://dummyjson.com/users/9999) Falling back to default user... User: Emily Johnson ``` `catchTags` takes an object where each key is a `_tag` value and each value is a handler function. You don't need to handle every possible tag, only the ones you list. Unhandled tags remain in the error channel. In this example, `HttpClientError` is caught and recovered with a fallback request. But `SchemaError` (from `schemaBodyJson`) is not listed, so it would propagate to the caller if the response shape doesn't match the schema. `catchTags` shines when you have three or more error types in the channel and want to handle each one differently in a single, readable block. If you only need to catch one specific tag, `catchTag` is simpler. If you want to catch everything, use `catch`. --- Sometimes you don't want to recover from an error. You just want to log it, send it to an error tracking service, increment a metric, then let it continue propagating. `HttpClient.tapError()` runs a side effect when an error occurs, without changing the error or preventing it from propagating. ```ts title="http.ts" {12} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect } from "effect"; function fetchUserWithErrorTracking(userId: number) { return Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.filterStatusOk, HttpClient.tapError((error) => Effect.sync(() => { // Simulate sending to an error tracking service console.log("[ErrorTracker] Reported:", error._tag, error.message); }), ), ); const request = HttpClientRequest.get( `https://dummyjson.com/users/${userId}`, ); const response = yield* client.execute(request); const user = yield* response.json; return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test with an invalid user — error is tracked, then still propagates Effect.runPromise(fetchUserWithErrorTracking(9999)).then( (user) => console.log("User:", user.firstName), (error) => console.log("[Main] Unhandled error:", error.message), ); ``` **Output:** ```bash [ErrorTracker] Reported: HttpClientError StatusCode: non 2xx status code (404 GET https://dummyjson.com/users/9999) [Main] Unhandled error: StatusCode: non 2xx status code (404 GET https://dummyjson.com/users/9999) ``` Notice both lines print. The `tapError` callback runs first, then the error continues to propagate. It's not swallowed. `tapError` is particularly useful for observability. You can add it to a client once, and every request through that client will have its errors observed without affecting the error handling strategy of the calling code. --- By default, `HttpClient` doesn't track cookies between requests. Each request is independent. If you need cookie persistence — for example, to maintain a session after logging in — you can use `HttpClient.withCookiesRef()`. `withCookiesRef` associates a `Ref` with the client. The client will automatically extract `Set-Cookie` headers from responses and include the stored cookies in subsequent requests. ```ts title="http.ts" {12, 15, 31} import { FetchHttpClient, HttpClient, HttpClientRequest, Cookies, } from "effect/unstable/http"; import { Effect, Ref } from "effect"; function sessionExample() { return Effect.gen(function* () { // Create a mutable Ref to hold cookies const cookieRef = yield* Ref.make(Cookies.empty); const client = (yield* HttpClient.HttpClient).pipe( HttpClient.withCookiesRef(cookieRef), ); // Step 1: Log in — the server sets session cookies const loginRequest = HttpClientRequest.post( "https://dummyjson.com/auth/login", ).pipe( HttpClientRequest.bodyJsonUnsafe({ username: "emilys", password: "emilyspass", }), ); yield* client.execute(loginRequest); // Step 2: Check what cookies were stored const cookies = yield* Ref.get(cookieRef); console.log("Stored cookies:", cookies); // Step 3: Subsequent requests automatically include the cookies const meResponse = yield* client.get("https://dummyjson.com/auth/me"); const user = yield* meResponse.json; return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(sessionExample()).then( (user) => console.log("User:", user.firstName, user.lastName), (error) => console.error("Error:", error), ); ``` **Output:** ```bash Stored cookies: { _id: 'effect/Cookies', cookies: { accessToken: { _id: 'effect/Cookies/Cookie', name: 'accessToken', value: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJlbWlseXMiLCJlbWFpbCI6ImVtaWx5LmpvaG5zb25AeC5kdW1teWpzb24uY29tIiwiZmlyc3ROYW1lIjoiRW1pbHkiLCJsYXN0TmFtZSI6IkpvaG5zb24iLCJnZW5kZXIiOiJmZW1hbGUiLCJpbWFnZSI6Imh0dHBzOi8vZHVtbXlqc29uLmNvbS9pY29uL2VtaWx5cy8xMjgiLCJpYXQiOjE3NzE1ODEzMTAsImV4cCI6MTc3MTU4NDkxMH0.oP3Sgp0kDaJx1YIK7RWSd6R5vOeVsxZn_VQhKMrJYdw', options: [Object] }, refreshToken: { _id: 'effect/Cookies/Cookie', name: 'refreshToken', value: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJlbWlseXMiLCJlbWFpbCI6ImVtaWx5LmpvaG5zb25AeC5kdW1teWpzb24uY29tIiwiZmlyc3ROYW1lIjoiRW1pbHkiLCJsYXN0TmFtZSI6IkpvaG5zb24iLCJnZW5kZXIiOiJmZW1hbGUiLCJpbWFnZSI6Imh0dHBzOi8vZHVtbXlqc29uLmNvbS9pY29uL2VtaWx5cy8xMjgiLCJpYXQiOjE3NzE1ODEzMTAsImV4cCI6MTc3NDE3MzMxMH0.xk7nJYPVBFoCYKuyEJSE3k4m8soWgHvJ0z_uuvpYgKU', options: [Object] } } } User: Emily Johnson ``` Here's how the flow works: 1. You create a `Ref` initialized with `Cookies.empty`. 2. You attach it to the client with `withCookiesRef`. 3. When a response includes `Set-Cookie` headers, the client automatically parses them and stores them in the `Ref`. 4. On every subsequent request, the client reads the `Ref` and attaches the stored cookies as a `Cookie` header. The `Ref` is mutable and shared. If you use the same `Ref` with multiple clients (or the same client across multiple requests), they all share the same cookie jar. You can also inspect or modify the cookies at any time using `Ref.get` and `Ref.set`. This is useful for debugging or for manually injecting cookies that weren't set by a server response. --- Network requests can fail for transient reasons: a brief network hiccup, a server restart, or a rate limit. Rather than failing immediately, you can retry the request using `HttpClient.retry()`. `retry` takes a Schedule that defines the retry behavior: how many times, how long to wait between attempts, and whether to apply backoff. ```ts title="http.ts" {13-17} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect, Schedule } from "effect"; function fetchWithRetry(userId: number) { return Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.filterStatusOk, // Retry up to 3 times with exponential backoff HttpClient.retry( Schedule.exponential("500 millis").pipe( Schedule.compose(Schedule.recurs(3)), ), ), ); const request = HttpClientRequest.get( `https://dummyjson.com/users/${userId}`, ); const response = yield* client.execute(request); const user = yield* response.json; return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test with a valid user Effect.runPromise(fetchWithRetry(1)).then( (user) => console.log("User:", user.firstName, user.lastName), (error) => console.error("Failed after retries:", error.message), ); ``` In this example, if a request fails, it retries up to 3 times with exponential backoff starting at 500ms (500ms, 1s, 2s). After all retries are exhausted, the original error propagates. You can also pass an options object for more control: ```ts HttpClient.retry({ times: 3, schedule: Schedule.exponential("1 second"), }); ``` The `times` option caps the total number of retries, and schedule controls the delay between them. `retry` applies to all errors from the client. If you have `filterStatusOk` enabled, a 404 will be retried too. To retry only specific errors, combine `retry` with a while predicate: ```ts HttpClient.retry({ times: 3, while: (error) => error._tag === "RequestError" && error.reason._tag === "TransportError", }); ``` This retries only transport-level failures (network errors), not status code errors. --- `HttpClient.retryTransient()` is a purpose-built retry combinator for the most common case: retrying requests that fail due to temporary issues like network errors, timeouts, or rate limiting. ```ts title="http.ts" {12-15} import { FetchHttpClient, HttpClient, HttpClientRequest, } from "effect/unstable/http"; import { Effect, Schedule } from "effect"; function fetchWithTransientRetry(userId: number) { return Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.filterStatusOk, HttpClient.retryTransient({ times: 3, schedule: Schedule.exponential("500 millis"), }), ); const request = HttpClientRequest.get( `https://dummyjson.com/users/${userId}`, ); const response = yield* client.execute(request); const user = yield* response.json; return user; }).pipe(Effect.provide(FetchHttpClient.layer)); } // Test it Effect.runPromise(fetchWithTransientRetry(1)).then( (user) => console.log("User:", user.firstName, user.lastName), (error) => console.error("Failed after retries:", error.message), ); ``` **Output:** ```bash User: Emily Johnson ``` Unlike `retry`, which retries on all errors, `retryTransient` only retries errors that are classified as transient. Specifically, it retries when: - The error is a **`TimeoutException`** (from `Effect.timeout`) - The error is an **`HttpClientError`** with a **`TransportError`** reason (network failures like DNS resolution, connection refused, etc.) - The error is an **`HttpClientError`** with a **`StatusCodeError`** reason where the status code is **408** (Request Timeout), **429** (Too Many Requests), **500** (Internal Server Error), **502** (Bad Gateway), **503** (Service Unavailable), or **504** (Gateway Timeout) A `404` or `400` won't be retried because those aren't transient. Retrying them would give the same result. You can also pass just a `Schedule` directly: ```ts HttpClient.retryTransient( Schedule.exponential("1 second").pipe(Schedule.compose(Schedule.recurs(5))), ); ``` The `mode` option lets you control what the schedule receives as input. By default, it receives both errors and responses. You can narrow this: ```ts // Only consider errors for scheduling (ignore response status) HttpClient.retryTransient({ mode: "errors-only", times: 3, schedule: Schedule.exponential("500 millis"), }); // Only consider response status for scheduling (ignore errors) HttpClient.retryTransient({ mode: "response-only", times: 3, schedule: Schedule.exponential("500 millis"), }); ``` If you have additional error types that should be considered transient, use the `while` predicate: ```ts HttpClient.retryTransient({ times: 3, while: (error) => error._tag === "TransportError", }); ``` The `while` predicate is checked in addition to the built-in transient checks. It lets you widen the set of retryable errors without replacing the defaults. For most applications, `retryTransient` with a `schedule` and a `times` cap is the right default. It handles the common failure modes — network blips, rate limits, server hiccups, and timeouts — without retrying errors that can't be fixed by waiting. --- Hope you found this course useful! We covered roughly 75–80% of Effect's HttpClient API. As I discover and use more APIs in real projects, I'll add new chapters to this course. Thanks for following along, and see you in the next course!

Stay in the loop