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.
View source on GitHub 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); // => falseR.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); // => falseDetermines 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); // => falseR.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); // => falseSplit 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']Categorize and count elements in an array using a defined callback function. The callback function is applied to each element in the array to determine its category and then counts how many elements fall into each category.
R.countBy(data, categorizationFn);R.countBy(["a", "b", "c", "B", "A", "a"], R.toLowerCase()); //=> { a: 3, b: 2, c: 1 }R.countBy(categorizationFn)(data);R.pipe(["a", "b", "c", "B", "A", "a"], R.countBy(R.toLowerCase())); //=> { a: 3, b: 2, c: 1 }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); // => 4R.find(predicate)(data);R.pipe(
[1, 3, 4, 6],
R.find((n) => n % 2 === 0),
); // => 4Returns 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); // => 2R.findIndex(predicate)(data);R.pipe(
[1, 3, 4, 6],
R.findIndex((n) => n % 2 === 0),
); // => 2Iterates 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); // => 3R.findLast(predicate)(data);R.pipe(
[1, 3, 4, 6],
R.findLast((n) => n % 2 === 1),
); // => 3Iterates 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); // => 1R.findLastIndex(fn)(items);R.pipe(
[1, 3, 4, 6],
R.findLastIndex((n) => n % 2 === 1),
); // => 1Gets the first element of array.
R.first(array);R.first([1, 2, 3]); // => 1
R.first([]); // => undefinedR.first()(array);R.pipe(
[1, 2, 4, 8, 16],
R.filter((x) => x > 3),
R.first(),
(x) => x + 1,
); // => 5Find 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(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}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}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.
If you are grouping objects by a property of theirs (e.g.
groupBy(data, ({ myProp }) => myProp) or groupBy(data, prop('myProp')))
consider using groupByProp (e.g. groupByProp(data, 'myProp')) instead,
as it would provide better typing.
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]}Groups the elements of an array of objects based on the values of a
specified property of those objects. The result would contain a property for
each unique value of the specific property, with it's value being the input
array filtered to only items that have that property set to that value.
For any object where the property is missing, or if it's value is
undefined the item would be filtered out.
The grouping property is enforced at the type level to exist in at least one
item and to never have a value that cannot be used as an object key (e.g. it
must be PropertyKey | undefined).
The resulting arrays are filtered with the prop and it's value as a type-guard, effectively narrowing the items in each output arrays. This means that when the grouping property is the discriminator of a discriminated union type each output array would contain just the subtype for that value.
If you need more control over the grouping you should use groupBy instead.
R.groupByProp(data, prop);const result = R.groupByProp(
// ^? { cat: [{ a: 'cat' }], dog: [{ a: 'dog' }] }
[{ a: "cat" }, { a: "dog" }] as const,
"a",
);R.groupByProp(prop)(data);const result = R.pipe(
// ^? { cat: [{ a: 'cat' }], dog: [{ a: 'dog' }] }
[{ a: "cat" }, { a: "dog" }] as const,
R.groupByProp("a"),
);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.
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([]); // => undefinedR.last()(array);R.pipe(
[1, 2, 4, 8, 16],
R.filter((x) => x > 3),
R.last(),
(x) => x + 1,
); // => 17Counts values of the collection or iterable.
R.length(array);R.length([1, 2, 3]); // => 3R.length()(array);R.pipe([1, 2, 3], R.length()); // => 3Creates 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 mapper that
converts each item into an object entry (a tuple of [<key>, <value>]).
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 a mapper for
values and another mapper for keys.fromEntries - Builds an object from an array of key-value pairs.Warning: We strongly advise against using this function unless it is
used with a huge input array and your app has stringent memory/gc
constraints. We recommend that in most cases you should use pullObject,
or the composition fromEntries(map(array, fn)). This function will be
deprecated and removed in future versions of the library!
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(array, fn);R.meanBy([{ a: 5 }, { a: 1 }, { a: 3 }], (x) => x.a); // 3R.meanBy(fn)(array);R.pipe(
[{ a: 5 }, { a: 1 }, { a: 3 }],
R.meanBy((x) => x.a),
); // 3Merges 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 }
R.mergeAll([]); // => {}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()); // => 3R.nthBy(index, ...rules)(data);R.pipe([2, 1, 4, 5, 3], R.nthBy(2, identity())); // => 3Returns the first and only element of array, or undefined otherwise.
R.only(array);R.only([]); // => undefined
R.only([1]); // => 1
R.only([1, 2]); // => undefinedR.only()(array);R.pipe([], R.only()); // => undefined
R.pipe([1], R.only()); // => 1
R.pipe([1, 2], R.only()); // => undefinedSplits 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")); // => 2R.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"))); // => 2Executes 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); // => 115R.reduce(fn, initialValue)(array);R.pipe(
[1, 2, 3, 4, 5],
R.reduce((acc, x) => acc + x, 100),
); // => 115Reverses 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(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},
// ]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 }]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"); // => 3R.sortedIndex(item)(data);R.pipe(["a", "a", "b", "c", "c"], R.sortedIndex("c")); // => 3Find 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")); // => 1Performs 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); // => 1R.sortedIndexWith(predicate)(data);R.pipe(
["a", "ab", "abc"],
R.sortedIndexWith((item) => item.length < 2),
); // => 1Find 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"); // => 5R.sortedLastIndex(item)(data);R.pipe(["a", "a", "b", "c", "c"], sortedLastIndex("c")); // => 5Find 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")); // => 1R.sortedLastIndexBy(item, valueFunction)(data);R.pipe([{ age: 20 }, { age: 22 }], sortedLastIndexBy({ age: 21 }, prop("age"))); // => 1Removes 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(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); // 9nR.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),
); // 9nSwaps 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); // => ['a', 'c', 'b']
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(first, second, fn);R.zipWith(["1", "2", "3"], ["a", "b", "c"], (a, b) => a + b); // => ['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']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.
! DEPRECATED: This implementation of debounce is known to have issues and might not behave as expected. It should be replaced with the funnel utility instead. The test file funnel.remeda-debounce.test.ts offers a reference implementation that replicates debounce via funnel!
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; // => 3A 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 });Creates a funnel that controls the timing and execution of callback. Its
main purpose is to manage multiple consecutive (usually fast-paced) calls,
reshaping them according to a defined batching strategy and timing policy.
This is useful when handling uncontrolled call rates, such as DOM events or
network traffic. It can implement strategies like debouncing, throttling,
batching, and more.
An optional reducer function can be provided to allow passing data to the
callback via calls to call (otherwise the signature of call takes no
arguments).
Typing is inferred from callbacks param, and from the rest params that
the optional reducer function accepts. Use explicit types for these
to ensure that everything else is well-typed.
Notice that this function constructs a funnel object, and does not
execute anything when called. The returned object should be used to execute
the funnel via the its call method.
minQuietPeriodMs and any triggerAt.minGapMs and triggerAt: "start" or "both".funnel.reference-batch.test.ts.R.funnel(callback, options);const debouncer = R.funnel(
() => {
console.log("Callback executed!");
},
{ minQuietPeriodMs: 100 },
);
debouncer.call();
debouncer.call();
const throttle = R.funnel(
() => {
console.log("Callback executed!");
},
{ minGapMs: 100, triggerAt: "start" },
);
throttle.call();
throttle.call();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 onceCreates 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: number, y: number, z: number) => x * 100 + y * 10 + z;
const partialFn = R.partialBind(fn, 1, 2);
partialFn(3); //=> 123
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: number, y: number, z: number) => x * 100 + y * 10 + z;
const partialFn = R.partialLastBind(fn, 2, 3);
partialFn(1); //=> 123
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(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);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),
);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 }, {}); //=> trueR.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 }); //=> trueA 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"); //=> falseA 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"); // => falseA 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"); //=> falseA 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"); //=> falsePerforms 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]); //=> trueR.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])); //=> trueA 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); //=> falseA 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 }); //=> falseA 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"); //=> falseA function that checks if the passed parameter is a Function and narrows its type accordingly.
R.isFunction(data);R.isFunction(() => {}); //=> true
R.isFunction("somethingElse"); //=> falseChecks 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); //=> trueA 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); //=> falseA 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); //=> falseA 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"); //=> falseA 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"); // => falseChecks 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); //=> falseChecks 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); //=> falseA 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"); //=> falsePerforms 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]]); //=> falseR.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]])); //=> falseDetermines 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]); //=> falseR.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])); //=> falseA 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); //=> falseA 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); //=> falseA 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(""); //=> falseAdds two numbers.
R.add(value, addend);R.add(10, 5); // => 15
R.add(10, -5); // => 5R.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); // => 457000R.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); // => 457000Clamp 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 }); // => 10R.clamp({ min, max })(value);clamp({ min: 20 })(10); // => 20
clamp({ max: 5 })(10); // => 5
clamp({ max: 20, min: 5 })(10); // => 10Divides two numbers.
R.divide(value, divisor);R.divide(12, 3); // => 4
R.reduce([1, 2, 3, 4], R.divide, 24); // => 1R.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); // => 456000R.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); // => 456000Returns 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([]); // => undefinedR.mean()(data);R.pipe([1, 2, 3], R.mean()); // => 2
R.pipe([], R.mean()); // => undefinedReturns 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([]); // => undefinedR.median()(data);R.pipe([6, 10, 11], R.median()); // => 10
R.pipe([], R.median()); // => undefinedMultiplies two numbers.
R.multiply(value, multiplicand);R.multiply(3, 4); // => 12
R.reduce([1, 2, 3, 4], R.multiply, 1); // => 24R.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([]); // => 1R.product()(data);R.pipe([1, 2, 3], R.product()); // => 6
R.pipe([1n, 2n, 3n], R.product()); // => 6n
R.pipe([], R.product()); // => 1Generate 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); // => 5nGenerate 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); // => 2Rounds 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); // => 457000R.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); // => 457000Subtracts 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); // => 10R.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([]); // => 0R.sum()(data);R.pipe([1, 2, 3], R.sum()); // => 6
R.pipe([1n, 2n, 3n], R.sum()); // => 6n
R.pipe([], R.sum()); // => 0Add 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(data, 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.
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.
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(obj, names);R.omit({ a: 1, b: 2, c: 3, d: 4 }, ["a", "d"]); // => { b: 2, c: 3 }R.omit(names)(obj);R.pipe({ a: 1, b: 2, c: 3, d: 4 }, R.omit(["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.
DEPRECATED: Use defaultTo(prop(object, ...path), defaultValue)
instead!
R.pathOr(object, array, defaultValue);R.pathOr({ x: 10 }, ["y"], 2); // 2
R.pathOr({ y: 10 }, ["y"], 2); // 10R.pathOr(array, defaultValue)(object);R.pipe({ x: 10 }, R.pathOr(["y"], 2)); // 2
R.pipe({ y: 10 }, R.pathOr(["y"], 2)); // 10Creates an object composed of the picked data properties.
R.pick(object, [prop1, prop2]);R.pick({ a: 1, b: 2, c: 3, d: 4 }, ["a", "d"]); // => { a: 1, d: 4 }R.pick([prop1, prop2])(object);R.pipe({ a: 1, b: 2, c: 3, d: 4 }, R.pick(["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 from an object. Nested properties can
be accessed by providing a variadic array of keys that define the path from
the root to the desired property. Arrays can be accessed by using numeric
keys. Unions and optional properties are handled gracefully by returning
undefined early for any non-existing property on the path. Paths are
validated against the object type to provide stronger type safety, better
compile-time errors, and to enable autocompletion in IDEs.
R.prop(data, ...keys);R.prop({ foo: { bar: "baz" } }, "foo"); //=> { bar: 'baz' }
R.prop({ foo: { bar: "baz" } }, "foo", "bar"); //=> 'baz'
R.prop(["cat", "dog"], 1); //=> 'dog'R.prop(...keys)(data);R.pipe({ foo: { bar: "baz" } }, R.prop("foo")); //=> { bar: 'baz' }
R.pipe({ foo: { bar: "baz" } }, R.prop("foo", "bar")); //=> 'baz'
R.pipe(["cat", "dog"], R.prop(1)); //=> 'dog'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.
Refer to the docs for more details.R.pullObject(data, keyExtractor, valueExtractor);R.pullObject(
[
{ name: "john", email: "john@remedajs.com" },
{ name: "jane", email: "jane@remedajs.com" },
],
R.prop("name"),
R.prop("email"),
); // => { john: "john@remedajs.com", jane: "jane@remedajs.com" }R.pullObject(keyExtractor, valueExtractor)(data);R.pipe(
[
{ name: "john", email: "john@remedajs.com" },
{ name: "jane", email: "jane@remedajs.com" },
],
R.pullObject(R.prop("email"), R.prop("name")),
); // => { john: "john@remedajs.com", jane: "jane@remedajs.com" }Sets the value at prop of object.
To add a new property to an object, or to override its type, use addProp
instead, and to set a property within a nested object use setPath.
R.set(obj, prop, value);R.set({ a: 1 }, "a", 2); // => { a: 2 }R.set(prop, value)(obj);R.pipe({ a: 1 }, R.set("a", 2)); // => { a: 2 }Sets the value at path of object.
For simple cases where the path is only one level deep, prefer set instead.
R.setPath(obj, path, value);R.setPath({ a: { b: 1 } }, ["a", "b"], 2); // => { a: { b: 2 } }R.setPath(path, value)(obj);R.pipe({ a: { b: 1 } }, R.setPath(["a", "b"], 2)); // { a: { b: 2 } }Swaps the positions of two properties in an object based on the provided keys.
swap(data, key1, key2);swap({ a: 1, b: 2, c: 3 }, "a", "b"); // => {a: 2, b: 1, c: 3}swap(key1, key2)(data);swap("a", "b")({ a: 1, b: 2, c: 3 }); // => {a: 2, b: 1, c: 3}Returns a new array containing the values of the array or object.
R.values(source);R.values(["x", "y", "z"]); // => ['x', 'y', 'z']
R.values({ a: "x", b: "y", c: "z" }); // => ['x', 'y', 'z']R.values()(source);R.pipe(["x", "y", "z"], R.values()); // => ['x', 'y', 'z']
R.pipe({ a: "x", b: "y", c: "z" }, R.values()); // => ['x', 'y', 'z']
R.pipe({ a: "x", b: "y", c: "z" }, R.values(), R.first()); // => 'x'A stricter wrapper around the Nullish coalescing operator ??
that ensures that the fallback matches the type of the data. Only works
when data can be null or undefined.
Notice that Number.NaN is not nullish and would not result in returning the
fallback!
R.defaultTo(data, fallback);R.defaultTo("hello" as string | undefined, "world"); //=> "hello"
R.defaultTo(undefined as string | undefined, "world"); //=> "world"R.defaultTo(fallback)(data);R.pipe("hello" as string | undefined, R.defaultTo("world")); //=> "hello"
R.pipe(undefined as string | undefined, R.defaultTo("world")); //=> "world"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]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"); // trueR.endsWith(suffix)(data);R.pipe("hello world", R.endsWith("hello")); // false
R.pipe("hello world", R.endsWith("world")); // trueRandom a non-cryptographic random string from characters a-zA-Z0-9.
R.randomString(length);R.randomString(5); // => aB92JR.randomString()(length);R.pipe(5, R.randomString()); // => aB92JExtracts 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"); // falseR.startsWith(prefix)(data);R.pipe("hello world", R.startsWith("hello")); // true
R.pipe("hello world", R.startsWith("world")); // falseConvert 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"Truncates strings longer than n, appending an omission marker to them
(which defaults to '...'); shorter strings are returned as-is. The total
length of the output will never exceed n (in the rare case where the
omission itself is too long, it will be truncated too).
The separator argument provides more control by optimistically searching
for a matching cutoff point, which could be used to avoid truncating in the
middle of a word or other semantic boundary.
If you just need to limit the total length of the string, without adding an
omission or optimizing the cutoff point via separator, prefer
sliceString instead, which runs more efficiently.
IMPORTANT: Prefer using CSS text-overflow: ellipsis when
the output is rendered in a browser; this function doesn't handle
diacritics, emojis, and any sort of semantic understanding of the string
contents.
R.truncate(data, n, { omission, separator });R.truncate("Hello, world!", 8); //=> "Hello..."
R.truncate("cat, dog, mouse", 12, { omission: "__", separator: "," }); //=> "cat, dog__"R.truncate(n, { omission, separator })(data);R.pipe("Hello, world!" as const, R.truncate(8)); //=> "Hello..."
R.pipe(
"cat, dog, mouse" as const,
R.truncate(12, { omission: "__", separator: "," }),
); //=> "cat, dog__"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"A utility to allow JSONPath-like strings to be used in other utilities which
take an array of path segments as input (e.g. prop, setPath, etc...).
The main purpose of this utility is to act as a bridge between the runtime
implementation that converts the path to an array, and the type-system that
parses the path string type into an array type. This type allows us
to return fine-grained types and to enforce correctness at the type-level.
We discourage using this utility for new code. This utility is for legacy code that already contains path strings (which are accepted by Lodash). We strongly recommend using path arrays instead as they provide better developer experience via significantly faster type-checking, fine-grained error messages, and automatic typeahead suggestions for each segment of the path.
There are a bunch of limitations to this utility derived from the limitations of the type itself, these are usually edge-cases around deeply nested paths, escaping, whitespaces, and empty segments. This is true even in cases where the runtime implementation can better handle them, this is intentional. See the tests for this utility for more details and the expected outputs.
R.stringToPath(path);R.stringToPath("a.b[0].c"); // => ['a', 'b', 0, 'c']