feat: 숫자를 한글로 바꾸는 함수 추가

docs/src/pages/docs/api/numberToHangul.en.mdx

@@ -0,0 +1,38 @@
+---
+title: numberToHangul
+---
+
+import { Sandpack } from '@/components/Sandpack';
+
+# numberToHangul
+
+Converts the given number into a Korean numeral expression using Sino-Korean numbers.
+It supports spacing for “man(萬)” units to accommodate various requirements.
+
+```typescript
+function numberToHangul(input: number, options?: { spacing?: boolean }): string;
+```
+
+## Examples
+
+```tsx
+numberToHangul(210_000); // '이십일만';
+numberToHangul(12_345); // '일만이천삼백사십오';
+numberToHangul(123_456_780); // '일억이천삼백사십오만육천칠백팔십';
+numberToHangul(123_456_780, { spacing: true }); // '일억 이천삼백사십오만 육천칠백팔십';
+```
+
+## 사용해보기
+
+<br />
+
+<Sandpack>
+
+```ts index.ts
+import { numberToHangul } from 'es-hangul';
+
+console.log(numberToHangul(123_456_780));
+console.log(numberToHangul(123_456_780, { spacing: true }));
+```
+
+</Sandpack>

docs/src/pages/docs/api/numberToHangul.ko.mdx

@@ -0,0 +1,38 @@
+---
+title: numberToHangul
+---
+
+import { Sandpack } from '@/components/Sandpack';
+
+# numberToHangul
+
+주어진 숫자를 한자어 수사로 바꿔줍니다.
+다양한 요구사항에 대응하도록 '만(萬)' 단위로 띄어쓰기를 지원합니다.
+
+```typescript
+function numberToHangul(input: number, options?: { spacing?: boolean }): string;
+```
+
+## Examples
+
+```tsx
+numberToHangul(210_000); // '이십일만';
+numberToHangul(12_345); // '일만이천삼백사십오';
+numberToHangul(123_456_780); // '일억이천삼백사십오만육천칠백팔십';
+numberToHangul(123_456_780, { spacing: true }); // '일억 이천삼백사십오만 육천칠백팔십';
+```
+
+## 사용해보기
+
+<br />
+
+<Sandpack>
+
+```ts index.ts
+import { numberToHangul } from 'es-hangul';
+
+console.log(numberToHangul(123_456_780));
+console.log(numberToHangul(123_456_780, { spacing: true }));
+```
+
+</Sandpack>

docs/src/pages/docs/api/numberToHanuglMixed.en.mdx

@@ -0,0 +1,38 @@
+---
+title: numberToHangulMixed
+---
+
+import { Sandpack } from '@/components/Sandpack';
+
+# numberToHangulMixed
+
+Attaches the Korean number units that change every 4 digits to the given number.
+It supports spacing for “man(萬)” units to accommodate various requirements.
+
+```typescript
+function numberToHangulMixed(input: number, options?: { spacing?: boolean }): string;
+```
+
+## Examples
+
+```tsx
+numberToHangulMixed(210_000); // '21만';
+numberToHangulMixed(12_345); // '1만2,345';
+numberToHangulMixed(123_456_780); // '1억2,345만6,780';
+numberToHangulMixed(123_456_780, { spacing: true }); // '1억 2,345만 6,780';
+```
+
+## 사용해보기
+
+<br />
+
+<Sandpack>
+
+```ts index.ts
+import { numberToHangulMixed } from 'es-hangul';
+
+console.log(numberToHangulMixed(1_2345_6780));
+console.log(numberToHangulMixed(1_2345_6780, { spacing: true }));
+```
+
+</Sandpack>

docs/src/pages/docs/api/numberToHanuglMixed.ko.mdx

@@ -0,0 +1,38 @@
+---
+title: numberToHangulMixed
+---
+
+import { Sandpack } from '@/components/Sandpack';
+
+# numberToHangulMixed
+
+주어진 숫자에 **4자리 마다 바뀌는 한글의 숫자 단위**를 붙여줍니다.
+다양한 요구사항에 대응하도록 '만(萬)' 단위로 띄어쓰기를 지원합니다.
+
+```typescript
+function numberToHangulMixed(input: number, options?: { spacing?: boolean }): string;
+```
+
+## Examples
+
+```tsx
+numberToHangulMixed(210_000); // '21만';
+numberToHangulMixed(12_345); // '1만2,345';
+numberToHangulMixed(123_456_780); // '1억2,345만6,780';
+numberToHangulMixed(123_456_780, { spacing: true }); // '1억 2,345만 6,780';
+```
+
+## 사용해보기
+
+<br />
+
+<Sandpack>
+
+```ts index.ts
+import { numberToHangulMixed } from 'es-hangul';
+
+console.log(numberToHangulMixed(123_456_780));
+console.log(numberToHangulMixed(123_456_780, { spacing: true }));
+```
+
+</Sandpack>

src/_internal/constants.ts

@@ -134,3 +134,30 @@ export const JONGSEONGS = (
     'ㅎ',
   ] as const
 ).map(consonant => DISASSEMBLED_CONSONANTS_BY_CONSONANT[consonant]);
+
+export const HANGUL_DIGITS = [
+  '',
+  '만',
+  '억',
+  '조',
+  '경',
+  '해',
+  '자',
+  '양',
+  '구',
+  '간',
+  '정',
+  '재',
+  '극',
+  '항하사',
+  '아승기',
+  '나유타',
+  '불가사의',
+  '무량대수',
+  '겁',
+  '업',
+];
+export const HANGUL_DIGITS_MAX = HANGUL_DIGITS.length * 4;
+export const HANGUL_NUMBERS = ['', '일', '이', '삼', '사', '오', '육', '칠', '팔', '구'];
+export const HANGUL_NUMBERS_FOR_DECIMAL = ['영', '일', '이', '삼', '사', '오', '육', '칠', '팔', '구'];
+export const HANGUL_CARDINAL = ['', '십', '백', '천'];

src/amountToHangul/amountToHangul.ts

@@ -1,30 +1,14 @@
-export const HANGUL_DIGITS = [
-  '',
-  '만',
-  '억',
-  '조',
-  '경',
-  '해',
-  '자',
-  '양',
-  '구',
-  '간',
-  '정',
-  '재',
-  '극',
-  '항하사',
-  '아승기',
-  '나유타',
-  '불가사의',
-  '무량대수',
-  '겁',
-  '업',
-];
-export const HANGUL_DIGITS_MAX = HANGUL_DIGITS.length * 4;
-export const HANGUL_NUMBERS = ['', '일', '이', '삼', '사', '오', '육', '칠', '팔', '구'];
-export const HANGUL_NUMBERS_FOR_DECIMAL = ['영', '일', '이', '삼', '사', '오', '육', '칠', '팔', '구'];
-export const HANGUL_CARDINAL = ['', '십', '백', '천'];
-
+import {
+  HANGUL_DIGITS_MAX,
+  HANGUL_NUMBERS_FOR_DECIMAL,
+  HANGUL_NUMBERS,
+  HANGUL_DIGITS,
+  HANGUL_CARDINAL,
+} from '@/_internal/constants';
+
+/**
+ * @deprecated 더 유연하게 사용 가능한 `numberToHangul`을 이용해 주세요
+ */
 export function amountToHangul(amount: string | number) {
   const [rawIntegerPart, rawDecimalPart] = String(amount)
     .replace(/[^\d.]+/g, '')

src/index.ts

@@ -13,3 +13,5 @@ export { hasBatchim } from './hasBatchim';
 export { canBeChoseong, canBeJongseong, canBeJungseong } from './canBe';
 export { getChoseong } from './getChoseong';
 export { amountToHangul } from './amountToHangul';
+export { numberToHangul } from './numberToHangul';
+export { numberToHangulMixed } from './numberToHangulMixed';

src/numberToHangul/index.ts

@@ -0,0 +1 @@
+export * from './numberToHangul';

src/numberToHangul/numberToHangul.spec.ts

@@ -0,0 +1,43 @@
+import { numberToHangul } from './numberToHangul';
+
+describe('numberToHangul', () => {
+  test('기본 변환', () => {
+    expect(numberToHangul(210_000)).toBe('이십일만');
+    expect(numberToHangul(12_345)).toBe('일만이천삼백사십오');
+    expect(numberToHangul(123_456_780)).toBe('일억이천삼백사십오만육천칠백팔십');
+  });
+
+  test('공백 포함 변환', () => {
+    expect(numberToHangul(210_000, { spacing: true })).toBe('이십일만');
+    expect(numberToHangul(12_345, { spacing: true })).toBe('일만 이천삼백사십오');
+    expect(numberToHangul(123_456_780, { spacing: true })).toBe('일억 이천삼백사십오만 육천칠백팔십');
+  });
+
+  test('0과 10,000보다 작은 경우', () => {
+    expect(numberToHangul(0)).toBe('영');
+    expect(numberToHangul(1)).toBe('일');
+    expect(numberToHangul(2)).toBe('이');
+    expect(numberToHangul(3)).toBe('삼');
+    expect(numberToHangul(4)).toBe('사');
+    expect(numberToHangul(5)).toBe('오');
+    expect(numberToHangul(6)).toBe('육');
+    expect(numberToHangul(7)).toBe('칠');
+    expect(numberToHangul(8)).toBe('팔');
+    expect(numberToHangul(9)).toBe('구');
+    expect(numberToHangul(10)).toBe('십');
+    expect(numberToHangul(11)).toBe('십일');
+    expect(numberToHangul(20)).toBe('이십');
+    expect(numberToHangul(30)).toBe('삼십');
+    expect(numberToHangul(100)).toBe('백');
+    expect(numberToHangul(101)).toBe('백일');
+    expect(numberToHangul(110)).toBe('백십');
+    expect(numberToHangul(200)).toBe('이백');
+    expect(numberToHangul(300)).toBe('삼백');
+    expect(numberToHangul(1_000)).toBe('천');
+    expect(numberToHangul(1_001)).toBe('천일');
+    expect(numberToHangul(1_100)).toBe('천백');
+    expect(numberToHangul(1_200)).toBe('천이백');
+    expect(numberToHangul(1_234)).toBe('천이백삼십사');
+    expect(numberToHangul(9_999)).toBe('구천구백구십구');
+  });
+});

src/numberToHangul/numberToHangul.ts

@@ -0,0 +1,46 @@
+import { HANGUL_CARDINAL, HANGUL_DIGITS, HANGUL_NUMBERS } from '@/_internal/constants';
+
+export function numberToHangul(input: number, options?: { spacing?: boolean }): string {
+  if (input === 0) {
+    return '영';
+  }
+
+  const koreanParts: string[] = [];
+  let remainingDigits = input.toString();
+  let placeIndex = 0;
+
+  while (remainingDigits.length > 0) {
+    const currentPart = remainingDigits.slice(-4);
+
+    koreanParts.unshift(`${numberToKoreanUpToThousand(Number(currentPart))}${HANGUL_DIGITS[placeIndex]}`);
+
+    remainingDigits = remainingDigits.slice(0, -4);
+    placeIndex++;
+  }
+
+  if (options?.spacing) {
+    return koreanParts
+      .filter(part => part !== '')
+      .join(' ')
+      .trim();
+  }
+
+  return koreanParts.join('');
+}
+
+function numberToKoreanUpToThousand(num: number): string {
+  if (num < 0 || num > 9999) {
+    throw new Error('0 이상 9999 이하의 숫자만 입력 가능합니다.');
+  }
+
+  const koreanDigits = num
+    .toString()
+    .split('')
+    .reverse()
+    .map((digit, index) => (digit === '0' ? '' : HANGUL_NUMBERS[Number(digit)] + HANGUL_CARDINAL[index]))
+    .reverse()
+    .join('');
+
+  return koreanDigits.replace(/일천/, '천').replace(/일백/, '백').replace(/일십/, '십') || '';
+
+}

src/numberToHangulMixed/index.ts

@@ -0,0 +1 @@
+export * from './numberToHangulMixed';

src/numberToHangulMixed/numberToHangulMixed.spec.ts

@@ -0,0 +1,43 @@
+import { numberToHangulMixed } from './numberToHangulMixed';
+
+describe('numberToHangulMixed', () => {
+  test('기본 변환', () => {
+    expect(numberToHangulMixed(210_000)).toBe('21만');
+    expect(numberToHangulMixed(12_345)).toBe('1만2,345');
+    expect(numberToHangulMixed(123_456_780)).toBe('1억2,345만6,780');
+  });
+
+  test('공백 포함 변환', () => {
+    expect(numberToHangulMixed(210_000, { spacing: true })).toBe('21만');
+    expect(numberToHangulMixed(12_345, { spacing: true })).toBe('1만 2,345');
+    expect(numberToHangulMixed(123_456_780, { spacing: true })).toBe('1억 2,345만 6,780');
+  });
+
+  test('0과 10,000보다 작은 경우', () => {
+    expect(numberToHangulMixed(0)).toBe('0');
+    expect(numberToHangulMixed(1)).toBe('1');
+    expect(numberToHangulMixed(2)).toBe('2');
+    expect(numberToHangulMixed(3)).toBe('3');
+    expect(numberToHangulMixed(4)).toBe('4');
+    expect(numberToHangulMixed(5)).toBe('5');
+    expect(numberToHangulMixed(6)).toBe('6');
+    expect(numberToHangulMixed(7)).toBe('7');
+    expect(numberToHangulMixed(8)).toBe('8');
+    expect(numberToHangulMixed(9)).toBe('9');
+    expect(numberToHangulMixed(10)).toBe('10');
+    expect(numberToHangulMixed(11)).toBe('11');
+    expect(numberToHangulMixed(20)).toBe('20');
+    expect(numberToHangulMixed(30)).toBe('30');
+    expect(numberToHangulMixed(100)).toBe('100');
+    expect(numberToHangulMixed(101)).toBe('101');
+    expect(numberToHangulMixed(110)).toBe('110');
+    expect(numberToHangulMixed(200)).toBe('200');
+    expect(numberToHangulMixed(300)).toBe('300');
+    expect(numberToHangulMixed(1_000)).toBe('1,000');
+    expect(numberToHangulMixed(1_001)).toBe('1,001');
+    expect(numberToHangulMixed(1_100)).toBe('1,100');
+    expect(numberToHangulMixed(1_200)).toBe('1,200');
+    expect(numberToHangulMixed(1_234)).toBe('1,234');
+    expect(numberToHangulMixed(9_999)).toBe('9,999');
+  });
+});