@mezo-org/passport 0.4.0-dev.5 → 0.4.0-dev.51

package/src/utils/numbers.test.ts

@@ -0,0 +1,220 @@
+import {
+  formatNumberToCompactString,
+  fromFixedPoint,
+  roundUpNumber,
+  formatNumberToLocaleString,
+  fromFixedPointToString,
+} from "./numbers"
+
+describe("formatNumberToCompactString", () => {
+  it("formats number less than 1000 with decimals", () => {
+    expect(formatNumberToCompactString(123.456789, 2)).toBe("123.46")
+  })
+
+  it("formats thousands with K", () => {
+    expect(formatNumberToCompactString(12_345, 2)).toBe("12.35K")
+  })
+
+  it("formats millions with M", () => {
+    expect(formatNumberToCompactString(12_345_678, 2)).toBe("12.35M")
+  })
+
+  it("formats billions with B", () => {
+    expect(formatNumberToCompactString(12_345_678_901, 2)).toBe("12.35B")
+  })
+
+  it("formats trillions with T", () => {
+    expect(formatNumberToCompactString(12_345_678_901_234, 2)).toBe("12.35T")
+  })
+
+  it("formats bigint as readable number", () => {
+    expect(formatNumberToCompactString(1234567890123456789n, 2)).toBe(
+      "1,234,567.89T",
+    )
+  })
+
+  it("caps at > 1000T for huge numbers", () => {
+    const hugeNumber = 10 ** 18 // 1e18
+    expect(formatNumberToCompactString(hugeNumber, 2)).toBe("1,000,000T")
+  })
+
+  it("formats numbers with trailing zeros correctly", () => {
+    expect(formatNumberToCompactString(1_000, 2)).toBe("1K")
+  })
+})
+
+describe("roundUpNumber", () => {
+  it("rounds up to 2 decimals", () => {
+    expect(roundUpNumber(1.234)).toBe(1.24)
+  })
+
+  it("rounds up to 3 decimals", () => {
+    expect(roundUpNumber(9.87654, 3)).toBe(9.877)
+  })
+
+  it("rounds up exact decimal", () => {
+    expect(roundUpNumber(2.5, 1)).toBe(2.5)
+  })
+})
+
+describe("fromFixedPoint", () => {
+  it("converts fixed point with 18 decimals to float", () => {
+    const raw = 1234567890000000000n // 1.23456789 ETH in 18 decimals
+    expect(fromFixedPoint(raw, 18)).toBe(1.2345)
+  })
+
+  it("converts with truncation to 2 decimals", () => {
+    const raw = 987654321000000000n // ~0.987654321 ETH
+    expect(fromFixedPoint(raw, 18, 2)).toBe(0.98)
+  })
+
+  it("handles large fixedPoint decimals", () => {
+    const raw = 1_000_000_000_000_000_000_000_000n // 1M with 6 decimals
+    expect(fromFixedPoint(raw, 6, 2)).toBe(1000000000000000000)
+  })
+})
+
+describe("formatNumberToLocaleString", () => {
+  it("formats zero with 0 decimals", () => {
+    expect(formatNumberToLocaleString(0, 0)).toBe("0")
+  })
+
+  it("formats zero with >0 decimals", () => {
+    expect(formatNumberToLocaleString(0, 2)).toBe("0.00")
+    expect(formatNumberToLocaleString(0, 4)).toBe("0.0000")
+  })
+
+  it("formats small decimal number", () => {
+    expect(formatNumberToLocaleString(0.123456, 2)).toBe("0.12")
+    expect(formatNumberToLocaleString(0.123456, 4)).toBe("0.1235")
+  })
+
+  it("formats number just above 1", () => {
+    expect(formatNumberToLocaleString(1.000001, 3)).toBe("1.000")
+    expect(formatNumberToLocaleString(1.234567, 2)).toBe("1.23")
+  })
+
+  it("formats whole number", () => {
+    expect(formatNumberToLocaleString(1234, 0)).toBe("1,234")
+    expect(formatNumberToLocaleString(1000, 2)).toBe("1,000.00")
+  })
+
+  it("formats number with trailing decimal zeroes", () => {
+    expect(formatNumberToLocaleString(10.1, 3)).toBe("10.100")
+    expect(formatNumberToLocaleString(5.0, 2)).toBe("5.00")
+  })
+
+  it("formats string input", () => {
+    expect(formatNumberToLocaleString("123.456", 2)).toBe("123.46")
+    expect(formatNumberToLocaleString("0.00123", 4)).toBe("0.0012")
+  })
+
+  it("formats negative number", () => {
+    expect(formatNumberToLocaleString(-123.456, 2)).toBe("-123.46")
+    expect(formatNumberToLocaleString("-0.00999", 3)).toBe("-0.010")
+  })
+
+  it("formats large number with commas", () => {
+    expect(formatNumberToLocaleString(12345678.9, 2)).toBe("12,345,678.90")
+  })
+
+  it("handles max decimals safely", () => {
+    expect(formatNumberToLocaleString(1.123456789, 8)).toBe("1.12345679")
+    expect(formatNumberToLocaleString("0.000000000000000001", 18)).toBe(
+      "0.000000000000000001",
+    )
+  })
+
+  it("defaults to 0 decimals if not passed", () => {
+    expect(formatNumberToLocaleString(1234.567)).toBe("1,235") // rounds up by default
+  })
+})
+
+describe("fromFixedPointToString", () => {
+  const toFixedPoint = (num: number) => BigInt(Math.round(num * 1e18))
+
+  const cases = [
+    { input: 2.0, expected: "2.000" },
+    { input: 2.009, expected: "2.009" },
+    { input: 2.01, expected: "2.010" },
+    { input: 2.015, expected: "2.016" },
+    { input: 2.05, expected: "2.050" },
+    { input: 2.09, expected: "2.090" },
+  ]
+
+  describe("withRoundUp: true", () => {
+    cases.forEach(({ input, expected }) => {
+      it(`formats ${input} → ${expected}`, () => {
+        const fixed = toFixedPoint(input)
+        expect(fromFixedPointToString(fixed, 18, 3, true)).toBe(expected)
+      })
+    })
+  })
+
+  describe("withRoundUp: false", () => {
+    const noRoundCases = [
+      { input: 2.0099, expected: "2.009" },
+      { input: 2.0159, expected: "2.015" },
+      { input: 2.0101, expected: "2.010" },
+      { input: 2.0199, expected: "2.019" },
+    ]
+
+    noRoundCases.forEach(({ input, expected }) => {
+      it(`formats ${input} → ${expected} (no rounding)`, () => {
+        const fixed = toFixedPoint(input)
+        expect(fromFixedPointToString(fixed, 18, 3, false)).toBe(expected)
+      })
+    })
+  })
+
+  describe("zero handling", () => {
+    it("formats 0 → 0.000 (3 decimals)", () => {
+      expect(fromFixedPointToString(0n, 18, 3)).toBe("0.000")
+    })
+
+    it("formats 0 → 0.0000 (4 decimals)", () => {
+      expect(fromFixedPointToString(0n, 18, 4)).toBe("0.0000")
+    })
+  })
+
+  describe("very small numbers below display threshold", () => {
+    it("returns <0.0001 for small number (3 decimals)", () => {
+      const small = BigInt(123) // ~1.23e-16
+      expect(fromFixedPointToString(small, 18, 4)).toBe("<0.0001")
+    })
+
+    it("returns <0.01 for small number with only 2 decimals", () => {
+      const tiny = BigInt(9999999999999) // <0.01
+      expect(fromFixedPointToString(tiny, 18, 2)).toBe("<0.01")
+    })
+  })
+
+  describe("input types", () => {
+    it("accepts bigint", () => {
+      const amount = 2100000000000000000n
+      expect(fromFixedPointToString(amount, 18, 3)).toBe("2.100")
+    })
+
+    it("accepts string", () => {
+      expect(fromFixedPointToString("2000000000000000000", 18, 3)).toBe("2.000")
+    })
+
+    it("accepts number", () => {
+      expect(fromFixedPointToString(Number("1000000000000000000"), 18, 3)).toBe(
+        "1.000",
+      )
+    })
+  })
+
+  describe("high values", () => {
+    it("formats 1_000_000.123456789 correctly", () => {
+      const big = toFixedPoint(1_000_000.123456789)
+      expect(fromFixedPointToString(big, 18, 6)).toBe("1,000,000.123456")
+    })
+
+    it("formats 1e12 ETH", () => {
+      const big = BigInt("1000000000000000000000000000000")
+      expect(fromFixedPointToString(big, 18, 2)).toBe("1,000,000,000,000.00")
+    })
+  })
+})

package/src/utils/numbers.ts

@@ -0,0 +1,188 @@
+type DesiredDecimals = Intl.NumberFormatOptions &
+  BigIntToLocaleStringOptions["minimumFractionDigits"]
+
+/**
+ * Formats a number or bigint into compact string with K, M, B, or T suffix.
+ * @param value The number or bigint to format.
+ * @param decimals Number of decimal places to include (ignored for bigint to avoid floating point issues).
+ * @returns The formatted number as a string.
+ */
+export function formatNumberToCompactString(
+  value: number | bigint,
+  decimals = 4,
+): string {
+  return value.toLocaleString("en-US", {
+    notation: "compact",
+    compactDisplay: "short",
+    maximumFractionDigits: decimals as DesiredDecimals,
+  })
+}
+
+/**
+ * Formats a number or string into a locale-sensitive string with the desired number of decimals.
+ * @param value The number or string to format.
+ * @param desiredDecimals The number of decimal places to include.
+ * @returns The formatted number as a string.
+ * @see https://github.com/thesis/acre/blob/2078d339f4ddce79e69c78529c9d72910dd2640a/dapp/src/utils/numbersUtils.ts#L5-L19
+ */
+export function formatNumberToLocaleString(
+  value: string | number,
+  desiredDecimals = 0,
+) {
+  const number = typeof value === "number" ? value : parseFloat(value)
+
+  if (number === 0 && desiredDecimals === 0) return "0"
+
+  if (number === 0) return `0.${"0".repeat(desiredDecimals)}`
+
+  return number.toLocaleString("en-US", {
+    minimumFractionDigits: desiredDecimals,
+    maximumFractionDigits: desiredDecimals,
+  })
+}
+
+/**
+ * Returns a number rounded up to the desired number of decimals.
+ * @param amount The number to round up.
+ * @param desiredDecimals The number of decimals to round up to.
+ * @returns The rounded up number.
+ * @see https://github.com/thesis/acre/blob/2078d339f4ddce79e69c78529c9d72910dd2640a/dapp/src/utils/numbersUtils.ts#L1-L3
+ */
+export function roundUpNumber(amount: number, desiredDecimals = 2): number {
+  return Math.ceil(amount * 10 ** desiredDecimals) / 10 ** desiredDecimals
+}
+
+/**
+ * Convert a fixed point bigint with precision `fixedPointDecimals` to a
+ * floating point number truncated to `desiredDecimals`.
+ * @param fixedPoint The fixed point bigint to convert.
+ * @param fixedPointDecimals The number of decimals in the fixed point bigint.
+ * @param desiredDecimals The number of decimals in the output number.
+ * @returns The floating point number truncated to `desiredDecimals`.
+ * @see https://github.com/tahowallet/extension/blob/f6b26b7cb4a0a0278b1fccc6319626638f1a6dfa/background/lib/fixed-point.ts#L216-L239
+ */
+export function fromFixedPoint(
+  fixedPoint: bigint,
+  fixedPointDecimals: number,
+  desiredDecimals = 4,
+): number {
+  const fixedPointDesiredDecimalsAmount =
+    fixedPoint /
+    10n ** BigInt(Math.max(1, fixedPointDecimals - desiredDecimals))
+
+  const formattedAmount =
+    Number(fixedPointDesiredDecimalsAmount) /
+    10 ** Math.min(desiredDecimals, fixedPointDecimals)
+
+  return formattedAmount
+}
+
+/**
+ * Display a token amount correctly with desired decimals.
+ * The function returns a string with a language-sensitive representation of this number.
+ * @param amount The fixed point number to convert.
+ * @param decimals The number of decimals in the fixed point number.
+ * @param desiredDecimals The number of decimals to display.
+ * @param withRoundUp Whether to round up the number.
+ * @returns The formatted number as a string.
+ * @see https://github.com/thesis/acre/blob/2078d339f4ddce79e69c78529c9d72910dd2640a/dapp/src/utils/numbersUtils.ts#L57-L87
+ */
+export const fromFixedPointToString = (
+  amount: number | string | bigint,
+  decimals = 18,
+  desiredDecimals = 4,
+  withRoundUp = false,
+) => {
+  const fixedPoint = BigInt(amount)
+
+  if (fixedPoint === 0n) {
+    return `0.${"0".repeat(desiredDecimals)}`
+  }
+
+  const formattedAmount = fromFixedPoint(
+    fixedPoint,
+    decimals,
+    // To round the amount up, let's increase the precision by one.
+    // The desired decimal numbers will be set later anyway.
+    withRoundUp ? desiredDecimals + 1 : desiredDecimals,
+  )
+
+  const minAmountToDisplay = 1 / 10 ** Math.min(desiredDecimals, decimals)
+
+  if (minAmountToDisplay > formattedAmount) {
+    return `<0.${"0".repeat(desiredDecimals - 1)}1`
+  }
+
+  const finalFormattedAmount = withRoundUp
+    ? Math.ceil(formattedAmount * 10 ** desiredDecimals) / 10 ** desiredDecimals
+    : formattedAmount
+  return formatNumberToLocaleString(finalFormattedAmount, desiredDecimals)
+}
+
+/**
+ * Converts a floating-point number or string to a bigint representation
+ * scaled by the specified number of decimal places (default: 18).
+ *
+ * This function avoids floating-point precision issues by manually
+ * parsing and scaling the number.
+ *
+ * @param amount - A number or string containing a floating point number.
+ * @param decimals - Number of decimals to scale to (default: 18).
+ * @returns A bigint representation scaled to the given decimal places.
+ * @see https://github.com/thesis/mezo-portal/blob/3bd4f39cb77c39948af2886a6ce7415a0c60307a/dapp/src/shared/utils/numbers.ts#L55
+ */
+export const fromFloatToBigInt = (
+  amount: string | number,
+  decimals = 18,
+): bigint => {
+  const FLOATING_POINT_REGEX = /^-?\d{1,3}(,\d{3})*(\.\d+)?$|^-?\d+(\.\d+)?$/
+
+  const parseToFixedPointNumber = (
+    floatingPointString: string,
+  ): { amount: bigint; decimals: number } | undefined => {
+    if (!floatingPointString.match(FLOATING_POINT_REGEX)) {
+      return undefined
+    }
+
+    const [whole, decimalsPart, ...extra] = floatingPointString.split(".")
+
+    if (extra.length > 0) return undefined
+
+    const noThousandsSeparatorWhole = whole.replace(/,/g, "")
+    const setDecimals = decimalsPart ?? ""
+
+    try {
+      return {
+        amount: BigInt([noThousandsSeparatorWhole, setDecimals].join("")),
+        decimals: setDecimals.length,
+      }
+    } catch {
+      return undefined
+    }
+  }
+
+  const convertFixedPoint = (
+    fixedPoint: bigint,
+    fixedPointDecimals: number,
+    targetDecimals: number,
+  ): bigint => {
+    if (fixedPointDecimals >= targetDecimals) {
+      return fixedPoint / 10n ** BigInt(fixedPointDecimals - targetDecimals)
+    }
+
+    return fixedPoint * 10n ** BigInt(targetDecimals - fixedPointDecimals)
+  }
+
+  const parsedAmount = amount.toString()
+  const fixedPointAmount = parseToFixedPointNumber(parsedAmount)
+
+  if (typeof fixedPointAmount === "undefined") {
+    return 0n
+  }
+
+  return convertFixedPoint(
+    fixedPointAmount.amount,
+    fixedPointAmount.decimals,
+    decimals,
+  )
+}