Class FormParser

The FormParser is a specialized parser designed to safely extract and validate values from a FormData object. It provides methods to retrieve form fields in a type-safe manner, ensuring that required fields are present and properly typed.

This parser is particularly useful when handling form submissions, such as in a Remix action, where structured validation of form data is necessary.

Usage

FormParser wraps the FormData object and provides methods to:

Check for the presence of form fields (has).
Retrieve values as strings, files, booleans, or arrays of these types.
Ensure that required fields are present, throwing errors if they are missing or of the wrong type.

The parser uses custom error types (MissingKeyError, InvalidTypeError, InvalidInstanceOfError) to simplify debugging and enforce validation rules.

How It Works

Methods like string, file, and boolean validate and return the form data in the correct type.
For multiple values (e.g., checkboxes or multi-select fields), stringArray and fileArray can be used to retrieve arrays of values.
Booleans are specifically treated such that a field with the value "on" is considered true, and all others are false.

Example

let formParser = new FormParser(formData);
// Retrieves the "username" field as a string.
formParser.string("username");
// Returns true if "subscribe" is "on" (checkbox checked).
formParser.boolean("subscribe");
// Retrieves the "avatar" field as a File object.
formParser.file("avatar");
// Retrieves multiple "hobbies" values as strings.
formParser.stringArray("hobbies");

Hierarchy (View Summary)

Parser<FormData>
- FormParser

Index

Constructors

constructor

new FormParser(value: FormData): FormParser
Parameters
- value: FormData
Returns FormParser
Inherited from Parser.constructor
- Defined in src/lib/parser.ts:52

Properties

`Protected`value

value: FormData

Methods

boolean

boolean(key: string): boolean
Returns true if the value of the specified field is "on", otherwise false.
Parameters
- key: string
  The name of the form field.
Returns boolean
A boolean representation of the form field value.
- Defined in src/lib/form-parser.ts:96

file

file(key: string): File
Retrieves the value of the specified form field as a File object.
Parameters
- key: string
  The name of the form field.
Returns File
The File object associated with the key.

Throws
If the key is missing from the form data.

Throws
If the value is not a File object.
- Defined in src/lib/form-parser.ts:124

fileArray

fileArray(key: string): File[]
Retrieves all File objects associated with the specified form field as an array.
Parameters
- key: string
  The name of the form field.
Returns File[]
An array of File objects associated with the key.
- Defined in src/lib/form-parser.ts:149

get

get(key: string): unknown
Retrieves the value of the specified form field.
Parameters
- key: string
  The name of the form field.
Returns unknown
The value associated with the key, or throws if it doesn't exist.

Throws
If the key is missing from the form data.
- Defined in src/lib/form-parser.ts:56

getAll

getAll(key: string): FormDataEntryValue[]
Retrieves all values associated with the specified form field as an array.
Parameters
- key: string
  The name of the form field.
Returns FormDataEntryValue[]
An array of values associated with the key.

Throws
If the key is missing from the form data.
- Defined in src/lib/form-parser.ts:69

has

has(key: string): boolean
Checks if the given key exists in the FormData.
Parameters
- key: string
  The name of the form field.
Returns boolean
true if the key exists, otherwise false.
- Defined in src/lib/form-parser.ts:45

number

number(key: string): number
Retrieves the value of the specified form field as a number.
Parameters
- key: string
  The name of the form field.
Returns number
The number value associated with the key.

Throws
If the key is missing from the form data.

Throws
If the value is not a valid number.

Throws
If the value cannot be coerced to a number.
- Defined in src/lib/form-parser.ts:163

set

set(key: string, value: string | File | Blob): void
Sets the value of a form field.

If the key already exists, the value is replaced with the new value.
Parameters
- key: string
  The name of the form field.
- value: string | File | Blob
  A string, Blob, or File to set as the value for the key.
Returns void
Example
```
parser.set("username", "johndoe");
```
- Defined in src/lib/form-parser.ts:85

string

string(key: string): string
Retrieves the value of the specified form field as a string.
Parameters
- key: string
  The name of the form field.
Returns string
The string value associated with the key.

Throws
If the key is missing from the form data.

Throws
If the value is not a string.
- Defined in src/lib/form-parser.ts:110

stringArray

stringArray(key: string): string[]
Retrieves all string values associated with the specified form field as an array.
Parameters
- key: string
  The name of the form field.
Returns string[]
An array of string values associated with the key.
- Defined in src/lib/form-parser.ts:137

valueOf

valueOf(): FormData
Returns FormData
Inherited from Parser.valueOf
- Defined in src/lib/parser.ts:54

Class FormParser

Usage

How It Works

Example

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns FormParser

Properties

Protectedvalue

Methods

boolean

Parameters

Returns boolean

file

Parameters

Returns File

Throws

Throws

fileArray

Parameters

Returns File[]

get

Parameters

Returns unknown

Throws

getAll

Parameters

Returns FormDataEntryValue[]

Throws

has

Parameters

Returns boolean

number

Parameters

Returns number

Throws

Throws

Throws

set

Parameters

Returns void

Example

string

Parameters

Returns string

Throws

Throws

stringArray

Parameters

Returns string[]

valueOf

Returns FormData

Settings

On This Page

`Protected`value