Documentation

Intro

Welcome to the Remeda documentation and API reference. Below, you’ll find the complete reference for all functions exported by Remeda.

Previous Versions

Are you using version 1.x.x? Visit our migration guide to help you transition to the latest version.


Adds two numbers.

Data First
R.add(value, addend);
R.add(10, 5); // => 15
R.add(10, -5); // => 5
R.reduce([1, 2, 3, 4], R.add, 0); // => 10
Data Last
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.

Data First
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
Data Last
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.

Data First
R.clamp(value, { min, max });
clamp(10, { min: 20 }); // => 20
clamp(10, { max: 5 }); // => 5
clamp(10, { max: 20, min: 5 }); // => 10
Data Last
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.

Data First
R.divide(value, divisor);
R.divide(12, 3); // => 4
R.reduce([1, 2, 3, 4], R.divide, 24); // => 1
Data Last
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.

Data First
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
Data Last
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.

Data First
R.mean(data);
R.mean([1, 2, 3]); // => 2
R.mean([1n, 2n, 3n]); // => 2n
R.mean([]); // => undefined
Data Last
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.

Data First
R.multiply(value, multiplicand);
R.multiply(3, 4); // => 12
R.reduce([1, 2, 3, 4], R.multiply, 1); // => 24
Data Last
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.

Data First
R.product(data);
R.product([1, 2, 3]); // => 6
R.product([1n, 2n, 3n]); // => 6n
R.product([]); // => 1
Data Last
R.product()(data);
R.pipe([1, 2, 3], R.product()); // => 6
R.pipe([1n, 2n, 3n], R.product()); // => 6n
R.pipe([], R.product()); // => 1

randomBigInt

View source on GitHub

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.

Data First
R.randomBigInt(from, to);
R.randomBigInt(1n, 10n); // => 5n

randomInteger

View source on GitHub

Generate a random integer between from and to (inclusive).

!Important: This function uses Math.random() under-the-hood, which has two major limitations:

  1. It generates 2^52 possible values, so the bigger the range, the less uniform the distribution of values would be, and at ranges larger than that some values would never come up.
  2. It is not cryptographically secure and should not be used for security scenarios.
Data First
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.

Data First
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
Data Last
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.

Data First
R.subtract(value, subtrahend);
R.subtract(10, 5); // => 5
R.subtract(10, -5); // => 15
R.reduce([1, 2, 3, 4], R.subtract, 20); // => 10
Data Last
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.

Data First
R.sum(data);
R.sum([1, 2, 3]); // => 6
R.sum([1n, 2n, 3n]); // => 6n
R.sum([]); // => 0
Data Last
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.

Data First
R.addProp(obj, prop, value);
R.addProp({ firstName: "john" }, "lastName", "doe"); // => {firstName: 'john', lastName: 'doe'}
Data Last
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).

Data First
R.clone(data);
R.clone({ foo: "bar" }); // {foo: 'bar'}
Data Last
R.clone()(data);
R.pipe({ foo: "bar" }, R.clone()); // {foo: 'bar'}

Returns an array of key/values of the enumerable properties of an object.

Data First
R.entries(object);
R.entries({ a: 1, b: 2, c: 3 }); // => [['a', 1], ['b', 2], ['c', 3]]
Data Last
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.

Data First
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 },
// }
Data Last
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 },
// }

forEachObj

View source on GitHub

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!

Data First
R.forEachObj(object, fn);
R.forEachObj({ a: 1 }, (val, key, obj) => {
  console.log(`${key}: ${val}`);
}); // "a: 1"
Data Last
R.forEachObj(fn)(object);
R.pipe(
  { a: 1 },
  R.forEachObj((val, key) => console.log(`${key}: ${val}`)),
); // "a: 1"

fromEntries

View source on GitHub

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.
Data First
R.fromEntries(tuples);
R.fromEntries([
  ["a", "b"],
  ["c", "d"],
]); // => {a: 'b', c: 'd'}
Data Last
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.
Data First
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>>)
Data Last
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.

Data First
R.invert(object);
R.invert({ a: "d", b: "e", c: "f" }); // => { d: "a", e: "b", f: "c" }
Data Last
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.

Data First
R.keys(source);
R.keys(["x", "y", "z"]); // => ['0', '1', '2']
R.keys({ a: "x", b: "y", 5: "z" }); // => ['a', 'b', '5']
Data Last
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.

Data First
R.mapKeys(object, fn);
R.mapKeys({ a: 1, b: 2 }, (key, value) => key + value); // => { a1: 1, b2: 2 }
Data Last
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))).

Data First
R.mapValues(data, mapper);
R.mapValues({ a: 1, b: 2 }, (value, key) => value + key); // => {a: '1a', b: '2b'}
Data Last
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 }.

Data First
R.merge(data, source);
R.merge({ x: 1, y: 2 }, { y: 10, z: 2 }); // => { x: 1, y: 10, z: 2 }
Data Last
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)).

Data First
R.mergeDeep(destination, source);
R.mergeDeep({ foo: "bar", x: 1 }, { foo: "baz", y: 2 }); // => { foo: 'baz', x: 1, y: 2 }
Data Last
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.

Data Last
R.omit(names)(obj);
R.pipe({ a: 1, b: 2, c: 3, d: 4 }, R.omit(["a", "d"])); // => { b: 2, c: 3 }
Data First
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.

Data First
R.omitBy(data, predicate);
R.omitBy({ a: 1, b: 2, A: 3, B: 4 }, (val, key) => key.toUpperCase() === key); // => {a: 1, b: 2}
Data Last
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.

Data First
R.pathOr(object, array, defaultValue);
R.pathOr({ x: 10 }, ["y"], 2); // 2
R.pathOr({ y: 10 }, ["y"], 2); // 10
Data Last
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.

Data Last
R.pick([prop1, prop2])(object);
R.pipe({ a: 1, b: 2, c: 3, d: 4 }, R.pick(["a", "d"])); // => { a: 1, d: 4 }
Data First
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).

Data First
R.pickBy(data, predicate);
R.pickBy({ a: 1, b: 2, A: 3, B: 4 }, (val, key) => key.toUpperCase() === key); // => {A: 3, B: 4}
Data Last
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.

Data First
R.prop(data, key);
R.prop({ foo: "bar" }, "foo"); // => 'bar'
Data Last
R.prop(key)(data);
R.pipe({ foo: "bar" }, R.prop("foo")); // => 'bar'

pullObject

View source on GitHub

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.
Data First
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" }
Data Last
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.

Data First
R.set(obj, prop, value);
R.set({ a: 1 }, "a", 2); // => { a: 2 }
Data Last
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.

Data First
R.setPath(obj, path, value);
R.setPath({ a: { b: 1 } }, ["a", "b"], 2); // => { a: { b: 2 } }
Data Last
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.

Data First
swap(data, key1, key2);
swap({ a: 1, b: 2, c: 3 }, "a", "b"); // => {a: 2, b: 1, c: 3}
Data Last
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.

Data First
R.values(source);
R.values(["x", "y", "z"]); // => ['x', 'y', 'z']
R.values({ a: "x", b: "y", c: "z" }); // => ['x', 'y', 'z']
Data Last
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.

Data First
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
Data Last
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.

Data First
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
Data Last
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.

Data First
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']]
Data Last
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.

Data First
R.concat(data, other);
R.concat([1, 2, 3], ["a"]); // [1, 2, 3, 'a']
Data Last
R.concat(arr2)(arr1);
R.concat(["a"])([1, 2, 3]); // [1, 2, 3, 'a']

difference

Lazy
View source on GitHub

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).

Data First
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]
Data First
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]

differenceWith

Lazy
View source on GitHub

Excludes the values from other array. Elements are compared by custom comparator isEquals.

Data First
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}]
Data Last
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.

Data First
R.drop(array, n);
R.drop([1, 2, 3, 4, 5], 2); // => [3, 4, 5]
Data Last
R.drop(n)(array);
R.drop(2)([1, 2, 3, 4, 5]); // => [3, 4, 5]

dropFirstBy

View source on GitHub

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.

Data First
R.dropFirstBy(data, n, ...rules);
R.dropFirstBy(["aa", "aaaa", "a", "aaa"], 2, (x) => x.length); // => ['aaa', 'aaaa']
Data Last
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.

Data First
R.dropLast(array, n);
R.dropLast([1, 2, 3, 4, 5], 2); // => [1, 2, 3]
Data Last
R.dropLast(n)(array);
R.dropLast(2)([1, 2, 3, 4, 5]); // => [1, 2, 3]

dropLastWhile

View source on GitHub

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.

Data First
R.dropLastWhile(data, predicate);
R.dropLastWhile([1, 2, 10, 3, 4], (x) => x < 10); // => [1, 2, 10]
Data Last
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.

Data First
R.dropWhile(data, predicate);
R.dropWhile([1, 2, 10, 3, 4], (x) => x < 10); // => [10, 3, 4]
Data Last
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.

Data First
R.filter(data, predicate);
R.filter([1, 2, 3], (x) => x % 2 === 1); // => [1, 3]
Data Last
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.
Data First
R.find(data, predicate);
R.find([1, 3, 4, 6], (n) => n % 2 === 0); // => 4
Data Last
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).

Data First
R.findIndex(data, predicate);
R.findIndex([1, 3, 4, 6], (n) => n % 2 === 0); // => 2
Data Last
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.
Data First
R.findLast(data, predicate);
R.findLast([1, 3, 4, 6], (n) => n % 2 === 1); // => 3
Data Last
R.findLast(predicate)(data);
R.pipe(
  [1, 3, 4, 6],
  R.findLast((n) => n % 2 === 1),
); // => 3

findLastIndex

View source on GitHub

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).

Data First
R.findLastIndex(data, predicate);
R.findLastIndex([1, 3, 4, 6], (n) => n % 2 === 1); // => 1
Data Last
R.findLastIndex(fn)(items);
R.pipe(
  [1, 3, 4, 6],
  R.findLastIndex((n) => n % 2 === 1),
); // => 1

Gets the first element of array.

Data First
R.first(array);
R.first([1, 2, 3]); // => 1
R.first([]); // => undefined
Data Last
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.

Data Last
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}
Data First
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.

Data First
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]
Data Last
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]

flatMap

Lazy
View source on GitHub

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.

Data First
R.flatMap(data, callbackfn);
R.flatMap([1, 2, 3], (x) => [x, x * 10]); // => [1, 10, 2, 20, 3, 30]
Data Last
R.flatMap(callbackfn)(data);
R.pipe(
  [1, 2, 3],
  R.flatMap((x) => [x, x * 10]),
); // => [1, 10, 2, 20, 3, 30]

forEach

Lazy
View source on GitHub

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!

Data First
R.forEach(data, callbackfn);
R.forEach([1, 2, 3], (x) => {
  console.log(x);
});
Data Last
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.

Data First
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]}
Data Last
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'.

Data First
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`
Data Last
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.
Data First
R.indexBy(array, fn);
R.indexBy(["one", "two", "three"], (x) => x.length); // => {3: 'two', 5: 'three'}
Data Last
R.indexBy(fn)(array);
R.pipe(
  ["one", "two", "three"],
  R.indexBy((x) => x.length),
); // => {3: 'two', 5: 'three'}

intersection

Lazy
View source on GitHub

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).

Data First
R.intersection(data, other);
R.intersection([1, 2, 3], [2, 3, 5]); // => [2, 3]
R.intersection([1, 1, 2, 2], [1]); // => [1]
Data First
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]

intersectionWith

Lazy
View source on GitHub

Returns a list of intersecting values based on a custom comparator function that compares elements of both arrays.

Data First
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' }]
Data Last
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).

Data First
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`)
Data Last
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.

Data First
R.last(array);
R.last([1, 2, 3]); // => 3
R.last([]); // => undefined
Data Last
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.

Data First
R.length(array);
R.length([1, 2, 3]); // => 3
Data Last
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.

Data First
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]
Data Last
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.
Data First
R.mapToObj(array, fn);
R.mapToObj([1, 2, 3], (x) => [String(x), x * 2]); // => {1: 2, 2: 4, 3: 6}
Data Last
R.mapToObj(fn)(array);
R.pipe(
  [1, 2, 3],
  R.mapToObj((x) => [String(x), x * 2]),
); // => {1: 2, 2: 4, 3: 6}

mapWithFeedback

Lazy
View source on GitHub

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.

Data First
R.mapWithFeedback(data, callbackfn, initialValue);
R.mapWithFeedback([1, 2, 3, 4, 5], (prev, x) => prev + x, 100); // => [101, 103, 106, 110, 115]
Data Last
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.

Data Last
R.meanBy(fn)(array);
R.pipe(
  [{ a: 5 }, { a: 1 }, { a: 3 }],
  R.meanBy((x) => x.a),
); // 3
Data First
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.

Data First
R.nthBy(data, index, ...rules);
R.nthBy([2, 1, 4, 5, 3], 2, identity()); // => 3
Data Last
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.

Data First
R.only(array);
R.only([]); // => undefined
R.only([1]); // => 1
R.only([1, 2]); // => undefined
Data Last
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.

Data First
R.partition(data, predicate);
R.partition(["one", "two", "forty two"], (x) => x.length === 3); // => [['one', 'two'], ['forty two']]
Data Last
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).

Data First
range(start, end);
R.range(1, 5); // => [1, 2, 3, 4]
Data Last
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).

Data First
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
Data Last
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.

Data First