adds flow serial function application (#3441)

source/flow.js

@@ -0,0 +1,40 @@
+import applyTo from './applyTo.js';
+import _curry2 from './internal/_curry2.js';
+import _reduce from './internal/_reduce.js';
+
+/**
+ * Takes the value of an expression and applies it to a function
+ * which is the left-to-right serial composition of the functions
+ * given in the second argument.
+ *
+ * The functions in the pipeline should be unary functions.
+ *
+ * `flow` is helps to avoid introducing an extra function with named arguments
+ * for computing the result of a function pipeline which depends on given initial values.
+ * Rather than defining a referential transparent function `f = (_x, _y) => R.pipe(g(_x), h(_y), …)`
+ * which is only later needed once `z = f(x, y)`,
+ * the introduction of `f`, `_x` and `_y` can be avoided: `z = flow(x, [g, h(y),…]`
+ *
+ * In some libraries this function is named `pipe`.
+ *
+ * @func
+ * @memberOf R
+ * @since v0.30.0
+ * @category Function
+ * @sig a → [(a → b), …, (y → z)] → z
+ * @param {*} a The seed value
+ * @param {Array<Function>} pipeline functions composing the pipeline
+ * @return {*} z The result of applying the seed value to the function pipeline
+ * @see R.pipe
+ * @example
+ *      R.flow(9, [Math.sqrt, R.negate, R.inc]), //=> -2
+ *
+ *      const defaultName = 'Jane Doe';
+ *      const savedName = R.flow(localStorage.get('name'), [R.when(R.isNil(defaultName)), R.match(/(.+)\s/), R.nth(0)]);
+ *      const givenName = R.flow($givenNameInput.value, [R.trim, R.when(R.isEmpty, R.always(savedName))])
+ */
+var flow = _curry2(function flow(seed, pipeline) {
+  return _reduce(applyTo, seed, pipeline);
+});
+
+export default flow;

source/index.js

@@ -70,6 +70,7 @@ export { default as findLast } from './findLast.js';
 export { default as findLastIndex } from './findLastIndex.js';
 export { default as flatten } from './flatten.js';
 export { default as flip } from './flip.js';
+export { default as flow } from './flow.js';
 export { default as forEach } from './forEach.js';
 export { default as forEachObjIndexed } from './forEachObjIndexed.js';
 export { default as fromPairs } from  './fromPairs.js';

test/flow.js

@@ -0,0 +1,21 @@
+var R = require('../source/index.js');
+var eq = require('./shared/eq.js');
+
+describe('flow', function() {
+
+  it('is a binary function', function() {
+    eq(typeof R.flow, 'function');
+    eq(R.flow.length, 2);
+  });
+
+  it('applies the first argument to a left-to-right composed function', function() {
+    //  f :: [Number] -> [Number]
+    var f2 = R.flow(4, [Math.sqrt, R.multiply, R.map]);
+    var f3 = R.flow(9, [Math.sqrt, R.multiply, R.map]);
+
+    eq(f2([1, 2, 3]), [2, 4, 6]);
+    eq(f3([1, 2, 3]), [3, 6, 9]);
+
+    eq(R.flow(9, [Math.sqrt, R.negate, R.inc]), -2);
+  });
+});