object-to-formdata

What is object-to-formdata?

The object-to-formdata npm package is a utility that converts JavaScript objects into FormData instances. This is particularly useful for sending data via HTTP requests, especially when dealing with file uploads or complex nested objects.

What are object-to-formdata's main functionalities?

Basic Object to FormData Conversion

This feature allows you to convert a simple JavaScript object into a FormData instance. The code sample demonstrates converting an object with basic key-value pairs into FormData.

const objectToFormData = require('object-to-formdata');
const obj = { name: 'John', age: 30 };
const formData = objectToFormData(obj);
console.log([...formData.entries()]);

Nested Object Conversion

This feature supports converting nested objects into FormData. The code sample shows how a nested object structure is handled and converted.

const objectToFormData = require('object-to-formdata');
const obj = { user: { name: 'John', age: 30 }, active: true };
const formData = objectToFormData(obj);
console.log([...formData.entries()]);

Array Handling

This feature allows arrays within objects to be converted into FormData. The code sample demonstrates converting an object containing an array into FormData.

const objectToFormData = require('object-to-formdata');
const obj = { tags: ['node', 'javascript', 'npm'] };
const formData = objectToFormData(obj);
console.log([...formData.entries()]);

File Uploads

This feature supports file uploads by converting file streams into FormData. The code sample shows how to include a file in the object and convert it into FormData.

const objectToFormData = require('object-to-formdata');
const fs = require('fs');
const obj = { file: fs.createReadStream('path/to/file.txt') };
const formData = objectToFormData(obj);
console.log([...formData.entries()]);

Other packages similar to object-to-formdata

form-data

The form-data package is a module to create readable 'multipart/form-data' streams. It is more low-level compared to object-to-formdata and requires manual handling of data structures, but it offers more control over the form data creation process.

axios

Axios is a popular HTTP client that supports sending FormData directly. While it is not specifically designed for converting objects to FormData, it can handle FormData instances and is often used in conjunction with other utilities like object-to-formdata.

formdata-polyfill

The formdata-polyfill package is a polyfill for the FormData API, providing a consistent implementation across different environments. It does not convert objects to FormData directly but ensures that FormData is available and works as expected in environments that do not support it natively.

README

object-to-formdata

Convenient JavaScript function that serializes Objects to FormData instances.

Install

npm install object-to-formdata

Usage

NOTE: STARTING WITH VERSION 4.0.0, THE NAMED EXPORT HAS CHANGED!

NOTE: STARTING WITH VERSION 3.0.0, THERE IS NO DEFAULT EXPORT!

import { serialize } from 'object-to-formdata';

const object = {
  /**
   * key-value mapping
   * values can be primitives or objects
   */
};

const options = {
  /**
   * include array indices in FormData keys
   * defaults to false
   */
  indices: false,

  /**
   * treat null values like undefined values and ignore them
   * defaults to false
   */
  nullsAsUndefineds: false,

  /**
   * convert true or false to 1 or 0 respectively
   * defaults to false
   */
  booleansAsIntegers: false,

  /**
   * store arrays even if they're empty
   * defaults to false
   */
  allowEmptyArrays: false,

  /**
   * don't include array notation in FormData keys for any Attributes excepted Files in arrays
   * defaults to false
   */
  noAttributesWithArrayNotation: false,

  /**
   * don't include array notation in FormData keys for Files in arrays
   * defaults to false
   */
  noFilesWithArrayNotation: false,

  /**
   * use dots instead of brackets for object notation in FormData keys
   * defaults to false
   */
  dotsForObjectNotation: false,
};

const formData = serialize(
  object,
  options, // optional
  existingFormData, // optional
  keyPrefix, // optional
);

console.log(formData);