Skip to main content

Object functions

Perform various manipulation and mutation operations with objects.


assign()

Assigns own enumerable string keyed properties of source objects to the destination object. Source objects are applied from left to right. Subsequent sources overwrite property assignments of previous sources.

Aliases: extend(), assign_in().

assign(object [, source1 [, source2 [...]]])

Arguments

object (Object)
The destination object.
sources (Object[])
The source objects.

Returns

(Object)
The new object.

Examples

InputExpressionResult
[{ "a": 0 }, { "a": 1 }]
assign([0], [1])
{
"a": 1
}
[{ "a": 0 }, { "a": 1, "c": 3 }, { "d": 4 }]
assign([0], [1], [2])
{
"a": 1,
"c": 3,
"d": 4
}

assign_in()

Alias for assign().


assign_with()

This function is like assign() except that it accepts customizer which is invoked to produce the assigned values. If customizer returns undefined, assignment is handled by the function instead. The customizer is invoked with an array of five arguments: [objValue, srcValue, key, object, source].

Aliases: extend_with().

assign_with(object, source, [customizer])

Arguments

object (Object)
The destination object.
source (Object)
The source object.
customizer (Expression)
(Optional) The function to customize assigned values. Default value is &[1]

Returns

(Object)
The new object.

Examples

InputExpressionResult
[{ "a": 0 }, { "a": 1, "b": 2 }]
assign_with([0], [1], &add([1], 2))
{
"a": 3,
"b": 4
}

assign_in_with()

Alias for assign_with().


at()

Creates an array of values corresponding to paths of object.

at(object, [paths])

Arguments

object (Object)
The object to iterate over.
paths (String | String[])
The property paths to pick.

Returns

(Array)
The picked values.

Examples

InputExpressionResult
{
"a": [
{
"b": {
"c": 3
}
},
4
]
}
at(@, ['a[0].b.c', 'a[1]'])
[3, 4]
{
"a": [
{
"b": {
"c": 3
}
},
4
]
}
at(@, 'a[0].b.c')
[3]

defaults()

Assigns own and inherited enumerable string keyed properties of source objects to the destination object for all destination properties that resolve to undefined. Source objects are applied from left to right. Once a property is set, additional values of the same property are ignored.

defaults(object, [sources])

Arguments

object (Object)
The object to iterate over.
sources (Object[])
The source objects.

Returns

(Array)
The new object.

Examples

InputExpressionResult
[{ "a": 1 }, { "a": 3, "b": 2 }]
defaults([0], [1])
{
"a": 1,
"b": 2
}

defaults_deep()

This method is like defaults() except that it recursively assigns default properties.

defaults_deep(object, [sources])

Arguments

object (Object)
The destination object.
sources (Object[])
The source objects.

Returns

(Array)
The new object.

Examples

InputExpressionResult
[
{
"a": {
"b": 2
}
},
{
"a": {
"b": 1,
"c": 3
}
}
]
defaults_deep([0], [1])
{
"a": {
"b": 2,
"c": 3
}
}

entries()

Alias for to_pairs().


entries_in()

Alias for to_pairs().


extend()

Alias for assign().


extend_with()

Alias for assign_with().


get()

Gets the value at path of object. If the resolved value is undefined, the defaultValue is returned in its place.

get(object, path, [defaultValue])

Arguments

object (Object)
The object to query.
path (Array | String)
The path of the property to get.
defaultValue (Any)
The value returned for undefined resolved values.

Returns

(Any)
The resolved value.

Examples

InputExpressionResult
{
"a": [
{
"b": {
"c": 3
}
}
]
}
get(@, 'a[0].b.c')
3
{
"a": [
{
"b": {
"c": 3
}
}
]
}
get(@, ['a', '0', 'b', 'c'])
3
{
"a": [
{
"b": {
"c": 3
}
}
]
}
get(@, 'a.b.c', 'default')
"default"

has()

Checks if path is a direct property of object.

has(object, path)

Arguments

object (Object)
The object to query.
path (Array | String)
The path to check.

Returns

(Any)
true if path exists, else false.

Examples

InputExpressionResult
{
"a": {
"b": 2
}
}
has(@, 'a')
true
{
"a": {
"b": 2
}
}
has(@, 'a.b')
true
{
"a": {
"b": 2
}
}
has(@, 'a.c')
false

has_in()

Alias for has().


invert()

Creates an object composed of the inverted keys and values of object. If object contains duplicate values, subsequent values overwrite property assignments of previous values.

invert(object)

Arguments

object (Object)
The object to invert.

Returns

(Object)
The new inverted object.

Examples

InputExpressionResult
{ "a": 1, "b": 2, "c": 1 }
invert(@)
{
"1": "c",
"2": "b"
}

invert_by()

This function is like invert() except that the inverted object is generated from the results of running each element of object thru iteratee. The corresponding inverted value of each inverted key is an array of keys responsible for generating the inverted value. The iteratee is invoked with one argument: @ (current element).

invert_by(object, [iteratee])

Arguments

object (Object)
The object to invert.
iteratee (Expression | Array | Object | String)
(Optional) The expression invoked per iteration. The iteratee expression is invoked with one argument: @ (current element). Default value is &@.

Returns

(Object)
The new inverted object.

Examples

InputExpressionResult
{
"a": 1,
"b": 2,
"c": 1
}
invert_by(@)
{
"1": ["a", "c"],
"2": ["b"]
}
{
"a": 1,
"b": 2,
"c": 1
}
invert_by(@, &join(['group',@], '_'))
{
"group_1": ["a", "c"],
"group_2": ["b"]
}
{
"a": 1,
"b": { "count": 2 },
"c": { "count": 1 }
}
invert_by(@, 'count')
{
"1": ["c"],
"2": ["b"],
"undefined": ["a"]
}

keys()

Creates an array of the own enumerable property names of object.

keys(object)

Arguments

object (Object)
The object to query.

Returns

(Array)
The array of property names.

Examples

InputExpressionResult
{
"a": 1,
"b": 2,
"c": 3
}
keys(@)
["a", "b", "c"]

keys_in()

Alias for keys().


map_keys()

The opposite of map_values(). This function creates an object with the same values as object and keys generated by running each own enumerable string keyed property of object thru mapper. The mapper is invoked with an array of three named arguments: [value, key, object].

map_keys(object, [mapper])

Arguments

object (Any)
The object to iterate over.
mapper (Expression | Array | Object | String)
(Optional) The expression invoked per iteration. Expression signature is (value, key, object). Default value is &key.

Returns

(Object)
The new mapped object.

Examples

InputExpressionResult
{
"a": { "id": 1 },
"b": { "id": 2 },
"c": { "id": 3 }
}
map_keys(@, &join([[1], [0].id], '_'))
{
"a_1": { "id": 1 },
"b_2": { "id": 2 },
"c_3": { "id": 3 }
}

map_values()

Creates an object with the same keys as object and values generated by running each own enumerable string keyed property of object thru mapper. The mapper is invoked with an array of three named arguments: [value, key, object].

map_values(object, [mapper])

Arguments

object (Any)
The object to iterate over.
mapper (Expression | Array | Object | String)
(Optional) The expression invoked per iteration. Expression signature is (value, key, object). Default value is &value.

Returns

(Object)
The new mapped object.

Examples

InputExpressionResult
{
"ben": {
"name": "Ben",
"age": 35
},
"fred": {
"name": "Fred",
"age": 12
}
}
map_values(@, 'age')
{
"ben": 35,
"fred": 12
}
{
"ben": {
"name": "Ben",
"age": 35
},
"fred": {
"name": "Fred",
"age": 12
}
}
map_values(
@,
&extend(
[0],
{adult: [0].age > 18 }
)
)
-- iteration order is not guaranteed
{
"ben": {
"name": "Ben",
"age": 35,
"adult": true
},
"fred": {
"name": "Fred",
"age": 12,
"adult": false
}
}

merge()

This function is like assign() except that it recursively merges own and inherited enumerable string keyed properties of source objects into the destination object. Source properties that resolve to undefined are skipped if a destination value exists. Array and plain object properties are merged recursively. Other objects and value types are overridden by assignment. Source objects are applied from left to right. Subsequent sources overwrite property assignments of previous sources.

merge(object, [sources])

Arguments

object (Object)
The destination object.
sources (Object[])
(Optional) The source objects.

Returns

(Object)
The object.

Examples

InputExpressionResult
[
{
"a": [{ "b": 2 }, { "d": 4 }]
},
{
"a": [{ "c": 3 }, { "e": 5 }]
}
]
merge([0], [1])
{
"a": [
{
"b": 2,
"c": 3
},
{
"d": 4,
"e": 5
}
]
}

omit()

The opposite of pick(); this function creates an object composed of the own enumerable property paths of object excluding the omitted paths.

omit(object, [paths])

Arguments

object (Object)
The source object.
paths (String | String[])
(Optional) The property paths to omit.

Returns

(Object)
The new object.

Examples

InputExpressionResult
{
"a": 1,
"b": 2,
"c": 3
}
omit(@, ['a', 'c'])
{
"b": 2
}

omit_by()

The opposite of pick_by(); this function creates an object composed of the own enumerable string keyed properties of object that predicate doesn't return truthy for. The predicate is invoked with an array of two arguments: [value, key].

omit_by(object, [predicate])

Arguments

object (Object)
The source object.
predicate (Expression | Array | Object | String)
(Optional) The expression, invoked per iteration. Default value is &[0]

Returns

(Object)
The new object.

Examples

InputExpressionResult
{
"a": 1,
"b": "2",
"c": 3
}
omit_by(@, &is_number([0]))
{
"b": "2"
}
{
"a": { "id": 1 },
"b": "2",
"c": { "id": 3 }
}
omit_by(@, {id: 1})
{
"b": "2",
"c": {
"id": 3
}
}
{
"a": { "id": 1 },
"b": "2",
"c": { "id": 3 }
}
omit_by(@, ['id', 1])
{
"b": "2",
"c": {
"id": 3
}
}
{
"a": { "id": 1 },
"b": "2",
"c": { "id": 3 }
}
omit_by(@, 'id')
{
"b": "2"
}

pick()

Creates an object composed of the picked object properties included in paths.

pick(object, [paths])

Arguments

object (Object)
The source object.
paths (String | String[])
(Optional) The property paths to pick.

Returns

(Object)
The new object.

Examples

InputExpressionResult
{
"a": 1,
"b": 2,
"c": 3
}
pick(@, 'a')
{
"a": 1
}
{
"a": 1,
"b": 2,
"c": 3
}
pick(@, ['a', 'c'])
{
"a": 1,
"c": 3
}

pick_by()

Creates an object composed of the object properties predicate returns truthy for. The predicate is invoked with an array of two arguments: [value, key].

pick_by(object, [predicate])

Arguments

object (Object)
The source object.
predicate (Expression | Array | Object | String)
(Optional) The expression, invoked per iteration. Default value is &[0]

Returns

(Object)
The new object.

Examples

InputExpressionResult
{
"a": 1,
"b": "2",
"c": 3
}
pick_by(@, &is_number([0]))
{
"a": 1,
"c": 3
}
{
"a": { "id": 1 },
"b": "2",
"c": { "id": 3 }
}
pick_by(@, {id: 1})
{
"a": {
"id": 1
}
}
{
"a": { "id": 1 },
"b": "2",
"c": { "id": 3 }
}
pick_by(@, ['id', 1])
{
"a": {
"id": 1
}
}
{
"a": { "id": 1 },
"b": "2",
"c": { "id": 3 }
}
pick_by(@, 'id')
{
"a": {
"id": 1
},
"c": {
"id": 3
}
}

set()

Sets the value at path of object. If a portion of path doesn't exist, it's created. Arrays are created for missing index properties while objects are created for all other missing properties.

set(object, path, value)

Arguments

object (Object)
The object to modify.
path (String | Array)
The path of the property to set.
value (Any)
The value to set.

Returns

(Object)
The object

Examples

InputExpressionResult
{
"a": [
{
"b": {
"c": 3
}
}
]
}
set(@, 'a[0].b.c', 4)
{
"a": [
{
"b": {
"c": 4
}
}
]
}
{
"a": [
{
"b": {
"c": 3
}
}
]
}
set(@, ['a', '0', 'y', 'z'], 5)
{
"a": [
{
"b": {
"c": 3
},
"y": {
"z": 5
}
}
]
}

to_pairs()

Creates an array of own enumerable string keyed-value pairs for object which can be consumed by from_pairs().

Aliases: entries(), entries_in(), to_pairs_in().

to_pairs(object)

Arguments

object (Object)
The object to query.

Returns

(Array)
The key-value pairs.

Examples

InputExpressionResult
{
"a": 1,
"b": 2
}
to_pairs(@)
[
["a", 1],
["b", 2]
]

to_pairs_in()

Alias for to_pairs().


unset()

Removes the property at path of object.

unset(object, path)

Arguments

object (Object)
The object to modify.
path (String | String[])
The path of the property to unset.

Returns

(Object)
The object

Examples

InputExpressionResult
{
"a": [{ "b": { "c": 7 } }]
}
unset(@, 'a[0].b.c')
{
"a": [{ "b": {} }]
}

update()

This function is like set() except that accepts updater to produce the value to set. The updater is invoked with one argument: (value).

update(object, path, updater)

Arguments

object (Object)
The object to modify.
path (Array | String)
The path of the property to set.
updater (Expression)
The expression to produce the updated value.

Returns

(Object)
The object

Examples

InputExpressionResult
{
"a": [{ "b": { "c": 3 } }]
}
update(@, 'a[0].b.c', &add(@, 2))
{
"a": [{ "b": { "c": 5 } }]
}
{
"a": [{ "b": { "c": 3 } }]
}
update(
@,
'x[0].y.z',
&@ && add(@, 1) || 0
)
{
"a": [{ "b": { "c": 3 } }],
"x": [{ "y": { "z": 0 } }]
}

values()

Creates an array of the own enumerable string keyed property values of object.

values(object)

Arguments

object (Object)
The object to query.

Returns

(Object)
The array of property values.

Examples

InputExpressionResult
{
"a": 1,
"b": 2
}
values(@)
[1, 2]
[]
values('hi')
["h", "i"]

values_in()

Alias for values().