From 76e61370207bfbc92c110f46233520ea3e40dd35 Mon Sep 17 00:00:00 2001
From: prgmr99 <johnyeom24@naver.com>
Date: Tue, 28 Oct 2025 17:35:16 +0900
Subject: [PATCH 1/2] feat: add formatNumberWithCommas utility function and
 tests

---
 .../formatNumberWithCommas/index.test.ts      | 45 +++++++++++++++++++
 .../formatNumberWithCommas/index.ts           | 27 +++++++++++
 package/formatUtil/index.ts                   |  1 +
 3 files changed, 73 insertions(+)
 create mode 100644 package/formatUtil/formatNumberWithCommas/index.test.ts
 create mode 100644 package/formatUtil/formatNumberWithCommas/index.ts

diff --git a/package/formatUtil/formatNumberWithCommas/index.test.ts b/package/formatUtil/formatNumberWithCommas/index.test.ts
new file mode 100644
index 0000000..c18b164
--- /dev/null
+++ b/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");
+  });
+});
diff --git a/package/formatUtil/formatNumberWithCommas/index.ts b/package/formatUtil/formatNumberWithCommas/index.ts
new file mode 100644
index 0000000..6d19b89
--- /dev/null
+++ b/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");
+}
diff --git a/package/formatUtil/index.ts b/package/formatUtil/index.ts
index df16a92..5b85b72 100644
--- a/package/formatUtil/index.ts
+++ b/package/formatUtil/index.ts
@@ -1 +1,2 @@
 export { default as formatPhoneNumber } from "./formatPhoneNumber";
+export { default as formatNumberWithCommas } from "./formatNumberWithCommas";

From ebd628481ae572404b92b96fa95c8e71f6d6285d Mon Sep 17 00:00:00 2001
From: prgmr99 <johnyeom24@naver.com>
Date: Tue, 28 Oct 2025 17:36:55 +0900
Subject: [PATCH 2/2] feat: add formatNumberWithCommas description to README

---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index 488ff0e..e147912 100644
--- a/README.md
+++ b/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