HTTP Client

The HttpClient module provides a functional, composable API for making HTTP requests. It supports middleware, retries, rate limiting, and seamless integration with Effect’s error handling.

Overview

HttpClient is designed to be:

Composable: Chain transformations and middleware using pipes
Type-safe: Full TypeScript support with precise error types
Resilient: Built-in retry logic and error handling
Testable: Easy to mock and test with dependency injection

Basic Usage

Making Requests

The client provides convenience methods for common HTTP methods:

import { HttpClient } from "effect/unstable/http"
import { Effect } from "effect"

const program = Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient
  
  // GET request
  const response = yield* client.get("https://api.example.com/users")
  
  // POST request with options
  const created = yield* client.post("https://api.example.com/users", {
    body: HttpBody.json({ name: "Alice", email: "alice@example.com" })
  })
})

Processing Responses

Use HttpClientResponse helpers to decode response bodies:

import { HttpClient, HttpClientResponse } from "effect/unstable/http"
import { Effect, Schema } from "effect"

class User extends Schema.Class<User>("User")({
  id: Schema.Number,
  name: Schema.String,
  email: Schema.String
}) {}

const getUser = (id: number) =>
  HttpClient.get(`https://api.example.com/users/${id}`).pipe(
    Effect.flatMap(HttpClientResponse.schemaBodyJson(User))
  )

Client Configuration

Base URL and Headers

Apply common settings to all requests:

import { HttpClient, HttpClientRequest } from "effect/unstable/http"
import { flow } from "effect"

const client = HttpClient.HttpClient.pipe(
  HttpClient.mapRequest(flow(
    HttpClientRequest.prependUrl("https://api.example.com"),
    HttpClientRequest.setHeader("Authorization", "Bearer token"),
    HttpClientRequest.acceptJson
  ))
)

Filtering Responses

Ensure successful status codes:

const client = HttpClient.HttpClient.pipe(
  HttpClient.filterStatusOk  // Only accept 2xx responses
)

// Custom status filtering
const clientWith404 = HttpClient.HttpClient.pipe(
  HttpClient.filterStatus(status => status === 200 || status === 404)
)

Error Handling

Retry Logic

Automatically retry transient failures:

import { HttpClient, Schedule } from "effect"

const resilientClient = HttpClient.HttpClient.pipe(
  HttpClient.filterStatusOk,
  HttpClient.retryTransient({
    schedule: Schedule.exponential(100),
    times: 3
  })
)

The retryTransient method automatically retries:

Network errors
Timeout errors
5xx server errors
429 rate limit errors

Error Recovery

Handle specific error types:

const client = HttpClient.HttpClient.pipe(
  HttpClient.catchTag("StatusCodeError", (error) =>
    Effect.succeed(HttpClientResponse.empty({ status: 200 }))
  )
)

Rate Limiting

Protect APIs with built-in rate limiting:

import { HttpClient } from "effect/unstable/http"
import { RateLimiter } from "effect/unstable/persistence"

const rateLimitedClient = HttpClient.HttpClient.pipe(
  HttpClient.withRateLimiter({
    limiter: RateLimiter.RateLimiter,
    window: "1 minute",
    limit: 60,
    key: "api-key",
    algorithm: "token-bucket"
  })
)

The rate limiter:

Automatically reads rate limit headers from responses
Respects Retry-After headers
Supports per-endpoint or per-user limits
Handles 429 responses automatically

Middleware

Request Transformation

Transform requests before sending:

const client = HttpClient.HttpClient.pipe(
  HttpClient.mapRequest((request) =>
    HttpClientRequest.setHeader(request, "X-Request-ID", crypto.randomUUID())
  )
)

Response Transformation

Process all responses:

const client = HttpClient.HttpClient.pipe(
  HttpClient.tap((response) =>
    Effect.log(`Request completed: ${response.status}`)
  )
)

Manage cookies across requests:

import { HttpClient, Cookies } from "effect/unstable/http"
import { Ref } from "effect"

const program = Effect.gen(function* () {
  const cookieRef = yield* Ref.make(Cookies.empty)
  
  const client = HttpClient.HttpClient.pipe(
    HttpClient.withCookiesRef(cookieRef)
  )
  
  // Cookies are automatically sent and stored
  yield* client.get("https://api.example.com/login")
  yield* client.get("https://api.example.com/profile")
})

Real-World Example

Here’s a complete service using HttpClient:

import { Effect, Layer, Schedule, Schema, ServiceMap } from "effect"
import { 
  FetchHttpClient, 
  HttpClient, 
  HttpClientRequest, 
  HttpClientResponse 
} from "effect/unstable/http"
import { flow } from "effect"

class Todo extends Schema.Class<Todo>("Todo")({
  userId: Schema.Number,
  id: Schema.Number,
  title: Schema.String,
  completed: Schema.Boolean
}) {}

export class JsonPlaceholder extends ServiceMap.Service<JsonPlaceholder, {
  readonly allTodos: Effect.Effect<ReadonlyArray<Todo>, JsonPlaceholderError>
  getTodo(id: number): Effect.Effect<Todo, JsonPlaceholderError>
  createTodo(todo: Omit<Todo, "id">): Effect.Effect<Todo, JsonPlaceholderError>
}>()("app/JsonPlaceholder") {
  static readonly layer = Layer.effect(
    JsonPlaceholder,
    Effect.gen(function*() {
      // Configure client with common middleware
      const client = (yield* HttpClient.HttpClient).pipe(
        HttpClient.mapRequest(flow(
          HttpClientRequest.prependUrl("https://jsonplaceholder.typicode.com"),
          HttpClientRequest.acceptJson
        )),
        HttpClient.filterStatusOk,
        HttpClient.retryTransient({
          schedule: Schedule.exponential(100),
          times: 3
        })
      )

      const allTodos = client.get("/todos").pipe(
        Effect.flatMap(HttpClientResponse.schemaBodyJson(Schema.Array(Todo))),
        Effect.mapError((cause) => new JsonPlaceholderError({ cause })),
        Effect.withSpan("JsonPlaceholder.allTodos")
      )

      const getTodo = Effect.fn("JsonPlaceholder.getTodo")(function*(id: number) {
        yield* Effect.annotateCurrentSpan({ id })
        
        const todo = yield* client.get(`/todos/${id}`, {
          urlParams: { format: "json" }
        }).pipe(
          Effect.flatMap(HttpClientResponse.schemaBodyJson(Todo)),
          Effect.mapError((cause) => new JsonPlaceholderError({ cause }))
        )
        
        return todo
      })

      const createTodo = Effect.fn("JsonPlaceholder.createTodo")(function*(todo: Omit<Todo, "id">) {
        yield* Effect.annotateCurrentSpan({ title: todo.title })
        
        const createdTodo = yield* HttpClientRequest.post("/todos").pipe(
          HttpClientRequest.setUrlParams({ format: "json" }),
          HttpClientRequest.bodyJsonUnsafe(todo),
          client.execute,
          Effect.flatMap(HttpClientResponse.schemaBodyJson(Todo)),
          Effect.mapError((cause) => new JsonPlaceholderError({ cause }))
        )
        
        return createdTodo
      })

      return JsonPlaceholder.of({
        allTodos,
        getTodo,
        createTodo
      })
    })
  ).pipe(
    Layer.provide(FetchHttpClient.layer)
  )
}

export class JsonPlaceholderError extends Schema.TaggedErrorClass<JsonPlaceholderError>()("JsonPlaceholderError", {
  cause: Schema.Defect
}) {}

Testing

Create test clients easily:

import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
import { Effect } from "effect"

const mockClient = HttpClient.make((request, url, signal, fiber) =>
  Effect.succeed(
    HttpClientResponse.fromWeb(
      request,
      new Response(JSON.stringify({ id: 1, name: "Test" }))
    )
  )
)

const testLayer = Layer.succeed(HttpClient.HttpClient, mockClient)

API Reference

Core Methods

get(url, options?) - Make a GET request
post(url, options?) - Make a POST request
put(url, options?) - Make a PUT request
patch(url, options?) - Make a PATCH request
del(url, options?) - Make a DELETE request
head(url, options?) - Make a HEAD request
options(url, options?) - Make an OPTIONS request
execute(request) - Execute a custom request

Transformations

mapRequest(fn) - Transform requests
mapRequestEffect(fn) - Transform requests with effects
transformResponse(fn) - Transform responses
tap(fn) - Side effect on success
tapError(fn) - Side effect on error

Error Handling

catch(fn) - Catch all errors
catchTag(tag, fn) - Catch specific error types
retry(policy) - Retry with custom policy
retryTransient(options) - Retry transient errors

Filters

filterStatus(fn) - Filter by status code
filterStatusOk - Only accept 2xx responses
filterOrElse(predicate, fn) - Filter with fallback

Get Started

Core Concepts

Guides

HTTP

Data & Persistence

AI & LLM

Advanced

Migration

Overview

Basic Usage

Making Requests

Processing Responses

Client Configuration

Base URL and Headers

Filtering Responses

Error Handling

Retry Logic

Error Recovery

Rate Limiting

Middleware

Request Transformation

Response Transformation

Real-World Example

Testing

API Reference

Core Methods

Transformations

Error Handling

Filters

See Also

Get Started

Core Concepts

Guides

HTTP

Data & Persistence

AI & LLM

Advanced

Migration

Documentation Index

​Overview

​Basic Usage

​Making Requests

​Processing Responses

​Client Configuration

​Base URL and Headers

​Filtering Responses

​Error Handling

​Retry Logic

​Error Recovery

​Rate Limiting

​Middleware

​Request Transformation

​Response Transformation

​Cookie Management

​Real-World Example

​Testing

​API Reference

​Core Methods

​Transformations

​Error Handling

​Filters

​See Also

Overview

Basic Usage

Making Requests

Processing Responses

Client Configuration

Base URL and Headers

Filtering Responses

Error Handling

Retry Logic

Error Recovery

Rate Limiting

Middleware

Request Transformation

Response Transformation

Cookie Management

Real-World Example

Testing

API Reference

Core Methods

Transformations

Error Handling

Filters

See Also