fix(utils): formatNumberWithUnits, formatNumberWithCurrency 로직 개선 및 인터페이스 변경

.changeset/curly-timers-hope.md

@@ -0,0 +1,5 @@
+---
+'@modern-kit/utils': minor
+---
+
+fix(utils): formatNumberWithUnits, formatNumberWithCurrency 로직 개선 및 인터페이스 변경 - @ssi02014

docs/docs/utils/formatter/formatNumberWithCurrency.md

@@ -0,0 +1,75 @@
+# formatNumberWithCurrency
+
+`숫자` 혹은 `숫자로 이루어진 문자열`을 주어진 `통화 기호`를 추가하는 함수입니다.
+
+<br />
+
+## Code
+[🔗 실제 구현 코드 확인](https://github.com/modern-agile-team/modern-kit/blob/main/packages/utils/src/formatter/formatNumberWithCurrency/index.ts)
+
+## Interface
+```ts title="typescript"
+type Locale = 'KRW' | 'KRW_SYMBOL' | 'USD' | 'JPY' | 'CNY' | 'EUR';
+
+interface CurrencyOptions {
+  symbol?: string; // default: ''
+  position?: 'prefix' | 'suffix'; // default: 'suffix'
+  space?: boolean; // default: false
+  commas?: boolean; // default: true
+  locale?: Locale;
+}
+```
+```ts title="typescript"
+function formatNumberWithCurrency(
+  value: number | string,
+  options?: CurrencyOptions
+): string;
+```
+
+## Usage
+### 기본 동작
+```ts title="typescript"
+import { formatNumberWithCurrency } from '@modern-kit/utils';
+
+// 기본 동작
+formatNumberWithCurrency(1000) // '1,000'
+
+// 통화 기호 추가 (기본 값: '')
+formatNumberWithCurrency(1000, { symbol: '원' }) // '1,000원'
+formatNumberWithCurrency(1000, { symbol: '$', position: 'prefix' }) // '$1,000'
+
+// 숫자로 이루어진 문자열도 허용
+formatNumberWithCurrency('1000', { symbol: '원' }) // '1,000원'
+formatNumberWithCurrency('1000', { symbol: '$', position: 'prefix' }) // '$1,000'
+
+// 음수 처리
+formatNumberWithCurrency(-1000, { symbol: '$', position: 'prefix' }) // '-$1,000'
+formatNumberWithCurrency(-1000, { symbol: '원', position: 'suffix' }) // '-1,000원'
+```
+
+<br />
+
+### 옵션 사용
+```ts title="typescript"
+import { formatNumberWithCurrency } from '@modern-kit/utils';
+
+// 통호 기호 위치 변경 (기본값: 'suffix')
+formatNumberWithCurrency(1000, { symbol: '$', position: 'prefix' }) // '$1,000'
+
+// 공백 추가 (기본값: false)
+formatNumberWithCurrency(1000, { symbol: '$', position: 'prefix', space: false }) // '$1000'
+formatNumberWithCurrency(1000, { symbol: '$', position: 'prefix', space: true }) // '$ 1000'
+
+// 천의 단위 구분 여부 (기본값: true)
+formatNumberWithCurrency(1000, { symbol: '원', commas: false }) // '1000원'
+formatNumberWithCurrency(1000, { symbol: '원', commas: true }) // '1,000원'
+
+// locale 사용 
+// locale 옵션이 있으면 commas 옵션을 제외한 나머지 옵션들은 무시됩니다.
+formatNumberWithCurrency(1000, { locale: 'USD' }) // '$1,000'
+formatNumberWithCurrency(1000, { locale: 'KRW' }) // '1,000원'
+formatNumberWithCurrency(1000, { locale: 'KRW_SYMBOL' }) // '1,000₩'
+formatNumberWithCurrency(1000, { locale: 'JPY' }) // '¥1,000'
+formatNumberWithCurrency(1000, { locale: 'CNY' }) // '¥1,000'
+formatNumberWithCurrency(1000, { locale: 'EUR' }) // '€1,000'
+```

docs/docs/utils/formatter/formatNumberWithUnits.md

@@ -0,0 +1,91 @@
+# formatNumberWithUnits
+
+`숫자` 혹은 `숫자로 이루어진 문자열`을 주어진 `단위` 별로 포맷팅하는 함수입니다.
+
+<br />
+
+## Code
+[🔗 실제 구현 코드 확인](https://github.com/modern-agile-team/modern-kit/blob/main/packages/utils/src/formatter/formatNumberWithUnits/index.ts)
+
+## Interface
+```ts title="typescript"
+interface Unit {
+  unit: string;
+  value: number;
+}
+
+type FloorUnit =
+  | 1
+  | 10
+  | 100
+  | 1_000
+  | 10_000
+  | 100_000
+  | 1_000_000
+  | 10_000_000
+  | 100_000_000
+  | 1_000_000_000
+  | 10_000_000_000
+  | 100_000_000_000
+  | 1_000_000_000_000;
+
+interface FormatNumberWithUnitsOptions {
+  units?: Unit[] | readonly Unit[]; // default: []
+  commas?: boolean; // default: true
+  floorUnit?: FloorUnit; // default: 1
+  space?: boolean; // default: true
+}
+```
+```ts title="typescript"
+function formatNumberWithUnits(
+  value: number | string,
+  options?: FormatNumberWithUnitsOptions
+): string;
+```
+
+## Usage
+### 기본 동작
+```ts title="typescript"
+import { formatNumberWithUnits } from '@modern-kit/utils';
+
+const KRW_UNITS = [
+  { unit: '조', value: 1_000_000_000_000 },
+  { unit: '억', value: 100_000_000 },
+  { unit: '만', value: 10_000 },
+] as const;
+
+// 기본 동작
+formatNumberWithUnits(1234567) // "1,234,567"
+
+formatNumberWithUnits(1234567, { units: KRW_UNITS }) // "123만 4,567"
+formatNumberWithUnits(-1234567, { units: KRW_UNITS }) // "-123만 4,567", 음수 처리
+
+formatNumberWithUnits('1234567', { units: KRW_UNITS }) // "123만 4,567", 숫자로 이루어진 문자열 허용
+```
+
+<br />
+
+### 옵션 사용
+```ts title="typescript"
+import { formatNumberWithUnits } from '@modern-kit/utils';
+
+const KRW_UNITS = [
+  { unit: '조', value: 1_000_000_000_000 },
+  { unit: '억', value: 100_000_000 },
+  { unit: '만', value: 10_000 },
+] as const;
+
+// 단위 사이 공백 추가 (기본값: true)
+formatNumberWithUnits(1234567, { units: KRW_UNITS, space: true }) // "123만 4,567"
+formatNumberWithUnits(1234567, { units: KRW_UNITS, space: false }) // "123만4,567"
+
+// 쉼표 사용 여부 (기본값: true)
+formatNumberWithUnits(1234567, { units: KRW_UNITS, commas: false }) // "123만 4567"
+formatNumberWithUnits(1234567, { units: KRW_UNITS, commas: true }) // "123만 4,567"
+
+// 버림 단위 (기본값: 1)
+formatNumberWithUnits(1234567, { units: KRW_UNITS, floorUnit: 10000 }) // "123만"
+
+// 소수점 자리수 (기본값: 0)
+formatNumberWithUnits(1234567.123, { units: KRW_UNITS, decimal: 2 }) // "123만 4,567.12"
+```