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.
Only number arrays are supported, as bigint is unable to represent fractional values.
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([]); // => undefined
R.mean()(data);
R.pipe([1, 2, 3], R.mean()); // => 2
R.pipe([], R.mean()); // => undefined
Returns the median of the elements of an array.
Only number arrays are supported, as bigint is unable to represent fractional values.
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.median(data);
R.pipe([6, 10, 11], R.median()); // => 10
R.median([]); // => undefined
R.median()(data);
R.pipe([6, 10, 11], R.median()); // => 10
R.pipe([], R.median()); // => 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 data 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', 'OOz']
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.
R.reduce(data, callbackfn, initialValue);
R.reduce([1, 2, 3, 4, 5], (acc, x) => acc + x, 100); // => 115
R.reduce(fn, initialValue)(array);
R.pipe(
[1, 2, 3, 4, 5],
R.reduce((acc, x) => acc + x, 100),
); // => 115
Reverses array.
R.reverse(arr);
R.reverse([1, 2, 3]); // [3, 2, 1]
R.reverse()(array);
R.reverse()([1, 2, 3]); // [3, 2, 1]
Returns a random subset of size sampleSize from array.
Maintains and infers most of the typing information that could be passed along to the output. This means that when using tuples, the output will be a tuple too, and when using literals, those literals would be preserved.
The items in the result are kept in the same order as they are in the input. If you need to get a shuffled response you can pipe the shuffle function after this one.
R.sample(array, sampleSize);
R.sample(["hello", "world"], 1); // => ["hello"] // typed string[]
R.sample(["hello", "world"] as const, 1); // => ["world"] // typed ["hello" | "world"]
R.sample(sampleSize)(array);
R.sample(1)(["hello", "world"]); // => ["hello"] // typed string[]
R.sample(1)(["hello", "world"] as const); // => ["world"] // typed ["hello" | "world"]
Shuffles the input array, returning a new array with the same elements in a random order.
R.shuffle(array);
R.shuffle([4, 2, 7, 5]); // => [7, 5, 4, 2]
R.shuffle()(array);
R.pipe([4, 2, 7, 5], R.shuffle()); // => [7, 5, 4, 2]
Sorts an array. The comparator function should accept two values at a time
and return a negative number if the first value is smaller, a positive number
if it's larger, and zero if they are equal. Sorting is based on a native
sort function.
R.sort(items, cmp);
R.sort([4, 2, 7, 5], (a, b) => a - b); // => [2, 4, 5, 7]
R.sort(cmp)(items);
R.pipe(
[4, 2, 7, 5],
R.sort((a, b) => a - b),
); // => [2, 4, 5, 7]
Sorts data using the provided ordering rules. The sort is done via the
native Array.prototype.sort but is performed on a shallow copy of the array
to avoid mutating the original data.
There are several other functions that take order rules and bypass the need to sort the array first (in O(nlogn) time):
firstBy === first(sortBy(data, ...rules)), O(n).takeFirstBy === take(sortBy(data, ...rules), k), O(nlogk).dropFirstBy === drop(sortBy(data, ...rules), k), O(nlogk).nthBy === sortBy(data, ...rules).at(k), O(n).rankBy === sortedIndex(sortBy(data, ...rules), item), O(n).
Refer to the docs for more details.R.sortBy(...rules)(data);
R.pipe([{ a: 1 }, { a: 3 }, { a: 7 }, { a: 2 }], R.sortBy(R.prop("a"))); // => [{ a: 1 }, { a: 2 }, { a: 3 }, { a: 7 }]
R.sortBy(data, ...rules);
R.sortBy([{ a: 1 }, { a: 3 }, { a: 7 }, { a: 2 }], prop("a")); // => [{ a: 1 }, { a: 2 }, { a: 3 }, { a: 7 }]
R.sortBy(
[
{ color: "red", weight: 2 },
{ color: "blue", weight: 3 },
{ color: "green", weight: 1 },
{ color: "purple", weight: 1 },
],
[prop("weight"), "asc"],
prop("color"),
); // => [
// {color: 'green', weight: 1},
// {color: 'purple', weight: 1},
// {color: 'red', weight: 2},
// {color: 'blue', weight: 3},
// ]
Find the insertion position (index) of an item in an array with items sorted
in ascending order; so that splice(sortedIndex, 0, item) would result in
maintaining the array's sort-ness. The array can contain duplicates.
If the item already exists in the array the index would be of the first
occurrence of the item.
Runs in O(logN) time.
R.sortedIndex(data, item);
R.sortedIndex(["a", "a", "b", "c", "c"], "c"); // => 3
R.sortedIndex(item)(data);
R.pipe(["a", "a", "b", "c", "c"], R.sortedIndex("c")); // => 3
Find the insertion position (index) of an item in an array with items sorted
in ascending order using a value function; so that
splice(sortedIndex, 0, item) would result in maintaining the arrays sort-
ness. The array can contain duplicates.
If the item already exists in the array the index would be of the first
occurrence of the item.
Runs in O(logN) time.
See also:
findIndex - scans a possibly unsorted array in-order (linear search).sortedIndex - like this function, but doesn't take a callbackfn.sortedLastIndexBy - like this function, but finds the last suitable index.sortedLastIndex - like sortedIndex, but finds the last suitable index.rankBy - scans a possibly unsorted array in-order, returning the index based on a sorting criteria.R.sortedIndexBy(data, item, valueFunction);
R.sortedIndexBy([{ age: 20 }, { age: 22 }], { age: 21 }, prop("age")); // => 1
R.sortedIndexBy(data, item, valueFunction);
R.sortedIndexBy([{ age: 20 }, { age: 22 }], { age: 21 }, prop("age")); // => 1
Performs a binary search for the index of the item at which the predicate
stops returning true. This function assumes that the array is "sorted" in
regards to the predicate, meaning that running the predicate as a mapper on
it would result in an array [...true[], ...false[]].
This stricter requirement from the predicate provides us 2 benefits over
findIndex which does a similar thing:
data.length if the
predicate returns true for all items).This function is the basis for all other sortedIndex functions which search for a specific item in a sorted array, and it could be used to perform similar efficient searches.
sortedIndex - scans a sorted array with a binary search, find the first suitable index.sortedIndexBy - like sortedIndex, but assumes sorting is based on a callbackfn.sortedLastIndex - scans a sorted array with a binary search, finding the last suitable index.sortedLastIndexBy - like sortedLastIndex, but assumes sorting is based on a callbackfn.See also:
R.sortedIndexWith(data, predicate);
R.sortedIndexWith(["a", "ab", "abc"], (item) => item.length < 2); // => 1
R.sortedIndexWith(predicate)(data);
R.pipe(
["a", "ab", "abc"],
R.sortedIndexWith((item) => item.length < 2),
); // => 1
Find the insertion position (index) of an item in an array with items sorted
in ascending order; so that splice(sortedIndex, 0, item) would result in
maintaining the array's sort-ness. The array can contain duplicates.
If the item already exists in the array the index would be of the last
occurrence of the item.
Runs in O(logN) time.
R.sortedLastIndex(data, item);
R.sortedLastIndex(["a", "a", "b", "c", "c"], "c"); // => 5
R.sortedLastIndex(item)(data);
R.pipe(["a", "a", "b", "c", "c"], sortedLastIndex("c")); // => 5
Find the insertion position (index) of an item in an array with items sorted
in ascending order using a value function; so that
splice(sortedIndex, 0, item) would result in maintaining the arrays sort-
ness. The array can contain duplicates.
If the item already exists in the array the index would be of the last
occurrence of the item.
Runs in O(logN) time.
See also:
findIndex - scans a possibly unsorted array in-order (linear search).sortedLastIndex - a simplified version of this function, without a callbackfn.sortedIndexBy - like this function, but returns the first suitable index.sortedIndex - like sortedLastIndex but without a callbackfn.rankBy - scans a possibly unsorted array in-order, returning the index based on a sorting criteria.R.sortedLastIndexBy(data, item, valueFunction);
R.sortedLastIndexBy([{ age: 20 }, { age: 22 }], { age: 21 }, prop("age")); // => 1
R.sortedLastIndexBy(item, valueFunction)(data);
R.pipe([{ age: 20 }, { age: 22 }], sortedLastIndexBy({ age: 21 }, prop("age"))); // => 1
Removes elements from an array and, inserts new elements in their place.
R.splice(items, start, deleteCount, replacement);
R.splice([1, 2, 3, 4, 5, 6, 7, 8], 2, 3, []); //=> [1,2,6,7,8]
R.splice([1, 2, 3, 4, 5, 6, 7, 8], 2, 3, [9, 10]); //=> [1,2,9,10,6,7,8]
R.splice(start, deleteCount, replacement)(items);
R.pipe([1, 2, 3, 4, 5, 6, 7, 8], R.splice(2, 3, [])); // => [1,2,6,7,8]
R.pipe([1, 2, 3, 4, 5, 6, 7, 8], R.splice(2, 3, [9, 10])); // => [1,2,9,10,6,7,8]
Splits a given array at a given index.
R.splitAt(array, index);
R.splitAt([1, 2, 3], 1); // => [[1], [2, 3]]
R.splitAt([1, 2, 3, 4, 5], -1); // => [[1, 2, 3, 4], [5]]
R.splitAt(index)(array);
R.splitAt(1)([1, 2, 3]); // => [[1], [2, 3]]
R.splitAt(-1)([1, 2, 3, 4, 5]); // => [[1, 2, 3, 4], [5]]
Splits a given array at the first index where the given predicate returns true.
R.splitWhen(array, fn);
R.splitWhen([1, 2, 3], (x) => x === 2); // => [[1], [2, 3]]
R.splitWhen(fn)(array);
R.splitWhen((x) => x === 2)([1, 2, 3]); // => [[1], [2, 3]]
Returns the sum of the elements of an array using the provided mapper.
Works for both number and bigint mappers, but not mappers that return both
types.
IMPORTANT: The result for empty arrays would be 0 (number) regardless of
the type of the mapper; 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.sumBy(fn)(array);
R.pipe(
[{ a: 5 }, { a: 1 }, { a: 3 }],
R.sumBy((x) => x.a),
); // 9
R.pipe(
[{ a: 5n }, { a: 1n }, { a: 3n }],
R.sumBy((x) => x.a),
); // 9n
R.sumBy(array, fn);
R.sumBy([{ a: 5 }, { a: 1 }, { a: 3 }], (x) => x.a); // 9
R.sumBy([{ a: 5n }, { a: 1n }, { a: 3n }], (x) => x.a); // 9n
Swaps the positions of two elements in an array or string at the provided indices.
Negative indices are supported and would be treated as an offset from the end of the array. The resulting type thought would be less strict than when using positive indices.
If either index is out of bounds the result would be a shallow copy of the input, as-is.
swapIndices(data, index1, index2);
swapIndices(["a", "b", "c"], 0, 1); // => ['b', 'a', 'c']
swapIndices(["a", "b", "c"], 1, -1); // => ['c', 'b', 'a']
swapIndices("abc", 0, 1); // => 'bac'
swapIndices(index1, index2)(data);
swapIndices(0, 1)(["a", "b", "c"]); // => ['b', 'a', 'c']
swapIndices(0, -1)("abc"); // => 'cba'
Returns the first n elements of array.
R.take(array, n);
R.take([1, 2, 3, 4, 3, 2, 1], 3); // => [1, 2, 3]
R.take(n)(array);
R.pipe([1, 2, 3, 4, 3, 2, 1], R.take(n)); // => [1, 2, 3]
Take the first n items from data based on the provided ordering criteria. This allows you to avoid sorting the array before taking the items. The complexity of this function is O(Nlogn) where N is the length of the array.
For the opposite operation (to drop n elements) see dropFirstBy.
R.takeFirstBy(data, n, ...rules);
R.takeFirstBy(["aa", "aaaa", "a", "aaa"], 2, (x) => x.length); // => ['a', 'aa']
R.takeFirstBy(n, ...rules)(data);
R.pipe(
["aa", "aaaa", "a", "aaa"],
R.takeFirstBy(2, (x) => x.length),
); // => ['a', 'aa']
Takes the last n elements from the array.
R.takeLast(array, n);
R.takeLast([1, 2, 3, 4, 5], 2); // => [4, 5]
R.takeLast(n)(array);
R.takeLast(2)([1, 2, 3, 4, 5]); // => [4, 5]
Returns elements from the end of the array until the predicate returns false. The returned elements will be in the same order as in the original array.
R.takeLastWhile(data, predicate);
R.takeLastWhile([1, 2, 10, 3, 4, 5], (x) => x < 10); // => [3, 4, 5]
R.takeLastWhile(predicate)(data);
R.pipe(
[1, 2, 10, 3, 4, 5],
R.takeLastWhile((x) => x < 10),
); // => [3, 4, 5]
Returns elements from the array until predicate returns false.
R.takeWhile(data, predicate);
R.takeWhile([1, 2, 3, 4, 3, 2, 1], (x) => x !== 4); // => [1, 2, 3]
R.takeWhile(predicate)(data);
R.pipe(
[1, 2, 3, 4, 3, 2, 1],
R.takeWhile((x) => x !== 4),
); // => [1, 2, 3]
Calls an input function n times, returning an array containing the results
of those function calls.
fn is passed one argument: The current value of n, which begins at 0
and is gradually incremented to n - 1.
R.times(count, fn);
R.times(5, R.identity()); //=> [0, 1, 2, 3, 4]
R.times(fn)(count);
R.times(R.identity())(5); //=> [0, 1, 2, 3, 4]
Returns a new array containing only one copy of each element in the original list. Elements are compared by reference using Set.
R.unique(array);
R.unique([1, 2, 2, 5, 1, 6, 7]); // => [1, 2, 5, 6, 7]
R.unique()(array);
R.pipe(
[1, 2, 2, 5, 1, 6, 7], // only 4 iterations
R.unique(),
R.take(3),
); // => [1, 2, 5]
Returns a new array containing only one copy of each element in the original list transformed by a function. Elements are compared by reference using Set.
R.uniqueBy(data, keyFunction);
R.uniqueBy(
[{ n: 1 }, { n: 2 }, { n: 2 }, { n: 5 }, { n: 1 }, { n: 6 }, { n: 7 }],
(obj) => obj.n,
); // => [{n: 1}, {n: 2}, {n: 5}, {n: 6}, {n: 7}]
R.uniqueBy(keyFunction)(data);
R.pipe(
[{ n: 1 }, { n: 2 }, { n: 2 }, { n: 5 }, { n: 1 }, { n: 6 }, { n: 7 }], // only 4 iterations
R.uniqueBy((obj) => obj.n),
R.take(3),
); // => [{n: 1}, {n: 2}, {n: 5}]
Returns a new array containing only one copy of each element in the original list. Elements are compared by custom comparator isEquals.
R.uniqueWith(array, isEquals);
R.uniqueWith(
[{ a: 1 }, { a: 2 }, { a: 2 }, { a: 5 }, { a: 1 }, { a: 6 }, { a: 7 }],
R.equals,
); // => [{a: 1}, {a: 2}, {a: 5}, {a: 6}, {a: 7}]
R.uniqueWith(isEquals)(array);
R.uniqueWith(R.equals)([
{ a: 1 },
{ a: 2 },
{ a: 2 },
{ a: 5 },
{ a: 1 },
{ a: 6 },
{ a: 7 },
]); // => [{a: 1}, {a: 2}, {a: 5}, {a: 6}, {a: 7}]
R.pipe(
[{ a: 1 }, { a: 2 }, { a: 2 }, { a: 5 }, { a: 1 }, { a: 6 }, { a: 7 }], // only 4 iterations
R.uniqueWith(R.equals),
R.take(3),
); // => [{a: 1}, {a: 2}, {a: 5}]
Creates a new list from two supplied lists by pairing up equally-positioned items. The length of the returned list will match the shortest of the two inputs.
R.zip(first, second);
R.zip([1, 2], ["a", "b"]); // => [[1, 'a'], [2, 'b']]
R.zip(second)(first);
R.zip(["a", "b"])([1, 2]); // => [[1, 'a'], [2, 'b']]
Creates a new list from two supplied lists by calling the supplied function with the same-positioned element from each list.
R.zipWith(fn)(first, second);
R.zipWith((a: string, b: string) => a + b)(["1", "2", "3"], ["a", "b", "c"]); // => ['1a', '2b', '3c']
R.zipWith(second, fn)(first);
R.pipe(
["1", "2", "3"],
R.zipWith(["a", "b", "c"], (a, b) => a + b),
); // => ['1a', '2b', '3c']
R.zipWith(first, second, fn);
R.zipWith(["1", "2", "3"], ["a", "b", "c"], (a, b) => a + b); // => ['1a', '2b', '3c']
Makes first character of a string upper-case. Uses the built-in
String.prototype.toUpperCase
for the runtime, and the built-in Capitalize
utility type for typing.
For other case manipulations see: toUpperCase, toLowerCase,
uncapitalize, toCamelCase, toKebabCase, and toSnakeCase.
!IMPORTANT: This function might work incorrectly for non-ascii inputs.
If the output is intended for display (on a browser) consider using
the text-transform: capitalize; CSS property
instead!
R.capitalize(data);
R.capitalize("hello world"); // "Hello world"
R.capitalize()(data);
R.pipe("hello world", R.capitalize()); // "Hello world"
Determines whether the string ends with the provided suffix, and refines
the output if possible. Uses the built-in String.prototype.endsWith.
R.endsWith(data, suffix);
R.endsWith("hello world", "hello"); // false
R.endsWith("hello world", "world"); // true
R.endsWith(data, suffix);
R.endsWith("hello world", "hello"); // false
R.endsWith("hello world", "world"); // true
Random a non-cryptographic random string from characters a-zA-Z0-9.
R.randomString(length);
R.randomString(5); // => aB92J
R.randomString()(length);
R.pipe(5, R.randomString()); // => aB92J
Extracts a section of this string and returns it as a new string, without
modifying the original string. Equivalent to String.prototype.slice.
R.sliceString(data, indexStart, indexEnd);
R.sliceString("abcdefghijkl", 1); // => `bcdefghijkl`
R.sliceString("abcdefghijkl", 4, 7); // => `efg`
R.sliceString(indexStart, indexEnd)(string);
R.sliceString(1)("abcdefghijkl"); // => `bcdefghijkl`
R.sliceString(4, 7)("abcdefghijkl"); // => `efg`
Takes a pattern and divides this string into an ordered list of substrings by
searching for the pattern, puts these substrings into an array, and returns
the array. This function mirrors the built-in String.prototype.split
method.
R.split(data, separator, limit);
R.split("a,b,c", ","); //=> ["a", "b", "c"]
R.split("a,b,c", ",", 2); //=> ["a", "b"]
R.split("a1b2c3d", /\d/u); //=> ["a", "b", "c", "d"]
R.split(separator, limit)(data);
R.pipe("a,b,c", R.split(",")); //=> ["a", "b", "c"]
R.pipe("a,b,c", R.split(",", 2)); //=> ["a", "b"]
R.pipe("a1b2c3d", R.split(/\d/u)); //=> ["a", "b", "c", "d"]
Determines whether the string begins with the provided prefix, and refines
the output if possible. Uses the built-in String.prototype.startsWith.
R.startsWith(data, prefix);
R.startsWith("hello world", "hello"); // true
R.startsWith("hello world", "world"); // false
R.startsWith(data, prefix);
R.startsWith("hello world", "hello"); // true
R.startsWith("hello world", "world"); // false
Convert a text to camelCase by splitting it into words, un-capitalizing the
first word, capitalizing the rest, then joining them back together. This is
the runtime implementation of type-fest's CamelCase type.
For other case manipulations see: toLowerCase, toUpperCase, capitalize,
uncapitalize, toKebabCase, and toSnakeCase.
!IMPORTANT: This function might work incorrectly for non-ascii inputs.
For PascalCase use capitalize(toCamelCase(data)).
R.toCamelCase(data);
R.toCamelCase(data, { preserveConsecutiveUppercase });
R.toCamelCase("hello world"); // "helloWorld"
R.toCamelCase("__HELLO_WORLD__"); // "helloWorld"
R.toCamelCase("HasHtml"); // "hasHTML"
R.toCamelCase("HasHtml", { preserveConsecutiveUppercase: false }); // "hasHtml"
R.toCamelCase()(data);
R.toCamelCase({ preserveConsecutiveUppercase })(data);
R.pipe("hello world", R.toCamelCase()); // "helloWorld"
R.pipe("__HELLO_WORLD__", toCamelCase()); // "helloWorld"
R.pipe("HasHtml", R.toCamelCase()); // "hasHTML"
R.pipe("HasHtml", R.toCamelCase({ preserveConsecutiveUppercase: false })); // "hasHtml"
Convert a text to kebab-Case by splitting it into words and joining them back together with "-", and then lowering the case of the result.
For other case manipulations see: toLowerCase, toUpperCase, capitalize,
uncapitalize, and toCamelCase.
!IMPORTANT: This function might work incorrectly for non-ascii inputs.
R.toKebabCase(data);
R.toKebabCase("hello world"); // "hello-world"
R.toKebabCase("__HELLO_WORLD__"); // "hello-world"
R.toKebabCase()(data);
R.pipe("hello world", R.toKebabCase()); // "hello-world"
R.pipe("__HELLO_WORLD__", toKebabCase()); // "hello-world"
Lowers the case of all characters in the input. Uses the built-in String.prototype.toLowerCase
for the runtime, and the built-in Lowercase
utility type for typing.
For other case manipulations see: toUpperCase, capitalize,
uncapitalize, toCamelCase, toKebabCase, and toSnakeCase.
!IMPORTANT: This function might work incorrectly for non-ascii inputs.
If the output is intended for display (on a browser) consider using
the text-transform: lowercase; CSS property
instead!
R.toLowerCase(data);
R.toLowerCase("Hello World"); // "hello world"
R.toLowerCase()(data);
R.pipe("Hello World", R.toLowerCase()); // "hello world"
Convert a text to snake-case by splitting it into words and joining them back together with "_", and then lowering the case of the result.
For other case manipulations see: toLowerCase, toUpperCase, capitalize,
uncapitalize, toCamelCase, and toKebabCase.
!IMPORTANT: This function might work incorrectly for non-ascii inputs.
R.toSnakeCase(data);
R.toSnakeCase("hello world"); // "hello_world"
R.toSnakeCase("__HELLO_WORLD__"); // "hello_world"
R.toSnakeCase()(data);
R.pipe("hello world", R.toSnakeCase()); // "hello_world"
R.pipe("__HELLO_WORLD__", toSnakeCase()); // "hello_world"
Replaces all lower-case characters to their upper-case equivalent in the
input. Uses the built-in String.prototype.toUpperCase
for the runtime, and the built-in Uppercase
utility type for typing.
For other case manipulations see: toLowerCase, capitalize,
uncapitalize, toCamelCase, toKebabCase, and toSnakeCase.
!IMPORTANT: This function might work incorrectly for non-ascii inputs.
If the output is intended for display (on a browser) consider using
the text-transform: uppercase; CSS property
instead!
R.toUpperCase(data);
R.toUpperCase("Hello World"); // "HELLO WORLD"
R.toUpperCase()(data);
R.pipe("Hello World", R.toUpperCase()); // "HELLO WORLD"
Makes first character of a string lower-case. Uses the built-in
String.prototype.toLowerCase
for the runtime, and the built-in Uncapitalize
utility type for typing.
For other case manipulations see: toUpperCase, toLowerCase, capitalize,
toCamelCase, toKebabCase, and toSnakeCase.
!IMPORTANT: This function might work incorrectly for non-ascii inputs.
R.uncapitalize(data);
R.uncapitalize("HELLO WORLD"); // "hELLO WORLD"
R.uncapitalize()(data);
R.pipe("HELLO WORLD", R.uncapitalize()); // "hELLO WORLD"
Executes a transformer function based on the first matching predicate,
functioning like a series of if...else if... statements. It sequentially
evaluates each case and, upon finding a truthy predicate, runs the
corresponding transformer, and returns, ignoring any further cases, even if
they would match.
For simpler cases you should also consider using when instead.
!IMPORTANT! - Unlike similar implementations in frameworks like Lodash and
Ramda, the Remeda implementation does NOT return a default/fallback
undefined value when none of the cases match; and instead will throw an
exception in those cases.
To add a default case use the conditional.defaultCase helper as the final
case of your implementation. By default it returns undefined, but could be
provided a transformer in order to return something else.
Due to TypeScript's inability to infer the result of negating a type-
predicate we can't refine the types used in subsequent cases based on
previous conditions. Using a switch (true) statement or ternary operators
is recommended for more precise type control when such type narrowing is
needed.
R.conditional(...cases)(data);
const nameOrId = 3 as string | number;
R.pipe(
nameOrId,
R.conditional(
[R.isString, (name) => `Hello ${name}`],
[R.isNumber, (id) => `Hello ID: ${id}`],
R.conditional.defaultCase(
(something) => `Hello something (${JSON.stringify(something)})`,
),
),
); //=> 'Hello ID: 3'
R.conditional(data, ...cases);
const nameOrId = 3 as string | number;
R.conditional(
nameOrId,
[R.isString, (name) => `Hello ${name}`],
[R.isNumber, (id) => `Hello ID: ${id}`],
R.conditional.defaultCase(
(something) => `Hello something (${JSON.stringify(something)})`,
),
); //=> 'Hello ID: 3'
A function that takes any arguments and returns the provided value on every
invocation. This is useful to provide trivial implementations for APIs or in
combination with a ternary or other conditional execution to allow to short-
circuit more complex implementations for a specific case.
Notice that this is a dataLast impl where the function needs to be invoked to get the "do nothing" function.
See also:
doNothing - A function that doesn't return anything.
identity - A function that returns the first argument it receives.
R.constant(value);
R.map([1, 2, 3], R.constant("a")); // => ['a', 'a', 'a']
R.map([1, 2, 3], isDemoMode ? R.add(1) : R.constant(0)); // => [2, 3, 4] or [0, 0, 0]
Wraps func with a debouncer object that "debounces" (delays) invocations of the function during a defined cool-down period (waitMs). It can be configured to invoke the function either at the start of the cool-down period, the end of it, or at both ends (timing).
It can also be configured to allow invocations during the cool-down period (maxWaitMs).
It stores the latest call's arguments so they could be used at the end of the cool-down period when invoking func (if configured to invoke the function at the end of the cool-down period).
It stores the value returned by func whenever its invoked. This value is returned on every call, and is accessible via the cachedValue property of the debouncer. Its important to note that the value might be different from the value that would be returned from running func with the current arguments as it is a cached value from a previous invocation.
Important: The cool-down period defines the minimum between two invocations, and not the maximum. The period will be extended each time a call is made until a full cool-down period has elapsed without any additional calls.
R.debounce(func, options);
const debouncer = debounce(identity(), { timing: "trailing", waitMs: 1000 });
const result1 = debouncer.call(1); // => undefined
const result2 = debouncer.call(2); // => undefined
// after 1 second
const result3 = debouncer.call(3); // => 2
// after 1 second
debouncer.cachedValue; // => 3
A function that takes any arguments and does nothing with them. This is useful as a placeholder for any function or API that requires a void function (a function that doesn't return a value). This could also be used in combination with a ternary or other conditional execution to allow disabling a function call for a specific case.
Notice that this is a dataLast impl where the function needs to be invoked to get the "do nothing" function.
See also:
R.doNothing();
myApi({ onSuccess: handleSuccess, onError: R.doNothing() });
myApi({ onSuccess: isDemoMode ? R.doNothing() : handleSuccess });
A function that returns the first argument passed to it.
Notice that this is a dataLast impl where the function needs to be invoked to get the "do nothing" function.
See also:
R.identity();
R.map([1, 2, 3], R.identity()); // => [1,2,3]
Creates a function that is restricted to invoking func once. Repeat calls to the function return the value of the first invocation.
R.once(fn);
const initialize = R.once(createApplication);
initialize();
initialize();
// => `createApplication` is invoked once
Creates a function that calls func with partial put before the arguments
it receives.
Can be thought of as "freezing" some portion of a function's arguments, resulting in a new function with a simplified signature.
R.partialBind(func, partial);
const fn = (x, y, z) => `${x}, ${y}, and ${z}`;
const partialFn = R.partialBind(fn, [1, 2]);
partialFn(3); // => 1, 2, and 3
const logWithPrefix = R.partialBind(console.log, ["[prefix]"]);
logWithPrefix("hello"); // => "[prefix] hello"
Creates a function that calls func with partial put after the arguments
it receives. Note that this doesn't support functions with both optional
and rest parameters.
Can be thought of as "freezing" some portion of a function's arguments, resulting in a new function with a simplified signature.
Useful for converting a data-first function to a data-last one.
R.partialLastBind(func, partial);
const fn = (x, y, z) => `${x}, ${y}, and ${z}`;
const partialFn = R.partialLastBind(fn, [2, 3]);
partialFn(1); // => 1, 2, and 3
const parseBinary = R.partialLastBind(parseInt, ["2"]);
parseBinary("101"); // => 5
R.pipe(
{ a: 1 },
// instead of (arg) => JSON.stringify(arg, null, 2)
R.partialLastBind(JSON.stringify, [null, 2]),
); // => '{\n "a": 1\n}'
Perform left-to-right function composition.
R.pipe(data, op1, op2, op3);
R.pipe(
[1, 2, 3, 4],
R.map((x) => x * 2),
(arr) => [arr[0] + arr[1], arr[2] + arr[3]],
); // => [6, 14]
A dataLast version of pipe that could be used to provide more complex
computations to functions that accept a function as a param (like map,
filter, groupBy, etc.).
The first function must be always annotated. Other functions are automatically inferred.
R.piped(...ops)(data);
R.filter(
[{ a: 1 }, { a: 2 }, { a: 3 }],
R.piped(R.prop("a"), (x) => x % 2 === 0),
); // => [{ a: 2 }]
Creates a function with dataFirst and dataLast signatures.
purry is a dynamic function and it's not type safe. It should be wrapped by
a function that have proper typings. Refer to the example below for correct
usage.
!IMPORTANT: functions that simply call purry and return the result (like
almost all functions in this library) should return unknown themselves if
an explicit return type is required. This is because we currently don't
provide a generic return type that is built from the input function, and
crafting one manually isn't worthwhile as we rely on function declaration
overloading to combine the types for dataFirst and dataLast invocations!
R.purry(fn, args);
function _findIndex(array, fn) {
for (let i = 0; i < array.length; i++) {
if (fn(array[i])) {
return i;
}
}
return -1;
}
// data-first
function findIndex<T>(array: T[], fn: (item: T) => boolean): number;
// data-last
function findIndex<T>(fn: (item: T) => boolean): (array: T[]) => number;
function findIndex(...args: unknown[]) {
return R.purry(_findIndex, args);
}
Conditionally run a function based on a predicate, returning it's result (similar to
the ?: (ternary) operator.)
If the optional onFalse function is not provided, the data will be passed
through in those cases.
Supports type predicates to refine the types for both branches and the return value.
Additional arguments are passed to all functions. In data-first calls, they are taken as variadic arguments; but in data-last calls, they are when the curried function itself is called.
For more complex cases check out conditional.
when(predicate, onTrue)(data, ...extraArgs);
when(predicate, { onTrue, onFalse })(data, ...extraArgs);
pipe(data, when(isNullish, constant(42)));
pipe(
data,
when((x) => x > 3, { onTrue: add(1), onFalse: multiply(2) }),
);
map(
data,
when(isNullish, (x, index) => x + index),
);
when(data, predicate, onTrue, ...extraArgs);
when(data, predicate, { onTrue, onFalse }, ...extraArgs);
when(data, isNullish, constant(42));
when(data, (x) => x > 3, { onTrue: add(1), onFalse: multiply(2) });
when(data, isString, (x, radix) => parseInt(x, radix), 10);
Checks if subObject is a sub-object of object, which means for every
property and value in subObject, there's the same property in object
with an equal value. Equality is checked with isDeepEqual.
R.hasSubObject(data, subObject);
R.hasSubObject({ a: 1, b: 2, c: 3 }, { a: 1, c: 3 }); //=> true
R.hasSubObject({ a: 1, b: 2, c: 3 }, { b: 4 }); //=> false
R.hasSubObject({ a: 1, b: 2, c: 3 }, {}); //=> true
R.hasSubObject(subObject)(data);
R.hasSubObject({ a: 1, c: 3 })({ a: 1, b: 2, c: 3 }); //=> true
R.hasSubObject({ b: 4 })({ a: 1, b: 2, c: 3 }); //=> false
R.hasSubObject({})({ a: 1, b: 2, c: 3 }); //=> true
A function that checks if the passed parameter is an Array and narrows its type accordingly.
R.isArray(data);
R.isArray([5]); //=> true
R.isArray([]); //=> true
R.isArray("somethingElse"); //=> false
A function that checks if the passed parameter is a bigint and narrows its type accordingly.
R.isBigInt(data);
R.isBigInt(1n); // => true
R.isBigInt(1); // => false
R.isBigInt("notANumber"); // => false
A function that checks if the passed parameter is a boolean and narrows its type accordingly.
R.isBoolean(data);
R.isBoolean(true); //=> true
R.isBoolean(false); //=> true
R.isBoolean("somethingElse"); //=> false
A function that checks if the passed parameter is a Date and narrows its type accordingly.
R.isDate(data);
R.isDate(new Date()); //=> true
R.isDate("somethingElse"); //=> false
Performs a deep structural comparison between two values to determine if
they are equivalent. For primitive values this is equivalent to ===, for
arrays the check would be performed on every item recursively, in order, and
for objects all props will be compared recursively.
The built-in Date and RegExp are special-cased and will be compared by their values.
!IMPORTANT: TypedArrays and symbol properties of objects are not supported right now and might result in unexpected behavior. Please open an issue in the Remeda github project if you need support for these types.
The result would be narrowed to the second value so that the function can be used as a type guard.
See:
isStrictEqual if you don't need a deep comparison and just want to
check for simple (===, Object.is) equality.isShallowEqual if you need to compare arrays and objects "by-value" but
don't want to recurse into their values.R.isDeepEqual(data, other);
R.isDeepEqual(1, 1); //=> true
R.isDeepEqual(1, "1"); //=> false
R.isDeepEqual([1, 2, 3], [1, 2, 3]); //=> true
R.isDeepEqual(other)(data);
R.pipe(1, R.isDeepEqual(1)); //=> true
R.pipe(1, R.isDeepEqual("1")); //=> false
R.pipe([1, 2, 3], R.isDeepEqual([1, 2, 3])); //=> true
A function that checks if the passed parameter is defined (!== undefined)
and narrows its type accordingly.
R.isDefined(data);
R.isDefined("string"); //=> true
R.isDefined(null); //=> true
R.isDefined(undefined); //=> false
A function that checks if the passed parameter is empty.
undefined is also considered empty, but only when it's in a union with a
string or string-like type.
This guard doesn't work negated because of typescript limitations! If you
need to check that an array is not empty, use R.hasAtLeast(data, 1)
and not !R.isEmpty(data). For strings and objects there's no way in
typescript to narrow the result to a non-empty type.
R.isEmpty(data);
R.isEmpty(undefined); //=>true
R.isEmpty(""); //=> true
R.isEmpty([]); //=> true
R.isEmpty({}); //=> true
R.isEmpty("test"); //=> false
R.isEmpty([1, 2, 3]); //=> false
R.isEmpty({ length: 0 }); //=> false
A function that checks if the passed parameter is an Error and narrows its type accordingly.
R.isError(data);
R.isError(new Error("message")); //=> true
R.isError("somethingElse"); //=> false
A function that checks if the passed parameter is a Function and narrows its type accordingly.
R.isFunction(data);
R.isFunction(() => {}); //=> true
R.isFunction("somethingElse"); //=> false
Checks if the item is included in the container. This is a wrapper around
Array.prototype.includes and Set.prototype.has and thus relies on the
same equality checks that those functions do (which is reference equality,
e.g. ===). In some cases the input's type is also narrowed to the
container's item types.
Notice that unlike most functions, this function takes a generic item as it's data and an array as it's parameter.
R.isIncludedIn(data, container);
R.isIncludedIn(2, [1, 2, 3]); // => true
R.isIncludedIn(4, [1, 2, 3]); // => false
const data = "cat" as "cat" | "dog" | "mouse";
R.isIncludedIn(data, ["cat", "dog"] as const); // true (typed "cat" | "dog");
R.isIncludedIn(container)(data);
R.pipe(2, R.isIncludedIn([1, 2, 3])); // => true
R.pipe(4, R.isIncludedIn([1, 2, 3])); // => false
const data = "cat" as "cat" | "dog" | "mouse";
R.pipe(data, R.isIncludedIn(["cat", "dog"] as const)); // => true (typed "cat" | "dog");
A function that checks if the passed parameter is not null and narrows its type accordingly.
Notice that undefined is not null!
R.isNonNull(data);
R.isNonNull("string"); //=> true
R.isNonNull(null); //=> false
R.isNonNull(undefined); //=> true
A function that checks if the passed parameter is defined AND isn't null
and narrows its type accordingly.
R.isNonNullish(data);
R.isNonNullish("string"); //=> true
R.isNonNullish(null); //=> false
R.isNonNullish(undefined); //=> false
A function that takes a guard function as predicate and returns a guard that negates it.
R.isNot(R.isTruthy)(data);
R.isNot(R.isTruthy)(false); //=> true
R.isNot(R.isTruthy)(true); //=> false
A function that checks if the passed parameter is either null or
undefined and narrows its type accordingly.
R.isNullish(data);
R.isNullish(undefined); //=> true
R.isNullish(null); //=> true
R.isNullish("somethingElse"); //=> false
A function that checks if the passed parameter is a number and narrows its type accordingly.
R.isNumber(data);
R.isNumber(1); // => true
R.isNumber(1n); // => false
R.isNumber("notANumber"); // => false
Checks if the given parameter is of type "object" via typeof, excluding null.
It's important to note that in JavaScript, many entities are considered objects, like Arrays, Classes, RegExps, Maps, Sets, Dates, URLs, Promise, Errors, and more. Although technically an object too, null is not considered an object by this function, so that its easier to narrow nullables.
For a more specific check that is limited to plain objects (simple struct/shape/record-like objects), consider using isPlainObject instead. For a simpler check that only removes null from the type prefer isNonNull or isDefined.
R.isObjectType(data);
// true
R.isObjectType({}); //=> true
R.isObjectType([]); //=> true
R.isObjectType(Promise.resolve("something")); //=> true
R.isObjectType(new Date()); //=> true
R.isObjectType(new Error("error")); //=> true
// false
R.isObjectType("somethingElse"); //=> false
R.isObjectType(null); //=> false
Checks if data is a "plain" object. A plain object is defined as an object with string keys and values of any type, including primitives, other objects, functions, classes, etc (aka struct/shape/record/simple). Technically, a plain object is one whose prototype is either Object.prototype or null, ensuring it does not inherit properties or methods from other object types.
This function is narrower in scope than isObjectType, which accepts any entity considered an "object" by JavaScript's typeof.
Note that Maps, Arrays, and Sets are not considered plain objects and would return false.
R.isPlainObject(data);
// true
R.isPlainObject({}); //=> true
R.isPlainObject({ a: 123 }); //=> true
// false
R.isPlainObject([]); //=> false
R.isPlainObject(Promise.resolve("something")); //=> false
R.isPlainObject(new Date()); //=> false
R.isPlainObject(new Error("error")); //=> false
R.isPlainObject("somethingElse"); //=> false
R.isPlainObject(null); //=> false
A function that checks if the passed parameter is a Promise and narrows its type accordingly.
R.isPromise(data);
R.isPromise(Promise.resolve(5)); //=> true
R.isPromise(Promise.reject(5)); //=> true
R.isPromise("somethingElse"); //=> false
Performs a shallow structural comparison between two values to determine if
they are equivalent. For primitive values this is equivalent to ===, for
arrays a strict equality check would be performed on every item, in
order, and for objects props will be matched and checked for strict
equality; Unlike isDeepEqual where the function also recurses into each
item and value.
!IMPORTANT: symbol properties of objects are not supported right now and might result in unexpected behavior. Please open an issue in the Remeda github project if you need support for these types.
!IMPORTANT: Promise, Date, and RegExp, are shallowly equal, even when they
are semantically different (e.g. resolved promises); but isDeepEqual does
compare the latter 2 semantically by-value.
The result would be narrowed to the second value so that the function can be used as a type guard.
See:
isStrictEqual if you don't need a deep comparison and just want to check
for simple (===, Object.is) equality.isDeepEqual for a recursively deep check of arrays and objects.R.isShallowEqual(data, other);
R.isShallowEqual(1, 1); //=> true
R.isShallowEqual(1, "1"); //=> false
R.isShallowEqual([1, 2, 3], [1, 2, 3]); //=> true
R.isShallowEqual([[1], [2], [3]], [[1], [2], [3]]); //=> false
R.isShallowEqual(other)(data);
R.pipe(1, R.isShallowEqual(1)); //=> true
R.pipe(1, R.isShallowEqual("1")); //=> false
R.pipe([1, 2, 3], R.isShallowEqual([1, 2, 3])); //=> true
R.pipe([[1], [2], [3]], R.isShallowEqual([[1], [2], [3]])); //=> false
Determines whether two values are functionally identical in all contexts. For primitive values (string, number), this is done by-value, and for objects it is done by-reference (i.e., they point to the same object in memory).
Under the hood we use both the === operator
and Object.is. This means that isStrictEqual(NaN, NaN) === true
(whereas NaN !== NaN), and isStrictEqual(-0, 0) === true (whereas
Object.is(-0, 0) === false).
The result would be narrowed to the second value so that the function can be used as a type guard.
See:
isDeepEqual for a semantic comparison that allows comparing arrays and
objects "by-value", and recurses for every item.isShallowEqual if you need to compare arrays and objects "by-value" but
don't want to recurse into their values.R.isStrictEqual(data, other);
R.isStrictEqual(1, 1); //=> true
R.isStrictEqual(1, "1"); //=> false
R.isStrictEqual([1, 2, 3], [1, 2, 3]); //=> false
R.isStrictEqual(other)(data);
R.pipe(1, R.isStrictEqual(1)); //=> true
R.pipe(1, R.isStrictEqual("1")); //=> false
R.pipe([1, 2, 3], R.isStrictEqual([1, 2, 3])); //=> false
A function that checks if the passed parameter is a string and narrows its type accordingly.
R.isString(data);
R.isString("string"); //=> true
R.isString(1); //=> false
A function that checks if the passed parameter is a symbol and narrows its type accordingly.
R.isSymbol(data);
R.isSymbol(Symbol("foo")); //=> true
R.isSymbol(1); //=> false
A function that checks if the passed parameter is truthy and narrows its type accordingly.
R.isTruthy(data);
R.isTruthy("somethingElse"); //=> true
R.isTruthy(null); //=> false
R.isTruthy(undefined); //=> false
R.isTruthy(false); //=> false
R.isTruthy(0); //=> false
R.isTruthy(""); //=> false
Converts a path string to an array of string keys (including array index access keys).
! IMPORTANT: Attempting to pass a simple string type will result in the
result being inferred as never. This is intentional to help with type-
safety as this function is primarily intended to help with other "object path
access" functions like pathOr or setPath.
R.stringToPath(path);
Calls the given function with the given value, then returns the given value. The return value of the provided function is ignored.
This allows "tapping into" a function sequence in a pipe, to perform side effects on intermediate results.
R.tap(value, fn);
R.tap("foo", console.log); // => "foo"
R.tap(fn)(value);
R.pipe(
[-5, -1, 2, 3],
R.filter((n) => n > 0),
R.tap(console.log), // prints [2, 3]
R.map((n) => n * 2),
); // => [4, 6]