clone

{*} → {*}

Parameters

  • valueThe object or array to clone

Returns * A deeply cloned copy of val

Added in v0.1.0

Creates a deep copy of the source that can be used in place of the source object without retaining any references to it. The source object may contain (nested) Arrays and Objects, Numbers, Strings, Booleans and Dates. Functions are assigned by reference rather than copied.

Dispatches to a clone method if present.

Note that if the source object has multiple nodes that share a reference, the returned object will have the same structure, but the references will be pointed to the location within the cloned value.

  1. const objects = [{}, {}, {}];
  2. const objectsClone = R.clone(objects);
  3. objects === objectsClone; //=> false
  4. objects[0] === objectsClone[0]; //=> false

values

{k: v} → [v]

Parameters

  • objThe object to extract values from

Returns Array An array of the values of the object’s own properties.

Added in v0.1.0

Returns a list of all the enumerable own properties of the supplied object. Note that the order of the output array is not guaranteed across different JS platforms.

See also valuesIn, keys, toPairs.

  1. R.values({a: 1, b: 2, c: 3}); //=> [1, 2, 3]

eqProps

k → {k: v} → {k: v} → Boolean

Parameters

  • propThe name of the property to compare
  • obj1
  • obj2

Returns Boolean

Added in v0.1.0

Reports whether two objects have the same value, in R.equals terms, for the specified property. Useful as a curried predicate.

  1. const o1 = { a: 1, b: 2, c: 3, d: 4 };
  2. const o2 = { a: 10, b: 20, c: 3, d: 40 };
  3. R.eqProps('a', o1, o2); //=> false
  4. R.eqProps('c', o1, o2); //=> true

keys

{k: v} → [k]

Parameters

  • objThe object to extract properties from

Returns Array An array of the object’s own properties.

Added in v0.1.0

Returns a list containing the names of all the enumerable own properties of the supplied object. Note that the order of the output array is not guaranteed to be consistent across different JS platforms.

See also keysIn, values, toPairs.

  1. R.keys({a: 1, b: 2, c: 3}); //=> ['a', 'b', 'c']

omit

[String] → {String: *} → {String: *}

Parameters

  • namesan array of String property names to omit from the new object
  • objThe object to copy from

Returns Object A new object with properties from names not on it.

Added in v0.1.0

Returns a partial copy of an object omitting the keys specified.

See also pick.

  1. R.omit(['a', 'd'], {a: 1, b: 2, c: 3, d: 4}); //=> {b: 2, c: 3}

pick

[k] → {k: v} → {k: v}

Parameters

  • namesan array of String property names to copy onto a new object
  • objThe object to copy from

Returns Object A new object with only properties from names on it.

Added in v0.1.0

Returns a partial copy of an object containing only the keys specified. If the key does not exist, the property is ignored.

See also omit, props.

  1. R.pick(['a', 'd'], {a: 1, b: 2, c: 3, d: 4}); //=> {a: 1, d: 4}
  2. R.pick(['a', 'e', 'f'], {a: 1, b: 2, c: 3, d: 4}); //=> {a: 1}

pickAll

[k] → {k: v} → {k: v}

Parameters

  • namesan array of String property names to copy onto a new object
  • objThe object to copy from

Returns Object A new object with only properties from names on it.

Added in v0.1.0

Similar to pick except that this one includes a key: undefined pair for properties that don’t exist.

See also pick.

  1. R.pickAll(['a', 'd'], {a: 1, b: 2, c: 3, d: 4}); //=> {a: 1, d: 4}
  2. R.pickAll(['a', 'e', 'f'], {a: 1, b: 2, c: 3, d: 4}); //=> {a: 1, e: undefined, f: undefined}

project

[k] → [{k: v}] → [{k: v}]

Parameters

  • propsThe property names to project
  • objsThe objects to query

Returns Array An array of objects with just the props properties.

Added in v0.1.0

Reasonable analog to SQL select statement.

See also pluck, props, prop.

  1. const abby = {name: 'Abby', age: 7, hair: 'blond', grade: 2};
  2. const fred = {name: 'Fred', age: 12, hair: 'brown', grade: 7};
  3. const kids = [abby, fred];
  4. R.project(['name', 'grade'], kids); //=> [{name: 'Abby', grade: 2}, {name: 'Fred', grade: 7}]

prop

Idx → {s: a} → a | Undefined

Idx = String | Int | Symbol

Parameters

  • pThe property name or array index
  • objThe object to query

Returns * The value at obj.p.

Added in v0.1.0

Returns a function that when supplied an object returns the indicated property of that object, if it exists.

See also path, props, pluck, project, nth.

  1. R.prop('x', {x: 100}); //=> 100
  2. R.prop('x', {}); //=> undefined
  3. R.prop(0, [100]); //=> 100
  4. R.compose(R.inc, R.prop('x'))({ x: 3 }) //=> 4

props

[k] → {k: v} → [v]

Parameters

  • psThe property names to fetch
  • objThe object to query

Returns Array The corresponding values or partially applied function.

Added in v0.1.0

Acts as multiple prop: array of keys in, array of values out. Preserves order.

See also prop, pluck, project.

  1. R.props(['x', 'y'], {x: 1, y: 2}); //=> [1, 2]
  2. R.props(['c', 'a', 'b'], {b: 2, a: 1}); //=> [undefined, 1, 2]
  4. const fullName = R.compose(R.join(' '), R.props(['first', 'last']));
  5. fullName({last: 'Bullet-Tooth', age: 33, first: 'Tony'}); //=> 'Tony Bullet-Tooth'

keysIn

{k: v} → [k]

Parameters

  • objThe object to extract properties from

Returns Array An array of the object’s own and prototype properties.

Added in v0.2.0

Returns a list containing the names of all the properties of the supplied object, including prototype properties. Note that the order of the output array is not guaranteed to be consistent across different JS platforms.

See also keys, valuesIn.

  1. const F = function() { this.x = 'X'; };
  2. F.prototype.y = 'Y';
  3. const f = new F();
  4. R.keysIn(f); //=> ['x', 'y']

path

[Idx] → {a} → a | Undefined

Idx = String | NonNegativeInt

Idx = String | Int | Symbol

Parameters

  • pathThe path to use.
  • objThe object or array to retrieve the nested property from.

Returns * The data at path.

Added in v0.2.0

Retrieves the value at a given path. The nodes of the path can be arbitrary strings or non-negative integers. For anything else, the value is unspecified. Integer paths are meant to index arrays, strings are meant for objects.

See also prop, nth, assocPath, dissocPath.

  1. R.path(['a', 'b'], {a: {b: 2}}); //=> 2
  2. R.path(['a', 'b'], {c: {b: 2}}); //=> undefined
  3. R.path(['a', 'b', 0], {a: {b: [1, 2, 3]}}); //=> 1
  4. R.path(['a', 'b', -2], {a: {b: [1, 2, 3]}}); //=> 2
  5. R.path([2], {'2': 2}); //=> 2
  6. R.path([-2], {'-2': 'a'}); //=> undefined

valuesIn

{k: v} → [v]

Parameters

  • objThe object to extract values from

Returns Array An array of the values of the object’s own and prototype properties.

Added in v0.2.0

Returns a list of all the properties, including prototype properties, of the supplied object. Note that the order of the output array is not guaranteed to be consistent across different JS platforms.

See also values, keysIn.

  1. const F = function() { this.x = 'X'; };
  2. F.prototype.y = 'Y';
  3. const f = new F();
  4. R.valuesIn(f); //=> ['X', 'Y']

toPairs

{String: *} → [[String,*]]

Parameters

  • objThe object to extract from

Returns Array An array of key, value arrays from the object’s own properties.

Added in v0.4.0

Converts an object into an array of key, value arrays. Only the object’s own properties are used. Note that the order of the output array is not guaranteed to be consistent across different JS platforms.

See also fromPairs, keys, values.

  1. R.toPairs({a: 1, b: 2, c: 3}); //=> [['a', 1], ['b', 2], ['c', 3]]

toPairsIn

{String: *} → [[String,*]]

Parameters

  • objThe object to extract from

Returns Array An array of key, value arrays from the object’s own and prototype properties.

Added in v0.4.0

Converts an object into an array of key, value arrays. The object’s own properties and prototype properties are used. Note that the order of the output array is not guaranteed to be consistent across different JS platforms.

  1. const F = function() { this.x = 'X'; };
  2. F.prototype.y = 'Y';
  3. const f = new F();
  4. R.toPairsIn(f); //=> [['x','X'], ['y','Y']]

propOr

a → String → Object → a

Parameters

  • valThe default value.
  • pThe name of the property to return.
  • objThe object to query.

Returns * The value of given property of the supplied object or the default value.

Added in v0.6.0

Return the specified property of the given non-null object if the property is present and it’s value is not null, undefined or NaN.

Otherwise the first argument is returned.

  1. const alice = {
  2.     name: 'ALICE',
  3.     age: 101
  4. };
  5. const favorite = R.prop('favoriteLibrary');
  6. const favoriteWithDefault = R.propOr('Ramda', 'favoriteLibrary');
  8. favorite(alice);  //=> undefined
  9. favoriteWithDefault(alice);  //=> 'Ramda'

has

s → {s: x} → Boolean

Parameters

  • propThe name of the property to check for.
  • objThe object to query.

Returns Boolean Whether the property exists.

Added in v0.7.0

Returns whether or not an object has an own property with the specified name

  1. const hasName = R.has('name');
  2. hasName({name: 'alice'});   //=> true
  3. hasName({name: 'bob'});     //=> true
  4. hasName({});                //=> false
  6. const point = {x: 0, y: 0};
  7. const pointHas = R.has(R.__, point);
  8. pointHas('x');  //=> true
  9. pointHas('y');  //=> true
  10. pointHas('z');  //=> false

hasIn

s → {s: x} → Boolean

Parameters

  • propThe name of the property to check for.
  • objThe object to query.

Returns Boolean Whether the property exists.

Added in v0.7.0

Returns whether or not an object or its prototype chain has a property with the specified name

  1. function Rectangle(width, height) {
  2.     this.width = width;
  3.     this.height = height;
  4. }
  5. Rectangle.prototype.area = function() {
  6.     return this.width * this.height;
  7. };
  9. const square = new Rectangle(2, 2);
  10. R.hasIn('width', square);  //=> true
  11. R.hasIn('area', square);  //=> true

assoc

Idx → a → {k: v} → {k: v}

Idx = String | Int

Parameters

  • propThe property name to set
  • valThe new value
  • objThe object to clone

Returns Object A new object equivalent to the original except for the changed property.

Added in v0.8.0

Makes a shallow clone of an object, setting or overriding the specified property with the given value. Note that this copies and flattens prototype properties onto the new object as well. All non-primitive properties are copied by reference.

See also dissoc, pick.

  1. R.assoc('c', 3, {a: 1, b: 2}); //=> {a: 1, b: 2, c: 3}

assocPath

[Idx] → a → {a} → {a}

Idx = String | Int | Symbol

Parameters

  • paththe path to set
  • valThe new value
  • objThe object to clone

Returns Object A new object equivalent to the original except along the specified path.

Added in v0.8.0

Makes a shallow clone of an object, setting or overriding the nodes required to create the given path, and placing the specific value at the tail end of that path. Note that this copies and flattens prototype properties onto the new object as well. All non-primitive properties are copied by reference.

See also dissocPath.

  1. R.assocPath(['a', 'b', 'c'], 42, {a: {b: {c: 0}}}); //=> {a: {b: {c: 42}}}
  3. // Any missing or non-object keys in path will be overridden
  4. R.assocPath(['a', 'b', 'c'], 42, {a: 5}); //=> {a: {b: {c: 42}}}

lens

(s → a) → ((a, s) → s) → Lens s a

Lens s a = Functor f => (a → f a) → s → f s

Parameters

  • getter
  • setter

Returns Lens

Added in v0.8.0

Returns a lens for the given getter and setter functions. The getter “gets” the value of the focus; the setter “sets” the value of the focus. The setter should not mutate the data structure.

See also view, set, over, lensIndex, lensProp.

  1. const xLens = R.lens(R.prop('x'), R.assoc('x'));
  3. R.view(xLens, {x: 1, y: 2});            //=> 1
  4. R.set(xLens, 4, {x: 1, y: 2});          //=> {x: 4, y: 2}
  5. R.over(xLens, R.negate, {x: 1, y: 2});  //=> {x: -1, y: 2}

pickBy

((v, k) → Boolean) → {k: v} → {k: v}

Parameters

  • predA predicate to determine whether or not a key should be included on the output object.
  • objThe object to copy from

Returns Object A new object with only properties that satisfy pred on it.

Added in v0.8.0

Returns a partial copy of an object containing only the keys that satisfy the supplied predicate.

See also pick, filter.

  1. const isUpperCase = (val, key) => key.toUpperCase() === key;
  2. R.pickBy(isUpperCase, {a: 1, b: 2, A: 3, B: 4}); //=> {A: 3, B: 4}

evolve

{k: (v → v)} → {k: v} → {k: v}

Parameters

  • transformationsThe object specifying transformation functions to apply to the object.
  • objectThe object to be transformed.

Returns Object The transformed object.

Added in v0.9.0

Creates a new object by recursively evolving a shallow copy of object, according to the transformation functions. All non-primitive properties are copied by reference.

A transformation function will not be invoked if its corresponding key does not exist in the evolved object.

  1. const tomato = {firstName: '  Tomato ', data: {elapsed: 100, remaining: 1400}, id:123};
  2. const transformations = {
  3.     firstName: R.trim,
  4.     lastName: R.trim, // Will not get invoked.
  5.     data: {elapsed: R.add(1), remaining: R.add(-1)}
  6. };
  7. R.evolve(transformations, tomato); //=> {firstName: 'Tomato', data: {elapsed: 101, remaining: 1399}, id:123}

invert

{s: x} → {x: [ s, … ]}

Parameters

  • objThe object or array to invert

Returns Object out A new object with keys in an array.

Added in v0.9.0

Same as R.invertObj, however this accounts for objects with duplicate values by putting the values into an array.

See also invertObj.

  1. const raceResultsByFirstName = {
  2.     first: 'alice',
  3.     second: 'jake',
  4.     third: 'alice',
  5. };
  6. R.invert(raceResultsByFirstName);
  7. //=> { 'alice': ['first', 'third'], 'jake':['second'] }

invertObj

{s: x} → {x: s}

Parameters

  • objThe object or array to invert

Returns Object out A new object

Added in v0.9.0

Returns a new object with the keys of the given object as values, and the values of the given object, which are coerced to strings, as keys. Note that the last key found is preferred when handling the same value.

See also invert.

  1. const raceResults = {
  2.     first: 'alice',
  3.     second: 'jake'
  4. };
  5. R.invertObj(raceResults);
  6. //=> { 'alice': 'first', 'jake':'second' }
  8. // Alternatively:
  9. const raceResults = ['alice', 'jake'];
  10. R.invertObj(raceResults);
  11. //=> { 'alice': '0', 'jake':'1' }

mapObjIndexed

((*, String, Object) → *) → Object → Object

Added in v0.9.0

An Object-specific version of map. The function is applied to three arguments: (value, key, obj). If only the value is significant, use map instead.

See also map.

  1. const xyz = { x: 1, y: 2, z: 3 };
  2. const prependKeyAndDouble = (num, key, obj) => key + (num * 2);
  4. R.mapObjIndexed(prependKeyAndDouble, xyz); //=> { x: 'x2', y: 'y4', z: 'z6' }

dissoc

String → {k: v} → {k: v}

Parameters

  • propThe name of the property to dissociate
  • objThe object to clone

Returns Object A new object equivalent to the original but without the specified property

Added in v0.10.0

Returns a new object that does not contain a prop property.

See also assoc, omit.

  1. R.dissoc('b', {a: 1, b: 2, c: 3}); //=> {a: 1, c: 3}

dissocPath

[Idx] → {k: v} → {k: v}

Idx = String | Int | Symbol

Parameters

  • pathThe path to the value to omit
  • objThe object to clone

Returns Object A new object without the property at path

Added in v0.11.0

Makes a shallow clone of an object, omitting the property at the given path. Note that this copies and flattens prototype properties onto the new object as well. All non-primitive properties are copied by reference.

See also assocPath.

  1. R.dissocPath(['a', 'b', 'c'], {a: {b: {c: 42}}}); //=> {a: {b: {}}}

lensIndex

Number → Lens s a

Lens s a = Functor f => (a → f a) → s → f s

Added in v0.14.0

Returns a lens whose focus is the specified index.

See also view, set, over, nth.

  1. const headLens = R.lensIndex(0);
  3. R.view(headLens, ['a', 'b', 'c']);            //=> 'a'
  4. R.set(headLens, 'x', ['a', 'b', 'c']);        //=> ['x', 'b', 'c']
  5. R.over(headLens, R.toUpper, ['a', 'b', 'c']); //=> ['A', 'b', 'c']

lensProp

String → Lens s a

Lens s a = Functor f => (a → f a) → s → f s

Added in v0.14.0

Returns a lens whose focus is the specified property.

See also view, set, over.

  1. const xLens = R.lensProp('x');
  3. R.view(xLens, {x: 1, y: 2});            //=> 1
  4. R.set(xLens, 4, {x: 1, y: 2});          //=> {x: 4, y: 2}
  5. R.over(xLens, R.negate, {x: 1, y: 2});  //=> {x: -1, y: 2}

whereEq

{String: *} → {String: *} → Boolean

Parameters

  • spec
  • testObj

Returns Boolean

Added in v0.14.0

Takes a spec object and a test object; returns true if the test satisfies the spec, false otherwise. An object satisfies the spec if, for each of the spec’s own properties, accessing that property of the object gives the same value (in R.equals terms) as accessing that property of the spec.

whereEq is a specialization of where.

See also propEq, where.

  1. // pred :: Object -> Boolean
  2. const pred = R.whereEq({a: 1, b: 2});
  4. pred({a: 1});              //=> false
  5. pred({a: 1, b: 2});        //=> true
  6. pred({a: 1, b: 2, c: 3});  //=> true
  7. pred({a: 1, b: 1});        //=> false

over

Lens s a → (a → a) → s → s

Lens s a = Functor f => (a → f a) → s → f s

Added in v0.16.0

Returns the result of “setting” the portion of the given data structure focused by the given lens to the result of applying the given function to the focused value.

See also view, set, lens, lensIndex, lensProp, lensPath.

  1. const headLens = R.lensIndex(0);
  3. R.over(headLens, R.toUpper, ['foo', 'bar', 'baz']); //=> ['FOO', 'bar', 'baz']

set

Lens s a → a → s → s

Lens s a = Functor f => (a → f a) → s → f s

Added in v0.16.0

Returns the result of “setting” the portion of the given data structure focused by the given lens to the given value.

See also view, over, lens, lensIndex, lensProp, lensPath.

  1. const xLens = R.lensProp('x');
  3. R.set(xLens, 4, {x: 1, y: 2});  //=> {x: 4, y: 2}
  4. R.set(xLens, 8, {x: 1, y: 2});  //=> {x: 8, y: 2}

view

Lens s a → s → a

Lens s a = Functor f => (a → f a) → s → f s

Added in v0.16.0

Returns a “view” of the given data structure, determined by the given lens. The lens’s focus determines which portion of the data structure is visible.

See also set, over, lens, lensIndex, lensProp, lensPath.

  1. const xLens = R.lensProp('x');
  3. R.view(xLens, {x: 1, y: 2});  //=> 1
  4. R.view(xLens, {x: 4, y: 2});  //=> 4

objOf

String → a → {String:a}

Added in v0.18.0

Creates an object containing a single key:value pair.

See also pair.

  1. const matchPhrases = R.compose(
  2.   R.objOf('must'),
  3.   R.map(R.objOf('match_phrase'))
  4. );
  5. matchPhrases(['foo', 'bar', 'baz']); //=> {must: [{match_phrase: 'foo'}, {match_phrase: 'bar'}, {match_phrase: 'baz'}]}

pathOr

a → [Idx] → {a} → a

Idx = String | Int | Symbol

Parameters

  • dThe default value.
  • pThe path to use.
  • objThe object to retrieve the nested property from.

Returns * The data at path of the supplied object or the default value.

Added in v0.18.0

If the given, non-null object has a value at the given path, returns the value at that path. Otherwise returns the provided default value.

  1. R.pathOr('N/A', ['a', 'b'], {a: {b: 2}}); //=> 2
  2. R.pathOr('N/A', ['a', 'b'], {c: {b: 2}}); //=> "N/A"