es-toolkit 1.48.1 → 1.49.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # es-toolkit Changelog
 
+## Version v1.49.0
+
+Released on June 26th, 2026.
+
+- Added the `es-toolkit/fp` entrypoint with data-last, pipeable utilities,
+  documentation, benchmarks, and bundle-size checks. ([#1781])
+- Added a broad set of array utilities to `es-toolkit/fp`, covering slicing,
+  grouping, set operations, ordering, zipping, and collection helpers. ([#1801])
+- Fixed `trimStart` to validate multi-character trim strings correctly before
+  it stops trimming. ([#1615])
+- Fixed `compat/pick` to prefer a literal key over a dot-notation path when the
+  picked value is `undefined`. ([#1775])
+- Fixed `compat/random` to better match Lodash behavior for coerced bounds and
+  floating-point options. ([#1767])
+- Fixed `compat/chunk` to handle `NaN` and `Infinity` size values consistently
+  with Lodash. ([#1797])
+- Improved documentation and JSDoc accuracy across array, function, and compat
+  references. ([#1785], [#1786], [#1788], [#1790], [#1791], [#1792], [#1793],
+  [#1795], [#1800])
+
+We sincerely thank @Antoliny0919, @D-Sketon, @eunwoo-levi, and @raon0211 for
+their contributions. We appreciate your great efforts!
+
 ## Version v1.48.1
 
 Released on June 21st, 2026.

package/dist/array/chunkBy.d.mts

@@ -0,0 +1,32 @@
+//#region src/array/chunkBy.d.ts
+/**
+ * Splits an array into chunks of consecutive elements that share the same key.
+ *
+ * Walking left to right, each element's key is derived by `iteratee`. Whenever
+ * the key differs from the previous element's key, a new chunk is started;
+ * otherwise the element is appended to the current chunk. Keys are compared with
+ * `!==` (strict inequality), so equal primitives stay together while distinct
+ * object references always start a new chunk.
+ *
+ * Unlike {@link chunk}, which splits by a fixed size, `chunkBy` splits by a
+ * boundary condition, keeping runs of same-keyed elements together.
+ *
+ * @template T - The type of elements in the array.
+ * @param arr - The array to split into chunks.
+ * @param iteratee - A function that derives the comparison key for each element.
+ * @returns A two-dimensional array where each sub-array is a run of consecutive
+ *   elements that produced the same key.
+ *
+ * @example
+ * // Group consecutive equal numbers
+ * chunkBy([1, 1, 2, 3, 3, 3], value => value);
+ * // Returns: [[1, 1], [2], [3, 3, 3]]
+ *
+ * @example
+ * // Group consecutive words by their length
+ * chunkBy(['a', 'b', 'cd', 'ef', 'g'], word => word.length);
+ * // Returns: [['a', 'b'], ['cd', 'ef'], ['g']]
+ */
+declare function chunkBy<T>(arr: readonly T[], iteratee: (value: T) => unknown): T[][];
+//#endregion
+export { chunkBy };

package/dist/array/chunkBy.d.ts

@@ -0,0 +1,32 @@
+//#region src/array/chunkBy.d.ts
+/**
+ * Splits an array into chunks of consecutive elements that share the same key.
+ *
+ * Walking left to right, each element's key is derived by `iteratee`. Whenever
+ * the key differs from the previous element's key, a new chunk is started;
+ * otherwise the element is appended to the current chunk. Keys are compared with
+ * `!==` (strict inequality), so equal primitives stay together while distinct
+ * object references always start a new chunk.
+ *
+ * Unlike {@link chunk}, which splits by a fixed size, `chunkBy` splits by a
+ * boundary condition, keeping runs of same-keyed elements together.
+ *
+ * @template T - The type of elements in the array.
+ * @param arr - The array to split into chunks.
+ * @param iteratee - A function that derives the comparison key for each element.
+ * @returns A two-dimensional array where each sub-array is a run of consecutive
+ *   elements that produced the same key.
+ *
+ * @example
+ * // Group consecutive equal numbers
+ * chunkBy([1, 1, 2, 3, 3, 3], value => value);
+ * // Returns: [[1, 1], [2], [3, 3, 3]]
+ *
+ * @example
+ * // Group consecutive words by their length
+ * chunkBy(['a', 'b', 'cd', 'ef', 'g'], word => word.length);
+ * // Returns: [['a', 'b'], ['cd', 'ef'], ['g']]
+ */
+declare function chunkBy<T>(arr: readonly T[], iteratee: (value: T) => unknown): T[][];
+//#endregion
+export { chunkBy };

package/dist/array/chunkBy.js

@@ -0,0 +1,42 @@
+//#region src/array/chunkBy.ts
+/**
+* Splits an array into chunks of consecutive elements that share the same key.
+*
+* Walking left to right, each element's key is derived by `iteratee`. Whenever
+* the key differs from the previous element's key, a new chunk is started;
+* otherwise the element is appended to the current chunk. Keys are compared with
+* `!==` (strict inequality), so equal primitives stay together while distinct
+* object references always start a new chunk.
+*
+* Unlike {@link chunk}, which splits by a fixed size, `chunkBy` splits by a
+* boundary condition, keeping runs of same-keyed elements together.
+*
+* @template T - The type of elements in the array.
+* @param arr - The array to split into chunks.
+* @param iteratee - A function that derives the comparison key for each element.
+* @returns A two-dimensional array where each sub-array is a run of consecutive
+*   elements that produced the same key.
+*
+* @example
+* // Group consecutive equal numbers
+* chunkBy([1, 1, 2, 3, 3, 3], value => value);
+* // Returns: [[1, 1], [2], [3, 3, 3]]
+*
+* @example
+* // Group consecutive words by their length
+* chunkBy(['a', 'b', 'cd', 'ef', 'g'], word => word.length);
+* // Returns: [['a', 'b'], ['cd', 'ef'], ['g']]
+*/
+function chunkBy(arr, iteratee) {
+	const result = [];
+	let prevKey;
+	for (let i = 0; i < arr.length; i++) {
+		const key = iteratee(arr[i]);
+		if (i === 0 || key !== prevKey) result.push([arr[i]]);
+		else result[result.length - 1].push(arr[i]);
+		prevKey = key;
+	}
+	return result;
+}
+//#endregion
+exports.chunkBy = chunkBy;

package/dist/array/chunkBy.mjs

@@ -0,0 +1,42 @@
+//#region src/array/chunkBy.ts
+/**
+* Splits an array into chunks of consecutive elements that share the same key.
+*
+* Walking left to right, each element's key is derived by `iteratee`. Whenever
+* the key differs from the previous element's key, a new chunk is started;
+* otherwise the element is appended to the current chunk. Keys are compared with
+* `!==` (strict inequality), so equal primitives stay together while distinct
+* object references always start a new chunk.
+*
+* Unlike {@link chunk}, which splits by a fixed size, `chunkBy` splits by a
+* boundary condition, keeping runs of same-keyed elements together.
+*
+* @template T - The type of elements in the array.
+* @param arr - The array to split into chunks.
+* @param iteratee - A function that derives the comparison key for each element.
+* @returns A two-dimensional array where each sub-array is a run of consecutive
+*   elements that produced the same key.
+*
+* @example
+* // Group consecutive equal numbers
+* chunkBy([1, 1, 2, 3, 3, 3], value => value);
+* // Returns: [[1, 1], [2], [3, 3, 3]]
+*
+* @example
+* // Group consecutive words by their length
+* chunkBy(['a', 'b', 'cd', 'ef', 'g'], word => word.length);
+* // Returns: [['a', 'b'], ['cd', 'ef'], ['g']]
+*/
+function chunkBy(arr, iteratee) {
+	const result = [];
+	let prevKey;
+	for (let i = 0; i < arr.length; i++) {
+		const key = iteratee(arr[i]);
+		if (i === 0 || key !== prevKey) result.push([arr[i]]);
+		else result[result.length - 1].push(arr[i]);
+		prevKey = key;
+	}
+	return result;
+}
+//#endregion
+export { chunkBy };

package/dist/array/index.d.mts

@@ -1,6 +1,7 @@
 import { at } from "./at.mjs";
 import { cartesianProduct } from "./cartesianProduct.mjs";
 import { chunk } from "./chunk.mjs";
+import { chunkBy } from "./chunkBy.mjs";
 import { combinations } from "./combinations.mjs";
 import { compact } from "./compact.mjs";
 import { countBy } from "./countBy.mjs";
@@ -66,4 +67,4 @@ import { xorWith } from "./xorWith.mjs";
 import { zip } from "./zip.mjs";
 import { zipObject } from "./zipObject.mjs";
 import { zipWith } from "./zipWith.mjs";
-export { at, cartesianProduct, chunk, combinations, compact, countBy, difference, differenceBy, differenceWith, drop, dropRight, dropRightWhile, dropWhile, fill, filterAsync, flatMap, flatMapAsync, flatMapDeep, flatten, flattenDeep, forEachAsync, forEachRight, groupBy, head, initial, intersection, intersectionBy, intersectionWith, isSubset, isSubsetWith, keyBy, last, limitAsync, mapAsync, maxBy, minBy, orderBy, partition, pull, pullAt, reduceAsync, remove, sample, sampleSize, shuffle, sortBy, tail, take, takeRight, takeRightWhile, takeWhile, toFilled, union, unionBy, unionWith, uniq, uniqBy, uniqWith, unzip, unzipWith, windowed, without, xor, xorBy, xorWith, zip, zipObject, zipWith };
+export { at, cartesianProduct, chunk, chunkBy, combinations, compact, countBy, difference, differenceBy, differenceWith, drop, dropRight, dropRightWhile, dropWhile, fill, filterAsync, flatMap, flatMapAsync, flatMapDeep, flatten, flattenDeep, forEachAsync, forEachRight, groupBy, head, initial, intersection, intersectionBy, intersectionWith, isSubset, isSubsetWith, keyBy, last, limitAsync, mapAsync, maxBy, minBy, orderBy, partition, pull, pullAt, reduceAsync, remove, sample, sampleSize, shuffle, sortBy, tail, take, takeRight, takeRightWhile, takeWhile, toFilled, union, unionBy, unionWith, uniq, uniqBy, uniqWith, unzip, unzipWith, windowed, without, xor, xorBy, xorWith, zip, zipObject, zipWith };

package/dist/array/index.d.ts

@@ -1,6 +1,7 @@
 import { at } from "./at.js";
 import { cartesianProduct } from "./cartesianProduct.js";
 import { chunk } from "./chunk.js";
+import { chunkBy } from "./chunkBy.js";
 import { combinations } from "./combinations.js";
 import { compact } from "./compact.js";
 import { countBy } from "./countBy.js";
@@ -66,4 +67,4 @@ import { xorWith } from "./xorWith.js";
 import { zip } from "./zip.js";
 import { zipObject } from "./zipObject.js";
 import { zipWith } from "./zipWith.js";
-export { at, cartesianProduct, chunk, combinations, compact, countBy, difference, differenceBy, differenceWith, drop, dropRight, dropRightWhile, dropWhile, fill, filterAsync, flatMap, flatMapAsync, flatMapDeep, flatten, flattenDeep, forEachAsync, forEachRight, groupBy, head, initial, intersection, intersectionBy, intersectionWith, isSubset, isSubsetWith, keyBy, last, limitAsync, mapAsync, maxBy, minBy, orderBy, partition, pull, pullAt, reduceAsync, remove, sample, sampleSize, shuffle, sortBy, tail, take, takeRight, takeRightWhile, takeWhile, toFilled, union, unionBy, unionWith, uniq, uniqBy, uniqWith, unzip, unzipWith, windowed, without, xor, xorBy, xorWith, zip, zipObject, zipWith };
+export { at, cartesianProduct, chunk, chunkBy, combinations, compact, countBy, difference, differenceBy, differenceWith, drop, dropRight, dropRightWhile, dropWhile, fill, filterAsync, flatMap, flatMapAsync, flatMapDeep, flatten, flattenDeep, forEachAsync, forEachRight, groupBy, head, initial, intersection, intersectionBy, intersectionWith, isSubset, isSubsetWith, keyBy, last, limitAsync, mapAsync, maxBy, minBy, orderBy, partition, pull, pullAt, reduceAsync, remove, sample, sampleSize, shuffle, sortBy, tail, take, takeRight, takeRightWhile, takeWhile, toFilled, union, unionBy, unionWith, uniq, uniqBy, uniqWith, unzip, unzipWith, windowed, without, xor, xorBy, xorWith, zip, zipObject, zipWith };

package/dist/array/index.js

@@ -2,6 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_at = require("./at.js");
 const require_cartesianProduct = require("./cartesianProduct.js");
 const require_chunk = require("./chunk.js");
+const require_chunkBy = require("./chunkBy.js");
 const require_combinations = require("./combinations.js");
 const require_compact = require("./compact.js");
 const require_countBy = require("./countBy.js");
@@ -70,6 +71,7 @@ const require_zipWith = require("./zipWith.js");
 exports.at = require_at.at;
 exports.cartesianProduct = require_cartesianProduct.cartesianProduct;
 exports.chunk = require_chunk.chunk;
+exports.chunkBy = require_chunkBy.chunkBy;
 exports.combinations = require_combinations.combinations;
 exports.compact = require_compact.compact;
 exports.countBy = require_countBy.countBy;

package/dist/array/index.mjs

@@ -1,6 +1,7 @@
 import { at } from "./at.mjs";
 import { cartesianProduct } from "./cartesianProduct.mjs";
 import { chunk } from "./chunk.mjs";
+import { chunkBy } from "./chunkBy.mjs";
 import { combinations } from "./combinations.mjs";
 import { compact } from "./compact.mjs";
 import { countBy } from "./countBy.mjs";
@@ -66,4 +67,4 @@ import { xorWith } from "./xorWith.mjs";
 import { zip } from "./zip.mjs";
 import { zipObject } from "./zipObject.mjs";
 import { zipWith } from "./zipWith.mjs";
-export { at, cartesianProduct, chunk, combinations, compact, countBy, difference, differenceBy, differenceWith, drop, dropRight, dropRightWhile, dropWhile, fill, filterAsync, flatMap, flatMapAsync, flatMapDeep, flatten, flattenDeep, forEachAsync, forEachRight, groupBy, head, initial, intersection, intersectionBy, intersectionWith, isSubset, isSubsetWith, keyBy, last, limitAsync, mapAsync, maxBy, minBy, orderBy, partition, pull, pullAt, reduceAsync, remove, sample, sampleSize, shuffle, sortBy, tail, take, takeRight, takeRightWhile, takeWhile, toFilled, union, unionBy, unionWith, uniq, uniqBy, uniqWith, unzip, unzipWith, windowed, without, xor, xorBy, xorWith, zip, zipObject, zipWith };
+export { at, cartesianProduct, chunk, chunkBy, combinations, compact, countBy, difference, differenceBy, differenceWith, drop, dropRight, dropRightWhile, dropWhile, fill, filterAsync, flatMap, flatMapAsync, flatMapDeep, flatten, flattenDeep, forEachAsync, forEachRight, groupBy, head, initial, intersection, intersectionBy, intersectionWith, isSubset, isSubsetWith, keyBy, last, limitAsync, mapAsync, maxBy, minBy, orderBy, partition, pull, pullAt, reduceAsync, remove, sample, sampleSize, shuffle, sortBy, tail, take, takeRight, takeRightWhile, takeWhile, toFilled, union, unionBy, unionWith, uniq, uniqBy, uniqWith, unzip, unzipWith, windowed, without, xor, xorBy, xorWith, zip, zipObject, zipWith };

package/dist/array/take.d.mts

@@ -7,7 +7,6 @@
  *
  * @param arr - The array to take elements from.
  * @param count - The number of elements to take.
- * @param guard - If truthy, ignores `count` and defaults to 1.
  * @returns A new array containing the first `count` elements from `arr`.
  *
  * @example
@@ -21,12 +20,7 @@
  * @example
  * // Returns [1, 2, 3]
  * take([1, 2, 3], 5);
- *
- * @example
- * // Returns [[1], [1], [1]]
- * const arr = [1, 2, 3];
- * const result = arr.map((v, i, array) => take(array, i, true));
  */
-declare function take<T>(arr: readonly T[], count?: number, guard?: unknown): T[];
+declare function take<T>(arr: readonly T[], count: number): T[];
 //#endregion
 export { take };

package/dist/array/take.d.ts

@@ -7,7 +7,6 @@
  *
  * @param arr - The array to take elements from.
  * @param count - The number of elements to take.
- * @param guard - If truthy, ignores `count` and defaults to 1.
  * @returns A new array containing the first `count` elements from `arr`.
  *
  * @example
@@ -21,12 +20,7 @@
  * @example
  * // Returns [1, 2, 3]
  * take([1, 2, 3], 5);
- *
- * @example
- * // Returns [[1], [1], [1]]
- * const arr = [1, 2, 3];
- * const result = arr.map((v, i, array) => take(array, i, true));
  */
-declare function take<T>(arr: readonly T[], count?: number, guard?: unknown): T[];
+declare function take<T>(arr: readonly T[], count: number): T[];
 //#endregion
 export { take };

package/dist/array/take.js

@@ -1,4 +1,3 @@
-const require_toInteger = require("../compat/util/toInteger.js");
 //#region src/array/take.ts
 /**
 * Returns a new array containing the first `count` elements from the input array `arr`.
@@ -8,7 +7,6 @@ const require_toInteger = require("../compat/util/toInteger.js");
 *
 * @param arr - The array to take elements from.
 * @param count - The number of elements to take.
-* @param guard - If truthy, ignores `count` and defaults to 1.
 * @returns A new array containing the first `count` elements from `arr`.
 *
 * @example
@@ -22,14 +20,8 @@ const require_toInteger = require("../compat/util/toInteger.js");
 * @example
 * // Returns [1, 2, 3]
 * take([1, 2, 3], 5);
-*
-* @example
-* // Returns [[1], [1], [1]]
-* const arr = [1, 2, 3];
-* const result = arr.map((v, i, array) => take(array, i, true));
 */
-function take(arr, count, guard) {
-	count = guard || count === void 0 ? 1 : require_toInteger.toInteger(count);
+function take(arr, count) {
 	return arr.slice(0, count);
 }
 //#endregion

package/dist/array/take.mjs

@@ -1,4 +1,3 @@
-import { toInteger } from "../compat/util/toInteger.mjs";
 //#region src/array/take.ts
 /**
 * Returns a new array containing the first `count` elements from the input array `arr`.
@@ -8,7 +7,6 @@ import { toInteger } from "../compat/util/toInteger.mjs";
 *
 * @param arr - The array to take elements from.
 * @param count - The number of elements to take.
-* @param guard - If truthy, ignores `count` and defaults to 1.
 * @returns A new array containing the first `count` elements from `arr`.
 *
 * @example
@@ -22,14 +20,8 @@ import { toInteger } from "../compat/util/toInteger.mjs";
 * @example
 * // Returns [1, 2, 3]
 * take([1, 2, 3], 5);
-*
-* @example
-* // Returns [[1], [1], [1]]
-* const arr = [1, 2, 3];
-* const result = arr.map((v, i, array) => take(array, i, true));
 */
-function take(arr, count, guard) {
-	count = guard || count === void 0 ? 1 : toInteger(count);
+function take(arr, count) {
 	return arr.slice(0, count);
 }
 //#endregion

package/dist/array/takeRight.d.mts

@@ -5,7 +5,7 @@
  *
  * @template T - The type of elements in the array.
  * @param arr - The array to take elements from.
- * @param [count=1] - The number of elements to take.
+ * @param count - The number of elements to take.
  * @returns A new array containing the last `count` elements from `arr`.
  *
  * @example
@@ -20,6 +20,6 @@
  * // Returns [1, 2, 3]
  * takeRight([1, 2, 3], 5);
  */
-declare function takeRight<T>(arr: readonly T[], count?: number, guard?: unknown): T[];
+declare function takeRight<T>(arr: readonly T[], count: number): T[];
 //#endregion
 export { takeRight };

package/dist/array/takeRight.d.ts

@@ -5,7 +5,7 @@
  *
  * @template T - The type of elements in the array.
  * @param arr - The array to take elements from.
- * @param [count=1] - The number of elements to take.
+ * @param count - The number of elements to take.
  * @returns A new array containing the last `count` elements from `arr`.
  *
  * @example
@@ -20,6 +20,6 @@
  * // Returns [1, 2, 3]
  * takeRight([1, 2, 3], 5);
  */
-declare function takeRight<T>(arr: readonly T[], count?: number, guard?: unknown): T[];
+declare function takeRight<T>(arr: readonly T[], count: number): T[];
 //#endregion
 export { takeRight };

package/dist/array/takeRight.js

@@ -1,4 +1,3 @@
-const require_toInteger = require("../compat/util/toInteger.js");
 //#region src/array/takeRight.ts
 /**
 * Returns a new array containing the last `count` elements from the input array `arr`.
@@ -6,7 +5,7 @@ const require_toInteger = require("../compat/util/toInteger.js");
 *
 * @template T - The type of elements in the array.
 * @param arr - The array to take elements from.
-* @param [count=1] - The number of elements to take.
+* @param count - The number of elements to take.
 * @returns A new array containing the last `count` elements from `arr`.
 *
 * @example
@@ -21,8 +20,7 @@ const require_toInteger = require("../compat/util/toInteger.js");
 * // Returns [1, 2, 3]
 * takeRight([1, 2, 3], 5);
 */
-function takeRight(arr, count, guard) {
-	count = guard || count === void 0 ? 1 : require_toInteger.toInteger(count);
+function takeRight(arr, count) {
 	if (count <= 0 || arr.length === 0) return [];
 	return arr.slice(-count);
 }

package/dist/array/takeRight.mjs

@@ -1,4 +1,3 @@
-import { toInteger } from "../compat/util/toInteger.mjs";
 //#region src/array/takeRight.ts
 /**
 * Returns a new array containing the last `count` elements from the input array `arr`.
@@ -6,7 +5,7 @@ import { toInteger } from "../compat/util/toInteger.mjs";
 *
 * @template T - The type of elements in the array.
 * @param arr - The array to take elements from.
-* @param [count=1] - The number of elements to take.
+* @param count - The number of elements to take.
 * @returns A new array containing the last `count` elements from `arr`.
 *
 * @example
@@ -21,8 +20,7 @@ import { toInteger } from "../compat/util/toInteger.mjs";
 * // Returns [1, 2, 3]
 * takeRight([1, 2, 3], 5);
 */
-function takeRight(arr, count, guard) {
-	count = guard || count === void 0 ? 1 : toInteger(count);
+function takeRight(arr, count) {
 	if (count <= 0 || arr.length === 0) return [];
 	return arr.slice(-count);
 }

package/dist/array/windowed.d.mts

@@ -50,4 +50,4 @@ declare function windowed<T>(arr: readonly T[], size: number, step?: number, {
   partialWindows
 }?: WindowedOptions): T[][];
 //#endregion
-export { windowed };
+export { WindowedOptions, windowed };

package/dist/array/windowed.d.ts

@@ -50,4 +50,4 @@ declare function windowed<T>(arr: readonly T[], size: number, step?: number, {
   partialWindows
 }?: WindowedOptions): T[][];
 //#endregion
-export { windowed };
+export { WindowedOptions, windowed };