Welcome to the Remeda documentation and API reference. Below, you’ll find the complete reference for all functions exported by Remeda.
Are you using version 1.x.x? Visit our migration guide to help you transition to the latest version.
Adds two numbers.
R.add(value, addend);
R.add(10, 5); // => 15
R.add(10, -5); // => 5
R.reduce([1, 2, 3, 4], R.add, 0); // => 10
R.add(addend)(value);
R.add(5)(10); // => 15
R.add(-5)(10); // => 5
R.map([1, 2, 3, 4], R.add(1)); // => [2, 3, 4, 5]
Rounds up a given number to a specific precision.
If you'd like to round up to an integer (i.e. use this function with constant precision === 0),
use Math.ceil instead, as it won't incur the additional library overhead.
R.ceil(value, precision);
R.ceil(123.9876, 3); // => 123.988
R.ceil(483.22243, 1); // => 483.3
R.ceil(8541, -1); // => 8550
R.ceil(456789, -3); // => 457000
R.ceil(precision)(value);
R.ceil(3)(123.9876); // => 123.988
R.ceil(1)(483.22243); // => 483.3
R.ceil(-1)(8541); // => 8550
R.ceil(-3)(456789); // => 457000
Clamp the given value within the inclusive min and max bounds.
R.clamp(value, { min, max });
clamp(10, { min: 20 }); // => 20
clamp(10, { max: 5 }); // => 5
clamp(10, { max: 20, min: 5 }); // => 10
R.clamp({ min, max })(value);
clamp({ min: 20 })(10); // => 20
clamp({ max: 5 })(10); // => 5
clamp({ max: 20, min: 5 })(10); // => 10
Divides two numbers.
R.divide(value, divisor);
R.divide(12, 3); // => 4
R.reduce([1, 2, 3, 4], R.divide, 24); // => 1
R.divide(divisor)(value);
R.divide(3)(12); // => 4
R.map([2, 4, 6, 8], R.divide(2)); // => [1, 2, 3, 4]
Rounds down a given number to a specific precision.
If you'd like to round down to an integer (i.e. use this function with constant precision === 0),
use Math.floor instead, as it won't incur the additional library overhead.
R.floor(value, precision);
R.floor(123.9876, 3); // => 123.987
R.floor(483.22243, 1); // => 483.2
R.floor(8541, -1); // => 8540
R.floor(456789, -3); // => 456000
R.floor(precision)(value);
R.floor(3)(123.9876); // => 123.987
R.floor(1)(483.22243); // => 483.2
R.floor(-1)(8541); // => 8540
R.floor(-3)(456789); // => 456000
Returns the mean of the elements of an array.
Works for both number and bigint arrays, but not arrays that contain both
types.
IMPORTANT: The result for empty arrays would be undefined, regardless of
the type of the array. This approach improves type-checking and ensures that
cases where NaN might occur are handled properly. To avoid adding this to
the return type for cases where the array is known to be non-empty you can use
hasAtLeast or isEmpty to guard against this case.
R.mean(data);
R.mean([1, 2, 3]); // => 2
R.mean([1n, 2n, 3n]); // => 2n
R.mean([]); // => undefined
R.mean()(data);
R.pipe([1, 2, 3], R.mean()); // => 2
R.pipe([1n, 2n, 3n], R.mean()); // => 2n
R.pipe([], R.mean()); // => undefined
Multiplies two numbers.
R.multiply(value, multiplicand);
R.multiply(3, 4); // => 12
R.reduce([1, 2, 3, 4], R.multiply, 1); // => 24
R.multiply(multiplicand)(value);
R.multiply(4)(3); // => 12
R.map([1, 2, 3, 4], R.multiply(2)); // => [2, 4, 6, 8]
Compute the product of the numbers in the array, or return 1 for an empty array.
Works for both number and bigint arrays, but not arrays that contain both
types.
IMPORTANT: The result for empty arrays would be 1 (number) regardless of
the type of the array; to avoid adding this to the return type for cases
where the array is known to be non-empty you can use hasAtLeast or
isEmpty to guard against this case.
R.product(data);
R.product([1, 2, 3]); // => 6
R.product([1n, 2n, 3n]); // => 6n
R.product([]); // => 1
R.product()(data);
R.pipe([1, 2, 3], R.product()); // => 6
R.pipe([1n, 2n, 3n], R.product()); // => 6n
R.pipe([], R.product()); // => 1
Generate a random bigint between from and to (inclusive).
! Important: In most environments this function uses
crypto.getRandomValues()
under-the-hood which is cryptographically strong. When the WebCrypto API
isn't available (Node 18) we fallback to an implementation that uses
Math.random()
which is NOT cryptographically secure.
R.randomBigInt(from, to);
R.randomBigInt(1n, 10n); // => 5n
Generate a random integer between from and to (inclusive).
!Important: This function uses Math.random() under-the-hood, which has two major limitations:
R.randomInteger(from, to);
R.randomInteger(1, 10); // => 5
R.randomInteger(1.5, 2.6); // => 2
Rounds a given number to a specific precision.
If you'd like to round to an integer (i.e. use this function with constant precision === 0),
use Math.round instead, as it won't incur the additional library overhead.
R.round(value, precision);
R.round(123.9876, 3); // => 123.988
R.round(483.22243, 1); // => 483.2
R.round(8541, -1); // => 8540
R.round(456789, -3); // => 457000
R.round(precision)(value);
R.round(3)(123.9876); // => 123.988
R.round(1)(483.22243); // => 483.2
R.round(-1)(8541); // => 8540
R.round(-3)(456789); // => 457000
Subtracts two numbers.
R.subtract(value, subtrahend);
R.subtract(10, 5); // => 5
R.subtract(10, -5); // => 15
R.reduce([1, 2, 3, 4], R.subtract, 20); // => 10
R.subtract(subtrahend)(value);
R.subtract(5)(10); // => 5
R.subtract(-5)(10); // => 15
R.map([1, 2, 3, 4], R.subtract(1)); // => [0, 1, 2, 3]
Sums the numbers in the array, or return 0 for an empty array.
Works for both number and bigint arrays, but not arrays that contain both
types.
IMPORTANT: The result for empty arrays would be 0 (number) regardless of
the type of the array; to avoid adding this to the return type for cases
where the array is known to be non-empty you can use hasAtLeast or
isEmpty to guard against this case.
R.sum(data);
R.sum([1, 2, 3]); // => 6
R.sum([1n, 2n, 3n]); // => 6n
R.sum([]); // => 0
R.sum()(data);
R.pipe([1, 2, 3], R.sum()); // => 6
R.pipe([1n, 2n, 3n], R.sum()); // => 6n
R.pipe([], R.sum()); // => 0
Add a new property to an object.
The function doesn't do any checks on the input object. If the property already exists it will be overwritten, and the type of the new value is not checked against the previous type.
Use set to override values explicitly with better protections.
R.addProp(obj, prop, value);
R.addProp({ firstName: "john" }, "lastName", "doe"); // => {firstName: 'john', lastName: 'doe'}
R.addProp(prop, value)(obj);
R.addProp("lastName", "doe")({ firstName: "john" }); // => {firstName: 'john', lastName: 'doe'}
Creates a deep copy of the value. Supported types: plain objects,
Array, number, string, boolean, Date, and RegExp. Functions are
assigned by reference rather than copied. Class instances or any other
built-in type that isn't mentioned above are not supported (but might
work).
R.clone(data);
R.clone({ foo: "bar" }); // {foo: 'bar'}
R.clone()(data);
R.pipe({ foo: "bar" }, R.clone()); // {foo: 'bar'}
Returns an array of key/values of the enumerable properties of an object.
R.entries(object);
R.entries({ a: 1, b: 2, c: 3 }); // => [['a', 1], ['b', 2], ['c', 3]]
R.entries()(object);
R.pipe({ a: 1, b: 2, c: 3 }, R.entries()); // => [['a', 1], ['b', 2], ['c', 3]]
Creates a new object by applying functions that is included in evolver object parameter
to the data object parameter according to their corresponding path.
Functions included in evolver object will not be invoked
if its corresponding key does not exist in the data object.
Also, values included in data object will be kept as is
if its corresponding key does not exist in the evolver object.
R.evolve(data, evolver);
const evolver = {
count: add(1),
time: { elapsed: add(1), remaining: add(-1) },
};
const data = {
id: 10,
count: 10,
time: { elapsed: 100, remaining: 1400 },
};
evolve(data, evolver);
// => {
// id: 10,
// count: 11,
// time: { elapsed: 101, remaining: 1399 },
// }
R.evolve(evolver)(data);
const evolver = {
count: add(1),
time: { elapsed: add(1), remaining: add(-1) },
};
const data = {
id: 10,
count: 10,
time: { elapsed: 100, remaining: 1400 },
};
R.pipe(object, R.evolve(evolver));
// => {
// id: 10,
// count: 11,
// time: { elapsed: 101, remaining: 1399 },
// }
Iterate an object using a defined callback function.
The dataLast version returns the original object (instead of not returning
anything (void)) to allow using it in a pipe. The returned object is the
same reference as the input object, and not a shallow copy of it!
R.forEachObj(object, fn);
R.forEachObj({ a: 1 }, (val, key, obj) => {
console.log(`${key}: ${val}`);
}); // "a: 1"
R.forEachObj(fn)(object);
R.pipe(
{ a: 1 },
R.forEachObj((val, key) => console.log(`${key}: ${val}`)),
); // "a: 1"
Creates a new object from an array of tuples by pairing up first and second elements as {[key]: value}. If a tuple is not supplied for any element in the array, the element will be ignored If duplicate keys exist, the tuple with the greatest index in the input array will be preferred.
The strict option supports more sophisticated use-cases like those that would
result when calling the strict toPairs function.
There are several other functions that could be used to build an object from an array:
fromKeys - Builds an object from an array of keys and a mapper for values.indexBy - Builds an object from an array of values and a mapper for keys.pullObject - Builds an object from an array of items with mappers for both keys and values.mapToObj - Builds an object from an array of items and a single mapper for key-value pairs.
Refer to the docs for more details.R.fromEntries(tuples);
R.fromEntries([
["a", "b"],
["c", "d"],
]); // => {a: 'b', c: 'd'}
R.fromEntries()(tuples);
R.pipe(
[
["a", "b"],
["c", "d"],
] as const,
R.fromEntries(),
); // => {a: 'b', c: 'd'}
Creates an object that maps each key in data to the result of mapper for
that key. Duplicate keys are overwritten, guaranteeing that mapper is run
for each item in data.
There are several other functions that could be used to build an object from an array:
indexBy - Builds an object from an array of values and a mapper for keys.pullObject - Builds an object from an array of items with mappers for both keys and values.fromEntries - Builds an object from an array of key-value pairs.mapToObj - Builds an object from an array of items and a single mapper for key-value pairs.
Refer to the docs for more details.R.fromKeys(data, mapper);
R.fromKeys(["cat", "dog"], R.length()); // { cat: 3, dog: 3 } (typed as Partial<Record<"cat" | "dog", number>>)
R.fromKeys([1, 2], R.add(1)); // { 1: 2, 2: 3 } (typed as Partial<Record<1 | 2, number>>)
R.fromKeys(mapper)(data);
R.pipe(["cat", "dog"], R.fromKeys(R.length())); // { cat: 3, dog: 3 } (typed as Partial<Record<"cat" | "dog", number>>)
R.pipe([1, 2], R.fromKeys(R.add(1))); // { 1: 2, 2: 3 } (typed as Partial<Record<1 | 2, number>>)
Returns an object whose keys and values are swapped. If the object contains duplicate values, subsequent values will overwrite previous values.
R.invert(object);
R.invert({ a: "d", b: "e", c: "f" }); // => { d: "a", e: "b", f: "c" }
R.invert()(object);
R.pipe({ a: "d", b: "e", c: "f" }, R.invert()); // => { d: "a", e: "b", f: "c" }
Returns a new array containing the keys of the array or object.
R.keys(source);
R.keys(["x", "y", "z"]); // => ['0', '1', '2']
R.keys({ a: "x", b: "y", 5: "z" }); // => ['a', 'b', '5']
R.keys()(source);
R.Pipe(["x", "y", "z"], keys()); // => ['0', '1', '2']
R.pipe({ a: "x", b: "y", 5: "z" } as const, R.keys()); // => ['a', 'b', '5']
Maps keys of object and keeps the same values.
R.mapKeys(object, fn);
R.mapKeys({ a: 1, b: 2 }, (key, value) => key + value); // => { a1: 1, b2: 2 }
R.mapKeys(fn)(object);
R.pipe(
{ a: 1, b: 2 },
R.mapKeys((key, value) => key + value),
); // => { a1: 1, b2: 2 }
Maps values of object and keeps the same keys. Symbol keys are not passed
to the mapper and will be removed from the output object.
To also copy the symbol keys to the output use merge:
merge(data, mapValues(data, mapper))).
R.mapValues(data, mapper);
R.mapValues({ a: 1, b: 2 }, (value, key) => value + key); // => {a: '1a', b: '2b'}
R.mapValues(mapper)(data);
R.pipe(
{ a: 1, b: 2 },
R.mapValues((value, key) => value + key),
); // => {a: '1a', b: '2b'}
Merges two objects into one by combining their properties, effectively creating a new object that incorporates elements from both. The merge operation prioritizes the second object's properties, allowing them to overwrite those from the first object with the same names.
Equivalent to { ...data, ...source }.
R.merge(data, source);
R.merge({ x: 1, y: 2 }, { y: 10, z: 2 }); // => { x: 1, y: 10, z: 2 }
R.merge(source)(data);
R.pipe({ x: 1, y: 2 }, R.merge({ y: 10, z: 2 })); // => { x: 1, y: 10, z: 2 }
Merges the source object into the destination object. The merge is similar to performing { ...destination, ... source } (where disjoint values from each object would be copied as-is, and for any overlapping props the value from source would be used); But for each prop (p), if both destination and source have a plain-object as a value, the value would be taken as the result of recursively deepMerging them (result.p === deepMerge(destination.p, source.p)).
R.mergeDeep(destination, source);
R.mergeDeep({ foo: "bar", x: 1 }, { foo: "baz", y: 2 }); // => { foo: 'baz', x: 1, y: 2 }
R.mergeDeep(source)(destination);
R.pipe({ foo: "bar", x: 1 }, R.mergeDeep({ foo: "baz", y: 2 })); // => { foo: 'baz', x: 1, y: 2 }
Creates an object containing a single key:value pair.
R.objOf(value, key);
R.objOf(10, "a"); // => { a: 10 }
R.objOf(key)(value);
R.pipe(10, R.objOf("a")); // => { a: 10 }
Returns a partial copy of an object omitting the keys specified.
R.omit(names)(obj);
R.pipe({ a: 1, b: 2, c: 3, d: 4 }, R.omit(["a", "d"])); // => { b: 2, c: 3 }
R.omit(obj, names);
R.omit({ a: 1, b: 2, c: 3, d: 4 }, ["a", "d"]); // => { b: 2, c: 3 }
Creates a shallow copy of the data, and then removes any keys that the predicate rejects. Symbol keys are not passed to the predicate and would be passed through to the output as-is.
See pickBy for a complementary function which starts with an empty object
and adds the entries that the predicate accepts. Because it is additive,
symbol keys will not be passed through to the output object.
R.omitBy(data, predicate);
R.omitBy({ a: 1, b: 2, A: 3, B: 4 }, (val, key) => key.toUpperCase() === key); // => {a: 1, b: 2}
R.omitBy(fn)(object);
R.omitBy((val, key) => key.toUpperCase() === key)({ a: 1, b: 2, A: 3, B: 4 }); // => {a: 1, b: 2}
Gets the value at path of object. If the resolved value is null or undefined, the defaultValue is returned in its place.
R.pathOr(object, array, defaultValue);
R.pathOr({ x: 10 }, ["y"], 2); // 2
R.pathOr({ y: 10 }, ["y"], 2); // 10
R.pathOr(array, defaultValue)(object);
R.pipe({ x: 10 }, R.pathOr(["y"], 2)); // 2
R.pipe({ y: 10 }, R.pathOr(["y"], 2)); // 10
Creates an object composed of the picked object properties.
R.pick([prop1, prop2])(object);
R.pipe({ a: 1, b: 2, c: 3, d: 4 }, R.pick(["a", "d"])); // => { a: 1, d: 4 }
R.pick(object, [prop1, prop2]);
R.pick({ a: 1, b: 2, c: 3, d: 4 }, ["a", "d"]); // => { a: 1, d: 4 }
Iterates over the entries of data and reconstructs the object using only
entries that predicate accepts. Symbol keys are not passed to the predicate
and would be filtered out from the output object.
See omitBy for a complementary function which starts with a shallow copy of
the input object and removes the entries that the predicate rejects. Because
it is subtractive symbol keys would be copied over to the output object.
See also entries, filter, and fromEntries which could be used to build
your own version of pickBy if you need more control (though the resulting
type might be less precise).
R.pickBy(data, predicate);
R.pickBy({ a: 1, b: 2, A: 3, B: 4 }, (val, key) => key.toUpperCase() === key); // => {A: 3, B: 4}
R.pickBy(predicate)(data);
R.pipe(
{ a: 1, b: 2, A: 3, B: 4 },
pickBy((val, key) => key.toUpperCase() === key),
); // => {A: 3, B: 4}
Gets the value of the given property.
R.prop(data, key);
R.prop({ foo: "bar" }, "foo"); // => 'bar'
R.prop(key)(data);
R.pipe({ foo: "bar" }, R.prop("foo")); // => 'bar'
Creates an object that maps the result of valueExtractor with a key
resulting from running keyExtractor on each item in data. Duplicate keys
are overwritten, guaranteeing that the extractor functions are run on each
item in data.
There are several other functions that could be used to build an object from an array:
fromKeys - Builds an object from an array of keys and a mapper for values.indexBy - Builds an object from an array of values and a mapper for keys.fromEntries - Builds an object from an array of key-value pairs.mapToObj - Builds an object from an array of items and a single mapper for key-value pairs.
Refer to the docs for more details.R.pullObject(data, keyExtractor, valueExtractor);
R.pullObject(
[
{ name: "john", email: "john@remedajs.com" },
{ name: "jane", email: "jane@remedajs.com" },
],
R.prop("name"),
R.prop("email"),
); // => { john: "john@remedajs.com", jane: "jane@remedajs.com" }
R.pullObject(keyExtractor, valueExtractor)(data);
R.pipe(
[
{ name: "john", email: "john@remedajs.com" },
{ name: "jane", email: "jane@remedajs.com" },
],
R.pullObject(R.prop("email"), R.prop("name")),
); // => { john: "john@remedajs.com", jane: "jane@remedajs.com" }
Sets the value at prop of object.
To add a new property to an object, or to override its type, use addProp
instead, and to set a property within a nested object use setPath.
R.set(obj, prop, value);
R.set({ a: 1 }, "a", 2); // => { a: 2 }
R.set(prop, value)(obj);
R.pipe({ a: 1 }, R.set("a", 2)); // => { a: 2 }
Sets the value at path of object.
For simple cases where the path is only one level deep, prefer set instead.
R.setPath(obj, path, value);
R.setPath({ a: { b: 1 } }, ["a", "b"], 2); // => { a: { b: 2 } }
R.setPath(path, value)(obj);
R.pipe({ a: { b: 1 } }, R.setPath(["a", "b"], 2)); // { a: { b: 2 } }
Swaps the positions of two properties in an object based on the provided keys.
swap(data, key1, key2);
swap({ a: 1, b: 2, c: 3 }, "a", "b"); // => {a: 2, b: 1, c: 3}
swap(key1, key2)(data);
swap("a", "b")({ a: 1, b: 2, c: 3 }); // => {a: 2, b: 1, c: 3}
Returns a new array containing the values of the array or object.
R.values(source);
R.values(["x", "y", "z"]); // => ['x', 'y', 'z']
R.values({ a: "x", b: "y", c: "z" }); // => ['x', 'y', 'z']
R.values()(source);
R.pipe(["x", "y", "z"], R.values()); // => ['x', 'y', 'z']
R.pipe({ a: "x", b: "y", c: "z" }, R.values()); // => ['x', 'y', 'z']
R.pipe({ a: "x", b: "y", c: "z" }, R.values(), R.first()); // => 'x'
Determines whether all predicates returns true for the input data.
R.allPass(data, fns);
const isDivisibleBy3 = (x: number) => x % 3 === 0;
const isDivisibleBy4 = (x: number) => x % 4 === 0;
const fns = [isDivisibleBy3, isDivisibleBy4];
R.allPass(12, fns); // => true
R.allPass(8, fns); // => false
R.allPass(fns)(data);
const isDivisibleBy3 = (x: number) => x % 3 === 0;
const isDivisibleBy4 = (x: number) => x % 4 === 0;
const fns = [isDivisibleBy3, isDivisibleBy4];
R.allPass(fns)(12); // => true
R.allPass(fns)(8); // => false
Determines whether any predicate returns true for the input data.
R.anyPass(data, fns);
const isDivisibleBy3 = (x: number) => x % 3 === 0;
const isDivisibleBy4 = (x: number) => x % 4 === 0;
const fns = [isDivisibleBy3, isDivisibleBy4];
R.anyPass(8, fns); // => true
R.anyPass(11, fns); // => false
R.anyPass(fns)(data);
const isDivisibleBy3 = (x: number) => x % 3 === 0;
const isDivisibleBy4 = (x: number) => x % 4 === 0;
const fns = [isDivisibleBy3, isDivisibleBy4];
R.anyPass(fns)(8); // => true
R.anyPass(fns)(11); // => false
Split an array into groups the length of size. If array can't be split evenly, the final chunk will be the remaining elements.
R.chunk(array, size);
R.chunk(["a", "b", "c", "d"], 2); // => [['a', 'b'], ['c', 'd']]
R.chunk(["a", "b", "c", "d"], 3); // => [['a', 'b', 'c'], ['d']]
R.chunk(size)(array);
R.chunk(2)(["a", "b", "c", "d"]); // => [['a', 'b'], ['c', 'd']]
R.chunk(3)(["a", "b", "c", "d"]); // => [['a', 'b', 'c'], ['d']]
Merge two or more arrays. This method does not change the existing arrays, but instead returns a new array, even if the other array is empty.
R.concat(data, other);
R.concat([1, 2, 3], ["a"]); // [1, 2, 3, 'a']
R.concat(arr2)(arr1);
R.concat(["a"])([1, 2, 3]); // [1, 2, 3, 'a']
Excludes the values from other array. The output maintains the same order
as the input. The inputs are treated as multi-sets/bags (multiple copies of
items are treated as unique items).
R.difference(data, other);
R.difference([1, 2, 3, 4], [2, 5, 3]); // => [1, 4]
R.difference([1, 1, 2, 2], [1]); // => [1, 2, 2]
R.difference(other)(data);
R.pipe([1, 2, 3, 4], R.difference([2, 5, 3])); // => [1, 4]
R.pipe([1, 1, 2, 2], R.difference([1])); // => [1, 2, 2]
Excludes the values from other array.
Elements are compared by custom comparator isEquals.
R.differenceWith(array, other, isEquals);
R.differenceWith(
[{ a: 1 }, { a: 2 }, { a: 3 }, { a: 4 }],
[{ a: 2 }, { a: 5 }, { a: 3 }],
R.equals,
); // => [{a: 1}, {a: 4}]
R.differenceWith(other, isEquals)(array);
R.differenceWith(
[{ a: 2 }, { a: 5 }, { a: 3 }],
R.equals,
)([{ a: 1 }, { a: 2 }, { a: 3 }, { a: 4 }]); // => [{a: 1}, {a: 4}]
R.pipe(
[{ a: 1 }, { a: 2 }, { a: 3 }, { a: 4 }, { a: 5 }, { a: 6 }], // only 4 iterations
R.differenceWith([{ a: 2 }, { a: 3 }], R.equals),
R.take(2),
); // => [{a: 1}, {a: 4}]
Removes first n elements from the array.
R.drop(array, n);
R.drop([1, 2, 3, 4, 5], 2); // => [3, 4, 5]
R.drop(n)(array);
R.drop(2)([1, 2, 3, 4, 5]); // => [3, 4, 5]
Drop the first n items from data based on the provided ordering criteria. This allows you to avoid sorting the array before dropping the items. The complexity of this function is O(Nlogn) where N is the length of the array.
For the opposite operation (to keep n elements) see takeFirstBy.
R.dropFirstBy(data, n, ...rules);
R.dropFirstBy(["aa", "aaaa", "a", "aaa"], 2, (x) => x.length); // => ['aaa', 'aaaa']
R.dropFirstBy(n, ...rules)(data);
R.pipe(
["aa", "aaaa", "a", "aaa"],
R.dropFirstBy(2, (x) => x.length),
); // => ['aaa', 'aaaa']
Removes last n elements from the array.
R.dropLast(array, n);
R.dropLast([1, 2, 3, 4, 5], 2); // => [1, 2, 3]
R.dropLast(n)(array);
R.dropLast(2)([1, 2, 3, 4, 5]); // => [1, 2, 3]
Removes elements from the end of the array until the predicate returns false.
The predicate is applied to each element in the array starting from the end and moving towards the beginning, until the predicate returns false. The returned array includes elements from the beginning of the array, up to and including the element that produced false for the predicate.
R.dropLastWhile(data, predicate);
R.dropLastWhile([1, 2, 10, 3, 4], (x) => x < 10); // => [1, 2, 10]
R.dropLastWhile(predicate)(data);
R.pipe(
[1, 2, 10, 3, 4],
R.dropLastWhile((x) => x < 10),
); // => [1, 2, 10]
Removes elements from the beginning of the array until the predicate returns false.
The predicate is applied to each element in the array, until the predicate returns false. The returned array includes the rest of the elements, starting with the element that produced false for the predicate.
R.dropWhile(data, predicate);
R.dropWhile([1, 2, 10, 3, 4], (x) => x < 10); // => [10, 3, 4]
R.dropWhile(predicate)(data);
R.pipe(
[1, 2, 10, 3, 4],
R.dropWhile((x) => x < 10),
); // => [10, 3, 4]
Creates a shallow copy of a portion of a given array, filtered down to just
the elements from the given array that pass the test implemented by the
provided function. Equivalent to Array.prototype.filter.
R.filter(data, predicate);
R.filter([1, 2, 3], (x) => x % 2 === 1); // => [1, 3]
R.filter(predicate)(data);
R.pipe(
[1, 2, 3],
R.filter((x) => x % 2 === 1),
); // => [1, 3]
Returns the first element in the provided array that satisfies the provided
testing function. If no values satisfy the testing function, undefined is
returned.
Similar functions:
findLast - If you need the last element that satisfies the provided testing function.findIndex - If you need the index of the found element in the array.indexOf - If you need to find the index of a value.includes - If you need to find if a value exists in an array.some - If you need to find if any element satisfies the provided testing function.filter - If you need to find all elements that satisfy the provided testing function.R.find(data, predicate);
R.find([1, 3, 4, 6], (n) => n % 2 === 0); // => 4
R.find(predicate)(data);
R.pipe(
[1, 3, 4, 6],
R.find((n) => n % 2 === 0),
); // => 4
Returns the index of the first element in an array that satisfies the provided testing function. If no elements satisfy the testing function, -1 is returned.
See also the find method, which returns the first element that satisfies
the testing function (rather than its index).
R.findIndex(data, predicate);
R.findIndex([1, 3, 4, 6], (n) => n % 2 === 0); // => 2
R.findIndex(predicate)(data);
R.pipe(
[1, 3, 4, 6],
R.findIndex((n) => n % 2 === 0),
); // => 2
Iterates the array in reverse order and returns the value of the first element that satisfies the provided testing function. If no elements satisfy the testing function, undefined is returned.
Similar functions:
find - If you need the first element that satisfies the provided testing function.findLastIndex - If you need the index of the found element in the array.lastIndexOf - If you need to find the index of a value.includes - If you need to find if a value exists in an array.some - If you need to find if any element satisfies the provided testing function.filter - If you need to find all elements that satisfy the provided testing function.R.findLast(data, predicate);
R.findLast([1, 3, 4, 6], (n) => n % 2 === 1); // => 3
R.findLast(predicate)(data);
R.pipe(
[1, 3, 4, 6],
R.findLast((n) => n % 2 === 1),
); // => 3
Iterates the array in reverse order and returns the index of the first element that satisfies the provided testing function. If no elements satisfy the testing function, -1 is returned.
See also findLast which returns the value of last element that satisfies
the testing function (rather than its index).
R.findLastIndex(data, predicate);
R.findLastIndex([1, 3, 4, 6], (n) => n % 2 === 1); // => 1
R.findLastIndex(fn)(items);
R.pipe(
[1, 3, 4, 6],
R.findLastIndex((n) => n % 2 === 1),
); // => 1
Gets the first element of array.
R.first(array);
R.first([1, 2, 3]); // => 1
R.first([]); // => undefined
R.first()(array);
R.pipe(
[1, 2, 4, 8, 16],
R.filter((x) => x > 3),
R.first(),
(x) => x + 1,
); // => 5
Find the first element in the array that adheres to the order rules provided. This is a superset of what a typical maxBy or minBy function would do as it allows defining "tie-breaker" rules when values are equal, and allows comparing items using any logic. This function is equivalent to calling R.first(R.sortBy(...)) but runs at O(n) instead of O(nlogn).
Use nthBy if you need an element other that the first, or takeFirstBy if you more than just the first element.
R.firstBy(...rules)(data);
const max = R.pipe([1, 2, 3], R.firstBy([R.identity(), "desc"])); // => 3;
const min = R.pipe([1, 2, 3], R.firstBy(R.identity())); // => 1;
const data = [{ a: "a" }, { a: "aa" }, { a: "aaa" }] as const;
const maxBy = R.pipe(data, R.firstBy([(item) => item.a.length, "desc"])); // => { a: "aaa" };
const minBy = R.pipe(
data,
R.firstBy((item) => item.a.length),
); // => { a: "a" };
const data = [
{ type: "cat", size: 1 },
{ type: "cat", size: 2 },
{ type: "dog", size: 3 },
] as const;
const multi = R.pipe(data, R.firstBy(R.prop("type"), [R.prop("size"), "desc"])); // => {type: "cat", size: 2}
R.firstBy(data, ...rules);
const max = R.firstBy([1, 2, 3], [R.identity(), "desc"]); // => 3;
const min = R.firstBy([1, 2, 3], R.identity()); // => 1;
const data = [{ a: "a" }, { a: "aa" }, { a: "aaa" }] as const;
const maxBy = R.firstBy(data, [(item) => item.a.length, "desc"]); // => { a: "aaa" };
const minBy = R.firstBy(data, (item) => item.a.length); // => { a: "a" };
const data = [
{ type: "cat", size: 1 },
{ type: "cat", size: 2 },
{ type: "dog", size: 3 },
] as const;
const multi = R.firstBy(data, R.prop("type"), [R.prop("size"), "desc"]); // => {type: "cat", size: 2}
Creates a new array with all sub-array elements concatenated into it
recursively up to the specified depth. Equivalent to the built-in
Array.prototype.flat method.
R.flat(data);
R.flat(data, depth);
R.flat([[1, 2], [3, 4], [5], [[6]]]); // => [1, 2, 3, 4, 5, [6]]
R.flat([[[1]], [[2]]], 2); // => [1, 2]
R.flat()(data);
R.flat(depth)(data);
R.pipe([[1, 2], [3, 4], [5], [[6]]], R.flat()); // => [1, 2, 3, 4, 5, [6]]
R.pipe([[[1]], [[2]]], R.flat(2)); // => [1, 2]
Returns a new array formed by applying a given callback function to each
element of the array, and then flattening the result by one level. It is
identical to a map followed by a flat of depth 1
(flat(map(data, ...args))), but slightly more efficient than calling those
two methods separately. Equivalent to Array.prototype.flatMap.
R.flatMap(data, callbackfn);
R.flatMap([1, 2, 3], (x) => [x, x * 10]); // => [1, 10, 2, 20, 3, 30]
R.flatMap(callbackfn)(data);
R.pipe(
[1, 2, 3],
R.flatMap((x) => [x, x * 10]),
); // => [1, 10, 2, 20, 3, 30]
Executes a provided function once for each array element. Equivalent to
Array.prototype.forEach.
The dataLast version returns the original array (instead of not returning
anything (void)) to allow using it in a pipe. When not used in a pipe the
returned array is equal to the input array (by reference), and not a shallow
copy of it!
R.forEach(data, callbackfn);
R.forEach([1, 2, 3], (x) => {
console.log(x);
});
R.forEach(callbackfn)(data);
R.pipe(
[1, 2, 3],
R.forEach((x) => {
console.log(x);
}),
); // => [1, 2, 3]
Groups the elements of a given iterable according to the string values
returned by a provided callback function. The returned object has separate
properties for each group, containing arrays with the elements in the group.
Unlike the built in Object.groupBy this function also allows the callback to
return undefined in order to exclude the item from being added to any
group.
R.groupBy(data, callbackfn);
R.groupBy([{ a: "cat" }, { a: "dog" }] as const, R.prop("a")); // => {cat: [{a: 'cat'}], dog: [{a: 'dog'}]}
R.groupBy([0, 1], (x) => (x % 2 === 0 ? "even" : undefined)); // => {even: [0]}
R.groupBy(callbackfn)(data);
R.pipe([{ a: "cat" }, { a: "dog" }] as const, R.groupBy(R.prop("a"))); // => {cat: [{a: 'cat'}], dog: [{a: 'dog'}]}
R.pipe(
[0, 1],
R.groupBy((x) => (x % 2 === 0 ? "even" : undefined)),
); // => {even: [0]}
Checks if the given array has at least the defined number of elements. When
the minimum used is a literal (e.g. 3) the output is refined accordingly so
that those indices are defined when accessing the array even when using
typescript's 'noUncheckedIndexAccess'.
R.hasAtLeast(data, minimum);
R.hasAtLeast([], 4); // => false
const data: number[] = [1, 2, 3, 4];
R.hasAtLeast(data, 1); // => true
data[0]; // 1, with type `number`
R.hasAtLeast(minimum)(data);
R.pipe([], R.hasAtLeast(4)); // => false
const data = [[1, 2], [3], [4, 5]];
R.pipe(
data,
R.filter(R.hasAtLeast(2)),
R.map(([, second]) => second),
); // => [2,5], with type `number[]`
Converts a list of objects into an object indexing the objects by the given key.
There are several other functions that could be used to build an object from an array:
fromKeys - Builds an object from an array of keys and a mapper for values.pullObject - Builds an object from an array of items with mappers for both keys and values.fromEntries - Builds an object from an array of key-value pairs.mapToObj - Builds an object from an array of items and a single mapper for key-value pairs.
Refer to the docs for more details.R.indexBy(array, fn);
R.indexBy(["one", "two", "three"], (x) => x.length); // => {3: 'two', 5: 'three'}
R.indexBy(fn)(array);
R.pipe(
["one", "two", "three"],
R.indexBy((x) => x.length),
); // => {3: 'two', 5: 'three'}
Returns a list of elements that exist in both array. The output maintains the same order as the input. The inputs are treated as multi-sets/bags (multiple copies of items are treated as unique items).
R.intersection(data, other);
R.intersection([1, 2, 3], [2, 3, 5]); // => [2, 3]
R.intersection([1, 1, 2, 2], [1]); // => [1]
R.intersection(other)(data);
R.pipe([1, 2, 3], R.intersection([2, 3, 5])); // => [2, 3]
R.pipe([1, 1, 2, 2], R.intersection([1])); // => [1]
Returns a list of intersecting values based on a custom comparator function that compares elements of both arrays.
R.intersectionWith(array, other, comparator);
R.intersectionWith(
[
{ id: 1, name: "Ryan" },
{ id: 3, name: "Emma" },
],
[3, 5],
(a, b) => a.id === b,
); // => [{ id: 3, name: 'Emma' }]
R.intersectionWith(other, comparator)(array);
R.intersectionWith(
[3, 5],
(a, b) => a.id === b,
)([
{ id: 1, name: "Ryan" },
{ id: 3, name: "Emma" },
]); // => [{ id: 3, name: 'Emma' }]
Joins the elements of the array by: casting them to a string and concatenating them one to the other, with the provided glue string in between every two elements.
When called on a tuple and with stricter item types (union of literal values, the result is strictly typed to the tuples shape and it's item types).
R.join(data, glue);
R.join([1, 2, 3], ","); // => "1,2,3" (typed `string`)
R.join(["a", "b", "c"], ""); // => "abc" (typed `string`)
R.join(["hello", "world"] as const, " "); // => "hello world" (typed `hello world`)
R.join(glue)(data);
R.pipe([1, 2, 3], R.join(",")); // => "1,2,3" (typed `string`)
R.pipe(["a", "b", "c"], R.join("")); // => "abc" (typed `string`)
R.pipe(["hello", "world"] as const, R.join(" ")); // => "hello world" (typed `hello world`)
Gets the last element of array.
R.last(array);
R.last([1, 2, 3]); // => 3
R.last([]); // => undefined
R.last()(array);
R.pipe(
[1, 2, 4, 8, 16],
R.filter((x) => x > 3),
R.last(),
(x) => x + 1,
); // => 17
Counts values of the collection or iterable.
R.length(array);
R.length([1, 2, 3]); // => 3
R.length()(array);
R.pipe([1, 2, 3], R.length()); // => 3
Creates a new array populated with the results of calling a provided function
on every element in the calling array. Equivalent to Array.prototype.map.
R.map(data, callbackfn);
R.map([1, 2, 3], R.multiply(2)); // => [2, 4, 6]
R.map([0, 0], R.add(1)); // => [1, 1]
R.map([0, 0], (value, index) => value + index); // => [0, 1]
R.map(callbackfn)(data);
R.pipe([1, 2, 3], R.map(R.multiply(2))); // => [2, 4, 6]
R.pipe([0, 0], R.map(R.add(1))); // => [1, 1]
R.pipe(
[0, 0],
R.map((value, index) => value + index),
); // => [0, 1]
Map each element of an array into an object using a defined callback function.
There are several other functions that could be used to build an object from an array:
fromKeys - Builds an object from an array of keys and a mapper for values.indexBy - Builds an object from an array of values and a mapper for keys.pullObject - Builds an object from an array of items with mappers for both keys and values.fromEntries - Builds an object from an array of key-value pairs.
Refer to the docs for more details.R.mapToObj(array, fn);
R.mapToObj([1, 2, 3], (x) => [String(x), x * 2]); // => {1: 2, 2: 4, 3: 6}
R.mapToObj(fn)(array);
R.pipe(
[1, 2, 3],
R.mapToObj((x) => [String(x), x * 2]),
); // => {1: 2, 2: 4, 3: 6}
Applies a function on each element of the array, using the result of the previous application, and returns an array of the successively computed values.
R.mapWithFeedback(data, callbackfn, initialValue);
R.mapWithFeedback([1, 2, 3, 4, 5], (prev, x) => prev + x, 100); // => [101, 103, 106, 110, 115]
R.mapWithFeedback(callbackfn, initialValue)(data);
R.pipe(
[1, 2, 3, 4, 5],
R.mapWithFeedback((prev, x) => prev + x, 100),
); // => [101, 103, 106, 110, 115]
Returns the mean of the elements of an array using the provided predicate.
R.meanBy(fn)(array);
R.pipe(
[{ a: 5 }, { a: 1 }, { a: 3 }],
R.meanBy((x) => x.a),
); // 3
R.meanBy(array, fn);
R.meanBy([{ a: 5 }, { a: 1 }, { a: 3 }], (x) => x.a); // 3
Merges a list of objects into a single object.
R.mergeAll(objects);
R.mergeAll([{ a: 1, b: 1 }, { b: 2, c: 3 }, { d: 10 }]); // => { a: 1, b: 2, c: 3, d: 10 }
Retrieves the element that would be at the given index if the array were sorted according to specified rules. This function uses the QuickSelect algorithm running at an average complexity of O(n). Semantically it is equivalent to sortBy(data, ...rules).at(index) which would run at O(nlogn).
See also firstBy which provides an even more efficient algorithm and a stricter return type, but only for index === 0. See takeFirstBy to get all the elements up to and including index.
R.nthBy(data, index, ...rules);
R.nthBy([2, 1, 4, 5, 3], 2, identity()); // => 3
R.nthBy(index, ...rules)(data);
R.pipe([2, 1, 4, 5, 3], R.nthBy(2, identity())); // => 3
Returns the first and only element of array, or undefined otherwise.
R.only(array);
R.only([]); // => undefined
R.only([1]); // => 1
R.only([1, 2]); // => undefined
R.only()(array);
R.pipe([], R.only()); // => undefined
R.pipe([1], R.only()); // => 1
R.pipe([1, 2], R.only()); // => undefined
Splits a collection into two groups, the first of which contains elements the
predicate type guard passes, and the second one containing the rest.
R.partition(data, predicate);
R.partition(["one", "two", "forty two"], (x) => x.length === 3); // => [['one', 'two'], ['forty two']]
R.partition(predicate)(data);
R.pipe(
["one", "two", "forty two"],
R.partition((x) => x.length === 3),
); // => [['one', 'two'], ['forty two']]
Returns a list of numbers from start (inclusive) to end (exclusive).
range(start, end);
R.range(1, 5); // => [1, 2, 3, 4]
range(end)(start);
R.range(5)(1); // => [1, 2, 3, 4]
Calculates the rank of an item in an array based on rules. The rank is the position where the item would appear in the sorted array. This function provides an efficient way to determine the rank in O(n) time, compared to O(nlogn) for the equivalent sortedIndex(sortBy(data, ...rules), item).
R.rankBy(data, item, ...rules);
const DATA = [{ a: 5 }, { a: 1 }, { a: 3 }] as const;
R.rankBy(DATA, 0, R.prop("a")); // => 0
R.rankBy(DATA, 1, R.prop("a")); // => 1
R.rankBy(DATA, 2, R.prop("a")); // => 1
R.rankBy(DATA, 3, R.prop("a")); // => 2
R.rankBy(item, ...rules)(data);
const DATA = [{ a: 5 }, { a: 1 }, { a: 3 }] as const;
R.pipe(DATA, R.rankBy(0, R.prop("a"))); // => 0
R.pipe(DATA, R.rankBy(1, R.prop("a"))); // => 1
R.pipe(DATA, R.rankBy(2, R.prop("a"))); // => 1
R.pipe(DATA, R.rankBy(3, R.prop("a"))); // => 2
Executes a user-supplied "reducer" callback function on each element of the
array, in order, passing in the return value from the calculation on the
preceding element. The final result of running the reducer across all
elements of the array is a single value. Equivalent to
Array.prototype.reduce.