reduce-precision is a versatile package for formatting and reducing the precision of numbers, currencies, and percentages. It supports various templates, precision levels, languages, and output formats, making it easy to generate formatted strings for different use cases.
- Format numbers with customizable precision levels: high, medium, low, or auto
- Support for multiple templates: number, USD, IRT (Iranian Toman), IRR (Iranian Rial), and percent
- Multilingual support: English and Persian (Farsi)
- Output formats: plain text, HTML, and Markdown
- Customizable prefix and postfix markers for HTML and Markdown output
- Intelligent handling of very small and very large numbers
- Automatic thousand separators and decimal points based on the selected language
- TypeScript type definitions included
- Optional inline Toman SVG and structured parts for custom UI rendering (JavaScript/TypeScript)
You can install reduce-precision using npm:
npm install reduce-precision
You can install the PHP version of reduce-precision via Composer:
composer require arzdigitallabs/reduce-precisionimport { NumberFormatter } from 'reduce-precision';
const formatter = new NumberFormatter();
formatter.setLanguage('en', { prefixMarker: 'strong', prefix: 'USD ' });
console.log(formatter.toHtmlString(123456789));
console.log(formatter.toJson(123456789));
console.log(formatter.toString(123456789));require 'vendor/autoload.php';
use NumberFormatter\NumberFormatter;
$formatter = new NumberFormatter();
echo $formatter->toString(12345.678); // Default formatThe JavaScript/TypeScript NumberFormatter constructor accepts an optional options object with the following properties:
| Option | Type | Default | Description |
|---|---|---|---|
precision |
'auto' | 'high' | 'medium' | 'low' |
'high' |
Precision level for formatting |
template |
'number' | 'usd' | 'irt' | 'irr' | 'percent' |
'number' |
Template for formatting |
language |
'en' | 'fa' |
'en' |
Language for formatting (English or Persian) |
outputFormat |
'plain' | 'html' | 'markdown' |
'plain' |
Output format |
prefixMarker |
string |
'i' |
Prefix marker for HTML and Markdown output |
postfixMarker |
string |
'i' |
Postfix marker for HTML and Markdown output |
prefix |
string |
'' |
Prefix string to be added before the formatted number |
postfix |
string |
'' |
Postfix string to be added after the formatted number |
currencySymbol |
'text' | 'svg' |
'text' |
Toman symbol style for HTML output (JavaScript/TypeScript) |
import { NumberFormatter } from 'reduce-precision';
// Create a formatter instance with default options
const formatter = new NumberFormatter();
// Basic usage
formatter.setLanguage('en');
// Basic number formatting
formatter.toJson(1234.5678); // Output: { value: '1,234.6', ... }
// Formatting with medium precision
formatter.setTemplate('number', 'medium').toJson(1234.5678); // Output: { value: '1.23K', ... }
// Formatting as USD
formatter.setTemplate('usd', 'high').toJson(1234.5678); // Output: { value: '$1,234.6', ... }
// Formatting as Iranian Rial with Persian numerals
formatter.setLanguage('fa');
formatter.setTemplate('irr', 'medium').toJson(1234.5678); // Output: { value: '۱٫۲۳ هزار ریال', ... }
// Formatting as a percentage with low precision
formatter.setTemplate('percent', 'low').toJson(0.1234); // Output: { value: '0.12%', ... }
// Formatting with HTML output and custom markers
formatter
.setLanguage('en', { prefixMarker: 'strong', prefix: 'USD ' })
.toHtmlString(1234.5678);
// Output: <strong>USD </strong>1,234.6
// Formatting with string input for small or big numbers
formatter.setTemplate('usd', 'medium').toJson('0.00000000000000000000005678521');
// Output: { value: '$0.0₂₂5678', ... }require 'vendor/autoload.php';
use NumberFormatter\NumberFormatter;
$formatter = new NumberFormatter();
echo $formatter->toString(12345.678); // Default format
$formatter->setLanguage('fa');
echo $formatter->toString(12345.678); // Output in Persian
$formatter->setTemplate('usd', 'high');
echo $formatter->toString(12345.678); // Output in USD format with high precision
echo $formatter->toHtmlString(12345.678); // HTML formatted output
echo $formatter->toMdString(12345.678); // Markdown formatted outputThe FormattedObject interface represents the structure of the formatted number object returned by the format method.
interface FormattedObject {
value: string; // The formatted value as a string
prefix: string; // The prefix string
postfix: string; // The postfix string
sign: string; // The sign of the number (either an empty string or '-')
wholeNumber: string; // The whole number part of the value
}Creates a new instance of the NumberFormatter class with optional configuration options.
Sets the language and optional language configuration for the formatter.
Sets the template and precision for the formatter.
Formats the input number as a string.
Formats the input number as a plain text string.
Formats the input number as an HTML string.
Formats the input number as a Markdown string.
Opt in to the bundled icon for HTML output:
import { NumberFormatter, tomanSymbolSvg } from 'reduce-precision';
const formatter = new NumberFormatter({
template: 'irt',
currencySymbol: 'svg', // default: 'text'
}).setLanguage('fa');
formatter.toHtmlString(12500); // localized amount with inline Toman SVG
formatter.toPlainString(12500); // existing text representation
const parts = formatter.formatToParts(12500);Plain text, Markdown, other templates, and the existing JSON contract retain their
behavior. toString() follows the selected output format, as before. The icon uses
currentColor, a 1em size, an accessible Toman label, and .rp-currency-symbol for styling.
SVG output escapes custom affix text. HTML markers support i, b, em,
strong, span, small, sup, and sub; other markers fall back to span
when SVG output is enabled.
formatToParts() returns { type, value } objects. IRT parts separate sign,
prefix, number, compact, currency, postfix, and spacing (literal).
Render text parts as text nodes and replace the currency part with the exported
tomanSymbolSvg or your framework component. Compact parts explicitly separate
scale and currency (for example, هزار میلیارد and ت instead of همت), so joining
parts may differ from legacy plain output. Other templates currently return a
single literal part. Invalid/empty input returns an empty array.
This feature is currently available in the JavaScript/TypeScript implementation; the PHP implementation is unchanged.
const output = document.querySelector('#price')!;
output.replaceChildren();
for (const part of formatter.formatToParts(12500)) {
if (part.type === 'currency') {
// Parse only the bundled SVG, never user-provided text.
const icon = new DOMParser()
.parseFromString(tomanSymbolSvg, 'image/svg+xml').documentElement;
output.appendChild(document.importNode(icon, true));
} else {
output.appendChild(document.createTextNode(part.value));
}
}The exported FormatPart TypeScript type describes each part. Calling
formatToParts() does not change the formatter's selected output mode.
From a checkout of this repository:
npm ci
npm run devOpen the local URL printed by Vite. Select Toman, choose Text or SVG icon, and switch between HTML, Plain, Markdown, and Parts preview. The demo displays the rendered result, raw output, and formatted object or parts. Plain and Markdown remain textual even when SVG is selected.
Build the package and demo:
npm run typecheck
npm test -- --runInBand
npm run build
npm run demo:build
npm run demo:previewThe demo build is written to demo-dist/ and is excluded from Git.
You can run tests using Jest or any other preferred testing framework for TypeScript.
You can run tests using PHPUnit:
./vendor/bin/phpunit php/tests/NumberFormatterTest.phpContributions are welcome! If you find a bug or have a feature request, please open an issue on the GitHub repository. If you'd like to contribute code, please fork the repository and submit a pull request.
This project is licensed under the MIT License.