HttpApiSchema.ts

HttpApiSchema.ts overview

Attaches HTTP API metadata to Effect Schema values.

This module is the schema-side bridge for HttpApi endpoint builders, generated clients, and OpenAPI support. It does not define routes or perform IO. Instead, the helpers annotate schemas so the surrounding HTTP API tooling can choose response status codes, content types, body codecs, multipart handling, and no-body response behavior.

Since v4.0.0

---

Exports Grouped by Category

• Empty
  • Accepted
  • Created
  • Empty
  • NoContent
• constructors
  • StreamSse
  • StreamUint8Array
• encoding
  • asFormUrlEncoded
  • asJson
  • asMultipart
  • asMultipartStream
  • asNoContent
  • asText
  • asUint8Array
• models
  • Accepted (interface)
  • Created (interface)
  • Encoding (type alias)
  • NoContent (interface)
  • PayloadEncoding (type alias)
  • ResponseEncoding (type alias)
  • SseEventFromData (interface)
  • StreamSchema (type alias)
  • StreamSse (interface)
  • StreamSseMode (type alias)
  • StreamUint8Array (interface)
• predicates
  • isNoContent
• schemas
  • asMultipart (interface)
  • asMultipartStream (interface)
  • asNoContent (interface)
• status
  • StatusLiteral (type alias)
  • status
• type IDs
  • MultipartStreamTypeId
  • MultipartStreamTypeId (type alias)
  • MultipartTypeId
  • MultipartTypeId (type alias)

---

Empty

Accepted

Schema for empty HTTP responses with status code 202.

Signature

declare const Accepted: Accepted

Source

Since v4.0.0

Created

Schema for empty HTTP responses with status code 201.

Signature

declare const Created: Created

Source

Since v4.0.0

Empty

Creates a void schema with the given HTTP status code. This is used to represent empty responses with a specific status code.

See

• NoContent for the predefined 204 no content schema.

Signature

declare const Empty: (code: number) => Schema.Void

Source

Since v4.0.0

NoContent

Schema for empty HTTP responses with status code 204.

Signature

declare const NoContent: NoContent

Source

Since v4.0.0

constructors

StreamSse

Creates a Server-Sent Events streaming success response schema.

Signature

declare const StreamSse: {
  <Events extends Sse.EventCodec, Error extends Schema.Constraint = Schema.Never>(options: {
    readonly contentType?: string | undefined
    readonly events: Events
    readonly error?: Error | undefined
  }): StreamSse<Events, Error, Events["Type"]>
  <Data extends Schema.Constraint, Error extends Schema.Constraint = Schema.Never>(options: {
    readonly contentType?: string | undefined
    readonly data: Data
    readonly error?: Error | undefined
  }): StreamSse<SseEventFromData<Data>, Error, Data["Type"]>
}

Source

Since v4.0.0

StreamUint8Array

Creates a streaming Uint8Array success response schema.

Signature

declare const StreamUint8Array: (options?: { readonly contentType?: string | undefined }) => StreamUint8Array

Source

Since v4.0.0

encoding

asFormUrlEncoded

Marks a schema as an application/x-www-form-urlencoded payload or response.

Details

The schema’s encoded side must be a record of strings.

Signature

declare const asFormUrlEncoded: (options?: {
  readonly contentType?: string
}) => <S extends Schema.Top>(self: S) => S["Rebuild"]

Source

Since v4.0.0

asJson

Marks a schema as a JSON payload / response.

Signature

declare const asJson: (options?: { readonly contentType?: string }) => <S extends Schema.Top>(self: S) => S["Rebuild"]

Source

Since v4.0.0

asMultipart

Marks a schema as a multipart payload.

See

• asMultipartStream for a multipart stream payload.

Signature

declare const asMultipart: (
  options?: Multipart_.withLimits.Options
) => <S extends Schema.Top>(self: S) => asMultipart<S>

Source

Since v4.0.0

asMultipartStream

Marks a schema as a multipart stream payload.

See

• asMultipart for a buffered multipart payload.

Signature

declare const asMultipartStream: (
  options?: Multipart_.withLimits.Options
) => <S extends Schema.Top>(self: S) => asMultipartStream<S>

Source

Since v4.0.0

asNoContent

Marks a schema as a no-content response while preserving a decoded client value.

Details

The server encodes the response as void; generated clients call decode to produce the schema’s decoded value when the response has no body.

See

• NoContent for a void schema with the status code 204.
• Empty for creating a void schema with a specific status code.

Signature

declare const asNoContent: <S extends Schema.Constraint>(options: {
  readonly decode: LazyArg<S["Type"]>
}) => (self: S) => asNoContent<S>

Source

Since v4.0.0

asText

Marks a schema as a text payload / response.

Details

The schema encoded side must be a string.

Signature

declare const asText: (options?: {
  readonly contentType?: string
}) => <S extends Schema.Top & { readonly Encoded: string }>(self: S) => S["Rebuild"]

Source

Since v4.0.0

asUint8Array

Marks a schema as a binary payload / response.

Details

The schema encoded side must be a Uint8Array.

Signature

declare const asUint8Array: (options?: {
  readonly contentType?: string
}) => <S extends Schema.Top & { readonly Encoded: Uint8Array }>(self: S) => S["Rebuild"]

Source

Since v4.0.0

models

Accepted (interface)

Type of the Accepted schema, a void schema annotated with HTTP status code 202.

Signature

export interface Accepted extends Schema.Void {}

Source

Since v4.0.0

Created (interface)

Type of the Created schema, a void schema annotated with HTTP status code 201.

Signature

export interface Created extends Schema.Void {}

Source

Since v4.0.0

Encoding (type alias)

HTTP API body encoding metadata used by payloads and responses.

Signature

type Encoding = PayloadEncoding | ResponseEncoding

Source

Since v4.0.0

NoContent (interface)

Type of the NoContent schema, a void schema annotated with HTTP status code 204.

Signature

export interface NoContent extends Schema.Void {}

Source

Since v4.0.0

PayloadEncoding (type alias)

HTTP API request payload encoding metadata.

Signature

type PayloadEncoding =
  | {
      readonly _tag: "Multipart"
      readonly mode: "buffered" | "stream"
      readonly contentType: string
      readonly limits?: Multipart_.withLimits.Options | undefined
    }
  | {
      readonly _tag: "Json" | "FormUrlEncoded" | "Uint8Array" | "Text"
      readonly contentType: string
    }

Source

Since v4.0.0

ResponseEncoding (type alias)

HTTP API response body encoding metadata.

Signature

type ResponseEncoding = {
  readonly _tag: "Json" | "FormUrlEncoded" | "Uint8Array" | "Text"
  readonly contentType: string
}

Source

Since v4.0.0

SseEventFromData (interface)

Event schema produced when StreamSse is constructed from a JSON data schema.

Signature

export interface SseEventFromData<Data extends Schema.Constraint> extends Schema.Codec<
  {
    readonly id: string | undefined
    readonly event: string
    readonly data: Data["Type"]
  },
  {
    readonly id?: string | undefined
    readonly event?: string | undefined
    readonly data: string
  },
  Data["DecodingServices"],
  Data["EncodingServices"]
> {}

Source

Since v4.0.0

StreamSchema (type alias)

Schema for a streaming HTTP API success response.

Signature

type StreamSchema = StreamSse<Sse.EventCodec, Schema.Top, unknown> | StreamUint8Array

Source

Since v4.0.0

StreamSse (interface)

Schema for a Server-Sent Events success response.

Details

events describes successful application events emitted by the stream, and error describes typed stream failures that will be encoded by later endpoint/server/client integrations using the reserved failure event. If error is omitted, it defaults to Schema.Never. When StreamSse is constructed from data, handlers and clients expose raw data values while the server and client still use an SSE event schema internally.

Signature

export interface StreamSse<
  Events extends Sse.EventCodec,
  Error extends Schema.Constraint,
  Value = Events["Type"]
> extends Schema.BottomLazy<SchemaAST.Declaration, StreamSse<Events, Error, Value>> {
  readonly Type: Stream.Stream<Value, Error["Type"], never>
  readonly Encoded: Stream.Stream<Value, Error["Type"], never>
  readonly DecodingServices: Events["DecodingServices"] | Error["DecodingServices"]
  readonly EncodingServices: Events["EncodingServices"] | Error["EncodingServices"]
  readonly Rebuild: StreamSse<Events, Error, Value>
  readonly "~type.make.in": Stream.Stream<Value, Error["Type"], never>
  readonly "~type.make": Stream.Stream<Value, Error["Type"], never>
  readonly Iso: Stream.Stream<Value, Error["Type"], never>
  readonly [StreamSchemaTypeId]: typeof StreamSchemaTypeId
  readonly _tag: "StreamSse"
  readonly mode: "sse"
  readonly sseMode: StreamSseMode
  readonly contentType: string
  readonly events: Events
  readonly error: Error
  readonly "~Value"?: Value | undefined
}

Source

Since v4.0.0

StreamSseMode (type alias)

Mode describing whether an SSE stream emits full events or raw data values.

Signature

type StreamSseMode = "events" | "data"

Source

Since v4.0.0

StreamUint8Array (interface)

Schema for a streaming Uint8Array success response.

Details

This declaration stores the response content type for later endpoint, server, client, and OpenAPI integrations. It is intentionally separate from the buffered asUint8Array response encoding.

Signature

export interface StreamUint8Array extends Schema.Bottom<
  Stream.Stream<Uint8Array, unknown, never>,
  Stream.Stream<Uint8Array, unknown, never>,
  never,
  never,
  SchemaAST.Declaration,
  StreamUint8Array
> {
  readonly Rebuild: StreamUint8Array
  readonly [StreamSchemaTypeId]: typeof StreamSchemaTypeId
  readonly _tag: "StreamUint8Array"
  readonly mode: "uint8array"
  readonly contentType: string
}

Source

Since v4.0.0

predicates

isNoContent

Returns true when a schema AST represents a no-content response.

Details

The check succeeds for direct void schemas and schemas whose encoded or transformation target is void.

Signature

declare const isNoContent: (ast: SchemaAST.AST) => boolean

Source

Since v4.0.0

schemas

asMultipart (interface)

Schema type returned by asMultipart for buffered multipart payloads.

Signature

export interface asMultipart<S extends Schema.Top> extends Schema.brand<S["Rebuild"], MultipartTypeId> {}

Source

Since v4.0.0

asMultipartStream (interface)

Schema type returned by asMultipartStream for streaming multipart payloads.

Signature

export interface asMultipartStream<S extends Schema.Top> extends Schema.brand<S["Rebuild"], MultipartStreamTypeId> {}

Source

Since v4.0.0

asNoContent (interface)

Schema type returned by asNoContent, encoding as void while decoding to the original schema type.

Signature

export interface asNoContent<S extends Schema.Constraint> extends Schema.decodeTo<Schema.toType<S>, Schema.Void> {}

Source

Since v4.0.0

status

StatusLiteral (type alias)

Common HTTP status code literals accepted by status.

Signature

type StatusLiteral = keyof typeof statusCodeByLiteral

Source

Since v4.0.0

status

Sets the HTTP status code of a schema.

Details

This is equivalent to calling .annotate({ httpApiStatus: code }) on the schema. You can pass either a numeric status code (for example, 201) or a common literal name (for example, "Created").

Signature

declare const status: {
  (code: number): { <S extends Schema.Top>(self: S): S["Rebuild"] }
  (code: StatusLiteral): { <S extends Schema.Top>(self: S): S["Rebuild"] }
}

Source

Since v4.0.0

type IDs

MultipartStreamTypeId

Runtime brand key used to mark schemas as streaming multipart payloads.

Signature

declare const MultipartStreamTypeId: "~effect/httpapi/HttpApiSchema/MultipartStream"

Source

Since v4.0.0

MultipartStreamTypeId (type alias)

Type-level brand identifier used by asMultipartStream.

Signature

type MultipartStreamTypeId = typeof MultipartStreamTypeId

Source

Since v4.0.0

MultipartTypeId

Runtime brand key used to mark schemas as buffered multipart payloads.

Signature

declare const MultipartTypeId: "~effect/httpapi/HttpApiSchema/Multipart"

Source

Since v4.0.0

MultipartTypeId (type alias)

Type-level brand identifier used by asMultipart.

Signature

type MultipartTypeId = typeof MultipartTypeId

Source

Since v4.0.0