toman-format

Zero-dependency Persian-digit currency formatting for Farsi-market apps — convert a number to Persian digits, format Toman amounts, and (optionally) convert from another currency with a configurable rate and margin.

Built and battle-tested serving live bilingual pricing pages at orbitalwebstudio.com before being extracted into its own package.

Why

Formatting prices for an Iranian audience means more than a currency symbol swap: Persian digits (۰-۹), Toman (not bare Rial), and sensible rounding so a converted price reads like a normal quoted number instead of a raw FX calculation. Surprisingly little polished, dependency-free tooling exists for this — most examples are Arabic-locale RTL demos, not Farsi-specific currency formatting.

Install

npm install toman-format

Usage

import { toPersianDigits, formatToman, convertToToman } from 'toman-format'

toPersianDigits('1250000')
// '۱۲۵۰۰۰۰'

formatToman(4_900_000)
// '۴,۹۰۰,۰۰۰ تومان'

convertToToman({
  amount: 490,
  fromCurrency: 'USD',
  rate: 174_900,       // Toman per 1 USD — you supply the current rate
  marginPercent: 0,    // optional adjustment, e.g. a market-specific discount
  roundTo: 100_000,    // round the result up to the nearest 100,000 Toman
})
// 85_701_000 -> rounded per roundTo

No bundled/hardcoded exchange rate — currency rates drift and this package doesn't try to be a live-rate service. Pass the rate you're already tracking.

API

• toPersianDigits(value: string | number): string
• formatToman(amount: number): string
• convertToToman(opts: { amount: number; fromCurrency: string; rate: number; marginPercent?: number; roundTo?: number }): number
• toLocaleNumber(locale: 'en' | 'fa', n: number): string

License

MIT — use it in anything, commercial or not.

Built by

Orbital — self-operating web platforms for e-commerce, B2B, and local-business industries, EN and FA markets.