Registry / http-networking / object-to-formdata

object-to-formdata

library4.5.1jsnpmunverified

object-to-formdata is a utility library for JavaScript that efficiently serializes plain JavaScript objects into `FormData` instances, a crucial browser API for sending data via `multipart/form-data` requests. Currently at version 4.5.1, it provides options to control how arrays, nulls, booleans, and object/array notation in keys are handled during serialization. The package is actively maintained with regular updates and bug fixes, indicated by its recent releases. Its primary differentiator is the configurable serialization logic, allowing developers to fine-tune how complex data structures are represented in `FormData` compared to manual construction or simpler serializers.

http-networking serialization

npm install object-to-formdata

github ↗package ↗

INSTALL

IMPORT

SIG · OBJECT-TO-FORMDATA

object-to-formdata

http-networkingjavascriptv4.5.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

serialize

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

✗ import serialize from 'object-to-formdata'; // incorrect since v3

Since version 3.0.0, there is no default export. Version 4.0.0 changed the named export from `formData` to `serialize`.

serialize (CommonJS)

✓ const { serialize } = require('object-to-formdata');

✗ const serialize = require('object-to-formdata'); // incorrect since v3

For CommonJS environments, ensure you destructure the `serialize` function as it's a named export.

FormData (Type)

✓ import type { FormData } from 'object-to-formdata';

The library ships with TypeScript types. While FormData is a global Web API, this might be used for specific internal types if exposed.

Demonstrates basic serialization of a complex JavaScript object, including files, arrays, and nested objects, into a FormData instance using various configuration options, and appending to existing FormData.

import { serialize } from 'object-to-formdata'; const userProfile = { name: 'John Doe', email: 'john.doe@example.com', age: 30, isActive: true, roles: ['admin', 'editor'], address: { street: '123 Main St', city: 'Anytown', zip: '12345' }, avatar: new File([''], 'avatar.png', { type: 'image/png' }) }; const options = { indices: true, // Serialize roles[0]=admin, roles[1]=editor booleansAsIntegers: true, // Serialize isActive=1 nullsAsUndefineds: true, // Ignore null values dotsForObjectNotation: false // Use brackets for objects (address[street]) }; const formData = serialize(userProfile, options); // To see the contents (FormData is not directly iterable by value without special methods): for (const pair of formData.entries()) { console.log(`${pair[0]}: ${pair[1]}`); } // Example of appending to an existing FormData instance const existingData = new FormData(); existingData.append('tenantId', '123-abc'); const combinedFormData = serialize({ metadata: 'important' }, {}, existingData); for (const pair of combinedFormData.entries()) { console.log(`Combined: ${pair[0]}: ${pair[1]}`); }

Debug

Known issues

breakingStarting with version 3.0.0, the package removed its default export. Attempts to import it using `import serialize from 'object-to-formdata'` will fail.

fix

Change your import statement to use named exports: `import { serialize } from 'object-to-formdata';`.

affects: >=3.0.0

breakingVersion 4.0.0 introduced a breaking change by renaming the primary named export from `formData` to `serialize`.

fix

Update your import statement from `import { formData } from 'object-to-formdata';` to `import { serialize } from 'object-to-formdata';`.

affects: >=4.0.0

gotchaBy default, boolean values (`true`/`false`) are serialized as the strings 'true'/'false'. If your backend expects integers (1/0), you need to configure this behavior.

fix

Set the `booleansAsIntegers` option to `true` in the configuration object: `serialize(object, { booleansAsIntegers: true })`.

affects: >=1.0.0

gotchaArrays are serialized with bracket notation by default (e.g., `items[]`). If you need indexed keys (e.g., `items[0]`), or no array notation for files/attributes, specific options are required.

fix

Use the `indices: true` option for indexed array keys, or `noAttributesWithArrayNotation: true` / `noFilesWithArrayNotation: true` to suppress bracket notation for non-file/file attributes respectively.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: (0 , object_to_formdata__WEBPACK_IMPORTED_MODULE_0__.formData) is not a function

Attempting to use the old `formData` named export after upgrading to version 4.0.0 or higher.

fix

The named export was renamed. Change `import { formData } from 'object-to-formdata';` to `import { serialize } from 'object-to-formdata';`.

TypeError: object_to_formdata__WEBPACK_IMPORTED_MODULE_0__.default is not a function

Attempting to import `object-to-formdata` as a default export, which was removed in version 3.0.0.

fix

The package no longer has a default export. Change `import serialize from 'object-to-formdata';` to `import { serialize } from 'object-to-formdata';`.

FormData entries show '[object Object]' for nested objects or arrays instead of serialized keys.

This is not an error but expected browser behavior. `FormData` itself flattens to key-value pairs where values are strings or `File`/`Blob` objects. Nested structures are flattened into keys like `parent[child]` or `array[0]`, not actual nested objects.

fix

The library correctly serializes nested objects and arrays into appropriate `FormData` keys. When inspecting `FormData` via `console.log`, you'll see the flattened key-value pairs, which is how HTTP `multipart/form-data` works. Ensure your backend is configured to parse these nested key structures (e.g., using a library like `multer` in Node.js).

Upgrade

Version history

4.5.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/therealparmesh/object-to-formdata ↗

packagehttps://www.npmjs.com/package/object-to-formdata ↗