A surprisingly simple trick: Converting FormData to multipart/form-data string and back using Response

While working on another article about converting various values into ReadableStream, I stumbled upon a neat trick to convert FormData into a multipart/form-data string and back using the Response. Surprisingly, FormData doesn't provide this functionality out of the box. However, by leveraging the methods of Response, we can achieve this quite easily.

I even tried to get assistance from ChatGPT (both 4o and o1-preview), but it couldn't suggest or synthesize this solution, even with hints. Google searches didn't yield any results either. It seems this approach is unknown or little-known, though I don't claim originality. I don't think the ability for such conversion was intentionally designed by the authors of the Response API; it's more of a side effect, which makes the solution even more interesting. So, I decided to write this article to share my findings.

Converting FormData to a multipart/form-data string

Let's suppose we have an instance of FormData:

const formData = new FormData();
formData.set('value', 123);
formData.set(
  'myfile',
  new File(['{"hello":"world"}'], 'demo.json', { type: 'application/json' })
);

Our goal is to obtain a multipart/form-data string from this FormData instance. Common suggestions involve manually serializing FormData into a string or performing complex manipulations via Request, or using a library for it. However, we can simply use the Response constructor, which accepts FormData as the body, and then call its text() method to get the desired string representation:

// FormData -> multipart/form-data string
function convertFormDataToMultipartString(formData) {
  return new Response(formData).text();
}

const multipartString = await convertFormDataToMultipartString(formData);

console.log(multipartString);
// ------WebKitFormBoundaryQi7NBNu0nAmyAhpU
// Content-Disposition: form-data; name="value"
//
// 123
// ------WebKitFormBoundaryQi7NBNu0nAmyAhpU
// Content-Disposition: form-data; name="myfile"; filename="demo.json"
// Content-Type: application/json
//
// {"hello":"world"}
// ------WebKitFormBoundaryQi7NBNu0nAmyAhpU--

If needed, we can also extract additional values like the Content-Type header and the boundary:

// FormData -> multipart/form-data
async function convertFormDataToMultipart(formData) {
  const response = new Response(formData);
  const contentType = response.headers.get('Content-Type');
  const boundary = contentType.match(/boundary=(\S+)/)[1];

  return {
    contentType,
    boundary,
    body: await response.text(),
  };
}

const multipart = await convertFormDataToMultipart(formData);

console.log(multipart);
// {
//   contentType: 'multipart/form-data; boundary=----WebKitFormBoundarybfJIH5LgEGPqNcqt',
//   boundary: '----WebKitFormBoundarybfJIH5LgEGPqNcqt',
//   body: '------WebKitFormBoundarybfJIH5LgEGPqNcqt\r\n...'
// }

Instead of using text(), we can also use other methods like arrayBuffer() to obtain the encoded content of FormData as an ArrayBuffer. The advantage of this type of value is that it's a transferable object and can be efficiently transferred between workers using postMessage() (meaning without copying, unlike a string). The FormData object itself is not transferable.

Converting multipart/form-data string back to FormData

To reverse the process, we again utilize Response, but this time we use its formData() method. A key aspect of this method is that it requires the correct Content-Type header, which must include the multipart/form-data type and the boundary used to separate the parts. If we have the boundary value, we can insert it into the header. However, we might only have the multipart string and nothing else. In that case, we can extract the boundary from the string using a regular expression.

// multipart/form-data string -> FormData
async function convertMultipartStringToFormData(multipartString) {
  const boundary = multipartString.match(/^\s*--(\S+)/)[1];

  return new Response(multipartString, {
    headers: {
      // Without the correct header, the string won't be parsed,
      // and an exception will be thrown on formData() call
      'Content-Type': 'multipart/form-data; boundary=' + boundary,
    },
  }).formData();
}

const restoredFormData = await convertMultipartStringToFormData(multipartString);

console.log([...restoredFormData]);
// [
//   ['value', '123'],
//   ['myfile', File]
// ]

Just like with serializing FormData, we can convert not only strings but also ArrayBuffer, TypedArray, and ReadableStream into FormData, since Response accepts such values as the body value.

Conclusion

One potential downside is that both types of conversions are asynchronous operations. Other than that, the method seems quite reliable and can be used for debugging or when conversion is needed outside of fetch().

This method has wide browser support (it should work in any browser released after 2017). The method is also applicable in Node.js, Deno, and Bun if they support the Response object (i.e., versions where fetch() is available).

I hope you find this approach as intriguing as I did. It's a simple yet effective way to convert FormData to a multipart/form-data string (and not only a string) and back, leveraging the capabilities of the Response API. If you have any thoughts or know of other methods to achieve the same result, feel free to share in the comments!