HttpBody
Describes HTTP request and response bodies before they reach a platform adapter.
HttpBody is the shared body representation used by the HTTP modules. Each variant stores the payload together with metadata that can be known before sending it, such as contentType and contentLength. This module includes body constructors for common payload shapes, support for schema-encoded JSON bodies, streaming and file-backed bodies, and the error type used when body construction fails.
Constants
Constructors
Creates a streaming HTTP body for a file path.
Details
The effect requires FileSystem, stats the file to set the selected content length, and can fail with PlatformError.
Signature
declare function file(
path: string,
options?: {
readonly bytesToRead?: SizeInput;
readonly chunkSize?: SizeInput;
readonly contentType?: string;
readonly offset?: SizeInput;
},
): Effect<Stream, PlatformError, FileSystem>;fileFromInfo
Creates a streaming HTTP body for a file path using already-known file information.
Details
The effect requires FileSystem, uses the provided file size to determine the selected content length, and can fail with PlatformError.
Signature
declare function fileFromInfo(
path: string,
info: Info,
options?: {
readonly bytesToRead?: SizeInput;
readonly chunkSize?: SizeInput;
readonly contentType?: string;
readonly offset?: SizeInput;
},
): Effect<Stream, PlatformError, FileSystem>;Wraps a Web FormData value as an HTTP body.
Signature
declare function formData(body: FormData): FormData;formDataRecord
Creates a FormData HTTP body from a record.
Details
Array fields append each item under the same key; primitive values are stringified, File and Blob values are appended directly, and nullish values are skipped.
Signature
declare function formDataRecord(entries: FormDataInput): FormData;Creates a JSON HTTP body in an Effect.
Details
JSON.stringify failures are captured as HttpBodyError values, and the content type defaults to application/json.
Signature
declare function json(body: unknown, contentType?: string): Effect<Uint8Array, HttpBodyError>;jsonSchema
Creates a JSON body constructor that first encodes values with the schema's JSON codec.
Details
Schema encoding issues and JSON serialization failures are returned as HttpBodyError values.
Signature
declare function jsonSchema<S extends Constraint>(
schema: S,
options?: ParseOptions,
): (
body: S["Type"],
contentType?: string,
) => Effect<Uint8Array, HttpBodyError, S["EncodingServices"]>;jsonUnsafe
Creates a JSON HTTP body using JSON.stringify, throwing if serialization fails.
Details
The content type defaults to application/json.
Signature
declare function jsonUnsafe(body: unknown, contentType?: string): Uint8Array;Creates a raw HTTP body from an arbitrary value and optional contentType and contentLength metadata.
Signature
declare function raw(
body: unknown,
options?: {
readonly contentLength?: number;
readonly contentType?: string;
},
): Raw;Creates a streaming HTTP body from a stream of byte chunks.
Details
The content type defaults to application/octet-stream; content length is optional.
Signature
declare function stream(
body: Stream<Uint8Array<ArrayBufferLike>, unknown>,
contentType?: string,
contentLength?: number,
): Stream;Creates a UTF-8 encoded text HTTP body.
Details
The content type defaults to text/plain.
Signature
declare function text(body: string, contentType?: string): Uint8Array;uint8Array
Creates a byte-array HTTP body.
Details
The content type defaults to application/octet-stream, and the content length is the byte array length.
Signature
declare function uint8Array(body: Uint8Array, contentType?: string): Uint8Array;Creates an application/x-www-form-urlencoded HTTP body from UrlParams.
Signature
declare function urlParams(urlParams: Input, contentType?: string): Uint8Array;Errors
ErrorReason type
Reason for an HttpBodyError.
Details
JsonError represents a JSON.stringify failure; SchemaError represents a schema encoding issue.
Signature
type ErrorReason =
| {
readonly _tag: "JsonError";
}
| {
readonly _tag: "SchemaError";
readonly issue: Issue;
};HttpBodyError
Error produced while constructing an HTTP body from JSON or schema-encoded input.
Signature
declare class HttpBodyError extends YieldableError<this> & {
readonly _tag: "HttpBodyError";
} & Readonly<{
readonly cause?: unknown;
readonly reason: ErrorReason;
}> {
constructor(args: {
readonly cause?: unknown;
readonly reason: ErrorReason;
});
readonly "~effect/http/HttpBody/HttpBodyError": "~effect/http/HttpBody/HttpBodyError";
}Guards
isHttpBody
Returns true if the provided value is an HttpBody.
Signature
declare function isHttpBody(u: unknown): u is HttpBody;Models
HTTP body variant representing the absence of request content.
Signature
declare class Empty extends Proto {
constructor();
readonly _tag: "Empty";
toJSON(): unknown;
}HTTP body variant backed by Web FormData.
Details
The content type and content length are left unset so the runtime can supply multipart boundaries.
Signature
declare class FormData extends Proto {
constructor(formData: FormData);
readonly _tag: "FormData";
readonly contentLength: undefined;
readonly contentType: undefined;
readonly formData: FormData;
toJSON(): unknown;
}FormDataCoercible type
Value that can be appended by formDataRecord.
Details
File and Blob values are appended directly, primitive values are converted to strings, and null or undefined values are skipped.
Signature
type FormDataCoercible =
| string
| number
| boolean
| globalThis.File
| globalThis.Blob
| null
| undefined;FormDataInput type
Record input accepted by formDataRecord.
Details
Each field may be a single coercible value or an array of coercible values.
Signature
type FormDataInput = Record<string, FormDataCoercible | ReadonlyArray<FormDataCoercible>>;Represents an HTTP request body.
Details
Supported variants include empty bodies, raw bodies, byte arrays, FormData, and streams of bytes.
Signature
type HttpBody = Empty | Raw | Uint8Array | FormData | Stream;HTTP body variant containing an arbitrary runtime body value with optional content metadata.
Signature
declare class Raw extends Proto {
constructor(body: unknown, contentType: string | undefined, contentLength: number | undefined);
readonly _tag: "Raw";
readonly body: unknown;
readonly contentLength: number | undefined;
readonly contentType: string | undefined;
toJSON(): unknown;
}HTTP body variant backed by a stream of Uint8Array chunks.
Signature
declare class Stream extends Proto {
constructor(
stream: Stream<Uint8Array<ArrayBufferLike>, unknown>,
contentType: string,
contentLength: number | undefined,
);
readonly _tag: "Stream";
readonly contentLength: number | undefined;
readonly contentType: string;
readonly stream: Stream<Uint8Array<ArrayBufferLike>, unknown>;
toJSON(): unknown;
}Uint8Array
HTTP body variant backed by a Uint8Array.
Details
It stores the bytes, content type, and byte length.
Signature
declare class Uint8Array extends Proto {
constructor(body: Uint8Array, contentType: string, contentLength: number);
readonly _tag: "Uint8Array";
readonly body: Uint8Array;
readonly contentLength: number;
readonly contentType: string;
toJSON(): unknown;
}
Provides the singleton empty HTTP body.
When to use
Use when you need an HTTP body value that represents no body content.