Why FxFetch?

If you’re using EffectTS to build your applications and make HTTP requests, you’ll find FxFetch to be a perfect fit. It provides a type-safe, ergonomic API for handling fetch operations.

Why globalThis.fetch is not enough?

There are two main reasons:

1. Non-trivial error handling
2. Lack of immutability

Non-trivial error handling

Let’s walk through the pitfalls

1. Let’s start with an example

const program = Effect.gen(function* () {
  const response = yield* Effect.tryPromise({
    try: () => fetch('./my-endpoint'),
    catch: () => new MyError(),
  });

  processResponse(response); // Some logic here
});

Do you see the problem here? There’s more than meets the eye.

• Missing promise cancellation
• Is the response OK? What if it’s a 4XX or 5XX?
• Why does it fail?

2. Let’s improve it a bit

//       ┌─── Effect.Effect<void, MyError, never>
//       ▼
const program = Effect.gen(function* () {
  const response = yield* Effect.tryPromise({
    try: (signal) => fetch('./my-endpoint', { signal }),
    catch: () => new MyError(),
  }).pipe(
    Effect.flatMap((response) => {
      if (!response.ok) {
        return Effect.fail(new MyError());
      }
      return Effect.succeed(response);
    })
  );

  processResponse(response); // Some logic here
});

• Missing promise cancellation
• Is the response OK? What if it’s a 4XX or 5XX?
• Why does it fail?

This is safer, but still not useful enough. What does MyError mean? Can I retry?

3. Let’s improve the error handling

What are the possible reasons for failure?

Here are the most common reasons why a fetch request might fail:

1. Non-OK HTTP response: The server responded, but with a status code outside the 200–299 range.
2. Request aborted: The request was cancelled via an AbortController.
3. Network error: The network is unreachable, DNS fails, or the connection is lost.
4. CORS not allowed: The request is blocked due to Cross-Origin Resource Sharing (CORS) policy.
5. Invalid request parameters:

• Invalid header name or value
• Invalid URL or unsupported protocol/scheme
• URL includes unwanted credentials
• Invalid referrer URL
• Invalid request mode (e.g., navigate, websocket)
• Forbidden HTTP method (e.g., CONNECT, TRACE, TRACK)
• Body present with GET or HEAD method
• Cache mode or request mode mismatch (e.g., only-if-cached with non-same-origin)

6. Blocked by permissions policy: The browser or environment blocks the request due to security or permissions settings.
7. Out of memory: The environment cannot allocate enough memory to complete the request (rare).

That’s pretty much it. Let’s model these errors.

//       ┌─── Effect.Effect<
//       │      void,
//       │      | FetchError
//       │      | AbortError
//       │      | NotAllowedError
//       │      | NotOkError,
//       │      never
//       │    >
//       ▼
const program = Effect.gen(function* () {
  const response = yield* Effect.tryPromise({
    try: (signal) => fetch('./my-endpoint', { signal }),
    catch(error) {
      if (error instanceof TypeError) {
        return new FetchError();
      }

      if (typeof error === 'object' && error !== null && 'name' in error) {
        if (error.name === 'AbortError') {
          return new AbortError();
        }

        if (error.name === 'NotAllowedError') {
          return new NotAllowedError();
        }
      }

      // Fallback for Out-of-Memory and other unknown errors
      return new UnknownError();
    },
  }).pipe(
    Effect.catchTag('UnknownError', () =>
      // Out-of-Memory error is mostly defect. So we can die here.
      Effect.dieMessage('Unknown error occurred during fetch request')
    ),
    Effect.flatMap((response) => {
      if (!response.ok) {
        return Effect.fail(new NotOkError());
      }
      return Effect.succeed(response);
    })
  );

  processResponse(response); // Some logic here
});

• Missing promise cancellation
• Is the response OK? What if it’s a 4XX or 5XX?
• Why does it fail?

Nice! We did it. It is perfect, right? Nope.

Moving from a non-effect world to an effect world can be tedious, verbose and error-prone. It’s similar to using untyped JavaScript in TypeScript. It’s better if the hard work is done by someone else.

In the untyped npm ecosystem, we have the @types/* initiative. In this case, we have FxFetch!

4. Use FxFetch to do the heavy lifting for you 🎉

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' });
  const response = yield* Fetch.fetch(request);

  processResponse(response); // Some logic here
});

---

Lack of immutability

EffectTS is built on functional programming principles. All building blocks (Effect, Option, Either, DateTime, …) are immutable and clonable by design.

For a library to truly be in symbiosis with EffectTS, it must adhere to the same principles.

EffectTS excels at parallel actions and concurrency. Without using immutable and clonable structures, unexpected issues may appear.

Working with immutable objects can be challenging without proper tools — that’s why we built fx-fetch.

Real-world examples of why immutability and clonability matter:

• Reusing the same Request for paginated API calls
• Appending general headers to already-created Request objects
• Retrying failed requests without worrying about side effects

Why aren’t Request.clone() enough?

Caution

First, they don’t work properly in some browsers ( looking at you, Firefox 🦊 ).

Even when they work correctly, they don’t solve DX issues or provide key features like reading request/response properties multiple times without side effects.

const req = new globalThis.Request("./endpoint", {
  method: "POST",
  body: "Hello World", // ◀︎── string
});

console.log(req.body); // `ReadableStream { }`

// ReadableStream can only be read once.
// You must know what you're reading.