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

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

@@ -0,0 +1,21 @@
+//#region src/fp/array/isSubsetWith.d.ts
+/**
+ * Creates a predicate that checks subset membership with a custom equality function.
+ *
+ * Every value in the piped array must match at least one value in superset according
+ * to areItemsEqual.
+ *
+ * @template T - The type of elements in the arrays.
+ * @param superset - The array that may contain all values from the piped array.
+ * @param areItemsEqual - Returns true when a piped value and a superset value are equal.
+ * @returns A predicate for the piped array.
+ *
+ * @example
+ * import { isSubsetWith, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([{ id: 1 }], isSubsetWith([{ id: 1 }, { id: 2 }], (a, b) => a.id === b.id));
+ * // => true
+ */
+declare function isSubsetWith<T>(superset: readonly T[], areItemsEqual: (item: T, other: T) => boolean): (array: readonly T[]) => boolean;
+//#endregion
+export { isSubsetWith };

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

@@ -0,0 +1,21 @@
+//#region src/fp/array/isSubsetWith.d.ts
+/**
+ * Creates a predicate that checks subset membership with a custom equality function.
+ *
+ * Every value in the piped array must match at least one value in superset according
+ * to areItemsEqual.
+ *
+ * @template T - The type of elements in the arrays.
+ * @param superset - The array that may contain all values from the piped array.
+ * @param areItemsEqual - Returns true when a piped value and a superset value are equal.
+ * @returns A predicate for the piped array.
+ *
+ * @example
+ * import { isSubsetWith, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([{ id: 1 }], isSubsetWith([{ id: 1 }, { id: 2 }], (a, b) => a.id === b.id));
+ * // => true
+ */
+declare function isSubsetWith<T>(superset: readonly T[], areItemsEqual: (item: T, other: T) => boolean): (array: readonly T[]) => boolean;
+//#endregion
+export { isSubsetWith };

package/dist/fp/array/isSubsetWith.js

@@ -0,0 +1,26 @@
+const require_isSubsetWith = require("../../array/isSubsetWith.js");
+//#region src/fp/array/isSubsetWith.ts
+/**
+* Creates a predicate that checks subset membership with a custom equality function.
+*
+* Every value in the piped array must match at least one value in superset according
+* to areItemsEqual.
+*
+* @template T - The type of elements in the arrays.
+* @param superset - The array that may contain all values from the piped array.
+* @param areItemsEqual - Returns true when a piped value and a superset value are equal.
+* @returns A predicate for the piped array.
+*
+* @example
+* import { isSubsetWith, pipe } from 'es-toolkit/fp';
+*
+* pipe([{ id: 1 }], isSubsetWith([{ id: 1 }, { id: 2 }], (a, b) => a.id === b.id));
+* // => true
+*/
+function isSubsetWith(superset, areItemsEqual) {
+	return function(array) {
+		return require_isSubsetWith.isSubsetWith(superset, array, areItemsEqual);
+	};
+}
+//#endregion
+exports.isSubsetWith = isSubsetWith;

package/dist/fp/array/isSubsetWith.mjs

@@ -0,0 +1,26 @@
+import { isSubsetWith as isSubsetWith$1 } from "../../array/isSubsetWith.mjs";
+//#region src/fp/array/isSubsetWith.ts
+/**
+* Creates a predicate that checks subset membership with a custom equality function.
+*
+* Every value in the piped array must match at least one value in superset according
+* to areItemsEqual.
+*
+* @template T - The type of elements in the arrays.
+* @param superset - The array that may contain all values from the piped array.
+* @param areItemsEqual - Returns true when a piped value and a superset value are equal.
+* @returns A predicate for the piped array.
+*
+* @example
+* import { isSubsetWith, pipe } from 'es-toolkit/fp';
+*
+* pipe([{ id: 1 }], isSubsetWith([{ id: 1 }, { id: 2 }], (a, b) => a.id === b.id));
+* // => true
+*/
+function isSubsetWith(superset, areItemsEqual) {
+	return function(array) {
+		return isSubsetWith$1(superset, array, areItemsEqual);
+	};
+}
+//#endregion
+export { isSubsetWith };

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

@@ -0,0 +1,20 @@
+//#region src/fp/array/join.d.ts
+/**
+ * Creates a function that joins array values into a string.
+ *
+ * The separator is passed to Array.prototype.join, so undefined uses a comma.
+ * Use the returned function with {@link pipe}.
+ *
+ * @template T - The type of elements in the array.
+ * @param separator - The separator placed between values.
+ * @returns A function that maps a readonly array to a joined string.
+ *
+ * @example
+ * import { join, pipe } from 'es-toolkit/fp';
+ *
+ * pipe(['a', 'b', 'c'], join('-'));
+ * // => 'a-b-c'
+ */
+declare function join<T>(separator?: string): (array: readonly T[]) => string;
+//#endregion
+export { join };

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

@@ -0,0 +1,20 @@
+//#region src/fp/array/join.d.ts
+/**
+ * Creates a function that joins array values into a string.
+ *
+ * The separator is passed to Array.prototype.join, so undefined uses a comma.
+ * Use the returned function with {@link pipe}.
+ *
+ * @template T - The type of elements in the array.
+ * @param separator - The separator placed between values.
+ * @returns A function that maps a readonly array to a joined string.
+ *
+ * @example
+ * import { join, pipe } from 'es-toolkit/fp';
+ *
+ * pipe(['a', 'b', 'c'], join('-'));
+ * // => 'a-b-c'
+ */
+declare function join<T>(separator?: string): (array: readonly T[]) => string;
+//#endregion
+export { join };

package/dist/fp/array/join.js

@@ -0,0 +1,24 @@
+//#region src/fp/array/join.ts
+/**
+* Creates a function that joins array values into a string.
+*
+* The separator is passed to Array.prototype.join, so undefined uses a comma.
+* Use the returned function with {@link pipe}.
+*
+* @template T - The type of elements in the array.
+* @param separator - The separator placed between values.
+* @returns A function that maps a readonly array to a joined string.
+*
+* @example
+* import { join, pipe } from 'es-toolkit/fp';
+*
+* pipe(['a', 'b', 'c'], join('-'));
+* // => 'a-b-c'
+*/
+function join(separator) {
+	return function(array) {
+		return array.join(separator);
+	};
+}
+//#endregion
+exports.join = join;

package/dist/fp/array/join.mjs

@@ -0,0 +1,24 @@
+//#region src/fp/array/join.ts
+/**
+* Creates a function that joins array values into a string.
+*
+* The separator is passed to Array.prototype.join, so undefined uses a comma.
+* Use the returned function with {@link pipe}.
+*
+* @template T - The type of elements in the array.
+* @param separator - The separator placed between values.
+* @returns A function that maps a readonly array to a joined string.
+*
+* @example
+* import { join, pipe } from 'es-toolkit/fp';
+*
+* pipe(['a', 'b', 'c'], join('-'));
+* // => 'a-b-c'
+*/
+function join(separator) {
+	return function(array) {
+		return array.join(separator);
+	};
+}
+//#endregion
+export { join };

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

@@ -0,0 +1,21 @@
+//#region src/fp/array/keyBy.d.ts
+/**
+ * Creates a function that indexes values by a derived key.
+ *
+ * The key selector receives each value, index, and full input array. When multiple values
+ * produce the same key, the last value wins, matching the main {@link keyBy} behavior.
+ *
+ * @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 an object key.
+ * @returns A function that maps a readonly array to an object keyed by the derived keys.
+ *
+ * @example
+ * import { keyBy, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([{ id: 'a', value: 1 }, { id: 'b', value: 2 }], keyBy(item => item.id));
+ * // => { a: { id: 'a', value: 1 }, b: { id: 'b', value: 2 } }
+ */
+declare function keyBy<T, K extends PropertyKey>(getKey: (item: T, index: number, array: readonly T[]) => K): (array: readonly T[]) => Record<K, T>;
+//#endregion
+export { keyBy };

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

@@ -0,0 +1,21 @@
+//#region src/fp/array/keyBy.d.ts
+/**
+ * Creates a function that indexes values by a derived key.
+ *
+ * The key selector receives each value, index, and full input array. When multiple values
+ * produce the same key, the last value wins, matching the main {@link keyBy} behavior.
+ *
+ * @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 an object key.
+ * @returns A function that maps a readonly array to an object keyed by the derived keys.
+ *
+ * @example
+ * import { keyBy, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([{ id: 'a', value: 1 }, { id: 'b', value: 2 }], keyBy(item => item.id));
+ * // => { a: { id: 'a', value: 1 }, b: { id: 'b', value: 2 } }
+ */
+declare function keyBy<T, K extends PropertyKey>(getKey: (item: T, index: number, array: readonly T[]) => K): (array: readonly T[]) => Record<K, T>;
+//#endregion
+export { keyBy };

package/dist/fp/array/keyBy.js

@@ -0,0 +1,26 @@
+const require_keyBy = require("../../array/keyBy.js");
+//#region src/fp/array/keyBy.ts
+/**
+* Creates a function that indexes values by a derived key.
+*
+* The key selector receives each value, index, and full input array. When multiple values
+* produce the same key, the last value wins, matching the main {@link keyBy} behavior.
+*
+* @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 an object key.
+* @returns A function that maps a readonly array to an object keyed by the derived keys.
+*
+* @example
+* import { keyBy, pipe } from 'es-toolkit/fp';
+*
+* pipe([{ id: 'a', value: 1 }, { id: 'b', value: 2 }], keyBy(item => item.id));
+* // => { a: { id: 'a', value: 1 }, b: { id: 'b', value: 2 } }
+*/
+function keyBy(getKey) {
+	return function(array) {
+		return require_keyBy.keyBy(array, getKey);
+	};
+}
+//#endregion
+exports.keyBy = keyBy;

package/dist/fp/array/keyBy.mjs

@@ -0,0 +1,26 @@
+import { keyBy as keyBy$1 } from "../../array/keyBy.mjs";
+//#region src/fp/array/keyBy.ts
+/**
+* Creates a function that indexes values by a derived key.
+*
+* The key selector receives each value, index, and full input array. When multiple values
+* produce the same key, the last value wins, matching the main {@link keyBy} behavior.
+*
+* @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 an object key.
+* @returns A function that maps a readonly array to an object keyed by the derived keys.
+*
+* @example
+* import { keyBy, pipe } from 'es-toolkit/fp';
+*
+* pipe([{ id: 'a', value: 1 }, { id: 'b', value: 2 }], keyBy(item => item.id));
+* // => { a: { id: 'a', value: 1 }, b: { id: 'b', value: 2 } }
+*/
+function keyBy(getKey) {
+	return function(array) {
+		return keyBy$1(array, getKey);
+	};
+}
+//#endregion
+export { keyBy };

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

@@ -0,0 +1,35 @@
+//#region src/fp/array/last.d.ts
+/**
+ * Creates a function that returns the last 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 last element.
+ *
+ * @example
+ * import { last, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3] as const, last());
+ * // => 3
+ */
+declare function last<T>(): (array: readonly [...T[], T]) => T;
+/**
+ * Creates a function that returns the last element of an array, or undefined.
+ *
+ * Empty arrays return undefined, matching the main {@link last} 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 last element, or undefined.
+ *
+ * @example
+ * import { last, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([] as number[], last());
+ * // => undefined
+ */
+declare function last<T>(): (array: readonly T[]) => T | undefined;
+//#endregion
+export { last };

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

@@ -0,0 +1,35 @@
+//#region src/fp/array/last.d.ts
+/**
+ * Creates a function that returns the last 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 last element.
+ *
+ * @example
+ * import { last, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3] as const, last());
+ * // => 3
+ */
+declare function last<T>(): (array: readonly [...T[], T]) => T;
+/**
+ * Creates a function that returns the last element of an array, or undefined.
+ *
+ * Empty arrays return undefined, matching the main {@link last} 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 last element, or undefined.
+ *
+ * @example
+ * import { last, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([] as number[], last());
+ * // => undefined
+ */
+declare function last<T>(): (array: readonly T[]) => T | undefined;
+//#endregion
+export { last };

package/dist/fp/array/last.js

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

package/dist/fp/array/last.mjs

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

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

@@ -0,0 +1,18 @@
+//#region src/fp/array/length.d.ts
+/**
+ * Creates a function that returns the length of an array.
+ *
+ * Use it with {@link pipe} when a pipeline should end with the number of input values.
+ *
+ * @template T - The type of elements in the array.
+ * @returns A function that maps a readonly array to its length.
+ *
+ * @example
+ * import { length, pipe } from 'es-toolkit/fp';
+ *
+ * pipe(['a', 'b', 'c'], length());
+ * // => 3
+ */
+declare function length<T>(): (array: readonly T[]) => number;
+//#endregion
+export { length };

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

@@ -0,0 +1,18 @@
+//#region src/fp/array/length.d.ts
+/**
+ * Creates a function that returns the length of an array.
+ *
+ * Use it with {@link pipe} when a pipeline should end with the number of input values.
+ *
+ * @template T - The type of elements in the array.
+ * @returns A function that maps a readonly array to its length.
+ *
+ * @example
+ * import { length, pipe } from 'es-toolkit/fp';
+ *
+ * pipe(['a', 'b', 'c'], length());
+ * // => 3
+ */
+declare function length<T>(): (array: readonly T[]) => number;
+//#endregion
+export { length };

package/dist/fp/array/length.js

@@ -0,0 +1,22 @@
+//#region src/fp/array/length.ts
+/**
+* Creates a function that returns the length of an array.
+*
+* Use it with {@link pipe} when a pipeline should end with the number of input values.
+*
+* @template T - The type of elements in the array.
+* @returns A function that maps a readonly array to its length.
+*
+* @example
+* import { length, pipe } from 'es-toolkit/fp';
+*
+* pipe(['a', 'b', 'c'], length());
+* // => 3
+*/
+function length() {
+	return function(array) {
+		return array.length;
+	};
+}
+//#endregion
+exports.length = length;

package/dist/fp/array/length.mjs

@@ -0,0 +1,22 @@
+//#region src/fp/array/length.ts
+/**
+* Creates a function that returns the length of an array.
+*
+* Use it with {@link pipe} when a pipeline should end with the number of input values.
+*
+* @template T - The type of elements in the array.
+* @returns A function that maps a readonly array to its length.
+*
+* @example
+* import { length, pipe } from 'es-toolkit/fp';
+*
+* pipe(['a', 'b', 'c'], length());
+* // => 3
+*/
+function length() {
+	return function(array) {
+		return array.length;
+	};
+}
+//#endregion
+export { length };

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

@@ -0,0 +1,27 @@
+//#region src/fp/array/map.d.ts
+/**
+ * Creates a function that builds a new array by calling `callback` on every
+ * element, equivalent to `Array.prototype.map`. Use it with {@link pipe}.
+ *
+ * The returned function is **lazy-capable**: inside a {@link pipe} it is fused
+ * with adjacent lazy functions and runs element-by-element, so a trailing
+ * `take` can terminate the walk early without mapping the rest of the input.
+ *
+ * @template T - The type of elements in the input array.
+ * @template U - The type of elements in the output array.
+ * @param callback - Called with `(value, index)` for each element; its return
+ *   value becomes the corresponding element of the output array.
+ * @returns A function that maps a `readonly T[]` to a new `U[]`.
+ *
+ * @example
+ * import { pipe, map } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3], map(x => x * 2)); // => [2, 4, 6]
+ *
+ * @example
+ * // The index is available as the second argument.
+ * pipe([10, 20, 30], map((value, index) => value + index)); // => [10, 21, 32]
+ */
+declare function map<T, U>(callback: (value: T, index: number) => U): (array: readonly T[]) => U[];
+//#endregion
+export { map };

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

@@ -0,0 +1,27 @@
+//#region src/fp/array/map.d.ts
+/**
+ * Creates a function that builds a new array by calling `callback` on every
+ * element, equivalent to `Array.prototype.map`. Use it with {@link pipe}.
+ *
+ * The returned function is **lazy-capable**: inside a {@link pipe} it is fused
+ * with adjacent lazy functions and runs element-by-element, so a trailing
+ * `take` can terminate the walk early without mapping the rest of the input.
+ *
+ * @template T - The type of elements in the input array.
+ * @template U - The type of elements in the output array.
+ * @param callback - Called with `(value, index)` for each element; its return
+ *   value becomes the corresponding element of the output array.
+ * @returns A function that maps a `readonly T[]` to a new `U[]`.
+ *
+ * @example
+ * import { pipe, map } from 'es-toolkit/fp';
+ *
+ * pipe([1, 2, 3], map(x => x * 2)); // => [2, 4, 6]
+ *
+ * @example
+ * // The index is available as the second argument.
+ * pipe([10, 20, 30], map((value, index) => value + index)); // => [10, 21, 32]
+ */
+declare function map<T, U>(callback: (value: T, index: number) => U): (array: readonly T[]) => U[];
+//#endregion
+export { map };

package/dist/fp/array/map.js

@@ -0,0 +1,36 @@
+const require_lazy = require("../_internal/lazy.js");
+//#region src/fp/array/map.ts
+/**
+* Creates a function that builds a new array by calling `callback` on every
+* element, equivalent to `Array.prototype.map`. Use it with {@link pipe}.
+*
+* The returned function is **lazy-capable**: inside a {@link pipe} it is fused
+* with adjacent lazy functions and runs element-by-element, so a trailing
+* `take` can terminate the walk early without mapping the rest of the input.
+*
+* @template T - The type of elements in the input array.
+* @template U - The type of elements in the output array.
+* @param callback - Called with `(value, index)` for each element; its return
+*   value becomes the corresponding element of the output array.
+* @returns A function that maps a `readonly T[]` to a new `U[]`.
+*
+* @example
+* import { pipe, map } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3], map(x => x * 2)); // => [2, 4, 6]
+*
+* @example
+* // The index is available as the second argument.
+* pipe([10, 20, 30], map((value, index) => value + index)); // => [10, 21, 32]
+*/
+function map(callback) {
+	function mapEager(array) {
+		return array.map(callback);
+	}
+	const mapLazy = require_lazy.createLazyFunction((value, index, emit) => {
+		emit(callback(value, index));
+	});
+	return require_lazy.combineEagerAndLazyFunctions(mapEager, mapLazy);
+}
+//#endregion
+exports.map = map;

package/dist/fp/array/map.mjs

@@ -0,0 +1,35 @@
+import { combineEagerAndLazyFunctions, createLazyFunction } from "../_internal/lazy.mjs";
+//#region src/fp/array/map.ts
+/**
+* Creates a function that builds a new array by calling `callback` on every
+* element, equivalent to `Array.prototype.map`. Use it with {@link pipe}.
+*
+* The returned function is **lazy-capable**: inside a {@link pipe} it is fused
+* with adjacent lazy functions and runs element-by-element, so a trailing
+* `take` can terminate the walk early without mapping the rest of the input.
+*
+* @template T - The type of elements in the input array.
+* @template U - The type of elements in the output array.
+* @param callback - Called with `(value, index)` for each element; its return
+*   value becomes the corresponding element of the output array.
+* @returns A function that maps a `readonly T[]` to a new `U[]`.
+*
+* @example
+* import { pipe, map } from 'es-toolkit/fp';
+*
+* pipe([1, 2, 3], map(x => x * 2)); // => [2, 4, 6]
+*
+* @example
+* // The index is available as the second argument.
+* pipe([10, 20, 30], map((value, index) => value + index)); // => [10, 21, 32]
+*/
+function map(callback) {
+	function mapEager(array) {
+		return array.map(callback);
+	}
+	return combineEagerAndLazyFunctions(mapEager, createLazyFunction((value, index, emit) => {
+		emit(callback(value, index));
+	}));
+}
+//#endregion
+export { map };

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

@@ -0,0 +1,37 @@
+//#region src/fp/array/maxBy.d.ts
+/**
+ * Creates a function that returns the element with the maximum selected number from a non-empty array.
+ *
+ * If the selector returns NaN, the element that produced NaN is returned, matching
+ * the main {@link maxBy} behavior.
+ *
+ * @template T - The type of elements in the array.
+ * @param getValue - Selects a numeric value from each element, index, and array.
+ * @returns A function that maps a non-empty readonly array to the maximum element.
+ *
+ * @example
+ * import { maxBy, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([{ score: 10 }, { score: 20 }] as const, maxBy(item => item.score));
+ * // => { score: 20 }
+ */
+declare function maxBy<T>(getValue: (element: T, index: number, array: readonly T[]) => number): (array: readonly [T, ...T[]]) => T;
+/**
+ * Creates a function that returns the element with the maximum selected number.
+ *
+ * Empty arrays return undefined. If the selector returns NaN, the element that
+ * produced NaN is returned, matching the main {@link maxBy} behavior.
+ *
+ * @template T - The type of elements in the array.
+ * @param getValue - Selects a numeric value from each element, index, and array.
+ * @returns A function that maps a readonly array to the maximum element, or undefined.
+ *
+ * @example
+ * import { maxBy, pipe } from 'es-toolkit/fp';
+ *
+ * pipe([] as Array<{ score: number }>, maxBy(item => item.score));
+ * // => undefined
+ */
+declare function maxBy<T>(getValue: (element: T, index: number, array: readonly T[]) => number): (array: readonly T[]) => T | undefined;
+//#endregion
+export { maxBy };