HttpClientRequest unstable

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.

54 exports Since v4.0.0 Source

Combinators

accept

unstable

Since v4.0.0

Sets the Accept header to the specified media type.

Signature

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

acceptJson

unstable

Since v4.0.0

Sets the Accept header to application/json.

Signature

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

appendUrl

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

Details

A Redacted value is sent unwrapped and stays redacted in inspection, errors and spans.

Signature

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

appendUrlParams

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

Details

Uses HttpBody.file to validate ranges lazily and calculate the EOF-clamped content length with exact bigint arithmetic. Invalid range inputs or a final length above Number.MAX_SAFE_INTEGER fail with PlatformError / BadArgument. Larger sizes, offsets, and byte counts are valid when the final length is representable as a safe integer. The request's Content-Length header contains that exact length.

Signature

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

bodyFormData

unstable

Since v4.0.0

Sets a FormData request body.

Signature

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

bodyFormDataRecord

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

compressBody

unstable

Since v4.0.0

Compresses a request body using Web CompressionStream and sets Content-Encoding.

Details

Byte-array bodies (including text, JSON, and URL-encoded bodies) are compressed into a new Uint8Array body, preserving the content type and updating Content-Length. The compressed body does not retain the original lazy text. Stream bodies are compressed lazily and have their content length removed. They still require a client runtime that supports streaming request bodies (Fetch requires duplex: "half", which Safari and Firefox do not support).

Returns the original request unchanged for empty, FormData, and raw bodies, bodies with a known length below options.minSize, or requests with any existing Content-Encoding header, including identity. Unknown-length streams are always compressed. The default minimum is 1024 bytes because gzip can make very small bodies larger.

Requires CompressionStream (available in browsers, Node 18+, Bun, and Deno). There is no typed error channel: byte compression failures are defects; stream failures surface when the body is sent.

To compress every request, use HttpClient.mapRequestEffect(HttpClientRequest.compressBody("gzip")). HttpClient.retryTransient re-runs preprocessing, so this recompresses on every retry. For large bodies, compress once before calling client.execute.

Signature

declare const compressBody: {
  (algorithm: CompressionAlgorithm, options?: CompressionOptions): (self: HttpClientRequest) => Effect<HttpClientRequest>;
  (self: HttpClientRequest, algorithm: CompressionAlgorithm, options?: CompressionOptions): Effect<HttpClientRequest>;
}

modify

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

Removes the URL fragment from a request.

Signature

declare function removeHash(self: HttpClientRequest): HttpClientRequest

removeHeader

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

Details

A Redacted value is sent unwrapped and stays redacted in inspection, errors and spans.

Signature

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

setUrlParams

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

Signature

declare const empty: HttpClientRequest

get

unstable

Since v4.0.0

Creates a GET request for the specified URL.

Signature

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

head

unstable

Since v4.0.0

Creates a HEAD request for the specified URL.

Signature

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

make

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

Creates an OPTIONS request for the specified URL.

Signature

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

patch

unstable

Since v4.0.0

Creates a PATCH request for the specified URL.

Signature

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

post

unstable

Since v4.0.0

Creates a POST request for the specified URL.

Signature

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

put

unstable

Since v4.0.0

Creates a PUT request for the specified URL.

Signature

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

query

unstable

Since v4.0.0

Creates a QUERY request for the specified URL.

Signature

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

trace

unstable

Since v4.0.0

Creates a TRACE request for the specified URL.

Signature

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

Converting

fromWeb

unstable

Since v4.0.0

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

Signature

declare function fromWeb(request: Request): HttpClientRequest

toWeb

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

Returns true when a value is an HttpClientRequest.

Signature

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

Models

CompressionAlgorithm

type unstable

Since v4.0.0

Algorithms supported by Web CompressionStream for request body compression.

Signature

type CompressionAlgorithm = "gzip" | "deflate"