Prairie
Version 4 is ESM.
Add new fields/properties to an object based on the values of existing properties.
Composable utility functions that make it easy to edit/replace properties of objects. For best results learn about _.flow()
and read the Lodash FP Guide.
All functions have been curried so they can be called with one argument at a time.
If you have used _.set()
and _.update()
but want more this is the library for you!
Table of Contents
- createObj
- toObject
- setIn
- setVal
- setState
- setField
- addField
- setFieldHas
- setFieldWhen
- replaceField
- updateToWhen
- updateTo
- setFieldWith
- mergeFields
- mergeWith
- mergeFieldsWith
- copy
- move
- moveAll
- renameFields
- findValueAt
- findAt
- getFields
- doProp
- propDo
- doPropOf
- hasMethodAt
- hasMethodOf
- transformHas
createObj
Create a new object based path and value. Dot notation or an array of strings will result in nested objects.
Parameters
Examples
createObj('foo.bar', 'happy') // => { foo: { bar: 'happy' } }
createObj('foo', 'bar') // => { foo: 'bar' }
createObj('foo')('bar') // => { foo: 'bar' }
createObj('baz', { a: 1 }) // => { baz: { a: 1 } }
Returns Object New object with value
placed on the last key of path
.
toObject
Convert a collection into new object defined by path for key and value.
Parameters
-
getKey
(string | Array | Function) The path used for key creation. -
getValue
(string | Array | Function) The path used for key creation. -
collection
any The thing used for value of key.
Examples
toObject('a', 'b', [{a: 'a1', b: 'b2'}]) // => { a1: 'b2' }
Returns Object New object that is similar to map(getValue), keyBy(getKey).
setIn
Rearranged _.set
args to setIn(path, object, value)
Type: function
Parameters
-
path
string The path of the property to replace. -
object
Object The object that to set value on. -
value
any The value to place on path.
Examples
setIn('foo', {}, 'bar') // => { foo: 'bar' }
setIn('a', { b: 1 }, 2) // => { a: 2, b: 1 }
Returns Object New object with value
set at path
.
setVal
Rearranged _.set
args to setVal(value, object, path)
Type: function
Examples
setVal(value, object, path)
setState
Normal lodash _.set with no rearg. setVal(object, path, value)
Examples
setVal(object, path, value)
setField
Set field. Like _.update
but transformer is given the entire item instead of only the field.
Parameters
-
path
string The path of the property to replace. -
transformer
Function Transformer given entire item. Return value set at path. -
item
Object The item to add or replace field on.
Returns Object Item with path
updated with result of transformer
.
addField
Set field like setField
but only if it's value is empty.
Parameters
-
path
string The path of the property to set. -
transformer
Function Transformer given entire item. Return value set at path. -
item
Object The item to update field on.
setFieldHas
Replace field only if it is already set. Transformer given entire item.
Parameters
-
path
string The path of the property to replace. -
transformer
Function Transformer given entire item. Return value set at path. -
item
Object The item to update field on.
Returns Object Item with path
updated with result of transformer
.
setFieldWhen
Set field when boolCheck is true. Otherwise return item untouched.
Parameters
-
path
string The path of the property to set. -
transformer
Function Transformer given entire item. Should return value of path. -
boolCheck
Function A function that returns true when field should be set. -
item
Object The item to update field on.
Returns Object Item with path
updated with result of transformer
.
replaceField
Replace field only if found. Transformer gets field value. Probably just use _.update() unless you want the check beforehand.
updateToWhen
Replace field with result of transformer when boolCheck return true.
Parameters
-
transformer
Function Transformer given value at path of item. Return replacement value. -
boolCheck
Function A function that returns true when field should be replaced. -
path
string The path of the property to update. -
item
Object The item to conditionally update field on.
Examples
const toArray = updateToWhen(Array, _.isPlainObject, 'foo')
toArray({ foo: { a: 'happy' } }) // => { foo: [{ a: 'happy' }] }
Returns Object Item with conditional transformer applied to path
.
updateTo
Rearranged _.update args to transformer, path, item
Parameters
-
transformer
Function Transformer given value at path of item. Return replacement value. -
path
string The path of the property to get. -
item
Object The item to update field on.
Returns Object Item with transformer applied to property at path
.
setFieldWith
Set field on item. Transformer given value of withId property.
Parameters
-
path
string The path of the property to get. -
withId
string The path of the property to send totransformer
. -
transformer
Function Transformer given value of withId property.
Returns ItemTransformer Result of transformer set at field
item
.
mergeFields
Replace item with result of transformer.
Parameters
Examples
mergeFields(({ a, b }) => ({ a4: a * 4, b3: b * 3 }), { a: 2, b: 3 });
// => { a: 2, b: 3, a4: 8, b3: 9 }
Returns Object Merged result of transformer on top of item
.
mergeWith
Merge source on top of item.
Parameters
-
source
Object Object to apply on top of item. -
item
Object Object that values of source will be applied.
Examples
mergeWith({ a: 1 })({ a: 2, b: 4 });
// => { a: 1, b: 4 }
Returns Object Merged result of surce
on top of item
.
mergeFieldsWith
Replace item. Transformer given value of withId property.
Parameters
-
withId
string The path of the property to send totransformer
. -
transformer
Function Sent item property at path ofwithId
. Should return new Object. -
item
Object The object to work with.
Returns Object Result of transformer set at field
item
.
copy
Copy value of getPath to setPath only if getPath finds something. Otherwise item left untouched.
Parameters
-
getPath
string The source path. -
setPath
string The destination path. -
item
Object The object to work with.
move
Move property from one names to another.
Parameters
-
getPath
string The source path. -
setPath
(string | Function) The destination path. -
item
Object The object to work with.
Examples
move('foo', 'bar', { foo: 1, baz: 2 }) // => { bar: 1, baz: 2 }
Returns Object Result after the move. Value at getPath
removed and added to setPath
.
moveAll
Map some keys.
Parameters
-
renamer
Function The function to send each key. Should return new key string. -
renameKeys
Array An array of source paths. -
item
Object The object to work with.
Examples
move('foo', 'bar', { foo: 1, baz: 2 }) // => { bar: 1, baz: 2 }
Returns Object Result after the move. Value at getPath
removed and added to setPath
.
renameFields
Move property from one names to another.
Parameters
-
renameObj
Object Object where each key will be moved to the value path. If value is a function it is sent the old key and will return the new one. -
item
Object The object to work with.
Examples
const rename = renameFields({ foo: 'bar', bin_baz: _.camelCase })
rename({ foo: 1, bin_baz: 2, bar: 3, other: 4 })
// => { bar: 1, binBaz: 2, other: 4 }
Returns Object Result after the renames.
findValueAt
Return the first value of paths. 0, null, and false are valid values.
Parameters
Examples
findAt(['c', 'b', 'a'])({ a: 'foo', b: 'bar', c: null }) // => null
findAt(['c', 'b', 'a'])({ a: 'foo', b: false, c: '' }) // => false
Returns any The first truthy value found at one of the getPaths
.
findAt
Return the first truthy value of paths.
Parameters
Examples
findAt(['c', 'b', 'a'])({ a: 'foo', b: 'bar', c: null }) // => 'bar'
findAt(['c', 'b', 'a'])({ a: 'foo', b: false, c: '' }) // => 'foo'
Returns any The first truthy value found at one of the getPaths
.
getFields
Return an object with same keys as object argument. Values replaced with result of value selector.
Parameters
-
structuredSelector
Object Object where each value is a selector accepting item. -
item
Object The object to work with.
Examples
getFields({bar: _.get('foo')}, { foo: 'happy'}) // => { bar: 'happy' }
getFields({bar: 'foo'})({ foo: 'happy'}) // => { bar: 'happy' }
Returns Object2 Result after each value is passed the item.
doProp
Return result of calling transformer with property value at path.
Parameters
-
transformer
Function Transformer given value at path of item. -
path
string The path of the property to get. -
item
Object The item to get property value on.
Examples
doProp(_.isString, 'foo')({ foo: 'bar' }) // => true
doProp(_.isString, 'foo')({ foo: 2 }) // => false
propDo
Return result of calling transformer with property value at path.
Parameters
-
path
string The path of the property to get. -
transformer
Function Transformer given value at path of item. -
item
Object The item to get property value on.
Examples
propDo('foo', _.isString)({ foo: 'bar' }) // => true
propDo('foo', _.isString)({ foo: 2 }) // => false
doPropOf
Create a function that will accept a path string and send its value of object to transformer.
Type: Function
hasMethodAt
Check if property has a method at path. An example of using doProp()
.
Type: Function
Examples
hasMethodAt(path)(object)
hasMethodOf
Check if property at path is a function. An example of using doPropOf()
.
Type: Function
Examples
hasMethodAt(path)(object)
transformHas
Replace entire item if has field. Transformer given value at path.
Type: Function