Response

Response module provides constructors and utilities for managing immutable interpretations of HTTP responses.

The Response Type

A Response represents immutable and clonable HTTP Response data. It is a base element of the Response module.

import { Response } from 'fx-fetch';

type Type = Response.Response;

The Input Type

A Response.Input represents all the possible inputs that can be used to create a Response.

Concrete types that make up the Input union:

import { Response } from 'fx-fetch';

type Type = Response.Response.Input;

• globalThis.Response — vanilla JS response
• Response.Response.Parts — Object with response parts
• Response.Response — Existing Response can be used too

Constructors

Note

Making a Response manually makes sense when you need to mock responses in tests or create responses from scratch.

unsafeMake

Creates a Response from any of Response.Input. Throws an IllegalArgumentException if the provided input is invalid.

import { Response } from 'fx-fetch';

//       ┌─── Response.Response
//       ▼
const response = Response.unsafeMake({
  body: 'Hello, world!',
  status: 200,
});

make

Similar to unsafeMake, but returns an Option instead of throwing an error if the input is invalid. If the input is invalid, it returns None. If valid, it returns Some containing the Response.

import { Option } from 'effect';
import { Response } from 'fx-fetch';

//       ┌─── Option.Option<Response.Response>
//       ▼
const response = Response.make({
  body: 'Hello, world!',
  status: 200,
});

from Response.Parts

For creating a Response from an object Response.Parts use same functions make or unsafeMake.

The Parts type is super primitive. It’s basically an object with all the properties of a JS response, but with better DX. Everything except the url is optional.

import { Response } from 'fx-fetch';

const parts: Response.Response.Parts = {
  body: 'Hello, world!',
  headers: {
    'Content-Type': 'text/plain',
    'X-Custom-Header': ['CustomValue', 'AnotherValue'],
  },
  redirected: false,
  status: 200,
  statusText: 'OK',
  type: 'cors',
  url: 'https://example.com/api',
};

const response = Response.unsafeMake(parts);

Properties url and headers have flexible input types.

• url is of type Url.Input. Read more about it in Url module documentation.
• headers can be almost anything what you can imagine as headers.
  • Record of strings
  • Entries (array of tuples)
  • Map of strings
  • Same as HeadersInit in Fetch API
  • many more…

---

Reading body

readJson

The readJson function reads the body of a Response and parses it as JSON.

import { Response } from 'fx-fetch';
//       ┌─── Effect<unknown, MalformedJsonError>
//       ▼
const payload = Response.readJson(response);

If you want a shortcut that combines fetching and reading JSON, use Fetch.fetchJson.

Tip

If you want to read JSON with a specific schema, consider using:

• readJsonWithSchema for Effect Schema

readText

The readText function reads the body of a Response and parses it as text.

import { Response } from 'fx-fetch';
//       ┌─── Effect<string, MalformedTextError>
//       ▼
const payload = Response.readText(response);

If you want a shortcut that combines fetching and reading text, use Fetch.fetchText.

readBlob

The readBlob function reads the body of a Response and parses it as a Blob.

import { Response } from 'fx-fetch';
//       ┌─── Effect<Blob, MalformedBlobError>
//       ▼
const payload = Response.readBlob(response);

If you want a shortcut that combines fetching and reading blob, use Fetch.fetchBlob.

readFormData

The readFormData function reads the body of a Response and parses it as form data.

import { Response } from 'fx-fetch';
//       ┌─── Effect<FormData, MalformedFormDataError>
//       ▼
const payload = Response.readFormData(response);

If you want a shortcut that combines fetching and reading form data, use Fetch.fetchFormData.

readBytes

The readBytes function reads the body of a Response and parses it as bytes.

import { Response } from 'fx-fetch';
//       ┌─── Effect<Uint8Array<ArrayBuffer>, MalformedBytesError>
//       ▼
const payload = Response.readBytes(response);

If you want a shortcut that combines fetching and reading bytes, use Fetch.fetchBytes.

readArrayBuffer

The readArrayBuffer function reads the body of a Response and parses it as an ArrayBuffer.

import { Response } from 'fx-fetch';
//       ┌─── Effect<ArrayBuffer, MalformedArrayBufferError>
//       ▼
const payload = Response.readArrayBuffer(response);

If you want a shortcut that combines fetching and reading bytes, use Fetch.fetchArrayBuffer.

readReadableStream

The readReadableStream function reads the body of a Response and parses it as a ReadableStream.

import { Response } from 'fx-fetch';
//       ┌─── Effect<
//       │      ReadableStream<Uint8Array<ArrayBuffer>>,
//       │      MalformedBytesError
//       │    >
//       ▼
const payload = Response.readReadableStream(response);

Tip

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

If you want a shortcut that combines fetching and reading bytes, use Fetch.fetchReadableStream.

readJsonWithSchema

The readJsonWithSchema function reads the body of a Response, parses it as JSON, and validates it against a provided schema.

import { Schema } from 'effect';
import { Response } from 'fx-fetch';

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

//       ┌─── Effect<
//       │      typeof UserSchema.Type,
//       │      MalformedJsonError | ParseError
//       │    >
//       ▼
const payload = Response.readJsonWithSchema(response, UserSchema);

readJsonWithStandardSchemaV1

The readJsonWithStandardSchemaV1 function reads the body of a Response, parses it as JSON, and validates it against a provided Standard Schema compatible schema.

This function works with any schema library that implements the Standard Schema specification, including Zod, Valibot, ArkType, and others.

import { Response } from 'fx-fetch';
import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});

//       ┌─── Effect.Effect<
//       │      { id: number; name: string },
//       │      MalformedJsonError | ParseError
//       │    >
//       ▼
const payload = Response.readJsonWithStandardSchemaV1(response, UserSchema);

readStream

The readStream function reads the body of a Response and parses it as an Effect Stream.

import { Response } from 'fx-fetch';
//       ┌─── Effect<
//       │      Stream<Uint8Array<ArrayBufferLike>, MyError>,
//       │      MalformedReadableStreamError
//       │    >
//       ▼
const payload = Response.readStream(response, {
  onError: (err) => new MyError(),
  releaseLockOnEnd: true, // optional
});

Errors

NotOkError

A NotOkError represents an error that occurs when a Response has a non-OK status code.

The error contains the following properties:

• response - The Response that caused the error.
• reason - A string indicating the category of the error based on the status code.
  • 'informational' for status codes 100-199
  • 'redirection' for status codes 300-399
  • 'client-error' for status codes 400-499
  • 'server-error' for status codes 500-599

import { Response } from 'fx-fetch';

function fn(error: Response.NotOkError) {
  error.response; // ◀︎── Response.Response
  error.reason; // ◀︎── 'client-error' | 'informational' | 'redirection' | 'server-error'
}

---

Catching Errors

notOkEither

Encapsulates both success Response and NotOkError failure of an Effect into an Either type of Response.

Transforms an Effect<Response, NotOkError> into an Effect<Either<Response, Response>>.

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

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

  //       ┌─── Either.Either<
  //       │      Response.Response, // Ok response 200-399
  //       │      Response.Response // NotOk response 400-599
  //       │    >
  //       ▼
  const result = yield* Fetch.fetch(request).pipe(
    Response.notOkEither
  );
});