HttpBody.ts

HttpBody.ts overview

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.

Since v4.0.0

---

Exports Grouped by Category

• constants
  • empty
• constructors
  • file
  • fileFromInfo
  • formData
  • formDataRecord
  • json
  • jsonSchema
  • jsonUnsafe
  • raw
  • stream
  • text
  • uint8Array
  • urlParams
• errors
  • ErrorReason (type alias)
  • HttpBodyError (class)
    • [HttpBodyErrorTypeId] (property)
• models
  • Empty (class)
    • toJSON (method)
    • _tag (property)
  • FormData (class)
    • toJSON (method)
    • _tag (property)
    • contentType (property)
    • contentLength (property)
    • formData (property)
  • FormDataCoercible (type alias)
  • FormDataInput (type alias)
  • HttpBody (type alias)
  • Raw (class)
    • toJSON (method)
    • _tag (property)
    • body (property)
    • contentType (property)
    • contentLength (property)
  • Stream (class)
    • toJSON (method)
    • _tag (property)
    • stream (property)
    • contentType (property)
    • contentLength (property)
  • Uint8Array (class)
    • toJSON (method)
    • _tag (property)
    • body (property)
    • contentType (property)
    • contentLength (property)
• refinements
  • isHttpBody
• utils
  • HttpBody (namespace)
    • Proto (interface)
    • FileLike (interface)

---

constants

empty

Provides the singleton empty HTTP body.

When to use

Use when you need an HTTP body value that represents no body content.

Signature

declare const empty: Empty

Source

Since v4.0.0

constructors

file

Creates a streaming HTTP body for a file path.

Details

The effect requires FileSystem, stats the file to set the content length, and can fail with PlatformError.

Signature

declare const file: (
  path: string,
  options?: {
    readonly bytesToRead?: FileSystem.SizeInput | undefined
    readonly chunkSize?: FileSystem.SizeInput | undefined
    readonly offset?: FileSystem.SizeInput | undefined
    readonly contentType?: string | undefined
  }
) => Effect.Effect<Stream, PlatformError.PlatformError, FileSystem.FileSystem>

Source

Since v4.0.0

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 as the content length, and can fail with PlatformError.

Signature

declare const fileFromInfo: (
  path: string,
  info: FileSystem.File.Info,
  options?: {
    readonly bytesToRead?: FileSystem.SizeInput | undefined
    readonly chunkSize?: FileSystem.SizeInput | undefined
    readonly offset?: FileSystem.SizeInput | undefined
    readonly contentType?: string | undefined
  }
) => Effect.Effect<Stream, PlatformError.PlatformError, FileSystem.FileSystem>

Source

Since v4.0.0

formData

Wraps a Web FormData value as an HTTP body.

Signature

declare const formData: (body: globalThis.FormData) => FormData

Source

Since v4.0.0

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 const formDataRecord: (entries: FormDataInput) => FormData

Source

Since v4.0.0

json

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 const json: (body: unknown, contentType?: string) => Effect.Effect<Uint8Array, HttpBodyError>

Source

Since v4.0.0

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 const jsonSchema: <S extends Schema.Constraint>(
  schema: S,
  options?: ParseOptions | undefined
) => (body: S["Type"], contentType?: string) => Effect.Effect<Uint8Array, HttpBodyError, S["EncodingServices"]>

Source

Since v4.0.0

jsonUnsafe

Creates a JSON HTTP body using JSON.stringify, throwing if serialization fails.

Details

The content type defaults to application/json.

Signature

declare const jsonUnsafe: (body: unknown, contentType?: string) => Uint8Array

Source

Since v4.0.0

raw

Creates a raw HTTP body from an arbitrary value and optional contentType and contentLength metadata.

Signature

declare const raw: (
  body: unknown,
  options?: { readonly contentType?: string | undefined; readonly contentLength?: number | undefined } | undefined
) => Raw

Source

Since v4.0.0

stream

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 const stream: (
  body: Stream_.Stream<globalThis.Uint8Array, unknown>,
  contentType?: string,
  contentLength?: number
) => Stream

Source

Since v4.0.0

text

Creates a UTF-8 encoded text HTTP body.

Details

The content type defaults to text/plain.

Signature

declare const text: (body: string, contentType?: string) => Uint8Array

Source

Since v4.0.0

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 const uint8Array: (body: globalThis.Uint8Array, contentType?: string) => Uint8Array

Source

Since v4.0.0

urlParams

Creates an application/x-www-form-urlencoded HTTP body from UrlParams.

Signature

declare const urlParams: (urlParams: UrlParams.UrlParams, contentType?: string) => Uint8Array

Source

Since v4.0.0

errors

ErrorReason (type alias)

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
    }

Source

Since v4.0.0

HttpBodyError (class)

Error produced while constructing an HTTP body from JSON or schema-encoded input.

Signature

declare class HttpBodyError

Source

Since v4.0.0

[HttpBodyErrorTypeId] (property)

Marks this value as an HTTP body error for runtime guards.

Signature

readonly [HttpBodyErrorTypeId]: "~effect/http/HttpBody/HttpBodyError"

Source

Since v4.0.0

models

Empty (class)

HTTP body variant representing the absence of request content.

Signature

declare class Empty

Source

Since v4.0.0

toJSON (method)

Signature

declare const toJSON: () => unknown

Source

_tag (property)

Signature

readonly _tag: "Empty"

Source

FormData (class)

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 {
  constructor(formData: globalThis.FormData)
}

Source

Since v4.0.0

toJSON (method)

Signature

declare const toJSON: () => unknown

Source

_tag (property)

Signature

readonly _tag: "FormData"

Source

contentType (property)

Signature

readonly contentType: undefined

Source

contentLength (property)

Signature

readonly contentLength: undefined

Source

formData (property)

Signature

readonly formData: globalThis.FormData

Source

FormDataCoercible (type alias)

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

Source

Since v4.0.0

FormDataInput (type alias)

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

Source

Since v4.0.0

HttpBody (type alias)

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

Source

Since v4.0.0

Raw (class)

HTTP body variant containing an arbitrary runtime body value with optional content metadata.

Signature

declare class Raw {
  constructor(body: unknown, contentType: string | undefined, contentLength: number | undefined)
}

Source

Since v4.0.0

toJSON (method)

Signature

declare const toJSON: () => unknown

Source

_tag (property)

Signature

readonly _tag: "Raw"

Source

body (property)

Signature

readonly body: unknown

Source

contentType (property)

Signature

readonly contentType: string | undefined

Source

contentLength (property)

Signature

readonly contentLength: number | undefined

Source

Stream (class)

HTTP body variant backed by a stream of Uint8Array chunks.

Signature

declare class Stream {
  constructor(
    stream: Stream_.Stream<globalThis.Uint8Array, unknown>,
    contentType: string,
    contentLength: number | undefined
  )
}

Source

Since v4.0.0

toJSON (method)

Signature

declare const toJSON: () => unknown

Source

_tag (property)

Signature

readonly _tag: "Stream"

Source

stream (property)

Signature

readonly stream: Stream_.Stream<globalThis.Uint8Array<ArrayBufferLike>, unknown, never>

Source

contentType (property)

Signature

readonly contentType: string

Source

contentLength (property)

Signature

readonly contentLength: number | undefined

Source

Uint8Array (class)

HTTP body variant backed by a Uint8Array.

Details

It stores the bytes, content type, and byte length.

Signature

declare class Uint8Array {
  constructor(body: globalThis.Uint8Array, contentType: string, contentLength: number)
}

Source

Since v4.0.0

toJSON (method)

Signature

declare const toJSON: () => unknown

Source

_tag (property)

Signature

readonly _tag: "Uint8Array"

Source

body (property)

Signature

readonly body: globalThis.Uint8Array<ArrayBufferLike>

Source

contentType (property)

Signature

readonly contentType: string

Source

contentLength (property)

Signature

readonly contentLength: number

Source

refinements

isHttpBody

Returns true if the provided value is an HttpBody.

Signature

declare const isHttpBody: (u: unknown) => u is HttpBody

Source

Since v4.0.0

utils

HttpBody (namespace)

Namespace containing type-level members associated with HttpBody.

Source

Since v4.0.0

Proto (interface)

Common protocol implemented by all HTTP body variants.

Details

It carries the variant tag plus optional contentType and contentLength metadata.

Signature

export interface Proto extends Inspectable.Inspectable {
  readonly [TypeId]: typeof TypeId
  readonly _tag: string
  readonly contentType?: string | undefined
  readonly contentLength?: number | undefined
}

Source

Since v4.0.0

FileLike (interface)

Minimal Web File-like shape used by HTTP helpers that need file metadata.

Signature

export interface FileLike {
  readonly name: string
  readonly lastModified: number
  readonly size: number
  readonly stream: () => unknown
  readonly type: string
}

Source

Since v4.0.0