ramda-adjunct 2.34.0

package/src/cata.js

@@ -0,0 +1,86 @@
+import { curry } from 'ramda';
+
+import isFunction from './isFunction';
+
+/**
+ * The catamorphism is a way of folding a type into a value.
+ *
+ * **Either**
+ *
+ * If the either is right then the right function will be executed with
+ * the `right` value and the value of the function returned. Otherwise the left function
+ * will be called with the `left` value.
+ *
+ * **Maybe**
+ *
+ * If the maybe is Some than the right function will be executed with the `some` value and the value of the function
+ * returned. Otherwise the left function with be called without an argument.
+ *
+ * **Result**
+ *
+ * If the result is Ok than the right function will be executed with the `Ok` value and the value of the function
+ * returned. Otherwise the left function will be called with the `Error` value.
+ *
+ * **Validation**
+ *
+ * If the validation is Success than the right function will be executed with the `Success` value and the value of the function
+ * returned. Otherwise the left function will be called with the `Failure` value.
+ *
+ * Supported monadic libraries: {@link https://monet.github.io/monet.js/|monet.js}, {@link https://folktale.origamitower.com/|folktale}, {@link https://github.com/ramda/ramda-fantasy|ramda-fantasy}
+ *
+ * @func cata
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/1.4.0|v1.4.0}
+ * @category Function
+ * @sig (a -> b) -> (a -> c) -> Cata a -> b | c
+ * @param {Function} leftFn The left function that consumes the left value
+ * @param {Function} rightFn The right function that consumes the right value
+ * @param {Cata} catamorphicObj Either, Maybe or any other type with catamorphic capabilities (`cata` or `either` method)
+ * @return {*}
+ * @see {@link https://monet.github.io/monet.js/#cata|cata explained}
+ * @example
+ *
+ * // Either
+ * const eitherR = Either.Right(1);
+ * const eitherL = Either.Left(2);
+ *
+ * RA.cata(identity, identity, eitherR); //=> 1
+ * RA.cata(identity, identity, eitherL); //=> 2
+ *
+ * // Maybe
+ * const maybeSome = Maybe.Some(1);
+ * const maybeNothing = Maybe.Nothing();
+ *
+ * RA.cata(identity, identity, maybeSome); //=> 1
+ * RA.cata(identity, identity, maybeNothing); //=> undefined
+ */
+const catamorphism = curry((leftFn, rightFn, catamorphicObj) => {
+  // folktale support
+  if (isFunction(catamorphicObj.matchWith)) {
+    return catamorphicObj.matchWith({
+      // Result type
+      Ok: ({ value }) => rightFn(value),
+      Error: ({ value }) => leftFn(value),
+      // Maybe type
+      Just: ({ value }) => rightFn(value),
+      Nothing: () => leftFn(undefined),
+      // Validation type
+      Success: ({ value }) => rightFn(value),
+      Failure: ({ value }) => leftFn(value),
+    });
+  }
+
+  if (isFunction(catamorphicObj.cata)) {
+    return catamorphicObj.cata(leftFn, rightFn);
+  }
+
+  if (isFunction(catamorphicObj.getOrElse)) {
+    const elseValue = `RA.cata${Math.random()}`;
+    const value = catamorphicObj.getOrElse(elseValue);
+    return value === elseValue ? leftFn() : rightFn(value);
+  }
+
+  return catamorphicObj.either(leftFn, rightFn);
+});
+
+export default catamorphism;

package/src/catchP.js

@@ -0,0 +1,25 @@
+import { invoker } from 'ramda';
+
+/**
+ * Composable shortcut for `Promise.catch`.
+ * The catchP function returns a Promise. It takes two arguments: a callback function for the failure of the Promise
+ * and the promise instance itself.
+ *
+ * @func catchP
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/2.29.0|v2.29.0}
+ * @category Function
+ * @sig (a -> Promise b | b) -> Promise b
+ * @param {Function} onRejected A Function called if the Promise is rejected. This function has one argument, the rejection reason.
+ * @param {Promise} promise Any Promise
+ * @return {Promise} Returns a Promise with dealt rejected cases
+ * @see {@link RA.thenP|thenP}, {@link RA.resolveP|resolveP}, {@link RA.rejectP|rejectP}, {@link RA.allP|allP}
+ *
+ * @example
+ *
+ * RA.catchP(() => 'b', Promise.resolve('a')); //=> Promise('a')
+ * RA.catchP(() => 'b', Promise.reject('a')); //=> Promise('b')
+ */
+const catchP = invoker(1, 'catch');
+
+export default catchP;

package/src/ceil.js

@@ -0,0 +1,28 @@
+import { bind, curryN } from 'ramda';
+
+/**
+ * Returns the smallest integer greater than or equal to a given number.
+ *
+ * Note: ceil(null) returns integer 0 and does not give a NaN error.
+ *
+ * @func ceil
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/2.15.0|v2.15.0}
+ * @category Math
+ * @sig Number -> Number
+ * @param {number} number The number to ceil
+ * @return {number} The smallest integer greater than or equal to the given number
+ * @example
+ *
+ * RA.ceil(.95); //=> 1
+ * RA.ceil(4); //=> 4
+ * RA.ceil(7.004); //=> 8
+ * RA.ceil(-0.95); //=> -0
+ * RA.ceil(-4); //=> -4
+ * RA.ceil(-7.004); //=> -7
+ * RA.ceil(null); //=> 0
+ */
+
+const ceil = curryN(1, bind(Math.ceil, Math));
+
+export default ceil;

package/src/compact.js

@@ -0,0 +1,23 @@
+import { reject } from 'ramda';
+
+import isFalsy from './isFalsy';
+
+/**
+ * Creates an array with all falsy values removed.
+ * The values false, null, 0, "", undefined, and NaN are falsy.
+ *
+ * @func compact
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/2.5.0|v2.5.0}
+ * @category List
+ * @sig Filterable f => f a -> f a
+ * @param {Array} list The array to compact
+ * @return {Array} Returns the new array of filtered values
+ * @see {@link RA.isFalsy|isFalsy}
+ * @example
+ *
+ * RA.compact([0, 1, false, 2, '', 3]); //=> [1, 2, 3]
+ */
+const compact = reject(isFalsy);
+
+export default compact;

package/src/concatAll.js

@@ -0,0 +1,34 @@
+import { concat, identical, identity, pipe, reduce, when } from 'ramda';
+
+import stubUndefined from './stubUndefined';
+
+const leftIdentitySemigroup = { concat: identity };
+
+/**
+ * Returns the result of concatenating the given lists or strings.
+ * Note: RA.concatAll expects all elements to be of the same type. It will throw an error if you concat an Array with a non-Array value.
+ * Dispatches to the concat method of the preceding element, if present. Can also concatenate multiple elements of a [fantasy-land compatible semigroup](https://github.com/fantasyland/fantasy-land#semigroup).
+ * Returns undefined if empty array was passed.
+ *
+ * @func concatAll
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/2.6.0|v2.6.0}
+ * @category List
+ * @sig [[a]] -> [a] | Undefined
+ * @sig [String] -> String | Undefined
+ * @sig Semigroup s => Foldable s f => f -> s | Undefined
+ * @param {Array.<Array|string>} list List containing elements that will be concatenated
+ * @return {Array|string|undefined} Concatenated elements
+ * @see {@link http://ramdajs.com/docs/#concat|R.concat}, {@link RA.concatRight|concatRight}, {@link http://ramdajs.com/docs/#unnest|R.unnest}, {@link http://ramdajs.com/docs/#join|R.join}
+ * @example
+ *
+ * concatAll([[1], [2], [3]]); //=> [1, 2, 3]
+ * concatAll(['1', '2', '3']); //=> '123'
+ * concatAll([]); //=> undefined;
+ */
+const concatAll = pipe(
+  reduce(concat, leftIdentitySemigroup),
+  when(identical(leftIdentitySemigroup), stubUndefined)
+);
+
+export default concatAll;

package/src/concatRight.js

@@ -0,0 +1,30 @@
+import { concat, flip } from 'ramda';
+
+/**
+ * Returns the result of concatenating the given lists or strings.
+ *
+ * Note: R.concat expects both arguments to be of the same type, unlike
+ * the native Array.prototype.concat method.
+ * It will throw an error if you concat an Array with a non-Array value.
+ * Dispatches to the concat method of the second argument, if present.
+ *
+ * @func concatRight
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/1.11.0|v1.11.0}
+ * @category List
+ * @sig [a] -> [a] -> [a]
+ * @sig String -> String -> String
+ * @param {Array|String} firstList The first list
+ * @param {Array|String} secondList The second list
+ * @return {Array|String} A list consisting of the elements of `secondList`
+ * followed by the elements of `firstList`.
+ * @see {@link http://ramdajs.com/docs/#concat|R.concat}
+ * @example
+ *
+ * RA.concatRight('ABC', 'DEF'); //=> 'DEFABC'
+ * RA.concatRight([4, 5, 6], [1, 2, 3]); //=> [1, 2, 3, 4, 5, 6]
+ * RA.concatRight([], []); //=> []
+ */
+const concatRight = flip(concat);
+
+export default concatRight;

package/src/contained.js

@@ -0,0 +1,30 @@
+import { flip, contains } from 'ramda';
+
+/**
+ * Returns true if the specified value is equal, in R.equals terms,
+ * to at least one element of the given list or false otherwise.
+ * Given list can be a string.
+ *
+ * Like {@link http://ramdajs.com/docs/#contains|R.contains} but with argument order reversed.
+ *
+ * @func contained
+ * @aliases included
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/2.8.0|v2.8.0}
+ * @deprecated since v2.12.0; please use RA.included alias
+ * @category List
+ * @sig [a] -> a -> Boolean
+ * @param {Array|String} list The list to consider
+ * @param {*} a The item to compare against
+ * @return {boolean} Returns Boolean `true` if an equivalent item is in the list or `false` otherwise
+ * @see {@link http://ramdajs.com/docs/#contains|R.contains}
+ * @example
+ *
+ * RA.contained([1, 2, 3], 3); //=> true
+ * RA.contained([1, 2, 3], 4); //=> false
+ * RA.contained([{ name: 'Fred' }], { name: 'Fred' }); //=> true
+ * RA.contained([[42]], [42]); //=> true
+ */
+const contained = flip(contains);
+
+export default contained;

package/src/curryRight.js

@@ -0,0 +1,26 @@
+import { converge, length, identity } from 'ramda';
+
+import curryRightN from './curryRightN';
+
+/**
+ * Returns a curried equivalent of the provided function.
+ * This function is like curry, except that the provided arguments order is reversed.
+ *
+ * @func curryRight
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/1.12.0|v1.12.0}
+ * @category Function
+ * @sig (* -> a) -> (* -> a)
+ * @param {Function} fn The function to curry
+ * @return {Function}  A new, curried function
+ * @see {@link http://ramdajs.com/docs/#curry|R.curry}, {@link RA.curryRightN|curryRightN}
+ * @example
+ *
+ * const concatStrings = (a, b, c) => a + b + c;
+ * const concatStringsCurried = RA.curryRight(concatStrings);
+ *
+ * concatStringCurried('a')('b')('c'); // => 'cba'
+ */
+const curryRight = converge(curryRightN, [length, identity]);
+
+export default curryRight;

package/src/curryRightN.js

@@ -0,0 +1,29 @@
+import { curryN, reverse } from 'ramda';
+
+/**
+ * Returns a curried equivalent of the provided function, with the specified arity.
+ * This function is like curryN, except that the provided arguments order is reversed.
+ *
+ * @func curryRightN
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/1.12.0|v1.12.0}
+ * @category Function
+ * @sig Number -> (* -> a) -> (* -> a)
+ * @param {number} length The arity for the returned function
+ * @param {Function} fn The function to curry
+ * @return {Function}  A new, curried function
+ * @see {@link http://ramdajs.com/docs/#curryN|R.curryN}, {@link RA.curryRight|curryRight}
+ * @example
+ *
+ * const concatStrings = (a, b, c) => a + b + c;
+ * const concatStringsCurried = RA.curryRightN(3, concatStrings);
+ *
+ * concatStringCurried('a')('b')('c'); // => 'cba'
+ */
+const curryRightN = curryN(2, (arity, fn) =>
+  curryN(arity, function wrapper(...args) {
+    return fn.apply(this, reverse(args));
+  })
+);
+
+export default curryRightN;

package/src/defaultWhen.js

@@ -0,0 +1,26 @@
+import { curry } from 'ramda';
+
+/**
+ * Returns the second argument if predicate function returns `true`,
+ * otherwise the third argument is returned.
+ *
+ * @func defaultWhen
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/2.2.0|v2.2.0}
+ * @category Logic
+ * @sig  (a -> Boolean) -> b -> a -> a | b
+ * @param {!function} predicate The predicate function
+ * @param {*} defaultVal The default value
+ * @param {*} val `val` will be returned instead of `defaultVal` if predicate returns false
+ * @return {*} The `val` if predicate returns `false`, otherwise the default value
+ * @see {@link http://ramdajs.com/docs/#defaultTo|R.defaultTo}
+ * @example
+ *
+ * RA.defaultWhen(RA.isNull, 1, null); // => 1
+ * RA.defaultWhen(RA.isNull, 1, 2); // => 2
+ */
+const defaultWhen = curry((predicate, defaultVal, val) =>
+  predicate(val) ? defaultVal : val
+);
+
+export default defaultWhen;

package/src/delayP.js

@@ -0,0 +1,45 @@
+import { curry, propOr, partial, nth } from 'ramda';
+
+import isNonNegative from './isNonNegative';
+import isInteger from './isInteger';
+
+/**
+ * Creates a promise which resolves/rejects after the specified milliseconds.
+ *
+ * @func delayP
+ * @memberOf RA
+ * @category Function
+ * @sig Number -> Promise Undefined
+ * @sig {timeout: Number, value: a} -> Promise a
+ * @param {number|Object} milliseconds number of milliseconds or options object
+ * @return {Promise} A Promise that is resolved/rejected with the given value (if provided) after the specified delay
+ * @example
+ *
+ * RA.delayP(200); //=> Promise(undefined)
+ * RA.delayP({ timeout: 1000, value: 'hello world' }); //=> Promise('hello world')
+ * RA.delayP.reject(100); //=> Promise(undefined)
+ * RA.delayP.reject({ timeout: 100, value: new Error('error') }); //=> Promise(Error('error'))
+ */
+
+const makeDelay = curry((settleFnPicker, opts) => {
+  let timeout;
+  let value;
+
+  if (isInteger(opts) && isNonNegative(opts)) {
+    timeout = opts;
+  } else {
+    timeout = propOr(0, 'timeout', opts);
+    value = propOr(value, 'value', opts);
+  }
+
+  return new Promise((...args) => {
+    const settleFn = settleFnPicker(args);
+
+    setTimeout(partial(settleFn, [value]), timeout);
+  });
+});
+
+const delayP = makeDelay(nth(0));
+delayP.reject = makeDelay(nth(1));
+
+export default delayP;

package/src/dispatch.js

@@ -0,0 +1,74 @@
+import {
+  sort,
+  comparator,
+  prop,
+  pipe,
+  head,
+  curryN,
+  reduce,
+  reduced,
+  curry,
+  ifElse,
+} from 'ramda';
+
+/**
+ * Can be used as a way to compose multiple invokers together to form polymorphic functions,
+ * or functions that exhibit different behaviors based on their argument(s).
+ * Consumes dispatching functions and keep trying to invoke each in turn, until a non-nil value is returned.
+ *
+ * Accepts a list of dispatching functions and returns a new function.
+ * When invoked, this new function is applied to some arguments,
+ * each dispatching function is applied to those same arguments until one of the
+ * dispatching functions returns a non-nil value.
+ *
+ * @func dispatch
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/2.6.0|v2.6.0}
+ * @category Function
+ * @sig [((a, b, ...) -> x1), ((a, b, ...) -> x2), ...] -> x1 | x2 | ...
+ * @param {!Array} functions A list of functions
+ * @return {*|undefined} Returns the first not-nil value, or undefined if either an empty list is provided or none of the dispatching functions returns a non-nil value
+ * @see {@link RA.isNotNil}
+ * @example
+ *
+ * // returns first non-nil value
+ * const stubNil = () => null;
+ * const stubUndefined = () => undefined;
+ * const addOne = v => v + 1;
+ * const addTwo = v => v + 2;
+ *
+ * RA.dispatch([stubNil, stubUndefined, addOne, addTwo])(1); //=> 2
+ *
+ * // acts as a switch
+ * const fnSwitch = RA.dispatch([
+ *   R.ifElse(RA.isString, s => `${s}-join`, RA.stubUndefined),
+ *   R.ifElse(RA.isNumber, n => n + 1, RA.stubUndefined),
+ *   R.ifElse(RA.isDate, R.T, RA.stubUndefined),
+ * ]);
+ * fnSwitch(1); //=> 2
+ */
+import isNotNil from './isNotNil';
+import isNonEmptyArray from './isNonEmptyArray';
+import stubUndefined from './stubUndefined';
+
+const byArity = comparator((a, b) => a.length > b.length);
+
+const getMaxArity = pipe(sort(byArity), head, prop('length'));
+
+const iteratorFn = curry((args, accumulator, fn) => {
+  const result = fn(...args);
+
+  return isNotNil(result) ? reduced(result) : accumulator;
+});
+
+const dispatchImpl = (functions) => {
+  const arity = getMaxArity(functions);
+
+  return curryN(arity, (...args) =>
+    reduce(iteratorFn(args), undefined, functions)
+  );
+};
+
+const dispatch = ifElse(isNonEmptyArray, dispatchImpl, stubUndefined);
+
+export default dispatch;

package/src/divideNum.js

@@ -0,0 +1,20 @@
+import { divide, flip } from 'ramda';
+
+/**
+ * Divides two numbers, where the second number is divided by the first number.
+ *
+ * @func divideNum
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/2.22.0|v2.22.0}
+ * @category Math
+ * @sig Number -> Number -> Number
+ * @param {number} divisor the number to divide by
+ * @param {number} dividend the number to divide
+ * @return {number} A number representing the quotient of dividing the dividend by the divisor
+ * @example
+ *
+ * RA.divideNum(2, 1); //=> 0.5
+ */
+const divideNum = flip(divide);
+
+export default divideNum;

package/src/dropArgs.js

@@ -0,0 +1,23 @@
+import { nAry } from 'ramda';
+
+/**
+ * Accepts a function with any arity and returns a function with arity of zero.
+ * The returned function ignores any arguments supplied to it.
+ *
+ * @func dropArgs
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/2.10.0|v2.10.0}
+ * @category Logic
+ * @sig (...a -> b)-> () -> b
+ * @param {Function} fn The function with any arity
+ * @return {Function} Returns function with arity of zero
+ * @see {@link http://ramdajs.com/docs/#nAry|R.nAry}
+ * @example
+ *
+ * const fn = (a = 1, b = 2) => a + b;
+ *
+ * RA.dropArgs(fn)('ignore1', 'ignore2'); //=> 3
+ */
+const dropArgs = nAry(0);
+
+export default dropArgs;

package/src/ensureArray.js

@@ -0,0 +1,24 @@
+import { when, of } from 'ramda';
+
+import isNotArray from './isNotArray';
+
+/**
+ * Returns a singleton array containing the value provided.
+ * If value is already an array, it is returned as is.
+ *
+ * @func ensureArray
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/2.6.0|v2.6.0}
+ * @category List
+ * @sig a | [a] -> [a]
+ * @param {*|Array} val the value ensure as Array
+ * @return {Array}
+ * @see {@link http://ramdajs.com/docs/#of|R.of}
+ * @example
+ *
+ * RA.ensureArray(42); //=> [42]
+ * RA.ensureArray([42]); //=> [42]
+ */
+const ensureArray = when(isNotArray, of);
+
+export default ensureArray;

package/src/escapeRegExp.js

@@ -0,0 +1,22 @@
+import { when, replace } from 'ramda';
+
+import isString from './isString';
+
+/**
+ * Escapes the RegExp special characters.
+ *
+ * @func escapeRegExp
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/2.21.0|v2.21.0}
+ * @category String
+ * @sig String -> String
+ * @param {string} val the value to escape
+ * @return {string}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#Escaping|MDN Regular Expressions Escaping}
+ * @example
+ *
+ * RA.escapeRegExp('[ramda-adjunct](https://github.com/char0n/ramda-adjunct)'); //=> '\[ramda\-adjunct\]\(https://github\.com/char0n/ramda\-adjunct\)'
+ */
+const escapeRegExp = when(isString, replace(/[.*+?^${}()|[\]\\-]/g, '\\$&'));
+
+export default escapeRegExp;