npm package: @rocklobsterinc/form-data-tree
Description: FormDataTree standardizes form data for compatibility.
Author: Takayuki Miyoshi
Latest version: 2.1.0

# 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](https://developer.mozilla.org/en-US/docs/Web/API/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](https://www.php.net/manual/en/language.variables.superglobals.php) 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 }
```