# exchange-rounding

> Exchange Number Formatting

Latest version **1.1.8** (published 2025-10-10) · CORE license · 0 weekly downloads

## Install

```sh
npm install exchange-rounding
pnpm add exchange-rounding
yarn add exchange-rounding
bun add exchange-rounding
```

## Health

**Score 65/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.1.8 |
| Published | 2025-10-10 |
| First published | 2023-11-23 |
| Weekly downloads | 0 |
| License | CORE |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=13.2.0 |
| Dependencies | 0 |
| Unpacked size | 23.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 0 |
| Author | Blockchain Hub |
| Maintainers | coreorg |
| Keywords | rounding, plugin, exchange, decimals, transform, floor, round, ceil, Intl.NumberFormat, NumberFormat, Intl |

## Links

- npm: https://www.npmjs.com/package/exchange-rounding
- Repository: https://github.com/bchainhub/exchange-rounding
- Homepage: https://github.com/bchainhub/exchange-rounding#readme
- Issues: https://github.com/bchainhub/exchange-rounding/issues
- npm.io page: https://npm.io/package/exchange-rounding

## Alternatives

- [random-seedable](https://npm.io/package/random-seedable.md) — 27.9K weekly downloads
- [n2words](https://npm.io/package/n2words.md) — 22.2K weekly downloads
- [@stdlib/math-base-special-factorialln](https://npm.io/package/@stdlib/math-base-special-factorialln.md) — 5.7K weekly downloads
- [@stdlib/math-base-special-abs2](https://npm.io/package/@stdlib/math-base-special-abs2.md) — 1.7K weekly downloads
- [commons-math-interpolation](https://npm.io/package/commons-math-interpolation.md) — 1.4K weekly downloads

## Recent versions

- 1.1.8 (latest) — 2025-10-10
- 1.1.7 — 2025-10-10
- 1.1.6 — 2025-03-14
- 1.1.5 — 2025-03-14
- 1.1.4 — 2025-02-15
- 1.1.3 — 2024-04-24
- 1.1.2 — 2024-04-12
- 1.1.1 — 2024-04-12
- 1.1.0 — 2024-04-11
- 1.0.8 — 2024-03-20
- 1.0.7 — 2024-03-18
- 1.0.6 — 2024-03-12
- 1.0.5 — 2024-03-12
- 1.0.4 — 2024-03-12
- 1.0.3 — 2024-03-12
- … 5 more at https://npm.io/package/exchange-rounding/versions

## README

# Exchange Number Formatting (`ExchNumberFormat`)

[![npm](https://img.shields.io/npm/v/exchange-rounding?label=npm&color=cb3837&logo=npm)](https://www.npmjs.com/package/exchange-rounding)
[![License: CORE](https://img.shields.io/badge/License-CORE-yellow?logo=googledocs)](LICENSE)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/exchange-rounding?label=Size&logo=tsnode)](https://bundlephobia.com/package/exchange-rounding@latest)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?logo=typescript)](https://www.typescriptlang.org/)
[![GitHub Sponsors](https://img.shields.io/github/sponsors/bchainhub?label=Sponsors&logo=githubsponsors&color=EA4AAA)](https://github.com/sponsors/bchainhub)

`ExchNumberFormat` is a comprehensive and customizable number formatting utility, designed specifically for financial and cryptocurrency applications. It extends the standard `Intl.NumberFormat` functionality with support for custom currencies, including cryptocurrencies, and provides additional formatting options.

## Features

- **Standard and Custom Currencies**: Extensive support for both standard ISO currencies and custom-defined currencies, including cryptocurrencies.
- **Rounding Modes**: Supports various rounding modes to meet different financial calculation requirements.
- **Locale-Aware Formatting**: Offers locale-aware formatting, supporting different number styles and notations.
- **Custom Currency Attributes**: Manages custom attributes for each currency, such as symbols, codes, and decimal places.
- **Dynamic Currency Support**: Dynamically adds or modifies currency definitions at runtime using the `useCustomCurrency` and `customCurrency` options.
- **Tested**: Robust test coverage.
- **Tree Shaking**: Zero dependencies, no side effects.

## Installation

Install the package using npm:

```bash
npm i exchange-rounding
```

Or using yarn:

```bash
yarn add exchange-rounding
```

## Usage

### Basic Usage

```typescript
import ExchNumberFormat from 'exchange-rounding';

// Example: Formatting a number with Bitcoin currency
const bitcoinFormatter = new ExchNumberFormat('en-US', {
    style: 'currency',
    currency: 'BTC',
    roundingMode: 'halfFloor',
    currencyDisplay: 'symbol'
});

const formattedBTC = bitcoinFormatter.format(1234.567);
console.log(formattedBTC); // Output: '₿1,234.567'

// Example: Formatting with custom options
const customFormatter = new ExchNumberFormat('en-US', {
    style: 'decimal',
    minimumFractionDigits: 2,
    maximumFractionDigits: 5
});

const formattedNumber = customFormatter.format(1234.56789);
console.log(formattedNumber); // Output: '1,234.56789'
```

### Advanced Usage with Custom Currencies

```typescript
const customCurrencyData = {
    'XCB': {
        symbol: '₡',
        narrowSymbol: '₡',
        code: 'XCB',
        name: 'Core',
        defaultDecimals: 2
    }
};

const formatter = new ExchNumberFormat('en-US', {
    useCustomCurrency: true,
    customCurrency: customCurrencyData,
    currency: 'XCB'
});

console.log(formatter.format(1234.567)); // Output: '₡1,234.57'
```

## API Reference

### new ExchNumberFormat(locales, options)

Creates a new formatter instance configured with the specified locales and options.

#### Parameters

- `locales`: A string with a BCP 47 language tag or an array of such strings.
- `options`: Configuration options for the formatter.

#### Options

- Inherits all options from `Intl.NumberFormatOptions`.
- `useAliases`: Enables the use of currency aliases.
- `aliases`: Defines mappings from alias strings to standard currency codes.
- `useCustomCurrency`: Enables the use of a custom currency dictionary.
- `customCurrency`: Specifies custom currency settings.
- `wrapped`: Indicates if the currency symbol should be wrapped with custom characters.
- `wrappedSymbol`: The symbol used to wrap the currency symbol.
- `digitized`: Indicates if the numeric values should be displayed with digital symbols.
- `digitizedSymbol`: The symbol used to represent digitized values.
- `roundingMode`: The rounding mode to use when formatting numbers.
- `cropZeros`: Controls the handling of trailing zeros in the decimal part:
  - `true`: Removes all trailing zeros
  - `false` (default): Keeps all trailing zeros according to `maximumFractionDigits`
  - `number`: Keeps at least this many trailing zeros (e.g., `2` would ensure at least two decimal places)
  - Note: Make sure to use `maximumFractionDigits` when using `cropZeros` to avoid unexpected results.

### Rounding Modes

- `ceil`: Rounds numbers up.
- `floor`: Rounds numbers down.
- `expand`: Similar to ceil but expands beyond the typical rounding limits.
- `trunc`: Truncates the number without rounding.
- `halfCeil`: Rounds half values up.
- `halfFloor`: Rounds half values down.
- `halfExpand`: Expands half values during rounding.
- `halfTrunc`: Truncates half values.
- `halfEven`: Rounds half values to the nearest even number.

### format(number)

Formats a number according to the instance's locale and formatting options.

### formatToParts(number)

Returns an array of objects representing the number string in parts that can be used for custom formatting.

### isCurrencySupported(currency)

Checks if the specified currency is supported by the formatter. Returns `true` if the currency is supported and `false` otherwise. If the formatter fails, an error is thrown.

### version

Prints the version of the `exchange-rounding` package.

## Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request on our GitHub repository.

## License

This project is licensed under the [CORE License](LICENSE).

## Funding

If you find this project useful, please consider supporting it:

- [GitHub Sponsors](https://github.com/sponsors/bchainhub)
- [Core](https://blockindex.net/address/cb7147879011ea207df5b35a24ca6f0859dcfb145999)
- [Bitcoin](https://www.blockchain.com/explorer/addresses/btc/bc1pd8guxjkr2p6n2kl388fdj2trete9w2fr89xlktdezmcctxvtzm8qsymg0d)
- [Litecoin](https://www.blockchain.com/explorer/addresses/ltc/ltc1ql8dvx0wv0nh2vncpt9j3zqefaehsd25cwp7pfx)

List of sponsors: [![GitHub Sponsors](https://img.shields.io/github/sponsors/bchainhub?label=Sponsors&logo=githubsponsors&color=EA4AAA)](https://github.com/sponsors/bchainhub)

---
_Source: https://npm.io/package/exchange-rounding · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._