feat: Introduce way to get return-value of first of many functions th…

…at matches an input-value

packages/fp/index.d.ts

@@ -122,3 +122,5 @@ export const getFrom: GetFrom;
 export const getSafeFrom: GetFrom;
 
 export const pipelineBreak: Symbol;
+
+export { firstMatchValue } from './src/firstMatchValue/firstMatchValue';

packages/fp/index.js

@@ -6,6 +6,7 @@ import pipeline from './src/pipeline/pipeline';
 import mapValuesDeep from './src/mapValuesDeep/mapValuesDeep';
 import getSafeFrom from './src/getSafeFrom/getSafeFrom';
 import getFrom from './src/getFrom/getFrom';
+import firstMatchValue from './src/firstMatchValue/firstMatchValue';
 
 export {
   awaitAll,
@@ -17,4 +18,5 @@ export {
   getFrom,
   getSafeFrom,
   pipelineBreak,
+  firstMatchValue,
 };

packages/fp/package.json

@@ -33,6 +33,7 @@
   "scripts": {
     "build": "ogre-tools-build-js",
     "test": "ogre-tools-test",
+    "test:types": "tsd --files ./src/**/*.test-d.ts",
     "code-style:verify": "ogre-tools-verify-code-style",
     "code-style:fix": "ogre-tools-fix-code-style"
   },

packages/fp/src/firstMatchValue/firstMatchValue.d.ts

@@ -0,0 +1,3 @@
+export function firstMatchValue<TInput, TOutput>(
+  ...functions: ((input: TInput) => TOutput | undefined)[]
+): (input: TInput) => TOutput | undefined;

packages/fp/src/firstMatchValue/firstMatchValue.js

@@ -0,0 +1,11 @@
+export const firstMatchValue =
+  (...functions) =>
+  data => {
+    for (const f of functions) {
+      const value = f(data);
+
+      if (value !== undefined) {
+        return value;
+      }
+    }
+  };

packages/fp/src/firstMatchValue/firstMatchValue.test-d.ts

@@ -0,0 +1,11 @@
+import { expectType } from 'tsd';
+import { firstMatchValue as firstMatchValueFor } from './firstMatchValue';
+
+const firstMatchValue = firstMatchValueFor(
+  x => 'some-string',
+  x => 'some-other-string',
+);
+
+const actual = firstMatchValue(true);
+
+expectType<string | undefined>(actual);

packages/fp/src/firstMatchValue/firstMatchValue.test.js

@@ -0,0 +1,53 @@
+import { firstMatchValue as firstMatchValueFor } from './firstMatchValue';
+import { constant, get } from 'lodash/fp';
+
+describe('firstMatchValue', () => {
+  describe('given array of functions used for finding', () => {
+    let firstMatchValue;
+    let finderMock;
+
+    beforeEach(() => {
+      finderMock = jest.fn();
+
+      firstMatchValue = firstMatchValueFor(
+        constant(undefined),
+        get('someProperty'),
+        finderMock,
+      );
+    });
+
+    describe('when called with data containing a match', () => {
+      let actual;
+
+      beforeEach(() => {
+        actual = firstMatchValue({ someProperty: 'some-value' });
+      });
+
+      it('returns the matched value from the matcher of highest priority', () => {
+        expect(actual).toBe('some-value');
+      });
+
+      it('does not call matchers of less priority than the one matching', () => {
+        expect(finderMock).not.toHaveBeenCalled();
+      });
+    });
+
+    describe('when called with data not containing a match', () => {
+      let actual;
+
+      beforeEach(() => {
+        actual = firstMatchValue({ someOtherProperty: 'irrelevant' });
+      });
+
+      it('returns undefined', () => {
+        expect(actual).toBeUndefined();
+      });
+
+      it('calls all matchers', () => {
+        expect(finderMock).toHaveBeenCalledWith({
+          someOtherProperty: 'irrelevant',
+        });
+      });
+    });
+  });
+});