@panosoft/ramda-utils

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 use createIndexOpts.
• 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) If true 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 property value and should return a Boolean.
• 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 property value and should return a Boolean.
• 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. If null, 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']