ramda-utils
Utilities built on top of Ramda.
Installation
npm install @panosoft/ramda-utils
Usage
var Ru = require('@panosoft/ramda-utils');
API
applyTo
compareProps
complementC
createIndex
createIndexOpts
defaults
defaultsR
filterObj
filterObjR
isEmptyC
isNotEmptyC
matchGroups
mergeAllR
mergeR
path
pathCommon
pickValues
rmap
subsetOf
substring
sumProps
sumColumn
toNumber
toString
toDate
trace
zipApply
applyTo ( obj , fn )
Apply an object to a function
Arguments
-
obj
- An object. -
fn
- A function.
Example
var obj = {a: 'a'};
var fn = (obj) => obj.a;
Ru.applyTo(obj, fn) // 'a';
compareProps ( props , a , b )
Returns a curried comparator function that can be used with R.sort
. Supports any number of sort orders (i.e. property1 ascending, property 2 descending, etc.). It also supports type based sorting (i.e. recognizes Date
, Number
, etc. and sorts them appropriately).
Arguments
-
props
- A string or an array of strings used to determine the sort order to apply. Each string signifies a property name to compare. A'+'
prefix is used to signify ascending order and a'-'
prefix is used to signify descending order. -
a
- A value to compare. -
b
- A value to compare.
Example
var list = [
{ b: true, n: 10, s: 'test', d: new Date('1/1/2015') },
{ b: false, n: -1, s: 'aaaa', d: new Date('1/1/2015') },
{ b: true, n: 12, s: 'aaaa', d: new Date('1/1/2015') },
{ b: false, n: 3, s: 'xyz', d: new Date('1/1/2000') },
{ b: false, n: 12, s: 'aaaa', d: new Date('1/1/2015') }
];
var props = ['-d', '+s', '-n', 'b'];
R.sort(Ru.compareProps(props), list);
/*
[
{ b: false, n: 12, s: 'aaaa', d: new Date('1/1/2015') },
{ b: true, n: 12, s: 'aaaa', d: new Date('1/1/2015') },
{ b: false, n: -1, s: 'aaaa', d: new Date('1/1/2015') },
{ b: true, n: 10, s: 'test', d: new Date('1/1/2015') },
{ b: false, n: 3, s: 'xyz', d: new Date('1/1/2000') }
];
*/
complementC ( fn )
Returns a curried complement.
Arguments
-
fn
- A function.
Example
var fn = (a,b) => b;
fn(null, false) // false;
Ru.complementC(fn)(null)(false) // true;
createIndex ( keys, objs )
Returns an indexed for an array of objects. This is just a partially applied version of createIndexOpts
with default options
.
Arguments
-
keys
- An array of keys to index on. If multiple keys are given then the keys are created with the default delimiter between keys, |. To change this delimiter usecreateIndexOpts
. -
objs
- An array of objects to index.
Example with single key
var indexTestData = [
{a: 1, b: 'a', c: 'x'},
{a: 2, b: 'b', c: 'y'},
{a: 3, b: 'b', c: 'y'},
{a: 4, b: 'b', c: 'z'}
];
createIndex(['b'], indexTestData);
// {
// a: [{a: 1, b: 'a', c: 'x'}],
// b: [
// {a: 2, b: 'b', c: 'y'},
// {a: 3, b: 'b', c: 'y'},
// {a: 4, b: 'b', c: 'z'}
// ]
// }
Example with composite key
var indexTestData = [
{a: 1, b: 'a', c: 'x'},
{a: 2, b: 'b', c: 'y'},
{a: 3, b: 'b', c: 'y'},
{a: 4, b: 'b', c: 'z'}
];
createIndex(['b', 'c'], indexTestData);
// {
// 'a|x': [{a: 1, b: 'a', c: 'x'}],
// 'b|y': [
// {a: 2, b: 'b', c: 'y'},
// {a: 3, b: 'b', c: 'y'}
// ],
// 'b|z': [{a: 4, b: 'b', c: 'z'}]
// }
createIndexOpts ( options, keys, objs )
Returns an indexed for an array of objects with the specified options
.
Arguments
-
options
:-
unique
- (default:false
) Iftrue
then if a key is not unique and Exception is thrown. -
keyDelimiter
- (default:|
) The delimiter used between object values to build the index key. This MUST be a character that is guaranteed to NOT be in the values otherwise the index may not be built properly.
-
-
keys
- An array of keys to index on. -
objs
- An array of objects to index.
Examples
var indexTestData = [
{a: 1, b: 'a', c: 'x'},
{a: 2, b: 'b', c: 'y'},
{a: 3, b: 'b', c: 'y'},
{a: 4, b: 'b', c: 'z'}
];
createIndexOpts({keyDelimiter: '&'}, ['b', 'c'], indexTestData);
// {
// 'a&x': [{a: 1, b: 'a', c: 'x'}],
// 'b&y': [
// {a: 2, b: 'b', c: 'y'},
// {a: 3, b: 'b', c: 'y'}
// ],
// 'b&z': [{a: 4, b: 'b', c: 'z'}]
// }
defaults ( def , obj )
Creates a new object with the own properties of def
merged with the defined own properties of obj
.
Any properties of obj
that resolve to undefined
will be replaced by the corresponding properties in def
if they exist. Otherwise, properties that resolve to undefined
in both obj
and def
will be omitted in the returned object.
Arguments
-
def
- An object containing default properties. -
obj
- An object to default.
Example
var def = {a: 1, b: 2, c: 3};
var obj = {a: 4, b: undefined};
Ru.defaults(def, obj); // { a: 4, b: 2, c: 3 }
defaultsR ( def , obj )
RECURSIVE version of defaults
. NOTE: When comparing keys, recursion only occurs if both keys are objects, otherwise a simple non-recursive replacement occurs.
Arguments
-
def
- An object containing default properties. -
obj
- An object to default.
Example
var def = {a: 1, b: 2, c: 3, o: {x: 1, z: 3}};
var obj = {a: 4, b: undefined, o: {x: undefined, y: 2}};
Ru.defaultsR(def, obj); // {a: 4, b: 2, c: 3, o: {x: 1, y: 2, z: 3}}
filterObj ( pred , obj )
Filters an object by property.
Arguments
-
pred
- A function used to test each object property. It is called with the propertyvalue
and should return aBoolean
. -
obj
- An object to filter.
Example
var obj = {a: true, b: false, c: true};
var pred = (x) => x;
Ru.filterObj(pred, obj) // {a: true, c: true}
filterObjR ( pred , obj )
RECURSIVE version of filterObj
. NOTE: pred
is NOT applied to object keys which means all object keys (recursively) will be included.
Arguments
-
pred
- A function used to test each object property. It is called with the propertyvalue
and should return aBoolean
. -
obj
- An object to filter.
Example
var obj = {a: true, b: false, c: true, o: {a: true, b: false}};
var pred = (x) => x;
Ru.filterObjR(pred, obj) // {a: true, c: true, o: {a: true}}
isEmptyC ( fn )
Returns a curried function that tests whether the original function returns a list with zero elements when called.
Arguments
-
fn
- A function.
Example
var fn = (a,b) => a+b;
fn('a','b') // 'ab'
fn('','') // ''
Ru.isEmptyC(fn)('a')('b') // false;
Ru.isEmptyC(fn)('')('') // true;
isNotEmptyC ( fn )
Returns a curried function that tests whether the original function returns a list with elements when called.
Arguments
-
fn
- A function.
Example
var fn = (a,b) => a+b;
fn('a','b') // 'ab'
fn('','') // ''
Ru.isNotEmptyC(fn)('a')('b') // true;
Ru.isNotEmptyC(fn)('')('') // false;
matchGroups ( reg , str )
Applies a Regular Expression to a String and returns the matched groups as an array of arrays. Returns an empty array, [], if no match.
Arguments
-
reg
- A regular expression. -
str
- A string to search.
Example
var str = 'abcd abbbd ab___d';
var reg = /ab(.+?)(d)/g;
Ru.matchGroups(reg, str); // [ [ 'c', 'd'], [ 'bb', 'd' ], ['___', 'd'] ]
Ru.matchGroups(/xyz/, str); // []
mergeAllR ( objs )
RECURSIVE version of R.mergeAll (see Ramda). NOTE: When comparing keys, recursion only occurs if both keys are objects, otherwise a simple non-recursive replacement occurs.
Arguments
-
objs
- Array of objects to merge.
Example
var a = {a: 1, o: {a: 1, x: 1}};
var b = {b: 2, o: {b: 2, x: 2}};
var c = {c: 3, o: {c: 3, x: 3}};
R.mergeAllR([a, b, c]); // {a: 1, b:2, c: 3, o: {a: 1, b: 2, c: 3, x: 3}}
var a = {oo: 'a'}};
var b = {oo: {y: 2}}; // this replaces a non-object with {y: 2}
var c = {oo: {x: 1}};
R.mergeAllR([a, b, c]); // {oo: {x: 1, y: 2}}
var a = {oo: {y: 2}};
var b = {oo: 'a'}}; // this replaces the object {y: 2} with a non-object
var c = {oo: {x: 1}};
R.mergeAllR([a, b, c]); // {oo: {x: 1}}
mergeR ( a , b )
RECURSIVE version of R.merge (see Ramda). NOTE: When comparing keys, recursion only occurs if both keys are objects, otherwise a simple non-recursive replacement occurs.
Arguments
-
a
- First object to merge. -
b
- Second object to merge with first.
Example
var a = {a: 1, b: 2, d: 4, o: {x: 1, z: 3}};
var b = {a: 10, c: 30, o: {x: 10, y: 20}};
Ru.mergeR(a, b) // {a: 10, b: 2, c: 30, d: 4, o: {x: 10, y: 20, z: 3}}
Ru.mergeR(b, a) // {a: 1, b: 2, c: 30, d: 4, o: {x: 1, y: 20, z: 3}}
path ( path , obj )
Retrieve a value at a given path using the standard .
path delimiter.
Arguments
-
path
- A path to a value within an object. -
obj
- An object to retrieve value from.
Example
Ru.path('a.b', {a: {b: 1}}); // returns 1
pathCommon ( delimiter, path , obj )
Retrieve a value at a given path with the specified path delimiter
.
Arguments
-
delimiter
- A path delimiter. -
path
- A path to a value within an object. -
obj
- An object to retrieve value from.
Example
Ru.pathCommon('/', 'a/b', {a: {b: 1}}); // returns 1
pickValues ( keys , obj )
Picks values from an object using the specified keys. Returns a new array.
Arguments
-
keys
- A string or an array of strings corresponding to the keys of values to be picked. -
obj
- An object to pick values from.
Example
var obj = {a: true, b: false, c: true};
var keys = ['b', 'c'];
Ru.pickValues(keys, obj) // [false, true]
rmap ( obj , fns )
Maps an array of functions to their return values by applying an object to each.
Arguments
-
obj
- An object to apply. -
fns
- A function or an array of functions to map.
Example
var obj = {a: 'a', b: 'b'};
var fns = [(obj) => obj.a, (obj) => obj.b];
Ru.rmap(obj, fns) // ['a', 'b']
subsetOf ( set , sub )
Tests if an array is a subset of another.
Arguments
-
set
- An array that defines the complete set. -
sub
- An array to test.
Example
var set = [1, 2, 3, 4];
var sub = [2, 3];
var notSub = [4, 5];
Ru.subsetOf(set, sub); // true
Ru.subsetOf(set, notSub)); // false
substring ( start , end, str )
Returns the substring of the specified string. This function differs from the standard JavaScript function in the case where end
is null
. In that case, end behaves as if it were not specified and will represent the end of the string.
Arguments
-
start
- An integer between 0 and the length of the string, specifying the offset into the string of the first character to include in the returned substring. -
end
- An integer between 0 and the length of the string, which specifies the offset into the string of the first character not to include in the returned substring. Ifnull
, then it will extract characters until the end of the string.
Example
substring(1, 2, 'abc'); // 'b'
substring(1, null, 'abc'); // 'bc'
sumProps ( keys , obj )
Returns the sum of the specified properties.
Arguments
-
keys
- An array of strings used to determine which properties to sum. -
obj
- An object containing the specified keys.
Example
var obj = {a: 1, b: 2, c: 4};
var keys = ['b', 'c'];
Ru.sumProps(keys, obj); // 6
sumColumn ( key , objs )
Return the sum of the specified property across an array of objects.
Arguments
-
key
- A string used to determine which property to sum. -
objs
- An object or an array of objects containing the specified key.
Example
var objs = [{a: 1}, {a: 2}, {a: 4}];
var key = 'a';
Ru.sumColumn(key, objs) // 7
toNumber ( x )
Converts a value to a Number
.
Arguments
-
x
- A value to convert.
Example
var str = '1';
Ru.toNumber(str) // 1
toString ( x )
Converts a value to a String
.
Arguments
-
x
- A value to convert.
Example
var num = 1;
Ru.toString(num) // '1'
toDate ( x )
Convert a value to a Date
.
Arguments
-
x
- A value to convert.
Example
var str = '1/1/2000';
Ru.toDate(str) // new Date(str)
trace ( msg , x )
Logs a message and value and then returns the value.
Arguments
-
msg
- A string message to log. -
x
- A value to log and return.
Example
var msg = 'X:';
var fn = R.compose(R.add(1), Ru.trace(msg), R.add(1));
var result = fn(1); // stdout: 'X: 3'
console.log(result); // 3
zipApply ( fns , objs )
Zips an array of functions and an array of objects into an array of values produced by applying each object to its respective function.
Arguments
-
fns
- An array of functions. -
objs
- An array of objects.
Example
var objs = [{a: 'a'}, {b: 'b'}];
var fns = [(obj) => obj.a, (obj) => obj.b];
Ru.zipApply(fns, objs) // ['a', 'b']