fabian-hiller
Decode FormData
When the values of your form are encoded to FormData, for example to send them to a server via HTTP, some information is lost. Using this library, you can decode FormData into a JavaScript object and supplement the information that was lost during encoding.
This library is especially useful in combination with progressively enhanced forms via actions in fullstack frameworks such as Next.js, Nuxt, Remix, SvelteKit, SolidStart, and Qwik. Furthermore, you can validate and type the decoded data afterwards with a schema library like Valibot or Zod.
Installation
This library is available for Node, Bun and Deno.
npm
npm install decode-formdata # npm
yarn add decode-formdata # yarn
pnpm add decode-formdata # pnpm
bun add decode-formdata # bunimport { decode } from 'decode-formdata';Deno
import { decode } from 'https://deno.land/x/decode_formdata/mod.ts';How it works
FormData stores the names of your fields and their values. However, there is a problem. Only strings and files are accepted as values, but complex forms can contain booleans, strings and dates. This leads to the fact that the boolean value true must be mapped with "on" and false values are simply ignored. Numbers and dates are also converted to strings.
Another problem are objects and arrays, which are usually mapped using dot and bracket notation. For example, the input field <input name="todos.0.label" /> should map to the object { todos: [{ label: "" }] }. By telling decode where arrays, booleans, dates, files, and numbers are located, the function can decode your FormData back into a complex JavaScript object.
Both dot and bracket notation are supported for arrays.
Consider the following form to add a new product to an online store:
<form enctype="multipart/form-data" method="post">
<!-- Product -->
<input name="title" type="text" />
<input name="price" type="number" />
<!-- Metadata -->
<input name="created" type="date" />
<input name="active" type="checkbox" />
<!-- Tags -->
<input name="tags.0" type="text" />
<input name="tags.1" type="text" />
<input name="tags.2" type="text" />
<!-- Images -->
<input name="images.0.title" type="text" />
<input name="images.0.created" type="date" />
<input name="images.0.file" type="file" />
<input name="images.1.title" type="text" />
<input name="images.1.created" type="date" />
<input name="images.1.file" type="file" />
</form>When the form is submitted to the server, the FormData may contain the following entries:
const formEntries = [
['title', 'Red apple'],
['price', '0.89'],
['created', '2023-10-09'],
['active', 'on'],
['tags.0', 'fruit'],
['tags.1', 'healthy'],
['tags.2', 'sweet'],
['images.0.title', 'Close up of an apple'],
['images.0.created', '2023-08-24'],
['images.0.file', Blob],
['images.1.title', 'Our fruit fields at Lake Constance'],
['images.1.created', '2023-08-12'],
['images.1.file', Blob],
];Using decode of this library you can easily decode this data back to JavaScript:
import { decode } from 'decode-formdata';
async function server(formData: FormData) {
const formValues = decode(formData, {
arrays: ['tags', 'images'],
booleans: ['active'],
dates: ['created', 'images.$.created'],
files: ['images.$.file'],
numbers: ['price'],
});
}For deeply nested arrays, use the
$symbol instead of the index when specifying the path to a specifiy data type.
After decoding, formValues now contains the following data:
const formValues = {
title: 'Red apple',
price: 0.89,
created: Date,
active: true,
tags: ['fruit', 'healthy', 'sweet'],
images: [
{
title: 'Close up of an apple',
created: Date,
file: Blob,
},
{
title: 'Our fruit fields at Lake Constance',
created: Date,
file: Blob,
},
],
};Validation
Now, to validate and type your form's data, you can use a schema library like Valibot or Zod.
import { decode } from 'decode-formdata';
import * as v from 'valibot';
// Create product schema
const ProductSchema = v.object({
title: v.string(),
price: v.number(),
created: v.date(),
active: v.boolean(),
tags: v.array(v.string()),
images: v.array(
v.object({
title: v.string(),
created: v.date(),
file: v.blob(),
})
),
});
async function server(formData: FormData) {
try {
// Decode form date
const formValues = decode(formData, {
arrays: ['tags', 'images'],
booleans: ['active'],
dates: ['created', 'images.$.created'],
files: ['images.$.file'],
numbers: ['price'],
});
// Parse form values
const productData = v.parse(ProductSchema, formValues);
// Handle errors
} catch (error) {
// ...
}
}Feedback
Find a bug or have an idea how to improve the library? Please fill out an issue. Together we can make the library even better!
License
This project is available free of charge and licensed under the MIT license.
Note
Both dot and bracket notation are supported for arrays.