fix(utils): formatNumberWithSeperator 변경 및 seperator 인자 추가

.changeset/fifty-hairs-march.md

@@ -0,0 +1,5 @@
+---
+'@modern-kit/utils': minor
+---
+
+fix(utils): formatNumberWithSeperator 변경 및 seperator 인자 추가 - @ssi02014

docs/docs/utils/formatter/formatNumberWithSeparator.md

@@ -0,0 +1,47 @@
+# formatNumberWithSeparator
+
+주어진 `숫자` 또는 `문자열`에 포함된 숫자를 천 단위로 `separator`를 추가한 문자열을 반환하는 함수입니다.
+
+<br />
+
+## Code
+[🔗 실제 구현 코드 확인](https://github.com/modern-agile-team/modern-kit/blob/main/packages/utils/src/formatter/formatNumberWithSeparator/index.ts)
+
+## Interface
+```ts title="typescript"
+function formatNumberWithSeparator(
+  value: number | string,
+  separator: string = ','
+): string;
+```
+
+## Usage
+### 기본 사용
+```ts title="typescript"
+import { formatNumberWithSeparator } from '@modern-kit/utils';
+
+// 숫자
+formatNumberWithSeparator(200); // '200'
+formatNumberWithSeparator(3000); // '3,000'
+formatNumberWithSeparator(-123123123); // '-123,123,123'
+formatNumberWithSeparator(123456.12345); // '123,456.12345'
+
+// 숫자로 이뤄진 문자열
+formatNumberWithSeparator('200'); // '200'
+formatNumberWithSeparator('3000'); // '3,000'
+formatNumberWithSeparator('-123123123'); // '-123,123,123'
+formatNumberWithSeparator('123456.12345'); // '123,456.12345'
+
+// 일반적인 문자열
+formatNumberWithSeparator('1433만 4567'); // '1,433만 4,567'
+formatNumberWithSeparator('1433만 4567.12345'); // '1,433만 4,567.12345'
+formatNumberWithSeparator('1234ddd'); // '1,234ddd'
+```
+
+### separator 변경
+```ts title="typescript"
+import { formatNumberWithSeparator } from '@modern-kit/utils';
+
+formatNumberWithSeparator('1234567', ' ') // '1 234 567'
+formatNumberWithSeparator('1234567', '-') // '1-234-567'
+```

docs/docs/utils/formatter/formatNumberWithUnits.md

@@ -2,6 +2,11 @@
 
 `숫자` 혹은 `숫자로 이루어진 문자열`을 주어진 `단위` 별로 포맷팅하는 함수입니다.
 
+- 천 단위 구분 기호 (`separator`)를 선택할 수 있습니다.
+- 버림 단위(`floorUnit`)를 선택할 수 있습니다.
+- 소수 일 경우 소수점 자리수(`decimal`)를 선택할 수 있습니다. 단, 버림 단위가 존재할 경우 소수 부분은 제거됩니다.
+- 단위 사이 공백 추가 여부(`space`)를 선택할 수 있습니다.
+
 <br />
 
 ## Code
@@ -31,9 +36,10 @@ type FloorUnit =
 
 interface FormatNumberWithUnitsOptions {
   units?: Unit[] | readonly Unit[]; // default: []
-  commas?: boolean; // default: true
+  separator?: string; // default: ','
   floorUnit?: FloorUnit; // default: 1
   space?: boolean; // default: true
+  decimal?: number; // default: 0
 }
 ```
 ```ts title="typescript"
@@ -79,9 +85,10 @@ const KRW_UNITS = [
 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"
+// 쉼표 사용 여부 (기본값: ',')
+formatNumberWithUnits(1234567, { units: KRW_UNITS, separator: '' }) // "123만 4567"
+formatNumberWithUnits(1234567, { units: KRW_UNITS, separator: ',' }) // "123만 4,567"
+formatNumberWithUnits(1234567, { units: KRW_UNITS, separator: ' ' }) // "123만 4 567"
 
 // 버림 단위 (기본값: 1)
 formatNumberWithUnits(1234567, { units: KRW_UNITS, floorUnit: 10000 }) // "123만"

docs/docs/utils/formatter/formatValueWithSymbol.md

@@ -3,8 +3,9 @@
 주어진 `숫자` 또는 `문자열`에 주어진 `기호`를 추가하는 함수입니다.
 
 - 기호는 `prefix` 또는 `suffix` 위치에 추가할 수 있습니다.
-- `음수` 값의 경우 기호 앞에 `-`가 추가됩니다.
-- 기호와 값 사이에 `공백`을 추가할 수 있습니다.
+- 음수일 경우 기호 앞에 `-`가 추가됩니다.
+- 기호와 값 사이에 공백 여부(`space`)를 선택할 수 있습니다.
+- 천 단위 구분 기호 (`separator`)를 선택할 수 있습니다.
 
 <br />
 
@@ -14,9 +15,10 @@
 ## Interface
 ```ts title="typescript"
 interface FormatValueWithSymbolOptions {
-  symbol?: string;
-  position?: 'prefix' | 'suffix';
-  space?: boolean;
+  symbol?: string; // default: ''
+  position?: 'prefix' | 'suffix'; // default: 'suffix'
+  space?: boolean; // default: false
+  separator?: string; // default: ','
 }
 ```
 ```ts title="typescript"
@@ -31,37 +33,36 @@ function formatValueWithSymbol(
 import { formatValueWithSymbol } from '@modern-kit/utils';
 
 // 통화 기호 추가 (기본 값: '')
-formatValueWithSymbol(1000) // '1000'
-formatValueWithSymbol(1000, { symbol: '원' }) // '1000원'
+formatValueWithSymbol(1000) // '1,000'
+formatValueWithSymbol(1000, { symbol: '원' }) // '1,000원'
 
 // 통호 기호 위치 변경 (기본값: 'suffix')
-formatValueWithSymbol(1000, { symbol: '$', position: 'prefix' }) // '$1000'
-formatValueWithSymbol(1000, { symbol: '원', position: 'suffix' }) // '1000원'
+formatValueWithSymbol(1000, { symbol: '$', position: 'prefix' }) // '$1,000'
+formatValueWithSymbol(1000, { symbol: '원', position: 'suffix' }) // '1,000원'
 
 // 공백 추가 (기본값: false)
-formatValueWithSymbol(1000, { symbol: '$', position: 'prefix', space: false }) // '$1000'
-formatValueWithSymbol(1000, { symbol: '$', position: 'prefix', space: true }) // '$ 1000'
+formatValueWithSymbol(1000, { symbol: '$', position: 'prefix', space: false }) // '$1,000'
+formatValueWithSymbol(1000, { symbol: '$', position: 'prefix', space: true }) // '$ 1,000'
+
+// 천 단위 구분 기호 변경 (기본값: `,`)
+formatValueWithSymbol(1000, { symbol: '$', position: 'prefix', separator: '' }) // '$1000'
+formatValueWithSymbol(1000, { symbol: '$', position: 'prefix', separator: ',' }) // '$1,000'
+formatValueWithSymbol(1000, { symbol: '$', position: 'prefix', separator: '-' }) // '$1-000'
 ```
 
 <br />
 
-### 응용
+### 응용 (with formatNumberWithUnits)
 ```ts title="typescript"
-import { 
-  formatValueWithSymbol, 
-  formatNumberWithCommas, 
-  formatNumberWithUnits 
-} from '@modern-kit/utils';
+import { formatValueWithSymbol, 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;
 
-const numberWithCommas = formatNumberWithCommas(1234567); // 1,234,567
-const numberWithKRWUnits = formatNumberWithUnits(1230000, { units: KRW_UNITS }); // 123만
+const numberWithKRWUnits = formatNumberWithUnits(12340000, { units: KRW_UNITS }); // 1,234만
 
-formatValueWithSymbol(numberWithKRWUnits, { symbol: '원' }) // '123만원'
-formatValueWithSymbol(numberWithCommas, { symbol: '원' }) // '1,234,567원'
+formatValueWithSymbol(numberWithKRWUnits, { symbol: '원' }) // '1,234만원'
 ```

packages/utils/src/formatter/formatNumberWithSeparator/formatNumberWithSeparator.spec.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import { formatNumberWithSeparator } from '.';
+
+describe('formatNumberWithSeparator', () => {
+  it('숫자에 천 단위마다 ","를 추가하고 문자열로 반환해야 합니다.', () => {
+    expect(formatNumberWithSeparator(200)).toBe('200');
+    expect(formatNumberWithSeparator(3000)).toBe('3,000');
+    expect(formatNumberWithSeparator(50000)).toBe('50,000');
+    expect(formatNumberWithSeparator(-50000)).toBe('-50,000');
+    expect(formatNumberWithSeparator(123123123)).toBe('123,123,123');
+    expect(formatNumberWithSeparator(123456.12345)).toBe('123,456.12345');
+  });
+
+  it('숫자로 이뤄진 문자열에도 ","를 추가해 반환해야 합니다.', () => {
+    expect(formatNumberWithSeparator('200')).toBe('200');
+    expect(formatNumberWithSeparator('3000')).toBe('3,000');
+    expect(formatNumberWithSeparator('50000')).toBe('50,000');
+    expect(formatNumberWithSeparator('-50000')).toBe('-50,000');
+    expect(formatNumberWithSeparator('123123123')).toBe('123,123,123');
+    expect(formatNumberWithSeparator('123456.12345')).toBe('123,456.12345');
+  });
+
+  it('일반적인 문자열의 경우에도 숫자에 천 단위마다 ","를 추가해야 합니다.', () => {
+    expect(formatNumberWithSeparator('1433만 4567')).toBe('1,433만 4,567');
+    expect(formatNumberWithSeparator('1433만 4567.12345')).toBe(
+      '1,433만 4,567.12345'
+    );
+    expect(formatNumberWithSeparator('1234ddd')).toBe('1,234ddd');
+  });
+
+  it('separator를 변경할 수 있어야 합니다.', () => {
+    expect(formatNumberWithSeparator('1234567', ' ')).toBe('1 234 567');
+    expect(formatNumberWithSeparator('1234567', '-')).toBe('1-234-567');
+  });
+
+  it('숫자가 없는 문자열의 경우 문자열을 그대로 반환해야 합니다.', () => {
+    expect(formatNumberWithSeparator('')).toBe('');
+    expect(formatNumberWithSeparator('ddd')).toBe('ddd');
+  });
+});

packages/utils/src/formatter/formatNumberWithSeparator/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @description 주어진 `숫자` 또는 `문자열`에 포함된 숫자를 천 단위로 `separator`를 추가한 문자열을 반환하는 함수입니다.
+ *
+ * @param {number | string} value - 포맷팅할 숫자 값입니다.
+ * @param {string} [separator=','] - 천 단위 구분 기호입니다. (기본값: `,`)
+ * @returns {string} 포맷팅된 문자열
+ *
+ * @example
+ * // 숫자
+ * formatNumberWithSeparator(1234567.89112); // '1,234,567.89112'
+ *
+ * // 숫자로 이루어진 문자열
+ * formatNumberWithSeparator('1234567.89112'); // '1,234,567.89112'
+ *
+ * // 숫자를 포함한 일반적인 문자열
+ * formatNumberWithSeparator('1433만 4567'); // '1,433만 4,567'
+ *
+ * @example
+ * // separator 변경
+ * formatNumberWithSeparator('1234567', ' ') // '1 234 567'
+ */
+export function formatNumberWithSeparator(
+  value: number | string,
+  separator: string = ','
+): string {
+  return String(value).replace(/\B(?<!\.\d*)(?=(\d{3})+(?!\d))/g, separator);
+}

packages/utils/src/formatter/formatNumberWithUnits/formatNumberWithUnits.spec.ts

@@ -66,23 +66,30 @@ describe('formatNumberWithUnits', () => {
       expect(formatNumberWithUnits(12345, { floorUnit: 10000 })).toBe('10,000');
     });
 
-    it('commas가 true라면 ","를 추가하며, false라면 제외해야 합니다.', () => {
+    it('separator가 주어진 값에 따라 천 단위 구분 기호를 적용해야 합니다.', () => {
       expect(
         formatNumberWithUnits(1234567890000, {
-          commas: false,
+          separator: '',
           units: KRW_UNITS,
         })
       ).toBe('1조 2345억 6789만');
 
       expect(
         formatNumberWithUnits(1234567890000, {
-          commas: true,
+          separator: ',',
           units: KRW_UNITS,
         })
       ).toBe('1조 2,345억 6,789만');
 
+      expect(
+        formatNumberWithUnits(1234567890000, {
+          separator: '-',
+          units: KRW_UNITS,
+        })
+      ).toBe('1조 2-345억 6-789만');
+
       // units 옵션이 주어지지 않으면 기본 단위로 포맷팅
-      expect(formatNumberWithUnits(1234567890000, { commas: true })).toBe(
+      expect(formatNumberWithUnits(1234567890000, { separator: ',' })).toBe(
         '1,234,567,890,000'
       );
     });
@@ -143,12 +150,6 @@ describe('formatNumberWithUnits', () => {
       ).toThrow('floorUnit은 1을 포함한 10의 제곱수여야 합니다.');
     });
 
-    it('floorUnit가 value의 절대값보다 작으면 예외를 발생시킵니다.', () => {
-      expect(() =>
-        formatNumberWithUnits(1234567, { floorUnit: 1000000000 })
-      ).toThrow('floorUnit 값은 value의 절대값보다 크거나 같아야 합니다.');
-    });
-
     it('decimal이 0보다 작으면 예외를 발생시킵니다.', () => {
       expect(() =>
         formatNumberWithUnits(1234567, { decimal: -1 as unknown as number })

packages/utils/src/formatter/formatNumberWithUnits/formatNumberWithUnits.types.ts

@@ -20,7 +20,7 @@ export interface Unit {
 
 export interface FormatNumberWithUnitsOptions {
   units?: Unit[] | readonly Unit[];
-  commas?: boolean;
+  separator?: string;
   floorUnit?: FloorUnit;
   space?: boolean;
   decimal?: number;