feat(converge): added a converge function

src/function/converge.js

@@ -0,0 +1,29 @@
+import _curry3 from '../_internals/_curry3'
+import map from '../array/map'
+
+/**
+ * @name converge
+ * @since v1.3.0
+ * @function
+ * @category Function
+ * @sig (...b -> c) -> [...(a -> b)] -> a -> c
+ * @description Takes a converging function, a list of data functions, and the data itself. Runs the data through each data function individually, and then passes the array of values to the converging function.
+ * @param {Function} convFn The converging function our array of data is given to
+ * @param {Array} fns The array of data functions to run our data with
+ * @param {Any} data The data we want to converge with
+ * @return {Any} The results of the converging function
+ * @example
+ * import { converge, divide, length, sum } from 'kyanite'
+ *
+ * converge(divide, [sum, length], [1, 2, 3, 4, 5, 6, 7]) // => 4
+ *
+ * // It's also curried
+ * const fn = converge(divide, [sum, length])
+ *
+ * fn([1, 2, 3, 4, 5, 6, 7]) // => 4
+ * fn([1, 2, 3]) // => 2
+ */
+const converge = (convFn, fns, data) =>
+  convFn(...map(f => f(data), fns))
+
+export default _curry3(converge)

tests/function/converge.js

@@ -0,0 +1,35 @@
+import test from 'tape'
+import converge from '../../src/function/converge'
+
+function sum (nums) {
+  return nums.reduce((acc, v) => acc + v, 0)
+}
+
+function length (list) {
+  return list.length
+}
+
+function divide (a, b) {
+  return a / b
+}
+
+test('converge() -- Basic', t => {
+  const average = converge(divide, [sum, length], [1, 2, 3, 4, 5, 6, 7])
+
+  t.same(average, 4, 'Gets the average of 4 from the array')
+  t.end()
+})
+
+test('converge() -- Is curried', t => {
+  const fn = converge(divide, [sum, length])
+  const interchange = converge(divide)
+
+  t.same(typeof interchange, 'function', 'Interchange is a function')
+  t.same(typeof interchange([sum, length]), 'function', 'Calling interchange with 1 param returns function')
+  t.same(typeof fn, 'function', 'fn is a function')
+  t.same(interchange([sum, length], [1, 2, 3]), 2, 'Giving 2 params to interchange runs the converge function fully')
+  t.same(fn([1, 2, 3, 4, 5, 6, 7]), 4, 'Average of 4')
+  t.same(fn([1, 2, 3]), 2, 'Average of 2')
+  t.same(fn([90, 47, 20, 13, 12]), 36.4, 'Average of 36.4')
+  t.end()
+})