@simplysm/core-common 13.0.0-beta.1

package/src/utils/path.ts

@@ -0,0 +1,40 @@
+/**
+ * 경로 유틸리티 함수
+ * Node.js path 모듈 대체용 (브라우저 환경 지원)
+ *
+ * @note 이 유틸리티는 POSIX 스타일 경로(슬래시 `/`)만 지원합니다.
+ *       Windows 백슬래시(`\`) 경로는 지원하지 않습니다.
+ *       브라우저 환경 및 Capacitor 플러그인용으로 설계되었습니다.
+ */
+
+/**
+ * 경로 조합 (path.join 대체)
+ * @note POSIX 스타일 경로만 지원 (슬래시 `/`)
+ */
+export function pathJoin(...segments: string[]): string {
+  return segments
+    .map((s, i) => (i === 0 ? s.replace(/\/+$/, "") : s.replace(/^\/+|\/+$/g, "")))
+    .filter(Boolean)
+    .join("/");
+}
+
+/**
+ * 파일명 추출 (path.basename 대체)
+ */
+export function pathBasename(filePath: string, ext?: string): string {
+  const name = filePath.split("/").pop() ?? "";
+  if (ext != null && ext !== "" && name.endsWith(ext)) {
+    return name.slice(0, -ext.length);
+  }
+  return name;
+}
+
+/**
+ * 확장자 추출 (path.extname 대체)
+ * @note 숨김 파일(예: `.gitignore`)은 빈 문자열을 반환합니다 (Node.js path.extname과 동일)
+ */
+export function pathExtname(filePath: string): string {
+  const name = filePath.split("/").pop() ?? "";
+  const dotIndex = name.lastIndexOf(".");
+  return dotIndex > 0 ? name.slice(dotIndex) : "";
+}

package/src/utils/primitive.ts

@@ -0,0 +1,33 @@
+import { DateTime } from "../types/date-time";
+import { DateOnly } from "../types/date-only";
+import { Time } from "../types/time";
+import { Uuid } from "../types/uuid";
+import { ArgumentError } from "../errors/argument-error";
+import type { PrimitiveTypeMap, PrimitiveTypeStr } from "../common.types";
+
+/**
+ * 값에서 PrimitiveTypeStr 추론
+ *
+ * 런타임에서 값의 타입을 검사하여 해당하는 PrimitiveTypeStr을 반환합니다.
+ *
+ * @param value 타입을 추론할 값
+ * @returns 값에 해당하는 PrimitiveTypeStr
+ * @throws ArgumentError 지원하지 않는 타입인 경우
+ *
+ * @example
+ * getPrimitiveTypeStr("hello") // "string"
+ * getPrimitiveTypeStr(123) // "number"
+ * getPrimitiveTypeStr(new DateTime()) // "DateTime"
+ * getPrimitiveTypeStr(new Uint8Array()) // "Bytes"
+ */
+export function getPrimitiveTypeStr(value: PrimitiveTypeMap[PrimitiveTypeStr]): PrimitiveTypeStr {
+  if (typeof value === "string") return "string";
+  if (typeof value === "number") return "number";
+  if (typeof value === "boolean") return "boolean";
+  if (value instanceof DateTime) return "DateTime";
+  if (value instanceof DateOnly) return "DateOnly";
+  if (value instanceof Time) return "Time";
+  if (value instanceof Uuid) return "Uuid";
+  if (value instanceof Uint8Array) return "Bytes";
+  throw new ArgumentError("알 수 없는 값 타입입니다.", { type: typeof value });
+}

package/src/utils/str.ts

@@ -0,0 +1,252 @@
+/**
+ * 문자열 유틸리티 함수
+ */
+
+//#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

package/src/utils/template-strings.ts

@@ -0,0 +1,132 @@
+/**
+ * 템플릿 문자열 태그 함수들
+ * IDE 코드 하이라이팅 지원용 (실제 동작은 문자열 조합 + 들여쓰기 정리)
+ */
+
+/**
+ * JavaScript 코드 하이라이팅용 템플릿 태그
+ * @param strings 템플릿 문자열 배열
+ * @param values 보간된 값들
+ * @returns 들여쓰기가 정리된 문자열
+ * @example
+ * const code = js`
+ *   function hello() {
+ *     return "world";
+ *   }
+ * `;
+ */
+export function js(strings: TemplateStringsArray, ...values: unknown[]): string {
+  return _combine(strings, values);
+}
+
+/**
+ * TypeScript 코드 하이라이팅용 템플릿 태그
+ * @param strings 템플릿 문자열 배열
+ * @param values 보간된 값들
+ * @returns 들여쓰기가 정리된 문자열
+ * @example
+ * const code = ts`
+ *   interface User {
+ *     name: string;
+ *     age: number;
+ *   }
+ * `;
+ */
+export function ts(strings: TemplateStringsArray, ...values: unknown[]): string {
+  return _combine(strings, values);
+}
+
+/**
+ * HTML 마크업 하이라이팅용 템플릿 태그
+ * @param strings 템플릿 문자열 배열
+ * @param values 보간된 값들
+ * @returns 들여쓰기가 정리된 문자열
+ * @example
+ * const markup = html`
+ *   <div class="container">
+ *     <span>${name}</span>
+ *   </div>
+ * `;
+ */
+export function html(strings: TemplateStringsArray, ...values: unknown[]): string {
+  return _combine(strings, values);
+}
+
+/**
+ * MSSQL T-SQL 하이라이팅용 템플릿 태그
+ * @param strings 템플릿 문자열 배열
+ * @param values 보간된 값들
+ * @returns 들여쓰기가 정리된 문자열
+ * @example
+ * const query = tsql`
+ *   SELECT TOP 10 *
+ *   FROM Users
+ *   WHERE Name LIKE '%${keyword}%'
+ * `;
+ */
+export function tsql(strings: TemplateStringsArray, ...values: unknown[]): string {
+  return _combine(strings, values);
+}
+
+/**
+ * MySQL SQL 하이라이팅용 템플릿 태그
+ * @param strings 템플릿 문자열 배열
+ * @param values 보간된 값들
+ * @returns 들여쓰기가 정리된 문자열
+ * @example
+ * const query = mysql`
+ *   SELECT *
+ *   FROM users
+ *   LIMIT 10
+ * `;
+ */
+export function mysql(strings: TemplateStringsArray, ...values: unknown[]): string {
+  return _combine(strings, values);
+}
+
+/**
+ * PostgreSQL SQL 하이라이팅용 템플릿 태그
+ * @param strings 템플릿 문자열 배열
+ * @param values 보간된 값들
+ * @returns 들여쓰기가 정리된 문자열
+ * @example
+ * const query = pgsql`
+ *   SELECT *
+ *   FROM users
+ *   OFFSET 0 LIMIT 10
+ * `;
+ */
+export function pgsql(strings: TemplateStringsArray, ...values: unknown[]): string {
+  return _combine(strings, values);
+}
+
+function _combine(strings: TemplateStringsArray, values: unknown[]): string {
+  const raw = strings.reduce((result, str, i) => {
+    const value = values[i] !== undefined ? String(values[i]) : "";
+    return result + str + value;
+  }, "");
+  return _trimIndent(raw);
+}
+
+function _trimIndent(text: string): string {
+  const lines = text.split("\n");
+
+  // 첫/마지막 빈 줄 제거 (연속된 빈 줄 모두 제거)
+  while (lines.length > 0 && lines[0].trim() === "") {
+    lines.shift();
+  }
+  while (lines.length > 0 && lines[lines.length - 1].trim() === "") {
+    lines.pop();
+  }
+
+  // 최소 들여쓰기 계산
+  const minIndent = lines
+    .filter((line) => line.trim() !== "")
+    .reduce((min, line) => {
+      const indent = line.match(/^ */)?.[0].length ?? 0;
+      return Math.min(min, indent);
+    }, Infinity);
+
+  // 들여쓰기 제거
+  return lines.map((line) => (line.trim() === "" ? "" : line.slice(minIndent))).join("\n");
+}