es-toolkit 1.17.0 → 1.18.0-dev.573

package/dist/array/flatMapDeep.d.ts

@@ -0,0 +1,18 @@
+import { ExtractNestedArrayType } from './flattenDeep.js';
+
+/**
+ * Recursively maps each element in an array using a provided iteratee function and then deeply flattens the resulting array.
+ *
+ * @template T - The type of elements within the array.
+ * @template U - The type of elements within the returned array from the iteratee function.
+ * @param {T[]} arr - The array to flatten.
+ * @param {(item: T) => U} iteratee - The function that produces the new array elements.
+ * @returns {Array<ExtractNestedArrayType<U>>} A new array that has been flattened.
+ *
+ * @example
+ * const result = flatMapDeep([1, 2, 3], n => [[n, n]]);
+ * // [1, 1, 2, 2, 3, 3]
+ */
+declare function flatMapDeep<T, U>(arr: readonly T[], iteratee: (item: T) => U): Array<ExtractNestedArrayType<U>>;
+
+export { flatMapDeep };

package/dist/array/flatMapDeep.mjs

@@ -0,0 +1,7 @@
+import { flattenDeep } from './flattenDeep.mjs';
+
+function flatMapDeep(arr, iteratee) {
+    return flattenDeep(arr.map((item) => iteratee(item)));
+}
+
+export { flatMapDeep };

package/dist/array/flattenDeep.d.mts

@@ -22,4 +22,4 @@ type ExtractNestedArrayType<T> = T extends ReadonlyArray<infer U> ? ExtractNeste
  */
 declare function flattenDeep<T>(arr: readonly T[]): Array<ExtractNestedArrayType<T>>;
 
-export { flattenDeep };
+export { type ExtractNestedArrayType, flattenDeep };

package/dist/array/flattenDeep.d.ts

@@ -22,4 +22,4 @@ type ExtractNestedArrayType<T> = T extends ReadonlyArray<infer U> ? ExtractNeste
  */
 declare function flattenDeep<T>(arr: readonly T[]): Array<ExtractNestedArrayType<T>>;
 
-export { flattenDeep };
+export { type ExtractNestedArrayType, flattenDeep };

package/dist/array/head.d.mts

@@ -5,19 +5,30 @@
  * If the array is empty, the function returns `undefined`.
  *
  * @template T - The type of elements in the array.
- * @param {T[]} arr - The array from which to get the first element.
- * @returns {T | undefined} The first element of the array, or `undefined` if the array is empty.
+ * @param {[T, ...T[]]} arr - A non-empty array from which to get the first element.
+ * @returns {T} The first element of the array.
  *
  * @example
  * const arr = [1, 2, 3];
  * const firstElement = head(arr);
  * // firstElement will be 1
+ */
+declare function head<T>(arr: readonly [T, ...T[]]): T;
+/**
+ * Returns the first element of an array or `undefined` if the array is empty.
+ *
+ * This function takes an array and returns the first element of the array.
+ * If the array is empty, the function returns `undefined`.
  *
+ * @template T - The type of elements in the array.
+ * @param {T[]} arr - The array from which to get the first element.
+ * @returns {T | undefined} The first element of the array, or `undefined` if the array is empty.
+ *
+ * @example
  * const emptyArr: number[] = [];
  * const noElement = head(emptyArr);
  * // noElement will be undefined
  */
-declare function head<T>(arr: readonly [T, ...T[]]): T;
 declare function head<T>(arr: readonly T[]): T | undefined;
 
 export { head };

package/dist/array/head.d.ts

@@ -5,19 +5,30 @@
  * If the array is empty, the function returns `undefined`.
  *
  * @template T - The type of elements in the array.
- * @param {T[]} arr - The array from which to get the first element.
- * @returns {T | undefined} The first element of the array, or `undefined` if the array is empty.
+ * @param {[T, ...T[]]} arr - A non-empty array from which to get the first element.
+ * @returns {T} The first element of the array.
  *
  * @example
  * const arr = [1, 2, 3];
  * const firstElement = head(arr);
  * // firstElement will be 1
+ */
+declare function head<T>(arr: readonly [T, ...T[]]): T;
+/**
+ * Returns the first element of an array or `undefined` if the array is empty.
+ *
+ * This function takes an array and returns the first element of the array.
+ * If the array is empty, the function returns `undefined`.
  *
+ * @template T - The type of elements in the array.
+ * @param {T[]} arr - The array from which to get the first element.
+ * @returns {T | undefined} The first element of the array, or `undefined` if the array is empty.
+ *
+ * @example
  * const emptyArr: number[] = [];
  * const noElement = head(emptyArr);
  * // noElement will be undefined
  */
-declare function head<T>(arr: readonly [T, ...T[]]): T;
 declare function head<T>(arr: readonly T[]): T | undefined;
 
 export { head };

package/dist/array/index.d.mts

@@ -11,27 +11,34 @@ export { dropRightWhile } from './dropRightWhile.mjs';
 export { dropWhile } from './dropWhile.mjs';
 export { fill } from './fill.mjs';
 export { flatMap } from './flatMap.mjs';
+export { flatMapDeep } from './flatMapDeep.mjs';
 export { flatten } from './flatten.mjs';
 export { flattenDeep } from './flattenDeep.mjs';
 export { forEachRight } from './forEachRight.mjs';
 export { groupBy } from './groupBy.mjs';
+export { head } from './head.mjs';
+export { initial } from './initial.mjs';
 export { intersection } from './intersection.mjs';
 export { intersectionBy } from './intersectionBy.mjs';
 export { intersectionWith } from './intersectionWith.mjs';
+export { isSubset } from './isSubset.mjs';
 export { keyBy } from './keyBy.mjs';
+export { last } from './last.mjs';
 export { maxBy } from './maxBy.mjs';
 export { minBy } from './minBy.mjs';
 export { orderBy } from './orderBy.mjs';
 export { partition } from './partition.mjs';
 export { pullAt } from './pullAt.mjs';
-export { sortBy } from './sortBy.mjs';
 export { sample } from './sample.mjs';
 export { sampleSize } from './sampleSize.mjs';
 export { shuffle } from './shuffle.mjs';
+export { sortBy } from './sortBy.mjs';
+export { tail } from './tail.mjs';
 export { take } from './take.mjs';
 export { takeRight } from './takeRight.mjs';
 export { takeRightWhile } from './takeRightWhile.mjs';
 export { takeWhile } from './takeWhile.mjs';
+export { toFilled } from './toFilled.mjs';
 export { union } from './union.mjs';
 export { unionBy } from './unionBy.mjs';
 export { unionWith } from './unionWith.mjs';
@@ -40,16 +47,10 @@ export { uniqBy } from './uniqBy.mjs';
 export { uniqWith } from './uniqWith.mjs';
 export { unzip } from './unzip.mjs';
 export { unzipWith } from './unzipWith.mjs';
+export { without } from './without.mjs';
 export { xor } from './xor.mjs';
 export { xorBy } from './xorBy.mjs';
 export { xorWith } from './xorWith.mjs';
 export { zip } from './zip.mjs';
 export { zipObject } from './zipObject.mjs';
 export { zipWith } from './zipWith.mjs';
-export { without } from './without.mjs';
-export { head } from './head.mjs';
-export { isSubset } from './isSubset.mjs';
-export { tail } from './tail.mjs';
-export { toFilled } from './toFilled.mjs';
-export { last } from './last.mjs';
-export { initial } from './initial.mjs';

package/dist/array/index.d.ts

@@ -11,27 +11,34 @@ export { dropRightWhile } from './dropRightWhile.js';
 export { dropWhile } from './dropWhile.js';
 export { fill } from './fill.js';
 export { flatMap } from './flatMap.js';
+export { flatMapDeep } from './flatMapDeep.js';
 export { flatten } from './flatten.js';
 export { flattenDeep } from './flattenDeep.js';
 export { forEachRight } from './forEachRight.js';
 export { groupBy } from './groupBy.js';
+export { head } from './head.js';
+export { initial } from './initial.js';
 export { intersection } from './intersection.js';
 export { intersectionBy } from './intersectionBy.js';
 export { intersectionWith } from './intersectionWith.js';
+export { isSubset } from './isSubset.js';
 export { keyBy } from './keyBy.js';
+export { last } from './last.js';
 export { maxBy } from './maxBy.js';
 export { minBy } from './minBy.js';
 export { orderBy } from './orderBy.js';
 export { partition } from './partition.js';
 export { pullAt } from './pullAt.js';
-export { sortBy } from './sortBy.js';
 export { sample } from './sample.js';
 export { sampleSize } from './sampleSize.js';
 export { shuffle } from './shuffle.js';
+export { sortBy } from './sortBy.js';
+export { tail } from './tail.js';
 export { take } from './take.js';
 export { takeRight } from './takeRight.js';
 export { takeRightWhile } from './takeRightWhile.js';
 export { takeWhile } from './takeWhile.js';
+export { toFilled } from './toFilled.js';
 export { union } from './union.js';
 export { unionBy } from './unionBy.js';
 export { unionWith } from './unionWith.js';
@@ -40,16 +47,10 @@ export { uniqBy } from './uniqBy.js';
 export { uniqWith } from './uniqWith.js';
 export { unzip } from './unzip.js';
 export { unzipWith } from './unzipWith.js';
+export { without } from './without.js';
 export { xor } from './xor.js';
 export { xorBy } from './xorBy.js';
 export { xorWith } from './xorWith.js';
 export { zip } from './zip.js';
 export { zipObject } from './zipObject.js';
 export { zipWith } from './zipWith.js';
-export { without } from './without.js';
-export { head } from './head.js';
-export { isSubset } from './isSubset.js';
-export { tail } from './tail.js';
-export { toFilled } from './toFilled.js';
-export { last } from './last.js';
-export { initial } from './initial.js';

package/dist/array/index.js

@@ -2,64 +2,93 @@
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
-const initial = require('../_chunk/initial-Ci2bn_.js');
+const zipWith = require('../_chunk/zipWith-CYaH1Y.js');
 
-function flattenDeep(arr) {
-    return initial.flatten(arr, Infinity);
+function compareValues(a, b, order) {
+    if (a < b) {
+        return order === 'asc' ? -1 : 1;
+    }
+    if (a > b) {
+        return order === 'asc' ? 1 : -1;
+    }
+    return 0;
 }
 
-exports.at = initial.at;
-exports.chunk = initial.chunk;
-exports.compact = initial.compact;
-exports.countBy = initial.countBy;
-exports.difference = initial.difference;
-exports.differenceBy = initial.differenceBy;
-exports.differenceWith = initial.differenceWith;
-exports.drop = initial.drop;
-exports.dropRight = initial.dropRight;
-exports.dropRightWhile = initial.dropRightWhile;
-exports.dropWhile = initial.dropWhile;
-exports.fill = initial.fill;
-exports.flatMap = initial.flatMap;
-exports.flatten = initial.flatten;
-exports.forEachRight = initial.forEachRight;
-exports.groupBy = initial.groupBy;
-exports.head = initial.head;
-exports.initial = initial.initial;
-exports.intersection = initial.intersection;
-exports.intersectionBy = initial.intersectionBy;
-exports.intersectionWith = initial.intersectionWith;
-exports.isSubset = initial.isSubset;
-exports.keyBy = initial.keyBy;
-exports.last = initial.last;
-exports.maxBy = initial.maxBy;
-exports.minBy = initial.minBy;
-exports.orderBy = initial.orderBy;
-exports.partition = initial.partition;
-exports.pullAt = initial.pullAt;
-exports.sample = initial.sample;
-exports.sampleSize = initial.sampleSize;
-exports.shuffle = initial.shuffle;
-exports.sortBy = initial.sortBy;
-exports.tail = initial.tail;
-exports.take = initial.take;
-exports.takeRight = initial.takeRight;
-exports.takeRightWhile = initial.takeRightWhile;
-exports.takeWhile = initial.takeWhile;
-exports.toFilled = initial.toFilled;
-exports.union = initial.union;
-exports.unionBy = initial.unionBy;
-exports.unionWith = initial.unionWith;
-exports.uniq = initial.uniq;
-exports.uniqBy = initial.uniqBy;
-exports.uniqWith = initial.uniqWith;
-exports.unzip = initial.unzip;
-exports.unzipWith = initial.unzipWith;
-exports.without = initial.without;
-exports.xor = initial.xor;
-exports.xorBy = initial.xorBy;
-exports.xorWith = initial.xorWith;
-exports.zip = initial.zip;
-exports.zipObject = initial.zipObject;
-exports.zipWith = initial.zipWith;
-exports.flattenDeep = flattenDeep;
+function orderBy(arr, criteria, orders) {
+    return arr.slice().sort((a, b) => {
+        const ordersLength = orders.length;
+        for (let i = 0; i < criteria.length; i++) {
+            const order = ordersLength > i ? orders[i] : orders[ordersLength - 1];
+            const criterion = criteria[i];
+            const criterionIsFunction = typeof criterion === 'function';
+            const valueA = criterionIsFunction ? criterion(a) : a[criterion];
+            const valueB = criterionIsFunction ? criterion(b) : b[criterion];
+            const result = compareValues(valueA, valueB, order);
+            if (result !== 0) {
+                return result;
+            }
+        }
+        return 0;
+    });
+}
+
+function sortBy(arr, criteria) {
+    return orderBy(arr, criteria, ['asc']);
+}
+
+exports.at = zipWith.at;
+exports.chunk = zipWith.chunk;
+exports.compact = zipWith.compact;
+exports.countBy = zipWith.countBy;
+exports.difference = zipWith.difference;
+exports.differenceBy = zipWith.differenceBy;
+exports.differenceWith = zipWith.differenceWith;
+exports.drop = zipWith.drop;
+exports.dropRight = zipWith.dropRight;
+exports.dropRightWhile = zipWith.dropRightWhile;
+exports.dropWhile = zipWith.dropWhile;
+exports.fill = zipWith.fill;
+exports.flatMap = zipWith.flatMap;
+exports.flatMapDeep = zipWith.flatMapDeep;
+exports.flatten = zipWith.flatten;
+exports.flattenDeep = zipWith.flattenDeep;
+exports.forEachRight = zipWith.forEachRight;
+exports.groupBy = zipWith.groupBy;
+exports.head = zipWith.head;
+exports.initial = zipWith.initial;
+exports.intersection = zipWith.intersection;
+exports.intersectionBy = zipWith.intersectionBy;
+exports.intersectionWith = zipWith.intersectionWith;
+exports.isSubset = zipWith.isSubset;
+exports.keyBy = zipWith.keyBy;
+exports.last = zipWith.last;
+exports.maxBy = zipWith.maxBy;
+exports.minBy = zipWith.minBy;
+exports.partition = zipWith.partition;
+exports.pullAt = zipWith.pullAt;
+exports.sample = zipWith.sample;
+exports.sampleSize = zipWith.sampleSize;
+exports.shuffle = zipWith.shuffle;
+exports.tail = zipWith.tail;
+exports.take = zipWith.take;
+exports.takeRight = zipWith.takeRight;
+exports.takeRightWhile = zipWith.takeRightWhile;
+exports.takeWhile = zipWith.takeWhile;
+exports.toFilled = zipWith.toFilled;
+exports.union = zipWith.union;
+exports.unionBy = zipWith.unionBy;
+exports.unionWith = zipWith.unionWith;
+exports.uniq = zipWith.uniq;
+exports.uniqBy = zipWith.uniqBy;
+exports.uniqWith = zipWith.uniqWith;
+exports.unzip = zipWith.unzip;
+exports.unzipWith = zipWith.unzipWith;
+exports.without = zipWith.without;
+exports.xor = zipWith.xor;
+exports.xorBy = zipWith.xorBy;
+exports.xorWith = zipWith.xorWith;
+exports.zip = zipWith.zip;
+exports.zipObject = zipWith.zipObject;
+exports.zipWith = zipWith.zipWith;
+exports.orderBy = orderBy;
+exports.sortBy = sortBy;

package/dist/array/index.mjs

@@ -11,27 +11,34 @@ export { dropRightWhile } from './dropRightWhile.mjs';
 export { dropWhile } from './dropWhile.mjs';
 export { fill } from './fill.mjs';
 export { flatMap } from './flatMap.mjs';
+export { flatMapDeep } from './flatMapDeep.mjs';
 export { flatten } from './flatten.mjs';
 export { flattenDeep } from './flattenDeep.mjs';
 export { forEachRight } from './forEachRight.mjs';
 export { groupBy } from './groupBy.mjs';
+export { head } from './head.mjs';
+export { initial } from './initial.mjs';
 export { intersection } from './intersection.mjs';
 export { intersectionBy } from './intersectionBy.mjs';
 export { intersectionWith } from './intersectionWith.mjs';
+export { isSubset } from './isSubset.mjs';
 export { keyBy } from './keyBy.mjs';
+export { last } from './last.mjs';
 export { maxBy } from './maxBy.mjs';
 export { minBy } from './minBy.mjs';
 export { orderBy } from './orderBy.mjs';
 export { partition } from './partition.mjs';
 export { pullAt } from './pullAt.mjs';
-export { sortBy } from './sortBy.mjs';
 export { sample } from './sample.mjs';
 export { sampleSize } from './sampleSize.mjs';
 export { shuffle } from './shuffle.mjs';
+export { sortBy } from './sortBy.mjs';
+export { tail } from './tail.mjs';
 export { take } from './take.mjs';
 export { takeRight } from './takeRight.mjs';
 export { takeRightWhile } from './takeRightWhile.mjs';
 export { takeWhile } from './takeWhile.mjs';
+export { toFilled } from './toFilled.mjs';
 export { union } from './union.mjs';
 export { unionBy } from './unionBy.mjs';
 export { unionWith } from './unionWith.mjs';
@@ -40,16 +47,10 @@ export { uniqBy } from './uniqBy.mjs';
 export { uniqWith } from './uniqWith.mjs';
 export { unzip } from './unzip.mjs';
 export { unzipWith } from './unzipWith.mjs';
+export { without } from './without.mjs';
 export { xor } from './xor.mjs';
 export { xorBy } from './xorBy.mjs';
 export { xorWith } from './xorWith.mjs';
 export { zip } from './zip.mjs';
 export { zipObject } from './zipObject.mjs';
 export { zipWith } from './zipWith.mjs';
-export { without } from './without.mjs';
-export { head } from './head.mjs';
-export { isSubset } from './isSubset.mjs';
-export { tail } from './tail.mjs';
-export { toFilled } from './toFilled.mjs';
-export { last } from './last.mjs';
-export { initial } from './initial.mjs';

package/dist/array/last.d.mts

@@ -1,3 +1,26 @@
+/**
+ * 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 T - The type of elements in the array.
+ * @param {[...T[], T]} arr - The array from which to get the last element.
+ * @returns {T} 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
+ */
+declare function last<T>(arr: readonly [...T[], T]): T;
 /**
  * Returns the last element of an array.
  *
@@ -20,7 +43,6 @@
  * const noElement = last(emptyArr);
  * // noElement will be undefined
  */
-declare function last<T>(arr: readonly [...T[], T]): T;
 declare function last<T>(arr: readonly T[]): T | undefined;
 
 export { last };

package/dist/array/last.d.ts

@@ -1,3 +1,26 @@
+/**
+ * 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 T - The type of elements in the array.
+ * @param {[...T[], T]} arr - The array from which to get the last element.
+ * @returns {T} 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
+ */
+declare function last<T>(arr: readonly [...T[], T]): T;
 /**
  * Returns the last element of an array.
  *
@@ -20,7 +43,6 @@
  * const noElement = last(emptyArr);
  * // noElement will be undefined
  */
-declare function last<T>(arr: readonly [...T[], T]): T;
 declare function last<T>(arr: readonly T[]): T | undefined;
 
 export { last };

package/dist/array/maxBy.d.mts

@@ -1,3 +1,16 @@
+/**
+ * Finds the element in an array that has the maximum value when applying
+ * the `getValue` function to each element.
+ *
+ * @template T - The type of elements in the array.
+ * @param {[T, ...T[]]} items The nonempty array of elements to search.
+ * @param {(element: T) => number} getValue A function that selects a numeric value from each element.
+ * @returns {T} 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
+ */
+declare function maxBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 /**
  * Finds the element in an array that has the maximum value when applying
  * the `getValue` function to each element.
@@ -10,7 +23,6 @@
  * maxBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: { a: 3 }
  * maxBy([], x => x.a); // Returns: undefined
  */
-declare function maxBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 declare function maxBy<T>(items: readonly T[], getValue: (element: T) => number): T | undefined;
 
 export { maxBy };

package/dist/array/maxBy.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Finds the element in an array that has the maximum value when applying
+ * the `getValue` function to each element.
+ *
+ * @template T - The type of elements in the array.
+ * @param {[T, ...T[]]} items The nonempty array of elements to search.
+ * @param {(element: T) => number} getValue A function that selects a numeric value from each element.
+ * @returns {T} 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
+ */
+declare function maxBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 /**
  * Finds the element in an array that has the maximum value when applying
  * the `getValue` function to each element.
@@ -10,7 +23,6 @@
  * maxBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: { a: 3 }
  * maxBy([], x => x.a); // Returns: undefined
  */
-declare function maxBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 declare function maxBy<T>(items: readonly T[], getValue: (element: T) => number): T | undefined;
 
 export { maxBy };

package/dist/array/minBy.d.mts

@@ -1,3 +1,16 @@
+/**
+ * Finds the element in an array that has the minimum value when applying
+ * the `getValue` function to each element.
+ *
+ * @template T - The type of elements in the array.
+ * @param {[T, ...T[]]} items The nonempty array of elements to search.
+ * @param {(element: T) => number} getValue A function that selects a numeric value from each element.
+ * @returns {T} 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
+ */
+declare function minBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 /**
  * Finds the element in an array that has the minimum value when applying
  * the `getValue` function to each element.
@@ -10,7 +23,6 @@
  * minBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: { a: 1 }
  * minBy([], x => x.a); // Returns: undefined
  */
-declare function minBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 declare function minBy<T>(items: readonly T[], getValue: (element: T) => number): T | undefined;
 
 export { minBy };

package/dist/array/minBy.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Finds the element in an array that has the minimum value when applying
+ * the `getValue` function to each element.
+ *
+ * @template T - The type of elements in the array.
+ * @param {[T, ...T[]]} items The nonempty array of elements to search.
+ * @param {(element: T) => number} getValue A function that selects a numeric value from each element.
+ * @returns {T} 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
+ */
+declare function minBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 /**
  * Finds the element in an array that has the minimum value when applying
  * the `getValue` function to each element.
@@ -10,7 +23,6 @@
  * minBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: { a: 1 }
  * minBy([], x => x.a); // Returns: undefined
  */
-declare function minBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 declare function minBy<T>(items: readonly T[], getValue: (element: T) => number): T | undefined;
 
 export { minBy };