korean-currency

숫자를 한글 금액으로 변환하는 라이브러리

12500 → "일만이천오백원"

설치

npm install korean-currency

사용법

ESM / TypeScript

import { toKorean, fromKorean } from 'korean-currency';

toKorean(12500);                      // "일만이천오백원"
toKorean(12500, { suffix: false });   // "일만이천오백"
toKorean(340000000);                  // "삼억사천만원"

fromKorean("일만이천오백원");           // 12500
fromKorean("삼억사천만원");             // 340000000

CommonJS

const { toKorean, fromKorean } = require('korean-currency');

toKorean(12500);  // "일만이천오백원"

API

toKorean(num, options?)

숫자를 한글 금액으로 변환합니다.

| 매개변수 | 타입 | 설명 | |---------|------|------| | num | number | 변환할 숫자 | | options | object | 옵션 (선택) |

Options

| 옵션 | 타입 | 기본값 | 설명 | |-----|------|-------|------| | suffix | boolean | true | "원"을 붙일지 여부 | | unit | boolean | true | 단위(만, 억 등)를 포함할지 여부 |

toKorean(12500);                      // "일만이천오백원"
toKorean(12500, { suffix: false });   // "일만이천오백"
toKorean(0);                          // "영원"
toKorean(-5000);                      // "마이너스 오천원"

fromKorean(korean)

한글 금액을 숫자로 변환합니다.

| 매개변수 | 타입 | 설명 | |---------|------|------| | korean | string | 한글 금액 문자열 |

fromKorean("일만이천오백원");   // 12500
fromKorean("삼억사천만원");     // 340000000
fromKorean("영");              // 0

지원 범위

• 0부터 해(10^20) 단위까지 지원
• 음수 지원 ("마이너스 ...")
• 소수점은 정수 부분만 변환

정밀도 안내

JavaScript의 Number.MAX_SAFE_INTEGER는 약 9천조(9 × 10^15)입니다.

| 단위 | 값 | 상태 | |-----|-----|------| | 조 (10^12) | 1,000,000,000,000 | ✅ 정확 | | 경 (10^16) | 10,000,000,000,000,000 | ⚠️ 정밀도 손실 가능 | | 해 (10^20) | 100,000,000,000,000,000,000 | ⚠️ 정밀도 손실 가능 |

조 단위까지는 100% 정확하며, 경/해 단위는 큰 금액 표시용으로 사용하세요.

에러 처리

잘못된 입력에 대해 에러를 throw합니다.

toKorean

toKorean(NaN);           // TypeError: NaN은 변환할 수 없습니다.
toKorean(Infinity);      // TypeError: Infinity는 변환할 수 없습니다.
toKorean(1e25);          // RangeError: 지원 범위를 초과했습니다.
toKorean("12500");       // TypeError: 숫자가 필요합니다.

fromKorean

fromKorean("");          // TypeError: 빈 문자열은 변환할 수 없습니다.
fromKorean("hello");     // TypeError: 잘못된 문자가 포함되어 있습니다.
fromKorean(12500);       // TypeError: 문자열이 필요합니다.

라이선스

MIT

korean-currency (English)

A library to convert numbers to Korean currency format.

12500 → "일만이천오백원" (approximately: "12,500 won" in Korean)

Installation

npm install korean-currency

Usage

import { toKorean, fromKorean } from 'korean-currency';

toKorean(12500);                      // "일만이천오백원"
toKorean(12500, { suffix: false });   // "일만이천오백"

fromKorean("일만이천오백원");           // 12500

API

toKorean(num, options?)

Converts a number to Korean currency string.

| Parameter | Type | Description | |-----------|------|-------------| | num | number | Number to convert | | options.suffix | boolean | Append "원" (won) suffix (default: true) | | options.unit | boolean | Include units like 만, 억 (default: true) |

fromKorean(korean)

Converts a Korean currency string to number.

| Parameter | Type | Description | |-----------|------|-------------| | korean | string | Korean currency string |

Supported Range

• Supports 0 to 해 (10^20)
• Supports negative numbers ("마이너스 ...")
• Decimals are truncated to integers

Precision Notice

JavaScript's Number.MAX_SAFE_INTEGER is approximately 9 × 10^15.

| Unit | Value | Status | |------|-------|--------| | 조 (trillion) | 10^12 | ✅ Accurate | | 경 (10 quadrillion) | 10^16 | ⚠️ Possible precision loss | | 해 (100 quintillion) | 10^20 | ⚠️ Possible precision loss |

Accurate up to 조 (trillion). Use 경/해 for display purposes only.

Error Handling

Throws errors for invalid inputs:

• TypeError: Invalid type, NaN, Infinity, empty string, invalid characters
• RangeError: Number exceeds supported range (> 10^24)

License

MIT