HttpClientRequest.ts

HttpClientRequest.ts overview

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.

Since v4.0.0

---

Exports Grouped by Category

• combinators
  • accept
  • acceptJson
  • appendUrl
  • appendUrlParam
  • appendUrlParams
  • basicAuth
  • bearerToken
  • bodyFile
  • bodyFormData
  • bodyFormDataRecord
  • bodyJson
  • bodyJsonUnsafe
  • bodyStream
  • bodyText
  • bodyUint8Array
  • bodyUrlParams
  • modify
  • prependUrl
  • removeHash
  • schemaBodyJson
  • setBody
  • setHash
  • setHeader
  • setHeaders
  • setMethod
  • setUrl
  • setUrlParam
  • setUrlParams
  • toUrl
  • updateUrl
• constructors
  • delete
  • empty
  • get
  • head
  • make
  • makeWith
  • options
  • patch
  • post
  • put
  • trace
• converting
  • fromWeb
  • toWeb
  • toWebResult
• guards
  • isHttpClientRequest
• models
  • HttpClientRequest (interface)
• options
  • Options (interface)
• utils
  • Options (namespace)
    • NoUrl (interface)

---

combinators

accept

Sets the Accept header to the specified media type.

Signature

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

Source

Since v4.0.0

acceptJson

Sets the Accept header to application/json.

Signature

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

Source

Since v4.0.0

appendUrl

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
}

Source

Since v4.0.0

appendUrlParam

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
}

Source

Since v4.0.0

appendUrlParams

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

Signature

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

Source

Since v4.0.0

basicAuth

Sets the Authorization header using HTTP Basic authentication credentials.

Signature

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

Source

Since v4.0.0

bearerToken

Sets the Authorization header using a bearer token.

Signature

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

Source

Since v4.0.0

bodyFile

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 | undefined
      readonly chunkSize?: FileSystem.SizeInput | undefined
      readonly offset?: FileSystem.SizeInput | undefined
      readonly contentType?: string
    }
  ): (self: HttpClientRequest) => Effect.Effect<HttpClientRequest, PlatformError.PlatformError, FileSystem.FileSystem>
  (
    self: HttpClientRequest,
    path: string,
    options?: {
      readonly bytesToRead?: FileSystem.SizeInput | undefined
      readonly chunkSize?: FileSystem.SizeInput | undefined
      readonly offset?: FileSystem.SizeInput | undefined
      readonly contentType?: string
    }
  ): Effect.Effect<HttpClientRequest, PlatformError.PlatformError, FileSystem.FileSystem>
}

Source

Since v4.0.0

bodyFormData

Sets a FormData request body.

Signature

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

Source

Since v4.0.0

bodyFormDataRecord

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
}

Source

Since v4.0.0

bodyJson

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.Effect<HttpClientRequest, HttpBody.HttpBodyError>
  (self: HttpClientRequest, body: unknown): Effect.Effect<HttpClientRequest, HttpBody.HttpBodyError>
}

Source

Since v4.0.0

bodyJsonUnsafe

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
}

Source

Since v4.0.0

bodyStream

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

Signature

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

Source

Since v4.0.0

bodyText

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
}

Source

Since v4.0.0

bodyUint8Array

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
}

Source

Since v4.0.0

bodyUrlParams

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

Signature

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

Source

Since v4.0.0

modify

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

Signature

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

Source

Since v4.0.0

prependUrl

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
}

Source

Since v4.0.0

removeHash

Removes the URL fragment from a request.

Signature

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

Source

Since v4.0.0

schemaBodyJson

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

Signature

declare const schemaBodyJson: <S extends Schema.Constraint>(
  schema: S,
  options?: ParseOptions | undefined
) => {
  (
    body: S["Type"]
  ): (self: HttpClientRequest) => Effect.Effect<HttpClientRequest, HttpBody.HttpBodyError, S["EncodingServices"]>
  (
    self: HttpClientRequest,
    body: S["Type"]
  ): Effect.Effect<HttpClientRequest, HttpBody.HttpBodyError, S["EncodingServices"]>
}

Source

Since v4.0.0

setBody

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

Signature

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

Source

Since v4.0.0

setHash

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

Signature

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

Source

Since v4.0.0

setHeader

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
}

Source

Since v4.0.0

setHeaders

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

Signature

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

Source

Since v4.0.0

setMethod

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
}

Source

Since v4.0.0

setUrl

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
}

Source

Since v4.0.0

setUrlParam

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
}

Source

Since v4.0.0

setUrlParams

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

Signature

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

Source

Since v4.0.0

toUrl

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

Signature

declare const toUrl: (self: HttpClientRequest) => Option.Option<URL>

Source

Since v4.0.0

updateUrl

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
}

Source

Since v4.0.0

constructors

delete

Creates a DELETE request for the specified URL.

Signature

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

Source

Since v4.0.0

empty

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

Signature

declare const empty: HttpClientRequest

Source

Since v4.0.0

get

Creates a GET request for the specified URL.

Signature

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

Source

Since v4.0.0

head

Creates a HEAD request for the specified URL.

Signature

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

Source

Since v4.0.0

make

Creates a request constructor for the specified HTTP method.

Signature

declare const make: <M extends HttpMethod>(
  method: M
) => (url: string | URL, options?: Options.NoUrl | undefined) => HttpClientRequest

Source

Since v4.0.0

makeWith

Constructs an HttpClientRequest from fully normalized request components.

Signature

declare const makeWith: (
  method: HttpMethod,
  url: string,
  urlParams: UrlParams.UrlParams,
  hash: Option.Option<string>,
  headers: Headers.Headers,
  body: HttpBody.HttpBody
) => HttpClientRequest

Source

Since v4.0.0

options

Creates an OPTIONS request for the specified URL.

Signature

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

Source

Since v4.0.0

patch

Creates a PATCH request for the specified URL.

Signature

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

Source

Since v4.0.0

post

Creates a POST request for the specified URL.

Signature

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

Source

Since v4.0.0

put

Creates a PUT request for the specified URL.

Signature

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

Source

Since v4.0.0

trace

Creates a TRACE request for the specified URL.

Signature

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

Source

Since v4.0.0

converting

fromWeb

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

Signature

declare const fromWeb: (request: globalThis.Request) => HttpClientRequest

Source

Since v4.0.0

toWeb

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

Signature

declare const toWeb: (
  self: HttpClientRequest,
  options?: { readonly signal?: AbortSignal | undefined }
) => Effect.Effect<Request, UrlParams.UrlParamsError>

Source

Since v4.0.0

toWebResult

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

Signature

declare const toWebResult: (
  self: HttpClientRequest,
  options?: { readonly signal?: AbortSignal | undefined; readonly context?: Context.Context<never> | undefined }
) => Result.Result<Request, UrlParams.UrlParamsError>

Source

Since v4.0.0

guards

isHttpClientRequest

Returns true when a value is an HttpClientRequest.

Signature

declare const isHttpClientRequest: (u: unknown) => u is HttpClientRequest

Source

Since v4.0.0

models

HttpClientRequest (interface)

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

Signature

export interface HttpClientRequest extends Inspectable.Inspectable, Pipeable {
  readonly [TypeId]: typeof TypeId
  readonly method: HttpMethod
  readonly url: string
  readonly urlParams: UrlParams.UrlParams
  readonly hash: Option.Option<string>
  readonly headers: Headers.Headers
  readonly body: HttpBody.HttpBody
}

Source

Since v4.0.0

options

Options (interface)

Options for constructing or modifying an HttpClientRequest.

Signature

export interface Options {
  readonly method?: HttpMethod | undefined
  readonly url?: string | URL | undefined
  readonly urlParams?: UrlParams.Input | undefined
  readonly hash?: string | undefined
  readonly headers?: Headers.Input | undefined
  readonly body?: HttpBody.HttpBody | undefined
  readonly accept?: string | undefined
  readonly acceptJson?: boolean | undefined
}

Source

Since v4.0.0

utils

Options (namespace)

Namespace containing option types associated with HttpClientRequest construction.

Source

Since v4.0.0

NoUrl (interface)

Request options that omit the method and URL for helpers that already receive those values separately.

Signature

export interface NoUrl extends Omit<Options, "method" | "url"> {}

Source

Since v4.0.0