Skip to content

HttpClientRequest

Describes immutable outgoing HTTP client requests.

HttpClientRequest is the request model shared by Effect HTTP clients and platform adapters. A request stores its method, URL, query parameters, hash, headers, and body as structured data. This module includes constructors, helpers for updating requests, body encoders for common payloads, and conversions to and from Web Request values.

50 exports Added in v4.0.0 Source

Combinators

accept

Added in v4.0.0 Source

Sets the Accept header to the specified media type.

Signature

declare const accept: {
  (mediaType: string): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, mediaType: string): HttpClientRequest;
};

acceptJson

Added in v4.0.0 Source

Sets the Accept header to application/json.

Signature

declare const acceptJson: (self: HttpClientRequest) => HttpClientRequest;

appendUrl

Added in v4.0.0 Source

Appends a URL segment to the request URL, inserting or trimming one slash as needed.

Signature

declare const appendUrl: {
  (path: string): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, path: string): HttpClientRequest;
};

appendUrlParam

Added in v4.0.0 Source

Appends one query parameter value without removing existing values for the same name.

Signature

declare const appendUrlParam: {
  (key: string, value: string): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, key: string, value: string): HttpClientRequest;
};

appendUrlParams

Added in v4.0.0 Source

Appends query parameters from an input collection without removing existing values for matching names.

Signature

declare const appendUrlParams: {
  (input: Input): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, input: Input): HttpClientRequest;
};

basicAuth

Added in v4.0.0 Source

Sets the Authorization header using HTTP Basic authentication credentials.

Signature

declare const basicAuth: {
  (
    username: string | Redacted<string>,
    password: string | Redacted<string>,
  ): (self: HttpClientRequest) => HttpClientRequest;
  (
    self: HttpClientRequest,
    username: string | Redacted<string>,
    password: string | Redacted<string>,
  ): HttpClientRequest;
};

bearerToken

Added in v4.0.0 Source

Sets the Authorization header using a bearer token.

Signature

declare const bearerToken: {
  (token: string | Redacted<string>): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, token: string | Redacted<string>): HttpClientRequest;
};

bodyFile

Added in v4.0.0 Source

Creates a file-backed request body from a filesystem path and sets it on the request.

Signature

declare const bodyFile: {
  (
    path: string,
    options?: {
      readonly bytesToRead?: FileSystem.SizeInput;
      readonly chunkSize?: FileSystem.SizeInput;
      readonly contentType?: string;
      readonly offset?: FileSystem.SizeInput;
    },
  ): (self: HttpClientRequest) => Effect<HttpClientRequest, PlatformError, FileSystem>;
  (
    self: HttpClientRequest,
    path: string,
    options?: {
      readonly bytesToRead?: FileSystem.SizeInput;
      readonly chunkSize?: FileSystem.SizeInput;
      readonly contentType?: string;
      readonly offset?: FileSystem.SizeInput;
    },
  ): Effect<HttpClientRequest, PlatformError, FileSystem>;
};

bodyFormData

Added in v4.0.0 Source

Sets a FormData request body.

Signature

declare const bodyFormData: {
  (body: FormData): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, body: FormData): HttpClientRequest;
};

bodyFormDataRecord

Added in v4.0.0 Source

Creates a FormData request body from record-style entries and sets it on the request.

Signature

declare const bodyFormDataRecord: {
  (entries: HttpBody.FormDataInput): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, entries: HttpBody.FormDataInput): HttpClientRequest;
};

bodyJson

Added in v4.0.0 Source

Encodes a value as a JSON request body and sets it on the request, failing with HttpBodyError if encoding fails.

Signature

declare const bodyJson: {
  (body: unknown): (self: HttpClientRequest) => Effect<HttpClientRequest, HttpBodyError>;
  (self: HttpClientRequest, body: unknown): Effect<HttpClientRequest, HttpBodyError>;
};

bodyJsonUnsafe

Added in v4.0.0 Source

Sets a JSON request body using unsafe JSON encoding.

When to use

Use when the request body is known to be JSON-serializable and a synchronous HttpClientRequest result is needed.

Gotchas

JSON encoding may throw instead of failing in the Effect error channel.

Signature

declare const bodyJsonUnsafe: {
  (body: unknown): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, body: unknown): HttpClientRequest;
};

bodyStream

Added in v4.0.0 Source

Sets a streaming Uint8Array request body with optional content type and content length metadata.

Signature

declare const bodyStream: {
  (
    body: Stream<Uint8Array<ArrayBufferLike>, unknown>,
    options?: {
      readonly contentLength?: number;
      readonly contentType?: string;
    },
  ): (self: HttpClientRequest) => HttpClientRequest;
  (
    self: HttpClientRequest,
    body: Stream<Uint8Array<ArrayBufferLike>, unknown>,
    options?: {
      readonly contentLength?: number;
      readonly contentType?: string;
    },
  ): HttpClientRequest;
};

bodyText

Added in v4.0.0 Source

Sets a text request body with an optional content type.

Signature

declare const bodyText: {
  (body: string, contentType?: string): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, body: string, contentType?: string): HttpClientRequest;
};

bodyUint8Array

Added in v4.0.0 Source

Sets a Uint8Array request body with an optional content type.

Signature

declare const bodyUint8Array: {
  (body: Uint8Array, contentType?: string): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, body: Uint8Array, contentType?: string): HttpClientRequest;
};

bodyUrlParams

Added in v4.0.0 Source

Sets an application/x-www-form-urlencoded request body from URL parameter input.

Signature

declare const bodyUrlParams: {
  (input: Input): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, input: Input): HttpClientRequest;
};

modify

Added in v4.0.0 Source

Applies request options to an HttpClientRequest, returning a new request.

Signature

declare const modify: {
  (options: Options): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, options: Options): HttpClientRequest;
};

prependUrl

Added in v4.0.0 Source

Prepends a URL segment to the request URL, inserting or trimming one slash as needed.

Signature

declare const prependUrl: {
  (path: string): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, path: string): HttpClientRequest;
};

removeHash

Added in v4.0.0 Source

Removes the URL fragment from a request.

Signature

declare function removeHash(self: HttpClientRequest): HttpClientRequest;

removeHeader

Added in v4.0.0 Source

Removes a single request header by name, returning a new request.

Signature

declare const removeHeader: {
  (key: string): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, key: string): HttpClientRequest;
};

schemaBodyJson

Added in v4.0.0 Source

Creates a schema-based JSON body encoder that sets the encoded value on a request.

Signature

declare function schemaBodyJson<S extends Constraint>(
  schema: S,
  options?: ParseOptions,
): {
  (
    body: S["Type"],
  ): (self: HttpClientRequest) => Effect<HttpClientRequest, HttpBodyError, S["EncodingServices"]>;
  (
    self: HttpClientRequest,
    body: S["Type"],
  ): Effect<HttpClientRequest, HttpBodyError, S["EncodingServices"]>;
};

setBody

Added in v4.0.0 Source

Sets the request body and updates Content-Type and Content-Length headers from the body metadata when available.

Signature

declare const setBody: {
  (body: HttpBody): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, body: HttpBody): HttpClientRequest;
};

setHash

Added in v4.0.0 Source

Sets the URL fragment on a request without the leading #.

Signature

declare const setHash: {
  (hash: string): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, hash: string): HttpClientRequest;
};

setHeader

Added in v4.0.0 Source

Sets a single request header, replacing any existing value for that header.

Signature

declare const setHeader: {
  (key: string, value: string): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, key: string, value: string): HttpClientRequest;
};

setHeaders

Added in v4.0.0 Source

Sets multiple request headers from an input collection, replacing existing values with matching names.

Signature

declare const setHeaders: {
  (input: Input): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, input: Input): HttpClientRequest;
};

setMethod

Added in v4.0.0 Source

Sets the HTTP method on a request, returning a new request.

Signature

declare const setMethod: {
  (method: HttpMethod): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, method: HttpMethod): HttpClientRequest;
};

setUrl

Added in v4.0.0 Source

Sets the request URL. When given a URL, its search parameters and hash are extracted into the request's structured fields.

Signature

declare const setUrl: {
  (url: string | URL): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, url: string | URL): HttpClientRequest;
};

setUrlParam

Added in v4.0.0 Source

Sets one query parameter, replacing existing values for that parameter name.

Signature

declare const setUrlParam: {
  (key: string, value: string): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, key: string, value: string): HttpClientRequest;
};

setUrlParams

Added in v4.0.0 Source

Sets query parameters from an input collection, replacing existing values for matching names.

Signature

declare const setUrlParams: {
  (input: Input): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, input: Input): HttpClientRequest;
};

toUrl

Added in v4.0.0 Source

Builds a URL from the request URL, query parameters, and hash, returning Option.none() if the URL is invalid.

Signature

declare function toUrl(self: HttpClientRequest): Option<URL>;

updateHeaders

Added in v4.0.0 Source

Transforms the request headers with the provided function, returning a new request.

Signature

declare const updateHeaders: {
  (f: (headers: Headers) => Headers): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, f: (headers: Headers) => Headers): HttpClientRequest;
};

updateUrl

Added in v4.0.0 Source

Updates the request URL by applying a function to the current URL string.

Signature

declare const updateUrl: {
  (f: (url: string) => string): (self: HttpClientRequest) => HttpClientRequest;
  (self: HttpClientRequest, f: (url: string) => string): HttpClientRequest;
};

Constructors

empty

Added in v4.0.0 Source

An empty GET request with no URL, query parameters, hash, headers, or body.

Signature

declare const empty: HttpClientRequest;

get

Added in v4.0.0 Source

Creates a GET request for the specified URL.

Signature

declare const get: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest;

make

Added in v4.0.0 Source

Creates a request constructor for the specified HTTP method.

Signature

declare function make<M extends HttpMethod>(
  method: M,
): (url: string | URL, options?: NoUrl) => HttpClientRequest;

makeWith

Added in v4.0.0 Source

Constructs an HttpClientRequest from fully normalized request components.

Signature

declare function makeWith(
  method: HttpMethod,
  url: string,
  urlParams: Input,
  hash: Option<string>,
  headers: Headers,
  body: HttpBody,
): HttpClientRequest;

options

Added in v4.0.0 Source

Creates an OPTIONS request for the specified URL.

Signature

declare const options: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest;

patch

Added in v4.0.0 Source

Creates a PATCH request for the specified URL.

Signature

declare const patch: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest;

post

Added in v4.0.0 Source

Creates a POST request for the specified URL.

Signature

declare const post: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest;

put

Added in v4.0.0 Source

Creates a PUT request for the specified URL.

Signature

declare const put: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest;

trace

Added in v4.0.0 Source

Creates a TRACE request for the specified URL.

Signature

declare const trace: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest;

Converting

fromWeb

Added in v4.0.0 Source

Converts a Web Request into an HttpClientRequest, preserving method, URL, headers, and supported request bodies.

Signature

declare function fromWeb(request: Request): HttpClientRequest;

toWeb

Added in v4.0.0 Source

Converts an HttpClientRequest to a Web Request, failing with UrlError when the request URL is invalid.

Signature

declare function toWeb(
  self: HttpClientRequest,
  options?: {
    readonly signal?: AbortSignal;
  },
): Effect<Request, UrlError>;

toWebResult

Added in v4.0.0 Source

Converts an HttpClientRequest safely to a Web Request as a Result, failing when the request URL is invalid.

Signature

declare function toWebResult(
  self: HttpClientRequest,
  options?: {
    readonly context?: Context<never>;
    readonly signal?: AbortSignal;
  },
): Result<Request, UrlError>;

Guards

isHttpClientRequest

Added in v4.0.0 Source

Returns true when a value is an HttpClientRequest.

Signature

declare function isHttpClientRequest(u: unknown): u is HttpClientRequest;

Models

HttpClientRequest interface

Added in v4.0.0 Source

Immutable model of an outgoing HTTP client request, including its method, URL components, headers, and body.

Signature

interface HttpClientRequest extends Inspectable, Pipeable {
  readonly "~effect/http/HttpClientRequest": "~effect/http/HttpClientRequest";
  readonly body: HttpBody;
  readonly hash: Option<string>;
  readonly headers: Headers;
  readonly method: HttpMethod;
  readonly url: string;
  readonly urlParams: UrlParams;
}

Options

Options interface

Added in v4.0.0 Source

Options for constructing or modifying an HttpClientRequest.

Signature

interface Options {
  readonly accept?: string;
  readonly acceptJson?: boolean;
  readonly body?: HttpBody;
  readonly hash?: string;
  readonly headers?: Input;
  readonly method?: HttpMethod;
  readonly url?: string | URL;
  readonly urlParams?: Input;
}

Other

delete

Source

Signature

declare const delete: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest

Options

Added in v4.0.0 Source

Namespace containing option types associated with HttpClientRequest construction.