FormData#

The FormData class provides a way to construct key/value pairs representing form fields and their values. It is mainly used for building multipart/form-data requests that can include both text and binary data (such as files or images).

In the Scripting app, FormData is fully compatible with the standard Fetch API, allowing you to send data through fetch() with mixed text and file fields.

Definition#

1class FormData {
2  private formData
3  append(name: string, value: string): void
4  append(name: string, value: Data, mimeType: string, filename?: string): void
5  get(name: string): string | Data | null
6  getAll(name: string): any[]
7  has(name: string): boolean
8  delete(name: string): void
9  set(name: string, value: string): void
10  set(name: string, value: Data, filename?: string): void
11  forEach(callback: (value: any, name: string, parent: FormData) => void): void
12  entries(): [string, any][]
13  toJson(): Record<string, any>
14}

Purpose#

FormData is used to:

• Build multipart/form-data requests with text and file fields.
• Upload files (images, documents, audio, etc.) with metadata.
• Replace JSON-based bodies when binary data is included.

Methods#

append(name: string, value: string): void#

append(name: string, value: Data, mimeType: string, filename?: string): void#

Appends a new field to the form. Can be used to add both text and file fields.

Parameters#

Example#

1const form = new FormData()
2form.append("username", "Tom")
3form.append("file", Data.fromFile("/path/to/image.png"), "image/png", "avatar.png")

set(name: string, value: string): void#

set(name: string, value: Data, filename?: string): void#

Sets a form field, replacing any existing field with the same name. Unlike append(), this overwrites previous values.

Example#

1const form = new FormData()
2form.set("message", "Hello world")
3form.set("file", Data.fromFile("/path/to/file.txt"), "text/plain", "note.txt")

get(name: string): string | Data | null#

Retrieves the value of a form field. Returns null if the field does not exist.

Example#

1const form = new FormData()
2form.append("title", "My Post")
3console.log(form.get("title")) // "My Post"

getAll(name: string): any[]#

Returns all values associated with a given field name (useful when using multiple append() calls with the same name).

Example#

1const form = new FormData()
2form.append("tag", "swift")
3form.append("tag", "ios")
4form.append("tag", "scripting")
5
6console.log(form.getAll("tag")) // ["swift", "ios", "scripting"]

has(name: string): boolean#

Checks whether a form field exists.

Example#

1const form = new FormData()
2form.append("username", "Tom")
3
4console.log(form.has("username")) // true
5console.log(form.has("password")) // false

delete(name: string): void#

Deletes the specified field and all of its values.

Example#

1const form = new FormData()
2form.append("title", "Hello")
3form.append("file", Data.fromFile("/path/to/file.txt"), "text/plain")
4
5form.delete("file")

forEach(callback: (value: any, name: string, parent: FormData) => void): void#

Iterates over all form fields and invokes the callback function for each one.

Example#

1const form = new FormData()
2form.append("user", "Tom")
3form.append("age", "25")
4
5form.forEach((value, name) => {
6  console.log(`${name}: ${value}`)
7})

entries(): [string, any][]#

Returns an array of [name, value] pairs for all form fields.

Example#

1const form = new FormData()
2form.append("username", "Tom")
3form.append("age", "25")
4console.log(form.entries())
5// [["username", "Tom"], ["age", "25"]]

toJson(): Record<string, any>#

Converts the form data into a plain JSON object for debugging or logging. If the form contains binary data (Data objects), those fields will be represented as descriptive placeholders instead of raw binary data.

Example#

1const form = new FormData()
2form.append("name", "Tom")
3form.append("photo", Data.fromFile("/path/to/avatar.png"), "image/png", "avatar.png")
4
5console.log(form.toJson())
6// { name: "Tom", photo: "[Data: image/png]" }

Usage Examples#

Example 1 — Upload a File#

1const form = new FormData()
2form.append("file", Data.fromFile("/path/to/image.png"), "image/png", "avatar.png")
3form.append("userId", "1234")
4
5const response = await fetch("https://api.example.com/upload", {
6  method: "POST",
7  body: form,
8})
9
10console.log(await response.json())

Example 2 — Upload Multiple Files#

1const form = new FormData()
2form.append("files", Data.fromFile("/path/to/photo1.jpg"), "image/jpeg", "photo1.jpg")
3form.append("files", Data.fromFile("/path/to/photo2.jpg"), "image/jpeg", "photo2.jpg")
4
5await fetch("https://api.example.com/multi-upload", {
6  method: "POST",
7  body: form,
8})

Example 3 — Mixed Text and File Fields#

1const form = new FormData()
2form.append("title", "Travel Memories")
3form.append("description", "A collection of travel photos.")
4form.append("cover", Data.fromFile("/path/to/cover.png"), "image/png", "cover.png")
5
6const response = await fetch("https://example.com/uploadPost", {
7  method: "POST",
8  body: form,
9})
10
11console.log(await response.text())

Example 4 — Iterating and Debugging#

1const form = new FormData()
2form.append("name", "Alice")
3form.append("file", Data.fromFile("/path/to/file.txt"), "text/plain", "file.txt")
4
5form.forEach((value, name) => {
6  console.log(`${name}:`, value instanceof Data ? "Binary Data" : value)
7})

Relationships with Other Classes#

Notes#

• Automatic Content-Type: When you pass a FormData instance to fetch(), the app automatically sets the correct Content-Type header (with a boundary). Do not manually set it.
• Multiple Fields: Use append() to add multiple values with the same name.
• Binary Uploads: Always provide a MIME type for binary uploads. Otherwise, the data defaults to application/octet-stream.
• JSON Conversion: The toJson() method is intended for debugging and should not be used for actual data transmission.

Summary#

FormData is the core class for building multipart/form-data requests in the Scripting app. It provides a flexible and developer-friendly API for combining text and binary fields, integrating seamlessly with fetch() and Data.

Key Features#

• Fully compatible with the Fetch API
• Supports text and file uploads
• Automatically handles multipart boundaries
• Useful debugging utilities (entries(), toJson())
• Integrates natively with Data, Request, and Response