Releases: mastermunj/to-words
Releases · mastermunj/to-words
v5.5.0
v5.4.0
v5.3.0
v5.2.1
v5.0.0 - BigInt, Tree-Shaking & 94 Locales
82ab419
This commit was signed with the committer’s verified signature.
mastermunj
Munjal Dhamecha
to-words v5.0.0 Release Notes
🎉 The biggest release yet!
v5 brings extended number support, tree-shakeable imports, UMD browser bundles, and comprehensive documentation improvements.
⚠️ Breaking Changes
Node.js Version Requirement
- Minimum Node.js version is now 20.0.0
- This enables native BigInt support and modern ES features
Module System Changes
- Package is now ESM-first with
"type": "module"in package.json - CommonJS builds are still available at
dist/cjs/ - Import paths have changed for tree-shaking (see Migration Guide below)
API Changes
- Locale classes are no longer directly exported from the main entry point
- Use subpath imports for individual locales:
import { ToWords } from 'to-words/en-US'
✨ New Features
Extended Number Scale Support
Handle numbers far beyond JavaScript's limits with BigInt support:
| Scale System | Maximum | Example |
|---|---|---|
| Short Scale (Western) | 10^63 (Vigintillion) | 1000000000000000000000000000000000000000000000000000000000000000n |
| Long Scale (European) | 10^63+ | French, German, Norwegian, Danish |
| Indian System | 10^17 (Shankh) | 100000000000000000n → "One Shankh" |
| East Asian | 10^52 (恒河沙) | Japanese, Chinese |
const toWords = new ToWords({ localeCode: 'en-US' });
toWords.convert(1000000000000000000000000000000000000000000000000000000000000000n);
// "One Vigintillion"
const toWordsIN = new ToWords({ localeCode: 'en-IN' });
toWordsIN.convert(100000000000000000n);
// "One Shankh"Tree-Shakeable Subpath Exports
Import only the locales you need for smaller bundles:
// Full bundle (~538 KB raw, ~54 KB gzip)
import { ToWords } from 'to-words';
// Single locale (~11 KB raw, ~3 KB gzip)
import { ToWords } from 'to-words/en-US';Bundle size reduction: 98% smaller when using a single locale!
UMD Browser Bundles
Use to-words directly in browsers without a build step:
<!-- Single locale (recommended, ~3 KB gzip) -->
<script src="https://cdn.jsdelivr.net/npm/to-words@5.0.0/dist/umd/en-US.min.js"></script>
<script>
const toWords = new ToWords();
console.log(toWords.convert(12345));
</script>
<!-- Full bundle with all 94 locales -->
<script src="https://cdn.jsdelivr.net/npm/to-words@5.0.0/dist/umd/to-words.min.js"></script>
<script>
const toWords = new ToWords({ localeCode: 'fr-FR' });
console.log(toWords.convert(12345));
</script>94 Locales
The most comprehensive locale coverage available:
- 21 English variants (US, UK, IN, AU, CA, and more)
- 5 Spanish variants (ES, MX, AR, VE, US)
- 4 French variants (FR, BE, MA, SA)
- 10 Indian language locales (Hindi, Bengali, Tamil, Telugu, etc.)
- 4 Numbering systems: Short scale, Long scale, Indian, East Asian
- Full currency and ordinal support for all locales
Performance
Benchmarked at 1M+ operations per second for typical conversions:
| Operation | Throughput |
|---|---|
| Small integers | ~1.4M ops/sec |
| Medium integers | ~800K ops/sec |
| Large integers | ~300K ops/sec |
| Currency conversion | ~500K ops/sec |
| BigInt (30+ digits) | ~130K ops/sec |
📦 New Export Structure
to-words/
├── (main) → Full ToWords with all 94 locales
├── /en-US → Pre-configured for en-US only
├── /en-IN → Pre-configured for en-IN only
├── /fr-FR → Pre-configured for fr-FR only
├── ... (94 locales)
├── /core → ToWordsCore (base class, no locales)
└── /types → TypeScript type definitions
🔄 Migration Guide
From v4.x to v5.0.0
1. Update Node.js
Ensure you're running Node.js 20.0.0 or later.
2. Update Imports (if using tree-shaking)
// v4.x - Not tree-shakeable
import { ToWords } from 'to-words';
// v5.0.0 - Tree-shakeable single locale
import { ToWords } from 'to-words/en-US';3. Browser Usage
<!-- v5.0.0 -->
<script src="https://cdn.jsdelivr.net/npm/to-words@5.0.0/dist/umd/en-US.min.js"></script>
<script>
const toWords = new ToWords(); // ✅ Direct instantiation
</script>4. BigInt for Large Numbers
For numbers beyond Number.MAX_SAFE_INTEGER, use BigInt or string:
// v4.x - May lose precision
toWords.convert(9007199254740993); // ⚠️ Precision loss
// v5.0.0 - Use BigInt or string
toWords.convert(9007199254740993n); // ✅ Exact
toWords.convert('9007199254740993'); // ✅ Exact🌐 Browser Compatibility
| Browser | Version |
|---|---|
| Chrome | 49+ |
| Firefox | 52+ |
| Safari | 10+ |
| Edge | 14+ |
| Opera | 36+ |
| IE | 11 (with polyfills) |
BigInt Support: Chrome 67+, Firefox 68+, Safari 14+, Edge 79+
📊 Bundle Size Comparison
| Version | Full Bundle | Single Locale |
|---|---|---|
| v4.x | ~450 KB | N/A |
| v5.0.0 | 564 KB | 11.5 KB |
| v5.0.0 (gzip) | 54 KB | 3.1 KB |
Full Changelog: v4.10.0...v5.0.0