Objects
Functions for working with objects.
hash(source, options)
This function can be used to create a modified version of a plain old Javascript object (aka "hash array" or "hash table", hence the name).
A source object can be passed as the first argument. A new copy of the object is returned.
const copy = hash({ a: 10, b: 20 }); // => { a: 10, b: 20 }
An array can be passed. This is passed to the splitHash()
function which turns it into a hash array. The elements of the array will be the keys of the returned objects with the values set to true
.
const copy = hash(['a', 'b']); // => { a: true, b: true }
A string can be passed containing words separated by commas and/or spaces. The string is split into an array of words and then converted to an object as above.
const copy1 = hash('a b'); // => { a: true, b: true }
const copy2 = hash('a,b'); // => { a: true, b: true }
const copy3 = hash('a, b'); // => { a: true, b: true }
A second argument can be passed as an object containing modification functions.
The include
option can be a function used to specify which items you want to include in the output object. It is passed a key
, value
, the input
object and output
object. It should return true
to include the entry in the output object, or false to exclude it.
const copy = hash(
{ a: 10, b: 20, c: 30 },
{ include: k => k === 'a' } // only include the 'a' key
); // => { a: 10 }
As well as specifying include
as a function, you can use any of the selection criteria supported by the selector()
function. For example, you can specify an object containing the keys you want to accept.
const copy = hash(
{ a: 10, b: 20, c: 30 },
{ include: { a: true, b: true } } // include the 'a' and 'b' keys
); // => { a: 10, b: 20 }
Or an array:
const copy = hash(
{ a: 10, b: 20, c: 30 },
{ include: ['a', 'b'] }
);
Or a string of keys delimited by whitespace and/or commas:
const copy = hash(
{ a: 10, b: 20, c: 30 },
{ include: 'a b' }
);
Or a regular expression:
const copy = hash(
{ a: 10, b: 20, c: 30 },
{ include: /^a|b$/ }
);
The exclude
option works the same way, but should return true
to exclude the entry and false
to include it.
const copy = hash(
{ a: 10, b: 20, c: 30 },
{ exclude: k => k === 'a' } // exclude the 'a' key
); // => { b: 20, c: 30 }
It can also be specified as an object, array, string or regular expression.
const copy = hash(
{ a: 10, b: 20, c: 30 },
{ exclude: { a: true } }
);
The key
option allows you to modify the keys of the object. It should be a function that will be passed the same arguments as for include
and exclude
. It should return the (potentially) modified key.
const copy = hash(
{ a: 10, b: 20, c: 30 },
{ key: k => k.toUpperCase() } // convert keys to upper case
); // => { A: 10, B: 20, C: 30 }
The value
option allows you to modify the value of the object. It should be a function like the others, but be warned that the order of the first two arguments is reversed: (value
, key
, input
, output
). This is to accommodate the usual case where you're only interested in modifying the value.
const copy = hash(
{ a: 10, b: 20, c: 30 },
{ value: v => v + 1 } // add 1 to each value
); // => { A: 11, B: 21, C: 31 }
These function are applied in the order listed above: include
, exclude
, key
and value
. In all cases you can modify the output
object, e.g. by adding new values, but you should not modify the input
object.
objMap(obj, fn)
Applies a function to each value of an object and returns a new object.
objMap(
{ a: 'alpha', b: 'bravo' },
v => v.toUpperCase()
)
// => { a: 'ALPHA', b: 'BRAVO' }
remove(object, key)
Removes an item from an object and returns the corresponding value.
let source = { a: 'alpha', b: 'bravo', c: 'charlie' };
let removed = remove(source, 'a');
// source = { b: 'bravo', c: 'charlie' }
// removed = 'alpha'
extract(object, keys, options)
Extracts a subset of the keys and values from an object and returns a new object.
The keys to extract can be specified in a number of ways. They can be the keys in an object that have a corresponding true value.
extract(
{ a: 'alpha', b: 'bravo', c: 'charlie', d: 'delta', e: 'echo' };
{ a: true, c: true, e: true }
)
// => { a: 'alpha', c: 'charlie', e: 'echo' }
The keys can also be specified as an array.
extract(
{ a: 'alpha', b: 'bravo', c: 'charlie', d: 'delta', e: 'echo' };
['a', 'c', 'e']
)
// => { a: 'alpha', c: 'charlie', e: 'echo' }
If the keys are all simple word strings (e.g. don't contain any non-word characters or spaces) then they can be specified as a string.
extract(
{ a: 'alpha', b: 'bravo', c: 'charlie', d: 'delta', e: 'echo' };
'a c e'
)
// => { a: 'alpha', c: 'charlie', e: 'echo' }
A regular expression can also be used.
extract(
{ a: 'alpha', b: 'bravo', c: 'charlie', d: 'delta', e: 'echo' };
/^[ace]$/
)
// => { a: 'alpha', c: 'charlie', e: 'echo' }
Or a function can be provided to select the items to extract.
extract(
{ a: 'alpha', b: 'bravo', c: 'charlie', d: 'delta', e: 'echo' };
key => key === 'a' || key === 'c' || key === 'e'
)
// => { a: 'alpha', c: 'charlie', e: 'echo' }
The third argument can be used to provide a set of options. The first is the delete
option which can be set to true
(default value is false
) to delete the items from the source object.
let source = { a: 'alpha', b: 'bravo', c: 'charlie', d: 'delta', e: 'echo' };
let subset = extract(
source,
'a c e',
{ delete: true }
)
// source = { b: 'bravo', d: 'delta' }
// subset = { a: 'alpha', c: 'charlie', e: 'echo' }
The key
option can be used to transform the keys that are extracted. It should be a function that accepts the source key and returns the modified key.
let subset = extract(
{
DATABASE_USERNAME: 'badger',
DATABASE_PASSWORD: 's3cr3t',
},
/^DATABASE_/,
{ key: key => key.replace(/^DATABASE_/, '').toLowerCase() }
)
// => { username: 'badger', password: 's3cr3t' }
The value
option can be used to transform values that are extracted. It should be a function that accepts the source value and returns the modified value.
extract(
{ a: 10, b: 20, c: 30 },
'a b',
{ value: value => value * 2 }
)
// => { a: 20, b: 40 }
keys(object)
An alias for Object.keys
which returns an array of the object's own enumerable string-keyed property names.
keys(
{ a: 10, b: 20, c: 30 }
)
// => ['a', 'b', 'c']
values(object)
An alias for Object.values
which returns an array of the object's own enumerable string-keyed property values.
values(
{ a: 10, b: 20, c: 30 }
)
// => [10, 20, 30]
entries(object)
An alias for Object.entries
which returns an array of the object's own enumerable string-keyed property key-value pairs.
entries(
{ a: 10, b: 20, c: 30 }
)
// => [['a', 10], ['b', 20], ['c', 30]]