es-toolkit 1.48.1 → 1.49.0

package/dist/fp/array/orderBy.js

@@ -0,0 +1,26 @@
+const require_orderBy = require("../../array/orderBy.js");
+//#region src/fp/array/orderBy.ts
+/**
+* Creates a function that sorts objects by criteria and order directions.
+*
+* Criteria can be object keys or selector functions. The returned function does not mutate
+* the input array; it returns a sorted copy following the main {@link orderBy} behavior.
+*
+* @template T - The object type in the array.
+* @param criteria - Keys or selector functions used for comparison.
+* @param orders - Sort directions corresponding to the criteria.
+* @returns A function that maps a readonly array to a sorted copy.
+*
+* @example
+* import { orderBy, pipe } from 'es-toolkit/fp';
+*
+* pipe([{ name: 'a', age: 2 }, { name: 'b', age: 1 }], orderBy(['age'], ['asc']));
+* // => [{ name: 'b', age: 1 }, { name: 'a', age: 2 }]
+*/
+function orderBy(criteria, orders) {
+	return function(array) {
+		return require_orderBy.orderBy(array, criteria, orders);
+	};
+}
+//#endregion
+exports.orderBy = orderBy;

package/dist/fp/array/orderBy.mjs

@@ -0,0 +1,26 @@
+import { orderBy as orderBy$1 } from "../../array/orderBy.mjs";
+//#region src/fp/array/orderBy.ts
+/**
+* Creates a function that sorts objects by criteria and order directions.
+*
+* Criteria can be object keys or selector functions. The returned function does not mutate
+* the input array; it returns a sorted copy following the main {@link orderBy} behavior.
+*
+* @template T - The object type in the array.
+* @param criteria - Keys or selector functions used for comparison.
+* @param orders - Sort directions corresponding to the criteria.
+* @returns A function that maps a readonly array to a sorted copy.
+*
+* @example
+* import { orderBy, pipe } from 'es-toolkit/fp';
+*
+* pipe([{ name: 'a', age: 2 }, { name: 'b', age: 1 }], orderBy(['age'], ['asc']));
+* // => [{ name: 'b', age: 1 }, { name: 'a', age: 2 }]
+*/
+function orderBy(criteria, orders) {
+	return function(array) {
+		return orderBy$1(array, criteria, orders);
+	};
+}
+//#endregion
+export { orderBy };

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

@@ -0,0 +1,39 @@
+//#region src/fp/array/partition.d.ts
+/**
+ * Creates a function that splits an array with a type-guard predicate.
+ *
+ * Values for which the predicate returns true are placed in the first array and
+ * narrowed to U. The remaining values are placed in the second array as Exclude<T, U>.
+ *
+ * @template T - The type of elements in the array.
+ * @template U - The narrowed element type accepted by the type guard.
+ * @param predicate - Type guard called with each value, index, and array.
+ * @returns A function that maps a readonly array to truthy and falsy partitions.
+ *
+ * @example
+ * import { partition, pipe } from 'es-toolkit/fp';
+ *
+ * const isString = (value: string | number): value is string => typeof value === 'string';
+ * pipe([1, 'a', 2, 'b'], partition(isString));
+ * // => [['a', 'b'], [1, 2]]
+ */
+declare function partition<T, U extends T>(predicate: (value: T, index: number, array: readonly T[]) => value is U): (array: readonly T[]) => [truthy: U[], falsy: Array<Exclude<T, U>>];
+/**
+ * Creates a function that splits an array by a predicate.
+ *
+ * Values for which the predicate returns true are placed in the first array; all
+ * other values are placed in the second array.
+ *
+ * @template T - The type of elements in the array.
+ * @param predicate - Predicate called with each value, index, and array.
+ * @returns A function that maps a readonly array to truthy and falsy partitions.
+ *
+ * @example
+ * import { partition, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3, 4], partition(value => value % 2 === 0));
+ * // => [[2, 4], [1, 3]]
+ */
+declare function partition<T>(predicate: (value: T, index: number, array: readonly T[]) => boolean): (array: readonly T[]) => [truthy: T[], falsy: T[]];
+//#endregion
+export { partition };

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

@@ -0,0 +1,39 @@
+//#region src/fp/array/partition.d.ts
+/**
+ * Creates a function that splits an array with a type-guard predicate.
+ *
+ * Values for which the predicate returns true are placed in the first array and
+ * narrowed to U. The remaining values are placed in the second array as Exclude<T, U>.
+ *
+ * @template T - The type of elements in the array.
+ * @template U - The narrowed element type accepted by the type guard.
+ * @param predicate - Type guard called with each value, index, and array.
+ * @returns A function that maps a readonly array to truthy and falsy partitions.
+ *
+ * @example
+ * import { partition, pipe } from 'es-toolkit/fp';
+ *
+ * const isString = (value: string | number): value is string => typeof value === 'string';
+ * pipe([1, 'a', 2, 'b'], partition(isString));
+ * // => [['a', 'b'], [1, 2]]
+ */
+declare function partition<T, U extends T>(predicate: (value: T, index: number, array: readonly T[]) => value is U): (array: readonly T[]) => [truthy: U[], falsy: Array<Exclude<T, U>>];
+/**
+ * Creates a function that splits an array by a predicate.
+ *
+ * Values for which the predicate returns true are placed in the first array; all
+ * other values are placed in the second array.
+ *
+ * @template T - The type of elements in the array.
+ * @param predicate - Predicate called with each value, index, and array.
+ * @returns A function that maps a readonly array to truthy and falsy partitions.
+ *
+ * @example
+ * import { partition, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3, 4], partition(value => value % 2 === 0));
+ * // => [[2, 4], [1, 3]]
+ */
+declare function partition<T>(predicate: (value: T, index: number, array: readonly T[]) => boolean): (array: readonly T[]) => [truthy: T[], falsy: T[]];
+//#endregion
+export { partition };

package/dist/fp/array/partition.js

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

package/dist/fp/array/partition.mjs

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

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

@@ -0,0 +1,19 @@
+//#region src/fp/array/reverse.d.ts
+/**
+ * Creates a function that returns a reversed copy of an array.
+ *
+ * Unlike Array.prototype.reverse, the returned function 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 reversed copy.
+ *
+ * @example
+ * import { pipe, reverse } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3], reverse());
+ * // => [3, 2, 1]
+ */
+declare function reverse<T>(): (array: readonly T[]) => T[];
+//#endregion
+export { reverse };

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

@@ -0,0 +1,19 @@
+//#region src/fp/array/reverse.d.ts
+/**
+ * Creates a function that returns a reversed copy of an array.
+ *
+ * Unlike Array.prototype.reverse, the returned function 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 reversed copy.
+ *
+ * @example
+ * import { pipe, reverse } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3], reverse());
+ * // => [3, 2, 1]
+ */
+declare function reverse<T>(): (array: readonly T[]) => T[];
+//#endregion
+export { reverse };

package/dist/fp/array/reverse.js

@@ -0,0 +1,23 @@
+//#region src/fp/array/reverse.ts
+/**
+* Creates a function that returns a reversed copy of an array.
+*
+* Unlike Array.prototype.reverse, the returned function 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 reversed copy.
+*
+* @example
+* import { pipe, reverse } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3], reverse());
+* // => [3, 2, 1]
+*/
+function reverse() {
+	return function(array) {
+		return array.slice().reverse();
+	};
+}
+//#endregion
+exports.reverse = reverse;

package/dist/fp/array/reverse.mjs

@@ -0,0 +1,23 @@
+//#region src/fp/array/reverse.ts
+/**
+* Creates a function that returns a reversed copy of an array.
+*
+* Unlike Array.prototype.reverse, the returned function 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 reversed copy.
+*
+* @example
+* import { pipe, reverse } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3], reverse());
+* // => [3, 2, 1]
+*/
+function reverse() {
+	return function(array) {
+		return array.slice().reverse();
+	};
+}
+//#endregion
+export { reverse };

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

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

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

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

package/dist/fp/array/sample.js

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

package/dist/fp/array/sample.mjs

@@ -0,0 +1,23 @@
+import { sample as sample$1 } from "../../array/sample.mjs";
+//#region src/fp/array/sample.ts
+/**
+* Creates a function that returns one random element from an array.
+*
+* The returned function follows the main {@link sample} behavior. Use it with {@link pipe}.
+*
+* @template T - The type of elements in the array.
+* @returns A function that maps a readonly array to a random element.
+*
+* @example
+* import { pipe, sample } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3], sample());
+* // => one of 1, 2, or 3
+*/
+function sample() {
+	return function(array) {
+		return sample$1(array);
+	};
+}
+//#endregion
+export { sample };

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

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

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

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

package/dist/fp/array/sampleSize.js

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

package/dist/fp/array/sampleSize.mjs

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

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

@@ -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.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 };