Mandarin Financial Capital Numerals (國語大寫數字)

A TypeScript library for converting numbers into Mandarin Chinese financial numerals (國語大寫數字), commonly used in monetary documents, bank checks, receipts, contracts, and formal financial documents across Chinese-speaking regions. These numerals are specifically designed to prevent forgery and ensure clarity in financial contexts.

Installation

You can directly copy the code from src/index.ts into your project. The implementation is self-contained with no external dependencies:

Then use it in your code:

import { toCapitalNumerals } from './path-to-your-file';

Usage

// Basic usage with numbers
toCapitalNumerals(1234)    // returns "壹仟貳佰參拾肆圓整"
toCapitalNumerals(0)       // returns "零圓整"

// Using strings for large numbers (beyond Number.MAX_SAFE_INTEGER)
toCapitalNumerals("10000000000000000")  // returns "壹京圓整"

Features

• Supports numbers from 0 up to 99,999,999,999,999,999 (京)
• Handles both number and string inputs
• Automatically formats with appropriate Mandarin Chinese units (單位): 拾、佰、仟、萬、億、兆、京
• Adds proper zero (零) placement between significant digits
• Appends standard currency suffix "圓整"

Testing Coverage

The implementation has been thoroughly tested with Vitest, covering:

Single digit formatting across all magnitude units (佰/仟/萬/億/兆/京)

• Clean powers of 10 for all units (拾/佰/仟/萬/億/兆/京)
• Complex combinations with multiple zeros
• Numbers in 京 range (up to 17 digits)
• Edge cases (maximum digits, zero)
• Error handling (invalid inputs, overflows)

All test cases pass successfully, ensuring reliable and accurate conversion for financial use.

Examples

// Basic numbers
toCapitalNumerals(1)          // "壹圓整"
toCapitalNumerals(10)         // "壹拾圓整"
toCapitalNumerals(100)        // "壹佰圓整"

// Numbers with zeros
toCapitalNumerals(1002)       // "壹仟零貳圓整"
toCapitalNumerals(10003)      // "壹萬零參圓整"
toCapitalNumerals(100004)     // "壹拾萬零肆圓整"

// Complex numbers
toCapitalNumerals(10101)      // "壹萬零壹佰零壹圓整"
toCapitalNumerals(1010100)    // "壹佰零壹萬零壹佰圓整"

// Large numbers (use string for values > Number.MAX_SAFE_INTEGER)
toCapitalNumerals("12345678987654321")  
// "壹京貳仟參佰肆拾伍兆陸仟柒佰捌拾玖億捌仟柒佰陸拾伍萬肆仟參佰貳拾壹圓整"

Error Handling

The function throws errors in the following cases:

// Non-integer numbers
toCapitalNumerals(1.5)        // Error: "Number must be an integer"

// Negative numbers
toCapitalNumerals(-1)         // Error: "Negative numbers are not supported"

// Numbers exceeding maximum safe integer
toCapitalNumerals(9999999999999999)  // Error: "Number exceeds maximum safe integer"

// Strings exceeding maximum supported digits
toCapitalNumerals("100000000000000000")  // Error: "Number exceeds maximum supported digits"

Supported Units

The function supports the following Mandarin Chinese numerical units in ascending order:

• 個位 (Ones)
• 拾 (Tens)
• 佰 (Hundreds)
• 仟 (Thousands)
• 萬 (Ten Thousands)
• 億 (Hundred Millions)
• 兆 (Trillions)
• 京 (Quadrillions)

Notes

• The function always appends "圓整" to the result, which is commonly used in financial contexts to indicate exact whole numbers
• For numbers larger than Number.MAX_SAFE_INTEGER (9007199254740991), use string input to maintain precision
• Zero is represented as "零圓整"
• The function handles proper insertion of 零 between non-zero digits across different units

Contact

If you have any questions, please feel free to file issues or contact me at bwchen.dev@gmail.com.