_

_

The object containing all immutable-lodash functions.

Source:

Example

// Important note for examples:

// Rather than specifying every example data structure like so:

let map = List([Map({ 'a': 1 }), Map({ 'b': 2 }), Map({ 'c': 3 }) ])

// Immutable Lists and Maps are implied:

let map = [ { 'a': 1 }, { 'b': 2 }, { 'c': 3 } ]

// This is to make the it easier for you to see what every function is actually doing.

// As a rule, `immutable-lodash` functions try to return the type of object that was passed in, or,
// where it makes more sense, a lazy `Seq`. The docs specify a "Returns:" type for every function,
// which you can see below.

Methods

_.at(iterable, […paths]) → {Iterable}

Creates an array of values corresponding to paths of iterable.

Example
let iterable = { 'a': [{ 'b': { 'c': 3 } }, 4] }

_.at(iterable, ['a[0].b.c', 'a[1]'])
// => [3, 4]
Parameters:
Name Type Attributes Description
iterable Iterable

The iterable to iterate over.

paths string | Array.<string> <optional>
<repeatable>

The property paths of elements to pick.

Source:
Returns:

Returns the picked values.

Type
Iterable

_.chunk(iterable, [size]) → {Iterable}

Creates an iterable of elements split into groups the length of size. If iterable can't be split evenly, the final chunk will be the remaining elements.

Example
let list = ['a', 'b', 'c', 'd']
_.chunk(list, 2)
// => [['a', 'b'], ['c', 'd']]

_.chunk(list, 3)
// => [['a', 'b', 'c'], ['d']]
Parameters:
Name Type Attributes Default Description
iterable Iterable

The iterable to process.

size number <optional>
1

The length of each chunk

Source:
Returns:

Returns the new iterable of chunks.

Type
Iterable

_.compact(iterable, Returns)

Creates an iterable with all falsey values removed. The values false, null, 0, "", undefined, and NaN are falsey.

Example
_.compact([0, 1, false, 2, '', 3])
// => [1, 2, 3]
Parameters:
Name Type Description
iterable Iterable

The iterable to compact.

Returns Iterable

the new iterable of filtered values.

Source:

_.concat(iterable, […values], Returns)

Creates an Iterable of the same type concatenating iterable with any additional iterables and/or values.

Example
_.concat(['a'], 2, [3], [[4]])
// => ['a', 2, 3, [4]]
Parameters:
Name Type Attributes Description
iterable Iterable

The iterable to concatenate.

values * <optional>
<repeatable>

The values to concatenate.

Returns Iterable

the new concatenated sequence.

Source:

_.countBy([iteratee])

Creates a Map composed of keys generated from the results of running each element of iterable through iteratee. The corresponding value of each key is the number of times the key was returned by iteratee. The iteratee is invoked with one argument: (value).

Example
_.countBy([6.1, 4.2, 6.3], Math.floor)
// => { '4': 1, '6': 2 }
Parameters:
Name Type Attributes Default Description
iteratee function <optional>
_.identity

The iteratee to transform keys.

Source:

_.defaults(iterable, […sources]) → {Iterable}

Creates new iterable with all properties of source iterables that resolve to undefined. Source iterables are applied from left to right. Once a key is set, additional values of the same key are ignored.

Example
_.defaults({ 'a': 1 }, { 'b': 2 }, { 'a': 3 })
// => { 'a': 1, 'b': 2 }
Parameters:
Name Type Attributes Description
iterable Iterable

The destination iterable.

sources Iterable <optional>
<repeatable>

The source iterables.

Source:
See:
Returns:

Returns iterable.

Type
Iterable

_.defaultsDeep(iterable, […sources]) → {Iterable}

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

Example
_.defaultsDeep({ 'a': { 'b': 2 } }, { 'a': { 'b': 1, 'c': 3 } })
// => { 'a': { 'b': 2, 'c': 3 } }
Parameters:
Name Type Attributes Description
iterable Iterable

The destination iterable.

sources Iterable <optional>
<repeatable>

The source iterables.

Source:
See:
Returns:

Returns iterable.

Type
Iterable

_.difference(iterable, […values]) → {Iterable}

Creates an Iterable of iterable values not included in the other given iterables The order of result values is determined by the order they occur in the first iterable.

Example
_.difference([2, 1], [2, 3])
// => [1]
Parameters:
Name Type Attributes Description
iterable Iterable

The iterable to inspect.

values Iterable <optional>
<repeatable>

The values to exclude.

Source:
See:
  • _.without, _.xor
Returns:

Returns the iterable of filtered values.

Type
Iterable

_.differenceBy(iterable, […values], [iteratee]) → {Iterable}

This method is like _.difference except that it accepts iteratee which is invoked for each element of iterable and values to generate the criterion by which they're compared. Result values are chosen from the first iterable. The iteratee is invoked with one argument: (value).

Example
_.differenceBy([2.1, 1.2], [2.3, 3.4], Math.floor)
// => [1.2]
Parameters:
Name Type Attributes Default Description
iterable Iterable

The iterable to inspect.

values Iterable <optional>
<repeatable>

The values to exclude.

iteratee function <optional>
_.identity

The iteratee invoked per element.

Source:
Returns:

Returns the new iterable of filtered values.

Type
Iterable

_.fill(iterable, value, [start], [end]) → {Iterable}

Fills elements of iterable with value from start up to, but not including, end.

Example
let list = [1, 2, 3]

_.fill(list, 'a')
// => ['a', 'a', 'a']

_.fill([4, 6, 8, 10], '*', 1, 3)
// => [4, '*', '*', 10]
Parameters:
Name Type Attributes Default Description
iterable Iterable

The iterable to fill.

value *

The value to fill iterable with.

start number <optional>
0

The start position.

end number <optional>
iterable.size

The end position.

Source:
Returns:

Returns iterable.

Type
Iterable

_.groupBy(iterable, [iteratee]) → {Map}

Creates a map composed of keys generated from the results of running each element of iterable through iteratee. The order of grouped values is determined by the order they occur in iterable. The corresponding value of each key is a List of elements responsible for generating the key. The iteratee is invoked with one argument: (value).

Example
_.groupBy([6.1, 4.2, 6.3], Math.floor)
// => { '4': [4.2], '6': [6.1, 6.3] }
Parameters:
Name Type Attributes Default Description
iterable Iterable

The iterable to iterate over.

iteratee function <optional>
_.identity

The iteratee to transform keys.

Source:
Returns:

Returns the composed aggregate map.

Type
Map

_.intersection([…iterables]) → {Iterable}

Returns a sequence of unique values that are included in all given iterables The order of result values is determined by the order they occur in the first iterable.

Example
_.intersection([2, 1], [2, 3])
// => Seq [2]
Parameters:
Name Type Attributes Description
iterables Iterable <optional>
<repeatable>

The iterables to inspect.

Source:
Returns:

Returns the new iterable of intersecting values.

Type
Iterable

_.invert(iterable) → {Iterable}

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

Example
let iterable = { 'a': 1, 'b': 2, 'c': 1 }

_.invert(iterable)
// => { '1': 'c', '2': 'b' }
Parameters:
Name Type Description
iterable Iterable

The iterable to invert.

Source:
Returns:

Returns the new inverted iterable.

Type
Iterable

_.keyBy(iterable, [iteratee]) → {Map}

Creates a Map composed of keys generated from the results of running each element of iterable through iteratee. The corresponding value of each key is the last element responsible for generating the key. The iteratee is invoked with one argument: (value).

Example
let keys = [
  { 'dir': 'left', 'code': 97 },
  { 'dir': 'right', 'code': 100 }
]

_.keyBy(keys, (o) => String.fromCharCode(o.code))
// => { 'a': { 'dir': 'left', 'code': 97 }, 'd': { 'dir': 'right', 'code': 100 } }

_.keyBy(keys, 'dir')
// => { 'left': { 'dir': 'left', 'code': 97 }, 'right': { 'dir': 'right', 'code': 100 } }
Parameters:
Name Type Attributes Default Description
iterable Iterable

The iterable to iterate over.

iteratee function <optional>
_.identity

The iteratee to transform keys.

Source:
Returns:

Returns the composed aggregate map.

Type
Map

_.omit(iterable, […props]) → {Iterable}

The opposite of _.pick this method creates a new iterable omitting the supplied keys

Example
let map = { 'a': 1, 'b': '2', 'c': 3 }

_.omit(map, ['a', 'c'])
// => { 'b': '2' }
Parameters:
Name Type Attributes Description
iterable Iterable

The source iterable.

props string | Array.<string> <optional>
<repeatable>

The property identifiers to omit.

Source:
Returns:

Returns the new iterable.

Type
Iterable

_.omitBy(iterable, [predicate]) → {Iterable}

The opposite of _.pick this method creates a new iterable omitting the supplied keys predicate doesn't return truthy for. The predicate is invoked with two arguments: (value, key).

Example
let iterable = { 'a': 1, 'b': '2', 'c': 3 }

_.omitBy(iterable, _.isNumber)
// => { 'b': '2' }
Parameters:
Name Type Attributes Default Description
iterable Iterable

The source iterable.

predicate function <optional>
_.identity

The function invoked per property.

Source:
Returns:

Returns the new iterable.

Type
Iterable

_.partition(iterable, [predicate]) → {List}

Creates a list of elements split into two groups, the first of which contains elements predicate returns truthy for, the second of which contains elements predicate returns falsey for. The predicate is invoked with one argument: (value).

Example
let users = [
  { 'user': 'barney',  'age': 36, 'active': false },
  { 'user': 'fred',    'age': 40, 'active': true },
  { 'user': 'pebbles', 'age': 1,  'active': false }
]

_.partition(users, (o) => o.active)
// => objects for [['fred'], ['barney', 'pebbles']]
Parameters:
Name Type Attributes Default Description
iterable Iterable

The iterable to iterate over.

predicate function <optional>
_.identity

The function invoked per iteration.

Source:
Returns:

Returns the list of grouped elements.

Type
List

_.pick(iterable, […props]) → {Iterable}

Creates an iterable composed of the picked iterable properties.

Example
let iterable = { 'a': 1, 'b': '2', 'c': 3 }

_.pick(iterable, ['a', 'c'])
// => { 'a': 1, 'c': 3 }
Parameters:
Name Type Attributes Description
iterable Iterable

The source iterable.

props string | Array.<string> <optional>
<repeatable>

The property identifiers to pick.

Source:
Returns:

Returns the new iterable.

Type
Iterable

_.pickBy(iterable, [predicate]) → {Iterable}

Creates an iterable composed of the iterable properties predicate returns truthy for. The predicate is invoked with two arguments: (value, key).

Example
let iterable = { 'a': 1, 'b': '2', 'c': 3 }

_.pickBy(iterable, _.isNumber)
// => { 'a': 1, 'c': 3 }
Parameters:
Name Type Attributes Default Description
iterable Iterable

The source iterable.

predicate function <optional>
_.identity

The function invoked per property.

Source:
Returns:

Returns the new iterable.

Type
Iterable

_.pullAt(iterable, […indexes]) → {Iterable}

Removes elements from iterable corresponding to indexes and returns an iterable of removed elements.

Example
let iterable = ['a', 'b', 'c', 'd']
_.pullAt(iterable, [1, 3])
// => ['b', 'd']
Parameters:
Name Type Attributes Description
iterable Iterable

The iterable to modify.

indexes number | Array.<number> <optional>
<repeatable>

The indexes of elements to remove.

Source:
Returns:

Returns the new iterable of removed elements.

Type
Iterable

_.sample(iterable) → {*}

Gets a random element from iterable.

Example
_.sample([1, 2, 3, 4])
// => 2
Parameters:
Name Type Description
iterable Iterable

The iterable to sample.

Source:
Returns:

Returns the random element.

Type
*

_.sampleSize(iterable, [n]) → {List}

Gets n random elements at unique keys from iterable up to the size of iterable.

Example
_.sampleSize([1, 2, 3], 2)
// => List [3, 1]

_.sampleSize([1, 2, 3], 4)
// => List [2, 3, 1]
Parameters:
Name Type Attributes Default Description
iterable Iterable

The iterable to sample.

n number <optional>
1

The number of elements to sample.

Source:
Returns:

Returns the random elements.

Type
List

_.shuffle(iterable) → {Iterable}

Creates an iterable of shuffled values, using a version of the Fisher-Yates shuffle.

Example
_.shuffle([1, 2, 3, 4])
// => [4, 1, 3, 2]
Parameters:
Name Type Description
iterable Iterable

The iterable to shuffle.

Source:
Returns:

Returns the new shuffled iterable.

Type
Iterable

_.sortedIndex(iterable, value) → {number}

Determines the lowest index at which value should be inserted into iterable in order to maintain its sort order.

Example
_.sortedIndex([30, 50], 40)
// => 1
Parameters:
Name Type Description
iterable Iterable

The sorted iterable to inspect.

value *

The value to evaluate.

Source:
Returns:

Returns the index at which value should be inserted into iterable.

Type
number

_.sortedIndexBy(iterable, value, [iteratee]) → {number}

This method is like _.sortedIndex except that it accepts iteratee which is invoked for value and each element of iterable to compute their sort ranking. The iteratee is invoked with one argument: (value).

Example
let maps = [{ 'x': 4 }, { 'x': 5 }]

_.sortedIndexBy(maps, { 'x': 4 }, (o) => o.x)
// => 0

// The `_.property` iteratee shorthand.
_.sortedIndexBy(maps, { 'x': 4 }, 'x')
// => 0
Parameters:
Name Type Attributes Default Description
iterable Iterable

The sorted iterable to inspect.

value *

The value to evaluate.

iteratee function <optional>
_.identity

The iteratee invoked per element.

Source:
Returns:

Returns the index at which value should be inserted into iterable.

Type
number

_.union([…iterables]) → {Seq}

Creates an iterable of unique values, in order, from all given iterables.

Example
_.union([2], [1, 2])
// => Seq [2, 1]
Parameters:
Name Type Attributes Description
iterables Iterable <optional>
<repeatable>

The iterables to inspect.

Source:
Returns:

Returns the new iterable of combined values.

Type
Seq

_.uniq(iterable) → {Seq}

Creates a duplicate-free sequence of the iterable, in which only the first occurrence of each element is kept.

Example
_.uniq([2, 1, 2])
// => Seq [2, 1]
Parameters:
Name Type Description
iterable Iterable

The iterable to inspect.

Source:
Returns:

Returns the new duplicate free sequence.

Type
Seq

_.xor([…iterables]) → {Seq}

Creates a sequence of unique values that is the symmetric difference of the given iterables. The order of result values is determined by the order they occur in the iterables.

Example
_.xor([2, 1], [2, 3])
// => [1, 3]
Parameters:
Name Type Attributes Description
iterables Iterable <optional>
<repeatable>

The iterables to inspect.

Source:
See:
Returns:

Returns the sequence of filtered values.

Type
Seq