decode-formdata

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       # bun

import { 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.

Changelog

v0.8.0 (August 20, 2024)

• Add support for array bracket notation (pull request #15)