From 0d3e816c03598f709771c75f0648007ae08b1652 Mon Sep 17 00:00:00 2001
From: Jonathan Goldwasser <jonathan.goldwasser@gmail.com>
Date: Thu, 30 Sep 2021 16:33:02 +0200
Subject: [PATCH] feat(core): subtract Duration

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

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

Closes #16535
---
 packages/@aws-cdk/core/README.md             |  7 +++++++
 packages/@aws-cdk/core/lib/duration.ts       | 18 ++++++++++++++++++
 packages/@aws-cdk/core/test/duration.test.ts | 10 +++++++---
 3 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/packages/@aws-cdk/core/README.md b/packages/@aws-cdk/core/README.md
index a6d4d2efc5a9b..96eb24f9a028c 100644
--- a/packages/@aws-cdk/core/README.md
+++ b/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
diff --git a/packages/@aws-cdk/core/lib/duration.ts b/packages/@aws-cdk/core/lib/duration.ts
index 0061e7928e900..e19340563b98d 100644
--- a/packages/@aws-cdk/core/lib/duration.ts
+++ b/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
    *
diff --git a/packages/@aws-cdk/core/test/duration.test.ts b/packages/@aws-cdk/core/test/duration.test.ts
index 68da12881d3ba..b04da705c846c 100644
--- a/packages/@aws-cdk/core/test/duration.test.ts
+++ b/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', () => {