FormDataTree

FormDataTree standardizes form data for compatibility.

What problems does it solve?

To access user input data through a web form on client-side, you can use the FormData interface. A FormData object provides a set of key/value pairs representing form fields and their values, and the data model emulates the multipart/form-data encoding type.

Programming languages and libraries that can handle HTTP requests on server-side often provide their own methods to access user input data in the request. For instance, PHP provides "superglobal" variables like $_GET, $_POST, and $_FILES.

What is worth noting here is that the data structure representing the same user input can look different on client-side and on server-side. For example, when the user input data is like this:

country=China&country=India

A FormData object representing it will be in a structure like this:

{
  [
    [ "country", "China" ],
    [ "country", "India" ]
  ]
}

On the other hand, PHP constructs an associative array based on the user input data. The $_POST variable will be like this:

{
  "country": "India"
}

When square bracket notation ([]) is used, the difference becomes more noticeable. When the user input data is like this:

country[]=China&country[]=India

A FormData object treats the square brackets as a meaningless part of a field name, so it will be like this:

{
  [
    [ "country[]", "China" ],
    [ "country[]", "India" ]
  ]
}

PHP treats the square brackets as an array literal, so the $_POST variable will be like this:

{
  "country": [ "China", "India" ]
}

This gap becomes a problem when you need to process user input data in a consistent way on client-side and on server-side. FormDataTree has been created to resolve this problem. A FormDataTree object works as a wrapper of a FormData object, and has the ability to provide user input data in a structure equivalent to PHP's $_POST variable.

Installation

npm install @rocklobsterinc/form-data-tree

Usage

import FormDataTree from '@rocklobsterinc/form-data-tree';

// Creating a FormData object for testing.
const formData = new FormData();

formData.append( 'your-name', 'John Doe' );
formData.append( 'your-penguin[]', 'Adelie' );
formData.append( 'your-penguin[]', 'Emperor' );
formData.append( 'your-penguin[]', 'Humboldt' );
formData.append( 'your-file', new Blob( [ 'bla bla bla' ] ) );

// FormDataTree.from() creates a FormDataTree object from form data.
const formDataTree = FormDataTree.from( formData );

// FormDataTree.prototype.getAll() returns an object containing form data values.
const yourName = formDataTree.getAll( 'your-name' );

console.log( yourName );
// Object { 0: "John Doe" }

const yourPenguins = formDataTree.getAll( 'your-penguin' );

console.log( yourPenguins );
// Object { 0: "Adelie", 1: "Emperor", 2: "Humboldt" }

// For file fields, use FormDataTree.prototype.getAllFiles().
const yourFile = formDataTree.getAllFiles( 'your-file' );

console.log( yourFile );
// Object { 0: File }