@rallycash/numbers 0.0.0-stage → 0.3.0

package/src/number-utils.ts

@@ -0,0 +1,479 @@
+import { coerceNumber, type DecimalLike, type NumberInput } from './decimal.js'
+import { formatUnits, parseUnits } from './units.js'
+
+export type SignFormatOptions = {
+  showNegativeSign?: boolean
+  showPositiveSign?: boolean
+}
+
+export type FormatNumberOptions = SignFormatOptions & {
+  showExponents?: boolean
+  minSignificantDigits?: number
+  maxDecimals?: number
+  minDecimals?: number
+  abbrThreshold?: number
+  prefix?: string
+  abbreviateLargeNumbers?: boolean
+  abbrMinSignificantDigits?: number
+}
+
+export type FormatUsdOptions = SignFormatOptions & {
+  showCurrencySymbol?: boolean
+}
+
+export type FormatUsdBalanceOptions = FormatNumberOptions & {
+  showCurrencySymbol?: boolean
+}
+
+export type UsdInput = NumberInput | string
+
+export const expToString = (value: string | number): string => {
+  const raw = value.toString()
+  const negative = raw.startsWith('-')
+  const expanded = expandUnsignedExponent(negative ? raw.slice(1) : raw)
+  if (!negative || expanded === '0') return expanded
+  return `-${expanded}`
+}
+
+const expandUnsignedExponent = (expString: string): string => {
+  const [maybeNumber, exponent] = expString.split('e')
+  const number = maybeNumber ?? '0'
+
+  if (!exponent) return number
+  const decimalPosition = number.indexOf('.')
+
+  const removedDecimalNumber = number.replace('.', '')
+
+  const actualDecimalPosition =
+    decimalPosition === -1 ? number.length : decimalPosition
+  const decimalMovement = actualDecimalPosition + parseInt(exponent, 10)
+
+  const additionaltrailingZeros = Math.max(
+    decimalMovement - removedDecimalNumber.length,
+    0,
+  )
+
+  const additionalLeadingZeros =
+    actualDecimalPosition + parseInt(exponent, 10) < 0
+      ? Math.abs(decimalMovement)
+      : 0
+
+  const numberArr = Array(additionalLeadingZeros)
+    .fill('0')
+    .concat(removedDecimalNumber.split(''))
+    .concat(Array(additionaltrailingZeros).fill('0'))
+
+  const newDecimalPosition = Math.max(decimalMovement, 0)
+
+  if (newDecimalPosition < numberArr.length) {
+    const decimalInsertion = newDecimalPosition === 0 ? '0.' : '.'
+    numberArr.splice(newDecimalPosition, 0, decimalInsertion)
+  }
+
+  return numberArr.join('')
+}
+
+function getMagnitude(n: number) {
+  if (n === 0) return 0
+  return Math.floor(Math.log10(Math.abs(n)))
+}
+
+function toSubscript(text: string | number) {
+  const subscriptMap: Record<string, string> = {
+    '0': '₀',
+    '1': '₁',
+    '2': '₂',
+    '3': '₃',
+    '4': '₄',
+    '5': '₅',
+    '6': '₆',
+    '7': '₇',
+    '8': '₈',
+    '9': '₉',
+  }
+
+  let result = ''
+  for (const char of expToString(text)) {
+    result += subscriptMap[char] || char
+  }
+  return result
+}
+
+function applyDisplaySign(
+  formatted: string,
+  signed: number,
+  options: SignFormatOptions | undefined,
+): string {
+  if (!formatted) return formatted
+  const showNegativeSign = options?.showNegativeSign !== false
+  const showPositiveSign = options?.showPositiveSign === true
+  const unsigned = formatted.startsWith('-') ? formatted.slice(1) : formatted
+  if (signed < 0 && showNegativeSign && formatted.startsWith('-')) return formatted
+  if (signed > 0 && showPositiveSign) return `+${unsigned}`
+  return unsigned
+}
+
+const abbreviateNumber = (
+  num: number,
+  decimals = 2,
+  preserveTrailingZeros = false,
+  options?: SignFormatOptions,
+) => {
+  const lookup = [
+    { value: 1, symbol: '' },
+    { value: 1e3, symbol: 'K' },
+    { value: 1e6, symbol: 'M' },
+    { value: 1e9, symbol: 'B' },
+    { value: 1e12, symbol: 'T' },
+    { value: 1e15, symbol: 'P' },
+    { value: 1e18, symbol: 'E' },
+  ]
+
+  const rx = /\.0+$|(\.[0-9]*[1-9])0+$/
+  const formatFixed = (fixed: string) =>
+    preserveTrailingZeros ? fixed : fixed.replace(rx, '$1')
+
+  if (!Number.isFinite(num)) {
+    return applyDisplaySign(formatFixed(num.toFixed(decimals)), num, options)
+  }
+
+  const absNum = Math.abs(num)
+  let tier = 0
+  for (let i = lookup.length - 1; i >= 0; i--) {
+    const entry = lookup[i]
+    if (entry && absNum >= entry.value) {
+      tier = i
+      break
+    }
+  }
+
+  const renderTier = (index: number) => {
+    const entry = lookup[index]
+    if (!entry) return { text: formatFixed(num.toFixed(decimals)), rounded: num }
+    const rounded = Number((num / entry.value).toFixed(decimals) || 0)
+    const formattedNumber = rounded.toLocaleString('en-us', {
+      minimumFractionDigits: decimals,
+      maximumFractionDigits: decimals,
+    })
+    return { text: formatFixed(formattedNumber) + entry.symbol, rounded }
+  }
+
+  let rendered = renderTier(tier)
+  if (Math.abs(rendered.rounded) >= 1000 && tier < lookup.length - 1) {
+    rendered = renderTier(tier + 1)
+  }
+  return applyDisplaySign(rendered.text, num, options)
+}
+
+const renderFormatNumber = (
+  value: NumberInput,
+  {
+    showExponents = true,
+    minSignificantDigits = 4,
+    maxDecimals: maxDecimalsParam,
+    minDecimals: minDecimalsParam,
+    abbrThreshold = 1e7,
+    abbreviateLargeNumbers = true,
+    abbrMinSignificantDigits = 3,
+    prefix = '',
+  }: FormatNumberOptions = {},
+) => {
+  let minDecimals: number
+  let maxDecimals: number
+
+  if (maxDecimalsParam == null && minDecimalsParam != null) {
+    minDecimals = minDecimalsParam
+    maxDecimals = Math.max(6, minDecimalsParam)
+  } else if (minDecimalsParam == null && maxDecimalsParam != null) {
+    maxDecimals = maxDecimalsParam
+    minDecimals = Math.min(2, maxDecimalsParam)
+  } else if (maxDecimalsParam != null && minDecimalsParam != null) {
+    maxDecimals = maxDecimalsParam
+    minDecimals = Math.min(maxDecimalsParam, minDecimalsParam)
+  } else {
+    maxDecimals = 6
+    minDecimals = 2
+  }
+
+  const num = coerceNumber(value)
+
+  if (num === 0) {
+    const zeros = '0'.repeat(minDecimals)
+    return `0${zeros ? `.${zeros}` : ''}`
+  }
+  if (!num) return ''
+  const absNumber = Math.abs(num)
+
+  const magnitude = getMagnitude(num)
+
+  if (magnitude <= -Math.abs(maxDecimals) && minSignificantDigits) {
+    if (!showExponents) {
+      const numberToRound =
+        Math.abs(num) * 10 ** (Math.abs(magnitude) + minSignificantDigits - 1)
+
+      const fullNumber = expToString(
+        Math.round(numberToRound) /
+          10 ** (Math.abs(magnitude) + minSignificantDigits - 1),
+      )
+
+      const sign = num < 0 ? '-' : ''
+      return `${sign}${prefix}${fullNumber}`
+    }
+    const unsignedEndPart = Math.abs(num) / 10 ** magnitude
+
+    const formattedEndPart = Number(
+      unsignedEndPart.toFixed(minSignificantDigits - 1),
+    )
+      .toLocaleString('en-us', {
+        minimumFractionDigits: minDecimals,
+        maximumFractionDigits: Math.max(
+          0,
+          Math.min(20, Math.max(minSignificantDigits - 2, minDecimals)),
+        ),
+      })
+      .replace(/\./g, '')
+
+    const sign = num < 0 ? '-' : ''
+
+    return `${sign}${prefix}0.0${toSubscript(Math.abs(magnitude) - 1)}${formattedEndPart}`
+  }
+
+  const smallestDisplayableNumber = 1 / 10 ** maxDecimals
+
+  if (absNumber < smallestDisplayableNumber) {
+    const zeros = '0'.repeat(minDecimals)
+    return `0${zeros ? `.${zeros}` : ''}`
+  }
+
+  if (abbreviateLargeNumbers && absNumber >= abbrThreshold) {
+    const numbersBeforeDecimal = (magnitude + 1) % 3 || 3
+    return `${prefix}${abbreviateNumber(
+      num,
+      Math.max(abbrMinSignificantDigits - numbersBeforeDecimal, 0),
+    )}`
+  }
+
+  if (absNumber < 1) {
+    const clampedMaxDecimals = Math.max(0, Math.min(20, maxDecimals))
+    return `${prefix}${Number(num.toFixed(maxDecimals)).toLocaleString(
+      'en-us',
+      {
+        minimumFractionDigits: minDecimals,
+        maximumFractionDigits: clampedMaxDecimals,
+      },
+    )}`
+  }
+
+  if (absNumber >= 1 && absNumber < 10000) {
+    const clampedMaxDecimals = Math.max(0, Math.min(20, maxDecimals))
+    return `${prefix}${Number(
+      num.toFixed(Math.min(maxDecimals, 2)),
+    ).toLocaleString('en-us', {
+      minimumFractionDigits: minDecimals,
+      maximumFractionDigits: clampedMaxDecimals,
+    })}`
+  }
+
+  const rounded = maxDecimals === 0 ? Math.round(num) : num
+  const clampedMaxDecimals = Math.max(0, Math.min(20, maxDecimals))
+
+  return `${prefix}${Number(rounded.toFixed(maxDecimals)).toLocaleString(
+    'en-us',
+    {
+      minimumFractionDigits: minDecimals,
+      maximumFractionDigits: clampedMaxDecimals,
+    },
+  )}`
+}
+
+const formatNumber = (
+  value: NumberInput,
+  options: FormatNumberOptions = {},
+) => {
+  const formatted = renderFormatNumber(value, options)
+  const numeric = coerceNumber(value)
+  if (numeric == null || !Number.isFinite(numeric)) return formatted
+  return applyDisplaySign(formatted, numeric, options)
+}
+
+const USD_BALANCE_PRESET: FormatNumberOptions = {
+  minDecimals: 2,
+  maxDecimals: 2,
+  minSignificantDigits: 0,
+  showExponents: false,
+}
+
+const PERCENTAGE_PRESET: FormatNumberOptions = {
+  minDecimals: 0,
+  maxDecimals: 2,
+  minSignificantDigits: 0,
+  showExponents: false,
+}
+
+const INTEGER_PRESET: FormatNumberOptions = {
+  minDecimals: 0,
+  maxDecimals: 0,
+  minSignificantDigits: 0,
+  showExponents: false,
+}
+
+function mergePreset(
+  preset: FormatNumberOptions,
+  options: FormatNumberOptions | undefined,
+): FormatNumberOptions {
+  if (options === undefined) return preset
+  return { ...preset, ...options }
+}
+
+function coerceUsd(value: UsdInput): number | null | undefined {
+  if (typeof value === 'string') {
+    const parsed = Number.parseFloat(value)
+    return Number.isNaN(parsed) ? undefined : parsed
+  }
+  return coerceNumber(value)
+}
+
+function formatSignedUsd(
+  value: UsdInput,
+  formatAbs: (absolute: number) => string,
+  options?: FormatUsdOptions,
+): string {
+  const showCurrencySymbol = options?.showCurrencySymbol !== false
+  const symbol = showCurrencySymbol ? '$' : ''
+  const numeric = coerceUsd(value)
+  if (numeric == null || !Number.isFinite(numeric) || numeric === 0) {
+    return `${symbol}0.00`
+  }
+  const body = formatAbs(Math.abs(numeric))
+  if (numeric < 0 && options?.showNegativeSign !== false) return `-${symbol}${body}`
+  if (numeric > 0 && options?.showPositiveSign === true) return `+${symbol}${body}`
+  return `${symbol}${body}`
+}
+
+function absoluteUsdFormatOptions(
+  options: FormatUsdBalanceOptions | undefined,
+): FormatNumberOptions | undefined {
+  if (options === undefined) return undefined
+  return {
+    ...options,
+    showNegativeSign: true,
+    showPositiveSign: false,
+  }
+}
+
+const formatUsdCompact = (value: UsdInput, options?: FormatUsdOptions) =>
+  formatSignedUsd(
+    value,
+    (absolute) => abbreviateNumber(absolute, 2, true),
+    options,
+  )
+
+const formatUsdBalance = (
+  value: UsdInput,
+  options?: FormatUsdBalanceOptions,
+) =>
+  formatSignedUsd(
+    value,
+    (absolute) =>
+      formatNumber(
+        absolute,
+        mergePreset(USD_BALANCE_PRESET, absoluteUsdFormatOptions(options)),
+      ),
+    options,
+  )
+
+const formatCryptoBalance = (
+  value: NumberInput,
+  options?: FormatNumberOptions,
+) => formatNumber(value, options)
+
+const formatPercentage = (value: NumberInput, options?: FormatNumberOptions) =>
+  formatNumber(value, mergePreset(PERCENTAGE_PRESET, options))
+
+const formatInteger = (value: NumberInput, options?: FormatNumberOptions) =>
+  formatNumber(value, mergePreset(INTEGER_PRESET, options))
+
+const formatTokenPrice = (price: NumberInput, options?: FormatNumberOptions) =>
+  formatNumber(price, options)
+
+const formatBigInt = (
+  input: bigint | string | DecimalLike,
+  decimals: number,
+  formatOptions?: FormatNumberOptions,
+) => {
+  let atomic: bigint
+  if (typeof input === 'bigint') {
+    atomic = input
+  } else if (typeof input === 'string') {
+    atomic = BigInt(input)
+  } else {
+    atomic = parseUnits(input.toFixed(0), 0)
+  }
+  return formatNumber(Number(formatUnits(atomic, decimals)), formatOptions)
+}
+
+const formatLargeNumber = (
+  value: number | DecimalLike,
+  options?: SignFormatOptions,
+) => {
+  const numeric = typeof value === 'number' ? value : value.toNumber()
+  return abbreviateNumber(numeric, 2, false, options)
+}
+
+const formatSwapAmount = (
+  value: number | string,
+  options?: SignFormatOptions,
+): string => {
+  const number = typeof value === 'string' ? Number.parseFloat(value) : value
+
+  if (!number || number === 0) return '0'
+  if (number < 0) return options?.showNegativeSign === false ? '0' : '<0'
+
+  const [integerPart, decimalPart = ''] = expToString(number).split('.')
+
+  let formatted: string
+  if (!decimalPart) {
+    formatted = integerPart ?? '0'
+  } else {
+    const leadingZeroLength = (decimalPart.match(/^0+/) || [''])[0].length
+    const significantDigits = decimalPart.replace(/^0+/, '').substring(0, 3)
+    formatted = significantDigits
+      ? `${integerPart}.${'0'.repeat(leadingZeroLength)}${significantDigits}`
+      : '0'
+  }
+
+  return applyDisplaySign(formatted, number, options)
+}
+
+function computePercentile(
+  sorted: number[],
+  percentile: number,
+): number | null {
+  if (sorted.length === 0) return null
+
+  const index = (percentile / 100) * (sorted.length - 1)
+  const lower = Math.floor(index)
+  const upper = Math.ceil(index)
+
+  if (lower === upper) return sorted[lower] ?? null
+
+  const lowerValue = sorted[lower] ?? 0
+  const upperValue = sorted[upper] ?? lowerValue
+  return lowerValue + (upperValue - lowerValue) * (index - lower)
+}
+
+export const NumberUtils = {
+  formatNumber,
+  formatCryptoBalance,
+  formatUsdBalance,
+  formatPercentage,
+  formatUsdCompact,
+  formatInteger,
+  formatTokenPrice,
+  formatBigInt,
+  abbreviateNumber,
+  formatLargeNumber,
+  formatSwapAmount,
+  expToString,
+  computePercentile,
+}

package/src/units.ts

@@ -0,0 +1,92 @@
+/**
+ * `formatUnits` / `parseUnits` behavior from viem's `Value` module.
+ * Inlined so this package does not depend on viem.
+ */
+
+export function formatUnits(value: bigint, decimals: number): string {
+  assertDecimals(decimals)
+
+  let display = value.toString()
+  const negative = display.startsWith('-')
+  if (negative) display = display.slice(1)
+
+  display = display.padStart(decimals, '0')
+
+  const integer = display.slice(0, display.length - decimals)
+  let fraction = display.slice(display.length - decimals)
+  fraction = fraction.replace(/(0+)$/, '')
+  return `${negative ? '-' : ''}${integer || '0'}${fraction ? `.${fraction}` : ''}`
+}
+
+export function parseUnits(value: string, decimals: number): bigint {
+  assertDecimals(decimals)
+
+  if (!/^-?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)$/.test(value)) {
+    throw new Error(`\`${value}\` is not a valid decimal number.`)
+  }
+
+  let [integer = '', fraction = '0'] = value.split('.')
+
+  const negative = integer.startsWith('-')
+  if (negative) integer = integer.slice(1)
+  if (integer === '') integer = '0'
+
+  fraction = fraction.replace(/(0+)$/, '')
+
+  if (decimals === 0) {
+    const firstFractionDigit = fraction[0]
+    if (
+      fraction.length > 0 &&
+      firstFractionDigit !== undefined &&
+      Number.parseInt(firstFractionDigit, 10) >= 5
+    ) {
+      integer = `${BigInt(integer) + 1n}`
+    }
+    fraction = ''
+  } else if (fraction.length > decimals) {
+    const left = fraction.slice(0, decimals)
+    const roundDigitChar = fraction.slice(decimals, decimals + 1)
+    const roundDigit = Number.parseInt(roundDigitChar, 10)
+
+    if (roundDigit >= 5) {
+      const carried = carry(left)
+      if (carried.length > decimals) {
+        fraction = carried.slice(1)
+        integer = `${BigInt(integer) + 1n}`
+      } else {
+        fraction = carried
+      }
+    } else {
+      fraction = left
+    }
+  } else {
+    fraction = fraction.padEnd(decimals, '0')
+  }
+
+  return BigInt(`${negative ? '-' : ''}${integer}${fraction}`)
+}
+
+function assertDecimals(decimals: number): void {
+  if (!Number.isInteger(decimals) || decimals < 0) {
+    throw new Error(
+      `decimals must be a non-negative integer. Got \`${decimals}\`.`,
+    )
+  }
+}
+
+function carry(digits: string): string {
+  const out = digits.split('')
+  let i = out.length - 1
+  while (i >= 0) {
+    const current = out[i]
+    if (current === undefined) break
+    const next = Number.parseInt(current, 10) + 1
+    if (next < 10) {
+      out[i] = String(next)
+      return out.join('')
+    }
+    out[i] = '0'
+    i -= 1
+  }
+  return `1${out.join('')}`
+}