Array Methods

/**
 * Casts `value` as an array if it's not one.
 * @param value - The value to inspect
 * @returns Returns the cast array
 */
function castArray<T>(value?: T | T[]): T[];

/**
 * Creates an array of elements split into groups the length of `size`.
 * @param array - The array to process
 * @param size - The length of each chunk (defaults to 1)
 * @returns Returns the new array of chunks
 */
function chunk<T>(array: T[], size?: number): T[][];

import { chunk } from 'lodash';

// Basic chunking
const numbers = [1, 2, 3, 4, 5, 6, 7, 8];
console.log(chunk(numbers, 3));
// => [[1, 2, 3], [4, 5, 6], [7, 8]]

// Chunking with different sizes
console.log(chunk(numbers, 2));
// => [[1, 2], [3, 4], [5, 6], [7, 8]]

// Single element chunks (default)
console.log(chunk([1, 2, 3]));
// => [[1], [2], [3]]

// Common use case: pagination
const users = [
  { name: 'Alice' }, { name: 'Bob' }, { name: 'Charlie' },
  { name: 'David' }, { name: 'Eve' }, { name: 'Frank' }
];
const pages = chunk(users, 2); // 2 users per page
console.log(pages);
// => [
//   [{ name: 'Alice' }, { name: 'Bob' }],
//   [{ name: 'Charlie' }, { name: 'David' }],
//   [{ name: 'Eve' }, { name: 'Frank' }]
// ]

/**
 * Creates an array with all falsey values removed. The values false, null,
 * 0, "", undefined, and NaN are falsey.
 * @param array - The array to compact
 * @returns Returns the new array of filtered values
 */
function compact<T>(array: (T | null | undefined | false | 0 | "")[]): T[];

/**
 * Creates a new array concatenating `array` with any additional arrays and/or values.
 * @param array - The array to concatenate
 * @param values - The values to concatenate
 * @returns Returns the new concatenated array
 */
function concat<T>(array: T[], ...values: Array<T | T[]>): T[];

/**
 * Creates an array of `array` values not included in the other given arrays
 * using SameValueZero for equality comparisons.
 * @param array - The array to inspect
 * @param values - The values to exclude
 * @returns Returns the new array of filtered values
 */
function difference<T>(array: T[], ...values: T[][]): T[];

/**
 * 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 they're compared.
 * @param array - The array to inspect
 * @param values - The values to exclude
 * @param iteratee - The iteratee invoked per element
 * @returns Returns the new array of filtered values
 */
function differenceBy<T>(
  array: T[],
  values: T[],
  iteratee?: string | ((value: T) => any)
): T[];

/**
 * This method is like `difference` except that it accepts `comparator` which
 * is invoked to compare elements of `array` to `values`.
 * @param array - The array to inspect
 * @param values - The values to exclude
 * @param comparator - The comparator invoked per element
 * @returns Returns the new array of filtered values
 */
function differenceWith<T>(
  array: T[],
  values: T[],
  comparator?: (arrVal: T, othVal: T) => boolean
): T[];

/**
 * Creates a slice of `array` with `n` elements dropped from the beginning.
 * @param array - The array to query
 * @param n - The number of elements to drop (defaults to 1)
 * @returns Returns the slice of `array`
 */
function drop<T>(array: T[], n?: number): T[];

/**
 * Creates a slice of `array` with `n` elements dropped from the end.
 * @param array - The array to query
 * @param n - The number of elements to drop (defaults to 1)
 * @returns Returns the slice of `array`
 */
function dropRight<T>(array: T[], n?: number): T[];

/**
 * Creates a slice of `array` excluding elements dropped from the end.
 * Elements are dropped until `predicate` returns falsey.
 * @param array - The array to query
 * @param predicate - The function invoked per iteration
 * @returns Returns the slice of `array`
 */
function dropRightWhile<T>(
  array: T[],
  predicate?: string | object | ((value: T, index: number, array: T[]) => boolean)
): T[];

/**
 * Creates a slice of `array` excluding elements dropped from the beginning.
 * Elements are dropped until `predicate` returns falsey.
 * @param array - The array to query
 * @param predicate - The function invoked per iteration
 * @returns Returns the slice of `array`
 */
function dropWhile<T>(
  array: T[],
  predicate?: string | object | ((value: T, index: number, array: T[]) => boolean)
): T[];

/**
 * Fills elements of `array` with `value` from `start` up to, but not
 * including, `end`.
 * @param array - The array to fill
 * @param value - The value to fill `array` with
 * @param start - The start position (defaults to 0)
 * @param end - The end position (defaults to array.length)
 * @returns Returns `array`
 */
function fill<T, U>(array: T[], value: U, start?: number, end?: number): (T | U)[];

/**
 * This method is like `find` except that it returns the index of the first
 * element `predicate` returns truthy for instead of the element itself.
 * @param array - The array to inspect
 * @param predicate - The function invoked per iteration
 * @param fromIndex - The index to search from (defaults to 0)
 * @returns Returns the index of the found element, else -1
 */
function findIndex<T>(
  array: T[],
  predicate?: string | object | ((value: T, index: number, array: T[]) => boolean),
  fromIndex?: number
): number;

/**
 * This method is like `findIndex` except that it iterates over elements
 * of `collection` from right to left.
 * @param array - The array to inspect
 * @param predicate - The function invoked per iteration
 * @param fromIndex - The index to search from (defaults to array.length - 1)
 * @returns Returns the index of the found element, else -1
 */
function findLastIndex<T>(
  array: T[],
  predicate?: string | object | ((value: T, index: number, array: T[]) => boolean),
  fromIndex?: number
): number;

/**
 * Flattens `array` a single level deep.
 * @param array - The array to flatten
 * @returns Returns the new flattened array
 */
function flatten<T>(array: T[] | T[][]): T[];

/**
 * Recursively flattens `array`.
 * @param array - The array to flatten
 * @returns Returns the new flattened array
 */
function flattenDeep<T>(array: any[]): T[];

/**
 * Recursively flatten `array` up to `depth` times.
 * @param array - The array to flatten
 * @param depth - The maximum recursion depth (defaults to 1)
 * @returns Returns the new flattened array
 */
function flattenDepth<T>(array: any[], depth?: number): T[];

/**
 * Returns an object composed from key-value `pairs`.
 * @param pairs - The key-value pairs
 * @returns Returns the new object
 */
function fromPairs<T>(pairs: Array<[PropertyKey, T]>): Record<string, T>;

/**
 * Gets the first element of `array`.
 * @param array - The array to query
 * @returns Returns the first element of `array`
 */
function head<T>(array: T[]): T | undefined;

/**
 * Gets the index at which the first occurrence of `value` is found in `array`
 * using SameValueZero for equality comparisons.
 * @param array - The array to inspect
 * @param value - The value to search for
 * @param fromIndex - The index to search from (defaults to 0)
 * @returns Returns the index of the matched value, else -1
 */
function indexOf<T>(array: T[], value: T, fromIndex?: number): number;

/**
 * Gets all but the last element of `array`.
 * @param array - The array to query
 * @returns Returns the slice of `array`
 */
function initial<T>(array: T[]): T[];

/**
 * Creates an array of unique values that are included in all given arrays
 * using SameValueZero for equality comparisons.
 * @param arrays - The arrays to inspect
 * @returns Returns the new array of intersecting values
 */
function intersection<T>(...arrays: T[][]): T[];

/**
 * 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 they're compared.
 * @param arrays - The arrays to inspect
 * @param iteratee - The iteratee invoked per element
 * @returns Returns the new array of intersecting values
 */
function intersectionBy<T>(
  array: T[],
  ...args: Array<T[] | string | ((value: T) => any)>
): T[];

/**
 * This method is like `intersection` except that it accepts `comparator`
 * which is invoked to compare elements of `arrays`.
 * @param arrays - The arrays to inspect
 * @param comparator - The comparator invoked per element
 * @returns Returns the new array of intersecting values
 */
function intersectionWith<T>(
  array: T[],
  ...args: Array<T[] | ((arrVal: T, othVal: T) => boolean)>
): T[];

/**
 * Converts all elements in `array` into a string separated by `separator`.
 * @param array - The array to convert
 * @param separator - The element separator (defaults to ',')
 * @returns Returns the joined string
 */
function join<T>(array: T[], separator?: string): string;

/**
 * Gets the last element of `array`.
 * @param array - The array to query
 * @returns Returns the last element of `array`
 */
function last<T>(array: T[]): T | undefined;

/**
 * This method is like `indexOf` except that it iterates over elements of
 * `array` from right to left.
 * @param array - The array to inspect
 * @param value - The value to search for
 * @param fromIndex - The index to search from (defaults to array.length - 1)
 * @returns Returns the index of the matched value, else -1
 */
function lastIndexOf<T>(array: T[], value: T, fromIndex?: number): number;

/**
 * Removes all given values from `array` using SameValueZero for equality comparisons.
 * @param array - The array to modify
 * @param values - The values to remove
 * @returns Returns `array`
 */
function pull<T>(array: T[], ...values: T[]): T[];

/**
 * This method is like `pull` except that it accepts an array of values to remove.
 * @param array - The array to modify
 * @param values - The values to remove
 * @returns Returns `array`
 */
function pullAll<T>(array: T[], values: T[]): T[];

/**
 * This method is like `pullAll` except that it accepts `iteratee` which is
 * invoked for each element of `array` and `values` to generate the criterion
 * by which they're compared.
 * @param array - The array to modify
 * @param values - The values to remove
 * @param iteratee - The iteratee invoked per element
 * @returns Returns `array`
 */
function pullAllBy<T>(
  array: T[],
  values: T[],
  iteratee?: string | ((value: T) => any)
): T[];

/**
 * This method is like `pullAll` except that it accepts `comparator` which
 * is invoked to compare elements of `array` to `values`.
 * @param array - The array to modify
 * @param values - The values to remove
 * @param comparator - The comparator invoked per element
 * @returns Returns `array`
 */
function pullAllWith<T>(
  array: T[],
  values: T[],
  comparator?: (arrVal: T, othVal: T) => boolean
): T[];

/**
 * Removes elements from `array` corresponding to `indexes` and returns an
 * array of removed elements.
 * @param array - The array to modify
 * @param indexes - The indexes of elements to remove
 * @returns Returns the new array of removed elements
 */
function pullAt<T>(array: T[], ...indexes: number[]): T[];

/**
 * Removes all elements from `array` that `predicate` returns truthy for
 * and returns an array of the removed elements.
 * @param array - The array to modify
 * @param predicate - The function invoked per iteration
 * @returns Returns the new array of removed elements
 */
function remove<T>(
  array: T[],
  predicate: string | object | ((value: T, index: number, array: T[]) => boolean)
): T[];

/**
 * Reverses `array` so that the first element becomes the last, the second
 * element becomes the second to last, and so on.
 * @param array - The array to modify
 * @returns Returns `array`
 */
function reverse<T>(array: T[]): T[];

/**
 * Creates a slice of `array` from `start` up to, but not including, `end`.
 * @param array - The array to slice
 * @param start - The start position (defaults to 0)
 * @param end - The end position (defaults to array.length)
 * @returns Returns the slice of `array`
 */
function slice<T>(array: T[], start?: number, end?: number): T[];

/**
 * Uses a binary search to determine the lowest index at which `value`
 * should be inserted into `array` in order to maintain its sort order.
 * @param array - The sorted array to inspect
 * @param value - The value to evaluate
 * @returns Returns the index at which `value` should be inserted
 */
function sortedIndex<T>(array: T[], value: T): number;

/**
 * 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.
 * @param array - The sorted array to inspect
 * @param value - The value to evaluate
 * @param iteratee - The iteratee invoked per element
 * @returns Returns the index at which `value` should be inserted
 */
function sortedIndexBy<T>(
  array: T[],
  value: T,
  iteratee?: string | ((value: T) => any)
): number;

/**
 * This method is like `indexOf` except that it performs a binary search
 * on a sorted `array`.
 * @param array - The array to inspect
 * @param value - The value to search for
 * @returns Returns the index of the matched value, else -1
 */
function sortedIndexOf<T>(array: T[], value: T): number;

/**
 * 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.
 * @param array - The sorted array to inspect
 * @param value - The value to evaluate
 * @returns Returns the index at which `value` should be inserted
 */
function sortedLastIndex<T>(array: T[], value: T): number;

/**
 * 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.
 * @param array - The sorted array to inspect
 * @param value - The value to evaluate
 * @param iteratee - The iteratee invoked per element
 * @returns Returns the index at which `value` should be inserted
 */
function sortedLastIndexBy<T>(
  array: T[],
  value: T,
  iteratee?: string | ((value: T) => any)
): number;

/**
 * This method is like `lastIndexOf` except that it performs a binary
 * search on a sorted `array`.
 * @param array - The array to inspect
 * @param value - The value to search for
 * @returns Returns the index of the matched value, else -1
 */
function sortedLastIndexOf<T>(array: T[], value: T): number;

/**
 * This method is like `uniq` except that it's designed and optimized
 * for sorted arrays.
 * @param array - The array to inspect
 * @returns Returns the new duplicate free array
 */
function sortedUniq<T>(array: T[]): T[];

/**
 * This method is like `uniqBy` except that it's designed and optimized
 * for sorted arrays.
 * @param array - The array to inspect
 * @param iteratee - The iteratee invoked per element
 * @returns Returns the new duplicate free array
 */
function sortedUniqBy<T>(
  array: T[],
  iteratee: string | ((value: T) => any)
): T[];

/**
 * Gets all but the first element of `array`.
 * @param array - The array to query
 * @returns Returns the slice of `array`
 */
function tail<T>(array: T[]): T[];

/**
 * Creates a slice of `array` with `n` elements taken from the beginning.
 * @param array - The array to query
 * @param n - The number of elements to take (defaults to 1)
 * @returns Returns the slice of `array`
 */
function take<T>(array: T[], n?: number): T[];

/**
 * Creates a slice of `array` with `n` elements taken from the end.
 * @param array - The array to query
 * @param n - The number of elements to take (defaults to 1)
 * @returns Returns the slice of `array`
 */
function takeRight<T>(array: T[], n?: number): T[];

/**
 * Creates a slice of `array` with elements taken from the end. Elements are
 * taken until `predicate` returns falsey.
 * @param array - The array to query
 * @param predicate - The function invoked per iteration
 * @returns Returns the slice of `array`
 */
function takeRightWhile<T>(
  array: T[],
  predicate?: string | object | ((value: T, index: number, array: T[]) => boolean)
): T[];

/**
 * Creates a slice of `array` with elements taken from the beginning. Elements
 * are taken until `predicate` returns falsey.
 * @param array - The array to query
 * @param predicate - The function invoked per iteration
 * @returns Returns the slice of `array`
 */
function takeWhile<T>(
  array: T[],
  predicate?: string | object | ((value: T, index: number, array: T[]) => boolean)
): T[];

/**
 * Creates an array of unique values, in order, from all given arrays using
 * SameValueZero for equality comparisons.
 * @param arrays - The arrays to inspect
 * @returns Returns the new array of combined values
 */
function union<T>(...arrays: T[][]): T[];

/**
 * 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.
 * @param arrays - The arrays to inspect
 * @param iteratee - The iteratee invoked per element
 * @returns Returns the new array of combined values
 */
function unionBy<T>(
  array: T[],
  ...args: Array<T[] | string | ((value: T) => any)>
): T[];

/**
 * This method is like `union` except that it accepts `comparator` which
 * is invoked to compare elements of `arrays`.
 * @param arrays - The arrays to inspect
 * @param comparator - The comparator invoked per element
 * @returns Returns the new array of combined values
 */
function unionWith<T>(
  array: T[],
  ...args: Array<T[] | ((arrVal: T, othVal: T) => boolean)>
): T[];

/**
 * Creates a duplicate-free version of an array, using SameValueZero for
 * equality comparisons, in which only the first occurrence of each element
 * is kept. The order of result values is determined by the order they occur
 * in the array.
 * @param array - The array to inspect
 * @returns Returns the new duplicate free array
 */
function uniq<T>(array: T[]): T[];

/**
 * 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.
 * @param array - The array to inspect
 * @param iteratee - The iteratee invoked per element
 * @returns Returns the new duplicate free array
 */
function uniqBy<T>(
  array: T[],
  iteratee: string | ((value: T) => any)
): T[];

/**
 * This method is like `uniq` except that it accepts `comparator` which
 * is invoked to compare elements of `array`.
 * @param array - The array to inspect
 * @param comparator - The comparator invoked per element
 * @returns Returns the new duplicate free array
 */
function uniqWith<T>(
  array: T[],
  comparator?: (arrVal: T, othVal: T) => boolean
): T[];

/**
 * 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.
 * @param array - The array of grouped elements to process
 * @returns Returns the new array of regrouped elements
 */
function unzip<T>(array: T[][]): T[][];

/**
 * This method is like `unzip` except that it accepts `iteratee` to specify
 * how regrouped values should be combined.
 * @param array - The array of grouped elements to process
 * @param iteratee - The function to combine regrouped values
 * @returns Returns the new array of regrouped elements
 */
function unzipWith<T, R>(
  array: T[][],
  iteratee?: (...values: T[]) => R
): R[];

/**
 * Creates an array excluding all given values using SameValueZero for
 * equality comparisons.
 * @param array - The array to inspect
 * @param values - The values to exclude
 * @returns Returns the new array of filtered values
 */
function without<T>(array: T[], ...values: T[]): T[];

/**
 * Creates an array of unique values that is the symmetric difference of
 * the given arrays. The order of result values is determined by the order
 * they occur in the arrays.
 * @param arrays - The arrays to inspect
 * @returns Returns the new array of filtered values
 */
function xor<T>(...arrays: T[][]): T[];

/**
 * 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 by which they're compared.
 * @param arrays - The arrays to inspect
 * @param iteratee - The iteratee invoked per element
 * @returns Returns the new array of filtered values
 */
function xorBy<T>(
  array: T[],
  ...args: Array<T[] | string | ((value: T) => any)>
): T[];

/**
 * This method is like `xor` except that it accepts `comparator` which is
 * invoked to compare elements of `arrays`.
 * @param arrays - The arrays to inspect
 * @param comparator - The comparator invoked per element
 * @returns Returns the new array of filtered values
 */
function xorWith<T>(
  array: T[],
  ...args: Array<T[] | ((arrVal: T, othVal: T) => boolean)>
): T[];

/**
 * 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.
 * @param arrays - The arrays to process
 * @returns Returns the new array of grouped elements
 */
function zip<T>(...arrays: T[][]): T[][];

/**
 * This method is like `fromPairs` except that it accepts two arrays,
 * one of property identifiers and one of corresponding values.
 * @param keys - The property identifiers
 * @param values - The property values
 * @returns Returns the new object
 */
function zipObject<K extends PropertyKey, V>(keys: K[], values: V[]): Record<K, V>;

/**
 * This method is like `zipObject` except that it supports property paths.
 * @param paths - The property identifiers
 * @param values - The property values
 * @returns Returns the new object
 */
function zipObjectDeep(paths: string[], values: any[]): any;

/**
 * This method is like `zip` except that it accepts `iteratee` to specify
 * how grouped values should be combined.
 * @param arrays - The arrays to process
 * @param iteratee - The function to combine grouped values
 * @returns Returns the new array of grouped elements
 */
function zipWith<T, R>(
  array: T[],
  ...args: Array<T[] | ((...values: T[]) => R)>
): R[];

type PropertyKey = string | number | symbol;