Fetch

Fetch module contains services and helpers for making HTTP requests.

Basic Fetching

fetch

The fetch function is the most basic way to perform requests.

It takes a Request as input and returns an Effect with Response. Automatically handles errors such as network issues, request abortion, and non-OK HTTP responses.

import { Effect } from 'effect';
import { Fetch, Request, Response } from 'fx-fetch';

//       ┌─── Effect.Effect<
//       │      void,
//       │      | Fetch.FetchError
//       │      | Fetch.AbortError
//       │      | Fetch.NotAllowedError
//       │      | Response.NotOkError,
//       │      Fetch.Fetch
//       │    >
//       ▼
const program = Effect.gen(function* () {
  const request = Request.unsafeMake({ url: './my-endpoint' });

  //       ┌─── Response.Response
  //       ▼
  const response = yield* Fetch.fetch(request);
});

As you can see, using fetch will add a new requirement: Fetch.Fetch. So to run programs that use fetch, you will need to provide an implementation of the Fetch service.

program.pipe(
  Effect.provideService(Fetch.Fetch, Fetch.FetchLive),
  Effect.runFork // or Effect.runPromise etc.
);

Having fetch as a service allows you to easily swap implementations for testing, mocking, or other purposes.

layer

The layer export provides a convenient way to use the live Fetch implementation with Effect’s layer composition. This is the recommended approach when building applications with multiple layers.

import { Effect } from 'effect';
import { Fetch, Request } from 'fx-fetch';

const program = Effect.gen(function* () {
  const request = Request.unsafeMake({ url: 'https://example.com' });
  const response = yield* Fetch.fetch(request);
});

program.pipe(
  Effect.provide(Fetch.layer), // ◀︎── Provide Fetch layer
  Effect.runPromise
);

Tip

Use Fetch.layer when composing with other layers using Layer.merge or Layer.provide. Use Effect.provideService(Fetch.Fetch, Fetch.FetchLive) for simple, one-off usage.

fetchJson

The fetchJson function is a helper that combines fetch with Response.readJson. It is syntactic sugar for better ergonomics.

import { Effect } from 'effect';
import { Fetch, Request, Response } from 'fx-fetch';

//       ┌─── Effect.Effect<
//       │      void,
//       │      | Fetch.FetchError | Fetch.AbortError | Fetch.NotAllowedError | Response.NotOkError
//       │      | MalformedJsonError,
//       │      Fetch.Fetch
//       │    >
//       ▼
const program = Effect.gen(function* () {
  const request = Request.unsafeMake({ url: './my-endpoint' });

  //       ┌─── unknown
  //       ▼
  const payload = yield* Fetch.fetchJson(request);
});

fetchText

The fetchText function is a helper that combines fetch with Response.readText. It is similar to fetchJson, but reads the body as plain text.

fetchBlob

The fetchBlob function is a helper that combines fetch with Response.readBlob. It is similar to fetchJson, but reads the body as Blob.

fetchFormData

The fetchFormData function is a helper that combines fetch with Response.readFormData. It is similar to fetchJson, but reads the body as FormData.

fetchBytes

The fetchBytes function is a helper that combines fetch with Response.readBytes. It is similar to fetchJson, but reads the body as bytes.

fetchArrayBuffer

The fetchArrayBuffer function is a helper that combines fetch with Response.readArrayBuffer. It is similar to fetchJson, but reads the body as ArrayBuffer.

fetchReadableStream

The fetchReadableStream function is a helper that combines fetch with Response.readReadableStream. It is similar to fetchJson, but reads the body as ReadableStream.

Tip

If you want read the body as an Effect Stream, consider using fetchStream instead.

fetchJsonWithSchema

The fetchJsonWithSchema function is another helper that combines fetch with Response.readJsonWithSchema. It allows you to validate the payload against a Effect Schema.

import { Effect, Schema } from 'effect';
import { Fetch, Request, Response } from 'fx-fetch';

const UserSchema = Schema.Struct({
  id: Schema.Int,
  name: Schema.String,
});

//       ┌─── Effect.Effect<
//       │      void,
//       │      | Fetch.FetchError | Fetch.AbortError | Fetch.NotAllowedError | Response.NotOkError
//       │      | MalformedJsonError
//       │      | ParseError,
//       │      Fetch.Fetch
//       │    >
//       ▼
const program = Effect.gen(function* () {
  const request = Request.unsafeMake({ url: './my-endpoint' });

  //       ┌─── typeof UserSchema.Type
  //       ▼
  const payload = yield* Fetch.fetchJsonWithSchema(request, UserSchema);
});

fetchStream

The fetchStream function is a helper that combines fetch with Response.readStream.

import { Data, Effect } from 'effect';
import { Fetch, Request, Response } from 'fx-fetch';

class MyError extends Data.TaggedClass('MyError') {}

//       ┌─── Effect.Effect<
//       │      void,
//       │      | Fetch.FetchError
//       │      | Fetch.AbortError
//       │      | Fetch.NotAllowedError
//       │      | Response.NotOkError
//       │      | MalformedReadableStreamError,
//       │      Fetch.Fetch
//       │    >
//       ▼
const program = Effect.gen(function* () {
  const request = Request.unsafeMake({ url: './my-endpoint' });

  //       ┌─── Stream<
  //       │      Uint8Array<ArrayBufferLike>,
  //       │      MyError,
  //       │      never
  //       │    >,
  //       ▼
  const stream = yield* Fetch.fetchStream(request, {
    onError: (err) => new MyError(),
    releaseLockOnEnd: true, // optional
  });
});

Paginated Fetching

When dealing with APIs that return paginated data, fx-fetch provides convenient functions to handle pagination: paginatedFetch and paginatedFetchStream.

paginatedFetch

The paginatedFetch function is used to handle paginated HTTP endpoints. It repeatedly performs fetch requests based on the provided logic until there are no more pages to fetch.

The function takes an initial Request and an onResponse callback. The callback receives the last Response and should return an object containing:

• pageEmission: The data to emit for the current page.
• nextRequest: An Option containing the next Request to fetch, or None if there are no more pages.

import { Effect, Option, Schema } from 'effect';
import { Fetch, Request, Response } from 'fx-fetch';

class Person extends Schema.Class<Person>('Person')({
  id: Schema.Number,
  name: Schema.NonEmptyString,
}) {}

const PayloadSchema = Schema.Struct({
  nextToken: Schema.String.pipe(Schema.optional),
  items: Person.pipe(Schema.Array),
});

const request = Request.unsafeMake({ url: './persons' });

//       ┌─── Effect.Effect<
//       │      Person[][], // ◀︎── array of pages
//       │      | Fetch.FetchError | Fetch.AbortError | Fetch.NotAllowedError | Response.NotOkError
//       │      | MalformedJsonError
//       │      | ParseError,
//       │      Fetch.Fetch
//       │    >
//       ▼
const program = Fetch.paginatedFetch(
  request,
  Effect.fn(function* (lastResponse) {
    const payload = yield* Response.readJsonWithSchema(lastResponse, PayloadSchema);

    const nextToken = Option.fromNullable(payload.nextToken);
    const nextRequest = nextToken.pipe(
      Option.map((token) => Request.setUrlSearchParam(request, 'token', token))
    );

    return {
      pageEmission: payload.items,  // ◀︎── Person[]
      nextRequest, // ◀︎── Option.Option<Request.Request>
    };
  })
);

If you want a lazier approach that emits each page as it is fetched, you can use paginatedFetchStream.

paginatedFetchStream

The paginatedFetchStream function is similar to paginatedFetch, but instead of returning all pages at once, it returns a Stream that emits each page as it is fetched.

import { Effect, Option, Schema, Stream } from 'effect';
import { Fetch, Request, Response } from 'fx-fetch';

class Person extends Schema.Class<Person>('Person')({
  id: Schema.Number,
  name: Schema.NonEmptyString,
}) { }

const PayloadSchema = Schema.Struct({
  nextToken: Schema.String.pipe(Schema.optional),
  items: Person.pipe(Schema.Array),
});

const request = Request.unsafeMake({ url: './persons' });

//       ┌─── Stream.Stream<
//       │      Person[], // ◀︎── page emission
//       │      | Fetch.FetchError | Fetch.AbortError | Fetch.NotAllowedError | Response.NotOkError
//       │      | MalformedJsonError
//       │      | ParseError,
//       │      Fetch.Fetch
//       │    >
//       ▼
const program = Fetch.paginatedFetchStream(
  request,
  Effect.fn(function* (lastResponse) {
    const payload = yield* Response.readJsonWithSchema(lastResponse, PayloadSchema);

    const nextToken = Option.fromNullable(payload.nextToken);
    const nextRequest = nextToken.pipe(
      Option.map((token) => Request.setUrlSearchParam(request, 'token', token))
    );

    return {
      pageEmission: payload.items, // ◀︎── Person[]
      nextRequest, // ◀︎── Option.Option<Request.Request>
    };
  })
);

Middleware

The makeMiddlewareLayer function creates a middleware Layer that allows customizing request and response handling. This is useful for adding cross-cutting concerns like authentication, logging, or request transformation.

makeMiddlewareLayer

The middleware can transform requests before they are sent and responses after they are received. Both mapRequest and mapResponse are optional - if not provided, they pass through unchanged.

Execution order: mapRequest → fetch → mapResponse → ensureOk

import { Effect } from 'effect';
import { Fetch, Request, Response } from 'fx-fetch';

//       ┌─── Layer<Fetch, never, never>
//       ▼
const authMiddlewareLayer = Fetch.makeMiddlewareLayer({
  mapRequest: (request) =>
    Effect.succeed(
      Request.appendHeaders(request, { Authorization: 'Bearer token' })
    ),
});

const program = Effect.gen(function* () {
  const request = Request.unsafeMake({ url: 'https://api.example.com/data' });
  const response = yield* Fetch.fetch(request);
});

program.pipe(
  Effect.provide(authMiddlewareLayer), // ◀︎── Middleware adds Authorization header
  Effect.runPromise
);

Middleware with Dependencies

The middleware layer properly tracks Effect requirements, allowing you to inject dependencies like configuration services.

import { Context, Effect, Layer } from 'effect';
import { Fetch, Request } from 'fx-fetch';

// Service for configuration
class Config extends Context.Tag('Config')<Config, { apiKey: string }>() {}

//       ┌─── Layer<Fetch, never, Config>
//       ▼
const authMiddlewareLayer = Fetch.makeMiddlewareLayer({
  mapRequest: (request) =>
    Effect.gen(function* () {
      const config = yield* Config;
      return Request.appendHeaders(request, { 'X-API-Key': config.apiKey });
    }),
});

const program = Effect.gen(function* () {
  const request = Request.unsafeMake({ url: 'https://api.example.com/data' });
  const response = yield* Fetch.fetch(request);
});

program.pipe(
  Effect.provide(authMiddlewareLayer),
  Effect.provide(Layer.succeed(Config, { apiKey: 'my-secret-key' })),
  Effect.runPromise
);

Response Transformation

You can also transform or inspect responses using mapResponse.

import { Effect } from 'effect';
import { Fetch } from 'fx-fetch';

const loggingMiddlewareLayer = Fetch.makeMiddlewareLayer({
  mapResponse: (response) =>
    Effect.gen(function* () {
      yield* Effect.log(`Response status: ${response.status}`);
      return response;
    }),
});

Tip

You can combine both mapRequest and mapResponse in the same middleware to handle complete request/response lifecycle.

Testing

The makeMockLayer function creates a mock Fetch layer for testing purposes. This allows you to test your code without making actual HTTP requests.

makeMockLayer

The mock function receives the Request and can return either:

• A plain Response object
• An Effect<Response, Error> for simulating async behavior or errors

import { Effect } from 'effect';
import { Fetch, Request, Response } from 'fx-fetch';

// Mock returning a simple Response
const mockLayer = Fetch.makeMockLayer(() =>
  Response.unsafeMake({ status: 200, ok: true, body: 'Hello' })
);

const program = Effect.gen(function* () {
  const request = Request.unsafeMake({ url: 'https://example.com' });
  const response = yield* Fetch.fetch(request);
});

program.pipe(
  Effect.provide(mockLayer), // ◀︎── Uses mock instead of real fetch
  Effect.runPromise
);

Request-Aware Mocking

The mock function receives the request, allowing you to return different responses based on the URL, headers, or other request properties.

import { Fetch, Response, Url } from 'fx-fetch';

const mockLayer = Fetch.makeMockLayer((request) => {
  if (Url.format(request.url).includes('/users')) {
    return Response.unsafeMake({
      status: 200,
      ok: true,
      body: JSON.stringify([{ id: 1, name: 'Alice' }]),
    });
  }

  return Response.unsafeMake({ status: 404, ok: false });
});

Error Simulation

You can simulate errors by returning an Effect.fail from the mock function.

import { Effect } from 'effect';
import { Fetch } from 'fx-fetch';

const mockLayer = Fetch.makeMockLayer(() =>
  Effect.fail(new Fetch.AbortError({ message: 'Request was aborted', cause: new Error() }))
);

Errors

When using the fetch functions, several error types may be encountered:

FetchError

Represents general errors that occur during the fetch operation.

Depending on the nature of the error, it may make sense to retry the operation.

import { Fetch } from 'fx-fetch';

type MyType = Fetch.FetchError;

AbortError

Indicates that the fetch operation was aborted.

Does not make sense to retry this error.

import { Fetch } from 'fx-fetch';

type MyType = Fetch.AbortError;

NotAllowedError

Indicates that the fetch operation is not allowed, possibly due to CORS restrictions.

Does not make sense to retry this error.

import { Fetch } from 'fx-fetch';

type MyType = Fetch.NotAllowedError;