Plain-old-JS near-implementation of the FormData web API with analogue methods for browsers with limited support and ergonomic parsing & serialization functionality
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] }
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] }
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 Array
s 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]