feat: add traversable lenses (#494)

src/index.d.ts

@@ -677,6 +677,19 @@ declare namespace RamdaAdjunct {
             from(lens: Function): Function,
         };
 
+        /**
+         * Creates a [Traversable](https://github.com/fantasyland/fantasy-land#traversable) lens
+         * from an [Applicative](https://github.com/fantasyland/fantasy-land#applicative)-returning function.
+         *
+         * When executed, it maps an [Applicative](https://github.com/fantasyland/fantasy-land#applicative)-returning
+         * function over a [Traversable](https://github.com/fantasyland/fantasy-land#traversable),
+         * then uses [`sequence`](#sequence) to transform the resulting Traversable of Applicative
+         * into an Applicative of Traversable.
+         *
+         * Dispatches to the `traverse` method of the third argument, if present.
+         */
+        lensTraverse(of: Function): Function;
+
         /**
          * Returns true if the specified object property is not equal,
          * in R.equals terms, to the given value; false otherwise.

src/index.js

@@ -131,6 +131,7 @@ export { default as lensEq } from './lensEq';
 export { default as lensNotEq } from './lensNotEq';
 export { default as lensSatisfies } from './lensSatisfies';
 export { default as lensNotSatisfy } from './lensNotSatisfy';
+export { default as lensTraverse } from './lensTraverse';
 export { default as lensIso } from './lensIso';
 export { default as propNotEq } from './propNotEq';
 export { default as pathNotEq } from './pathNotEq';

src/lensTraverse.js

@@ -0,0 +1,43 @@
+import { traverse, curry, pipe, prop } from 'ramda';
+
+import Identity from './fantasy-land/Identity';
+
+/**
+ * Creates a [Traversable](https://github.com/fantasyland/fantasy-land#traversable) lens
+ * from an [Applicative](https://github.com/fantasyland/fantasy-land#applicative)-returning function.
+ *
+ * When executed, it maps an [Applicative](https://github.com/fantasyland/fantasy-land#applicative)-returning
+ * function over a [Traversable](https://github.com/fantasyland/fantasy-land#traversable),
+ * then uses [`sequence`](#sequence) to transform the resulting Traversable of Applicative
+ * into an Applicative of Traversable.
+ *
+ * Dispatches to the `traverse` method of the third argument, if present.
+ *
+ * @func lensTraverse
+ * @memberOf RA
+ * @since {@link https://char0n.github.io/ramda-adjunct/2.7.0|2.7.0}
+ * @category Relation
+ * @typedef Lens s a = Functor f => (a -> f a) -> s -> f s
+ * @sig Applicative f => (a -> f a) -> Lens s a
+ * @param {!function} of The Applicative-returning function
+ * @return {!function} The Traversable lens
+ * @see {@link http://ramdajs.com/docs/#lens|R.lens}, {@link http://ramdajs.com/docs/#traverse|R.traverse}
+ *
+ * @example
+ *
+ * const maybeLens = RA.lensTraverse(Maybe.of);
+ * const safeDiv = n => d => d === 0 ? Maybe.Nothing() : Maybe.Just(n / d)
+ *
+ * R.over(maybeLens, safeDiv(10), [2, 4, 5]); // => Just([5, 2.5, 2])
+ * R.over(maybeLens, safeDiv(10), [2, 0, 5]); // => Nothing
+ *
+ * R.view(maybeLens, [Maybe.Just(2), Maybe.Just(3)]); // => Maybe.Just([2, 3])
+ *
+ * R.set(maybeLens, Maybe.Just(1), [Maybe.just(2), Maybe.Just(3)]); // => Maybe.Just([1, 1])
+ */
+const lensTraverse = of =>
+  curry((toFunctorFn, target) =>
+    Identity.of(traverse(of, pipe(toFunctorFn, prop('value')), target))
+  );
+
+export default lensTraverse;

test/lensTraverse.js

@@ -0,0 +1,124 @@
+import * as R from 'ramda';
+import { assert } from 'chai';
+
+import * as RA from '../src';
+
+const isRamdaFlSpec1Compatible = (() => {
+  const m1 = RA.Identity.of(1).map(R.add);
+  const m2 = RA.Identity.of(2);
+
+  try {
+    R.ap(m1, m2);
+    return false;
+  } catch (e) {
+    return true;
+  }
+})();
+
+describe('lensTraverse', function() {
+  if (!isRamdaFlSpec1Compatible) {
+    it('should operate on a list of Applicatives', function() {
+      const result = R.over(RA.lensTraverse(RA.Identity.of), R.map(R.add(1)), [
+        RA.Identity.of(2),
+        RA.Identity.of(3),
+      ]);
+      const expected = RA.Identity.of([3, 4]);
+
+      assert.deepEqual(result.value, expected.value);
+    });
+  }
+
+  if (!isRamdaFlSpec1Compatible) {
+    it('should operate on list of  primitives (numbers)', function() {
+      const travFn = x => RA.Identity.of(x + 1);
+      const result = R.over(RA.lensTraverse(RA.Identity.of), travFn, [2, 3]);
+      const expected = RA.Identity.of([3, 4]);
+
+      assert.deepEqual(result.value, expected.value);
+    });
+  }
+
+  if (!isRamdaFlSpec1Compatible) {
+    it('should traverse Applicatives left to right', function() {
+      const result = R.over(RA.lensTraverse(RA.Identity.of), R.identity, [
+        RA.Identity.of(2),
+        RA.Identity.of(3),
+      ]);
+      const expected = RA.Identity.of([2, 3]);
+
+      assert.deepEqual(result.value, expected.value);
+    });
+  }
+
+  it('should throw on traversing on non Applicatives (e.g. numbers)', function() {
+    const fn = R.over(RA.lensTraverse(RA.Identity.of), R.identity);
+
+    assert.throws(() => fn([2, 3]), TypeError);
+  });
+
+  it('should dispatch to sequence function', function() {
+    RA.Identity.prototype.sequence = function() {
+      return R.map(RA.Identity.of, this.value);
+    };
+
+    const result = R.over(
+      RA.lensTraverse(R.of),
+      R.map(R.add(1)),
+      RA.Identity.of([2, 3])
+    );
+    const expected = [RA.Identity.of(3), RA.Identity.of(4)];
+
+    assert.deepEqual(result, expected);
+
+    delete RA.Identity.prototype.sequence;
+  });
+
+  if (!isRamdaFlSpec1Compatible) {
+    it('should compose', function() {
+      const result = R.over(
+        R.compose(R.lensProp('prop'), RA.lensTraverse(RA.Identity.of)),
+        R.map(R.add(1)),
+        {
+          prop: [RA.Identity.of(2), RA.Identity.of(3)],
+        }
+      );
+      const expected = {
+        prop: RA.Identity.of([3, 4]),
+      };
+
+      assert.deepEqual(result, expected);
+    });
+  }
+
+  context('view', function() {
+    if (!isRamdaFlSpec1Compatible) {
+      specify('should work on list of Applicables', function() {
+        const result = R.view(RA.lensTraverse(RA.Identity.of), [
+          RA.Identity.of(2),
+          RA.Identity.of(3),
+        ]);
+        const expected = RA.Identity.of([2, 3]);
+
+        assert.deepEqual(result, expected);
+      });
+    }
+
+    specify('should throw on list of non Applicables', function() {
+      const fn = R.view(RA.lensTraverse(RA.Identity.of));
+
+      assert.throws(() => fn([2, 3]));
+    });
+  });
+
+  if (!isRamdaFlSpec1Compatible) {
+    it('should be modifiable via set', function() {
+      const result = R.set(RA.lensTraverse(RA.Identity.of), RA.Identity.of(2), [
+        RA.Identity.of(2),
+        RA.Identity.of(3),
+      ]);
+      const expected = RA.Identity.of([2, 2]);
+
+      assert.deepEqual(result, expected);
+    });
+  }
+});