feat: Add format number utility (#70)

* feat: add formatNumberWithCommas utility function and tests

* feat: add formatNumberWithCommas description to README

Author: prgmr99

README.md

@@ -166,6 +166,7 @@ storage.set("data", { key: "value" });
 ### FormatUtil
 
 - `formatPhoneNumber(phone: string): string` - Formats a phone number string to a standard format (e.g., "010-1234-5678")
+- `formatNumberWithCommas(value: number | string | null | undefined): string` - Converts numbers or strings to comma-separated format (e.g., "1,234,567"). Returns empty string for null/undefined values.
 
 ### ValidationUtil
 

package/formatUtil/formatNumberWithCommas/index.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "vitest";
+import formatNumberWithCommas from ".";
+
+describe("formatNumberWithCommas", () => {
+  test("네 자리 정수를 올바르게 포맷팅해야 합니다.", () => {
+    expect(formatNumberWithCommas(1234)).toBe("1,234");
+  });
+
+  test("세 자리 정수는 콤마 없이 그대로 반환해야 합니다.", () => {
+    expect(formatNumberWithCommas(999)).toBe("999");
+  });
+
+  test('숫자 0을 올바르게 "0"으로 반환해야 합니다.', () => {
+    expect(formatNumberWithCommas(0)).toBe("0");
+  });
+
+  test("숫자 입력 시 3자리마다 콤마가 포함된 문자열을 반환한다", () => {
+    expect(formatNumberWithCommas(1234567)).toBe("1,234,567");
+    expect(formatNumberWithCommas(-12345.67)).toBe("-12,345.67");
+  });
+
+  test("null 입력 시 빈 문자열을 반환해야 합니다.", () => {
+    expect(formatNumberWithCommas(null)).toBe("");
+  });
+
+  test("undefined 입력 시 빈 문자열을 반환해야 합니다.", () => {
+    expect(formatNumberWithCommas(undefined)).toBe("");
+  });
+
+  test("빈 문자열 입력 시 빈 문자열을 반환해야 합니다.", () => {
+    expect(formatNumberWithCommas("")).toBe("");
+  });
+
+  test("숫자로 변환할 수 없는 문자열은 그대로 반환해야 합니다.", () => {
+    expect(formatNumberWithCommas("안녕하세요")).toBe("안녕하세요");
+  });
+
+  test("이미 콤마가 포함된 문자열은 (NaN으로 처리되어) 그대로 반환해야 합니다.", () => {
+    expect(formatNumberWithCommas("12,345")).toBe("12,345");
+  });
+
+  test('NaN 값을 직접 입력하면 "NaN" 문자열을 반환해야 합니다.', () => {
+    expect(formatNumberWithCommas(NaN)).toBe("NaN");
+  });
+});

package/formatUtil/formatNumberWithCommas/index.ts

@@ -0,0 +1,27 @@
+/**
+ * 숫자나 문자열을 3자리마다 콤마(,)가 포함된 문자열로 변환합니다.
+ * null, undefined, 또는 유효하지 않은 값이 들어오면 빈 문자열을 반환합니다.
+ *
+ * @param value - 콤마를 추가할 숫자 또는 문자열
+ * @returns 콤마가 추가된 문자열
+ *
+ * @example
+ * formatNumberWithCommas(1234567); // "1,234,567"
+ * formatNumberWithCommas(-12345.67); // "-12,345.67"
+ * formatNumberWithCommas("12345"); // "12,345"
+ */
+export default function formatNumberWithCommas(
+  value: number | string | null | undefined
+): string {
+  if (value === null || value === undefined || value === "") {
+    return "";
+  }
+
+  const num = Number(value);
+
+  if (isNaN(num)) {
+    return String(value);
+  }
+
+  return num.toLocaleString("en-US");
+}

package/formatUtil/index.ts

@@ -1 +1,2 @@
 export { default as formatPhoneNumber } from "./formatPhoneNumber";
+export { default as formatNumberWithCommas } from "./formatNumberWithCommas";