feat: token.Quantity docs & test, return this from parser functions

README.md

@@ -53,6 +53,15 @@ const denomination = aoCredToken.info.Denomination;
 const logo = aoCredToken.info.Logo;
 ```
 
+#### Token quantity
+
+You can easily manage quantities as special, `bigint` based floating point numbers that keep precision, using the `token.Quantity` field. This field provides a [`Quantity`](#quantities) instance every time it's called, with a pre-configured denomination matching the token's denomination. Read more about quantities [here](#quantities).
+
+```ts
+// initialise a quantity from a token
+const amountToSend = aoCredToken.Quantity.fromString("752.34");
+```
+
 #### Wallet balance
 
 You can query the token balance for an address. This will return a `Quantity` instance.
@@ -86,7 +95,7 @@ The transfer functions allows you to send a message to the token process that in
 ```ts
 // this will transfer 1000 CRED to the provided address
 const id = await aoCredToken.transfer(
-  new Quantity(0n, aoCredToken.info.Denomination).fromString("1000"),
+  aoCredToken.Quantity.fromString("1000"),
   "XjvCPN31XCLPFBo9FUeB7vAK0VC6TwY52MCS-6Iho8h"
 );
 

src/Quantity.ts

@@ -103,7 +103,7 @@ export default class Quantity {
   fromString(value: string) {
     if (!value) {
       this.#qty = 0n;
-      return;
+      return this;
     }
 
     // replace formatters
@@ -112,7 +112,7 @@ export default class Quantity {
     // empty value
     if (value === "") {
       this.#qty = 0n;
-      return;
+      return this;
     }
 
     // multiplier according to the denomination
@@ -138,6 +138,8 @@ export default class Quantity {
 
     // set result
     this.#qty = result;
+
+    return this;
   }
 
   /**
@@ -238,6 +240,7 @@ export default class Quantity {
    */
   _one() {
     this.#qty = 10n ** this.#D;
+    return this;
   }
 
   /**
@@ -260,6 +263,8 @@ export default class Quantity {
 
     this.#D = newDenomination;
     this.#qty = newInst.#qty;
+
+    return this;
   }
 
   /**

src/token.test.ts

@@ -33,6 +33,19 @@ describe("Token testing", () => {
     expect(Quantity.isQuantityOf(invalidQty, token)).toBeFalsy();
   });
 
+  test("Quantity instance for token", () => {
+    const inst1 = token.Quantity.fromString("1000.245");
+
+    expect(Quantity.isQuantityOf(inst1, token)).toBeTruthy();
+    expect(inst1.toString()).toEqual("1000.245");
+
+    const inst2 = token.Quantity.fromNumber(2);
+
+    expect(Quantity.isQuantityOf(inst2, token)).toBeTruthy();
+    expect(inst2.toString()).toEqual("2");
+    expect(inst1.toString()).toEqual("1000.245");
+  });
+
   test("Get balance returns the correct balance", async () => {
     const existingBal = await token.getBalance(tokenID);