refactor(utils): rename mapping methods and deprecate old ones (#493)

.changeset/curvy-boxes-rescue.md

@@ -0,0 +1,5 @@
+---
+"@reactive-dot/utils": minor
+---
+
+Renamed `DenominatedNumber` mapping methods.

apps/docs/react/guides/number-utility.md

@@ -37,14 +37,14 @@ let dotAmount = DenominatedNumber.fromNumber(10, 10, "DOT");
 
 // Arithmetic operations can be performed using the number's planck value
 
-dotAmount = dotAmount.mapFromPlanck((planck) => planck + 5_000_000_000n);
+dotAmount = dotAmount.mapPlanck((planck) => planck + 5_000_000_000n);
 
 console.log(dotAmount.toLocaleString()); // DOT 10.50
 
 // Arithmetic operations can also be carried out with the number value
 // instead of planck if possible lost of precision is acceptable
 
-dotAmount = dotAmount.mapFromNumber((number) => (number * 2) / 4);
+dotAmount = dotAmount.mapNumber((number) => (number * 2) / 4);
 
 console.log(dotAmount.toLocaleString()); // DOT 5.25
 ```

apps/docs/vue/guides/number-utility.md

@@ -37,14 +37,14 @@ let dotAmount = DenominatedNumber.fromNumber(10, 10, "DOT");
 
 // Arithmetic operations can be performed using the number's planck value
 
-dotAmount = dotAmount.mapFromPlanck((planck) => planck + 5_000_000_000n);
+dotAmount = dotAmount.mapPlanck((planck) => planck + 5_000_000_000n);
 
 console.log(dotAmount.toLocaleString()); // DOT 10.50
 
 // Arithmetic operations can also be carried out with the number value
 // instead of planck if possible lost of precision is acceptable
 
-dotAmount = dotAmount.mapFromNumber((number) => (number * 2) / 4);
+dotAmount = dotAmount.mapNumber((number) => (number * 2) / 4);
 
 console.log(dotAmount.toLocaleString()); // DOT 5.25
 ```

packages/utils/src/denominated-number.test.ts

@@ -1,5 +1,5 @@
 import { DenominatedNumber } from "./denominated-number.js";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, test } from "vitest";
 
 describe("fromPlanck", () => {
   it("leads to correct atomics value", () => {
@@ -239,3 +239,19 @@ describe("toLocaleString", () => {
     expect(string).toContain("30K");
   });
 });
+
+test("mapPlanck", () => {
+  const number = new DenominatedNumber(30, 0, "DOT").mapPlanck(
+    (planck) => planck * 2n,
+  );
+
+  expect(number.toString()).toEqual("60");
+});
+
+test("mapNumber", () => {
+  const number = new DenominatedNumber(30, 0, "DOT").mapNumber(
+    (number) => number * 2,
+  );
+
+  expect(number.toString()).toEqual("60");
+});

packages/utils/src/denominated-number.ts

@@ -112,22 +112,32 @@ export class DenominatedNumber extends Number {
       .replace("XTS", this.denomination);
   }
 
-  mapFromPlanck(mapper: (planck: bigint) => bigint) {
+  mapPlanck(mapper: (planck: bigint) => bigint) {
     return new DenominatedNumber(
       mapper(this.planck),
       this.decimals,
       this.denomination,
     );
   }
 
-  mapFromNumber(mapper: (number: number) => number) {
+  /**
+   * @deprecated Use {@link DenominatedNumber.mapPlanck} instead.
+   */
+  mapFromPlanck = this.mapPlanck;
+
+  mapNumber(mapper: (number: number) => number) {
     return DenominatedNumber.fromNumber(
       mapper(this.valueOf()),
       this.decimals,
       this.denomination,
     );
   }
 
+  /**
+   * @deprecated Use {@link DenominatedNumber.mapNumber} instead.
+   */
+  mapFromNumber = this.mapNumber;
+
   static #verifyDecimals(fractionalDigits: number): void {
     if (!Number.isInteger(fractionalDigits))
       throw new Error("Decimals is not an integer");