@lifi/perps-sdk 23.1.0 → 24.0.0

package/src/decimal/convert.ts

@@ -1,44 +1,92 @@
-import { type DecimalString, PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsErrorCode } from '@lifi/perps-types'
 import Big from 'big.js'
 import { formatUnits } from 'viem'
 import { PerpsError } from '../errors/PerpsError.js'
-import { requireDecimal } from './requireDecimal.js'
+import { createSafeFunction } from '../utils/createSafeFunction.js'
+import { bigToDecimalString, decimalStringToBig } from './decimalStringToBig.js'
+import { isDecimalString } from './parse.js'
 
 /**
- * Off-grid resolution for {@link decimalToBaseUnits}:
- * - `truncate` — toward zero, for sizes and collateral amounts. The wire
- *   value never exceeds the caller's intent.
- * - `round` — half away from zero, for prices, which snap to the nearest
- *   tick.
+ * Off-grid resolution for {@link roundDecimalString}:
+ * - `truncate`: toward zero, for sizes and collateral amounts. The result
+ *   never exceeds the caller's intent.
+ * - `round`: half away from zero, for prices, which snap to the nearest tick.
+ * - `up`: away from zero, for an amount that must cover a target.
  * @public
  */
-export type BaseUnitsRounding = 'truncate' | 'round'
+export type DecimalRounding = 'truncate' | 'round' | 'up'
+
+const BIG_ROUNDING = {
+  truncate: Big.roundDown,
+  round: Big.roundHalfUp,
+  up: Big.roundUp,
+} as const
 
 /**
- * Scale a decimal string to a scaled integer in exact decimal arithmetic — an
- * on-grid input maps to its exact scaled integer with no binary float
- * artifacts (`'0.29'` at 2 decimals is 29, never 28). Off-grid input resolves
- * per `rounding`; there is no silent default.
+ * Round a decimal string to `decimals` places with exact decimal arithmetic.
+ * The result has no trailing zeros: `roundDecimalString('1.50', 1, 'round')`
+ * is `'1.5'`.
  *
- * @throws {PerpsError} `ValidationError` when `value` is not a
- *   {@link DecimalString}, `decimals` is not a non-negative integer, or the scaled
- *   result's magnitude exceeds `Number.MAX_SAFE_INTEGER`.
+ * @throws {PerpsError} `ValidationError` when `value` is not a decimal string,
+ *   or `decimals` is not a non-negative integer.
  * @public
  */
-export const decimalToBaseUnits = (
-  value: DecimalString,
+export function roundDecimalString(
+  value: string,
   decimals: number,
-  rounding: BaseUnitsRounding
-): number => {
+  rounding: DecimalRounding
+): string {
+  if (!Number.isInteger(decimals) || decimals < 0) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid decimals for rounding: ${decimals}`
+    )
+  }
+  return bigToDecimalString(
+    decimalStringToBig(value).round(decimals, BIG_ROUNDING[rounding])
+  )
+}
+
+/**
+ * {@link roundDecimalString}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export const safeRoundDecimalString = createSafeFunction(
+  'roundDecimalString',
+  roundDecimalString
+)
+
+/**
+ * Scale a decimal string to an integer at `decimals` places in exact decimal
+ * arithmetic: `'0.29'` at 2 decimals is 29, never 28. Off-grid input resolves
+ * per `rounding`. No `$`, `%` or `,` is removed first.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` is not a decimal string,
+ *   `decimals` is not a non-negative integer, or the result's magnitude
+ *   exceeds `Number.MAX_SAFE_INTEGER`.
+ * @public
+ */
+export function decimalStringToScaledInteger(
+  value: string,
+  decimals: number,
+  rounding: DecimalRounding
+): number {
+  if (!isDecimalString(value)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `'${value}' is not a decimal string.`
+    )
+  }
   if (!Number.isInteger(decimals) || decimals < 0) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
       `Invalid decimals for integer scaling: ${decimals}`
     )
   }
-  const scaled = requireDecimal(value, 'decimalToBaseUnits(value)')
+  const scaled = new Big(value)
     .times(new Big(10).pow(decimals))
-    .round(0, rounding === 'truncate' ? Big.roundDown : Big.roundHalfUp)
+    .round(0, BIG_ROUNDING[rounding])
   if (scaled.abs().gt(Number.MAX_SAFE_INTEGER)) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
@@ -48,40 +96,57 @@ export const decimalToBaseUnits = (
   return scaled.toNumber()
 }
 
-const BASE_UNITS_PATTERN = /^-?\d+$/
+/**
+ * {@link decimalStringToScaledInteger}, or `undefined` with a warning when it
+ * throws.
+ *
+ * @public
+ */
+export const safeDecimalStringToScaledInteger = createSafeFunction(
+  'decimalStringToScaledInteger',
+  decimalStringToScaledInteger
+)
+
+export const BASE_UNITS_PATTERN = /^-?\d+$/
 
 /**
- * Convert a base-unit amount (integer string) to a decimal string.
+ * Convert a scaled integer string (a token amount in base units) to a decimal
+ * string: `scaledIntegerToDecimalString('1000000', 6)` is `'1'`.
  *
- * @param amount - Amount in base units (e.g. "1000000" for 1 USDC)
- * @param decimals - Token decimals (e.g. 6 for USDC)
  * @throws {PerpsError} `ValidationError` when `amount` is not an integer
  *   string, or `decimals` is not a non-negative integer.
- * @example
- * ```ts
- * baseUnitsToDecimal('1000000', 6) // '1'
- * ```
  * @public
  */
-export function baseUnitsToDecimal(
-  amount: DecimalString,
+export function scaledIntegerToDecimalString(
+  amount: string,
   decimals: number
-): DecimalString {
+): string {
   if (!Number.isInteger(decimals) || decimals < 0) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
-      `Invalid \`baseUnitsToDecimal(decimals)\`: ${decimals} is not a non-negative integer.`
+      `Invalid \`scaledIntegerToDecimalString(decimals)\`: ${decimals} is not a non-negative integer.`
     )
   }
   if (!BASE_UNITS_PATTERN.test(amount)) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
-      `Invalid \`baseUnitsToDecimal(amount)\`: '${amount}' is not an integer base-unit string.`
+      `Invalid \`scaledIntegerToDecimalString(amount)\`: '${amount}' is not an integer base-unit string.`
     )
   }
   return formatUnits(BigInt(amount), decimals)
 }
 
+/**
+ * {@link scaledIntegerToDecimalString}, or `undefined` with a warning when it
+ * throws.
+ *
+ * @public
+ */
+export const safeScaledIntegerToDecimalString = createSafeFunction(
+  'scaledIntegerToDecimalString',
+  scaledIntegerToDecimalString
+)
+
 /**
  * Round `value` down to `decimals` and pad the result to exactly that many
  * decimal places. The padding is the point: this seeds a fixed-decimal input,
@@ -94,27 +159,31 @@ export function baseUnitsToDecimal(
  * `'0.010000000000000000'`, which `Number#toFixed` cannot.
  *
  * @throws {PerpsError} `ValidationError` when `value` is not a
- *   {@link DecimalString}, or `decimals` is not a non-negative integer.
+ *   decimal string, or `decimals` is not a non-negative integer.
  * @public
  */
-export function truncateDecimal(
-  value: DecimalString,
-  decimals: number
-): DecimalString {
+export function truncateDecimal(value: string, decimals: number): string {
   if (!Number.isInteger(decimals) || decimals < 0) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
       `Invalid decimals for truncation: ${decimals}`
     )
   }
-  const truncated = requireDecimal(value, 'truncateDecimal(value)').round(
-    decimals,
-    Big.roundDown
-  )
+  const truncated = decimalStringToBig(value).round(decimals, Big.roundDown)
   // big.js carries the sign through a round to zero; '-0.00' is not a spelling.
   return (truncated.eq(0) ? new Big(0) : truncated).toFixed(decimals)
 }
 
+/**
+ * {@link truncateDecimal}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export const safeTruncateDecimal = createSafeFunction(
+  'truncateDecimal',
+  truncateDecimal
+)
+
 /**
  * Spell a `number` as a {@link DecimalString} in plain notation: `1e-7`
  * becomes `'0.0000001'`, never `'1e-7'`. The boundary helper for a venue or
@@ -125,7 +194,7 @@ export function truncateDecimal(
  * @throws {PerpsError} `ValidationError` when `value` is `NaN` or infinite.
  * @public
  */
-export function numberToDecimalString(value: number): DecimalString {
+export function numberToDecimalString(value: number): string {
   if (!Number.isFinite(value)) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
@@ -135,3 +204,13 @@ export function numberToDecimalString(value: number): DecimalString {
   const parsed = new Big(value)
   return (parsed.eq(0) ? new Big(0) : parsed).toFixed()
 }
+
+/**
+ * {@link numberToDecimalString}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export const safeNumberToDecimalString = createSafeFunction(
+  'numberToDecimalString',
+  numberToDecimalString
+)

package/src/decimal/decimalStringToBig.ts

@@ -0,0 +1,47 @@
+import { DECIMAL_PATTERN, PerpsErrorCode } from '@lifi/perps-types'
+import Big from 'big.js'
+import { PerpsError } from '../errors/PerpsError.js'
+import { DivBig } from './big.js'
+
+const DISPLAY_CHARACTERS = /[\s$%,]/g
+
+/**
+ * Read a decimal string as a `Big`. Whitespace, `$`, `%` and `,` are removed
+ * first, so `'$1,234.5'` reads as `1234.5`; the rest must match
+ * `DECIMAL_PATTERN`, so an exponent form such as `'1e5'` is rejected.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` is not a string or the
+ *   cleaned string is not a decimal string.
+ * @internal
+ */
+export function decimalStringToBig(value: string): Big {
+  const cleaned =
+    typeof value === 'string' ? value.replace(DISPLAY_CHARACTERS, '') : ''
+  if (!DECIMAL_PATTERN.test(cleaned)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `'${String(value)}' is not a decimal string.`
+    )
+  }
+  return new Big(cleaned)
+}
+
+/**
+ * Spell a `Big` as a canonical decimal string, with no exponent and no `-0`.
+ *
+ * @internal
+ */
+export function bigToDecimalString(value: Big): string {
+  return value.eq(0) ? '0' : value.toFixed()
+}
+
+/**
+ * {@link decimalStringToBig} as a `DivBig`, so a later `div` keeps 40 decimal
+ * places.
+ *
+ * @throws {PerpsError} `ValidationError` as {@link decimalStringToBig}.
+ * @internal
+ */
+export function decimalStringToDivBig(value: string): Big {
+  return new DivBig(decimalStringToBig(value))
+}

package/src/decimal/format.ts

@@ -1,4 +1,6 @@
 import type { DecimalString } from '@lifi/perps-types'
+import Big from 'big.js'
+import { decimalStringToBig } from './decimalStringToBig.js'
 
 /**
  * Options shared by the human-facing display formatters.
@@ -8,7 +10,10 @@ import type { DecimalString } from '@lifi/perps-types'
 export interface FormatOptions {
   /** Fixed number of decimal places. Defaults are per-formatter. */
   decimals?: number
-  /** Rendered when the value is null/undefined/NaN/non-finite. Defaults to `'—'`. */
+  /**
+   * Rendered when the value is null, undefined, blank or a non-finite number.
+   * A string that is not a decimal is shown unchanged. Defaults to `'—'`.
+   */
   placeholder?: string
   /** BCP 47 locale controlling digit grouping and separators (e.g. `'en-US'`). */
   locale?: string
@@ -33,76 +38,62 @@ const DEFAULT_PLACEHOLDER = '—'
 type FormatInput = number | DecimalString | string | null | undefined
 
 /**
- * Extra decimal places used to normalise IEEE-754 representation noise before
- * truncating. `toFixed` at this higher precision cleans values like
- * `0.28999999…` back to `0.29`; truncation then chops the guard digits.
- */
-const FLOAT_GUARD_DIGITS = 9
-
-/**
- * Tolerantly coerce a display input to a finite number.
- *
- * Strips `$`, `,`, and surrounding whitespace from strings. Returns `null`
- * when the value is null/undefined/blank or does not resolve to a finite
- * number, so callers can render a placeholder instead of `$0.00` or `$NaN`.
+ * Read a display input as a `Big`: `$`, `%`, `,` and whitespace are removed
+ * from a string first. `null` means the formatter renders the placeholder;
+ * a string it cannot read is returned unchanged for display.
  */
-function toFiniteNumber(value: FormatInput): number | null {
-  let n: number
-  if (typeof value === 'string') {
-    const cleaned = value.replace(/[$,\s]/g, '')
-    if (!cleaned) {
-      return null
-    }
-    n = Number(cleaned)
-  } else if (typeof value === 'number') {
-    n = value
-  } else {
+function toBig(value: FormatInput): Big | null | string {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? new Big(value) : null
+  }
+  if (typeof value !== 'string' || value.trim() === '') {
     return null
   }
-  return Number.isFinite(n) ? n : null
+  try {
+    return decimalStringToBig(value)
+  } catch {
+    return value
+  }
 }
 
-/**
- * Truncate a non-negative value toward zero to `decimals` places using its
- * decimal string, never float scaling. Representation noise is first
- * normalised by `toFixed` at {@link FLOAT_GUARD_DIGITS} extra precision, then
- * the guard digits are chopped: `99.999` at 2dp → `99.99`, `0.29` → `0.29`.
- */
-function truncateAbs(abs: number, decimals: number): number {
-  // `toFixed` emits exponent notation at >= 1e21; every double that large is an integer.
-  if (Number.isInteger(abs)) {
-    return abs
-  }
-  const s = abs.toFixed(Math.min(decimals + FLOAT_GUARD_DIGITS, 100))
-  const dot = s.indexOf('.')
-  const cut = decimals === 0 ? dot : dot + 1 + decimals
-  return Number(s.slice(0, cut))
+function decimalSeparator(locale: string | undefined): string {
+  return (
+    new Intl.NumberFormat(locale)
+      .formatToParts(1.5)
+      .find((part) => part.type === 'decimal')?.value ?? '.'
+  )
 }
 
 /**
- * Reduce `n` to `decimals` places then split into a sign and the
+ * Reduce `value` to `decimals` places then split into a sign and the
  * locale-formatted absolute body. The sign is derived from the reduced value
  * so magnitudes that collapse to zero render without a spurious `-`/`+`.
  * `signed` emits `+` for positives; `rounding` selects half-up or truncation.
  */
 function signAndBody(
-  n: number,
+  value: Big,
   decimals: number,
   locale: string | undefined,
   grouping: boolean,
   rounding: RoundingMode,
   signed: boolean
 ): { sign: '+' | '-' | ''; body: string } {
-  const reduced =
-    rounding === 'floor'
-      ? (n < 0 ? -1 : 1) * truncateAbs(Math.abs(n), decimals)
-      : Number(n.toFixed(decimals))
-  const sign = reduced < 0 ? '-' : signed && reduced > 0 ? '+' : ''
-  const body = Math.abs(reduced).toLocaleString(locale, {
-    minimumFractionDigits: decimals,
-    maximumFractionDigits: decimals,
-    useGrouping: grouping,
-  })
+  const reduced = value.round(
+    decimals,
+    rounding === 'floor' ? Big.roundDown : Big.roundHalfUp
+  )
+  const sign = reduced.lt(0) ? '-' : signed && reduced.gt(0) ? '+' : ''
+  const [integerPart = '0', fractionPart] = reduced
+    .abs()
+    .toFixed(decimals)
+    .split('.')
+  const integerBody = grouping
+    ? BigInt(integerPart).toLocaleString(locale)
+    : integerPart
+  const body =
+    fractionPart === undefined
+      ? integerBody
+      : `${integerBody}${decimalSeparator(locale)}${fractionPart}`
   return { sign, body }
 }
 
@@ -110,14 +101,14 @@ function signAndBody(
  * Auto-detect a sensible number of decimal places from a value's magnitude:
  * `>=1` → 2, `>=0.1` → 4, `>=0.01` → 5, otherwise 6.
  */
-function autoDecimals(abs: number): number {
-  if (abs >= 1) {
+function autoDecimals(abs: Big): number {
+  if (abs.gte(1)) {
     return 2
   }
-  if (abs >= 0.1) {
+  if (abs.gte('0.1')) {
     return 4
   }
-  if (abs >= 0.01) {
+  if (abs.gte('0.01')) {
     return 5
   }
   return 6
@@ -145,10 +136,13 @@ export function formatNumber(
     locale,
     rounding = 'halfUp',
   } = options
-  const n = toFiniteNumber(value)
+  const n = toBig(value)
   if (n === null) {
     return placeholder
   }
+  if (typeof n === 'string') {
+    return n
+  }
   const { sign, body } = signAndBody(n, decimals, locale, true, rounding, false)
   return `${sign}${body}`
 }
@@ -171,10 +165,13 @@ export function formatUsd(
     locale,
     rounding = 'halfUp',
   } = options
-  const n = toFiniteNumber(value)
+  const n = toBig(value)
   if (n === null) {
     return placeholder
   }
+  if (typeof n === 'string') {
+    return n
+  }
   const { sign, body } = signAndBody(n, decimals, locale, true, rounding, false)
   return `${sign}$${body}`
 }
@@ -198,10 +195,13 @@ export function formatSignedUsd(
     locale,
     rounding = 'halfUp',
   } = options
-  const n = toFiniteNumber(value)
+  const n = toBig(value)
   if (n === null) {
     return placeholder
   }
+  if (typeof n === 'string') {
+    return n
+  }
   const { sign, body } = signAndBody(n, decimals, locale, true, rounding, true)
   return `${sign}$${body}`
 }
@@ -225,10 +225,13 @@ export function formatSignedPercent(
     locale,
     rounding = 'halfUp',
   } = options
-  const n = toFiniteNumber(value)
+  const n = toBig(value)
   if (n === null) {
     return placeholder
   }
+  if (typeof n === 'string') {
+    return n
+  }
   const { sign, body } = signAndBody(n, decimals, locale, false, rounding, true)
   return `${sign}${body}%`
 }
@@ -252,17 +255,20 @@ export function formatPrice(
     locale,
     rounding = 'halfUp',
   } = options
-  const n = toFiniteNumber(value)
+  const n = toBig(value)
   if (n === null) {
     return placeholder
   }
-  const abs = Math.abs(n)
+  if (typeof n === 'string') {
+    return n
+  }
+  const abs = n.abs()
   const decimals = options.decimals ?? autoDecimals(abs)
   const { sign, body } = signAndBody(
     n,
     decimals,
     locale,
-    abs >= 1000,
+    abs.gte(1000),
     rounding,
     false
   )
@@ -283,20 +289,23 @@ export function formatCompactUsd(
   options: FormatOptions = {}
 ): string {
   const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER } = options
-  const n = toFiniteNumber(value)
+  const n = toBig(value)
   if (n === null) {
     return placeholder
   }
-  const sign = n < 0 ? '-' : ''
-  const abs = Math.abs(n)
-  if (abs >= 1_000_000_000) {
-    return `${sign}$${(abs / 1_000_000_000).toFixed(decimals)}B`
+  if (typeof n === 'string') {
+    return n
+  }
+  const sign = n.lt(0) ? '-' : ''
+  const abs = n.abs()
+  if (abs.gte(1_000_000_000)) {
+    return `${sign}$${abs.div(1_000_000_000).toFixed(decimals)}B`
   }
-  if (abs >= 1_000_000) {
-    return `${sign}$${(abs / 1_000_000).toFixed(decimals)}M`
+  if (abs.gte(1_000_000)) {
+    return `${sign}$${abs.div(1_000_000).toFixed(decimals)}M`
   }
-  if (abs >= 1_000) {
-    return `${sign}$${(abs / 1_000).toFixed(decimals)}K`
+  if (abs.gte(1_000)) {
+    return `${sign}$${abs.div(1_000).toFixed(decimals)}K`
   }
   return `${sign}$${abs.toFixed(decimals)}`
 }