@rallycash/numbers 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @rallycash/numbers
 
+## 0.3.0
+
+### Minor Changes
+
+- ecdc16e: Rename `formatUsd` to `formatUsdCompact`. Add `showCurrencySymbol`, `showNegativeSign`, and `showPositiveSign` to the display formatters.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -18,10 +18,19 @@ yarn add @rallycash/numbers
 
 ## NumberUtils
 
-`formatNumber` is the general formatter. The named methods below are presets on top of it, except `formatUsd`, which always abbreviates.
+`formatNumber` is the general formatter. The named formatters below are presets on top of it, except `formatUsdCompact`, `abbreviateNumber`, `formatLargeNumber`, and `formatSwapAmount`.
+
+Two pairs that look alike:
+
+- `formatUsdBalance` is a cash balance. `$1,234.50` stays written out, and abbreviation starts at 10 million.
+- `formatUsdCompact` is a compact dollar headline. Abbreviation starts at one thousand, so the same amount is `$1.23K`.
+- `formatCryptoBalance` is a token balance. It uses grouping, two fraction digits, and subscript dust (`0.0₆123`).
+- `formatSwapAmount` is a swap size. It keeps three significant digits after leading zeros, with no commas and no subscripts (`0.0000150`).
 
 ### `formatNumber(value, options?)`
 
+Use when no preset fits and you need to set the fraction digits, subscript behavior, or abbreviation threshold yourself.
+
 ```ts
 formatNumber(
   value: number | DecimalLike | null | undefined,
@@ -39,6 +48,8 @@ formatNumber(
 | `abbreviateLargeNumbers` | `true` |
 | `abbrMinSignificantDigits` | `3` |
 | `prefix` | `''` |
+| `showNegativeSign` | `true` |
+| `showPositiveSign` | `false` |
 
 `null`, `undefined`, and `NaN` return `''`. `0` returns `0.00` at the default fraction digits.
 
@@ -54,88 +65,159 @@ Dust smaller than `maxDecimals` places, but not small enough for a subscript, re
 
 This is the server formatter. The web copy abbreviated from 1 trillion, used 4 fraction digits below 10, and rendered that underflow case as `0.00`.
 
-### Presets
+### `formatCryptoBalance(value, options?)`
 
-Each preset calls `formatNumber` with fixed options. Pass `options` to override the preset. `formatUsd` does not. It always abbreviates through `abbreviateNumber`.
+Use when the value is a token balance already in human units, and a million tokens should still read as `1,000,000.00`.
 
-#### `formatCryptoBalance(value, options?)`
-
-Token amount. Same defaults as `formatNumber`, including subscripts for dust.
+Atomic units go through `formatBigInt` first.
 
 ```ts
+// equivalent to -> formatNumber(value)
+// Pass options to override.
 NumberUtils.formatCryptoBalance(1234.5) // "1,234.50"
 NumberUtils.formatCryptoBalance(0.0000001234) // "0.0₆123"
+NumberUtils.formatCryptoBalance(0.000015045814) // "0.000015"
 ```
 
-Atomic units go through `formatBigInt` or `BigIntUtils.toNumber` first. This method formats an already-human amount.
-
-#### `formatUsdBalance(value, options?)`
-
-Cash balance. Replaces `formatCurrencyAmount`.
+### `formatUsdBalance(value, options?)`
 
-Preset options: `minDecimals: 2`, `maxDecimals: 2`, `minSignificantDigits: 0`, `showExponents: false`.
+Use when the value is someone's cash balance, rewards, or fees, and `$1,234.50` should stay fully written.
 
-The `$` is applied here, with the sign in front. `0`, `null`, `undefined`, and `NaN` return `$0.00`. Amounts at or above 10 million still abbreviate, same as `formatNumber`.
+Replaces `formatCurrencyAmount`. The `$` is applied after formatting, with the sign in front. `showCurrencySymbol` defaults to `true`. `0`, `null`, `undefined`, and `NaN` return `$0.00`. Amounts at or above 10 million still abbreviate. There is no subscript for dust.
 
 ```ts
+// equivalent to -> formatNumber(value, { minDecimals: 2, maxDecimals: 2, minSignificantDigits: 0, showExponents: false })
+// Pass options to override. `$` is applied outside that call.
 NumberUtils.formatUsdBalance(1234.5) // "$1,234.50"
 NumberUtils.formatUsdBalance(-1.2) // "-$1.20"
 NumberUtils.formatUsdBalance(0) // "$0.00"
 NumberUtils.formatUsdBalance(12_345_678) // "$12.3M"
+NumberUtils.formatUsdBalance(1234.5, { showCurrencySymbol: false }) // "1,234.50"
+NumberUtils.formatUsdBalance(1.2, { showPositiveSign: true }) // "+$1.20"
+```
+
+### `formatUsdCompact(value, options?)`
+
+Use when the value is a dollar headline in a tight row: market cap, volume, liquidity, or trade size. Abbreviation starts at one thousand, not ten million.
+
+Not a `formatNumber` wrapper. It abbreviates with two fraction digits and keeps trailing zeros, then puts `$` in front. `showCurrencySymbol` defaults to `true`. `0`, `null`, `undefined`, and `NaN` return `$0.00`.
+
+```ts
+NumberUtils.formatUsdCompact(1.5) // "$1.50"
+NumberUtils.formatUsdCompact(1234.5) // "$1.23K"
+NumberUtils.formatUsdCompact(-12_345_678) // "-$12.35M"
+NumberUtils.formatUsdCompact(null) // "$0.00"
+NumberUtils.formatUsdCompact(1234.5, { showCurrencySymbol: false }) // "1.23K"
 ```
 
-#### `formatPercentage(value, options?)`
+### `formatPercentage(value, options?)`
 
-Preset options: `minDecimals: 0`, `maxDecimals: 2`, `minSignificantDigits: 0`, `showExponents: false`.
+Use when the value is already a percent (`12.3` means 12.3%) and the caller will add `%` if the UI needs it.
 
-Does not append `%`.
+Does not append `%`. Dust collapses to `0` because subscripts are off.
 
 ```ts
+// equivalent to -> formatNumber(value, { minDecimals: 0, maxDecimals: 2, minSignificantDigits: 0, showExponents: false })
+// Pass options to override.
 NumberUtils.formatPercentage(12.3) // "12.3"
 NumberUtils.formatPercentage(12.345) // "12.35"
 NumberUtils.formatPercentage(0.0000001234) // "0"
 ```
 
-#### `formatUsd(value)`
+### `formatInteger(value, options?)`
 
-Abbreviated USD. Not a `formatNumber` preset. Two fraction digits, trailing zeros kept, `$` in front.
+Use when the value is a count: transactions, holders, or points. The fraction is dropped.
+
+Counts at or above 10 million still abbreviate.
 
 ```ts
-NumberUtils.formatUsd(1.5) // "$1.50"
-NumberUtils.formatUsd(1234.5) // "$1.23K"
-NumberUtils.formatUsd(-12_345_678) // "-$12.35M"
-NumberUtils.formatUsd(null) // "$0.00"
+// equivalent to -> formatNumber(value, { minDecimals: 0, maxDecimals: 0, minSignificantDigits: 0, showExponents: false })
+// Pass options to override.
+NumberUtils.formatInteger(6737233.2323223) // "6,737,233"
+NumberUtils.formatInteger(12_345_678, { abbreviateLargeNumbers: false }) // "12,345,678"
 ```
 
-`formatUsd(1234.5)` is `$1.23K`. `formatUsdBalance(1234.5)` is `$1,234.50`.
-
-#### `formatInteger(value, options?)`
+### `formatTokenPrice(value)`
 
-Whole numbers. Preset: `minDecimals: 0`, `maxDecimals: 0`, `minSignificantDigits: 0`, `showExponents: false`.
+Use when the value is a token price in USD and it should follow the general formatter, including subscript dust and the 10 million abbreviation threshold. The caller adds `$`.
 
 ```ts
-NumberUtils.formatInteger(6737233.2323223) // "6,737,233"
+// equivalent to -> formatNumber(value)
+// Pass options to override.
+NumberUtils.formatTokenPrice(1234.5) // "1,234.50"
+NumberUtils.formatTokenPrice(0.0000001234) // "0.0₆123"
 ```
 
-### Other NumberUtils methods
+### `formatBigInt(atomic, decimals, options?)`
 
-| Method | Role |
-| --- | --- |
-| `formatTokenPrice(value)` | Alias of `formatNumber`. No extra preset. |
-| `formatBigInt(atomic, decimals, options?)` | Atomic `bigint`, integer string, or `DecimalLike` to a human string, then `formatNumber`. |
-| `abbreviateNumber(value, decimals = 2, preserveTrailingZeros = false)` | `K`/`M`/`B`/`T`/`P`/`E`. Negatives abbreviate. |
-| `formatLargeNumber(value)` | `abbreviateNumber(value, 2)`. |
-| `formatSwapAmount(value)` | Three significant digits after leading zeros. `0.000015045` becomes `0.0000150`. |
-| `expToString(value)` | Scientific notation to a plain decimal string. |
-| `computePercentile(sorted, percentile)` | Linear interpolation. Empty input returns `null`. |
+Use when the value is still in atomic units (`bigint`, integer string, or `DecimalLike`) and the result should look like `formatNumber`.
+
+`decimals` is the token scale. A `DecimalLike` is read with `toFixed(0)` and treated as the atomic integer.
 
 ```ts
+// equivalent to -> formatNumber(humanAmount)
+// Pass options to override. `humanAmount` is the atomic value divided by 10 ** decimals.
 NumberUtils.formatBigInt(1_500000n, 6) // "1.50"
+NumberUtils.formatBigInt('1500000', 6) // "1.50"
+```
+
+### `abbreviateNumber(value, decimals = 2, preserveTrailingZeros = false)`
+
+Use when you want `K` / `M` / `B` / `T` / `P` / `E` and you are choosing the fraction digits yourself. Abbreviation starts at 1,000. This does not add `$` or grouping commas.
+
+`preserveTrailingZeros` keeps `1.50K` instead of `1.5K`. An exact tier uses that suffix. A coefficient that rounds to `1,000` promotes to the next suffix. Negatives keep the minus.
+
+```ts
+NumberUtils.abbreviateNumber(1_000_000, 2) // "1M"
+NumberUtils.abbreviateNumber(999_500, 0) // "1M"
+NumberUtils.abbreviateNumber(1500, 2) // "1.5K"
+NumberUtils.abbreviateNumber(1500, 2, true) // "1.50K"
+```
+
+### `formatLargeNumber(value)`
+
+Use when a stat such as market cap, liquidity, or volume should abbreviate from one thousand, with two fraction digits and trailing zeros removed. A `DecimalLike` is read with `toNumber()`. This does not add `$`.
+
+`formatLargeNumber(1500)` is `1.5K`. `formatUsdCompact(1500)` is `$1.50K`.
+
+```ts
+NumberUtils.formatLargeNumber(1500) // "1.5K"
+NumberUtils.formatLargeNumber(1_000_000) // "1M"
+```
+
+### `formatSwapAmount(value)`
+
+Use when the value is a swap input or output and the UI needs the first three significant digits, including a small amount that must not become a subscript or a rounded balance.
+
+No commas, no `$`, no abbreviation, and no `formatNumber` rounding. A negative returns `<0`. `0` returns `0`. Scientific notation is expanded before the split, so `1.5e-7` stays a decimal.
+
+```ts
+NumberUtils.formatSwapAmount(0.15045814096) // "0.150"
 NumberUtils.formatSwapAmount(0.000015045814) // "0.0000150"
+NumberUtils.formatSwapAmount(1.5e-7) // "0.00000015"
+NumberUtils.formatSwapAmount(1234.5) // "1234.5"
+```
+
+`formatCryptoBalance(0.000015045814)` is `0.000015`. `formatSwapAmount` keeps the third significant digit: `0.0000150`.
+
+### `expToString(value)`
+
+Use when a number or numeric string is in scientific notation and a later step needs the full plain decimal, not a display string. The minus stays on the outside, so `-1e-7` is `-0.0000001`.
+
+```ts
 NumberUtils.expToString(1e23) // "100000000000000000000000"
+NumberUtils.expToString(-1e-7) // "-0.0000001"
 ```
 
-`formatBigInt` on a `DecimalLike` reads `toFixed(0)` and treats that as the atomic integer.
+### `computePercentile(sorted, percentile)`
+
+Use when you already have an ascending list of numbers and need a linearly interpolated percentile. Empty input returns `null`. `50` on five sorted values is the middle value.
+
+```ts
+NumberUtils.computePercentile([10, 20, 30, 40, 50], 50) // 30
+NumberUtils.computePercentile([10, 20, 30, 40, 50], 95) // 48
+NumberUtils.computePercentile([], 50) // null
+```
 
 ## BigIntUtils
 
@@ -222,7 +304,7 @@ Prisma's `Decimal` and decimal.js both satisfy `DecimalLike`. Detection is struc
 | --- | --- |
 | `formatNumber` | `formatNumber` |
 | `formatCurrencyAmount` | `formatUsdBalance` (adds `$`, sign in front) |
-| `formatUSD` | `formatUsd` |
+| `formatUSD` | `formatUsdCompact` |
 | token balance via `formatNumber` | `formatCryptoBalance` |
 | `formatPercentage` | `formatPercentage` |
 | `formatInteger` | `formatInteger` |

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { type BigIntInput, BigIntUtils } from './bigint-utils.js';
 export type { DecimalLike, NumberInput } from './decimal.js';
-export { type FormatNumberOptions, NumberUtils, type UsdInput, } from './number-utils.js';
+export { type FormatNumberOptions, type FormatUsdBalanceOptions, type FormatUsdOptions, NumberUtils, type SignFormatOptions, type UsdInput, } from './number-utils.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACjE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EACL,KAAK,mBAAmB,EACxB,WAAW,EACX,KAAK,QAAQ,GACd,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACjE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,WAAW,EACX,KAAK,iBAAiB,EACtB,KAAK,QAAQ,GACd,MAAM,mBAAmB,CAAA"}

package/dist/number-utils.d.ts

@@ -1,5 +1,9 @@
 import { type DecimalLike, type NumberInput } from './decimal.js';
-export type FormatNumberOptions = {
+export type SignFormatOptions = {
+    showNegativeSign?: boolean;
+    showPositiveSign?: boolean;
+};
+export type FormatNumberOptions = SignFormatOptions & {
     showExponents?: boolean;
     minSignificantDigits?: number;
     maxDecimals?: number;
@@ -9,21 +13,27 @@ export type FormatNumberOptions = {
     abbreviateLargeNumbers?: boolean;
     abbrMinSignificantDigits?: number;
 };
+export type FormatUsdOptions = SignFormatOptions & {
+    showCurrencySymbol?: boolean;
+};
+export type FormatUsdBalanceOptions = FormatNumberOptions & {
+    showCurrencySymbol?: boolean;
+};
 export type UsdInput = NumberInput | string;
 export declare const expToString: (value: string | number) => string;
 declare function computePercentile(sorted: number[], percentile: number): number | null;
 export declare const NumberUtils: {
-    formatNumber: (value: NumberInput, { showExponents, minSignificantDigits, maxDecimals: maxDecimalsParam, minDecimals: minDecimalsParam, abbrThreshold, abbreviateLargeNumbers, abbrMinSignificantDigits, prefix, }?: FormatNumberOptions) => string;
+    formatNumber: (value: NumberInput, options?: FormatNumberOptions) => string;
     formatCryptoBalance: (value: NumberInput, options?: FormatNumberOptions) => string;
-    formatUsdBalance: (value: UsdInput, options?: FormatNumberOptions) => string;
+    formatUsdBalance: (value: UsdInput, options?: FormatUsdBalanceOptions) => string;
     formatPercentage: (value: NumberInput, options?: FormatNumberOptions) => string;
-    formatUsd: (value: UsdInput) => string;
+    formatUsdCompact: (value: UsdInput, options?: FormatUsdOptions) => string;
     formatInteger: (value: NumberInput, options?: FormatNumberOptions) => string;
-    formatTokenPrice: (price: NumberInput) => string;
+    formatTokenPrice: (price: NumberInput, options?: FormatNumberOptions) => string;
     formatBigInt: (input: bigint | string | DecimalLike, decimals: number, formatOptions?: FormatNumberOptions) => string;
-    abbreviateNumber: (num: number, decimals?: number, preserveTrailingZeros?: boolean) => string;
-    formatLargeNumber: (value: number | DecimalLike) => string;
-    formatSwapAmount: (value: number | string) => string;
+    abbreviateNumber: (num: number, decimals?: number, preserveTrailingZeros?: boolean, options?: SignFormatOptions) => string;
+    formatLargeNumber: (value: number | DecimalLike, options?: SignFormatOptions) => string;
+    formatSwapAmount: (value: number | string, options?: SignFormatOptions) => string;
     expToString: (value: string | number) => string;
     computePercentile: typeof computePercentile;
 };

package/dist/number-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"number-utils.d.ts","sourceRoot":"","sources":["../src/number-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAG/E,MAAM,MAAM,mBAAmB,GAAG;IAChC,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,wBAAwB,CAAC,EAAE,MAAM,CAAA;CAClC,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,MAAM,CAAA;AAE3C,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,GAAG,MAAM,KAAG,MAMpD,CAAA;AAwVD,iBAAS,iBAAiB,CACxB,MAAM,EAAE,MAAM,EAAE,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAYf;AAED,eAAO,MAAM,WAAW;0BArPf,WAAW,oLAUf,mBAAmB;iCAuKf,WAAW,YACR,mBAAmB;8BAPE,QAAQ,YAAY,mBAAmB;8BAUvC,WAAW,YAAY,mBAAmB;uBAbjD,QAAQ;2BAgBJ,WAAW,YAAY,mBAAmB;8BAGvC,WAAW;0BAGnC,MAAM,GAAG,MAAM,GAAG,WAAW,YAC1B,MAAM,kBACA,mBAAmB;4BAjP9B,MAAM;+BA8PqB,MAAM,GAAG,WAAW;8BAKrB,MAAM,GAAG,MAAM,KAAG,MAAM;yBA5UtB,MAAM,GAAG,MAAM,KAAG,MAAM;;CA6X1D,CAAA"}
+{"version":3,"file":"number-utils.d.ts","sourceRoot":"","sources":["../src/number-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAG/E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,GAAG;IACpD,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,wBAAwB,CAAC,EAAE,MAAM,CAAA;CAClC,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG;IACjD,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG,mBAAmB,GAAG;IAC1D,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,MAAM,CAAA;AAE3C,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,GAAG,MAAM,KAAG,MAMpD,CAAA;AA4ZD,iBAAS,iBAAiB,CACxB,MAAM,EAAE,MAAM,EAAE,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAYf;AAED,eAAO,MAAM,WAAW;0BA/Kf,WAAW,YACT,mBAAmB;iCA+FrB,WAAW,YACR,mBAAmB;8BAftB,QAAQ,YACL,uBAAuB;8BAiBF,WAAW,YAAY,mBAAmB;8BA1B1C,QAAQ,YAAY,gBAAgB;2BA6BvC,WAAW,YAAY,mBAAmB;8BAGvC,WAAW,YAAY,mBAAmB;0BAIlE,MAAM,GAAG,MAAM,GAAG,WAAW,YAC1B,MAAM,kBACA,mBAAmB;4BA7R9B,MAAM,gEAGD,iBAAiB;+BAwSpB,MAAM,GAAG,WAAW,YACjB,iBAAiB;8BAOpB,MAAM,GAAG,MAAM,YACZ,iBAAiB,KAC1B,MAAM;yBA5Y0B,MAAM,GAAG,MAAM,KAAG,MAAM;;CAic1D,CAAA"}

package/dist/number-utils.js

@@ -56,7 +56,19 @@ function toSubscript(text) {
     }
     return result;
 }
-const abbreviateNumber = (num, decimals = 2, preserveTrailingZeros = false) => {
+function applyDisplaySign(formatted, signed, options) {
+    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, decimals = 2, preserveTrailingZeros = false, options) => {
     const lookup = [
         { value: 1, symbol: '' },
         { value: 1e3, symbol: 'K' },
@@ -68,8 +80,9 @@ const abbreviateNumber = (num, decimals = 2, preserveTrailingZeros = false) => {
     ];
     const rx = /\.0+$|(\.[0-9]*[1-9])0+$/;
     const formatFixed = (fixed) => preserveTrailingZeros ? fixed : fixed.replace(rx, '$1');
-    if (!Number.isFinite(num))
-        return formatFixed(num.toFixed(decimals));
+    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--) {
@@ -94,9 +107,9 @@ const abbreviateNumber = (num, decimals = 2, preserveTrailingZeros = false) => {
     if (Math.abs(rendered.rounded) >= 1000 && tier < lookup.length - 1) {
         rendered = renderTier(tier + 1);
     }
-    return rendered.text;
+    return applyDisplaySign(rendered.text, num, options);
 };
-const formatNumber = (value, { showExponents = true, minSignificantDigits = 4, maxDecimals: maxDecimalsParam, minDecimals: minDecimalsParam, abbrThreshold = 1e7, abbreviateLargeNumbers = true, abbrMinSignificantDigits = 3, prefix = '', } = {}) => {
+const renderFormatNumber = (value, { showExponents = true, minSignificantDigits = 4, maxDecimals: maxDecimalsParam, minDecimals: minDecimalsParam, abbrThreshold = 1e7, abbreviateLargeNumbers = true, abbrMinSignificantDigits = 3, prefix = '', } = {}) => {
     let minDecimals;
     let maxDecimals;
     if (maxDecimalsParam == null && minDecimalsParam != null) {
@@ -172,6 +185,13 @@ const formatNumber = (value, { showExponents = true, minSignificantDigits = 4, m
         maximumFractionDigits: clampedMaxDecimals,
     })}`;
 };
+const formatNumber = (value, options = {}) => {
+    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 = {
     minDecimals: 2,
     maxDecimals: 2,
@@ -202,19 +222,35 @@ function coerceUsd(value) {
     }
     return coerceNumber(value);
 }
-function formatSignedUsd(value, formatAbs) {
+function formatSignedUsd(value, formatAbs, options) {
+    const showCurrencySymbol = options?.showCurrencySymbol !== false;
+    const symbol = showCurrencySymbol ? '$' : '';
     const numeric = coerceUsd(value);
-    if (numeric == null || !Number.isFinite(numeric) || numeric === 0)
-        return '$0.00';
+    if (numeric == null || !Number.isFinite(numeric) || numeric === 0) {
+        return `${symbol}0.00`;
+    }
     const body = formatAbs(Math.abs(numeric));
-    return numeric < 0 ? `-$${body}` : `$${body}`;
+    if (numeric < 0 && options?.showNegativeSign !== false)
+        return `-${symbol}${body}`;
+    if (numeric > 0 && options?.showPositiveSign === true)
+        return `+${symbol}${body}`;
+    return `${symbol}${body}`;
 }
-const formatUsd = (value) => formatSignedUsd(value, (absolute) => abbreviateNumber(absolute, 2, true));
-const formatUsdBalance = (value, options) => formatSignedUsd(value, (absolute) => formatNumber(absolute, mergePreset(USD_BALANCE_PRESET, options)));
+function absoluteUsdFormatOptions(options) {
+    if (options === undefined)
+        return undefined;
+    return {
+        ...options,
+        showNegativeSign: true,
+        showPositiveSign: false,
+    };
+}
+const formatUsdCompact = (value, options) => formatSignedUsd(value, (absolute) => abbreviateNumber(absolute, 2, true), options);
+const formatUsdBalance = (value, options) => formatSignedUsd(value, (absolute) => formatNumber(absolute, mergePreset(USD_BALANCE_PRESET, absoluteUsdFormatOptions(options))), options);
 const formatCryptoBalance = (value, options) => formatNumber(value, options);
 const formatPercentage = (value, options) => formatNumber(value, mergePreset(PERCENTAGE_PRESET, options));
 const formatInteger = (value, options) => formatNumber(value, mergePreset(INTEGER_PRESET, options));
-const formatTokenPrice = (price) => formatNumber(price);
+const formatTokenPrice = (price, options) => formatNumber(price, options);
 const formatBigInt = (input, decimals, formatOptions) => {
     let atomic;
     if (typeof input === 'bigint') {
@@ -228,24 +264,29 @@ const formatBigInt = (input, decimals, formatOptions) => {
     }
     return formatNumber(Number(formatUnits(atomic, decimals)), formatOptions);
 };
-const formatLargeNumber = (value) => {
+const formatLargeNumber = (value, options) => {
     const numeric = typeof value === 'number' ? value : value.toNumber();
-    return abbreviateNumber(numeric, 2);
+    return abbreviateNumber(numeric, 2, false, options);
 };
-const formatSwapAmount = (value) => {
+const formatSwapAmount = (value, options) => {
     const number = typeof value === 'string' ? Number.parseFloat(value) : value;
     if (!number || number === 0)
         return '0';
     if (number < 0)
-        return '<0';
+        return options?.showNegativeSign === false ? '0' : '<0';
     const [integerPart, decimalPart = ''] = expToString(number).split('.');
-    if (!decimalPart)
-        return integerPart ?? '0';
-    const leadingZeroLength = (decimalPart.match(/^0+/) || [''])[0].length;
-    const significantDigits = decimalPart.replace(/^0+/, '').substring(0, 3);
-    if (!significantDigits)
-        return '0';
-    return `${integerPart}.${'0'.repeat(leadingZeroLength)}${significantDigits}`;
+    let formatted;
+    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, percentile) {
     if (sorted.length === 0)
@@ -264,7 +305,7 @@ export const NumberUtils = {
     formatCryptoBalance,
     formatUsdBalance,
     formatPercentage,
-    formatUsd,
+    formatUsdCompact,
     formatInteger,
     formatTokenPrice,
     formatBigInt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rallycash/numbers",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Number formatting and fixed-point bigint conversion",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -2,6 +2,9 @@ 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

@@ -47,6 +47,17 @@ describe('NumberUtils.formatNumber', () => {
       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', () => {
@@ -70,10 +81,34 @@ describe('NumberUtils presets', () => {
   })
 
   it('formats abbreviated USD', () => {
-    expect(NumberUtils.formatUsd(1.5)).toBe('$1.50')
-    expect(NumberUtils.formatUsd(1234.5)).toBe('$1.23K')
-    expect(NumberUtils.formatUsd(-12_345_678)).toBe('-$12.35M')
-    expect(NumberUtils.formatUsd(null)).toBe('$0.00')
+    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', () => {
@@ -84,6 +119,9 @@ describe('NumberUtils presets', () => {
 
   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')
   })
 })
 
@@ -122,4 +160,26 @@ describe('NumberUtils.formatSwapAmount', () => {
     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',
+    )
+  })
 })

package/src/number-utils.ts

@@ -1,7 +1,12 @@
 import { coerceNumber, type DecimalLike, type NumberInput } from './decimal.js'
 import { formatUnits, parseUnits } from './units.js'
 
-export type FormatNumberOptions = {
+export type SignFormatOptions = {
+  showNegativeSign?: boolean
+  showPositiveSign?: boolean
+}
+
+export type FormatNumberOptions = SignFormatOptions & {
   showExponents?: boolean
   minSignificantDigits?: number
   maxDecimals?: number
@@ -12,6 +17,14 @@ export type FormatNumberOptions = {
   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 => {
@@ -86,10 +99,25 @@ function toSubscript(text: string | number) {
   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: '' },
@@ -105,7 +133,9 @@ const abbreviateNumber = (
   const formatFixed = (fixed: string) =>
     preserveTrailingZeros ? fixed : fixed.replace(rx, '$1')
 
-  if (!Number.isFinite(num)) return formatFixed(num.toFixed(decimals))
+  if (!Number.isFinite(num)) {
+    return applyDisplaySign(formatFixed(num.toFixed(decimals)), num, options)
+  }
 
   const absNum = Math.abs(num)
   let tier = 0
@@ -132,10 +162,10 @@ const abbreviateNumber = (
   if (Math.abs(rendered.rounded) >= 1000 && tier < lookup.length - 1) {
     rendered = renderTier(tier + 1)
   }
-  return rendered.text
+  return applyDisplaySign(rendered.text, num, options)
 }
 
-const formatNumber = (
+const renderFormatNumber = (
   value: NumberInput,
   {
     showExponents = true,
@@ -256,6 +286,16 @@ const formatNumber = (
   )}`
 }
 
+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,
@@ -296,20 +336,50 @@ function coerceUsd(value: UsdInput): number | null | undefined {
 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 '$0.00'
+  if (numeric == null || !Number.isFinite(numeric) || numeric === 0) {
+    return `${symbol}0.00`
+  }
   const body = formatAbs(Math.abs(numeric))
-  return numeric < 0 ? `-$${body}` : `$${body}`
+  if (numeric < 0 && options?.showNegativeSign !== false) return `-${symbol}${body}`
+  if (numeric > 0 && options?.showPositiveSign === true) return `+${symbol}${body}`
+  return `${symbol}${body}`
 }
 
-const formatUsd = (value: UsdInput) =>
-  formatSignedUsd(value, (absolute) => abbreviateNumber(absolute, 2, true))
+function absoluteUsdFormatOptions(
+  options: FormatUsdBalanceOptions | undefined,
+): FormatNumberOptions | undefined {
+  if (options === undefined) return undefined
+  return {
+    ...options,
+    showNegativeSign: true,
+    showPositiveSign: false,
+  }
+}
 
-const formatUsdBalance = (value: UsdInput, options?: FormatNumberOptions) =>
-  formatSignedUsd(value, (absolute) =>
-    formatNumber(absolute, mergePreset(USD_BALANCE_PRESET, options)),
+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 = (
@@ -323,7 +393,8 @@ const formatPercentage = (value: NumberInput, options?: FormatNumberOptions) =>
 const formatInteger = (value: NumberInput, options?: FormatNumberOptions) =>
   formatNumber(value, mergePreset(INTEGER_PRESET, options))
 
-const formatTokenPrice = (price: NumberInput) => formatNumber(price)
+const formatTokenPrice = (price: NumberInput, options?: FormatNumberOptions) =>
+  formatNumber(price, options)
 
 const formatBigInt = (
   input: bigint | string | DecimalLike,
@@ -341,27 +412,37 @@ const formatBigInt = (
   return formatNumber(Number(formatUnits(atomic, decimals)), formatOptions)
 }
 
-const formatLargeNumber = (value: number | DecimalLike) => {
+const formatLargeNumber = (
+  value: number | DecimalLike,
+  options?: SignFormatOptions,
+) => {
   const numeric = typeof value === 'number' ? value : value.toNumber()
-  return abbreviateNumber(numeric, 2)
+  return abbreviateNumber(numeric, 2, false, options)
 }
 
-const formatSwapAmount = (value: number | string): string => {
+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 '<0'
+  if (number < 0) return options?.showNegativeSign === false ? '0' : '<0'
 
   const [integerPart, decimalPart = ''] = expToString(number).split('.')
 
-  if (!decimalPart) return integerPart ?? '0'
-
-  const leadingZeroLength = (decimalPart.match(/^0+/) || [''])[0].length
-  const significantDigits = decimalPart.replace(/^0+/, '').substring(0, 3)
-
-  if (!significantDigits) return '0'
+  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 `${integerPart}.${'0'.repeat(leadingZeroLength)}${significantDigits}`
+  return applyDisplaySign(formatted, number, options)
 }
 
 function computePercentile(
@@ -386,7 +467,7 @@ export const NumberUtils = {
   formatCryptoBalance,
   formatUsdBalance,
   formatPercentage,
-  formatUsd,
+  formatUsdCompact,
   formatInteger,
   formatTokenPrice,
   formatBigInt,