exchange-rounding
Version:
Exchange Number Formatting
161 lines (115 loc) • 6.29 kB
Markdown
# Exchange Number Formatting (`ExchNumberFormat`)
[](https://www.npmjs.com/package/exchange-rounding)
[](LICENSE)
[](https://bundlephobia.com/package/exchange-rounding@latest)
[](https://www.typescriptlang.org/)
[](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: [](https://github.com/sponsors/bchainhub)