FileUpload

Summary

A file that was uploaded as part of a multipart/form-data request, passed to a FileUploadHandler as soon as its headers arrive.

Its contents are streamed from the request as you read them, so you can store large uploads without holding them in memory. It has the properties and methods of a File, with these differences:

• Its contents can only be read once, with stream(), bytes(), arrayBuffer(), or text()
• size throws until its contents have been read; limit upload size with maxFileSize
• slice() is not supported
• It is not a File instance, so pass stream() to APIs that read a File natively, like new Response()

The name and type properties are untrusted client input from the submitted multipart metadata; they do not validate the file contents. The name is not sanitized for filesystem use and must not be used directly as a filesystem path, including on files returned in FormData. Generate storage names and validate file contents in your upload handler before using files in application-specific contexts.

Signature

interface FileUpload {
  fieldName: string
  lastModified: number
  name: string
  type: string
  webkitRelativePath: ''
  get [toStringTag](): string
  get size(): number
  arrayBuffer(): Promise<ArrayBuffer>
  bytes(): Promise<Uint8Array<ArrayBuffer>>
  formData(): Promise<FormData>
  json(): Promise<any>
  slice(): never
  stream(): ReadableStream<Uint8Array<ArrayBuffer>>
  text(): Promise<string>
  toString(): never
}

Properties

fieldName

The name of the <input> field used to upload the file.

lastModified

The time the upload was received, in milliseconds since the Unix epoch.

name

The name of the file, from the multipart Content-Disposition header.

type

The media type of the file, from the multipart Content-Type header.

webkitRelativePath

Always an empty string.

Accessors

[toStringTag]

size

The size of the file in bytes. Throws until the file's contents have been read.

Methods

arrayBuffer(): Promise<ArrayBuffer>

Reads the file's contents into an ArrayBuffer.

bytes(): Promise<Uint8Array<ArrayBuffer>>

Reads the file's contents into a Uint8Array.

formData(): Promise<FormData>

Parses the file's contents as form data, using its type as the content type.

json(): Promise<any>

Parses the file's contents as JSON.

slice(): never

Not supported, because the file's contents are streamed from the request.

stream(): ReadableStream<Uint8Array<ArrayBuffer>>

Returns a stream of the file's contents.

text(): Promise<string>

Reads the file's contents as a UTF-8 string.

toString(): never

Throws, so a file upload isn't silently converted to a string by APIs that expect a File, like FormData#append() or new Response().