es-toolkit 1.48.1-dev.1890 → 1.48.1-dev.1894

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

@@ -0,0 +1,19 @@
+//#region src/fp/array/shuffle.d.ts
+/**
+ * Creates a function that returns a shuffled copy of an array.
+ *
+ * The returned function uses the main {@link shuffle} implementation and does not mutate
+ * the input array. Use it with {@link pipe}.
+ *
+ * @template T - The type of elements in the array.
+ * @returns A function that maps a readonly array to a shuffled copy.
+ *
+ * @example
+ * import { pipe, shuffle } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3], shuffle());
+ * // => the same values in random order
+ */
+declare function shuffle<T>(): (array: readonly T[]) => T[];
+//#endregion
+export { shuffle };

package/dist/fp/array/shuffle.js

@@ -0,0 +1,24 @@
+const require_shuffle = require("../../array/shuffle.js");
+//#region src/fp/array/shuffle.ts
+/**
+* Creates a function that returns a shuffled copy of an array.
+*
+* The returned function uses the main {@link shuffle} implementation and does not mutate
+* the input array. Use it with {@link pipe}.
+*
+* @template T - The type of elements in the array.
+* @returns A function that maps a readonly array to a shuffled copy.
+*
+* @example
+* import { pipe, shuffle } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3], shuffle());
+* // => the same values in random order
+*/
+function shuffle() {
+	return function(array) {
+		return require_shuffle.shuffle(array);
+	};
+}
+//#endregion
+exports.shuffle = shuffle;

package/dist/fp/array/shuffle.mjs

@@ -0,0 +1,24 @@
+import { shuffle as shuffle$1 } from "../../array/shuffle.mjs";
+//#region src/fp/array/shuffle.ts
+/**
+* Creates a function that returns a shuffled copy of an array.
+*
+* The returned function uses the main {@link shuffle} implementation and does not mutate
+* the input array. Use it with {@link pipe}.
+*
+* @template T - The type of elements in the array.
+* @returns A function that maps a readonly array to a shuffled copy.
+*
+* @example
+* import { pipe, shuffle } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3], shuffle());
+* // => the same values in random order
+*/
+function shuffle() {
+	return function(array) {
+		return shuffle$1(array);
+	};
+}
+//#endregion
+export { shuffle };

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

@@ -0,0 +1,26 @@
+//#region src/fp/array/sortBy.d.ts
+/**
+ * Creates a function that sorts an array of objects in ascending order by the
+ * given `criteria`. Each criterion is either an object key or a function
+ * returning the value to compare. When two elements tie on a criterion, the
+ * next criterion breaks the tie. The sort is stable. Use it with {@link pipe}.
+ *
+ * @template T - The type of the objects in the array.
+ * @param criteria - Object keys and/or selector functions used for comparison, applied in order.
+ * @returns A function that maps a `readonly T[]` to a new, sorted `T[]`.
+ *
+ * @example
+ * import { pipe, sortBy } from 'es-toolkit/fp';
+ *
+ * const users = [
+ *   { user: 'foo', age: 24 },
+ *   { user: 'bar', age: 7 },
+ *   { user: 'foo', age: 8 },
+ * ];
+ *
+ * pipe(users, sortBy(['user', 'age']));
+ * // => [{ user: 'bar', age: 7 }, { user: 'foo', age: 8 }, { user: 'foo', age: 24 }]
+ */
+declare function sortBy<T extends object>(criteria: Array<((item: T) => unknown) | keyof T>): (array: readonly T[]) => T[];
+//#endregion
+export { sortBy };

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

@@ -0,0 +1,26 @@
+//#region src/fp/array/sortBy.d.ts
+/**
+ * Creates a function that sorts an array of objects in ascending order by the
+ * given `criteria`. Each criterion is either an object key or a function
+ * returning the value to compare. When two elements tie on a criterion, the
+ * next criterion breaks the tie. The sort is stable. Use it with {@link pipe}.
+ *
+ * @template T - The type of the objects in the array.
+ * @param criteria - Object keys and/or selector functions used for comparison, applied in order.
+ * @returns A function that maps a `readonly T[]` to a new, sorted `T[]`.
+ *
+ * @example
+ * import { pipe, sortBy } from 'es-toolkit/fp';
+ *
+ * const users = [
+ *   { user: 'foo', age: 24 },
+ *   { user: 'bar', age: 7 },
+ *   { user: 'foo', age: 8 },
+ * ];
+ *
+ * pipe(users, sortBy(['user', 'age']));
+ * // => [{ user: 'bar', age: 7 }, { user: 'foo', age: 8 }, { user: 'foo', age: 24 }]
+ */
+declare function sortBy<T extends object>(criteria: Array<((item: T) => unknown) | keyof T>): (array: readonly T[]) => T[];
+//#endregion
+export { sortBy };

package/dist/fp/array/sortBy.js

@@ -0,0 +1,31 @@
+const require_sortBy = require("../../array/sortBy.js");
+//#region src/fp/array/sortBy.ts
+/**
+* Creates a function that sorts an array of objects in ascending order by the
+* given `criteria`. Each criterion is either an object key or a function
+* returning the value to compare. When two elements tie on a criterion, the
+* next criterion breaks the tie. The sort is stable. Use it with {@link pipe}.
+*
+* @template T - The type of the objects in the array.
+* @param criteria - Object keys and/or selector functions used for comparison, applied in order.
+* @returns A function that maps a `readonly T[]` to a new, sorted `T[]`.
+*
+* @example
+* import { pipe, sortBy } from 'es-toolkit/fp';
+*
+* const users = [
+*   { user: 'foo', age: 24 },
+*   { user: 'bar', age: 7 },
+*   { user: 'foo', age: 8 },
+* ];
+*
+* pipe(users, sortBy(['user', 'age']));
+* // => [{ user: 'bar', age: 7 }, { user: 'foo', age: 8 }, { user: 'foo', age: 24 }]
+*/
+function sortBy(criteria) {
+	return function(array) {
+		return require_sortBy.sortBy(array, criteria);
+	};
+}
+//#endregion
+exports.sortBy = sortBy;

package/dist/fp/array/sortBy.mjs

@@ -0,0 +1,31 @@
+import { sortBy as sortBy$1 } from "../../array/sortBy.mjs";
+//#region src/fp/array/sortBy.ts
+/**
+* Creates a function that sorts an array of objects in ascending order by the
+* given `criteria`. Each criterion is either an object key or a function
+* returning the value to compare. When two elements tie on a criterion, the
+* next criterion breaks the tie. The sort is stable. Use it with {@link pipe}.
+*
+* @template T - The type of the objects in the array.
+* @param criteria - Object keys and/or selector functions used for comparison, applied in order.
+* @returns A function that maps a `readonly T[]` to a new, sorted `T[]`.
+*
+* @example
+* import { pipe, sortBy } from 'es-toolkit/fp';
+*
+* const users = [
+*   { user: 'foo', age: 24 },
+*   { user: 'bar', age: 7 },
+*   { user: 'foo', age: 8 },
+* ];
+*
+* pipe(users, sortBy(['user', 'age']));
+* // => [{ user: 'bar', age: 7 }, { user: 'foo', age: 8 }, { user: 'foo', age: 24 }]
+*/
+function sortBy(criteria) {
+	return function(array) {
+		return sortBy$1(array, criteria);
+	};
+}
+//#endregion
+export { sortBy };

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

@@ -0,0 +1,19 @@
+//#region src/fp/array/tail.d.ts
+/**
+ * Creates a function that returns every element except the first one.
+ *
+ * Empty and single-element arrays return an empty array, matching the main {@link tail}
+ * 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 tail elements.
+ *
+ * @example
+ * import { pipe, tail } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3], tail());
+ * // => [2, 3]
+ */
+declare function tail<T>(): (array: readonly T[]) => T[];
+//#endregion
+export { tail };

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

@@ -0,0 +1,19 @@
+//#region src/fp/array/tail.d.ts
+/**
+ * Creates a function that returns every element except the first one.
+ *
+ * Empty and single-element arrays return an empty array, matching the main {@link tail}
+ * 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 tail elements.
+ *
+ * @example
+ * import { pipe, tail } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3], tail());
+ * // => [2, 3]
+ */
+declare function tail<T>(): (array: readonly T[]) => T[];
+//#endregion
+export { tail };

package/dist/fp/array/tail.js

@@ -0,0 +1,24 @@
+const require_tail = require("../../array/tail.js");
+//#region src/fp/array/tail.ts
+/**
+* Creates a function that returns every element except the first one.
+*
+* Empty and single-element arrays return an empty array, matching the main {@link tail}
+* 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 tail elements.
+*
+* @example
+* import { pipe, tail } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3], tail());
+* // => [2, 3]
+*/
+function tail() {
+	return function(array) {
+		return require_tail.tail(array);
+	};
+}
+//#endregion
+exports.tail = tail;

package/dist/fp/array/tail.mjs

@@ -0,0 +1,24 @@
+import { tail as tail$1 } from "../../array/tail.mjs";
+//#region src/fp/array/tail.ts
+/**
+* Creates a function that returns every element except the first one.
+*
+* Empty and single-element arrays return an empty array, matching the main {@link tail}
+* 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 tail elements.
+*
+* @example
+* import { pipe, tail } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3], tail());
+* // => [2, 3]
+*/
+function tail() {
+	return function(array) {
+		return tail$1(array);
+	};
+}
+//#endregion
+export { tail };

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

@@ -0,0 +1,26 @@
+//#region src/fp/array/take.d.ts
+/**
+ * Creates a function that returns the first `count` elements of an array. If
+ * `count` is greater than the array length, the whole array is returned. Use it
+ * with {@link pipe}.
+ *
+ * The returned function is **lazy-capable** for a non-negative integer `count`:
+ * inside a {@link pipe} it stops the walk as soon as `count` elements have been
+ * collected, so preceding lazy functions never process the rest of the input.
+ *
+ * @template T - The type of elements in the array.
+ * @param count - The number of elements to take from the front of the array.
+ * @returns A function that maps a `readonly T[]` to a new `T[]`.
+ *
+ * @example
+ * import { pipe, take } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3, 4, 5], take(3)); // => [1, 2, 3]
+ *
+ * @example
+ * // Early termination: `map` only runs three times.
+ * pipe([1, 2, 3, 4, 5], map(expensive), take(3));
+ */
+declare function take<T>(count: number): (array: readonly T[]) => T[];
+//#endregion
+export { take };

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

@@ -0,0 +1,26 @@
+//#region src/fp/array/take.d.ts
+/**
+ * Creates a function that returns the first `count` elements of an array. If
+ * `count` is greater than the array length, the whole array is returned. Use it
+ * with {@link pipe}.
+ *
+ * The returned function is **lazy-capable** for a non-negative integer `count`:
+ * inside a {@link pipe} it stops the walk as soon as `count` elements have been
+ * collected, so preceding lazy functions never process the rest of the input.
+ *
+ * @template T - The type of elements in the array.
+ * @param count - The number of elements to take from the front of the array.
+ * @returns A function that maps a `readonly T[]` to a new `T[]`.
+ *
+ * @example
+ * import { pipe, take } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3, 4, 5], take(3)); // => [1, 2, 3]
+ *
+ * @example
+ * // Early termination: `map` only runs three times.
+ * pipe([1, 2, 3, 4, 5], map(expensive), take(3));
+ */
+declare function take<T>(count: number): (array: readonly T[]) => T[];
+//#endregion
+export { take };

package/dist/fp/array/take.js

@@ -0,0 +1,39 @@
+const require_take = require("../../array/take.js");
+const require_lazy = require("../_internal/lazy.js");
+//#region src/fp/array/take.ts
+/**
+* Creates a function that returns the first `count` elements of an array. If
+* `count` is greater than the array length, the whole array is returned. Use it
+* with {@link pipe}.
+*
+* The returned function is **lazy-capable** for a non-negative integer `count`:
+* inside a {@link pipe} it stops the walk as soon as `count` elements have been
+* collected, so preceding lazy functions never process the rest of the input.
+*
+* @template T - The type of elements in the array.
+* @param count - The number of elements to take from the front of the array.
+* @returns A function that maps a `readonly T[]` to a new `T[]`.
+*
+* @example
+* import { pipe, take } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3, 4, 5], take(3)); // => [1, 2, 3]
+*
+* @example
+* // Early termination: `map` only runs three times.
+* pipe([1, 2, 3, 4, 5], map(expensive), take(3));
+*/
+function take(count) {
+	function takeEager(array) {
+		return require_take.take(array, count);
+	}
+	if (!Number.isInteger(count) || count < 0) return takeEager;
+	const takeLazy = require_lazy.createLazyFunction((value, index, emit) => {
+		if (index >= count) return false;
+		emit(value);
+		return index < count - 1;
+	});
+	return require_lazy.combineEagerAndLazyFunctions(takeEager, takeLazy, { shortCircuit: true });
+}
+//#endregion
+exports.take = take;

package/dist/fp/array/take.mjs

@@ -0,0 +1,38 @@
+import { take as take$1 } from "../../array/take.mjs";
+import { combineEagerAndLazyFunctions, createLazyFunction } from "../_internal/lazy.mjs";
+//#region src/fp/array/take.ts
+/**
+* Creates a function that returns the first `count` elements of an array. If
+* `count` is greater than the array length, the whole array is returned. Use it
+* with {@link pipe}.
+*
+* The returned function is **lazy-capable** for a non-negative integer `count`:
+* inside a {@link pipe} it stops the walk as soon as `count` elements have been
+* collected, so preceding lazy functions never process the rest of the input.
+*
+* @template T - The type of elements in the array.
+* @param count - The number of elements to take from the front of the array.
+* @returns A function that maps a `readonly T[]` to a new `T[]`.
+*
+* @example
+* import { pipe, take } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3, 4, 5], take(3)); // => [1, 2, 3]
+*
+* @example
+* // Early termination: `map` only runs three times.
+* pipe([1, 2, 3, 4, 5], map(expensive), take(3));
+*/
+function take(count) {
+	function takeEager(array) {
+		return take$1(array, count);
+	}
+	if (!Number.isInteger(count) || count < 0) return takeEager;
+	return combineEagerAndLazyFunctions(takeEager, createLazyFunction((value, index, emit) => {
+		if (index >= count) return false;
+		emit(value);
+		return index < count - 1;
+	}), { shortCircuit: true });
+}
+//#endregion
+export { take };

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

@@ -0,0 +1,20 @@
+//#region src/fp/array/takeRight.d.ts
+/**
+ * Creates a function that returns the last count values of an array.
+ *
+ * The returned function follows the main {@link takeRight} behavior and returns a new array.
+ * Use it with {@link pipe}.
+ *
+ * @template T - The type of elements in the array.
+ * @param count - The number of values to take from the end.
+ * @returns A function that maps a readonly array to its suffix.
+ *
+ * @example
+ * import { pipe, takeRight } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3, 4], takeRight(2));
+ * // => [3, 4]
+ */
+declare function takeRight<T>(count: number): (array: readonly T[]) => T[];
+//#endregion
+export { takeRight };

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

@@ -0,0 +1,20 @@
+//#region src/fp/array/takeRight.d.ts
+/**
+ * Creates a function that returns the last count values of an array.
+ *
+ * The returned function follows the main {@link takeRight} behavior and returns a new array.
+ * Use it with {@link pipe}.
+ *
+ * @template T - The type of elements in the array.
+ * @param count - The number of values to take from the end.
+ * @returns A function that maps a readonly array to its suffix.
+ *
+ * @example
+ * import { pipe, takeRight } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3, 4], takeRight(2));
+ * // => [3, 4]
+ */
+declare function takeRight<T>(count: number): (array: readonly T[]) => T[];
+//#endregion
+export { takeRight };

package/dist/fp/array/takeRight.js

@@ -0,0 +1,25 @@
+const require_takeRight = require("../../array/takeRight.js");
+//#region src/fp/array/takeRight.ts
+/**
+* Creates a function that returns the last count values of an array.
+*
+* The returned function follows the main {@link takeRight} behavior and returns a new array.
+* Use it with {@link pipe}.
+*
+* @template T - The type of elements in the array.
+* @param count - The number of values to take from the end.
+* @returns A function that maps a readonly array to its suffix.
+*
+* @example
+* import { pipe, takeRight } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3, 4], takeRight(2));
+* // => [3, 4]
+*/
+function takeRight(count) {
+	return function(array) {
+		return require_takeRight.takeRight(array, count);
+	};
+}
+//#endregion
+exports.takeRight = takeRight;

package/dist/fp/array/takeRight.mjs

@@ -0,0 +1,25 @@
+import { takeRight as takeRight$1 } from "../../array/takeRight.mjs";
+//#region src/fp/array/takeRight.ts
+/**
+* Creates a function that returns the last count values of an array.
+*
+* The returned function follows the main {@link takeRight} behavior and returns a new array.
+* Use it with {@link pipe}.
+*
+* @template T - The type of elements in the array.
+* @param count - The number of values to take from the end.
+* @returns A function that maps a readonly array to its suffix.
+*
+* @example
+* import { pipe, takeRight } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3, 4], takeRight(2));
+* // => [3, 4]
+*/
+function takeRight(count) {
+	return function(array) {
+		return takeRight$1(array, count);
+	};
+}
+//#endregion
+export { takeRight };

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

@@ -0,0 +1,20 @@
+//#region src/fp/array/takeRightWhile.d.ts
+/**
+ * Creates a function that takes trailing values while a predicate returns true.
+ *
+ * The predicate is evaluated from right to left and receives the value, index, and full
+ * input array. Use the returned function with {@link pipe}.
+ *
+ * @template T - The type of elements in the array.
+ * @param predicate - Called with each value, index, and array while taking from the end.
+ * @returns A function that maps a readonly array to the matching suffix.
+ *
+ * @example
+ * import { pipe, takeRightWhile } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3, 4], takeRightWhile(value => value > 2));
+ * // => [3, 4]
+ */
+declare function takeRightWhile<T>(predicate: (element: T, index: number, array: readonly T[]) => boolean): (array: readonly T[]) => T[];
+//#endregion
+export { takeRightWhile };

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

@@ -0,0 +1,20 @@
+//#region src/fp/array/takeRightWhile.d.ts
+/**
+ * Creates a function that takes trailing values while a predicate returns true.
+ *
+ * The predicate is evaluated from right to left and receives the value, index, and full
+ * input array. Use the returned function with {@link pipe}.
+ *
+ * @template T - The type of elements in the array.
+ * @param predicate - Called with each value, index, and array while taking from the end.
+ * @returns A function that maps a readonly array to the matching suffix.
+ *
+ * @example
+ * import { pipe, takeRightWhile } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3, 4], takeRightWhile(value => value > 2));
+ * // => [3, 4]
+ */
+declare function takeRightWhile<T>(predicate: (element: T, index: number, array: readonly T[]) => boolean): (array: readonly T[]) => T[];
+//#endregion
+export { takeRightWhile };

package/dist/fp/array/takeRightWhile.js

@@ -0,0 +1,25 @@
+const require_takeRightWhile = require("../../array/takeRightWhile.js");
+//#region src/fp/array/takeRightWhile.ts
+/**
+* Creates a function that takes trailing values while a predicate returns true.
+*
+* The predicate is evaluated from right to left and receives the value, index, and full
+* input array. Use the returned function with {@link pipe}.
+*
+* @template T - The type of elements in the array.
+* @param predicate - Called with each value, index, and array while taking from the end.
+* @returns A function that maps a readonly array to the matching suffix.
+*
+* @example
+* import { pipe, takeRightWhile } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3, 4], takeRightWhile(value => value > 2));
+* // => [3, 4]
+*/
+function takeRightWhile(predicate) {
+	return function(array) {
+		return require_takeRightWhile.takeRightWhile(array, predicate);
+	};
+}
+//#endregion
+exports.takeRightWhile = takeRightWhile;

package/dist/fp/array/takeRightWhile.mjs

@@ -0,0 +1,25 @@
+import { takeRightWhile as takeRightWhile$1 } from "../../array/takeRightWhile.mjs";
+//#region src/fp/array/takeRightWhile.ts
+/**
+* Creates a function that takes trailing values while a predicate returns true.
+*
+* The predicate is evaluated from right to left and receives the value, index, and full
+* input array. Use the returned function with {@link pipe}.
+*
+* @template T - The type of elements in the array.
+* @param predicate - Called with each value, index, and array while taking from the end.
+* @returns A function that maps a readonly array to the matching suffix.
+*
+* @example
+* import { pipe, takeRightWhile } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3, 4], takeRightWhile(value => value > 2));
+* // => [3, 4]
+*/
+function takeRightWhile(predicate) {
+	return function(array) {
+		return takeRightWhile$1(array, predicate);
+	};
+}
+//#endregion
+export { takeRightWhile };

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

@@ -0,0 +1,21 @@
+//#region src/fp/array/takeWhile.d.ts
+/**
+ * Creates a function that takes leading values while a predicate returns true.
+ *
+ * The returned function is lazy-capable and short-circuiting inside
+ * {@link pipe}; once the predicate returns false, upstream lazy operators stop
+ * processing further input.
+ *
+ * @template T - The type of elements in the array.
+ * @param predicate - Called with each value and index until it returns false.
+ * @returns A function that maps the piped array to the matching prefix.
+ *
+ * @example
+ * import { pipe, takeWhile } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3, 1], takeWhile(value => value < 3));
+ * // => [1, 2]
+ */
+declare function takeWhile<T>(predicate: (element: T, index: number) => boolean): (array: readonly T[]) => T[];
+//#endregion
+export { takeWhile };

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

@@ -0,0 +1,21 @@
+//#region src/fp/array/takeWhile.d.ts
+/**
+ * Creates a function that takes leading values while a predicate returns true.
+ *
+ * The returned function is lazy-capable and short-circuiting inside
+ * {@link pipe}; once the predicate returns false, upstream lazy operators stop
+ * processing further input.
+ *
+ * @template T - The type of elements in the array.
+ * @param predicate - Called with each value and index until it returns false.
+ * @returns A function that maps the piped array to the matching prefix.
+ *
+ * @example
+ * import { pipe, takeWhile } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3, 1], takeWhile(value => value < 3));
+ * // => [1, 2]
+ */
+declare function takeWhile<T>(predicate: (element: T, index: number) => boolean): (array: readonly T[]) => T[];
+//#endregion
+export { takeWhile };