feat(core): subtract Duration

Add a `.subtract()` method to `Duration`.

Deprecate `.plus()` in favor of `.add()`, feels like a better naming.

Closes aws#16535

packages/@aws-cdk/core/README.md

@@ -172,6 +172,13 @@ Duration.days(7)        // 7 days
 Duration.parse('PT5M')  // 5 minutes
 ```
 
+Durations can be added or subtracted together:
+
+```ts
+Duration.minutes(1).add(Duration.seconds(60)); // 2 minutes
+Duration.minutes(5).subtract(Duration.seconds(10)); // 290 secondes
+```
+
 ## Size (Digital Information Quantity)
 
 To make specification of digital storage quantities unambiguous, a class called

packages/@aws-cdk/core/lib/duration.ts

@@ -102,13 +102,31 @@ export class Duration {
 
   /**
    * Add two Durations together
+   *
+   * @deprecated use `add()`
    */
   public plus(rhs: Duration): Duration {
+    return this.add(rhs);
+  }
+
+  /**
+   * Add two Durations together
+   */
+  public add(rhs: Duration): Duration {
     const targetUnit = finestUnit(this.unit, rhs.unit);
     const total = convert(this.amount, this.unit, targetUnit, {}) + convert(rhs.amount, rhs.unit, targetUnit, {});
     return new Duration(total, targetUnit);
   }
 
+  /**
+   * Substract two Durations together
+   */
+  public subtract(rhs: Duration): Duration {
+    const targetUnit = finestUnit(this.unit, rhs.unit);
+    const total = convert(this.amount, this.unit, targetUnit, {}) - convert(rhs.amount, rhs.unit, targetUnit, {});
+    return new Duration(total, targetUnit);
+  }
+
   /**
    * Return the total number of milliseconds in this Duration
    *

packages/@aws-cdk/core/test/duration.test.ts

@@ -167,11 +167,15 @@ describe('duration', () => {
   });
 
   test('add two durations', () => {
-    expect(Duration.minutes(1).plus(Duration.seconds(30)).toSeconds()).toEqual(Duration.seconds(90).toSeconds());
-    expect(Duration.minutes(1).plus(Duration.seconds(30)).toMinutes({ integral: false }))
+    expect(Duration.minutes(1).add(Duration.seconds(30)).toSeconds()).toEqual(Duration.seconds(90).toSeconds());
+    expect(Duration.minutes(1).add(Duration.seconds(30)).toMinutes({ integral: false }))
       .toEqual(Duration.seconds(90).toMinutes({ integral: false }));
+  });
 
-
+  test('subtract two durations', () => {
+    expect(Duration.minutes(1).subtract(Duration.seconds(30)).toSeconds()).toEqual(Duration.seconds(30).toSeconds());
+    expect(Duration.minutes(1).subtract(Duration.seconds(30)).toMinutes({ integral: false }))
+      .toEqual(Duration.seconds(30).toMinutes({ integral: false }));
   });
 
   test('get unit label from duration', () => {