https://github.com/shahradelahi/compact-number
π’ A tiny and fast library for compact number formatting and parsing.
https://github.com/shahradelahi/compact-number
abbreviate compact format i18n intl locale number
Last synced: 9 months ago
JSON representation
π’ A tiny and fast library for compact number formatting and parsing.
- Host: GitHub
- URL: https://github.com/shahradelahi/compact-number
- Owner: shahradelahi
- License: mit
- Created: 2025-10-05T09:39:11.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-10-06T15:05:09.000Z (9 months ago)
- Last Synced: 2025-10-06T15:32:40.911Z (9 months ago)
- Topics: abbreviate, compact, format, i18n, intl, locale, number
- Language: TypeScript
- Homepage: https://npmjs.com/@se-oss/compact-number
- Size: 59.6 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @se-oss/compact-number
[](https://github.com/shahradelahi/compact-number/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@se-oss/compact-number)
[](/LICENSE)
[](https://packagephobia.com/result?p=@se-oss/compact-number)
_@se-oss/compact-number_ is a lightweight, fast, and highly customizable library for compact number formatting and parsing, offering robust internationalization support.
---
- [Installation](#-installation)
- [Usage](#-usage)
- [Advanced Usage](#-advanced-usage)
- [Documentation](#-documentation)
- [Using Locales](#-using-locales)
- [Performance](#-performance)
- [Contributing](#-contributing)
- [License](#license)
## π¦ Installation
```bash
npm install @se-oss/compact-number
```
Install using your favorite package manager
**pnpm**
```bash
pnpm install @se-oss/compact-number
```
**yarn**
```bash
yarn add @se-oss/compact-number
```
## π Usage
### `compactNumber`
Format a number into a compact, human-readable string.
```typescript
import { compactNumber } from '@se-oss/compact-number';
console.log('Formatting 1234:', compactNumber(1234));
// => 1.2K
console.log('Formatting 1500000:', compactNumber(1500000));
// => 1.5M
console.log(
'Formatting -1234 with precision 2:',
compactNumber(-1234, { maximumFractionDigits: 2 })
);
// => -1.23K
```
### `uncompactNumber`
Parse a compacted string back into a number.
```typescript
import { uncompactNumber } from '@se-oss/compact-number';
console.log(uncompactNumber('1.2K'));
// => 1200
console.log(uncompactNumber('1.5M'));
// => 1500000
console.log(uncompactNumber('-1.23K'));
// => -1230
```
## π‘ Advanced Usage
You can dynamically load locales from the `cldr-numbers-full` package instead of bundling them. This is useful for applications that support many languages.
First, install the CLDR data package:
```bash
pnpm add cldr-numbers-full
```
### Loading a Single Locale
To keep your bundle size small, you can import and register individual locales as needed. This works in any environment.
```typescript
import { compactNumber, store } from '@se-oss/compact-number';
// Import any CLDR locale data directly
import ca from 'cldr-numbers-full/main/ca/numbers.json';
// Register the Catalan locale from the raw CLDR data
store.registerFromCLDR(ca);
// You can now format numbers using the 'ca' locale
console.log(compactNumber(12345, { locale: 'ca' }));
// => 12,3 mil
```
### Loading All Locales (Node.js)
In Node.js environments, you can register all available CLDR locales at once using `registerFullCLDR`. This is useful for servers that need to handle many different locales.
```typescript
import { compactNumber, store } from '@se-oss/compact-number';
// Register all CLDR locales
await store.registerFullCLDR();
// Now you can format numbers in any of the registered locales
console.log(compactNumber(12345, { locale: 'ja' })); // Japanese
// => 1.2δΈ
console.log(compactNumber(54321, { locale: 'fr' })); // French
// => 54,3 k
```
**Note:** This function only works in Node.js. It will throw an error in the browser to prevent bundling the entire `cldr-numbers-full` package.
## π Using Locales
By default, only the `en` locale is registered. To use other locales, you must import and register them. This ensures that unused locales are not included in your final bundle.
```typescript
import { compactNumber, es, store } from '@se-oss/compact-number';
// Register the Spanish (es) locale
store.register(es);
console.log(compactNumber(1234, { locale: 'es' }));
// => 1.2 mil
```
## π Documentation
For all configuration options, please see [the API docs](https://www.jsdocs.io/package/@se-oss/compact-number).
## π Performance
_@se-oss/compact-number_ is designed for speed. Our benchmarks show it's significantly faster than `Intl.NumberFormat` for compact number formatting.
| Library | Operations/second (hz) |
| :------------------------- | :--------------------- |
| `@se-oss/compact-number` | 274,863.69 |
| `Intl.NumberFormat` | 22,298.90 |
| **Performance Difference** | **~12.33x faster** |
_Benchmark script: [`src/index.bench.ts`](src/index.bench.ts)_
## π€ Contributing
Want to contribute? Awesome! To show your support is to star the project, or to raise issues on [GitHub](https://github.com/shahradelahi/compact-number)
Thanks again for your support, it is much appreciated! π
## License
[MIT](/LICENSE) Β© [Shahrad Elahi](https://github.com/shahradelahi) and [contributors](https://github.com/shahradelahi/compact-number/graphs/contributors).