feat: Size.asString that preserves original units (#1494)

We currently do not have a way to return the unit in a way that would work in Kubernetes. This PR would be a prerequisite PR for this issue: cdk8s-team/cdk8s#1166. 

We are converting `memory` units to `mebibytes` and `ephemeral-storage` to `gibibyte` even if user passes something else. This does not seem correct. For instance, [here](https://github.com/cdk8s-team/cdk8s-plus/blob/k8s-27/main/src/container.ts#L880). So this PR would help resolving this issue.
I believe this [issue](cdk8s-team/cdk8s-plus#1950) is another instance of being impacted by us converting the inputs.

docs/java.md

@@ -2330,7 +2330,7 @@ If true, this reference points to the managing controller.
 
 ### SizeConversionOptions <a name="SizeConversionOptions" id="cdk8s.SizeConversionOptions"></a>
 
-Options for how to convert time to a different unit.
+Options for how to convert size to a different unit.
 
 #### Initializer <a name="Initializer" id="cdk8s.SizeConversionOptions.Initializer"></a>
 
@@ -4039,6 +4039,7 @@ When the amount is passed as a token, unit conversion is not possible.
 
 | **Name** | **Description** |
 | --- | --- |
+| <code><a href="#cdk8s.Size.asString">asString</a></code> | Returns amount with abbreviated storage unit. |
 | <code><a href="#cdk8s.Size.toGibibytes">toGibibytes</a></code> | Return this storage as a total number of gibibytes. |
 | <code><a href="#cdk8s.Size.toKibibytes">toKibibytes</a></code> | Return this storage as a total number of kibibytes. |
 | <code><a href="#cdk8s.Size.toMebibytes">toMebibytes</a></code> | Return this storage as a total number of mebibytes. |
@@ -4047,6 +4048,14 @@ When the amount is passed as a token, unit conversion is not possible.
 
 ---
 
+##### `asString` <a name="asString" id="cdk8s.Size.asString"></a>
+
+```java
+public java.lang.String asString()
+```
+
+Returns amount with abbreviated storage unit.
+
 ##### `toGibibytes` <a name="toGibibytes" id="cdk8s.Size.toGibibytes"></a>
 
 ```java

docs/python.md

@@ -2366,7 +2366,7 @@ If true, this reference points to the managing controller.
 
 ### SizeConversionOptions <a name="SizeConversionOptions" id="cdk8s.SizeConversionOptions"></a>
 
-Options for how to convert time to a different unit.
+Options for how to convert size to a different unit.
 
 #### Initializer <a name="Initializer" id="cdk8s.SizeConversionOptions.Initializer"></a>
 
@@ -4334,6 +4334,7 @@ When the amount is passed as a token, unit conversion is not possible.
 
 | **Name** | **Description** |
 | --- | --- |
+| <code><a href="#cdk8s.Size.asString">as_string</a></code> | Returns amount with abbreviated storage unit. |
 | <code><a href="#cdk8s.Size.toGibibytes">to_gibibytes</a></code> | Return this storage as a total number of gibibytes. |
 | <code><a href="#cdk8s.Size.toKibibytes">to_kibibytes</a></code> | Return this storage as a total number of kibibytes. |
 | <code><a href="#cdk8s.Size.toMebibytes">to_mebibytes</a></code> | Return this storage as a total number of mebibytes. |
@@ -4342,6 +4343,14 @@ When the amount is passed as a token, unit conversion is not possible.
 
 ---
 
+##### `as_string` <a name="as_string" id="cdk8s.Size.asString"></a>
+
+```python
+def as_string() -> str
+```
+
+Returns amount with abbreviated storage unit.
+
 ##### `to_gibibytes` <a name="to_gibibytes" id="cdk8s.Size.toGibibytes"></a>
 
 ```python

docs/typescript.md

@@ -2035,7 +2035,7 @@ If true, this reference points to the managing controller.
 
 ### SizeConversionOptions <a name="SizeConversionOptions" id="cdk8s.SizeConversionOptions"></a>
 
-Options for how to convert time to a different unit.
+Options for how to convert size to a different unit.
 
 #### Initializer <a name="Initializer" id="cdk8s.SizeConversionOptions.Initializer"></a>
 
@@ -3555,6 +3555,7 @@ When the amount is passed as a token, unit conversion is not possible.
 
 | **Name** | **Description** |
 | --- | --- |
+| <code><a href="#cdk8s.Size.asString">asString</a></code> | Returns amount with abbreviated storage unit. |
 | <code><a href="#cdk8s.Size.toGibibytes">toGibibytes</a></code> | Return this storage as a total number of gibibytes. |
 | <code><a href="#cdk8s.Size.toKibibytes">toKibibytes</a></code> | Return this storage as a total number of kibibytes. |
 | <code><a href="#cdk8s.Size.toMebibytes">toMebibytes</a></code> | Return this storage as a total number of mebibytes. |
@@ -3563,6 +3564,14 @@ When the amount is passed as a token, unit conversion is not possible.
 
 ---
 
+##### `asString` <a name="asString" id="cdk8s.Size.asString"></a>
+
+```typescript
+public asString(): string
+```
+
+Returns amount with abbreviated storage unit.
+
 ##### `toGibibytes` <a name="toGibibytes" id="cdk8s.Size.toGibibytes"></a>
 
 ```typescript

src/size.ts

@@ -58,6 +58,13 @@ export class Size {
     this.unit = unit;
   }
 
+  /**
+   * Returns amount with abbreviated storage unit
+   */
+  public asString(): string {
+    return `${this.amount}${this.unit.abbr}`;
+  }
+
   /**
    * Return this storage as a total number of kibibytes.
    */
@@ -104,11 +111,10 @@ export enum SizeRoundingBehavior {
   FLOOR,
   /** Don't round. Return even if the result is a fraction. */
   NONE,
-
 }
 
 /**
- * Options for how to convert time to a different unit.
+ * Options for how to convert size to a different unit.
  */
 export interface SizeConversionOptions {
   /**
@@ -119,13 +125,13 @@ export interface SizeConversionOptions {
 }
 
 class StorageUnit {
-  public static readonly Kibibytes = new StorageUnit('kibibytes', 1);
-  public static readonly Mebibytes = new StorageUnit('mebibytes', 1024);
-  public static readonly Gibibytes = new StorageUnit('gibibytes', 1024 * 1024);
-  public static readonly Tebibytes = new StorageUnit('tebibytes', 1024 * 1024 * 1024);
-  public static readonly Pebibytes = new StorageUnit('pebibytes', 1024 * 1024 * 1024 * 1024);
+  public static readonly Kibibytes = new StorageUnit('kibibytes', 1, 'Ki');
+  public static readonly Mebibytes = new StorageUnit('mebibytes', 1024, 'Mi');
+  public static readonly Gibibytes = new StorageUnit('gibibytes', 1024 * 1024, 'Gi');
+  public static readonly Tebibytes = new StorageUnit('tebibytes', 1024 * 1024 * 1024, 'Ti');
+  public static readonly Pebibytes = new StorageUnit('pebibytes', 1024 * 1024 * 1024 * 1024, 'Pi');
 
-  private constructor(public readonly label: string, public readonly inKibiBytes: number) {
+  private constructor(public readonly label: string, public readonly inKibiBytes: number, public readonly abbr: string) {
     // MAX_SAFE_INTEGER is 2^53, so by representing storage in kibibytes,
     // the highest storage we can represent is 8 exbibytes.
   }
@@ -137,7 +143,9 @@ class StorageUnit {
 
 function convert(amount: number, fromUnit: StorageUnit, toUnit: StorageUnit, options: SizeConversionOptions = {}) {
   const rounding = options.rounding ?? SizeRoundingBehavior.FAIL;
-  if (fromUnit.inKibiBytes === toUnit.inKibiBytes) { return amount; }
+  if (fromUnit.inKibiBytes === toUnit.inKibiBytes) {
+    return amount;
+  }
 
   const multiplier = fromUnit.inKibiBytes / toUnit.inKibiBytes;
   const value = amount * multiplier;
@@ -153,4 +161,4 @@ function convert(amount: number, fromUnit: StorageUnit, toUnit: StorageUnit, opt
       }
       return value;
   }
-}
+}

test/size.test.ts

@@ -82,3 +82,10 @@ test('rounding behavior', () => {
   expect(size.toKibibytes({ rounding: SizeRoundingBehavior.NONE })).toEqual(5_324_800);
 });
 
+test('asString function gives abbreviated units', () => {
+  expect(Size.kibibytes(10).asString()).toEqual('10Ki');
+  expect(Size.mebibytes(10).asString()).toEqual('10Mi');
+  expect(Size.gibibytes(10).asString()).toEqual('10Gi');
+  expect(Size.tebibytes(10).asString()).toEqual('10Ti');
+  expect(Size.pebibyte(10).asString()).toEqual('10Pi');
+});