@rallycash/numbers 0.0.0-stage → 0.3.0

package/src/bigint-utils.ts

@@ -0,0 +1,222 @@
+import { type DecimalLike, isDecimalLike } from './decimal.js'
+import { expToString } from './number-utils.js'
+import { formatUnits, parseUnits } from './units.js'
+
+export type BigIntInput = bigint | number | string | DecimalLike
+
+/**
+ * Float multipliers are turned into a rational at this scale.
+ * Server wallet code used 18. Web used 10. Pass `scale` to pick one.
+ * This is not a USD decimal count.
+ */
+const DEFAULT_FLOAT_SCALE = 18
+
+const toBigInt = (value: BigIntInput, decimals = 0): bigint => {
+  if (typeof value === 'bigint') return value
+  if (isDecimalLike(value)) return parseUnits(value.toFixed(decimals), decimals)
+  return parseUnits(expToString(value), decimals)
+}
+
+const toNumber = (value: BigIntInput, decimals = 0): number =>
+  Number(formatUnits(toBigInt(value), decimals))
+
+const multiplyByNumber = (
+  value: bigint,
+  multiplier: number,
+  scale = DEFAULT_FLOAT_SCALE,
+) => {
+  if (!Number.isFinite(multiplier) || multiplier === 0) return 0n
+  const factor = 10 ** scale
+  const numerator =
+    multiplier < 1 ? 1n * BigInt(factor) : toBigInt(multiplier * factor)
+  const denominator =
+    multiplier < 1 ? toBigInt((1 / multiplier) * factor) : 1n * BigInt(factor)
+  return (value * numerator) / denominator
+}
+
+const createPercentage = (
+  numerator: BigIntInput,
+  denominator: BigIntInput,
+  scale = DEFAULT_FLOAT_SCALE,
+) => {
+  if (typeof numerator === 'number' && typeof denominator === 'number') {
+    return numerator / denominator
+  }
+  return Number(
+    formatUnits(
+      (toBigInt(numerator) * BigInt(10 ** scale)) / toBigInt(denominator),
+      scale,
+    ),
+  )
+}
+
+const abs = (value: bigint) => (value < 0n ? -value : value)
+
+const min = (a: bigint, b: bigint) => (a < b ? a : b)
+const max = (a: bigint, b: bigint) => (a > b ? a : b)
+
+const multiplyAsBigInt = (a: BigIntInput, b: BigIntInput, decimals: number) =>
+  toNumber(toBigInt(a, decimals) * toBigInt(b, decimals), decimals * 2)
+
+/**
+ * USD notional to token atomic units at `tokenPriceUsd`.
+ * `usdDecimals` is the caller's USD scale. This package does not pick one.
+ */
+const usdToTokenAmount = (
+  usd: number,
+  tokenPriceUsd: number,
+  tokenDecimals: number,
+  usdDecimals: number,
+): bigint => {
+  if (
+    !(usd > 0) ||
+    !(tokenPriceUsd > 0) ||
+    tokenDecimals < 0 ||
+    usdDecimals < 0
+  )
+    return 0n
+  return (
+    (toBigInt(usd, usdDecimals) * 10n ** BigInt(tokenDecimals)) /
+    toBigInt(tokenPriceUsd, usdDecimals)
+  )
+}
+
+/**
+ * Split a bigint amount into `count` parts as evenly as possible.
+ * Any remainder is distributed starting from the last bucket, so that
+ * `buckets[count - 1]` absorbs the remainder bits.
+ *
+ * Guarantees:
+ * - buckets.length === count
+ * - buckets.reduce(+, 0n) === amount
+ * - every bucket >= 0n
+ *
+ * Throws when count <= 0.
+ */
+const splitEvenly = (amount: bigint, count: number): bigint[] => {
+  if (count <= 0) throw new Error('splitEvenly: count must be > 0')
+  if (count === 1) return [amount]
+  const base = amount / BigInt(count)
+  const remainder = amount - base * BigInt(count)
+  const buckets = Array.from({ length: count }, () => base)
+  const last = buckets[count - 1]
+  if (last === undefined) throw new Error('splitEvenly: missing bucket')
+  buckets[count - 1] = last + remainder
+  return buckets
+}
+
+/**
+ * Like `splitEvenly`, but each of the first N-1 buckets is jittered within
+ * ±`variance` (as a fraction of the even-split base, e.g. 0.2 = ±20%),
+ * and the last bucket absorbs whatever's left so the total is preserved
+ * exactly.
+ *
+ * - Returns `splitEvenly` when `variance <= 0`, `count === 1`, or `amount === 0n`.
+ * - The last bucket's variance is emergent (it absorbs the complement of
+ *   the first N-1 jitters). If those buckets already sum past `amount`,
+ *   the excess is taken back from them so the total stays exact and no
+ *   bucket goes negative. Callers that need a strict per-bucket cap should
+ *   compose with `clampToCaps`.
+ *
+ * Guarantees (same as splitEvenly):
+ * - buckets.length === count
+ * - buckets.reduce(+, 0n) === amount
+ * - every bucket >= 0n (when variance ≤ 1; throws otherwise on negative)
+ */
+const splitWithVariance = (
+  amount: bigint,
+  count: number,
+  variance: number,
+  rng: () => number = Math.random,
+): bigint[] => {
+  if (count <= 0) throw new Error('splitWithVariance: count must be > 0')
+  if (count === 1 || variance <= 0 || amount === 0n) {
+    return splitEvenly(amount, count)
+  }
+  const clampedVariance = Math.min(1, Math.max(0, variance))
+
+  const precision = 1_000_000n
+  const base = amount / BigInt(count)
+
+  const buckets: bigint[] = []
+  let assigned = 0n
+  for (let i = 0; i < count - 1; i++) {
+    const factor = 1 + (rng() * 2 - 1) * clampedVariance
+    const scaled = BigInt(Math.round(factor * Number(precision)))
+    const bucket = (base * scaled) / precision
+    const nonNegative = bucket < 0n ? 0n : bucket
+    buckets.push(nonNegative)
+    assigned += nonNegative
+  }
+
+  let remaining = amount - assigned
+  if (remaining < 0n) {
+    for (let i = buckets.length - 1; i >= 0 && remaining < 0n; i--) {
+      const bucket = buckets[i] ?? 0n
+      const deficit = -remaining
+      const take = bucket < deficit ? bucket : deficit
+      buckets[i] = bucket - take
+      remaining += take
+    }
+  }
+  buckets.push(remaining < 0n ? 0n : remaining)
+  return buckets
+}
+
+/**
+ * Given an initial per-bucket allocation and per-bucket caps, clamp each
+ * bucket to its cap and redistribute the overflow to buckets that still
+ * have headroom (largest-headroom-first), preserving the total sum.
+ *
+ * Throws if `sum(caps) < sum(initial)`.
+ */
+const clampToCaps = (initial: bigint[], caps: bigint[]): bigint[] => {
+  if (initial.length !== caps.length) {
+    throw new Error('clampToCaps: initial and caps must be the same length')
+  }
+  const total = initial.reduce((sum, amount) => sum + amount, 0n)
+  const totalCap = caps.reduce((sum, cap) => sum + cap, 0n)
+  if (total > totalCap) {
+    throw new Error('clampToCaps: total exceeds aggregate capacity')
+  }
+
+  const result = initial.map((amount, i) => {
+    const cap = caps[i] ?? 0n
+    return amount > cap ? cap : amount
+  })
+  let shortfall = total - result.reduce((sum, amount) => sum + amount, 0n)
+  if (shortfall === 0n) return result
+
+  const byHeadroomDesc = result
+    .map((_, i) => i)
+    .sort((a, b) => {
+      const headroomA = (caps[a] ?? 0n) - (result[a] ?? 0n)
+      const headroomB = (caps[b] ?? 0n) - (result[b] ?? 0n)
+      return headroomA > headroomB ? -1 : headroomA < headroomB ? 1 : 0
+    })
+
+  for (const i of byHeadroomDesc) {
+    if (shortfall === 0n) break
+    const headroom = (caps[i] ?? 0n) - (result[i] ?? 0n)
+    const give = shortfall < headroom ? shortfall : headroom
+    result[i] = (result[i] ?? 0n) + give
+    shortfall -= give
+  }
+
+  return result
+}
+
+export const BigIntUtils = {
+  multiplyByNumber,
+  createPercentage,
+  abs,
+  min,
+  max,
+  toNumber,
+  toBigInt,
+  multiplyAsBigInt,
+  usdToTokenAmount,
+  splitEvenly,
+  splitWithVariance,
+  clampToCaps,
+}

package/src/decimal.ts

@@ -0,0 +1,25 @@
+/**
+ * Structural stand-in for Prisma's `Decimal` and decimal.js.
+ * Both satisfy this: `toFixed` keeps the decimal string, `toNumber` is the float view.
+ */
+export type DecimalLike = {
+  toFixed(digits: number): string
+  toNumber(): number
+}
+
+export type NumberInput = number | DecimalLike | null | undefined
+
+export function isDecimalLike(value: unknown): value is DecimalLike {
+  if (typeof value !== 'object' || value === null) return false
+  if (!('toFixed' in value) || !('toNumber' in value)) return false
+  return (
+    typeof value.toFixed === 'function' && typeof value.toNumber === 'function'
+  )
+}
+
+export function coerceNumber(value: NumberInput): number | null | undefined {
+  if (value == null) return value
+  if (typeof value === 'number') return value
+  if (isDecimalLike(value)) return value.toNumber()
+  return undefined
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { type BigIntInput, BigIntUtils } from './bigint-utils.js'
+export type { DecimalLike, NumberInput } from './decimal.js'
+export {
+  type FormatNumberOptions,
+  type FormatUsdBalanceOptions,
+  type FormatUsdOptions,
+  NumberUtils,
+  type SignFormatOptions,
+  type UsdInput,
+} from './number-utils.js'

package/src/number-utils.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from 'vitest'
+
+import { NumberUtils } from './number-utils.js'
+
+const decimalLike = {
+  toFixed(digits: number) {
+    return (1.5).toFixed(digits)
+  },
+  toNumber() {
+    return 1.5
+  },
+}
+
+describe('NumberUtils.formatNumber', () => {
+  it('formats a normal amount with grouping and two fraction digits', () => {
+    expect(NumberUtils.formatNumber(1234.5)).toBe('1,234.50')
+  })
+
+  it('abbreviates from 10 million', () => {
+    expect(NumberUtils.formatNumber(12_345_678)).toBe('12.3M')
+    expect(NumberUtils.formatNumber(1_000_000)).toBe('1,000,000.00')
+  })
+
+  it('renders dust with a subscript zero count', () => {
+    expect(NumberUtils.formatNumber(0.0000001234)).toBe('0.0₆123')
+  })
+
+  it('accepts a decimal-like object', () => {
+    expect(NumberUtils.formatNumber(decimalLike)).toBe('1.50')
+  })
+
+  it('returns an empty string for null', () => {
+    expect(NumberUtils.formatNumber(null)).toBe('')
+  })
+
+  it('keeps the sign on a tiny number when exponents are off', () => {
+    expect(
+      NumberUtils.formatNumber(-0.0000001234, { showExponents: false }),
+    ).toBe('-0.0000001234')
+  })
+
+  it('honors abbreviation options', () => {
+    expect(
+      NumberUtils.formatNumber(1_000_000_000, { abbrThreshold: 1e12 }),
+    ).toBe('1,000,000,000.00')
+    expect(
+      NumberUtils.formatNumber(1_000_000_000, { abbreviateLargeNumbers: false }),
+    ).toBe('1,000,000,000.00')
+  })
+
+  it('shows a minus by default and a plus only when asked', () => {
+    expect(NumberUtils.formatNumber(-1.2)).toBe('-1.20')
+    expect(NumberUtils.formatNumber(-1.2, { showNegativeSign: false })).toBe(
+      '1.20',
+    )
+    expect(NumberUtils.formatNumber(1.2, { showPositiveSign: true })).toBe(
+      '+1.20',
+    )
+    expect(NumberUtils.formatNumber(0, { showPositiveSign: true })).toBe('0.00')
+  })
+})
+
+describe('NumberUtils.abbreviateNumber', () => {
+  it('uses the suffix of an exact tier and promotes a rounded 1000', () => {
+    expect(NumberUtils.abbreviateNumber(1_000_000, 2)).toBe('1M')
+    expect(NumberUtils.abbreviateNumber(999_500, 0)).toBe('1M')
+  })
+})
+
+describe('NumberUtils presets', () => {
+  it('formats a crypto balance with the general formatter', () => {
+    expect(NumberUtils.formatCryptoBalance(1234.5)).toBe('1,234.50')
+    expect(NumberUtils.formatCryptoBalance(0.0000001234)).toBe('0.0₆123')
+  })
+
+  it('formats a USD balance with a leading dollar sign and two decimals', () => {
+    expect(NumberUtils.formatUsdBalance(1234.5)).toBe('$1,234.50')
+    expect(NumberUtils.formatUsdBalance(-1.2)).toBe('-$1.20')
+    expect(NumberUtils.formatUsdBalance(0)).toBe('$0.00')
+    expect(NumberUtils.formatUsdBalance(12_345_678)).toBe('$12.3M')
+  })
+
+  it('formats abbreviated USD', () => {
+    expect(NumberUtils.formatUsdCompact(1.5)).toBe('$1.50')
+    expect(NumberUtils.formatUsdCompact(1234.5)).toBe('$1.23K')
+    expect(NumberUtils.formatUsdCompact(-12_345_678)).toBe('-$12.35M')
+    expect(NumberUtils.formatUsdCompact(null)).toBe('$0.00')
+  })
+
+  it('can hide the dollar sign and choose the sign character', () => {
+    expect(
+      NumberUtils.formatUsdBalance(1234.5, { showCurrencySymbol: false }),
+    ).toBe('1,234.50')
+    expect(
+      NumberUtils.formatUsdBalance(-1.2, {
+        showCurrencySymbol: false,
+        showNegativeSign: false,
+      }),
+    ).toBe('1.20')
+    expect(
+      NumberUtils.formatUsdBalance(1.2, { showPositiveSign: true }),
+    ).toBe('+$1.20')
+    expect(
+      NumberUtils.formatUsdCompact(1234.5, { showCurrencySymbol: false }),
+    ).toBe('1.23K')
+    expect(
+      NumberUtils.formatUsdCompact(-12_345_678, { showNegativeSign: false }),
+    ).toBe('$12.35M')
+    expect(NumberUtils.formatUsdCompact(1.5, { showPositiveSign: true })).toBe(
+      '+$1.50',
+    )
+  })
+
+  it('formats a percentage with at most two decimals and no subscript', () => {
+    expect(NumberUtils.formatPercentage(12.3)).toBe('12.3')
+    expect(NumberUtils.formatPercentage(12.345)).toBe('12.35')
+    expect(NumberUtils.formatPercentage(0.0000001234)).toBe('0')
+  })
+
+  it('formats an integer', () => {
+    expect(NumberUtils.formatInteger(6737233.2323223)).toBe('6,737,233')
+    expect(
+      NumberUtils.formatInteger(12_345_678, { abbreviateLargeNumbers: false }),
+    ).toBe('12,345,678')
+  })
+})
+
+describe('NumberUtils.formatBigInt', () => {
+  it('formats atomic units with the general formatter', () => {
+    expect(NumberUtils.formatBigInt(1_500000n, 6)).toBe('1.50')
+  })
+})
+
+describe('NumberUtils.expToString', () => {
+  it('expands scientific notation', () => {
+    expect(NumberUtils.expToString(1e23)).toBe('100000000000000000000000')
+    expect(NumberUtils.expToString(-1e-7)).toBe('-0.0000001')
+    expect(NumberUtils.expToString('1e23')).toBe('100000000000000000000000')
+    expect(NumberUtils.expToString('100000000000000000000000')).toBe(
+      '100000000000000000000000',
+    )
+  })
+})
+
+describe('NumberUtils.computePercentile', () => {
+  it('interpolates', () => {
+    expect(NumberUtils.computePercentile([10, 20, 30, 40, 50], 50)).toBe(30)
+    expect(NumberUtils.computePercentile([10, 20, 30, 40, 50], 75)).toBe(40)
+    expect(NumberUtils.computePercentile([10, 20, 30, 40, 50], 95)).toBe(48)
+  })
+
+  it('returns null for an empty list', () => {
+    expect(NumberUtils.computePercentile([], 50)).toBeNull()
+  })
+})
+
+describe('NumberUtils.formatSwapAmount', () => {
+  it('keeps three digits after leading zeros', () => {
+    expect(NumberUtils.formatSwapAmount(0.000015045814)).toBe('0.0000150')
+    expect(NumberUtils.formatSwapAmount(1.5e-7)).toBe('0.00000015')
+    expect(NumberUtils.formatSwapAmount(0.15045814096)).toBe('0.150')
+  })
+
+  it('adds a plus only when asked and can hide the negative marker', () => {
+    expect(
+      NumberUtils.formatSwapAmount(0.15045814096, { showPositiveSign: true }),
+    ).toBe('+0.150')
+    expect(NumberUtils.formatSwapAmount(-1, { showNegativeSign: false })).toBe(
+      '0',
+    )
+    expect(NumberUtils.formatSwapAmount(-1)).toBe('<0')
+  })
+})
+
+describe('NumberUtils sign options on abbreviation', () => {
+  it('applies to abbreviateNumber and formatLargeNumber', () => {
+    expect(NumberUtils.abbreviateNumber(-1500, 2)).toBe('-1.5K')
+    expect(
+      NumberUtils.abbreviateNumber(-1500, 2, false, { showNegativeSign: false }),
+    ).toBe('1.5K')
+    expect(NumberUtils.formatLargeNumber(1500, { showPositiveSign: true })).toBe(
+      '+1.5K',
+    )
+  })
+})