arrays

Variables

at

const at: typeof esToolkit_at = esToolkit_at;

Retrieves elements from an array at the specified indices.

This function supports negative indices, which count from the end of the array.

Template

Param

The array to retrieve elements from.

Param

An array of indices specifying the positions of elements to retrieve.

Returns

A new array containing the elements at the specified indices.

Example

const numbers = [10, 20, 30, 40, 50];
const result = at(numbers, [1, 3, 4]);
console.log(result); // [20, 40, 50]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

chunk

const chunk: typeof esToolkit_chunk = esToolkit_chunk;

Splits an array into smaller arrays of a specified length.

This function takes an input array and divides it into multiple smaller arrays, each of a specified length. If the input array cannot be evenly divided, the final sub-array will contain the remaining elements.

Template

The type of elements in the array.

Param

The array to be chunked into smaller arrays.

Param

The size of each smaller array. Must be a positive integer.

Returns

A two-dimensional array where each sub-array has a maximum length of size.

Throws

Throws an error if size is not a positive integer.

Examples

// Splits an array of numbers into sub-arrays of length 2
chunk([1, 2, 3, 4, 5], 2);
// Returns: [[1, 2], [3, 4], [5]]

// Splits an array of strings into sub-arrays of length 3
chunk(['a', 'b', 'c', 'd', 'e', 'f', 'g'], 3);
// Returns: [['a', 'b', 'c'], ['d', 'e', 'f'], ['g']]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

compact

const compact: typeof esToolkit_compact = esToolkit_compact;

Removes falsey values (false, null, 0, -0, 0n, '', undefined, NaN) from an array.

Template

The type of elements in the array.

Param

The input array to remove falsey values.

Returns

A new array with all falsey values removed.

Example

compact([0, -0, 0n, 1, false, 2, '', 3, null, undefined, 4, NaN, 5]);
Returns: [1, 2, 3, 4, 5]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

countBy

const countBy: typeof esToolkit_countBy = esToolkit_countBy;

Count the occurrences of each item in an array based on a transformation function.

This function takes an array and a transformation function that converts each item in the array to a key. It then counts the occurrences of each transformed item and returns an object with the transformed items as keys and the counts as values.

Template

The type of the items in the input array.

Template

The type of keys.

Param

The input array to count occurrences.

Param

The transformation function that maps each item, its index, and the array to a key.

Returns

An object containing the transformed items as keys and the counts as values.

Examples

const array = ['a', 'b', 'c', 'a', 'b', 'a'];
const result = countBy(array, x => x);
// result will be { a: 3, b: 2, c: 1 }

const array = [1, 2, 3, 4, 5];
const result = countBy(array, item => item % 2 === 0 ? 'even' : 'odd');
// result will be { odd: 3, even: 2 }

// Using index parameter
const array = ['a', 'b', 'c', 'd'];
const result = countBy(array, (item, index) => index < 2 ? 'first' : 'rest');
// result will be { first: 2, rest: 2 }

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

difference

const difference: typeof esToolkit_difference = esToolkit_difference;

Computes the difference between two arrays.

This function takes two arrays and returns a new array containing the elements that are present in the first array but not in the second array. It effectively filters out any elements from the first array that also appear in the second array.

Template

Param

The array from which to derive the difference. This is the primary array from which elements will be compared and filtered.

Param

The array containing elements to be excluded from the first array. Each element in this array will be checked against the first array, and if a match is found, that element will be excluded from the result.

Returns

A new array containing the elements that are present in the first array but not in the second array.

Example

const array1 = [1, 2, 3, 4, 5];
const array2 = [2, 4];
const result = difference(array1, array2);
// result will be [1, 3, 5] since 2 and 4 are in both arrays and are excluded from the result.

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

differenceBy

const differenceBy: typeof esToolkit_differenceBy = esToolkit_differenceBy;

Computes the difference between two arrays after mapping their elements through a provided function.

This function takes two arrays and a mapper function. It returns a new array containing the elements that are present in the first array but not in the second array, based on the identity calculated by the mapper function.

Essentially, it filters out any elements from the first array that, when mapped, match an element in the mapped version of the second array.

Template

U

Param

The primary array from which to derive the difference.

Param

The array containing elements to be excluded from the first array.

Param

The function to map the elements of both arrays. This function is applied to each element in both arrays, and the comparison is made based on the mapped values.

Returns

A new array containing the elements from the first array that do not have a corresponding mapped identity in the second array.

Examples

const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }];
const array2 = [{ id: 2 }, { id: 4 }];
const mapper = item => item.id;
const result = differenceBy(array1, array2, mapper);
// result will be [{ id: 1 }, { id: 3 }] since the elements with id 2 are in both arrays and are excluded from the result.

const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }];
const array2 = [2, 4];
const mapper = item => (typeof item === 'object' ? item.id : item);
const result = differenceBy(array1, array2, mapper);
// result will be [{ id: 1 }, { id: 3 }] since 2 is present in both arrays after mapping, and is excluded from the result.

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

differenceWith

const differenceWith: typeof esToolkit_differenceWith = esToolkit_differenceWith;

Computes the difference between two arrays based on a custom equality function.

This function takes two arrays and a custom comparison function. It returns a new array containing the elements that are present in the first array but not in the second array. The comparison to determine if elements are equal is made using the provided custom function.

Template

U

Param

The array from which to get the difference.

Param

The array containing elements to exclude from the first array.

Param

A function to determine if two items are equal.

Returns

A new array containing the elements from the first array that do not match any elements in the second array according to the custom equality function.

Examples

const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }];
const array2 = [{ id: 2 }, { id: 4 }];
const areItemsEqual = (a, b) => a.id === b.id;
const result = differenceWith(array1, array2, areItemsEqual);
// result will be [{ id: 1 }, { id: 3 }] since the elements with id 2 are considered equal and are excluded from the result.

const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }];
const array2 = [2, 4];
const areItemsEqual = (a, b) => a.id === b;
const result = differenceWith(array1, array2, areItemsEqual);
// result will be [{ id: 1 }, { id: 3 }] since the element with id 2 is considered equal to the second array's element and is excluded from the result.

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

drop

const drop: typeof esToolkit_drop = esToolkit_drop;

Removes a specified number of elements from the beginning of an array and returns the rest.

This function takes an array and a number, and returns a new array with the specified number of elements removed from the start.

Template

The type of elements in the array.

Param

The array from which to drop elements.

Param

The number of elements to drop from the beginning of the array.

Returns

A new array with the specified number of elements removed from the start.

Example

const array = [1, 2, 3, 4, 5];
const result = drop(array, 2);
// result will be [3, 4, 5] since the first two elements are dropped.

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

dropRight

const dropRight: typeof esToolkit_dropRight = esToolkit_dropRight;

Removes a specified number of elements from the end of an array and returns the rest.

This function takes an array and a number, and returns a new array with the specified number of elements removed from the end.

Template

The type of elements in the array.

Param

The array from which to drop elements.

Param

The number of elements to drop from the end of the array.

Returns

A new array with the specified number of elements removed from the end.

Example

const array = [1, 2, 3, 4, 5];
const result = dropRight(array, 2);
// result will be [1, 2, 3] since the last two elements are dropped.

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

dropRightWhile

const dropRightWhile: typeof esToolkit_dropRightWhile = esToolkit_dropRightWhile;

Removes elements from the end of an array until the predicate returns false.

This function iterates over an array from the end and drops elements until the provided predicate function returns false. It then returns a new array with the remaining elements.

Template

The type of elements in the array.

Param

The array from which to drop elements.

Param

A predicate function that determines whether to continue dropping elements. The function is called with each element from the end, and dropping continues as long as it returns true.

Returns

A new array with the elements remaining after the predicate returns false.

Example

const array = [1, 2, 3, 4, 5];
const result = dropRightWhile(array, x => x > 3);
// result will be [1, 2, 3] since elements greater than 3 are dropped from the end.

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

dropWhile

const dropWhile: typeof esToolkit_dropWhile = esToolkit_dropWhile;

Removes elements from the beginning of an array until the predicate returns false.

This function iterates over an array and drops elements from the start until the provided predicate function returns false. It then returns a new array with the remaining elements.

Template

The type of elements in the array.

Param

The array from which to drop elements.

Param

A predicate function that determines whether to continue dropping elements. The function is called with each element, and dropping continues as long as it returns true.

Returns

A new array with the elements remaining after the predicate returns false.

Example

const array = [1, 2, 3, 4, 5];
const result = dropWhile(array, x => x < 3);
// result will be [3, 4, 5] since elements less than 3 are dropped.

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

flatMap

const flatMap: typeof esToolkit_flatMap = esToolkit_flatMap;

Maps each element in the array using the iteratee function and flattens the result up to the specified depth.

Template

The type of elements within the array.

Template

The type of elements within the returned array from the iteratee function.

Template

The depth to which the array should be flattened.

Param

The array to flatten.

Param

The function that produces the new array elements. It receives the element, its index, and the array.

Param

The depth level specifying how deep a nested array structure should be flattened. Defaults to 1.

Returns

The new array with the mapped and flattened elements.

Example

const arr = [1, 2, 3];

flatMap(arr, (item: number) => [item, item]);
// [1, 1, 2, 2, 3, 3]

flatMap(arr, (item: number) => [[item, item]], 2);
// [1, 1, 2, 2, 3, 3]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

flatMapDeep

const flatMapDeep: typeof esToolkit_flatMapDeep = esToolkit_flatMapDeep;

Recursively maps each element in an array using a provided iteratee function and then deeply flattens the resulting array.

Template

The type of elements within the array.

Template

The type of elements within the returned array from the iteratee function.

Param

The array to flatten.

Param

The function that produces the new array elements. It receives the element, its index, and the array.

Returns

A new array that has been flattened.

Example

const result = flatMapDeep([1, 2, 3], n => [[n, n]]);
// [1, 1, 2, 2, 3, 3]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

flatten

const flatten: typeof esToolkit_flatten = esToolkit_flatten;

Flattens an array up to the specified depth.

Template

The type of elements within the array.

Template

The depth to which the array should be flattened.

Param

The array to flatten.

Param

The depth level specifying how deep a nested array structure should be flattened. Defaults to 1.

Returns

A new array that has been flattened.

Example

const arr = flatten([1, [2, 3], [4, [5, 6]]], 1);
// Returns: [1, 2, 3, 4, [5, 6]]

const arr = flatten([1, [2, 3], [4, [5, 6]]], 2);
// Returns: [1, 2, 3, 4, 5, 6]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

flattenDeep

const flattenDeep: typeof esToolkit_flattenDeep = esToolkit_flattenDeep;

Utility type for recursively unpacking nested array types to extract the type of the innermost element

Example

ExtractNestedArrayType<(number | (number | number[])[])[]>
// number

ExtractNestedArrayType<(boolean | (string | number[])[])[]>
// string | number | boolean

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

groupBy

const groupBy: typeof esToolkit_groupBy = esToolkit_groupBy;

Groups the elements of an array based on a provided key-generating function.

This function takes an array and a function that generates a key from each element. It returns an object where the keys are the generated keys and the values are arrays of elements that share the same key.

Template

The type of elements in the array.

Template

The type of keys.

Param

The array to group.

Param

A function that generates a key from an element, its index, and the array.

Returns

An object where each key is associated with an array of elements that share that key.

Examples

const array = [
  { category: 'fruit', name: 'apple' },
  { category: 'fruit', name: 'banana' },
  { category: 'vegetable', name: 'carrot' }
];
const result = groupBy(array, item => item.category);
// result will be:
// {
//   fruit: [
//     { category: 'fruit', name: 'apple' },
//     { category: 'fruit', name: 'banana' }
//   ],
//   vegetable: [
//     { category: 'vegetable', name: 'carrot' }
//   ]
// }

// Using index parameter
const items = ['a', 'b', 'c', 'd'];
const result = groupBy(items, (item, index) => index % 2 === 0 ? 'even' : 'odd');
// result will be: { even: ['a', 'c'], odd: ['b', 'd'] }

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

head

const head: typeof esToolkit_head = esToolkit_head;

Returns the first element of an array.

This function takes an array and returns the first element of the array. If the array is empty, the function returns undefined.

Template

The type of elements in the array.

Param

A non-empty array from which to get the first element.

Returns

The first element of the array.

Example

const arr = [1, 2, 3];
const firstElement = head(arr);
// firstElement will be 1

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

initial

const initial: typeof esToolkit_initial = esToolkit_initial;

Returns an empty array when the input is a tuple containing exactly one element.

Template

The type of the single element.

Param

A tuple containing exactly one element.

Returns

An empty array since there is only one element.

Example

const array = [100] as const;
const result = initial(array);
// result will be []

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

intersection

const intersection: typeof esToolkit_intersection = esToolkit_intersection;

Returns the intersection of two arrays.

This function takes two arrays and returns a new array containing the elements that are present in both arrays. It effectively filters out any elements from the first array that are not found in the second array.

Template

The type of elements in the array.

Param

The first array to compare.

Param

The second array to compare.

Returns

A new array containing the elements that are present in both arrays.

Example

const array1 = [1, 2, 3, 4, 5];
const array2 = [3, 4, 5, 6, 7];
const result = intersection(array1, array2);
// result will be [3, 4, 5] since these elements are in both arrays.

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

intersectionBy

const intersectionBy: typeof esToolkit_intersectionBy = esToolkit_intersectionBy;

Returns the intersection of two arrays based on a mapping function.

This function takes two arrays and a mapping function. It returns a new array containing the elements from the first array that, when mapped using the provided function, have matching mapped elements in the second array. It effectively filters out any elements from the first array that do not have corresponding mapped values in the second array.

Template

The type of elements in the first array.

Template

The type of elements in the second array.

Param

The first array to compare.

Param

The second array to compare.

Param

A function to map the elements of both arrays for comparison.

Returns

A new array containing the elements from the first array that have corresponding mapped values in the second array.

Examples

const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }];
const array2 = [{ id: 2 }, { id: 4 }];
const mapper = item => item.id;
const result = intersectionBy(array1, array2, mapper);
// result will be [{ id: 2 }] since only this element has a matching id in both arrays.

const array1 = [
  { id: 1, name: 'jane' },
  { id: 2, name: 'amy' },
  { id: 3, name: 'michael' },
];
const array2 = [2, 4];
const mapper = item => (typeof item === 'object' ? item.id : item);
const result = intersectionBy(array1, array2, mapper);
// result will be [{ id: 2, name: 'amy' }] since only this element has a matching id that is equal to seconds array's element.

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

intersectionWith

const intersectionWith: typeof esToolkit_intersectionWith = esToolkit_intersectionWith;

Returns the intersection of two arrays based on a custom equality function.

This function takes two arrays and a custom equality function. It returns a new array containing the elements from the first array that have matching elements in the second array, as determined by the custom equality function. It effectively filters out any elements from the first array that do not have corresponding matches in the second array according to the equality function.

Template

The type of elements in the first array.

Template

The type of elements in the second array.

Param

The first array to compare.

Param

The second array to compare.

Param

A custom function to determine if two elements are equal. This function takes two arguments, one from each array, and returns true if the elements are considered equal, and false otherwise.

Returns

A new array containing the elements from the first array that have corresponding matches in the second array according to the custom equality function.

Examples

const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }];
const array2 = [{ id: 2 }, { id: 4 }];
const areItemsEqual = (a, b) => a.id === b.id;
const result = intersectionWith(array1, array2, areItemsEqual);
// result will be [{ id: 2 }] since this element has a matching id in both arrays.

const array1 = [
  { id: 1, name: 'jane' },
  { id: 2, name: 'amy' },
  { id: 3, name: 'michael' },
];
const array2 = [2, 4];
const areItemsEqual = (a, b) => a.id === b;
const result = intersectionWith(array1, array2, areItemsEqual);
// result will be [{ id: 2, name: 'amy' }] since this element has a matching id that is equal to seconds array's element.

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

isSubset

const isSubset: typeof esToolkit_isSubset = esToolkit_isSubset;

Checks if the subset array is entirely contained within the superset array.

Template

The type of elements contained in the arrays.

Param

The array that may contain all elements of the subset.

Param

The array to check against the superset.

Returns

Returns true if all elements of the subset are present in the superset, otherwise returns false.

Examples

const superset = [1, 2, 3, 4, 5];
const subset = [2, 3, 4];
isSubset(superset, subset); // true

const superset = ['a', 'b', 'c'];
const subset = ['a', 'd'];
isSubset(superset, subset); // false

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

isSubsetWith

const isSubsetWith: typeof esToolkit_isSubsetWith = esToolkit_isSubsetWith;

Checks if the subset array is entirely contained within the superset array based on a custom equality function.

This function takes two arrays and a custom comparison function. It returns a boolean indicating whether all elements in the subset array are present in the superset array, as determined by the provided custom equality function.

Template

The type of elements contained in the arrays.

Param

The array that may contain all elements of the subset.

Param

The array to check against the superset.

Param

A function to determine if two items are equal.

Returns

Returns true if all elements of the subset are present in the superset according to the custom equality function, otherwise returns false.

Examples

const superset = [{ id: 1 }, { id: 2 }, { id: 3 }];
const subset = [{ id: 2 }, { id: 1 }];
const areItemsEqual = (a, b) => a.id === b.id;
isSubsetWith(superset, subset, areItemsEqual); // true

const superset = [{ id: 1 }, { id: 2 }, { id: 3 }];
const subset = [{ id: 4 }];
const areItemsEqual = (a, b) => a.id === b.id;
isSubsetWith(superset, subset, areItemsEqual); // false

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

keyBy

const keyBy: typeof esToolkit_keyBy = esToolkit_keyBy;

Maps each element of an array based on a provided key-generating function.

This function takes an array and a function that generates a key from each element. It returns an object where the keys are the generated keys and the values are the corresponding elements. If there are multiple elements generating the same key, the last element among them is used as the value.

Template

The type of elements in the array.

Template

The type of keys.

Param

The array of elements to be mapped.

Param

A function that generates a key from an element, its index, and the array.

Returns

An object where keys are mapped to each element of an array.

Examples

const array = [
  { category: 'fruit', name: 'apple' },
  { category: 'fruit', name: 'banana' },
  { category: 'vegetable', name: 'carrot' }
];
const result = keyBy(array, item => item.category);
// result will be:
// {
//   fruit: { category: 'fruit', name: 'banana' },
//   vegetable: { category: 'vegetable', name: 'carrot' }
// }

// Using index parameter
const items = ['a', 'b', 'c'];
const result = keyBy(items, (item, index) => index);
// result will be: { 0: 'a', 1: 'b', 2: 'c' }

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

last

const last: typeof esToolkit_last = esToolkit_last;

Returns the last element of an array.

This function takes an array and returns the last element of the array. If the array is empty, the function returns undefined.

Unlike some implementations, this function is optimized for performance by directly accessing the last index of the array.

Template

The type of elements in the array.

Param

The array from which to get the last element.

Returns

The last element of the array, or undefined if the array is empty.

Example

const arr = [1, 2, 3];
const lastElement = last(arr);
// lastElement will be 3

const emptyArr: number[] = [];
const noElement = last(emptyArr);
// noElement will be undefined

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

maxBy

const maxBy: typeof esToolkit_maxBy = esToolkit_maxBy;

Finds the element in an array that has the maximum value when applying the getValue function to each element.

Template

The type of elements in the array.

Param

The nonempty array of elements to search.

Param

A function that selects a numeric value from each element.

Returns

The element with the maximum value as determined by the getValue function.

Example

maxBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: { a: 3 }
maxBy([], x => x.a); // Returns: undefined
maxBy(
  [
    { name: 'john', age: 30 },
    { name: 'jane', age: 28 },
    { name: 'joe', age: 26 },
  ],
  x => x.age
); // Returns: { name: 'john', age: 30 }

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

minBy

const minBy: typeof esToolkit_minBy = esToolkit_minBy;

Finds the element in an array that has the minimum value when applying the getValue function to each element.

Template

The type of elements in the array.

Param

The nonempty array of elements to search.

Param

A function that selects a numeric value from each element.

Returns

The element with the minimum value as determined by the getValue function.

Example

minBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: { a: 1 }
minBy([], x => x.a); // Returns: undefined
minBy(
  [
    { name: 'john', age: 30 },
    { name: 'jane', age: 28 },
    { name: 'joe', age: 26 },
  ],
  x => x.age
); // Returns: { name: 'joe', age: 26 }

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

orderBy

const orderBy: typeof esToolkit_orderBy = esToolkit_orderBy;

Sorts an array of objects based on the given criteria and their corresponding order directions.

If you provide keys, it sorts the objects by the values of those keys.
If you provide functions, it sorts based on the values returned by those functions.

The function returns the array of objects sorted in corresponding order directions. If two objects have the same value for the current criterion, it uses the next criterion to determine their order. If the number of orders is less than the number of criteria, it uses the last order for the rest of the criteria.

Template

The type of elements in the array.

Param

The array of objects to be sorted.

Param

The criteria for sorting. This can be an array of object keys or functions that return values used for sorting.

Param

An array of order directions ('asc' for ascending or 'desc' for descending).

Returns

The sorted array.

Example

// Sort an array of objects by 'user' in ascending order and 'age' in descending order.
const users = [
  { user: 'fred', age: 48 },
  { user: 'barney', age: 34 },
  { user: 'fred', age: 40 },
  { user: 'barney', age: 36 },
];

const result = orderBy(users, [obj => obj.user, 'age'], ['asc', 'desc']);
// result will be:
// [
//   { user: 'barney', age: 36 },
//   { user: 'barney', age: 34 },
//   { user: 'fred', age: 48 },
//   { user: 'fred', age: 40 },
// ]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

partition

const partition: typeof esToolkit_partition = esToolkit_partition;

Splits an array into two groups based on a predicate function.

This function takes an array and a predicate function. It returns a tuple of two arrays: the first array contains elements for which the predicate function returns true, and the second array contains elements for which the predicate function returns false.

Template

The type of elements in the array.

Template

The type being filtered for.

Param

The array to partition.

Param

A type guard that determines whether an element should be placed in the truthy array. The function is called with each element of the array and its index.

Returns

A tuple containing two arrays: the first array contains elements for which the predicate returned true, and the second array contains elements for which the predicate returned false.

Example

const array = [1, 2, 3, 4] as const;
const isEven = (x: number): x is 2 | 4 => x % 2 === 0;
const [even, odd]: [(2 | 4)[], (2 | 4)[]] = partition(array, isEven);
// even will be [2, 4], and odd will be [1, 3]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

sortBy

const sortBy: typeof esToolkit_sortBy = esToolkit_sortBy;

Sorts an array of objects based on the given criteria.

If you provide keys, it sorts the objects by the values of those keys.
If you provide functions, it sorts based on the values returned by those functions.

The function returns the array of objects sorted in ascending order. If two objects have the same value for the current criterion, it uses the next criterion to determine their order.

Template

The type of the objects in the array.

Param

The array of objects to be sorted.

Param

The criteria for sorting. This can be an array of object keys or functions that return values used for sorting.

Returns

The sorted array.

Example

const users = [
 { user: 'foo', age: 24 },
 { user: 'bar', age: 7 },
 { user: 'foo', age: 8 },
 { user: 'bar', age: 29 },
];

sortBy(users, ['user', 'age']);
sortBy(users, [obj => obj.user, 'age']);
// results will be:
// [
//   { user : 'bar', age: 7 },
//   { user : 'bar', age: 29 },
//   { user : 'foo', age: 8 },
//   { user : 'foo', age: 24 },
// ]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

tail

const tail: typeof esToolkit_tail = esToolkit_tail;

Returns an empty array when the input is a single-element array.

Template

The type of the single element in the array.

Param

The single-element array to process.

Returns

An empty array.

Example

const arr = [1];
const result = tail(arr);
// result will be []

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

take

const take: typeof esToolkit_take = esToolkit_take;

Returns a new array containing the first count elements from the input array arr. If count is greater than the length of arr, the entire array is returned.

Template

Type of elements in the input array.

Param

The array to take elements from.

Param

The number of elements to take.

Param

If truthy, ignores count and defaults to 1.

Returns

A new array containing the first count elements from arr.

Examples

// Returns [1, 2, 3]
take([1, 2, 3, 4, 5], 3);

// Returns ['a', 'b']
take(['a', 'b', 'c'], 2);

// Returns [1, 2, 3]
take([1, 2, 3], 5);

// Returns [[1], [1], [1]]
const arr = [1, 2, 3];
const result = arr.map((v, i, array) => take(array, i, true));

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

takeRight

const takeRight: typeof esToolkit_takeRight = esToolkit_takeRight;

Returns a new array containing the last count elements from the input array arr. If count is greater than the length of arr, the entire array is returned.

Template

The type of elements in the array.

Param

The array to take elements from.

Param

The number of elements to take.

Returns

A new array containing the last count elements from arr.

Examples

// Returns [4, 5]
takeRight([1, 2, 3, 4, 5], 2);

// Returns ['b', 'c']
takeRight(['a', 'b', 'c'], 2);

// Returns [1, 2, 3]
takeRight([1, 2, 3], 5);

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

takeRightWhile

const takeRightWhile: typeof esToolkit_takeRightWhile = esToolkit_takeRightWhile;

Takes elements from the end of the array while the predicate function returns true.

Template

Type of elements in the input array.

Param

The array to take elements from.

Param

The function invoked per element with the item, its index, and the array.

Returns

A new array containing the elements taken from the end while the predicate returns true.

Examples

// Returns [3, 2, 1]
takeRightWhile([5, 4, 3, 2, 1], n => n < 4);

// Returns []
takeRightWhile([1, 2, 3], n => n > 3);

// Using index parameter
takeRightWhile([10, 20, 30, 40], (x, index) => index > 1);
// Returns: [30, 40]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

takeWhile

const takeWhile: typeof esToolkit_takeWhile = esToolkit_takeWhile;

Returns a new array containing the leading elements of the provided array that satisfy the provided predicate function. It stops taking elements as soon as an element does not satisfy the predicate.

Template

The type of elements in the array.

Param

The array to process.

Param

The predicate function that is called with each element, its index, and the array. Elements are included in the result as long as this function returns true.

Returns

A new array containing the leading elements that satisfy the predicate.

Examples

// Returns [1, 2]
takeWhile([1, 2, 3, 4], x => x < 3);

// Returns []
takeWhile([1, 2, 3, 4], x => x > 3);

// Using index parameter
takeWhile([10, 20, 30, 40], (x, index) => index < 2);
// Returns: [10, 20]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

toFilled

const toFilled: typeof esToolkit_toFilled = esToolkit_toFilled;

Creates a new array filled with the specified value from the start position up to, but not including, the end position. This function does not mutate the original array.

Template

The type of elements in the original array.

Template

The type of the value to fill the new array with.

Param

The array to base the new array on.

Param

The value to fill the new array with.

Returns

The new array with the filled values.

Example

const array = [1, 2, 3, 4, 5];
let result = toFilled(array, '*', 2);
console.log(result); // [1, 2, '*', '*', '*']
console.log(array); // [1, 2, 3, 4, 5]

result = toFilled(array, '*', 1, 4);
console.log(result); // [1, '*', '*', '*', 5]
console.log(array); // [1, 2, 3, 4, 5]

result = toFilled(array, '*');
console.log(result); // ['*', '*', '*', '*', '*']
console.log(array); // [1, 2, 3, 4, 5]

result = toFilled(array, '*', -4, -1);
console.log(result); // [1, '*', '*', '*', 5]
console.log(array); // [1, 2, 3, 4, 5]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

union

const union: typeof esToolkit_union = esToolkit_union;

Creates an array of unique values from all given arrays.

This function takes two arrays, merges them into a single array, and returns a new array containing only the unique values from the merged array.

Template

The type of elements in the array.

Param

The first array to merge and filter for unique values.

Param

The second array to merge and filter for unique values.

Returns

A new array of unique values.

Example

const array1 = [1, 2, 3];
const array2 = [3, 4, 5];
const result = union(array1, array2);
// result will be [1, 2, 3, 4, 5]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

unionBy

const unionBy: typeof esToolkit_unionBy = esToolkit_unionBy;

Creates an array of unique values, in order, from all given arrays using a provided mapping function to determine equality.

Template

The type of elements in the array.

Template

The type of mapped elements.

Param

The first array.

Param

The second array.

Param

The function to map array elements to comparison values.

Returns

A new array containing the union of unique elements from arr1 and arr2, based on the values returned by the mapping function.

Examples

// Custom mapping function for numbers (modulo comparison)
const moduloMapper = (x) => x % 3;
unionBy([1, 2, 3], [4, 5, 6], moduloMapper);
// Returns [1, 2, 3]

// Custom mapping function for objects with an 'id' property
const idMapper = (obj) => obj.id;
unionBy([{ id: 1 }, { id: 2 }], [{ id: 2 }, { id: 3 }], idMapper);
// Returns [{ id: 1 }, { id: 2 }, { id: 3 }]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

unionWith

const unionWith: typeof esToolkit_unionWith = esToolkit_unionWith;

Creates an array of unique values from two given arrays based on a custom equality function.

This function takes two arrays and a custom equality function, merges the arrays, and returns a new array containing only the unique values as determined by the custom equality function.

Template

The type of elements in the array.

Param

The first array to merge and filter for unique values.

Param

The second array to merge and filter for unique values.

Param

A custom function to determine if two elements are equal. It takes two arguments and returns true if the elements are considered equal, and false otherwise.

Returns

A new array of unique values based on the custom equality function.

Example

const array1 = [{ id: 1 }, { id: 2 }];
const array2 = [{ id: 2 }, { id: 3 }];
const areItemsEqual = (a, b) => a.id === b.id;
const result = unionWith(array1, array2, areItemsEqual);
// result will be [{ id: 1 }, { id: 2 }, { id: 3 }] since { id: 2 } is considered equal in both arrays

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

uniq

const uniq: typeof esToolkit_uniq = esToolkit_uniq;

Creates a duplicate-free version of an array.

This function takes an array and returns a new array containing only the unique values from the original array, preserving the order of first occurrence.

Template

The type of elements in the array.

Param

The array to process.

Returns

A new array with only unique values from the original array.

Example

const array = [1, 2, 2, 3, 4, 4, 5];
const result = uniq(array);
// result will be [1, 2, 3, 4, 5]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

uniqBy

const uniqBy: typeof esToolkit_uniqBy = esToolkit_uniqBy;

Returns a new array containing only the unique elements from the original array, based on the values returned by the mapper function.

When duplicates are found, the first occurrence is kept and the rest are discarded.

Template

The type of elements in the array.

Template

The type of mapped elements.

Param

The array to process.

Param

The function used to convert the array elements.

Returns

A new array containing only the unique elements from the original array, based on the values returned by the mapper function.

Examples

uniqBy([1.2, 1.5, 2.1, 3.2, 5.7, 5.3, 7.19], Math.floor);
// [1.2, 2.1, 3.2, 5.7, 7.19]

const array = [ { category: 'fruit', name: 'apple' }, { category: 'fruit', name: 'banana' }, { category: 'vegetable', name: 'carrot' }, ]; uniqBy(array, item => item.category).length // 2

@see Powered by `es-toolkit` (MIT License): [https://github.com/toss/es-toolkit](https://github.com/toss/es-toolkit)

***

### uniqWith

```ts
const uniqWith: typeof esToolkit_uniqWith = esToolkit_uniqWith;

Returns a new array containing only the unique elements from the original array, based on the values returned by the comparator function.

Template

The type of elements in the array.

Param

The array to process.

Param

The function used to compare the array elements.

Returns

A new array containing only the unique elements from the original array, based on the values returned by the comparator function.

Example

uniqWith([1.2, 1.5, 2.1, 3.2, 5.7, 5.3, 7.19], (a, b) => Math.abs(a - b) < 1);
// [1.2, 3.2, 5.7, 7.19]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

unzip

const unzip: typeof esToolkit_unzip = esToolkit_unzip;

Gathers elements in the same position in an internal array from a grouped array of elements and returns them as a new array.

Template

The type of elements in the nested array.

Param

The nested array to unzip.

Returns

A new array of unzipped elements.

Example

const zipped = [['a', true, 1],['b', false, 2]];
const result = unzip(zipped);
// result will be [['a', 'b'], [true, false], [1, 2]]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

unzipWith

const unzipWith: typeof esToolkit_unzipWith = esToolkit_unzipWith;

Unzips an array of arrays, applying an iteratee function to regrouped elements.

Template

R

Param

The nested array to unzip. This is an array of arrays, where each inner array contains elements to be unzipped.

Param

A function to transform the unzipped elements.

Returns

A new array of unzipped and transformed elements.

Example

const nestedArray = [[1, 2], [3, 4], [5, 6]];
const result = unzipWith(nestedArray, (item, item2, item3) => item + item2 + item3);
// result will be [9, 12]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

windowed

const windowed: typeof esToolkit_windowed = esToolkit_windowed;

Interface

Options for the windowed function.

WindowedOptions

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

without

const without: typeof esToolkit_without = esToolkit_without;

Creates an array that excludes all specified values.

It correctly excludes NaN, as it compares values using SameValueZero.

Template

The type of elements in the array.

Param

The array to filter.

Param

The values to exclude.

Returns

A new array without the specified values.

Examples

// Removes the specified values from the array
without([1, 2, 3, 4, 5], 2, 4);
// Returns: [1, 3, 5]

// Removes specified string values from the array
without(['a', 'b', 'c', 'a'], 'a');
// Returns: ['b', 'c']

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

xor

const xor: typeof esToolkit_xor = esToolkit_xor;

Computes the symmetric difference between two arrays. The symmetric difference is the set of elements which are in either of the arrays, but not in their intersection.

Template

The type of elements in the array.

Param

The first array.

Param

The second array.

Returns

An array containing the elements that are present in either arr1 or arr2 but not in both.

Examples

// Returns [1, 2, 5, 6]
xor([1, 2, 3, 4], [3, 4, 5, 6]);

// Returns ['a', 'c']
xor(['a', 'b'], ['b', 'c']);

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

xorBy

const xorBy: typeof esToolkit_xorBy = esToolkit_xorBy;

Computes the symmetric difference between two arrays using a custom mapping function. The symmetric difference is the set of elements which are in either of the arrays, but not in their intersection, determined by the result of the mapping function.

Template

Type of elements in the input arrays.

Template

Type of the values returned by the mapping function.

Param

The first array.

Param

The second array.

Param

The function to map array elements to comparison values.

Returns

An array containing the elements that are present in either arr1 or arr2 but not in both, based on the values returned by the mapping function.

Example

// Custom mapping function for objects with an 'id' property
const idMapper = obj => obj.id;
xorBy([{ id: 1 }, { id: 2 }], [{ id: 2 }, { id: 3 }], idMapper);
// Returns [{ id: 1 }, { id: 3 }]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

xorWith

const xorWith: typeof esToolkit_xorWith = esToolkit_xorWith;

Computes the symmetric difference between two arrays using a custom equality function. The symmetric difference is the set of elements which are in either of the arrays, but not in their intersection.

Template

Type of elements in the input arrays.

Param

The first array.

Param

The second array.

Param

The custom equality function to compare elements.

Returns

An array containing the elements that are present in either arr1 or arr2 but not in both, based on the custom equality function.

Example

// Custom equality function for objects with an 'id' property
const areObjectsEqual = (a, b) => a.id === b.id;
xorWith([{ id: 1 }, { id: 2 }], [{ id: 2 }, { id: 3 }], areObjectsEqual);
// Returns [{ id: 1 }, { id: 3 }]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

zip

const zip: typeof esToolkit_zip = esToolkit_zip;

Combines multiple arrays into a single array of tuples.

This function takes multiple arrays and returns a new array where each element is a tuple containing the corresponding elements from the input arrays. If the input arrays are of different lengths, the resulting array will have the length of the longest input array, with undefined values for missing elements.

Template

Param

The first array to zip.

Returns

A new array of tuples containing the corresponding elements from the input arrays.

Example

const arr1 = [1, 2, 3];
const result = zip(arr1);
// result will be [[1], [2], [3]]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

zipObject

const zipObject: typeof esToolkit_zipObject = esToolkit_zipObject;

Combines two arrays, one of property names and one of corresponding values, into a single object.

This function takes two arrays: one containing property names and another containing corresponding values. It returns a new object where the property names from the first array are keys, and the corresponding elements from the second array are values. If the keys array is longer than the values array, the remaining keys will have undefined as their values.

Template

The type of elements in the array.

Template

The type of elements in the array.

Param

An array of property names.

Param

An array of values corresponding to the property names.

Returns

A new object composed of the given property names and values.

Example

const keys = ['a', 'b', 'c'];
const values = [1, 2, 3];
const result = zipObject(keys, values);
// result will be { a: 1, b: 2, c: 3 }

const keys2 = ['a', 'b', 'c'];
const values2 = [1, 2];
const result2 = zipObject(keys2, values2);
// result2 will be { a: 1, b: 2, c: undefined }

const keys2 = ['a', 'b'];
const values2 = [1, 2, 3];
const result2 = zipObject(keys2, values2);
// result2 will be { a: 1, b: 2 }

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit

zipWith

const zipWith: typeof esToolkit_zipWith = esToolkit_zipWith;

Combines multiple arrays into a single array using a custom combiner function.

This function takes multiple arrays and a combiner function, and returns a new array where each element is the result of applying the combiner function to the corresponding elements of the input arrays.

Template

The type of elements in the first array.

Template

The type of elements in the resulting array.

Param

The first array to zip.

Param

The combiner function that takes corresponding elements from each array, their index, and returns a single value.

Returns

A new array where each element is the result of applying the combiner function to the corresponding elements of the input arrays.

Examples

// Example usage with two arrays:
const arr1 = [1, 2, 3];
const arr2 = [4, 5, 6];
const result = zipWith(arr1, arr2, (a, b) => a + b);
// result will be [5, 7, 9]

// Example usage with three arrays:
const arr1 = [1, 2];
const arr2 = [3, 4];
const arr3 = [5, 6];
const result = zipWith(arr1, arr2, arr3, (a, b, c) => `${a}${b}${c}`);
// result will be [`135`, `246`]

See

Powered by es-toolkit (MIT License): https://github.com/toss/es-toolkit