refactor(library/math): documents alternative terms for "greatest common divisor" (#575)

- captures the aliases and abbreviations mentioned in [this article for this operator](https://en.wikipedia.org/wiki/Greatest_common_divisor)
- see [commits](https://github.com/nod-ai/shark-ui/pull/575/commits) for refactor operations

Author: bjacobgordon

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

@@ -14,9 +14,7 @@ import {
   squared,
 } from '../hyper';
 
-import {
-  greatestCommonDivisor,
-} from './greatestCommonDivisor';
+import * as GCDAlias from './greatestCommonDivisor';
 
 const pairCombos = <
   LeftElement extends number,
@@ -48,7 +46,11 @@ const symmetricPairCombos = <
   filler: given.filler,
 });
 
-describe(greatestCommonDivisor, () => {
+const aliasKeys = Object.keys(GCDAlias) as (keyof typeof GCDAlias)[];
+
+describe.each(aliasKeys)(`${GCDAlias.default.name} alias: "%s"`, (eachAliasKey) => {
+  const eachAliasedGCD = GCDAlias[eachAliasKey]; // eslint-disable-line import/namespace
+
   const singleDigitPrimes = [2, 3, 5, 7] as const;
 
   const [
@@ -67,7 +69,7 @@ describe(greatestCommonDivisor, () => {
       it.each(combosOfInoperableNumbers)('should reject inoperable operands', (...$0) => {
         expect.assertions(1);
 
-        expect(() => greatestCommonDivisor(...$0)).toThrow(Error);
+        expect(() => eachAliasedGCD(...$0)).toThrow(Error);
       });
 
       const combosOfInfiniteNumbers = symmetricPairCombos({
@@ -78,7 +80,7 @@ describe(greatestCommonDivisor, () => {
       it.each(combosOfInfiniteNumbers)('should reject infinite operands', (...$0) => {
         expect.assertions(1);
 
-        expect(() => greatestCommonDivisor(...$0)).toThrow(Error);
+        expect(() => eachAliasedGCD(...$0)).toThrow(Error);
       });
     });
 
@@ -94,13 +96,13 @@ describe(greatestCommonDivisor, () => {
         it.each(combosOfFractionalNumbers)('should reject them', (...$0) => {
           expect.assertions(1);
 
-          expect(() => greatestCommonDivisor(...$0)).toThrow(Error);
+          expect(() => eachAliasedGCD(...$0)).toThrow(Error);
         });
 
         it.each(combosOfFractionalNumbers)('should safely propagate the error', (...$0) => {
           expect.assertions(1);
 
-          expect(() => greatestCommonDivisor(...$0)).toThrow(Attempt.NonActionableError);
+          expect(() => eachAliasedGCD(...$0)).toThrow(Attempt.NonActionableError);
         });
 
         const fractionalCombosWithMessage = [
@@ -121,7 +123,7 @@ describe(greatestCommonDivisor, () => {
         it.each(fractionalCombosWithMessage)('should communicate clearly with developers', ($0) => {
           expect.assertions(1);
 
-          expect(() => greatestCommonDivisor(...$0.numbers)).toThrow($0.message);
+          expect(() => eachAliasedGCD(...$0.numbers)).toThrow($0.message);
         });
       });
     });
@@ -131,7 +133,7 @@ describe(greatestCommonDivisor, () => {
     it('should accept valid operands', () => {
       expect.assertions(1);
 
-      expect(() => greatestCommonDivisor(primeA, primeB)).not.toThrow();
+      expect(() => eachAliasedGCD(primeA, primeB)).not.toThrow();
     });
 
     const combosOfSignedIdentityFactors = symmetricPairCombos({
@@ -145,22 +147,22 @@ describe(greatestCommonDivisor, () => {
       const signedA = eachComboOfSignedIdentityFactors[0] * primeA;
       const signedB = eachComboOfSignedIdentityFactors[1] * primeB;
 
-      expect(/* */greatestCommonDivisor(/**/signedA, /**/signedB))
-        .toBe(/**/greatestCommonDivisor(/* */primeA, /* */primeB));
+      expect(/* */eachAliasedGCD(/**/signedA, /**/signedB))
+        .toBe(/**/eachAliasedGCD(/* */primeA, /* */primeB));
     });
 
     it('should be commutative', () => {
       expect.assertions(1);
 
-      expect(/* */greatestCommonDivisor(primeA, primeB))
-        .toBe(/**/greatestCommonDivisor(primeB, primeA));
+      expect(/* */eachAliasedGCD(primeA, primeB))
+        .toBe(/**/eachAliasedGCD(primeB, primeA));
     });
 
     it('should be associative', () => {
       expect.assertions(1);
 
-      expect(/* */greatestCommonDivisor(greatestCommonDivisor(primeA, primeB), primeC))
-        .toBe(/**/greatestCommonDivisor(greatestCommonDivisor(primeB, primeC), primeA));
+      expect(/* */eachAliasedGCD(eachAliasedGCD(primeA, primeB), primeC))
+        .toBe(/**/eachAliasedGCD(eachAliasedGCD(primeB, primeC), primeA));
     });
 
     const combosOfTogglingFactors = [
@@ -173,7 +175,7 @@ describe(greatestCommonDivisor, () => {
       expect.assertions(1);
 
       expect(
-        greatestCommonDivisor(
+        eachAliasedGCD(
           primeA * eachComboOfTogglingFactors[0],
           primeA * eachComboOfTogglingFactors[1],
         ),
@@ -185,7 +187,7 @@ describe(greatestCommonDivisor, () => {
     it('should preserve the identity of matching operands', () => {
       expect.assertions(1);
 
-      expect(greatestCommonDivisor(primeA, primeA)).toBe(primeA);
+      expect(eachAliasedGCD(primeA, primeA)).toBe(primeA);
     });
 
     const identityFactor = 1;
@@ -204,7 +206,7 @@ describe(greatestCommonDivisor, () => {
       expect.assertions(1);
 
       expect(
-        greatestCommonDivisor(
+        eachAliasedGCD(
           identityFactor * eachCoPrimePair[0],
           identityFactor * eachCoPrimePair[1],
         ),
@@ -232,7 +234,7 @@ describe(greatestCommonDivisor, () => {
         expect.assertions(1);
 
         expect(
-          greatestCommonDivisor(
+          eachAliasedGCD(
             eachCommonFactor * eachComboOfNonComposites[0],
             eachCommonFactor * eachComboOfNonComposites[1],
           ),

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

@@ -33,6 +33,27 @@ const greatestCommonDivisor = (
   return leftHandMagnitude;
 };
 
+/** Alias for {@link greatestCommonDivisor} */
+const greatestCommonFactor = greatestCommonDivisor;
+
+/** Alias for {@link greatestCommonDivisor} */
+const highestCommonDivisor = greatestCommonDivisor;
+
+/** Alias for {@link greatestCommonDivisor} */
+const highestCommonFactor = greatestCommonDivisor;
+
+/** Abbreviation for {@link greatestCommonDivisor} */
+const gcd = greatestCommonDivisor;
+
+/** Abbreviation for {@link greatestCommonFactor} */
+const gcf = greatestCommonFactor;
+
 export {
+  greatestCommonDivisor as default,
   greatestCommonDivisor,
+  greatestCommonFactor,
+  highestCommonDivisor,
+  highestCommonFactor,
+  gcd,
+  gcf,
 };