lodash - Documentation

npm install lodash

import { chunk, map } from 'lodash';

const chunkedArray = chunk([1, 2, 3, 4, 5, 6], 2); // [[1, 2], [3, 4], [5, 6]]
const mappedArray = map([1, 2, 3], (n) => n * 2); // [2, 4, 6]

const _ = require('lodash');

const chunkedArray = _.chunk([1, 2, 3, 4, 5, 6], 2); // [[1, 2], [3, 4], [5, 6]]
const mappedArray = _.map([1, 2, 3], (n) => n * 2); // [2, 4, 6]

yarn add lodash

<script src="https://cdn.jsdelivr.net/npm/lodash@4.17.21/lodash.min.js"></script>
<script>
  // Lodash is now available as the '_' global variable.
  const result = _.chunk([1, 2, 3, 4, 5, 6], 2);
</script>
```  Remember that using a CDN exposes the entire library, even if you only need a small portion.


### Core Concepts and Terminology

Lodash is organized around collections (arrays and objects) and utility functions. Key concepts include:

* **Collections:** Lodash functions frequently work with collections (arrays and objects).  Functions are designed to handle both types efficiently.

* **Iterators:**  Many Lodash functions iterate over collections, applying a given function to each element.  `_.each`, `_.map`, `_.filter`, and `_.reduce` are examples of iterator functions.

* **Chaining:** Lodash supports method chaining, allowing you to string together multiple operations in a fluent and readable manner. This improves readability and allows for complex operations in a concise way.

* **Currying:** Some Lodash functions support currying, allowing you to create specialized versions of functions with pre-filled arguments.

* **Memoization:**  Some Lodash functions utilize memoization to cache results, improving performance for repeated calls with the same arguments.

* **_.get, _.set:** These functions provide safer ways to access and modify nested object properties, avoiding errors caused by undefined properties.

* **Modules:**  Lodash is modular; you can import only the functions you need, minimizing the size of your application.  Refer to the Lodash documentation for a list of available modules.

* **Underscore-style and method-style:** Lodash methods can be used in two ways: the underscore style (e.g., `_.map`) or method style (`_.map.call(array, ...)`).


Understanding these core concepts and terms is vital for effectively using Lodash in your projects.  Refer to the Lodash API documentation for a complete list of functions and their usage.




## Collections

Lodash provides a rich set of functions for working with collections (arrays and objects).  These functions are designed for efficiency and readability, simplifying common data manipulation tasks.

### Arrays

Lodash offers numerous functions specifically designed for manipulating arrays.  Here are some key categories and examples:

* **Creation & Modification:**
    * `_.chunk(array, [size=1])`: Creates an array of elements split into groups the length of `size`.
    * `_.compact(array)`: Creates a new array with all falsey values removed.  Falsey values include `false`, `null`, `0`, `""`, `undefined`, and `NaN`.
    * `_.concat(array, [values])`: Creates a new array concatenating `array` with any additional arrays and/or values.
    * `_.difference(array, [values])`: Creates an array of array values not included in the other given arrays.
    * `_.drop(array, [n=1])`: Creates a slice of `array` excluding `n` elements from the beginning.
    * `_.dropRight(array, [n=1])`: Creates a slice of `array` excluding `n` elements from the end.
    * `_.fill(array, value, [start=0], [end=array.length])`: Fills elements of `array` with `value` from `start` up to, but not including, `end`.
    * `_.flatten(array)`: Flattens a nested array.  `_.flattenDeep` flattens recursively.
    * `_.flattenDeep(array)`: Recursively flattens a nested array.
    * `_.fromPairs(pairs)`: Creates an object from key-value pairs.
    * `_.unzip(array)`: Groups the elements of each array at their corresponding indexes.  The inverse of `_.zip`.
    * `_.union(arrays)`: Creates an array of unique values, in order, from all given arrays.
    * `_.uniq(array)`: Creates a duplicate-free version of an array, using === to compare values, in the order they are first found in the array.  `_.uniqBy` allows customization of the uniqueness check.
    * `_.uniqBy(array, [iteratee=identity])`: Creates a duplicate-free version of an array, in which uniqueness is determined by the result of `iteratee`.


* **Searching & Finding:**
    * `_.indexOf(array, value, [fromIndex=0])`: Gets the index at which the first occurrence of `value` is found in `array`.
    * `_.lastIndexOf(array, value, [fromIndex=array.length-1])`: Gets the index at which the last occurrence of `value` is found in `array`.
    * `_.find(array, [predicate=_.identity], [fromIndex=0])`: Iterates over elements of `collection`, returning the first element predicate returns truthy for.
    * `_.findIndex(array, [predicate=_.identity], [fromIndex=0])`: This method is like `_.find`, except that it returns the index of the first element predicate returns truthy for instead of the element itself.


### Objects

Lodash provides functions for manipulating objects, including:

* **Creation & Modification:**
    * `_.assign(object, [sources])`: Assigns own enumerable string keyed properties of source objects to the destination object.
    * `_.defaults(object, [defaults])`: Assigns own and inherited enumerable string keyed properties of source objects to the destination object for all destination properties that resolve to `undefined`.
    * `_.clone(value)`: Creates a shallow clone of `value`.
    * `_.cloneDeep(value)`: Creates a deep clone of `value`.
    * `_.omit(object, [props])`: Creates an object composed of the own and inherited enumerable string keyed properties of object that are not omitted.
    * `_.pick(object, [props])`: Creates an object composed of the picked object properties.
    * `_.set(object, path, value)`: Sets the value at `path` of `object`. If a portion of `path` doesn't exist, it's created.  Handles nested objects gracefully.
    * `_.get(object, path, [defaultValue])`: Gets the value at `path` of `object`. If the resolved value is `undefined`, the `defaultValue` is returned in its place.  Handles nested objects gracefully.


* **Checking & Inspecting:**
    * `_.isEmpty(object)`: Checks if an object is empty.
    * `_.has(object, path)`: Checks if `object` has a direct or inherited property of the given `path`.
    * `_.isNil(value)`: Checks if value is `null` or `undefined`.
    * `_.isPlainObject(value)`: Checks if `value` is a plain object, that is, an object created by the `Object` constructor or one with a plain prototype (e.g. `{}`).


### Iteration Methods

These methods traverse collections (arrays and objects), applying a function to each element.

* `_.forEach(collection, [iteratee=_.identity])`: Iterates over elements of `collection` and invokes `iteratee` for each element.
* `_.forIn(object, [iteratee=_.identity])`: Iterates over own and inherited enumerable string keyed properties of an object and invokes `iteratee` for each property.
* `_.forOwn(object, [iteratee=_.identity])`: Iterates over own enumerable string keyed properties of an object and invokes `iteratee` for each property.
* `_.times(n, [iteratee=_.identity])`: Invokes the iteratee n times, and returns an array of the results of each invocation.


### Filtering Methods

These methods create new collections containing only elements that meet specific criteria.

* `_.filter(collection, [predicate=_.identity])`: Iterates over elements of `collection`, returning an array of all elements predicate returns truthy for.
* `_.reject(collection, [predicate=_.identity])`: The opposite of `_.filter`; returns elements for which the predicate returns falsy.
* `_.find(collection, [predicate=_.identity])`: Returns the first element that satisfies the provided testing function.
* `_.some(collection, [predicate=_.identity])`: Checks if predicate returns truthy for any element of collection.
* `_.every(collection, [predicate=_.identity])`: Checks if predicate returns truthy for all elements of collection.


### Transformation Methods

These methods create new collections by transforming existing ones.

* `_.map(collection, [iteratee=_.identity])`: Creates an array of values by running each element of collection thru iteratee. The iteratee is invoked with three arguments: (value, index|key, collection).
* `_.groupBy(collection, [iteratee=_.identity])`: Creates an object composed of keys generated from the results of running each element of collection thru iteratee. The order of grouped values is determined by the order they occur in collection. The corresponding value is an array of elements responsible for generating the key.
* `_.countBy(collection, [iteratee=_.identity])`: Creates an object composed of keys generated from the results of running each element of collection thru iteratee. The corresponding value is the number of times the key was returned by iteratee.


### Searching Methods

These methods help find specific elements within collections.

* `_.find(collection, [predicate=_.identity])`: Returns the first element that satisfies the provided testing function.
* `_.findIndex(collection, [predicate=_.identity])`: Returns the index of the first element that satisfies the provided testing function.
* `_.includes(collection, value, [fromIndex=0])`: Checks if collection includes the value.
* `_.indexOf(array, value, [fromIndex=0])`: Gets the index at which the first occurrence of value is found in array.
* `_.lastIndexOf(array, value, [fromIndex=array.length-1])`: Gets the index at which the last occurrence of value is found in array.


This is not an exhaustive list of all Lodash collection functions, but it covers many of the most commonly used ones.  Consult the official Lodash documentation for a complete reference.




## Utility Functions

Lodash provides a wide range of utility functions beyond its collection methods.  These functions handle various data types and common programming tasks.

### Working with Numbers

* `_.clamp(number, lower, upper)`: Clamps `number` within the inclusive range specified by `lower` and `upper`.
* `_.inRange(number, start, end)`: Checks if `number` is within the range specified by `start` and `end`.  `end` is exclusive.
* `_.random([lower=0], [upper=1], [floating])`: Produces a random number between the inclusive lower and upper bounds. If only one argument is provided, a number between 0 and the given number is returned.  If floating is true, or either bound is a float, a floating-point number is returned instead of an integer.
* `_.round(number, [precision=0])`: Rounds `number` to `precision` decimal places.


### Working with Strings

* `_.camelCase(string)`: Converts `string`, as space separated words, to camel case.
* `_.capitalize(string)`: Converts the first character of `string` to upper case and the remaining to lower case.
* `_.deburr(string)`: Deburrs `string` by converting Latin-1 Supplement and Latin Extended-A and B letters to basic Latin letters.
* `_.endsWith(string, target, [position=string.length])`: Checks if `string` ends with the given target string.
* `_.escape(string)`: Escapes the HTML in a given string of text.
* `_.kebabCase(string)`: Converts `string`, as a space separated words, to kebab case.
* `_.lowerCase(string)`: Converts `string` to lower case.
* `_.pad(string, length, [chars=' '])`: Pads `string` on the left and right sides if it’s shorter than `length`. Padding characters are truncated if they can’t be evenly divided by length.
* `_.padEnd(string, length, [chars=' '])`: Pads `string` on the right side if it’s shorter than `length`.
* `_.padStart(string, length, [chars=' '])`: Pads `string` on the left side if it’s shorter than `length`.
* `_.parseInt(string, radix)`: Parses `string` into an integer.
* `_.repeat(string, n)`: Repeats the given string `n` times.
* `_.snakeCase(string)`: Converts `string`, as space separated words, to snake case.
* `_.split(string, separator, [limit])`: Splits `string` by `separator`.
* `_.startsWith(string, target, [position=0])`: Checks if `string` starts with the given target string.
* `_.toLower(string)`: Converts `string` to lower case.
* `_.toUpper(string)`: Converts `string` to upper case.
* `_.trim(string, [chars=' '])`: Removes leading and trailing whitespace or specified characters from `string`.
* `_.trimEnd(string, [chars=' '])`: Removes trailing whitespace or specified characters from `string`.
* `_.trimStart(string, [chars=' '])`: Removes leading whitespace or specified characters from `string`.
* `_.truncate(string, [options])`: Truncates `string` if it's longer than the given maximum string length. The last characters will be replaced with the omission string which defaults to "...".


### Working with Dates

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


### Working with Objects

* `_.assignIn(object, ...sources)`: This method is like `_.assign` except that it iterates over inherited source properties.
* `_.defaultsDeep(object, ...sources)`: This method is like `_.defaults` except that it recursively assigns default properties.
* `_.isEqual(value, other)`: Performs a deep comparison between two values to determine if they are equivalent.
* `_.isMatch(object, source)`: Checks if `object` matches the source's properties.
* `_.merge(object, ...sources)`: 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.


### Working with Arrays

Many array utility functions are covered in the "Collections" section; however, here are a few more:

* `_.zip(...arrays)`: 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.


### Conditional Logic

* `_.cond(pairs)`: Creates a function that iterates over pairs and invokes the first pair whose predicate returns truthy.
* `_.defaultTo(value, defaultValue)`: Checks `value` to determine whether it’s an empty object, collection, map, set, or `undefined`/`null`; if it is, it returns the `defaultValue`.
* `_.ifElse(condition, ifTrue, ifFalse)`: Creates a function that will process either `ifTrue` or `ifFalse` based on the result of the condition function.
* `_.over(iteratees)`: Creates a function that invokes the iteratees with the arguments provided as its `this` binding and returns an array of the results.
* `_.overEvery(iteratees)`: Creates a function that checks if all of the predicates return truthy when invoked with the arguments provided as its `this` binding and `arguments`.
* `_.overSome(iteratees)`: Creates a function that checks if any of the predicates return truthy when invoked with the arguments provided as its `this` binding and `arguments`.
* `_.stubArray()` : Returns a new empty array.  Useful for stubbing methods.
* `_.stubFalse()` : Returns `false`. Useful for stubbing methods.
* `_.stubObject()` : Returns a new empty object. Useful for stubbing methods.
* `_.stubString()` : Returns an empty string. Useful for stubbing methods.
* `_.stubTrue()` : Returns `true`. Useful for stubbing methods.


### Type Checking

* `_.isArray(value)`: Checks if `value` is classified as an `Array` object.
* `_.isArrayBuffer(value)`: Checks if `value` is classified as an `ArrayBuffer` object.
* `_.isArrayLike(value)`: Checks if `value` is array-like. A value is considered array-like if it’s not a function and has a `length` property that’s an integer greater than or equal to 0.
* `_.isArguments(value)`: Checks if `value` is classified as an `arguments` object.
* `_.isBoolean(value)`: Checks if `value` is classified as a boolean primitive or object.
* `_.isBuffer(value)`: Checks if `value` is a buffer.
* `_.isDate(value)`: Checks if `value` is classified as a `Date` object.
* `_.isElement(value)`: Checks if `value` is a DOM element.
* `_.isEmpty(value)`: Checks if `value` is an empty object, collection, map or set.
* `_.isEqual(value, other)`: Performs a deep comparison between two values to determine if they are equivalent.
* `_.isError(value)`: Checks if `value` is an `Error` object.
* `_.isFinite(value)`: Checks if `value` is a finite number.
* `_.isFunction(value)`: Checks if `value` is classified as a `Function` object.
* `_.isInteger(value)`: Checks if `value` is an integer.
* `_.isLength(value)`: Checks if `value` is a valid array-like length.
* `_.isMap(value)`: Checks if `value` is classified as a `Map` object.
* `_.isNaN(value)`: Checks if `value` is `NaN`.
* `_.isNil(value)`: Checks if `value` is `null` or `undefined`.
* `_.isNull(value)`: Checks if `value` is `null`.
* `_.isNumber(value)`: Checks if `value` is classified as a number primitive or object.
* `_.isObject(value)`: Checks if `value` is the language type of `Object`. (e.g. arrays, functions, objects, regexes, new Number(0), and new String('') are objects.)
* `_.isObjectLike(value)`: Checks if `value` is object-like. A value is object-like if it’s not a primitive and has a `typeof` result of "object".
* `_.isPlainObject(value)`: Checks if `value` is a plain object, that is, an object created by the `Object` constructor or one with a plain prototype (e.g. `{}`).
* `_.isRegExp(value)`: Checks if `value` is classified as a `RegExp` object.
* `_.isSet(value)`: Checks if `value` is classified as a `Set` object.
* _.isString(value): Checks if `value` is classified as a `String` primitive or object.
* `_.isSymbol(value)`: Checks if `value` is classified as a `Symbol` primitive or object.
* `_.isTypedArray(value)`: Checks if `value` is classified as a typed array.
* `_.isUndefined(value)`: Checks if `value` is `undefined`.


This is a selection of Lodash's utility functions.  The complete list and detailed explanations can be found in the official Lodash documentation. Remember to import only the functions you need to keep your bundle size small and improve performance.




## Advanced Usage

Lodash offers several advanced features that can significantly enhance your workflow and code efficiency.  This section explores these techniques.

### Chaining Methods

Lodash supports method chaining, allowing you to sequence multiple operations on a collection or value.  This improves readability and conciseness.  Chaining is enabled by the `_.chain()` method.  The chain is finalized using `_.value()`.

```javascript
const result = _( [1, 2, 3] )
  .map( (n) => n * 2 )
  .filter( (n) => n > 3 )
  .value(); // => [4, 6]

const add = (a, b, c) => a + b + c;
const add5 = _.partial(add, 5); // Partially apply the first argument as 5
const result = add5(2, 3); // => 10

const expensiveFunction = _.memoize((n) => {
  console.log('Calculating...'); // This will only log once for each unique n
  // ... some computationally expensive operation ...
  return n * 2;
});

console.log(expensiveFunction(5)); // => 10, logs "Calculating..."
console.log(expensiveFunction(5)); // => 10, does NOT log "Calculating..." (cached)
console.log(expensiveFunction(10)); // => 20, logs "Calculating..."

const addOne = (x) => x + 1;
const multiplyByTwo = (x) => x * 2;
const composedFunction = _.flow([addOne, multiplyByTwo]);
const result = composedFunction(3); // => 8 ( (3 + 1) * 2 )

const composedFunctionRight = _.flowRight([addOne, multiplyByTwo]);
const resultRight = composedFunctionRight(3); // => 7 ( 3 * 2 + 1)

const greet = (greeting, name) => `${greeting}, ${name}!`;
const greetJohn = _.partial(greet, 'Hello');
const result = greetJohn('John'); // => 'Hello, John!'

async function fetchDataAndProcess() {
  const data = await someAsyncFunction();
  const processedData = _.map(data, (item) => item.value * 2);
  // ... further processing ...
}

import { chunk, map } from 'lodash'; // Import specific functions from the 'lodash' package

const chunkedArray = chunk([1, 2, 3, 4, 5, 6], 2);
const mappedArray = map([1, 2, 3], (n) => n * 2);

import _array from 'lodash/array'; // Import the entire 'array' module

const chunkedArray = _array.chunk([1, 2, 3, 4, 5, 6], 2);

const { chunk, map } = require('lodash');

const chunkedArray = chunk([1, 2, 3, 4, 5, 6], 2);
const mappedArray = map([1, 2, 3], (n) => n * 2);

const _array = require('lodash/array');

const chunkedArray = _array.chunk([1, 2, 3, 4, 5, 6], 2);

// my-lodash-utils.js
const myCustomFunction = (arr) => {
  // ... your custom function logic ...
  return arr.map(x => x * 2);
};

export { myCustomFunction };

// Your main application code:
import { myCustomFunction } from './my-lodash-utils';
import { map } from 'lodash';

const result = myCustomFunction([1, 2, 3]); // Use your custom function
const mappedResult = map([4,5,6], x => x + 1); // Use standard lodash