fix(library/math): guards against fractional operands in greatestCommonDivisor (#541)

Author: bjacobgordon

src/library/math/operator/constructive/greatestCommonDivisor.test.ts

@@ -44,9 +44,9 @@ const symmetricPairCombos = <
 
 describe(greatestCommonDivisor, () => {
   describe('the sad outcomes', () => {
-    describe('when delegated', () => {
-      const primeA = 2;
+    const primeA = 2;
 
+    describe('when delegated', () => {
       const combosOfInoperableNumbers = symmetricPairCombos({
         of    : numberTaxonomy.undefined,
         filler: primeA,
@@ -72,7 +72,16 @@ describe(greatestCommonDivisor, () => {
 
     describe('when generated', () => {
       describe('due to fractional operands', () => {
-        it.todo('should reject them');
+        const combosOfFractionalNumbers = symmetricPairCombos({
+          of    : numberTaxonomy.fractional.transcendental,
+          filler: primeA,
+        });
+
+        it.each(combosOfFractionalNumbers)('should reject them', (...$0) => {
+          expect.assertions(1);
+
+          expect(() => greatestCommonDivisor(...$0)).toThrow(Error);
+        });
 
         it.todo('should safely propagate the error');
 

src/library/math/operator/constructive/greatestCommonDivisor.ts

@@ -1,20 +1,20 @@
 import Attempt from '@/library/Attempt';
 
 import {
-  isFinite,
+  isWhole,
 } from '../predicate';
 
 const greatestCommonDivisor = (
   leftHandOperand: number,
   rightHandOperand: number,
 ): number => {
   if (
-    !isFinite(leftHandOperand)
-  ) return Attempt.abandon('Left operand must be finite.');
+    !isWhole(leftHandOperand)
+  ) return Attempt.abandon('Left operand must be whole.');
 
   if (
-    !isFinite(rightHandOperand)
-  ) return Attempt.abandon('Right operand must be finite.');
+    !isWhole(rightHandOperand)
+  ) return Attempt.abandon('Right operand must be whole.');
 
   let nextDividend = leftHandOperand;
   let previousRemainder = rightHandOperand;

src/library/math/operator/predicate/index.ts

@@ -1,3 +1,5 @@
 export * from './isOperable';
 
 export * from './isFinite';
+
+export * from './isWhole';

src/library/math/operator/predicate/isWhole.test.ts

@@ -0,0 +1,101 @@
+import {
+  describe,
+  it,
+  expect,
+} from 'vitest';
+
+import Attempt from '@/library/Attempt';
+
+import {
+  numberTaxonomy,
+} from '../../numberTaxonomy';
+
+import {
+  isWhole,
+} from './isWhole';
+
+describe(isWhole, () => {
+  describe('the sad outcomes', () => {
+    describe('when delegated', () => {
+      it('should reject inoperable operands', () => {
+        expect.assertions(1);
+
+        expect(() => isWhole(numberTaxonomy.undefined)).toThrow(Error);
+      });
+    });
+
+    describe('when generated', () => {
+      const infiniteNumbers = [
+        numberTaxonomy.infinite.positive,
+        numberTaxonomy.infinite.negative,
+      ];
+
+      describe.each(infiniteNumbers)('due to infinite operands', (eachInfiniteNumber) => {
+        it('should reject them', () => {
+          expect.assertions(1);
+
+          expect(() => isWhole(eachInfiniteNumber)).toThrow(Error);
+        });
+
+        it('should safely propagate the error', () => {
+          expect.assertions(1);
+
+          expect(() => isWhole(eachInfiniteNumber)).toThrow(Attempt.NonActionableError);
+        });
+
+        it('should communicate clearly with developers', () => {
+          expect.assertions(1);
+
+          expect(() => isWhole(eachInfiniteNumber)).toThrow('Operand must be finite.');
+        });
+      });
+    });
+  });
+
+  describe('the happy outcomes', () => {
+    const wholeNumbers = [
+      numberTaxonomy.origin,
+      numberTaxonomy.signed.negative,
+      numberTaxonomy.signed.positive,
+      numberTaxonomy.runtime.max,
+    ];
+
+    const fractionalNumbers = [
+      numberTaxonomy.runtime.min,
+      numberTaxonomy.fractional.rational,
+      numberTaxonomy.fractional.irrational,
+      numberTaxonomy.fractional.transcendental,
+    ];
+
+    const finiteNumbers = [
+      ...wholeNumbers,
+      ...fractionalNumbers,
+    ];
+
+    it.each(finiteNumbers)('should accept valid operands', (eachFiniteNumber) => {
+      expect.assertions(1);
+
+      expect(() => isWhole(eachFiniteNumber)).not.toThrow();
+    });
+
+    describe.each(wholeNumbers)('when given whole operands', (eachWholeNumber) => {
+      it('should detect them when fractional portions are omitted', () => {
+        expect.assertions(1);
+
+        expect(isWhole(eachWholeNumber)).toBe(true);
+      });
+
+      it('should detect them when fractional portions are present but zero', () => {
+        expect.assertions(1);
+
+        expect(isWhole((eachWholeNumber + 0.0))).toBe(true);
+      });
+    });
+
+    it.each(fractionalNumbers)('should detect fractional operands', (eachFractionalNumber) => {
+      expect.assertions(1);
+
+      expect(isWhole(eachFractionalNumber)).toBe(false);
+    });
+  });
+});

src/library/math/operator/predicate/isWhole.ts

@@ -0,0 +1,23 @@
+import Attempt from '@/library/Attempt';
+
+import {
+  isFinite,
+} from './isFinite';
+
+const isWhole = (
+  givenOperand: number,
+): boolean => {
+  if (
+    !isFinite(givenOperand)
+  ) return Attempt.abandon('Operand must be finite.');
+
+  return Number.isInteger(givenOperand);
+};
+
+/** Alias for {@link isWhole} */
+const isInteger = isWhole;
+
+export {
+  isWhole,
+  isInteger,
+};