feat: 🎸 add support for subtraction

Author: alanhussey

README.md

@@ -334,9 +334,38 @@ eightFeet.value === 8;
 eightFeet.unit === foot;
 ```
 
+#### `.subtract(measurement1, measurement2)`
+
+`subtract` will take the two given measurements and attempt to subtract them, converting them if needed.
+
+Consider a `UnitSystem` that defines centimeters and inches:
+
+```js
+const centimeter = createUnit('centimeter');
+const inch = createUnit('inch', {
+  alias: 'inches',
+  convert: {
+    to: [centimeter, conversion.multiplyBy(2.54)],
+  },
+});
+```
+
+It can subtract two values in either of those units, converting them to the same unit:
+
+```js
+const eighteenInches = system.subtract(
+  m`24 inches`,
+  m(15.24, centimeter)
+);
+eighteenInches.value === 18;
+eighteenInches.unit === inch;
+```
+
+`subtract` does not support operating on more than 2 measurements at a time.
+
 ## Roadmap
 
-- Unit-safe math operations beyond `add`
+- Unit-safe math operations beyond `add` and `subtract`
 - Extended units:
   - Compound units - `m^2`, `m^3`
   - Rate units - `m/s`, `mph`

src/UnitSystem/UnitSystem.js

@@ -1,4 +1,4 @@
-const { add } = require('../math');
+const { add, subtract } = require('../math');
 const Measurement = require('../Measurement');
 const Unit = require('../Unit');
 const Aliases = require('./Aliases');
@@ -98,6 +98,10 @@ class UnitSystem {
     const unit = measurements[0].unit;
     return add(...measurements.map(m => this.convert(m, unit)));
   }
+  subtract(...measurements) {
+    const unit = measurements[0].unit;
+    return subtract(...measurements.map(m => this.convert(m, unit)));
+  }
 }
 
 module.exports = UnitSystem;

src/UnitSystem/UnitSystem.test.js

@@ -287,4 +287,28 @@ describe(UnitSystem, () => {
       ).toEqual(new Measurement(2, foot));
     });
   });
+
+  describe('#subtract', () => {
+    it('subtracts', () => {
+      const inch = new Unit('inch');
+      const system = new UnitSystem([[inch]]);
+
+      expect(
+        system.subtract(new Measurement(3, inch), new Measurement(1, inch))
+      ).toEqual(new Measurement(2, inch));
+    });
+
+    it('subtracts measurements in compatible units', () => {
+      const inch = new Unit('inch');
+      const foot = new Unit('foot');
+      const system = new UnitSystem([
+        [inch],
+        [foot, { convert: { to: [inch, multiplyBy(12)] } }],
+      ]);
+
+      expect(
+        system.subtract(new Measurement(2, foot), new Measurement(12, inch))
+      ).toEqual(new Measurement(1, foot));
+    });
+  });
 });

src/createUnitSystem.js

@@ -17,10 +17,11 @@ function createUnitSystem(units) {
 
   const convert = bound(system, 'convert');
   const add = bound(system, 'add');
+  const subtract = bound(system, 'subtract');
 
   const m = createMeasurement(system);
 
-  return { m, createUnit, convert, add, system };
+  return { m, createUnit, convert, add, subtract, system };
 }
 
 module.exports = createUnitSystem;

src/createUnitSystem.test.js

@@ -10,6 +10,7 @@ describe(createUnitSystem, () => {
       m: jasmine.any(Function),
       convert: jasmine.any(Function),
       add: jasmine.any(Function),
+      subtract: jasmine.any(Function),
     });
   });
 

src/index.test.js

@@ -14,7 +14,7 @@ describe('createUnitSystem', () => {
   const { createUnitSystem, conversion } = index;
 
   test('creates a functional unit system', () => {
-    const { createUnit, m, convert, add } = createUnitSystem();
+    const { createUnit, m, convert, add, subtract } = createUnitSystem();
 
     const kilometer = createUnit('kilometer', {
       alias: 'km',
@@ -53,8 +53,7 @@ describe('createUnitSystem', () => {
 
     expect(
       add(
-        m`2 feet`,
-        m`12 inches`,
+        subtract(m`4 feet`, m`12 inches`),
         m`2 inches`,
         m(15.24, centimeter),
         m`10 inches`,

src/math/add.js

@@ -1,13 +1,6 @@
+const measurementsHaveSameUnit = require('./measurementsHaveSameUnit');
 const Measurement = require('../Measurement');
 
-function unitsDoNotMatch(measurement, index, array) {
-  if (index === 0) {
-    return false;
-  }
-  const previousMeasurement = array[index - 1];
-  return previousMeasurement.unit !== measurement.unit;
-}
-
 function _add(measurements) {
   return measurements.reduce(
     (total, measurement) => total + measurement.value,
@@ -22,7 +15,7 @@ function add(...measurements) {
   if (measurements.length === 1) {
     return measurements[0];
   }
-  if (measurements.some(unitsDoNotMatch)) {
+  if (!measurementsHaveSameUnit(measurements)) {
     throw new TypeError('Cannot add measurements with different units');
   }
   const unit = measurements[0].unit;

src/math/index.js

@@ -1,3 +1,5 @@
 const add = require('./add');
+const subtract = require('./subtract');
 
 exports.add = add;
+exports.subtract = subtract;

src/math/measurementsHaveSameUnit.js

@@ -0,0 +1,11 @@
+function measurementsHaveSameUnit(measurements) {
+  return measurements.every((measurement, index, array) => {
+    if (index === 0) {
+      return true;
+    }
+    const previousMeasurement = array[index - 1];
+    return previousMeasurement.unit === measurement.unit;
+  });
+}
+
+module.exports = measurementsHaveSameUnit;

src/math/subtract.js

@@ -0,0 +1,20 @@
+const measurementsHaveSameUnit = require('./measurementsHaveSameUnit');
+const Measurement = require('../Measurement');
+
+function subtract(...measurements) {
+  if (measurements.length < 1 || measurements.length > 2) {
+    throw new TypeError(
+      `Expected exactly 2 Measurements but got ${measurements.length}`
+    );
+  }
+  if (measurements.length === 1) {
+    return measurements[0];
+  }
+  if (!measurementsHaveSameUnit(measurements)) {
+    throw new TypeError('Cannot subtract measurements with different units');
+  }
+  const unit = measurements[0].unit;
+  return new Measurement(measurements[0].value - measurements[1].value, unit);
+}
+
+module.exports = subtract;