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().