feat: implement flip

src/functions.js

@@ -66,5 +66,33 @@ module.exports = {
   curry: fn => {
     assert_function(fn, 'curry: `fn` is not a function');
     return _curry(fn);
+  },
+
+  /**
+   * Takes a function `fn` of arity 2 (or more) and returns
+   * a (curried) version of it in which the first two parameters
+   * have been swapped.
+   *
+   * @example
+   * ```javascript
+   * const x = (a, b, c) => a + b + c;
+   * x('foo', 'bar', 'baz');
+   * //=> 'foobarbaz'
+   *
+   * const y = flip(x);
+   * y('foo')('bar', 'baz');
+   * //=> 'barfoobaz'
+   * ```
+   *
+   * @public
+   * @param {function()} fn
+   * @return {function()}
+   */
+  flip: fn => {
+    assert_function(fn, 'flip: `fn` is not a function');
+    return _curry(function (a, b) {
+      const [x, y, ...z] = Array.from(arguments);
+      return fn(y, x, ...z);
+    });
   }
-};
+};

test/flip.test.js

@@ -0,0 +1,28 @@
+const test = require('tape');
+const td = require('testdouble');
+const {flip} = require('../dist');
+
+test('flip inverts the order of the first two parameters.', t => {
+  const fn = td.function();
+  const flipped = flip(fn);
+  flipped('foo')('bar');
+  td.verify(fn('bar', 'foo'));
+  flipped('baz', 'bat');
+  td.verify(fn('bat', 'baz'));
+  t.end();
+});
+
+test('flip forwards the rest of the parameters.', t => {
+  const fn = td.function();
+  const flipped = flip(fn);
+  flipped('foo')('bar', 'baz');
+  td.verify(fn('bar', 'foo', 'baz'));
+  flipped('foo', 'bar', 'baz', 'bat');
+  td.verify(fn('bar', 'foo', 'baz', 'bat'));
+  t.end();
+});
+
+test('flip fails when not given a function.', t => {
+  t.throws(() => flip([]));
+  t.end();
+});