js-form-data v1.1.0

JS Form Data

Plain-old-JS near-implementation of the FormData web API with analogue methods for browsers with limited support and ergonomic parsing & serialization functionality

Constructor

Every class that instantiates has one!

JSFormData
Creates a new JSFormData object from a <form> tag and its children.

// in document body:
//<form id="example">
//	<input name="foo" value="bar" />
//	<input name="baz" value="qux" />
//	<input name="bool" value="true" />
//	<input name="bool" value="false" />
//</form>

// params: <form>
const formData = new JSFormData(document.getElementById('example'));
formData.serialize();
// => { foo: 'bar', baz: 'qux', bool: [true, false] }

Class Methods

The JSFormData class has one util method but it's an important one if you need an instance but don't have a DOM element to pass to the constructor

JSFormData::parse
Creates a new JSFormData object from k/v pairs in a plain JS object argument.

// params: <Object>
const formData = JSFormData.parse({ foo: 'bar', baz: true, qux: [1, 2, 3] });
formData.serialize();
// => { foo: 'bar', baz: true, qux: [1, 2, 3] }

Instance Methods

JSFormData instance methods are analogues of the regular FormData web API instance methods, modified to accept and return friendlier objects for easier integration with other processing logic

JSFormData.append
Appends a new value onto an existing key in a JSFormData internal data structure, or adds the key and value if it does not already exist.

// params: <String>, <_>
const formData = new JSFormData();
formData.append('foo', 'bar');
formData.append('foo', 'baz');
formData.append('qux', true);
formData.serialize();
// => { foo: ['bar', 'baz'], qux: true }

// params: <String>, <Blob>, <String>
const formData = new JSFormData();
formData.append('blob', new Blob(), 'blob-name');
formData.serialize().blob.name;
=> 'blob-name'

// params: <Object>
const formData = new JSFormData();
formData.append({ foo: 'bar' });
formData.serialize();
// => { foo: ['bar'] }

JSFormData.delete
Deletes a k/v pair from a JSFormData internal data structure.

// params: <String>
const formData = JSFormData.parse({ foo: 'bar', baz: 'qux'});
formData.delete('foo');
formData.serialize();
// => { baz: 'qux' }

JSFormData.entries
Returns an Array of 2-element Arrays from k/v pairs in JSFormData's internal data structure.

// params: none
const formData = JSFormData.parse({ foo: 'bar', baz: ['qux', 'quux']});
formData.serialize();
// => [['foo', 'bar'], ['baz', ['qux', 'quux]]]

JSFormData.get
Returns the first value associated with a given key in a JSFormData instance.

// params: <String>
const formData = JSFormData.parse({ foo: 'bar', baz: [1, 2] });
formData.get('foo');
// => 'bar'
formData.get('baz');
// => 1

JSFormData.getAll
Returns an Array of all values associated with a given key in a JSFormData instance.

params: <String>
const formData = JSFormData.parse({ foo: 'bar', baz: [1, 2] });
formData.getAll('foo');
// => ['bar']
formData.getAll('baz');
// => [1, 2]

JSFormData.has
Returns a boolean indicating whether a JSFormData instance contains a given key.

params: <String>
const formData = JSFormData.parse({ foo: 'bar', baz: false });
formData.has('foo');
// => true
formData.has('baz');
// => true
formData.has('qux');
// => false

JSFormData.keys
Returns an Array of all the keys in a JSFormData instance.

// params: none
const formData = JSFormData.parse({ foo: 'bar', baz: false, qux: [1, 2, 3] });
formData.keys();
// => ['foo', 'baz', 'qux']

JSFormData.set(<str>, <_>)
Sets a new value for an existing key in a JSFormData instance, or adds a k/v pair if the given key does not already exist. Similar to append, but replaces any existing values on specified keys.

params: <String>, <_>
const formData = JSFormData({ foo: 'bar' });
formData.set('foo', 'baz');
formData.serialize();
 // => { foo: 'baz' }
 
 // params: <String>, <Blob>, <String>
 const formData = new JSFormData();
 formData.set('blob', 'test-value');
 formData.set('blob', new Blob(), 'blob-name');
 formData.serialize().blob.name;
 => 'blob-name'
 
 // params: <Object>
 const formData = new JSFormData();
 formData.set({ foo: 'bar' });
 formData.set({ foo: 'baz' });
 formData.serialize();
 // => { foo: ['baz'] }

JSFormData.values
Returns an Array of values in a JSFormData instance; Array elements are either single values associated 1:1 with a key, or the first of a set of values associated many:1 with a key.

// params: none
const formData = JSFormData.parse({ foo: 'bar', baz: false, qux: [1, 2, 3] });
JSFormData.values();
// => ['bar', false, 1]

1: https://developer.mozilla.org/en-US/docs/Web/API/FormData