Multipart.ts

Multipart.ts overview

Parses and persists HTTP multipart/form-data request bodies.

Multipart turns incoming byte streams into typed form parts. Text parts become decoded fields, while upload parts stay as streamed files until they are collected or written to scoped temporary files. The persisted representation can then be decoded with schemas for handlers that receive fields and uploaded files together. This module also includes multipart error types, schema helpers for persisted files, and parser limit settings.

Since v4.0.0

---

Exports Grouped by Category

• Parsers
  • makeChannel
• configuration
  • makeConfig
• converting
  • collectUint8Array
  • toPersisted
• errors
  • MultipartError (class)
    • fromReason (static method)
    • [MultipartErrorTypeId] (property)
  • MultipartErrorReason (class)
• guards
  • isField
  • isFile
  • isPart
  • isPersistedFile
• models
  • Field (interface)
  • File (interface)
  • Part (type alias)
  • Persisted (interface)
  • PersistedFile (interface)
• references
  • FieldMimeTypes
  • MaxFieldSize
  • MaxFileSize
  • MaxParts
  • limitsServices
• schemas
  • FilesSchema
  • PersistedFileSchema
  • PersistedFileSchema (interface)
  • SingleFileSchema
  • schemaJson
  • schemaPersisted
• type IDs
  • TypeId
• utils
  • Part (namespace)
    • Proto (interface)
  • withLimits (namespace)
    • Options (type alias)

---

Parsers

makeChannel

Creates a channel that parses multipart byte chunks into multipart parts.

Details

The channel consumes non-empty batches of Uint8Array chunks and emits non-empty batches of parsed Part values, failing with MultipartError for parser and limit failures.

Signature

declare const makeChannel: <IE>(
  headers: Record<string, string>
) => Channel.Channel<
  Arr.NonEmptyReadonlyArray<Part>,
  MultipartError | IE,
  void,
  Arr.NonEmptyReadonlyArray<Uint8Array>,
  IE,
  unknown
>

Source

Since v4.0.0

configuration

makeConfig

Builds the low-level multipart parser configuration from request headers and the current fiber context.

Details

Parser limits are read from the multipart references, including maximum parts, field size, file size, total body size, and field MIME type overrides.

Signature

declare const makeConfig: (headers: Record<string, string>) => Effect.Effect<MP.BaseConfig>

Source

Since v4.0.0

converting

collectUint8Array

Runs a channel of byte chunks and collects all output into a single Uint8Array.

Gotchas

This materializes the full content in memory.

Signature

declare const collectUint8Array: <OE, OD, R>(
  self: Channel.Channel<Arr.NonEmptyReadonlyArray<Uint8Array>, OE, OD, unknown, unknown, unknown, R>
) => Effect.Effect<Uint8Array<ArrayBuffer>, OE, R>

Source

Since v4.0.0

toPersisted

Persists a stream of multipart parts into a record.

Details

Text fields are collected as strings, and file parts are written to files in a scoped temporary directory.

Gotchas

Persisted file paths remain valid for the lifetime of the scope.

Signature

declare const toPersisted: (
  stream: Stream.Stream<Part, MultipartError>,
  writeFile?: (path: string, file: File) => Effect.Effect<void, MultipartError, FileSystem.FileSystem>
) => Effect.Effect<Persisted, MultipartError, FileSystem.FileSystem | Path.Path | Scope.Scope>

Source

Since v4.0.0

errors

MultipartError (class)

Error raised while parsing, streaming, or persisting multipart form data.

Details

The reason field contains the concrete MultipartErrorReason.

Signature

declare class MultipartError

Source

Since v4.0.0

fromReason (static method)

Creates a multipart error from a reason tag and optional cause.

Signature

declare const fromReason: (reason: MultipartErrorReason["_tag"], cause?: unknown) => MultipartError

Source

Since v4.0.0

[MultipartErrorTypeId] (property)

Marks this value as a multipart error for runtime guards.

Signature

readonly [MultipartErrorTypeId]: "~effect/http/Multipart/MultipartError"

Source

Since v4.0.0

MultipartErrorReason (class)

Error reason carried by a MultipartError.

Details

It identifies parser and limit failures such as oversized files or fields, too many parts, total body size limits, parse errors, and internal errors.

Signature

declare class MultipartErrorReason

Source

Since v4.0.0

guards

isField

Returns true when a value is a multipart text Field.

Signature

declare const isField: (u: unknown) => u is Field

Source

Since v4.0.0

isFile

Returns true when a value is a multipart File.

Signature

declare const isFile: (u: unknown) => u is File

Source

Since v4.0.0

isPart

Returns true when a value is a multipart Part.

Signature

declare const isPart: (u: unknown) => u is Part

Source

Since v4.0.0

isPersistedFile

Returns true when a value is a persisted multipart file.

Signature

declare const isPersistedFile: (u: unknown) => u is PersistedFile

Source

Since v4.0.0

models

Field (interface)

Multipart form field containing a decoded text value.

Details

The key is the field name, contentType is the part media type, and value is the decoded field content.

Signature

export interface Field extends Part.Proto {
  readonly _tag: "Field"
  readonly key: string
  readonly contentType: string
  readonly value: string
}

Source

Since v4.0.0

File (interface)

Multipart file part.

Gotchas

The file content is exposed as a byte stream. contentEffect collects the full file into memory and should be used only when the file size is acceptable.

Signature

export interface File extends Part.Proto {
  readonly _tag: "File"
  readonly key: string
  readonly name: string
  readonly contentType: string
  readonly content: Stream.Stream<Uint8Array, MultipartError>
  readonly contentEffect: Effect.Effect<Uint8Array, MultipartError>
}

Source

Since v4.0.0

Part (type alias)

A parsed multipart part.

Details

A part is either a text Field or a streamed File.

Signature

type Part = Field | File

Source

Since v4.0.0

Persisted (interface)

Record representation of persisted multipart data.

Details

Field names map to text values, arrays of text values, or arrays of PersistedFile values.

Signature

export interface Persisted {
  readonly [key: string]: ReadonlyArray<PersistedFile> | ReadonlyArray<string> | string
}

Source

Since v4.0.0

PersistedFile (interface)

Multipart file part that has been written to the filesystem.

Details

The path points to the persisted file while the scope used to persist the multipart data remains open.

Signature

export interface PersistedFile extends Part.Proto {
  readonly _tag: "PersistedFile"
  readonly key: string
  readonly name: string
  readonly contentType: string
  readonly path: string
}

Source

Since v4.0.0

references

FieldMimeTypes

Context reference for MIME type fragments that should be parsed as multipart fields instead of files.

Details

The default treats application/json parts as fields.

Signature

declare const FieldMimeTypes: Context.Reference<ReadonlyArray<string>>

Source

Since v4.0.0

MaxFieldSize

Context reference for the maximum size of a multipart field value.

Details

The default limit is 10 MiB.

Signature

declare const MaxFieldSize: Context.Reference<FileSystem.SizeInput>

Source

Since v4.0.0

MaxFileSize

Context reference for the maximum size of a multipart file part.

Details

The default is undefined, meaning no explicit per-file limit.

Signature

declare const MaxFileSize: Context.Reference<FileSystem.SizeInput | undefined>

Source

Since v4.0.0

MaxParts

Context reference for the maximum number of multipart parts allowed.

Details

The default is undefined, meaning no explicit part-count limit.

Signature

declare const MaxParts: Context.Reference<number | undefined>

Source

Since v4.0.0

limitsServices

Creates a context containing multipart parser limit settings.

Details

The context can provide maximum part count, field size, file size, total body size, and MIME types that should be parsed as fields.

Signature

declare const limitsServices: (options: {
  readonly maxParts?: number | undefined
  readonly maxFieldSize?: FileSystem.SizeInput | undefined
  readonly maxFileSize?: FileSystem.SizeInput | undefined
  readonly maxTotalSize?: FileSystem.SizeInput | undefined
  readonly fieldMimeTypes?: ReadonlyArray<string> | undefined
}) => Context.Context<never>

Source

Since v4.0.0

schemas

FilesSchema

Schema for an array of persisted multipart files.

Signature

declare const FilesSchema: Schema.$Array<PersistedFileSchema>

Source

Since v4.0.0

PersistedFileSchema

Schema for persisted multipart files.

Details

The encoded form contains the field key, original file name, content type, and filesystem path.

Signature

declare const PersistedFileSchema: PersistedFileSchema

Source

Since v4.0.0

PersistedFileSchema (interface)

Schema type for persisted multipart files.

Signature

export interface PersistedFileSchema extends Schema.declare<PersistedFile> {}

Source

Since v4.0.0

SingleFileSchema

Schema for exactly one persisted multipart file.

Details

The encoded form is a one-element file array, while the decoded value is the single PersistedFile.

Signature

declare const SingleFileSchema: Schema.decodeTo<PersistedFileSchema, Schema.$Array<PersistedFileSchema>, never, never>

Source

Since v4.0.0

schemaJson

Creates a decoder for a JSON-encoded field in persisted multipart data.

Details

The selected field is parsed from a JSON string and decoded with the supplied schema.

Signature

declare const schemaJson: <A, I, RD, RE>(
  schema: Schema.Codec<A, I, RD, RE>,
  options?: ParseOptions | undefined
) => {
  (field: string): (persisted: Persisted) => Effect.Effect<A, Schema.SchemaError, RD>
  (persisted: Persisted, field: string): Effect.Effect<A, Schema.SchemaError, RD>
}

Source

Since v4.0.0

schemaPersisted

Creates a decoder for persisted multipart data using the supplied schema.

Details

The returned function decodes an unknown input into the schema output and fails with SchemaError when validation fails.

Signature

declare const schemaPersisted: <A, I extends Partial<Persisted>, RD, RE>(
  schema: Schema.Codec<A, I, RD, RE>
) => (input: unknown, options?: ParseOptions) => Effect.Effect<A, Schema.SchemaError, RD>

Source

Since v4.0.0

type IDs

TypeId

Type identifier used to brand multipart part values.

Signature

declare const TypeId: "~effect/http/Multipart"

Source

Since v4.0.0

utils

Part (namespace)

Namespace containing shared multipart part model types.

Source

Since v4.0.0

Proto (interface)

Common protocol implemented by multipart part values.

Details

It provides the multipart type identifier, tag, and inspectable behavior shared by fields, files, and persisted files.

Signature

export interface Proto extends Inspectable.Inspectable {
  readonly [TypeId]: typeof TypeId
  readonly _tag: string
}

Source

Since v4.0.0

withLimits (namespace)

Namespace containing multipart parser limit option types.

Source

Since v4.0.0

Options (type alias)

Options for overriding multipart parser limits.

Details

These settings control maximum part count, field size, file size, total body size, and MIME types that should be treated as fields instead of files.

Signature

type Options = {
  readonly maxParts?: number | undefined
  readonly maxFieldSize?: FileSystem.SizeInput | undefined
  readonly maxFileSize?: FileSystem.SizeInput | undefined
  readonly maxTotalSize?: FileSystem.SizeInput | undefined
  readonly fieldMimeTypes?: ReadonlyArray<string> | undefined
}

Source

Since v4.0.0