@octetstream/object-to-form-data

object-to-form-data

Transform an object/collection to FormData. Good to use with then-busboy

Installation

pnpm:

pnpm add @octetstream/object-to-form-data

npm:

npm i @octetstream/object-to-form-data

Usage

import {objectToFormData} from "@octetstream/object-to-form-data"

const object = {
  message: {
    sender: "Glim Glam",
    text: "Can you believe it, Trixie?",
    attachments: [
      {
        file: File, // this field will be represented as a window.File instance
        description: "I beat Twilight Sparkle and all I got was this lousy t-shirt."
      }
    ]
  }
}

// You will receive a FormData instance with all fields of given object
const form = objectToFormData(object)

const options = {
  method: "post",
  body: form
}

const response = await fetch("https://httpbin.org/post", options)

API

objectToFormData(input[, options]): FormData

Indicates whether or not to omit every false values. Applied enabled. Does not affect boolean array values

This function takes following arguments:

Name	Type	Required	Default	Description
input	unknown[] | Record<sting | number, unknown>	true	–	An object to transform
options	ObjectToFormDataOptions	false	undefined	Additional serialization options

interface ObjectToFormDataOptions

Serialization options

Name	Type	Required	Default	Description
strict	boolean	false	false	Indicates whether or not to omit every false values. Applied enabled. Does not affect boolean array values
FormData	FormData	false	globalThis.FormData	Custom spec-compliant FormData implementation
notation	"dot" | "bracket"	false	"bracket"	Type of the path notation. Can be either "dot" or "bracket"
normalizeValue	NormalizeValue	false	undefined	Value normalizer. This function will be called on each scalar value, before it's added to FormData instance

type NormalizeValue

Value normalizer.

This function will be called on each scalar value, before it's added to FormData instance. It must return either Blob or string

This function will be called with the following arguments:

Name	Type	Description
value	unknown	Current entry value
name	string	The name of the entry
path	Array<string | number>	Entry's path within original object

Changelog

3.0.0

Major Changes

• a08f935 Thanks @octet-stream! - Add normalizeValue option. It allows to apply custom transformation per entry value

• a08f935 Thanks @octet-stream! - Deprecate serialize.strict member. Use objectToFormData function directly

• a08f935 Thanks @octet-stream! - Add FormData option allowing to pass custom FormData implementation

• a08f935 Thanks @octet-stream! - Rewrite project with TypeScript

• a08f935 Thanks @octet-stream! - Drop formdata-node in Node.js environment and rely on globalThis.FormData by default

• a08f935 Thanks @octet-stream! - Add notation option and support dot notation in addition to bracket notation