Add unit tests for TokenAmount

Author: soerenbf

packages/sdk/src/plt/TokenAmount.ts

@@ -1,3 +1,5 @@
+import Big, { BigSource } from 'big.js';
+
 import { MAX_U32, MAX_U64 } from '../constants.js';
 import type * as Proto from '../grpc-api/v2/concordium/protocol-level-tokens.js';
 
@@ -24,6 +26,10 @@ export enum ErrorType {
     NEGATIVE = 'NEGATIVE',
     /** Error type indicating the token amount has more decimals than allowed. */
     EXCEEDS_MAX_DECIMALS = 'EXCEEDS_MAX_DECIMALS',
+    /** Error type indicating the token value is specified as a fractional value when multiplied by `10 ** decimals` */
+    FRACTIONAL_VALUE = 'FRACTIONAL_VALUE',
+    /** Error type indicating the token decimals were specified as a fractional number. */
+    FRACTIONAL_DECIMALS = 'FRACTIONAL_DECIMALS',
 }
 
 /**
@@ -47,10 +53,10 @@ export class Err extends Error {
     }
 
     /**
-     * Creates a TokenAmount.Err indicating that the token amount is negative.
+     * Creates a TokenAmount.Err indicating that the token amount/decimals is negative.
      */
     public static negative(): Err {
-        return new Err(ErrorType.NEGATIVE, 'Token amounts cannot be negative');
+        return new Err(ErrorType.NEGATIVE, 'Token amounts/decimals cannot be negative');
     }
 
     /**
@@ -59,6 +65,16 @@ export class Err extends Error {
     public static exceedsMaxDecimals(): Err {
         return new Err(ErrorType.EXCEEDS_MAX_DECIMALS, `Token amounts cannot have more than than ${MAX_U32}`);
     }
+
+    /** Creates a TokenAmount.Err indicating the token decimals were specified as a fractional number. */
+    public static fractionalDecimals(): Err {
+        return new Err(ErrorType.FRACTIONAL_DECIMALS, `Token decimals must be specified as whole numbers`);
+    }
+
+    /** Creates a TokenAmount.Err indicating the token decimals were specified as a fractional number. */
+    public static fractionalValue(): Err {
+        return new Err(ErrorType.FRACTIONAL_VALUE, `Can not create TokenAmount from a non-whole number`);
+    }
 }
 
 /**
@@ -72,7 +88,7 @@ class TokenAmount {
      * Constructs a new TokenAmount instance.
      * Validates that the value is within the allowed range and is non-negative.
      *
-     * @throws {Err} If the value/digits exceeds the maximum allowed or is negative.
+     * @throws {Err} If the value/decimals exceeds the maximum allowed or is negative.
      */
     constructor(
         /** The unsigned integer representation of the token amount. */
@@ -89,6 +105,12 @@ class TokenAmount {
         if (decimals > MAX_U32) {
             throw Err.exceedsMaxDecimals();
         }
+        if (decimals < 0) {
+            throw Err.negative();
+        }
+        if (Math.floor(decimals) !== decimals) {
+            throw Err.fractionalDecimals();
+        }
     }
 
     /**
@@ -125,12 +147,54 @@ export function instanceOf(value: unknown): value is TokenAmount {
     return value instanceof TokenAmount;
 }
 
+/**
+ * Creates a TokenAmount from a number, string, {@linkcode Big}, or bigint.
+ *
+ * @param amount The amount of tokens as a number, string, big or bigint.
+ * @returns {TokenAmount} The token amount.
+ *
+ * @throws {Err} If the value/decimals exceeds the maximum allowed or is negative.
+ */
+export function fromDecimal(amount: BigSource | bigint, decimals: number): TokenAmount {
+    let parsed: BigSource;
+    if (typeof amount !== 'bigint') {
+        parsed = newBig(amount);
+    } else {
+        parsed = amount.toString();
+    }
+
+    const intAmount = newBig(parsed).mul(Big(10 ** decimals));
+    // Assert that the number is whole
+    if (!intAmount.mod(Big(1)).eq(Big(0))) {
+        throw Err.fractionalValue();
+    }
+
+    return new TokenAmount(BigInt(intAmount.toString()), decimals);
+}
+
+function newBig(bigSource: BigSource): Big {
+    if (typeof bigSource === 'string') {
+        return Big(bigSource.replace(',', '.'));
+    }
+    return Big(bigSource);
+}
+
+/**
+ * Convert a token amount into a decimal value represented as a {@linkcode Big}
+ *
+ * @param {TokenAmount} amount
+ * @returns {Big} The token amount as a {@linkcode Big}.
+ */
+export function toDecimal(amount: TokenAmount): Big {
+    return Big(amount.toString());
+}
+
 /**
  * Converts {@linkcode JSON} to a token amount.
  *
  * @param {string} json The JSON representation of the CCD amount.
- * @returns {CcdAmount} The CCD amount.
- * @throws {Err} If the value/digits exceeds the maximum allowed or is negative.
+ * @returns {TokenAmount} The CCD amount.
+ * @throws {Err} If the value/decimals exceeds the maximum allowed or is negative.
  */
 export function fromJSON(json: JSON): TokenAmount {
     return new TokenAmount(BigInt(json.value), Number(json.decimals));
@@ -142,7 +206,7 @@ export function fromJSON(json: JSON): TokenAmount {
  * @param {bigint} value The integer representation of the token amount.
  * @param {number} decimals The decimals of the token amount, defining the precision at which amounts of the token can be specified.
  * @returns {TokenAmount} The token amount.
- * @throws {Err} If the value/digits exceeds the maximum allowed or is negative.
+ * @throws {Err} If the value/decimals exceeds the maximum allowed or is negative.
  */
 export function create(value: bigint, decimals: number): TokenAmount {
     return new TokenAmount(value, decimals);
@@ -153,7 +217,7 @@ export function create(value: bigint, decimals: number): TokenAmount {
  *
  * @param {number} decimals The decimals of the token amount, defining the precision at which amounts of the token can be specified.
  * @returns {TokenAmount} The token amount.
- * @throws {Err} If the digits exceeds the maximum allowed.
+ * @throws {Err} If the decimals exceeds the maximum allowed.
  */
 export function zero(decimals: number): TokenAmount {
     return new TokenAmount(BigInt(0), decimals);
@@ -163,7 +227,7 @@ export function zero(decimals: number): TokenAmount {
  * Convert token amount from its protobuf encoding.
  * @param {Proto.TokenAmount} amount
  * @returns {Type} The token amount.
- * @throws {Err} If the value/digits exceeds the maximum allowed or is negative.
+ * @throws {Err} If the value/decimals exceeds the maximum allowed or is negative.
  */
 export function fromProto(amount: Proto.TokenAmount): Type {
     return create(amount.digits, amount.nrOfDecimals);

packages/sdk/test/ci/plt/TokenAmount.test.ts

@@ -0,0 +1,57 @@
+import Big from 'big.js';
+
+import { MAX_U32, MAX_U64 } from '../../../src/constants.ts';
+import { TokenAmount } from '../../../src/plt/types.js';
+
+describe('PLT TokenAmount', () => {
+    test('Parses decimals correctly', () => {
+        expect(TokenAmount.fromDecimal('1', 6)).toEqual(TokenAmount.create(1000000n, 6));
+        expect(TokenAmount.fromDecimal('1.002', 4)).toEqual(TokenAmount.create(10020n, 4));
+        expect(TokenAmount.fromDecimal('15.002456687544126548', 18)).toEqual(
+            TokenAmount.create(15002456687544126548n, 18)
+        );
+    });
+
+    test('Token amounts that specifies more decimals than declared throws', () => {
+        expect(() => TokenAmount.fromDecimal('0.12345', 4)).toThrow(TokenAmount.Err.fractionalValue());
+    });
+
+    test('Token amounts with invalid decimals throws', () => {
+        expect(() => TokenAmount.zero(-1)).toThrow(TokenAmount.Err.negative());
+        expect(() => TokenAmount.zero(1.5)).toThrow(TokenAmount.Err.fractionalDecimals());
+        expect(() => TokenAmount.zero(MAX_U32 + 1)).toThrow(TokenAmount.Err.exceedsMaxDecimals());
+    });
+
+    test('Token amounts with invalid values throws', () => {
+        expect(() => TokenAmount.create(-504n, 0)).toThrow(TokenAmount.Err.negative());
+        expect(() => TokenAmount.create(MAX_U64 + 1n, 0)).toThrow(TokenAmount.Err.exceedsMaxValue());
+    });
+
+    test('Returns expected amount', () => {
+        expect(TokenAmount.zero(0)).toEqual(TokenAmount.create(0n, 0));
+        expect(TokenAmount.zero(4)).toEqual(TokenAmount.create(0n, 4));
+    });
+
+    test('JSON conversion works both ways', () => {
+        const json = { value: 123n, decimals: 2 };
+        expect(TokenAmount.fromJSON(json).toJSON()).toEqual(json);
+    });
+
+    test('Formats to string as expected', () => {
+        expect(TokenAmount.create(1588n, 3).toString()).toEqual('1.588');
+        expect(TokenAmount.create(1588n, 9).toString()).toEqual('0.000001588');
+    });
+
+    test('Returns correct decimal amount', () => {
+        expect(TokenAmount.toDecimal(TokenAmount.create(1000n, 6))).toEqual(Big('0.001'));
+        expect(TokenAmount.toDecimal(TokenAmount.create(123456789n, 2))).toEqual(Big('1234567.89'));
+    });
+
+    test('FromCcd correctly takes comma as a decimal seperator', () => {
+        expect(TokenAmount.toDecimal(TokenAmount.fromDecimal('10,000', 6))).toEqual(Big('10'));
+    });
+
+    test('TokenAmount constructor correctly rejects multiple comma seperators', () => {
+        expect(() => TokenAmount.fromDecimal('10,000,000', 6)).toThrow(Error('[big.js] Invalid number'));
+    });
+});