Decode FormData to JavaScript Object

Common errors

• TypeError: formData.entries is not a function

  cause `decode` expects an actual `FormData` instance or an object that implements the `entries()` method compatible with the `FormData` interface. This error often occurs when a plain JavaScript object or an incorrect type is passed.
  fix Ensure you are passing a proper `FormData` object to the `decode` function. In Node.js, if not using Node 16+ (which has global `FormData`), you might need to import a polyfill like `@remix-run/node`'s `FormData` or `node-fetch`'s `FormData`.

• Unexpected string value for a field expected to be a number/boolean/date/file.

  cause This typically happens when a field's type (e.g., 'price' as a number) is not correctly specified in the options object passed to `decode`, or the path is incorrect. The library defaults to strings if a type isn't specified.
  fix Carefully review the `options` object in your `decode` call. Ensure that `arrays`, `booleans`, `dates`, `files`, and `numbers` arrays contain the correct paths for all fields that should be converted from their string `FormData` representation to the desired type. Remember to use `$` for nested array paths.

• Arrays are not being parsed correctly or are appearing as objects with numeric keys.

  cause This is a common issue when `decode` is not explicitly told which fields represent arrays. By default, `decode-formdata` will parse `foo.0`, `foo.1` as an object `{ foo: { '0': ..., '1': ... } }` if `foo` is not listed in the `arrays` option.
  fix Add the root path of the array to the `arrays` option in the `decode` function call. For example, if you have fields like `tags.0`, `tags.1`, ensure `tags` is in the `arrays` option: `decode(formData, { arrays: ['tags'], ... })`.

Warnings

• breaking The output behavior for empty strings (`''`), the string `'null'`, and the string `'undefined'` changed. Previously, these might have been treated differently, but now their interpretation might result in different values in the decoded object.
  Fix: Review any code that relies on the exact decoded value of empty strings, 'null', or 'undefined' from `FormData` entries. Update expectations or add explicit `transform` functions if specific previous behavior is desired.
• gotcha Version 0.9.0 introduced a fix for potential prototype pollution by ignoring certain keys during decoding. While this is a security enhancement, it means that `FormData` entries with keys like `__proto__` or `constructor.prototype` will now be explicitly ignored and will not appear in the decoded object. This is a positive change for security but could be a behavioral shift for applications that, for unusual reasons, relied on these keys being processed.
  Fix: No direct fix is needed as this is a security improvement. However, if your application exceptionally relied on `__proto__` or similar keys being present in the decoded object, you will need to adjust your logic or naming conventions.
• gotcha When specifying paths for deeply nested arrays (e.g., `images.$.created`), the `$` symbol is crucial as a wildcard for array indices. Forgetting to use `$` will lead to incorrect type parsing for elements within the array.
  Fix: Always use the `$` wildcard for array indices when defining paths in `arrays`, `booleans`, `dates`, `files`, or `numbers` options that target elements within nested arrays (e.g., `['images.$.file']`).

Install

• npm install decode-formdata npm
• yarn add decode-formdata yarn
• pnpm add decode-formdata pnpm

Imports

• decode
  wrong:

  const decode = require('decode-formdata');

  correct:

  import { decode } from 'decode-formdata';

  The library is primarily designed for ESM usage. While CommonJS `require` might work with transpilation or specific Node configurations, `import` is the idiomatic and recommended way.
• FormDataEntry
  wrong:

  import { FormDataEntry } from 'decode-formdata';

  correct:

  import type { FormDataEntry } from 'decode-formdata';

  `FormDataEntry` is a TypeScript type (or interface since v0.9.0) and should be imported using `import type` to avoid bundling issues and clearly indicate its role.
• FormDataInfo
  wrong:

  import { FormDataInfo } from 'decode-formdata';

  correct:

  import type { FormDataInfo } from 'decode-formdata';

  `FormDataInfo` is a TypeScript type (or interface since v0.9.0) and should be imported using `import type` to avoid bundling issues and clearly indicate its role.

Quickstart

This quickstart demonstrates how to use `decode` to transform a `FormData` object, populated with various data types and nested structures, back into a complex JavaScript object. It highlights specifying array paths, and type conversions for booleans, dates, files, and numbers, mimicking a common server-side form handling scenario.

import { decode } from 'decode-formdata';

// In a Node.js environment, you might need to polyfill FormData
// or use a library like 'form-data-polyfill' if not using Node 16+ which has it globally.
// For browser or modern environments (like Cloudflare Workers, Deno, Bun), FormData is globally available.

async function handleFormSubmission() {
  // Simulate receiving FormData from an HTTP request (e.g., request.formData() in a web framework)
  const formData = new FormData();

  // Populate the FormData object with various types of data and nesting
  formData.append('title', 'Red apple');
  formData.append('price', '0.89');
  formData.append('created', '2023-10-09');
  formData.append('active', 'on'); // 'on' is a common representation for true from checkboxes
  formData.append('tags.0', 'fruit');
  formData.append('tags.1', 'healthy');
  formData.append('tags.2', 'sweet');
  formData.append('images.0.title', 'Close up of an apple');
  formData.append('images.0.created', '2023-08-24');
  formData.append('images.0.file', new Blob(['image-data-1'], { type: 'image/png' }), 'apple.png');
  formData.append('images.1.title', 'Our fruit fields at Lake Constance');
  formData.append('images.1.created', '2023-08-12');
  formData.append('images.1.file', new Blob(['image-data-2'], { type: 'image/jpeg' }), 'fields.jpg');

  // Decode the FormData into a JavaScript object, specifying expected types and array paths
  const formValues = decode(formData, {
    arrays: ['tags', 'images'], // 'tags' is a simple array, 'images' is an array of objects
    booleans: ['active'],       // 'active' field should be parsed as a boolean
    dates: ['created', 'images.$.created'], // 'created' and 'images[i].created' fields as Date objects
    files: ['images.$.file'],   // 'images[i].file' fields as File/Blob objects
    numbers: ['price'],         // 'price' field as a number
  });

  console.log('Decoded Form Values:', formValues);

  // Expected output structure:
  // {
  //   title: 'Red apple',
  //   price: 0.89,
  //   created: <Date object for 2023-10-09>,
  //   active: true,
  //   tags: ['fruit', 'healthy', 'sweet'],
  //   images: [
  //     {
  //       title: 'Close up of an apple',
  //       created: <Date object for 2023-08-24>,
  //       file: <Blob object for apple.png>
  //     },
  //     {
  //       title: 'Our fruit fields at Lake Constance',
  //       created: <Date object for 2023-08-12>,
  //       file: <Blob object for fields.jpg>
  //     }
  //   ]
  // }
}

handleFormSubmission();