NodeHttpClient unstable

Node.js implementations of the Effect HttpClient.

This module supplies Node runtime backends for the platform-independent Effect HTTP client API. It re-exports the fetch-based Fetch, RequestInit, and layerFetch APIs, defines an Undici-backed client with dispatcher services and request options, and defines a lower-level node:http / node:https client with scoped HTTP agent layers.

23 exports Since v4.0.0 Source

Constructors

makeNodeHttp

unstable

Since v4.0.0

Creates an HttpClient backed by Node http and https, using the current HttpAgent, streaming request bodies, and wrapping Node responses as HttpClientResponse values.

Signature

declare const makeNodeHttp: Effect<HttpClient, never, HttpAgent>

makeUndici

unstable

Since v4.0.0

Creates an HttpClient that sends requests through the current Undici Dispatcher, converts Effect HTTP bodies to Undici bodies, and maps transport and decode failures to HttpClientError.

Signature

declare const makeUndici: Effect<HttpClient, never, Dispatcher>

Layers

dispatcherLayerGlobal

unstable

Since v4.0.0

Provides the Dispatcher service from Undici's process-global dispatcher, without creating or owning a new agent.

Signature

declare const dispatcherLayerGlobal: Layer.Layer<Dispatcher>

layerAgent

unstable

Since v4.0.0

Provides the HttpAgent service using default scoped Node http and https agents.

Signature

declare const layerAgent: Layer.Layer<HttpAgent>

layerAgentOptions

unstable

Since v4.0.0

Provides the HttpAgent service using scoped Node http and https agents configured with the supplied options.

Signature

declare const layerAgentOptions: (options?: HttpAgentOptions) => Layer.Layer<HttpAgent>

layerDispatcher

unstable

Since v4.0.0

Provides the Dispatcher service using a scoped Undici Agent.

Signature

declare const layerDispatcher: Layer.Layer<Dispatcher>

layerDispatcherOptions

unstable

Since v4.0.5

Provides the Dispatcher service using a scoped Undici Agent configured with the supplied options.

Details

See makeDispatcherOptions for the unix socket and TLS settings.

Signature

declare const layerDispatcherOptions: (options?: Undici.Agent.Options) => Layer.Layer<Dispatcher>

layerFetch

unstable

Since v4.0.0

Layer 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. Stream request bodies are sent as Web streams with duplex: "half", and any content-length header is removed before calling fetch.

See

Fetch for supplying the fetch implementation used by this layer
RequestInit for default RequestInit options applied before request-specific fields

Signature

declare const layerFetch: Layer.Layer<HttpClient.HttpClient>

layerNodeHttp

unstable

Since v4.0.0

Provides a node:http-backed HttpClient together with default scoped Node http and https agents.

Signature

declare const layerNodeHttp: Layer.Layer<Client.HttpClient>

layerNodeHttpNoAgent

unstable

Since v4.0.0

Provides a node:http-backed HttpClient using the current HttpAgent service.

Signature

declare const layerNodeHttpNoAgent: Layer.Layer<Client.HttpClient, never, HttpAgent>

layerNodeHttpOptions

unstable

Since v4.0.5

Provides a node:http-backed HttpClient together with scoped Node http and https agents configured with the supplied options.

When to use

Use to send every request over a unix domain socket with { socketPath }, or over TLS with a custom CA and client certificate with { ca, cert, key, servername, rejectUnauthorized }.

Details

See HttpAgentOptions for how the options are applied.

Signature

declare function layerNodeHttpOptions(options?: HttpAgentOptions): Layer<HttpClient>

layerUndici

unstable

Since v4.0.0

Provides an Undici-backed HttpClient together with a scoped default Undici Agent dispatcher.

Signature

declare const layerUndici: Layer.Layer<Client.HttpClient>

layerUndiciNoDispatcher

unstable

Since v4.0.0

Provides an Undici-backed HttpClient using the current Dispatcher service.

Signature

declare const layerUndiciNoDispatcher: Layer.Layer<Client.HttpClient, never, Dispatcher>

layerUndiciOptions

unstable

Since v4.0.5

Provides an Undici-backed HttpClient together with a scoped Undici Agent dispatcher configured with the supplied options.

When to use

Use to send every request over a unix domain socket with { connect: { socketPath } }, or over TLS with a custom CA and client certificate with { connect: { ca, cert, key, servername, rejectUnauthorized } }.

Details

See makeDispatcherOptions for how the options are applied.

Signature

declare function layerUndiciOptions(options?: any): Layer<HttpClient>

Models

HttpAgentOptions

interface unstable

Since v4.0.5

Options for the Node http and https agents created by makeAgent.

Details

Extends https.AgentOptions with socketPath. Node agents merge their options into every request they create, so:

socketPath dials a unix domain socket (or a Windows named pipe) instead of TCP. The request URL still supplies the Host header and path.
ca, cert, key, servername and rejectUnauthorized configure TLS for https: URLs, including mutual TLS.

Both agents receive the same options.

Signature

interface HttpAgentOptions extends AgentOptions {
  readonly socketPath?: string;
}

Resource Management

makeAgent

unstable

Since v4.0.0

Acquires Node http and https agents with the supplied options and destroys both agents when the enclosing scope is finalized.

Signature

declare function makeAgent(options?: HttpAgentOptions): Effect<{
  readonly http: Agent;
  readonly https: Agent;
}, never, Scope>

makeDispatcher

unstable

Since v4.0.0

Acquires a new Undici Agent dispatcher and destroys it when the enclosing scope is finalized.

Signature

declare const makeDispatcher: Effect.Effect<Undici.Dispatcher, never, Scope.Scope>

makeDispatcherOptions

unstable

Since v4.0.5

Acquires a new Undici Agent dispatcher configured with the supplied options and destroys it when the enclosing scope is finalized.

When to use

Use to control how the Undici client connects, for example to send every request over a unix domain socket or to present a client certificate.

Details

The options are passed to new Agent(options). Connection settings live under connect:

connect: { socketPath } dials a unix domain socket (or a Windows named pipe) instead of TCP. The request URL still supplies the Host header and path, so any origin such as http://localhost works.
connect: { ca, cert, key, servername, rejectUnauthorized } configures TLS for https: origins, including mutual TLS.

makeUndici sets headersTimeout and bodyTimeout on every request, so timeouts given here are overridden. Use Effect.timeout instead.

Signature

declare function makeDispatcherOptions(options?: any): Effect<Dispatcher, never, Scope>

Services

Dispatcher

unstable

Since v4.0.0

Service tag for the Undici Dispatcher used by the Undici-backed HTTP client.

Signature

declare class Dispatcher extends Shape<"@effect/platform-node/NodeHttpClient/Dispatcher", Dispatcher, this> {
  constructor(_: never);
}

Fetch

unstable

Since v4.0.0

Context 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>

HttpAgent

unstable

Since v4.0.0

Service tag for the paired Node http and https agents used by the node:http-backed HTTP client.

Signature

declare class HttpAgent extends Shape<"@effect/platform-node/NodeHttpClient/HttpAgent", {
  readonly http: Agent;
  readonly https: Agent;
}, this> {
  constructor(_: never);
}

RequestInit

unstable

Since v4.0.0

Service 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.

Signature

declare class RequestInit extends RequestInit_base {
  constructor(_: never);
}

UndiciOptions

unstable

Since v4.0.0

Fiber reference containing default Undici request options applied to requests sent by makeUndici.

Signature

declare const UndiciOptions: Reference<RequestOptions>