@simplysm/core-common 13.0.69 → 13.0.71

package/src/utils/primitive.ts

@@ -6,13 +6,13 @@ import { ArgumentError } from "../errors/argument-error";
 import type { PrimitiveTypeMap, PrimitiveTypeStr } from "../common.types";
 
 /**
- * 값에서 PrimitiveTypeStr 추론
+ * Infer PrimitiveTypeStr from a value
  *
- * 런타임에서 값의 타입을 검사하여 해당하는 PrimitiveTypeStr을 반환합니다.
+ * Checks the type of a value at runtime and returns the corresponding PrimitiveTypeStr.
  *
- * @param value 타입을 추론할 값
- * @returns 값에 해당하는 PrimitiveTypeStr
- * @throws ArgumentError 지원하지 않는 타입인 경우
+ * @param value The value to infer the type from
+ * @returns The PrimitiveTypeStr corresponding to the value
+ * @throws ArgumentError If the type is not supported
  *
  * @example
  * getPrimitiveTypeStr("hello") // "string"
@@ -29,5 +29,5 @@ export function getPrimitiveTypeStr(value: PrimitiveTypeMap[PrimitiveTypeStr]):
   if (value instanceof Time) return "Time";
   if (value instanceof Uuid) return "Uuid";
   if (value instanceof Uint8Array) return "Bytes";
-  throw new ArgumentError("알 수 없는 값 타입입니다.", { type: typeof value });
+  throw new ArgumentError("Unknown value type.", { type: typeof value });
 }

package/src/utils/str.ts

@@ -1,261 +1,260 @@
-/**
- * 문자열 유틸리티 함수
- */
-
-//#region 한글 조사 처리
-
-// 한글 조사 매핑 테이블 (모듈 로드 시 1회만 생성)
-const suffixTable = {
-  을: { t: "을", f: "를" },
-  은: { t: "은", f: "는" },
-  이: { t: "이", f: "가" },
-  와: { t: "과", f: "와" },
-  랑: { t: "이랑", f: "랑" },
-  로: { t: "으로", f: "로" },
-  라: { t: "이라", f: "라" },
-};
-
-/**
- * 한글 조사를 받침에 따라 적절히 반환
- * @param text 텍스트
- * @param type 조사 타입
- *   - `"을"`: 을/를
- *   - `"은"`: 은/는
- *   - `"이"`: 이/가
- *   - `"와"`: 과/와
- *   - `"랑"`: 이랑/랑
- *   - `"로"`: 으로/로
- *   - `"라"`: 이라/라
- *
- * @example
- * getSuffix("사과", "을") // "를"
- * getSuffix("책", "이") // "이"
- */
-export function strGetSuffix(
-  text: string,
-  type: "을" | "은" | "이" | "와" | "랑" | "로" | "라",
-): string {
-  const table = suffixTable;
-
-  // 빈 문자열 또는 마지막 글자가 한글이 아닌 경우 받침 없음으로 처리
-  if (text.length === 0) {
-    return table[type].f;
-  }
-
-  const lastCharCode = text.charCodeAt(text.length - 1);
-
-  // 한글 범위 체크 (0xAC00 ~ 0xD7A3)
-  if (lastCharCode < 0xac00 || lastCharCode > 0xd7a3) {
-    return table[type].f;
-  }
-
-  // 받침 존재 여부 및 종성 인덱스 계산
-  const jongseongIndex = (lastCharCode - 0xac00) % 28;
-  const hasLast = jongseongIndex !== 0;
-
-  // "로" 조사는 받침 ㄹ(종성 인덱스 8)일 때 "로"로 처리
-  if (type === "로" && jongseongIndex === 8) {
-    return table[type].f;
-  }
-
-  return hasLast ? table[type].t : table[type].f;
-}
-
-//#endregion
-
-//#region 전각→반각 변환
-
-// 전각 → 반각 매핑 테이블 (모듈 로드 시 1회만 생성)
-const specialCharMap: Record<string, string> = {
-  "Ａ": "A",
-  "Ｂ": "B",
-  "Ｃ": "C",
-  "Ｄ": "D",
-  "Ｅ": "E",
-  "Ｆ": "F",
-  "Ｇ": "G",
-  "Ｈ": "H",
-  "Ｉ": "I",
-  "Ｊ": "J",
-  "Ｋ": "K",
-  "Ｌ": "L",
-  "Ｍ": "M",
-  "Ｎ": "N",
-  "Ｏ": "O",
-  "Ｐ": "P",
-  "Ｑ": "Q",
-  "Ｒ": "R",
-  "Ｓ": "S",
-  "Ｔ": "T",
-  "Ｕ": "U",
-  "Ｖ": "V",
-  "Ｗ": "W",
-  "Ｘ": "X",
-  "Ｙ": "Y",
-  "Ｚ": "Z",
-  "ａ": "a",
-  "ｂ": "b",
-  "ｃ": "c",
-  "ｄ": "d",
-  "ｅ": "e",
-  "ｆ": "f",
-  "ｇ": "g",
-  "ｈ": "h",
-  "ｉ": "i",
-  "ｊ": "j",
-  "ｋ": "k",
-  "ｌ": "l",
-  "ｍ": "m",
-  "ｎ": "n",
-  "ｏ": "o",
-  "ｐ": "p",
-  "ｑ": "q",
-  "ｒ": "r",
-  "ｓ": "s",
-  "ｔ": "t",
-  "ｕ": "u",
-  "ｖ": "v",
-  "ｗ": "w",
-  "ｘ": "x",
-  "ｙ": "y",
-  "ｚ": "z",
-  "０": "0",
-  "１": "1",
-  "２": "2",
-  "３": "3",
-  "４": "4",
-  "５": "5",
-  "６": "6",
-  "７": "7",
-  "８": "8",
-  "９": "9",
-  "　": " ",
-  "）": ")",
-  "（": "(",
-};
-
-// 정규식도 1회만 생성
-const specialCharRegex = new RegExp(`[${Object.keys(specialCharMap).join("")}]`, "g");
-
-/**
- * 전각(Full-width) 문자를 반각(Half-width) 문자로 변환
- *
- * 변환 대상:
- * - 전각 영문 대문자 (Ａ-Ｚ → A-Z)
- * - 전각 영문 소문자 (ａ-ｚ → a-z)
- * - 전각 숫자 (０-９ → 0-9)
- * - 전각 공백 (　 → 일반 공백)
- * - 전각 괄호 (（） → ())
- *
- * @example
- * replaceSpecialDefaultChar("Ａ１２３") // "A123"
- * replaceSpecialDefaultChar("（株）") // "(株)"
- */
-export function strReplaceFullWidth(str: string): string {
-  return str.replace(specialCharRegex, (char) => specialCharMap[char] ?? char);
-}
-
-//#endregion
-
-//#region 케이스 변환
-
-/**
- * PascalCase로 변환
- * @example "hello-world" → "HelloWorld"
- * @example "hello_world" → "HelloWorld"
- * @example "hello.world" → "HelloWorld"
- */
-export function strToPascalCase(str: string): string {
-  return str
-    .replace(/[-._][a-z]/g, (m) => m[1].toUpperCase())
-    .replace(/^[a-z]/, (m) => m.toUpperCase());
-}
-
-/**
- * camelCase로 변환
- * @example "hello-world" → "helloWorld"
- * @example "hello_world" → "helloWorld"
- * @example "HelloWorld" → "helloWorld"
- */
-export function strToCamelCase(str: string): string {
-  return str
-    .replace(/[-._][a-z]/g, (m) => m[1].toUpperCase())
-    .replace(/^[A-Z]/, (m) => m.toLowerCase());
-}
-
-/**
- * kebab-case로 변환
- *
- * @example "HelloWorld" → "hello-world"
- * @example "helloWorld" → "hello-world"
- * @example "hello_world" → "hello_world" (소문자만 있으면 변환 안됨)
- * @example "Hello_World" → "hello-_world" (기존 분리자는 유지됨)
- * @example "Hello-World" → "hello--world" (기존 분리자는 유지됨)
- * @example "XMLParser" → "x-m-l-parser" (연속된 대문자는 각각 분리됨)
- */
-export function strToKebabCase(str: string): string {
-  return toCaseWithSeparator(str, "-");
-}
-
-/**
- * snake_case로 변환
- *
- * @example "HelloWorld" → "hello_world"
- * @example "helloWorld" → "hello_world"
- * @example "hello-world" → "hello-world" (소문자만 있으면 변환 안됨)
- * @example "Hello-World" → "hello_-world" (기존 분리자는 유지됨)
- * @example "Hello_World" → "hello__world" (기존 분리자는 유지됨)
- * @example "XMLParser" → "x_m_l_parser" (연속된 대문자는 각각 분리됨)
- */
-export function strToSnakeCase(str: string): string {
-  return toCaseWithSeparator(str, "_");
-}
-
-function toCaseWithSeparator(str: string, separator: string): string {
-  return str
-    .replace(/^[A-Z]/, (m) => m.toLowerCase())
-    .replace(/[-_]?[A-Z]/g, (m) => separator + m.toLowerCase());
-}
-
-//#endregion
-
-//#region 기타
-
-/**
- * undefined 또는 빈 문자열 여부 체크 (타입 가드)
- *
- * @param str 체크할 문자열
- * @returns undefined, null, 빈 문자열이면 true
- *
- * @example
- * const name: string | undefined = getValue();
- * if (strIsNullOrEmpty(name)) {
- *   // name: "" | undefined
- *   console.log("이름이 비어있습니다");
- * } else {
- *   // name: string (비어있지 않은 문자열)
- *   console.log(`이름: ${name}`);
- * }
- */
-export function strIsNullOrEmpty(str: string | undefined): str is "" | undefined {
-  return str == null || str === "";
-}
-
-/**
- * 문자열 특정 위치에 삽입
- *
- * @param str 원본 문자열
- * @param index 삽입할 위치 (0부터 시작)
- * @param insertString 삽입할 문자열
- * @returns 삽입된 새 문자열
- *
- * @example
- * strInsert("Hello World", 5, ","); // "Hello, World"
- * strInsert("abc", 0, "X"); // "Xabc"
- * strInsert("abc", 3, "X"); // "abcX"
- */
-export function strInsert(str: string, index: number, insertString: string): string {
-  return str.substring(0, index) + insertString + str.substring(index);
-}
-
-//#endregion
+/**
+ * String utility functions
+ */
+
+//#region Korean particle handling
+
+// Korean particle mapping table (created only once when module loads)
+const suffixTable = {
+  을: { t: "을", f: "를" },
+  은: { t: "은", f: "는" },
+  이: { t: "이", f: "가" },
+  와: { t: "과", f: "와" },
+  랑: { t: "이랑", f: "랑" },
+  로: { t: "으로", f: "로" },
+  라: { t: "이라", f: "라" },
+};
+
+/**
+ * Return the appropriate Korean particle based on the final consonant
+ * @param text The text to check
+ * @param type The particle type
+ *   - `"을"`: 을/를 (eul/reul - object particle)
+ *   - `"은"`: 은/는 (eun/neun - subject particle)
+ *   - `"이"`: 이/가 (i/ga - subject particle)
+ *   - `"와"`: 과/와 (gwa/wa - and particle)
+ *   - `"랑"`: 이랑/랑 (irang/rang - and particle)
+ *   - `"로"`: 으로/로 (euro/ro - instrumental particle)
+ *   - `"라"`: 이라/라 (ira/ra - copula particle)
+ *
+ * @example
+ * koreanGetSuffix("Apple", "을") // "를"
+ * koreanGetSuffix("책", "이") // "이"
+ */
+export function koreanGetSuffix(
+  text: string,
+  type: "을" | "은" | "이" | "와" | "랑" | "로" | "라",
+): string {
+  const table = suffixTable;
+
+  if (text.length === 0) {
+    return table[type].f;
+  }
+
+  const lastCharCode = text.charCodeAt(text.length - 1);
+
+  // Hangul range check (0xAC00 ~ 0xD7A3)
+  if (lastCharCode < 0xac00 || lastCharCode > 0xd7a3) {
+    return table[type].f;
+  }
+
+  // Determine if final consonant (jongseong) exists
+  const jongseongIndex = (lastCharCode - 0xac00) % 28;
+  const hasLast = jongseongIndex !== 0;
+
+  // Special handling for "로" particle: when final consonant is ㄹ (jongseong index 8), use "로"
+  if (type === "로" && jongseongIndex === 8) {
+    return table[type].f;
+  }
+
+  return hasLast ? table[type].t : table[type].f;
+}
+
+//#endregion
+
+//#region Full-width to half-width conversion
+
+// Full-width to half-width mapping table (created only once when module loads)
+const fullWidthCharMap: Record<string, string> = {
+  "Ａ": "A",
+  "Ｂ": "B",
+  "Ｃ": "C",
+  "Ｄ": "D",
+  "Ｅ": "E",
+  "Ｆ": "F",
+  "Ｇ": "G",
+  "Ｈ": "H",
+  "Ｉ": "I",
+  "Ｊ": "J",
+  "Ｋ": "K",
+  "Ｌ": "L",
+  "Ｍ": "M",
+  "Ｎ": "N",
+  "Ｏ": "O",
+  "Ｐ": "P",
+  "Ｑ": "Q",
+  "Ｒ": "R",
+  "Ｓ": "S",
+  "Ｔ": "T",
+  "Ｕ": "U",
+  "Ｖ": "V",
+  "Ｗ": "W",
+  "Ｘ": "X",
+  "Ｙ": "Y",
+  "Ｚ": "Z",
+  "ａ": "a",
+  "ｂ": "b",
+  "ｃ": "c",
+  "ｄ": "d",
+  "ｅ": "e",
+  "ｆ": "f",
+  "ｇ": "g",
+  "ｈ": "h",
+  "ｉ": "i",
+  "ｊ": "j",
+  "ｋ": "k",
+  "ｌ": "l",
+  "ｍ": "m",
+  "ｎ": "n",
+  "ｏ": "o",
+  "ｐ": "p",
+  "ｑ": "q",
+  "ｒ": "r",
+  "ｓ": "s",
+  "ｔ": "t",
+  "ｕ": "u",
+  "ｖ": "v",
+  "ｗ": "w",
+  "ｘ": "x",
+  "ｙ": "y",
+  "ｚ": "z",
+  "０": "0",
+  "１": "1",
+  "２": "2",
+  "３": "3",
+  "４": "4",
+  "５": "5",
+  "６": "6",
+  "７": "7",
+  "８": "8",
+  "９": "9",
+  "　": " ",
+  "）": ")",
+  "（": "(",
+};
+
+// Regex also created only once
+const fullWidthCharRegex = new RegExp(`[${Object.keys(fullWidthCharMap).join("")}]`, "g");
+
+/**
+ * Convert full-width characters to half-width characters
+ *
+ * Conversion targets:
+ * - Full-width uppercase letters (Ａ-Ｚ → A-Z)
+ * - Full-width lowercase letters (ａ-ｚ → a-z)
+ * - Full-width digits (０-９ → 0-9)
+ * - Full-width space (　 → regular space)
+ * - Full-width parentheses (（） → ())
+ *
+ * @example
+ * strReplaceFullWidth("Ａ１２３") // "A123"
+ * strReplaceFullWidth("（株）") // "(株)"
+ */
+export function strReplaceFullWidth(str: string): string {
+  return str.replace(fullWidthCharRegex, (char) => fullWidthCharMap[char] ?? char);
+}
+
+//#endregion
+
+//#region Case conversion
+
+/**
+ * Convert to PascalCase
+ * @example "hello-world" → "HelloWorld"
+ * @example "hello_world" → "HelloWorld"
+ * @example "hello.world" → "HelloWorld"
+ */
+export function strToPascalCase(str: string): string {
+  return str
+    .replace(/[-._][a-z]/g, (m) => m[1].toUpperCase())
+    .replace(/^[a-z]/, (m) => m.toUpperCase());
+}
+
+/**
+ * Convert to camelCase
+ * @example "hello-world" → "helloWorld"
+ * @example "hello_world" → "helloWorld"
+ * @example "HelloWorld" → "helloWorld"
+ */
+export function strToCamelCase(str: string): string {
+  return str
+    .replace(/[-._][a-z]/g, (m) => m[1].toUpperCase())
+    .replace(/^[A-Z]/, (m) => m.toLowerCase());
+}
+
+/**
+ * Convert to kebab-case
+ *
+ * @example "HelloWorld" → "hello-world"
+ * @example "helloWorld" → "hello-world"
+ * @example "hello_world" → "hello_world" (no conversion if only lowercase)
+ * @example "Hello_World" → "hello-_world" (existing separators are preserved)
+ * @example "Hello-World" → "hello--world" (existing separators are preserved)
+ * @example "XMLParser" → "x-m-l-parser" (consecutive uppercase letters are separated)
+ */
+export function strToKebabCase(str: string): string {
+  return toCaseWithSeparator(str, "-");
+}
+
+/**
+ * Convert to snake_case
+ *
+ * @example "HelloWorld" → "hello_world"
+ * @example "helloWorld" → "hello_world"
+ * @example "hello-world" → "hello-world" (no conversion if only lowercase)
+ * @example "Hello-World" → "hello_-world" (existing separators are preserved)
+ * @example "Hello_World" → "hello__world" (existing separators are preserved)
+ * @example "XMLParser" → "x_m_l_parser" (consecutive uppercase letters are separated)
+ */
+export function strToSnakeCase(str: string): string {
+  return toCaseWithSeparator(str, "_");
+}
+
+function toCaseWithSeparator(str: string, separator: string): string {
+  return str
+    .replace(/^[A-Z]/, (m) => m.toLowerCase())
+    .replace(/[-_]?[A-Z]/g, (m) => separator + m.toLowerCase());
+}
+
+//#endregion
+
+//#region Other
+
+/**
+ * Check if string is undefined or empty (type guard)
+ *
+ * @param str The string to check
+ * @returns true if undefined, null, or empty string
+ *
+ * @example
+ * const name: string | undefined = getValue();
+ * if (strIsNullOrEmpty(name)) {
+ *   // name: "" | undefined
+ *   console.log("Name is empty");
+ * } else {
+ *   // name: string (non-empty string)
+ *   console.log(`Name: ${name}`);
+ * }
+ */
+export function strIsNullOrEmpty(str: string | undefined): str is "" | undefined {
+  return str == null || str === "";
+}
+
+/**
+ * Insert a string at a specific position
+ *
+ * @param str The original string
+ * @param index The position to insert at (0-based)
+ * @param insertString The string to insert
+ * @returns A new string with the insertion applied
+ *
+ * @example
+ * strInsert("Hello World", 5, ","); // "Hello, World"
+ * strInsert("abc", 0, "X"); // "Xabc"
+ * strInsert("abc", 3, "X"); // "abcX"
+ */
+export function strInsert(str: string, index: number, insertString: string): string {
+  return str.substring(0, index) + insertString + str.substring(index);
+}
+
+//#endregion