BrowserHttpClient unstable
Browser implementations of the Effect HttpClient.
This module exposes HTTP client layers for code that runs in a browser. It
re-exports the fetch-based Fetch, RequestInit, and layerFetch APIs for
the common case where requests use the platform fetch implementation. It
also provides an XMLHttpRequest-backed client, including controls for the
XHR response type, an overridable XMLHttpRequest constructor service, and
the layerXMLHttpRequest layer.
Requests with an Upgrade header fail with TransportError before anything
is sent because neither fetch nor XMLHttpRequest can hand over the connection.
Layers
layerFetch
unstableLayer that provides an HttpClient implementation backed by the configured
Fetch function.
When to use
Use when an Effect program should execute HttpClient requests through the
platform fetch implementation, especially in browser, edge, or Node.js
runtimes with globalThis.fetch.
Details
The layer uses the current Fetch reference and optional RequestInit
service for each request. Request-specific method, headers, body, and abort
signal are supplied by the client and override matching RequestInit fields.
Gotchas
Fetch behavior comes from the runtime's implementation, so CORS, cookies,
redirects, abort handling, and streaming support can vary by platform.
fetch follows redirects itself by default, so HttpClient.followRedirects
has no effect unless RequestInit sets redirect: "manual". Trace
propagation is on by default, and a browser preflight fails unless the
target allows b3 and traceparent. Stream request bodies are sent as Web
streams with duplex: "half" when the runtime supports it; see
StreamBodyFallback for the unsupported case. Any content-length header is
removed before calling fetch. Chrome passes the support check but rejects
streaming uploads over HTTP/1.1, which surfaces as a TransportError, and
browsers only deliver the response after the entire request body has been sent.
See
- Fetch for supplying the fetch implementation used by this layer
- RequestInit for default
RequestInitoptions applied before request-specific fields - StreamBodyFallback for opting into buffering on unsupported runtimes
- HttpClient.TracerPropagationEnabled for leaving
b3andtraceparentoff a browser request
Signature
declare const layerFetch: Layer.Layer<HttpClient.HttpClient>layerXMLHttpRequest
unstableLayer that provides an HttpClient implementation backed by the browser XMLHttpRequest API.
Signature
declare const layerXMLHttpRequest: Layer.Layer<HttpClient.HttpClient>Models
Allowed response body modes for the browser XHR HTTP client.
Signature
type XHRResponseType = "arraybuffer" | "text"Providing Services
withXHRArrayBuffer
unstableRuns an effect with CurrentXHRResponseType set to "arraybuffer" so the XHR HTTP client receives response bodies as ArrayBuffer values.
Signature
declare function withXHRArrayBuffer<A, E, R>(self: Effect<A, E, R>): Effect<A, E, R>Services
CurrentXHRResponseType
unstableContext reference for the XMLHttpRequest.responseType used by the browser XHR HTTP client, defaulting to "text".
When to use
Use when you need XHR-backed HTTP requests to receive response bodies as text
or raw ArrayBuffer values.
See
- XHRResponseType for the allowed response body modes
- withXHRArrayBuffer for scoping XHR response handling to
ArrayBuffer
Signature
declare const CurrentXHRResponseType: Context.Reference<XHRResponseType>Fetch
unstableContext reference for the fetch implementation used by the fetch-based HTTP client.
Details
Defaults to globalThis.fetch.
Signature
declare const Fetch: Context.Reference<typeof globalThis.fetch>RequestInit
unstableService that contains default fetch options for the fetch-based HTTP client.
When to use
Use to provide default credentials, cache, redirect, integrity, or other fetch options for outgoing HTTP requests.
Details
Request-specific method, headers, body, and abort signal are supplied by the client when a request is executed.
See
- HttpClient.followRedirects for following redirects in the client, which needs
{ redirect: "manual" }here
Signature
declare class RequestInit extends RequestInit_base { constructor(_: never);}XMLHttpRequest
unstableService tag for the XMLHttpRequest constructor used by the browser XHR HTTP client.
Signature
declare class XMLHttpRequest extends Shape<"@effect/platform-browser/BrowserHttpClient/XMLHttpRequest", LazyArg<XMLHttpRequest>, this> { constructor(_: never);}