Fetch

Fetch module contains services and helpers for making HTTP requests.

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.

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
  });
});

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>
    };
  })
);