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

head

Added in v4.0.0 Source

Creates a HEAD request for the specified URL.

Signature

declare const head: (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