lodash

A JavaScript utility library delivering consistency, modularity, performance, & extras.

Example

_.assign({ 'a': 1 }, { 'b': 2 }, { 'c': 3 });
// → { 'a': 1, 'b': 2, 'c': 3 }

_.map([1, 2, 3], function(n) { return n * 3; });
// → [3, 6, 9]

Features

• ~100% code coverage
• Follows semantic versioning for releases
• Lazily evaluated chaining
• _(…) supports implicit chaining
• _.ary & _.rearg to change function argument limits & order
• _.at for cherry-picking collection values
• _.attempt to execute functions which may error without a try-catch
• _.before to complement _.after
• _.bindKey for binding “lazy” defined methods
• _.chunk for splitting an array into chunks of a given size
• _.clone supports shallow cloning of Date & RegExp objects
• _.cloneDeep for deep cloning arrays & objects
• _.curry & _.curryRight for creating curried functions
• _.debounce & _.throttle are cancelable & accept options for more control
• _.defaultsDeep for recursively assigning default properties
• _.fill to fill arrays with values
• _.findKey for finding keys
• _.flow to complement _.flowRight (a.k.a _.compose)
• _.forEach supports exiting early
• _.forIn for iterating all enumerable properties
• _.forOwn for iterating own properties
• _.get & _.set for deep property getting & setting
• _.gt, _.gte, _.lt, & _.lte relational methods
• _.inRange for checking whether a number is within a given range
• _.isNative to check for native functions
• _.isPlainObject & _.toPlainObject to check for & convert to Object objects
• _.isTypedArray to check for typed arrays
• _.mapKeys for mapping keys to an object
• _.matches supports deep object comparisons
• _.matchesProperty to complement _.matches & _.property
• _.merge for a deep _.extend
• _.method & _.methodOf to create functions that invoke methods
• _.modArgs for more advanced functional composition
• _.parseInt for consistent cross-environment behavior
• _.pull, _.pullAt, & _.remove for mutating arrays
• _.random supports returning floating-point numbers
• _.restParam & _.spread for applying rest parameters & spreading arguments to functions
• _.runInContext for collisionless mixins & easier mocking
• _.slice for creating subsets of array-like values
• _.sortByAll & _.sortByOrder for sorting by multiple properties & orders
• _.support for flagging environment features
• _.template supports “imports” options & ES template delimiters
• _.transform as a powerful alternative to _.reduce for transforming objects
• _.unzipWith & _.zipWith to specify how grouped values should be combined
• _.valuesIn for getting values of all enumerable properties
• _.xor to complement _.difference, _.intersection, & _.union
• _.add, _.round, _.sum, & more math methods
• _.bind, _.curry, _.partial, & more support customizable argument placeholders
• _.capitalize, _.trim, & more string methods
• _.clone, _.isEqual, & more accept customizer callbacks
• _.dropWhile, _.takeWhile, & more to complement _.first, _.initial, _.last, & _.rest
• _.findLast, _.findLastKey, & more right-associative methods
• _.includes, _.toArray, & more accept strings
• _#commit & _#plant for working with chain sequences
• _#thru to pass values thru a chain sequence

Download

Review the build differences & pick the one that’s right for you.

• Modern build (minified) For new environments like Chrome, Firefox, IE ≥ 9, & Safari ≥ 5.1
• Compatibility build (minified) For new & old environments like IE ≤ 8 & PhantomJS

Installation

In a browser:

<script src="lodash.js"></script>

In an AMD loader:

require(['lodash'], function(_) {});

Using npm:

$ {sudo -H} npm i -g npm$ npm i --save lodash

In Node.js/io.js:

// load the modern build
var _ = require('lodash');

// or a method category
var array = require('lodash/array');

// or a method (great for smaller builds with browserify/webpack)
var chunk = require('lodash/array/chunk');

See the package source for more details.

Note: Don’t assign values to the special variable “_” when in the REPL. Install n_ for a REPL that includes lodash by default.

Module formats

lodash is also available in a variety of other builds & module formats.

• npm packages for modern, compatibility, & per method builds
• AMD modules for modern & compatibility builds
• ES modules for the modern build

CDN copies are available on cdnjs & jsDelivr. Create custom builds with only the features you need. Looking for more functional usage? Try lodash-fp.

Dive in

Check out our changelog, roadmap, as well as community created podcasts, posts, & videos.

Support

Tested in Chrome 43-44, Firefox 38-39, IE 6-11, MS Edge, Safari 5-8, ChakraNode 0.12.2, Node.js 0.8.28, 0.10.40, 0.12.7, & 4.0.0, PhantomJS 1.9.8, RingoJS 0.11, & Rhino 1.7.6

Automated browser & CI test runs are available. Special thanks to Sauce Labs for providing automated browser testing.

Custom builds

Custom builds make it easy to create lightweight versions of lodash containing only the features you need. To top it off, we handle all function dependency & alias mapping for you. Review the build differences & pick the one that’s right for you.

Using Grunt? We also provide a Grunt plugin to build lodash as part of your Gruntfile.

The lodash command-line utility is available when lodash-cli is installed as a global package:

$ {sudo -H} npm i -g npm
$ {sudo -H} npm i -g lodash-cli
$ lodash -h

Note: Uninstall older versions before installing lodash-cli.

• Compat builds, with support for old & new environments, are created using the compat modifier. (default)

lodash compat

• Modern builds, tailored for newer environments with ES5/ES6 support, are created using the modern modifier.

lodash modern

• Strict builds, with ES strict mode enabled, are created using the strict modifier.

lodash strict

• Modularized builds, splitting lodash into modules, are created using the modularize modifier.

lodash modularize

Build commands:

• Use the category command to pass comma separated categories of functions to include in the build. Valid categories are “array”, “chain”, “collection”, “date”, “function”, “lang”, “object”, “number”, “string”, & “utility”.

lodash category=collection,function

• Use the exports command to pass comma separated names of ways to export the lodash function. Valid exports are “amd”, “commonjs”, “es”, “global”, “iojs”, “node”, “npm”, “none”, & “umd”.

lodash exports=amd,commonjs,iojs

• Use the iife command to specify code to replace the IIFE that wraps lodash.

lodash iife="!function(window,undefined){%output%}(this)"

• Use the include command to pass comma separated names of functions to include in the build.

lodash include=each,filter,map

• Use the minus command to pass comma separated function/category names to remove from the build.

lodash modern minus=result,shuffle

• Use the plus command to pass comma separated function/category names to add to the build.

lodash category=array plus=random,template

• Use the template command to pass the file path pattern used to match template files to precompile. Note: Precompiled templates are assigned to the _.<span class="me1">templates</span> object.

lodash template="./*.jst"

• Use the settings command to pass template settings used when precompiling templates.

lodash settings="{interpolate:/\{\{([\s\S]+?)\}\}/g}"

• Use the moduleId command to specify the AMD module ID for lodash or the module ID used to include lodash in compiled templates. Use “none” as the module ID to create compiled templates without a dependency on lodash.

lodash moduleId=underscore

Notes:

• All commands except compat & modern may be combined
• The exports values “es” & “npm” may only be used in conjunction with the modularize command
• The modularize command uses the first exports values as its module format, ignoring subsequent values.
• Unless specified by -o or --output all files created are saved to the current working directory
• Node.js 0.10.8-0.10.11 have bugs preventing minified builds

The following options are also supported:

-c, --stdout .......... Write output to standard output
-d, --development ..... Write only the non-minified development output
-h, --help ............ Display help information
-m, --source-map ...... Generate a source map using an optional source map URL
-o, --output .......... Write output to a given path/filename
-p, --production ...... Write only the minified production output
-s, --silent .......... Skip status updates normally logged to the console
-V, --version ......... Output current version of lodash

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

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

_.chunk(['a', 'b', 'c', 'd'], 3);
// => [['a', 'b', 'c'], ['d']]

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

_.compact([0, 1, false, 2, '', 3]);
// => [1, 2, 3]

Creates an array of unique array values not included in the other provided arrays using SameValueZero for equality comparisons.

_.difference([3, 2, 1], [4, 2]);
// => [3, 1]

This method is like _.difference except that it accepts iteratee which is invoked for each element of array and values to generate the criterion by which uniqueness is computed. The iteratee is invoked with one argument: (value).

_.differenceBy([3.1, 2.2, 1.3], [4.4, 2.5], Math.floor);
// => [3.1, 1.3]

// using the `_.property` callback shorthand
_.differenceBy([{ 'x': 2 }, { 'x': 1 }], [{ 'x': 1 }], 'x');
// => [{ 'x': 2 }]

This method is like _.difference except that it accepts comparator which is invoked to compare elements of array to values. The comparator is invoked with two arguments: (arrVal, othVal).

var objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }];

_.differenceWith(objects, [{ 'x': 1, 'y': 2 }], _.isEqual);
// => [{ 'x': 2, 'y': 1 }]

Creates a slice of array with n elements dropped from the beginning.

_.drop([1, 2, 3]);
// => [2, 3]

_.drop([1, 2, 3], 2);
// => [3]

_.drop([1, 2, 3], 5);
// => []

_.drop([1, 2, 3], 0);
// => [1, 2, 3]

Creates a slice of array with n elements dropped from the end.

_.dropRight([1, 2, 3]);
// => [1, 2]

_.dropRight([1, 2, 3], 2);
// => [1]

_.dropRight([1, 2, 3], 5);
// => []

_.dropRight([1, 2, 3], 0);
// => [1, 2, 3]

Creates a slice of array excluding elements dropped from the end. Elements are dropped until predicate returns falsey. The predicate is invoked with three arguments: (value, index, array).

var resolve = _.partial(_.map, _, 'user');

var users = [
  { 'user': 'barney',  'active': true },
  { 'user': 'fred',    'active': false },
  { 'user': 'pebbles', 'active': false }
];

resolve( _.dropRightWhile(users, function(o) { return !o.active; }) );
// => ['barney']

// using the `_.matches` callback shorthand
resolve( _.dropRightWhile(users, { 'user': 'pebbles', 'active': false }) );
// => ['barney', 'fred']

// using the `_.matchesProperty` callback shorthand
resolve( _.dropRightWhile(users, ['active', false]) );
// => ['barney']

// using the `_.property` callback shorthand
resolve( _.dropRightWhile(users, 'active') );
// => ['barney', 'fred', 'pebbles']

Creates a slice of array excluding elements dropped from the beginning. Elements are dropped until predicate returns falsey. The predicate is invoked with three arguments: (value, index, array).

var resolve = _.partial(_.map, _, 'user');

var users = [
  { 'user': 'barney',  'active': false },
  { 'user': 'fred',    'active': false },
  { 'user': 'pebbles', 'active': true }
];

resolve( _.dropWhile(users, function(o) { return !o.active; }) );
// => ['pebbles']

// using the `_.matches` callback shorthand
resolve( _.dropWhile(users, { 'user': 'barney', 'active': false }) );
// => ['fred', 'pebbles']

// using the `_.matchesProperty` callback shorthand
resolve( _.dropWhile(users, ['active', false]) );
// => ['pebbles']

// using the `_.property` callback shorthand
resolve( _.dropWhile(users, 'active') );
// => ['barney', 'fred', 'pebbles']

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

Note: This method mutates array.

var array = [1, 2, 3];

_.fill(array, 'a');
console.log(array);
// => ['a', 'a', 'a']

_.fill(Array(3), 2);
// => [2, 2, 2]

_.fill([4, 6, 8, 10], '*', 1, 3);
// => [4, '*', '*', 10]

This method is like _.find except that it returns the index of the first element predicate returns truthy for instead of the element itself.

var users = [
  { 'user': 'barney',  'active': false },
  { 'user': 'fred',    'active': false },
  { 'user': 'pebbles', 'active': true }
];

_.findIndex(users, function(o) { return o.user == 'barney'; });
// => 0

// using the `_.matches` callback shorthand
_.findIndex(users, { 'user': 'fred', 'active': false });
// => 1

// using the `_.matchesProperty` callback shorthand
_.findIndex(users, ['active', false]);
// => 0

// using the `_.property` callback shorthand
_.findIndex(users, 'active');
// => 2

This method is like _.findIndex except that it iterates over elements of collection from right to left.

var users = [
  { 'user': 'barney',  'active': true },
  { 'user': 'fred',    'active': false },
  { 'user': 'pebbles', 'active': false }
];

_.findLastIndex(users, function(o) { return o.user == 'pebbles'; });
// => 2

// using the `_.matches` callback shorthand
_.findLastIndex(users, { 'user': 'barney', 'active': true });
// => 0

// using the `_.matchesProperty` callback shorthand
_.findLastIndex(users, ['active', false]);
// => 2

// using the `_.property` callback shorthand
_.findLastIndex(users, 'active');
// => 0

Flattens array a single level.

_.flatten([1, [2, 3, [4]]]);
// => [1, 2, 3, [4]]

This method is like _.flatten except that it recursively flattens array.

_.flattenDeep([1, [2, 3, [4]]]);
// => [1, 2, 3, 4]

Gets the first element of array.

_.head([1, 2, 3]);
// => 1

_.head([]);
// => undefined

Gets the index at which the first occurrence of value is found in array using SameValueZero for equality comparisons. If fromIndex is negative, it's used as the offset from the end of array. If array is sorted providing true for fromIndex performs a faster binary search.

_.indexOf([1, 2, 1, 2], 2);
// => 1

// using `fromIndex`
_.indexOf([1, 2, 1, 2], 2, 2);
// => 3

Gets all but the last element of array.

_.initial([1, 2, 3]);
// => [1, 2]

Creates an array of unique values that are included in all of the provided arrays using SameValueZero for equality comparisons.

_.intersection([2, 1], [4, 2], [1, 2]);
// => [2]

This method is like _.intersection except that it accepts iteratee which is invoked for each element of each arrays to generate the criterion by which uniqueness is computed. The iteratee is invoked with one argument: (value).

_.intersectionBy([2.1, 1.2], [4.3, 2.4], Math.floor);
// => [2.1]

// using the `_.property` callback shorthand
_.intersectionBy([{ 'x': 1 }], [{ 'x': 2 }, { 'x': 1 }], 'x');
// => [{ 'x': 1 }]

This method is like _.intersection except that it accepts comparator which is invoked to compare elements of arrays. The comparator is invoked with two arguments: (arrVal, othVal).

var objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }];
var others = [{ 'x': 1, 'y': 1 }, { 'x': 1, 'y': 2 }];

_.intersectionWith(objects, others, _.isEqual);
// => [{ 'x': 1, 'y': 2 }]

Gets the last element of array.

_.last([1, 2, 3]);
// => 3

This method is like _.indexOf except that it iterates over elements of array from right to left.

_.lastIndexOf([1, 2, 1, 2], 2);
// => 3

// using `fromIndex`
_.lastIndexOf([1, 2, 1, 2], 2, 2);
// => 1

Reverses array so that the first element becomes the last, the second element becomes the second to last, and so on.

Note: This method mutates array.

var array = [1, 2, 3];

_.reverse(array);
// => [3, 2, 1]

console.log(array);
// => [3, 2, 1]

Removes all provided values from array using SameValueZero for equality comparisons.

Note: Unlike _.without, this method mutates array.

var array = [1, 2, 3, 1, 2, 3];

_.pull(array, 2, 3);
console.log(array);
// => [1, 1]

This method is like _.pull except that it accepts an array of values to remove.

Note: Unlike _.difference, this method mutates array.

var array = [1, 2, 3, 1, 2, 3];

_.pull(array, [2, 3]);
console.log(array);
// => [1, 1]

This method is like _.pullAll except that it accepts iteratee which is invoked for each element of array and values to to generate the criterion by which uniqueness is computed. The iteratee is invoked with one argument: (value).

Note: Unlike _.differenceBy, this method mutates array.

var array = [{ 'x': 1 }, { 'x': 2 }, { 'x': 3 }, { 'x': 1 }];

_.pullAllBy(array, [{ 'x': 1 }, { 'x': 3 }], 'x');
console.log(array);
// => [{ 'x': 2 }]

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

Note: Unlike _.at, this method mutates array.

var array = [5, 10, 15, 20];
var evens = _.pullAt(array, 1, 3);

console.log(array);
// => [5, 15]

console.log(evens);
// => [10, 20]

Removes all elements from array that predicate returns truthy for and returns an array of the removed elements. The predicate is invoked with three arguments: (value, index, array).

Note: Unlike _.filter, this method mutates array.

var array = [1, 2, 3, 4];
var evens = _.remove(array, function(n) {
  return n % 2 == 0;
});

console.log(array);
// => [1, 3]

console.log(evens);
// => [2, 4]

Creates a slice of array from start up to, but not including, end.

Note: This method is used instead of Array#slice to ensure dense arrays are returned.

Uses a binary search to determine the lowest index at which value should be inserted into array in order to maintain its sort order.

_.sortedIndex([30, 50], 40);
// => 1

_.sortedIndex([4, 5], 4);
// => 0

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

var dict = { 'thirty': 30, 'forty': 40, 'fifty': 50 };

_.sortedIndexBy(['thirty', 'fifty'], 'forty', _.propertyOf(dict));
// => 1

// using the `_.property` callback shorthand
_.sortedIndexBy([{ 'x': 4 }, { 'x': 5 }], { 'x': 4 }, 'x');
// => 0

This method is like _.indexOf except that it performs a binary search on a sorted array.

_.sortedIndexOf([1, 1, 2, 2], 2);
// => 2

This method is like _.sortedIndex except that it returns the highest index at which value should be inserted into array in order to maintain its sort order.

_.sortedLastIndex([4, 5], 4);
// => 1

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

// using the `_.property` callback shorthand
_.sortedLastIndexBy([{ 'x': 4 }, { 'x': 5 }], { 'x': 4 }, 'x');
// => 1

This method is like _.lastIndexOf except that it performs a binary search on a sorted array.

_.sortedLastIndexOf([1, 1, 2, 2], 2);
// => 3

This method is like _.uniq except that it's designed and optimized for sorted arrays.

_.sortedUniq([1, 1, 2]);
// => [1, 2]

This method is like _.uniqBy except that it's designed and optimized for sorted arrays.

_.sortedUniqBy([1.1, 1.2, 2.3, 2.4], Math.floor);
// => [1.1, 2.2]

Gets all but the first element of array.

_.tail([1, 2, 3]);
// => [2, 3]

Creates a slice of array with n elements taken from the beginning.

_.take([1, 2, 3]);
// => [1]

_.take([1, 2, 3], 2);
// => [1, 2]

_.take([1, 2, 3], 5);
// => [1, 2, 3]

_.take([1, 2, 3], 0);
// => []

Creates a slice of array with n elements taken from the end.

_.takeRight([1, 2, 3]);
// => [3]

_.takeRight([1, 2, 3], 2);
// => [2, 3]

_.takeRight([1, 2, 3], 5);
// => [1, 2, 3]

_.takeRight([1, 2, 3], 0);
// => []

Creates a slice of array with elements taken from the end. Elements are taken until predicate returns falsey. The predicate is invoked with three arguments: (value, index, array).

var resolve = _.partial(_.map, _, 'user');

var users = [
  { 'user': 'barney',  'active': true },
  { 'user': 'fred',    'active': false },
  { 'user': 'pebbles', 'active': false }
];

resolve( _.takeRightWhile(users, function(o) { return !o.active; }) );
// => ['fred', 'pebbles']

// using the `_.matches` callback shorthand
resolve( _.takeRightWhile(users, { 'user': 'pebbles', 'active': false }) );
// => ['pebbles']

// using the `_.matchesProperty` callback shorthand
resolve( _.takeRightWhile(users, ['active', false]) );
// => ['fred', 'pebbles']

// using the `_.property` callback shorthand
resolve( _.takeRightWhile(users, 'active') );
// => []

Creates a slice of array with elements taken from the beginning. Elements are taken until predicate returns falsey. The predicate is invoked with three arguments: (value, index, array).

var resolve = _.partial(_.map, _, 'user');

var users = [
  { 'user': 'barney',  'active': false },
  { 'user': 'fred',    'active': false},
  { 'user': 'pebbles', 'active': true }
];

resolve( _.takeWhile(users, function(o) { return !o.active; }) );
// => ['barney', 'fred']

// using the `_.matches` callback shorthand
resolve( _.takeWhile(users, { 'user': 'barney', 'active': false }) );
// => ['barney']

// using the `_.matchesProperty` callback shorthand
resolve( _.takeWhile(users, ['active', false]) );
// => ['barney', 'fred']

// using the `_.property` callback shorthand
resolve( _.takeWhile(users, 'active') );
// => []

Creates an array of unique values, in order, from all of the provided arrays using SameValueZero for equality comparisons.

_.union([2, 1], [4, 2], [1, 2]);
// => [2, 1, 4]

This method is like _.union except that it accepts iteratee which is invoked for each element of each arrays to generate the criterion by which uniqueness is computed. The iteratee is invoked with one argument: (value).

_.unionBy([2.1, 1.2], [4.3, 2.4], Math.floor);
// => [2.1, 1.2, 4.3]

// using the `_.property` callback shorthand
_.unionBy([{ 'x': 1 }], [{ 'x': 2 }, { 'x': 1 }], 'x');
// => [{ 'x': 1 }, { 'x': 2 }]

This method is like _.union except that it accepts comparator which is invoked to compare elements of arrays. The comparator is invoked with two arguments: (arrVal, othVal).

var objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }];
var others = [{ 'x': 1, 'y': 1 }, { 'x': 1, 'y': 2 }];

_.unionWith(objects, others, _.isEqual);
// => [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }, { 'x': 1, 'y': 1 }]

Creates a duplicate-free version of an array, using SameValueZero for equality comparisons, in which only the first occurrence of each element is kept.

_.uniq([2, 1, 2]);
// => [2, 1]

This method is like _.uniq except that it accepts iteratee which is invoked for each element in array to generate the criterion by which uniqueness is computed. The iteratee is invoked with one argument: (value).

_.uniqBy([2.1, 1.2, 2.3], Math.floor);
// => [2.1, 1.2]

// using the `_.property` callback shorthand
_.uniqBy([{ 'x': 1 }, { 'x': 2 }, { 'x': 1 }], 'x');
// => [{ 'x': 1 }, { 'x': 2 }]

This method is like _.uniq except that it accepts comparator which is invoked to compare elements of array. The comparator is invoked with two arguments: (arrVal, othVal).

var objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 },  { 'x': 1, 'y': 2 }];

_.uniqWith(objects, _.isEqual);
// => [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }]

This method is like _.zip except that it accepts an array of grouped elements and creates an array regrouping the elements to their pre-zip configuration.

var zipped = _.zip(['fred', 'barney'], [30, 40], [true, false]);
// => [['fred', 30, true], ['barney', 40, false]]

_.unzip(zipped);
// => [['fred', 'barney'], [30, 40], [true, false]]

This method is like _.unzip except that it accepts iteratee to specify how regrouped values should be combined. The iteratee is invoked with four arguments: (accumulator, value, index, group). The first element of each group is used as the initial accumulator value.

var zipped = _.zip([1, 2], [10, 20], [100, 200]);
// => [[1, 10, 100], [2, 20, 200]]

_.unzipWith(zipped, _.add);
// => [3, 30, 300]

Creates an array excluding all provided values using SameValueZero for equality comparisons.

_.without([1, 2, 1, 3], 1, 2);
// => [3]

Creates an array of unique values that is the symmetric difference of the provided arrays.

_.xor([2, 1], [4, 2]);
// => [1, 4]

This method is like _.xor except that it accepts iteratee which is invoked for each element of each arrays to generate the criterion by which uniqueness is computed. The iteratee is invoked with one argument: (value).

_.xorBy([2.1, 1.2], [4.3, 2.4], Math.floor);
// => [1.2, 4.3]

// using the `_.property` callback shorthand
_.xorBy([{ 'x': 1 }], [{ 'x': 2 }, { 'x': 1 }], 'x');
// => [{ 'x': 2 }]

This method is like _.xor except that it accepts comparator which is invoked to compare elements of arrays. The comparator is invoked with two arguments: (arrVal, othVal).

var objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }];
var others = [{ 'x': 1, 'y': 1 }, { 'x': 1, 'y': 2 }];

_.xorWith(objects, others, _.isEqual);
// => [{ 'x': 2, 'y': 1 }, { 'x': 1, 'y': 1 }]

Creates an array of grouped elements, the first of which contains the first elements of the given arrays, the second of which contains the second elements of the given arrays, and so on.

_.zip(['fred', 'barney'], [30, 40], [true, false]);
// => [['fred', 30, true], ['barney', 40, false]]

The inverse of _.pairs; this method returns an object composed from arrays of property names and values. Provide either a single two dimensional array, e.g. [[key1, value1], [key2, value2]] or two arrays, one of property names and one of corresponding values.

_.zipObject([['fred', 30], ['barney', 40]]);
// => { 'fred': 30, 'barney': 40 }

_.zipObject(['fred', 'barney'], [30, 40]);
// => { 'fred': 30, 'barney': 40 }

This method is like _.zip except that it accepts iteratee to specify how grouped values should be combined. The iteratee is invoked with four arguments: (accumulator, value, index, group). The first element of each group is used as the initial accumulator value.

_.zipWith([1, 2], [10, 20], [100, 200], _.add);
// => [111, 222]

Creates a lodash object which wraps value to enable implicit method chaining. Methods that operate on and return arrays, collections, and functions can be chained together. Methods that retrieve a single value or may return a primitive value will automatically end the chain sequence and return the unwrapped value. Otherwise, the value must be unwrapped with _#value.

Explicit chaining, which must be unwrapped with _#value in all cases, may be enabled using _.chain.

The execution of chained methods is lazy, that is, execution is deferred until _#value is implicitly or explicitly called.

Lazy evaluation allows several methods to support shortcut fusion. Shortcut fusion is an optimization strategy which merge iteratee calls; this can help to avoid the creation of intermediate data structures and greatly reduce the number of iteratee executions. Sections of a chain sequence may qualify for shortcut fusion if the section is applied to an array of at least two hundred elements and any iteratees or predicates accept only one argument. The heuristic for whether a section qualifies for shortcut fusion is subject to change.

Chaining is supported in custom builds as long as the _#value method is directly or indirectly included in the build.

In addition to lodash methods, wrappers have Array and String methods.

The wrapper Array methods are:
concat, join, pop, push, shift, sort, splice, and unshift

The wrapper String methods are:
replace and split

The wrapper methods that support shortcut fusion are:
compact, drop, dropRight, dropWhile, filter, find, findLast, head, initial, last, map, reject, reverse, slice, tail, take, takeRight, takeRightWhile, takeWhile, and toArray

The chainable wrapper methods are:
after, ary, assign, assignIn, assignInWith, assignWith, at, before, bind, bindAll, bindKey, chain, chunk, commit, compact, concat, conforms, conj, constant, countBy, create, curry, debounce, defaults, defaultsDeep, defer, delay, difference, differenceBy, differenceWith, disj, drop, dropRight, dropRightWhile, dropWhile, fill, filter, flatten, flattenDeep, flip, flow, flowRight, forEach, forEachRight, forIn, forInRight, forOwn, forOwnRight, functions, functionsIn, groupBy, initial, intersection, intersectionBy, intersectionWith, invert,invoke,iteratee,keyBy,keys,keysIn,map,mapKeys,mapValues,matches,matchesProperty,memoize,merge,mergeWith,method,methodOf,mixin,modArgs,modArgsSet', negate, nthArg, omit, omitBy, once, pairs, pairsIn, partial, partialRight, partition, pick, pickBy, plant, property, propertyOf, pull, pullAll, pullAllBy, pullAt, push, range, rearg, reject, remove, rest, reverse, sampleSize, set, setWith, shuffle, slice, sort, sortBy, sortByOrder, splice, spread, tail, take, takeRight, takeRightWhile, takeWhile, tap, throttle, thru, times, toArray, toPath, toPlainObject, transform, unary, union, unionBy, unionWith, uniq, uniqBy, uniqWith, unset, unshift, unzip, unzipWith, values, valuesIn, without, wrap, xor, xorBy, xorWith, zip, zipObject, and zipWith

The wrapper methods that are not chainable by default are:
add, attempt, camelCase, capitalize, ceil, clamp, clone, cloneDeep, cloneDeepWith, cloneWith, deburr, endsWith, eq, escape, escapeRegExp, every, find, findIndex, findKey, findLast, findLastIndex, findLastKey, floor, get, gt, gte, has, hasIn, head, identity, includes, indexOf, inRange, isArguments, isArray, isArrayLike, isArrayLikeObject, isBoolean, isDate, isElement, isEmpty, isEqual, isEqualWith, isError, isFinite, isFunction, isInteger, isLength, isMatch, isMatchWith, isNaN, isNative, isNil, isNull, isNumber, isObject, isObjectLike, isPlainObject, isRegExp, isSafeInteger, isString, isUndefined, isTypedArray, join, kebabCase, last, lastIndexOf, lowerCase, lowerFirst, lt, lte, max, maxBy, min, minBy, noConflict, noop, now, pad, padLeft, padRight, parseInt, pop, random, reduce, reduceRight, repeat, result, round, runInContext, sample, shift, size, snakeCase, some, sortedIndex, sortedIndexBy, sortedLastIndex, sortedLastIndexBy, startCase, startsWith, sum, sumBy, template, toLower, toInteger, toLength, toNumber, toSafeInteger, toString,toUpper,trim,trimLeft,trimRight,truncate,unescape,uniqueId,upperCase,upperFirst,value, andwords`

function square(n) {
  return n * n;
}

var wrapped = _([1, 2, 3]);

// returns an unwrapped value
wrapped.reduce(_.add);
// => 6

// returns a wrapped value
var squares = wrapped.map(square);

_.isArray(squares);
// => false

_.isArray(squares.value());
// => true

Creates a lodash object that wraps value with explicit method chaining enabled. The result of such method chaining must be unwrapped with _#value.

var users = [
  { 'user': 'barney',  'age': 36 },
  { 'user': 'fred',    'age': 40 },
  { 'user': 'pebbles', 'age': 1 }
];

var youngest = _
  .chain(users)
  .sortBy('age')
  .map(function(o) {
    return o.user + ' is ' + o.age;
  })
  .head()
  .value();
// => 'pebbles is 1'

Enables explicit method chaining on the wrapper object.

var users = [
  { 'user': 'barney', 'age': 36 },
  { 'user': 'fred',   'age': 40 }
];

// without explicit chaining
_(users).head();
// => { 'user': 'barney', 'age': 36 }

// with explicit chaining
_(users)
  .chain()
  .head()
  .pick('user')
  .value();
// => { 'user': 'barney' }

Executes the chained sequence and returns the wrapped result.

var array = [1, 2];
var wrapped = _(array).push(3);

console.log(array);
// => [1, 2]

wrapped = wrapped.commit();
console.log(array);
// => [1, 2, 3]

wrapped.last();
// => 3

console.log(array);
// => [1, 2, 3]

Creates a new array joining a wrapped array with any additional arrays and/or values.

var array = [1];
var wrapped = _(array).concat(2, [3], [[4]]);

console.log(wrapped.value());
// => [1, 2, 3, [4]]

console.log(array);
// => [1]

Gets the next value on a wrapped object following the iterator protocol.

var wrapped = _([1, 2]);

wrapped.next();
// => { 'done': false, 'value': 1 }

wrapped.next();
// => { 'done': false, 'value': 2 }

wrapped.next();
// => { 'done': true, 'value': undefined }

Creates a clone of the chained sequence planting value as the wrapped value.

function square(n) {
  return n * n;
}

var wrapped = _([1, 2]).map(square);
var other = wrapped.plant([3, 4]);

other.value();
// => [9, 16]

wrapped.value();
// => [1, 4]

Enables the wrapper to be iterable.

var wrapped = _([1, 2]);

wrapped[Symbol.iterator]() === wrapped;
// => true

Array.from(wrapped);
// => [1, 2]

Executes the chained sequence to extract the unwrapped value.

_([1, 2, 3]).value();
// => [1, 2, 3]

This method invokes interceptor and returns value. The interceptor is invoked with one argument; (value). The purpose of this method is to "tap into" a method chain in order to perform operations on intermediate results within the chain.

_([1, 2, 3])
 .tap(function(array) {
   array.pop();
 })
 .reverse()
 .value();
// => [2, 1]

This method is like _.tap except that it returns the result of interceptor.

_('  abc  ')
 .chain()
 .trim()
 .thru(function(value) {
   return [value];
 })
 .value();
// => ['abc']

Creates an object composed of keys generated from the results of running each element of collection 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).

_.countBy([6.1, 4.2, 6.3], Math.floor);
// => { '4': 1, '6': 2 }

_.countBy(['one', 'two', 'three'], 'length');
// => { '3': 2, '5': 1 }

Checks if predicate returns truthy for all elements of collection. Iteration is stopped once predicate returns falsey. The predicate is invoked with three arguments: (value, index|key, collection).

_.every([true, 1, null, 'yes'], Boolean);
// => false

var users = [
  { 'user': 'barney', 'active': false },
  { 'user': 'fred',   'active': false }
];

// using the `_.matches` callback shorthand
_.every(users, { 'user': 'barney', 'active': false });
// => false

// using the `_.matchesProperty` callback shorthand
_.every(users, ['active', false]);
// => true

// using the `_.property` callback shorthand
_.every(users, 'active');
// => false

Iterates over elements of collection, returning an array of all elements predicate returns truthy for. The predicate is invoked with three arguments:
(value, index|key, collection).

var resolve = _.partial(_.map, _, 'user');

var users = [
  { 'user': 'barney', 'age': 36, 'active': true },
  { 'user': 'fred',   'age': 40, 'active': false }
];

resolve( _.filter(users, function(o) { return !o.active; }) );
// => ['fred']

// using the `_.matches` callback shorthand
resolve( _.filter(users, { 'age': 36, 'active': true }) );
// => ['barney']

// using the `_.matchesProperty` callback shorthand
resolve( _.filter(users, ['active', false]) );
// => ['fred']

// using the `_.property` callback shorthand
resolve( _.filter(users, 'active') );
// => ['barney']

Iterates over elements of collection, returning the first element predicate returns truthy for. The predicate is invoked with three arguments:
(value, index|key, collection).

var resolve = _.partial(_.result, _, 'user');

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

resolve( _.find(users, function(o) { return o.age < 40; }) );
// => 'barney'

// using the `_.matches` callback shorthand
resolve( _.find(users, { 'age': 1, 'active': true }) );
// => 'pebbles'

// using the `_.matchesProperty` callback shorthand
resolve( _.find(users, ['active', false]) );
// => 'fred'

// using the `_.property` callback shorthand
resolve( _.find(users, 'active') );
// => 'barney'

This method is like _.find except that it iterates over elements of collection from right to left.

_.findLast([1, 2, 3, 4], function(n) {
  return n % 2 == 1;
});
// => 3

Iterates over elements of collection invoking iteratee for each element. The iteratee is invoked with three arguments: (value, index|key, collection). Iteratee functions may exit iteration early by explicitly returning false.

Note: As with other "Collections" methods, objects with a "length" property are iterated like arrays. To avoid this behavior use _.forIn or _.forOwn for object iteration.

_([1, 2]).forEach(function(value) {
  console.log(value);
});
// => logs `1` then `2`

_.forEach({ 'a': 1, 'b': 2 }, function(value, key) {
  console.log(key);
});
// => logs 'a' then 'b' (iteration order is not guaranteed)

This method is like _.forEach except that it iterates over elements of collection from right to left.

_.forEachRight([1, 2], function(value) {
  console.log(value);
});
// => logs `2` then `1`

Creates an object composed of keys generated from the results of running each element of collection through iteratee. The corresponding value of each key is an array of the elements responsible for generating the key. The iteratee is invoked with one argument: (value).

_.groupBy([6.1, 4.2, 6.3], Math.floor);
// => { '4': [4.2], '6': [6.1, 6.3] }

// using the `_.property` callback shorthand
_.groupBy(['one', 'two', 'three'], 'length');
// => { '3': ['one', 'two'], '5': ['three'] }

Checks if target is in collection using SameValueZero for equality comparisons. If fromIndex is negative, it's used as the offset from the end of collection.

_.includes([1, 2, 3], 1);
// => true

_.includes([1, 2, 3], 1, 2);
// => false

_.includes({ 'user': 'fred', 'age': 40 }, 'fred');
// => true

_.includes('pebbles', 'eb');
// => true

Invokes the method at path of each element in collection, returning an array of the results of each invoked method. Any additional arguments are provided to each invoked method. If methodName is a function it's invoked for, and this bound to, each element in collection.

_.invoke([[5, 1, 7], [3, 2, 1]], 'sort');
// => [[1, 5, 7], [1, 2, 3]]

_.invoke([123, 456], String.prototype.split, '');
// => [['1', '2', '3'], ['4', '5', '6']]

Creates an object composed of keys generated from the results of running each element of collection 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).

var keyData = [
  { 'dir': 'left', 'code': 97 },
  { 'dir': 'right', 'code': 100 }
];

_.keyBy(keyData, 'dir');
// => { 'left': { 'dir': 'left', 'code': 97 }, 'right': { 'dir': 'right', 'code': 100 } }

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

Creates an array of values by running each element in collection through iteratee. The iteratee is invoked with three arguments:
(value, index|key, collection).

Many lodash methods are guarded to work as iteratees for methods like _.every, _.filter, _.map, _.mapValues, _.reject, and _.some.

The guarded methods are:
ary, callback, curry, curryRight, drop, dropRight, every, fill, invert, parseInt, random, range, slice, some, sortBy, take, takeRight, template, trim, trimLeft, trimRight, uniq, and words

function square(n) {
  return n * n;
}

_.map([1, 2], square);
// => [3, 6]

_.map({ 'a': 1, 'b': 2 }, square);
// => [3, 6] (iteration order is not guaranteed)

var users = [
  { 'user': 'barney' },
  { 'user': 'fred' }
];

// using the `_.property` callback shorthand
_.map(users, 'user');
// => ['barney', 'fred']

Creates an array of elements split into two groups, the first of which contains elements predicate returns truthy for, while the second of which contains elements predicate returns falsey for. The predicate is invoked with three arguments: (value, index|key, collection).

var resolve = function(result) {
  return _.map(result, function(array) { return _.map(array, 'user'); });
};

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

resolve( _.partition(users, function(o) { return o.active; }) );
// => [['fred'], ['barney', 'pebbles']]

// using the `_.matches` callback shorthand
resolve( _.partition(users, { 'age': 1, 'active': false }) );
// => [['pebbles'], ['barney', 'fred']]

// using the `_.matchesProperty` callback shorthand
resolve( _.partition(users, ['active', false]) );
// => [['barney', 'pebbles'], ['fred']]

// using the `_.property` callback shorthand
resolve( _.partition(users, 'active') );
// => [['fred'], ['barney', 'pebbles']]

Reduces collection to a value which is the accumulated result of running each element in collection through iteratee, where each successive invocation is supplied the return value of the previous. If accumulator is not provided the first element of collection is used as the initial value. The iteratee is invoked with four arguments:
(accumulator, value, index|key, collection).

Many lodash methods are guarded to work as iteratees for methods like _.reduce, _.reduceRight, and _.transform.

The guarded methods are:
assign, defaults, defaultsDeep, includes, merge, sortBy, and sortByOrder

_.reduce([1, 2], function(sum, n) {
  return sum + n;
});
// => 3

_.reduce({ 'a': 1, 'b': 2, 'c': 1 }, function(result, value, key) {
  (result[value] || (result[value] = [])).push(key);
  return result;
}, {});
// => { '1': ['a', 'c'], '2': ['b'] } (iteration order is not guaranteed)

This method is like _.reduce except that it iterates over elements of collection from right to left.

var array = [[0, 1], [2, 3], [4, 5]];

_.reduceRight(array, function(flattened, other) {
  return flattened.concat(other);
}, []);
// => [4, 5, 2, 3, 0, 1]

The opposite of _.filter; this method returns the elements of collection that predicate does not return truthy for.

var resolve = _.partial(_.map, _, 'user');

var users = [
  { 'user': 'barney', 'age': 36, 'active': false },
  { 'user': 'fred',   'age': 40, 'active': true }
];

resolve( _.reject(users, function(o) { return !o.active; }) );
// => ['fred']

// using the `_.matches` callback shorthand
resolve( _.reject(users, { 'age': 40, 'active': true }) );
// => ['barney']

// using the `_.matchesProperty` callback shorthand
resolve( _.reject(users, ['active', false]) );
// => ['fred']

// using the `_.property` callback shorthand
resolve( _.reject(users, 'active') );
// => ['barney']

Gets a random element from collection.

_.sample([1, 2, 3, 4]);
// => 2

Gets n random elements from collection.

_.sampleSize([1, 2, 3, 4], 2);
// => [3, 1]

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

_.shuffle([1, 2, 3, 4]);
// => [4, 1, 3, 2]

Gets the size of collection by returning its length for array-like values or the number of own enumerable properties for objects.

_.size([1, 2, 3]);
// => 3

_.size({ 'a': 1, 'b': 2 });
// => 2

_.size('pebbles');
// => 7

Checks if predicate returns truthy for any element of collection. Iteration is stopped once predicate returns truthy. The predicate is invoked with three arguments: (value, index|key, collection).

_.some([null, 0, 'yes', false], Boolean);
// => true

var users = [
  { 'user': 'barney', 'active': true },
  { 'user': 'fred',   'active': false }
];

// using the `_.matches` callback shorthand
_.some(users, { 'user': 'barney', 'active': false });
// => false

// using the `_.matchesProperty` callback shorthand
_.some(users, ['active', false]);
// => true

// using the `_.property` callback shorthand
_.some(users, 'active');
// => true

Creates an array of elements, sorted in ascending order by the results of running each element in a collection through each iteratee. This method performs a stable sort, that is, it preserves the original sort order of equal elements. The iteratees are invoked with one argument: (value).

var resolve = _.partial(_.map, _, _.values);

var users = [
  { 'user': 'fred',   'age': 48 },
  { 'user': 'barney', 'age': 36 },
  { 'user': 'fred',   'age': 42 },
  { 'user': 'barney', 'age': 34 }
];

resolve( _.sortBy(users, function(o) { return o.user; }) );
// => // => [['barney', 36], ['barney', 34], ['fred', 48], ['fred', 42]]

resolve( _.sortBy(users, ['user', 'age']) );
// => [['barney', 34], ['barney', 36], ['fred', 42], ['fred', 48]]

resolve( _.sortBy(users, 'user', function(o) {
  return Math.floor(o.age / 10);
}) );
// => [['barney', 36], ['barney', 34], ['fred', 48], ['fred', 42]]

This method is like _.sortBy except that it allows specifying the sort orders of the iteratees to sort by. If orders is unspecified, all values are sorted in ascending order. Otherwise, a value is sorted in ascending order if its corresponding order is "asc", and descending if "desc".

var resolve = _.partial(_.map, _, _.values);

var users = [
  { 'user': 'fred',   'age': 48 },
  { 'user': 'barney', 'age': 34 },
  { 'user': 'fred',   'age': 42 },
  { 'user': 'barney', 'age': 36 }
];

// sort by `user` in ascending order and by `age` in descending order
resolve( _.sortByOrder(users, ['user', 'age'], ['asc', 'desc']) );
// => [['barney', 36], ['barney', 34], ['fred', 48], ['fred', 42]]

Gets the timestamp of the number of milliseconds that have elapsed since the Unix epoch (1 January 1970 00:00:00 UTC).

_.defer(function(stamp) {
  console.log(_.now() - stamp);
}, _.now());
// => logs the number of milliseconds it took for the deferred function to be invoked

The opposite of _.before; this method creates a function that invokes func once it's called n or more times.

var saves = ['profile', 'settings'];

var done = _.after(saves.length, function() {
  console.log('done saving!');
});

_.forEach(saves, function(type) {
  asyncSave({ 'type': type, 'complete': done });
});
// => logs 'done saving!' after the two async saves have completed

Creates a function that accepts up to n arguments, ignoring any additional arguments.

_.map(['6', '8', '10'], _.ary(parseInt, 1));
// => [6, 8, 10]

Creates a function that invokes func, with the this binding and arguments of the created function, while it's called less than n times. Subsequent calls to the created function return the result of the last func invocation.