es-toolkit 1.48.1 → 1.49.0

package/dist/fp/array/forEach.d.mts

@@ -0,0 +1,22 @@
+//#region src/fp/array/forEach.d.ts
+/**
+ * Creates a function that runs a callback for every element and returns the original array.
+ *
+ * This mirrors Remeda's pipeline-friendly `forEach` behavior: the side effect
+ * runs, then the input continues through the pipeline by reference. The returned
+ * function is lazy-capable inside {@link pipe}; when followed by a
+ * short-circuiting operator, the callback only runs for consumed values.
+ *
+ * @template T - The type of elements in the array.
+ * @param callback - Called with each value and index.
+ * @returns A function that performs the side effect and returns the original array.
+ *
+ * @example
+ * import { forEach, map, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3], forEach(value => console.log(value)), map(value => value * 2));
+ * // => [2, 4, 6]
+ */
+declare function forEach<T>(callback: (value: T, index: number) => void): (array: readonly T[]) => readonly T[];
+//#endregion
+export { forEach };

package/dist/fp/array/forEach.d.ts

@@ -0,0 +1,22 @@
+//#region src/fp/array/forEach.d.ts
+/**
+ * Creates a function that runs a callback for every element and returns the original array.
+ *
+ * This mirrors Remeda's pipeline-friendly `forEach` behavior: the side effect
+ * runs, then the input continues through the pipeline by reference. The returned
+ * function is lazy-capable inside {@link pipe}; when followed by a
+ * short-circuiting operator, the callback only runs for consumed values.
+ *
+ * @template T - The type of elements in the array.
+ * @param callback - Called with each value and index.
+ * @returns A function that performs the side effect and returns the original array.
+ *
+ * @example
+ * import { forEach, map, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3], forEach(value => console.log(value)), map(value => value * 2));
+ * // => [2, 4, 6]
+ */
+declare function forEach<T>(callback: (value: T, index: number) => void): (array: readonly T[]) => readonly T[];
+//#endregion
+export { forEach };

package/dist/fp/array/forEach.js

@@ -0,0 +1,33 @@
+const require_lazy = require("../_internal/lazy.js");
+//#region src/fp/array/forEach.ts
+/**
+* Creates a function that runs a callback for every element and returns the original array.
+*
+* This mirrors Remeda's pipeline-friendly `forEach` behavior: the side effect
+* runs, then the input continues through the pipeline by reference. The returned
+* function is lazy-capable inside {@link pipe}; when followed by a
+* short-circuiting operator, the callback only runs for consumed values.
+*
+* @template T - The type of elements in the array.
+* @param callback - Called with each value and index.
+* @returns A function that performs the side effect and returns the original array.
+*
+* @example
+* import { forEach, map, pipe } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3], forEach(value => console.log(value)), map(value => value * 2));
+* // => [2, 4, 6]
+*/
+function forEach(callback) {
+	function forEachEager(array) {
+		array.forEach(callback);
+		return array;
+	}
+	const forEachLazy = require_lazy.createLazyFunction((value, index, emit) => {
+		callback(value, index);
+		emit(value);
+	});
+	return require_lazy.combineEagerAndLazyFunctions(forEachEager, forEachLazy);
+}
+//#endregion
+exports.forEach = forEach;

package/dist/fp/array/forEach.mjs

@@ -0,0 +1,32 @@
+import { combineEagerAndLazyFunctions, createLazyFunction } from "../_internal/lazy.mjs";
+//#region src/fp/array/forEach.ts
+/**
+* Creates a function that runs a callback for every element and returns the original array.
+*
+* This mirrors Remeda's pipeline-friendly `forEach` behavior: the side effect
+* runs, then the input continues through the pipeline by reference. The returned
+* function is lazy-capable inside {@link pipe}; when followed by a
+* short-circuiting operator, the callback only runs for consumed values.
+*
+* @template T - The type of elements in the array.
+* @param callback - Called with each value and index.
+* @returns A function that performs the side effect and returns the original array.
+*
+* @example
+* import { forEach, map, pipe } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3], forEach(value => console.log(value)), map(value => value * 2));
+* // => [2, 4, 6]
+*/
+function forEach(callback) {
+	function forEachEager(array) {
+		array.forEach(callback);
+		return array;
+	}
+	return combineEagerAndLazyFunctions(forEachEager, createLazyFunction((value, index, emit) => {
+		callback(value, index);
+		emit(value);
+	}));
+}
+//#endregion
+export { forEach };

package/dist/fp/array/groupBy.d.mts

@@ -0,0 +1,21 @@
+//#region src/fp/array/groupBy.d.ts
+/**
+ * Creates a function that groups values by a derived key.
+ *
+ * The key selector receives each value, index, and full input array. Values that produce
+ * the same key are collected in insertion order.
+ *
+ * @template T - The type of elements in the array.
+ * @template K - The property-key type produced by the selector.
+ * @param getKey - Called with each value, index, and array to produce a group key.
+ * @returns A function that maps a readonly array to grouped values.
+ *
+ * @example
+ * import { groupBy, pipe } from 'es-toolkit/fp';
+ *
+ * pipe(['ant', 'bear', 'cat'], groupBy(word => word.length));
+ * // => { 3: ['ant', 'cat'], 4: ['bear'] }
+ */
+declare function groupBy<T, K extends PropertyKey>(getKey: (item: T, index: number, array: readonly T[]) => K): (array: readonly T[]) => Record<K, T[]>;
+//#endregion
+export { groupBy };

package/dist/fp/array/groupBy.d.ts

@@ -0,0 +1,21 @@
+//#region src/fp/array/groupBy.d.ts
+/**
+ * Creates a function that groups values by a derived key.
+ *
+ * The key selector receives each value, index, and full input array. Values that produce
+ * the same key are collected in insertion order.
+ *
+ * @template T - The type of elements in the array.
+ * @template K - The property-key type produced by the selector.
+ * @param getKey - Called with each value, index, and array to produce a group key.
+ * @returns A function that maps a readonly array to grouped values.
+ *
+ * @example
+ * import { groupBy, pipe } from 'es-toolkit/fp';
+ *
+ * pipe(['ant', 'bear', 'cat'], groupBy(word => word.length));
+ * // => { 3: ['ant', 'cat'], 4: ['bear'] }
+ */
+declare function groupBy<T, K extends PropertyKey>(getKey: (item: T, index: number, array: readonly T[]) => K): (array: readonly T[]) => Record<K, T[]>;
+//#endregion
+export { groupBy };

package/dist/fp/array/groupBy.js

@@ -0,0 +1,26 @@
+const require_groupBy = require("../../array/groupBy.js");
+//#region src/fp/array/groupBy.ts
+/**
+* Creates a function that groups values by a derived key.
+*
+* The key selector receives each value, index, and full input array. Values that produce
+* the same key are collected in insertion order.
+*
+* @template T - The type of elements in the array.
+* @template K - The property-key type produced by the selector.
+* @param getKey - Called with each value, index, and array to produce a group key.
+* @returns A function that maps a readonly array to grouped values.
+*
+* @example
+* import { groupBy, pipe } from 'es-toolkit/fp';
+*
+* pipe(['ant', 'bear', 'cat'], groupBy(word => word.length));
+* // => { 3: ['ant', 'cat'], 4: ['bear'] }
+*/
+function groupBy(getKey) {
+	return function(array) {
+		return require_groupBy.groupBy(array, getKey);
+	};
+}
+//#endregion
+exports.groupBy = groupBy;

package/dist/fp/array/groupBy.mjs

@@ -0,0 +1,26 @@
+import { groupBy as groupBy$1 } from "../../array/groupBy.mjs";
+//#region src/fp/array/groupBy.ts
+/**
+* Creates a function that groups values by a derived key.
+*
+* The key selector receives each value, index, and full input array. Values that produce
+* the same key are collected in insertion order.
+*
+* @template T - The type of elements in the array.
+* @template K - The property-key type produced by the selector.
+* @param getKey - Called with each value, index, and array to produce a group key.
+* @returns A function that maps a readonly array to grouped values.
+*
+* @example
+* import { groupBy, pipe } from 'es-toolkit/fp';
+*
+* pipe(['ant', 'bear', 'cat'], groupBy(word => word.length));
+* // => { 3: ['ant', 'cat'], 4: ['bear'] }
+*/
+function groupBy(getKey) {
+	return function(array) {
+		return groupBy$1(array, getKey);
+	};
+}
+//#endregion
+export { groupBy };

package/dist/fp/array/head.d.mts

@@ -0,0 +1,35 @@
+//#region src/fp/array/head.d.ts
+/**
+ * Creates a function that returns the first element of a non-empty array.
+ *
+ * This overload preserves the non-empty tuple guarantee: the returned function
+ * always returns T when the piped array has at least one element.
+ *
+ * @template T - The type of elements in the array.
+ * @returns A function that maps a non-empty readonly array to its first element.
+ *
+ * @example
+ * import { head, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3] as const, head());
+ * // => 1
+ */
+declare function head<T>(): (array: readonly [T, ...T[]]) => T;
+/**
+ * Creates a function that returns the first element of an array, or undefined.
+ *
+ * Empty arrays return undefined, matching the main {@link head} behavior. Use
+ * the returned function with {@link pipe}.
+ *
+ * @template T - The type of elements in the array.
+ * @returns A function that maps a readonly array to its first element, or undefined.
+ *
+ * @example
+ * import { head, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([] as number[], head());
+ * // => undefined
+ */
+declare function head<T>(): (array: readonly T[]) => T | undefined;
+//#endregion
+export { head };

package/dist/fp/array/head.d.ts

@@ -0,0 +1,35 @@
+//#region src/fp/array/head.d.ts
+/**
+ * Creates a function that returns the first element of a non-empty array.
+ *
+ * This overload preserves the non-empty tuple guarantee: the returned function
+ * always returns T when the piped array has at least one element.
+ *
+ * @template T - The type of elements in the array.
+ * @returns A function that maps a non-empty readonly array to its first element.
+ *
+ * @example
+ * import { head, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3] as const, head());
+ * // => 1
+ */
+declare function head<T>(): (array: readonly [T, ...T[]]) => T;
+/**
+ * Creates a function that returns the first element of an array, or undefined.
+ *
+ * Empty arrays return undefined, matching the main {@link head} behavior. Use
+ * the returned function with {@link pipe}.
+ *
+ * @template T - The type of elements in the array.
+ * @returns A function that maps a readonly array to its first element, or undefined.
+ *
+ * @example
+ * import { head, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([] as number[], head());
+ * // => undefined
+ */
+declare function head<T>(): (array: readonly T[]) => T | undefined;
+//#endregion
+export { head };

package/dist/fp/array/head.js

@@ -0,0 +1,9 @@
+const require_head = require("../../array/head.js");
+//#region src/fp/array/head.ts
+function head() {
+	return function(array) {
+		return require_head.head(array);
+	};
+}
+//#endregion
+exports.head = head;

package/dist/fp/array/head.mjs

@@ -0,0 +1,9 @@
+import { head as head$1 } from "../../array/head.mjs";
+//#region src/fp/array/head.ts
+function head() {
+	return function(array) {
+		return head$1(array);
+	};
+}
+//#endregion
+export { head };

package/dist/fp/array/index.d.mts

@@ -0,0 +1,69 @@
+import { WindowedOptions } from "../../array/windowed.mjs";
+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";
+import { difference } from "./difference.mjs";
+import { differenceBy } from "./differenceBy.mjs";
+import { differenceWith } from "./differenceWith.mjs";
+import { drop } from "./drop.mjs";
+import { dropRight } from "./dropRight.mjs";
+import { dropRightWhile } from "./dropRightWhile.mjs";
+import { dropWhile } from "./dropWhile.mjs";
+import { filter } from "./filter.mjs";
+import { find } from "./find.mjs";
+import { findIndex } from "./findIndex.mjs";
+import { findLast } from "./findLast.mjs";
+import { findLastIndex } from "./findLastIndex.mjs";
+import { flatMap } from "./flatMap.mjs";
+import { flatMapDeep } from "./flatMapDeep.mjs";
+import { flatten } from "./flatten.mjs";
+import { flattenDeep } from "./flattenDeep.mjs";
+import { forEach } from "./forEach.mjs";
+import { groupBy } from "./groupBy.mjs";
+import { head } from "./head.mjs";
+import { initial } from "./initial.mjs";
+import { intersection } from "./intersection.mjs";
+import { intersectionBy } from "./intersectionBy.mjs";
+import { intersectionWith } from "./intersectionWith.mjs";
+import { isSubset } from "./isSubset.mjs";
+import { isSubsetWith } from "./isSubsetWith.mjs";
+import { join } from "./join.mjs";
+import { keyBy } from "./keyBy.mjs";
+import { last } from "./last.mjs";
+import { length } from "./length.mjs";
+import { map } from "./map.mjs";
+import { maxBy } from "./maxBy.mjs";
+import { minBy } from "./minBy.mjs";
+import { orderBy } from "./orderBy.mjs";
+import { partition } from "./partition.mjs";
+import { reverse } from "./reverse.mjs";
+import { sample } from "./sample.mjs";
+import { sampleSize } from "./sampleSize.mjs";
+import { shuffle } from "./shuffle.mjs";
+import { sortBy } from "./sortBy.mjs";
+import { tail } from "./tail.mjs";
+import { take } from "./take.mjs";
+import { takeRight } from "./takeRight.mjs";
+import { takeRightWhile } from "./takeRightWhile.mjs";
+import { takeWhile } from "./takeWhile.mjs";
+import { toFilled } from "./toFilled.mjs";
+import { union } from "./union.mjs";
+import { unionBy } from "./unionBy.mjs";
+import { unionWith } from "./unionWith.mjs";
+import { uniq } from "./uniq.mjs";
+import { uniqBy } from "./uniqBy.mjs";
+import { uniqWith } from "./uniqWith.mjs";
+import { unzip } from "./unzip.mjs";
+import { unzipWith } from "./unzipWith.mjs";
+import { windowed } from "./windowed.mjs";
+import { without } from "./without.mjs";
+import { xor } from "./xor.mjs";
+import { xorBy } from "./xorBy.mjs";
+import { xorWith } from "./xorWith.mjs";
+import { zip } from "./zip.mjs";
+import { zipObject } from "./zipObject.mjs";
+import { zipWith } from "./zipWith.mjs";

package/dist/fp/array/index.d.ts

@@ -0,0 +1,69 @@
+import { WindowedOptions } from "../../array/windowed.js";
+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";
+import { difference } from "./difference.js";
+import { differenceBy } from "./differenceBy.js";
+import { differenceWith } from "./differenceWith.js";
+import { drop } from "./drop.js";
+import { dropRight } from "./dropRight.js";
+import { dropRightWhile } from "./dropRightWhile.js";
+import { dropWhile } from "./dropWhile.js";
+import { filter } from "./filter.js";
+import { find } from "./find.js";
+import { findIndex } from "./findIndex.js";
+import { findLast } from "./findLast.js";
+import { findLastIndex } from "./findLastIndex.js";
+import { flatMap } from "./flatMap.js";
+import { flatMapDeep } from "./flatMapDeep.js";
+import { flatten } from "./flatten.js";
+import { flattenDeep } from "./flattenDeep.js";
+import { forEach } from "./forEach.js";
+import { groupBy } from "./groupBy.js";
+import { head } from "./head.js";
+import { initial } from "./initial.js";
+import { intersection } from "./intersection.js";
+import { intersectionBy } from "./intersectionBy.js";
+import { intersectionWith } from "./intersectionWith.js";
+import { isSubset } from "./isSubset.js";
+import { isSubsetWith } from "./isSubsetWith.js";
+import { join } from "./join.js";
+import { keyBy } from "./keyBy.js";
+import { last } from "./last.js";
+import { length } from "./length.js";
+import { map } from "./map.js";
+import { maxBy } from "./maxBy.js";
+import { minBy } from "./minBy.js";
+import { orderBy } from "./orderBy.js";
+import { partition } from "./partition.js";
+import { reverse } from "./reverse.js";
+import { sample } from "./sample.js";
+import { sampleSize } from "./sampleSize.js";
+import { shuffle } from "./shuffle.js";
+import { sortBy } from "./sortBy.js";
+import { tail } from "./tail.js";
+import { take } from "./take.js";
+import { takeRight } from "./takeRight.js";
+import { takeRightWhile } from "./takeRightWhile.js";
+import { takeWhile } from "./takeWhile.js";
+import { toFilled } from "./toFilled.js";
+import { union } from "./union.js";
+import { unionBy } from "./unionBy.js";
+import { unionWith } from "./unionWith.js";
+import { uniq } from "./uniq.js";
+import { uniqBy } from "./uniqBy.js";
+import { uniqWith } from "./uniqWith.js";
+import { unzip } from "./unzip.js";
+import { unzipWith } from "./unzipWith.js";
+import { windowed } from "./windowed.js";
+import { without } from "./without.js";
+import { xor } from "./xor.js";
+import { xorBy } from "./xorBy.js";
+import { xorWith } from "./xorWith.js";
+import { zip } from "./zip.js";
+import { zipObject } from "./zipObject.js";
+import { zipWith } from "./zipWith.js";

package/dist/fp/array/index.js

@@ -0,0 +1,68 @@
+require("./at.js");
+require("./cartesianProduct.js");
+require("./chunk.js");
+require("./chunkBy.js");
+require("./combinations.js");
+require("./compact.js");
+require("./countBy.js");
+require("./difference.js");
+require("./differenceBy.js");
+require("./differenceWith.js");
+require("./drop.js");
+require("./dropRight.js");
+require("./dropRightWhile.js");
+require("./dropWhile.js");
+require("./filter.js");
+require("./find.js");
+require("./findIndex.js");
+require("./findLast.js");
+require("./findLastIndex.js");
+require("./flatMap.js");
+require("./flatMapDeep.js");
+require("./flatten.js");
+require("./flattenDeep.js");
+require("./forEach.js");
+require("./groupBy.js");
+require("./head.js");
+require("./initial.js");
+require("./intersection.js");
+require("./intersectionBy.js");
+require("./intersectionWith.js");
+require("./isSubset.js");
+require("./isSubsetWith.js");
+require("./join.js");
+require("./keyBy.js");
+require("./last.js");
+require("./length.js");
+require("./map.js");
+require("./maxBy.js");
+require("./minBy.js");
+require("./orderBy.js");
+require("./partition.js");
+require("./reverse.js");
+require("./sample.js");
+require("./sampleSize.js");
+require("./shuffle.js");
+require("./sortBy.js");
+require("./tail.js");
+require("./take.js");
+require("./takeRight.js");
+require("./takeRightWhile.js");
+require("./takeWhile.js");
+require("./toFilled.js");
+require("./union.js");
+require("./unionBy.js");
+require("./unionWith.js");
+require("./uniq.js");
+require("./uniqBy.js");
+require("./uniqWith.js");
+require("./unzip.js");
+require("./unzipWith.js");
+require("./windowed.js");
+require("./without.js");
+require("./xor.js");
+require("./xorBy.js");
+require("./xorWith.js");
+require("./zip.js");
+require("./zipObject.js");
+require("./zipWith.js");

package/dist/fp/array/index.mjs

@@ -0,0 +1,68 @@
+import "./at.mjs";
+import "./cartesianProduct.mjs";
+import "./chunk.mjs";
+import "./chunkBy.mjs";
+import "./combinations.mjs";
+import "./compact.mjs";
+import "./countBy.mjs";
+import "./difference.mjs";
+import "./differenceBy.mjs";
+import "./differenceWith.mjs";
+import "./drop.mjs";
+import "./dropRight.mjs";
+import "./dropRightWhile.mjs";
+import "./dropWhile.mjs";
+import "./filter.mjs";
+import "./find.mjs";
+import "./findIndex.mjs";
+import "./findLast.mjs";
+import "./findLastIndex.mjs";
+import "./flatMap.mjs";
+import "./flatMapDeep.mjs";
+import "./flatten.mjs";
+import "./flattenDeep.mjs";
+import "./forEach.mjs";
+import "./groupBy.mjs";
+import "./head.mjs";
+import "./initial.mjs";
+import "./intersection.mjs";
+import "./intersectionBy.mjs";
+import "./intersectionWith.mjs";
+import "./isSubset.mjs";
+import "./isSubsetWith.mjs";
+import "./join.mjs";
+import "./keyBy.mjs";
+import "./last.mjs";
+import "./length.mjs";
+import "./map.mjs";
+import "./maxBy.mjs";
+import "./minBy.mjs";
+import "./orderBy.mjs";
+import "./partition.mjs";
+import "./reverse.mjs";
+import "./sample.mjs";
+import "./sampleSize.mjs";
+import "./shuffle.mjs";
+import "./sortBy.mjs";
+import "./tail.mjs";
+import "./take.mjs";
+import "./takeRight.mjs";
+import "./takeRightWhile.mjs";
+import "./takeWhile.mjs";
+import "./toFilled.mjs";
+import "./union.mjs";
+import "./unionBy.mjs";
+import "./unionWith.mjs";
+import "./uniq.mjs";
+import "./uniqBy.mjs";
+import "./uniqWith.mjs";
+import "./unzip.mjs";
+import "./unzipWith.mjs";
+import "./windowed.mjs";
+import "./without.mjs";
+import "./xor.mjs";
+import "./xorBy.mjs";
+import "./xorWith.mjs";
+import "./zip.mjs";
+import "./zipObject.mjs";
+import "./zipWith.mjs";

package/dist/fp/array/initial.d.mts

@@ -0,0 +1,19 @@
+//#region src/fp/array/initial.d.ts
+/**
+ * Creates a function that returns every element except the last one.
+ *
+ * The returned function follows the main {@link initial} behavior and always returns a new array.
+ * Use it with {@link pipe}.
+ *
+ * @template T - The type of elements in the array.
+ * @returns A function that maps a readonly array to its initial elements.
+ *
+ * @example
+ * import { initial, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3], initial());
+ * // => [1, 2]
+ */
+declare function initial<T>(): (array: readonly T[]) => T[];
+//#endregion
+export { initial };

package/dist/fp/array/initial.d.ts

@@ -0,0 +1,19 @@
+//#region src/fp/array/initial.d.ts
+/**
+ * Creates a function that returns every element except the last one.
+ *
+ * The returned function follows the main {@link initial} behavior and always returns a new array.
+ * Use it with {@link pipe}.
+ *
+ * @template T - The type of elements in the array.
+ * @returns A function that maps a readonly array to its initial elements.
+ *
+ * @example
+ * import { initial, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3], initial());
+ * // => [1, 2]
+ */
+declare function initial<T>(): (array: readonly T[]) => T[];
+//#endregion
+export { initial };

package/dist/fp/array/initial.js

@@ -0,0 +1,24 @@
+const require_initial = require("../../array/initial.js");
+//#region src/fp/array/initial.ts
+/**
+* Creates a function that returns every element except the last one.
+*
+* The returned function follows the main {@link initial} behavior and always returns a new array.
+* Use it with {@link pipe}.
+*
+* @template T - The type of elements in the array.
+* @returns A function that maps a readonly array to its initial elements.
+*
+* @example
+* import { initial, pipe } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3], initial());
+* // => [1, 2]
+*/
+function initial() {
+	return function(array) {
+		return require_initial.initial(array);
+	};
+}
+//#endregion
+exports.initial = initial;