@simplysm/core-common 13.0.100 → 14.0.4

package/src/utils/primitive.ts

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

package/src/utils/str.ts

@@ -1,10 +1,10 @@
 /**
- * String utility functions
+ * 문자열 유틸리티 함수
  */
 
-//#region Korean particle handling
+//#region 한국어 조사 처리
 
-// Korean particle mapping table (created only once when module loads)
+// 한국어 조사 매핑 테이블 (모듈 로드 시 한 번만 생성)
 const suffixTable = {
   을: { t: "을", f: "를" },
   은: { t: "은", f: "는" },
@@ -16,16 +16,16 @@ const suffixTable = {
 };
 
 /**
- * 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)
+ * 받침 유무에 따라 적절한 한국어 조사 반환
+ * @param text 확인할 텍스트
+ * @param type 조사 타입
+ *   - `"을"`: 을/를 (목적격 조사)
+ *   - `"은"`: 은/는 (주격 보조사)
+ *   - `"이"`: 이/가 (주격 조사)
+ *   - `"와"`: 과/와 (접속 조사)
+ *   - `"랑"`: 이랑/랑 (접속 조사)
+ *   - `"로"`: 으로/로 (도구격 조사)
+ *   - `"라"`: 이라/라 (서술격 조사)
  *
  * @example
  * getKoreanSuffix("Apple", "을") // "를"
@@ -43,16 +43,16 @@ export function getKoreanSuffix(
 
   const lastCharCode = text.charCodeAt(text.length - 1);
 
-  // Hangul range check (0xAC00 ~ 0xD7A3)
+  // 한글 범위 확인 (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 "로"
+  // "로" 조사 특수 처리: 받침이 ㄹ (종성 인덱스 8)이면 "로" 사용
   if (type === "로" && jongseongIndex === 8) {
     return table[type].f;
   }
@@ -62,9 +62,9 @@ export function getKoreanSuffix(
 
 //#endregion
 
-//#region Full-width to half-width conversion
+//#region 전각 → 반각 변환
 
-// Full-width to half-width mapping table (created only once when module loads)
+// 전각 → 반각 매핑 테이블 (모듈 로드 시 한 번만 생성)
 const fullWidthCharMap: Record<string, string> = {
   "Ａ": "A",
   "Ｂ": "B",
@@ -133,18 +133,18 @@ const fullWidthCharMap: Record<string, string> = {
   "（": "(",
 };
 
-// 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 (（） → ())
+ * 변환 대상:
+ * - 전각 대문자 (Ａ-Ｚ → A-Z)
+ * - 전각 소문자 (ａ-ｚ → a-z)
+ * - 전각 숫자 (０-９ → 0-9)
+ * - 전각 공백 (　 → 일반 공백)
+ * - 전각 괄호 (（） → ())
  *
  * @example
  * replaceFullWidth("Ａ１２３") // "A123"
@@ -156,10 +156,10 @@ export function replaceFullWidth(str: string): string {
 
 //#endregion
 
-//#region Case conversion
+//#region 대소문자 변환
 
 /**
- * Convert to PascalCase
+ * PascalCase로 변환
  * @example "hello-world" → "HelloWorld"
  * @example "hello_world" → "HelloWorld"
  * @example "hello.world" → "HelloWorld"
@@ -171,7 +171,7 @@ export function toPascalCase(str: string): string {
 }
 
 /**
- * Convert to camelCase
+ * camelCase로 변환
  * @example "hello-world" → "helloWorld"
  * @example "hello_world" → "helloWorld"
  * @example "HelloWorld" → "helloWorld"
@@ -183,28 +183,28 @@ export function toCamelCase(str: string): string {
 }
 
 /**
- * Convert to kebab-case
+ * 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)
+ * @example "hello_world" → "hello_world" (소문자만이면 변환 없음)
+ * @example "Hello_World" → "hello-_world" (기존 구분자 유지)
+ * @example "Hello-World" → "hello--world" (기존 구분자 유지)
+ * @example "XMLParser" → "x-m-l-parser" (연속 대문자 분리)
  */
 export function toKebabCase(str: string): string {
   return toCaseWithSeparator(str, "-");
 }
 
 /**
- * Convert to snake_case
+ * 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)
+ * @example "hello-world" → "hello-world" (소문자만이면 변환 없음)
+ * @example "Hello-World" → "hello_-world" (기존 구분자 유지)
+ * @example "Hello_World" → "hello__world" (기존 구분자 유지)
+ * @example "XMLParser" → "x_m_l_parser" (연속 대문자 분리)
  */
 export function toSnakeCase(str: string): string {
   return toCaseWithSeparator(str, "_");
@@ -218,13 +218,13 @@ function toCaseWithSeparator(str: string, separator: string): string {
 
 //#endregion
 
-//#region Other
+//#region 기타
 
 /**
- * Check if string is undefined or empty (type guard)
+ * 문자열이 undefined 또는 빈 문자열인지 검사 (타입 가드)
  *
- * @param str The string to check
- * @returns true if undefined, null, or empty string
+ * @param str 검사할 문자열
+ * @returns undefined, null, 또는 빈 문자열이면 true
  *
  * @example
  * const name: string | undefined = getValue();
@@ -241,12 +241,12 @@ export function isNullOrEmpty(str: string | undefined): str is "" | undefined {
 }
 
 /**
- * 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
+ * @param str 원본 문자열
+ * @param index 삽입할 위치 (0부터 시작)
+ * @param insertString 삽입할 문자열
+ * @returns 삽입이 적용된 새 문자열
  *
  * @example
  * insert("Hello World", 5, ","); // "Hello, World"

package/src/utils/template-strings.ts

@@ -1,13 +1,13 @@
 /**
- * Template string tag functions
- * For IDE code highlighting support (actual behavior is string concatenation + indent normalization)
+ * 템플릿 문자열 태그 함수
+ * IDE 코드 하이라이팅 지원용 (실제 동작은 문자열 결합 + 들여쓰기 정규화)
  */
 
 /**
- * Template tag for JavaScript code highlighting
- * @param strings Template string array
- * @param values Interpolated values
- * @returns String with normalized indentation
+ * JavaScript 코드 하이라이팅용 템플릿 태그
+ * @param strings 템플릿 문자열 배열
+ * @param values 보간된 값들
+ * @returns 들여쓰기가 정규화된 문자열
  * @example
  * const code = js`
  *   function hello() {
@@ -20,10 +20,10 @@ export function js(strings: TemplateStringsArray, ...values: unknown[]): string
 }
 
 /**
- * Template tag for TypeScript code highlighting
- * @param strings Template string array
- * @param values Interpolated values
- * @returns String with normalized indentation
+ * TypeScript 코드 하이라이팅용 템플릿 태그
+ * @param strings 템플릿 문자열 배열
+ * @param values 보간된 값들
+ * @returns 들여쓰기가 정규화된 문자열
  * @example
  * const code = ts`
  *   interface User {
@@ -37,10 +37,10 @@ export function ts(strings: TemplateStringsArray, ...values: unknown[]): string
 }
 
 /**
- * Template tag for HTML markup highlighting
- * @param strings Template string array
- * @param values Interpolated values
- * @returns String with normalized indentation
+ * HTML 마크업 하이라이팅용 템플릿 태그
+ * @param strings 템플릿 문자열 배열
+ * @param values 보간된 값들
+ * @returns 들여쓰기가 정규화된 문자열
  * @example
  * const markup = html`
  *   <div class="container">
@@ -53,10 +53,10 @@ export function html(strings: TemplateStringsArray, ...values: unknown[]): strin
 }
 
 /**
- * Template tag for MSSQL T-SQL highlighting
- * @param strings Template string array
- * @param values Interpolated values
- * @returns String with normalized indentation
+ * MSSQL T-SQL 하이라이팅용 템플릿 태그
+ * @param strings 템플릿 문자열 배열
+ * @param values 보간된 값들
+ * @returns 들여쓰기가 정규화된 문자열
  * @example
  * const query = tsql`
  *   SELECT TOP 10 *
@@ -69,10 +69,10 @@ export function tsql(strings: TemplateStringsArray, ...values: unknown[]): strin
 }
 
 /**
- * Template tag for MySQL SQL highlighting
- * @param strings Template string array
- * @param values Interpolated values
- * @returns String with normalized indentation
+ * MySQL SQL 하이라이팅용 템플릿 태그
+ * @param strings 템플릿 문자열 배열
+ * @param values 보간된 값들
+ * @returns 들여쓰기가 정규화된 문자열
  * @example
  * const query = mysql`
  *   SELECT *
@@ -85,10 +85,10 @@ export function mysql(strings: TemplateStringsArray, ...values: unknown[]): stri
 }
 
 /**
- * Template tag for PostgreSQL SQL highlighting
- * @param strings Template string array
- * @param values Interpolated values
- * @returns String with normalized indentation
+ * PostgreSQL SQL 하이라이팅용 템플릿 태그
+ * @param strings 템플릿 문자열 배열
+ * @param values 보간된 값들
+ * @returns 들여쓰기가 정규화된 문자열
  * @example
  * const query = pgsql`
  *   SELECT *
@@ -111,7 +111,7 @@ function _combine(strings: TemplateStringsArray, values: unknown[]): string {
 function _trimIndent(text: string): string {
   const lines = text.split("\n");
 
-  // Remove leading and trailing empty lines (remove all consecutive empty lines)
+  // 앞뒤 빈 줄 제거 (연속된 빈 줄 모두 제거)
   while (lines.length > 0 && lines[0].trim() === "") {
     lines.shift();
   }
@@ -119,7 +119,7 @@ function _trimIndent(text: string): string {
     lines.pop();
   }
 
-  // Calculate minimum indentation
+  // 최소 들여쓰기 계산
   const minIndent = lines
     .filter((line) => line.trim() !== "")
     .reduce((min, line) => {
@@ -127,6 +127,6 @@ function _trimIndent(text: string): string {
       return Math.min(min, indent);
     }, Infinity);
 
-  // Remove indentation
+  // 들여쓰기 제거
   return lines.map((line) => (line.trim() === "" ? "" : line.slice(minIndent))).join("\n");
 }

package/src/utils/transferable.ts

@@ -4,44 +4,44 @@ import { Time } from "../types/time";
 import { Uuid } from "../types/uuid";
 
 /**
- * Object types that can be transferred between Workers
+ * Worker 간 전송 가능한 객체 타입
  *
- * Only ArrayBuffer is used in this code.
+ * 이 코드에서는 ArrayBuffer만 사용됨.
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects
  */
 type Transferable = ArrayBuffer;
 
 /**
- * Transferable conversion utility functions
+ * Transferable 변환 유틸리티 함수
  *
- * Performs serialization/deserialization for data transfer between Workers.
- * Handles custom types that structuredClone does not support.
+ * Worker 간 데이터 전송을 위한 직렬화/역직렬화 수행.
+ * structuredClone이 지원하지 않는 커스텀 타입을 처리.
  *
- * Supported types:
+ * 지원 타입:
  * - Date, DateTime, DateOnly, Time, Uuid, RegExp
- * - Error (including cause, code, detail)
- * - Uint8Array (other TypedArrays not supported, handled as plain objects)
- * - Array, Map, Set, plain objects
+ * - Error (cause, code, detail 포함)
+ * - Uint8Array (다른 TypedArray는 지원하지 않으며 일반 객체로 처리)
+ * - Array, Map, Set, 일반 객체
  *
- * @note Circular references cause TypeError in transferableEncode (includes path info)
- * @note If the same object is referenced from multiple places, the cached encoding result is reused
+ * @note 순환 참조 시 transferableEncode에서 TypeError 발생 (경로 정보 포함)
+ * @note 같은 객체가 여러 곳에서 참조되면 캐싱된 인코딩 결과를 재사용
  *
  * @example
- * // Send data to Worker
+ * // Worker로 데이터 전송
  * const { result, transferList } = transferableEncode(data);
  * worker.postMessage(result, transferList);
  *
- * // Receive data from Worker
+ * // Worker에서 데이터 수신
  * const decoded = decode(event.data);
  */
 
 //#region encode
 
 /**
- * Convert objects using Simplysm types to plain objects
- * Serializes in a form that can be sent to a Worker
+ * Simplysm 타입을 사용하는 객체를 일반 객체로 변환
+ * Worker로 전송 가능한 형태로 직렬화
  *
- * @throws TypeError if circular reference is detected
+ * @throws TypeError 순환 참조가 감지된 경우
  */
 export function encode(obj: unknown): {
   result: unknown;
@@ -63,19 +63,19 @@ function encodeImpl(
 ): unknown {
   if (obj == null) return obj;
 
-  // Object type processing: circular reference detection + cache
+  // 객체 타입 처리: 순환 참조 감지 + 캐시
   if (typeof obj === "object") {
-    // Circular reference detection (object in current recursion stack)
+    // 순환 참조 감지 (현재 재귀 스택에 있는 객체)
     if (ancestors.has(obj)) {
       const currentPath = path.length > 0 ? path.join(".") : "root";
-      throw new TypeError(`Circular reference detected: ${currentPath}`);
+      throw new TypeError(`순환 참조 감지됨: ${currentPath}`);
     }
 
-    // If object was already encoded, reuse cached result
+    // 이미 인코딩된 객체이면 캐싱된 결과 재사용
     const cached = cache.get(obj);
     if (cached !== undefined) return cached;
 
-    // Add to recursion stack
+    // 재귀 스택에 추가
     ancestors.add(obj);
   }
 
@@ -84,8 +84,8 @@ function encodeImpl(
   try {
     // 1. Uint8Array
     if (obj instanceof Uint8Array) {
-      // SharedArrayBuffer is already shared memory, so don't add to transferList
-      // Add only ArrayBuffer to transferList for zero-copy transfer
+      // SharedArrayBuffer는 이미 공유 메모리이므로 transferList에 추가하지 않음
+      // zero-copy 전송을 위해 ArrayBuffer만 transferList에 추가
       const isSharedArrayBuffer =
         typeof SharedArrayBuffer !== "undefined" && obj.buffer instanceof SharedArrayBuffer;
       const buffer = obj.buffer as ArrayBuffer;
@@ -94,7 +94,7 @@ function encodeImpl(
       }
       result = obj;
     }
-    // 2. Special type conversion (convert to tagged object without JSON.stringify)
+    // 2. 특수 타입 변환 (JSON.stringify 없이 태그된 객체로 변환)
     else if (obj instanceof Date) {
       result = { __type__: "Date", data: obj.getTime() };
     } else if (obj instanceof DateTime) {
@@ -138,13 +138,13 @@ function encodeImpl(
         },
       };
     }
-    // 3. Array recursion
+    // 3. Array 재귀
     else if (Array.isArray(obj)) {
       result = obj.map((item, idx) =>
         encodeImpl(item, transferList, [...path, idx], ancestors, cache),
       );
     }
-    // 4. Map recursion
+    // 4. Map 재귀
     else if (obj instanceof Map) {
       let idx = 0;
       result = new Map(
@@ -159,7 +159,7 @@ function encodeImpl(
         }),
       );
     }
-    // 5. Set recursion
+    // 5. Set 재귀
     else if (obj instanceof Set) {
       let idx = 0;
       result = new Set(
@@ -168,7 +168,7 @@ function encodeImpl(
         ),
       );
     }
-    // 6. Plain object recursion
+    // 6. 일반 객체 재귀
     else if (typeof obj === "object") {
       const res: Record<string, unknown> = {};
       const record = obj as Record<string, unknown>;
@@ -177,19 +177,19 @@ function encodeImpl(
       }
       result = res;
     }
-    // 7. Primitive types
+    // 7. 원시 타입
     else {
       return obj;
     }
 
-    // Save to cache (only on success)
+    // 캐시에 저장 (성공 시에만)
     if (typeof obj === "object") {
       cache.set(obj, result);
     }
 
     return result;
   } finally {
-    // Remove from recursion stack (must execute even on exception)
+    // 재귀 스택에서 제거 (예외 발생 시에도 반드시 실행)
     if (typeof obj === "object") {
       ancestors.delete(obj);
     }
@@ -201,13 +201,13 @@ function encodeImpl(
 //#region decode
 
 /**
- * Convert serialized objects to objects using Simplysm types
- * Deserialize data received from a Worker
+ * 직렬화된 객체를 Simplysm 타입을 사용하는 객체로 변환
+ * Worker에서 수신한 데이터 역직렬화
  */
 export function decode(obj: unknown): unknown {
   if (obj == null) return obj;
 
-  // 1. Restore special types from tagged objects
+  // 1. 태그된 객체에서 특수 타입 복원
   if (typeof obj === "object" && "__type__" in obj && "data" in obj) {
     const typed = obj as { __type__: string; data: unknown };
     const data = typed.data;
@@ -245,12 +245,12 @@ export function decode(obj: unknown): unknown {
     }
   }
 
-  // 2. Array recursion
+  // 2. Array 재귀
   if (Array.isArray(obj)) {
     return obj.map((item) => decode(item));
   }
 
-  // 3. Map recursion
+  // 3. Map 재귀
   if (obj instanceof Map) {
     const newMap = new Map<unknown, unknown>();
     for (const [k, v] of obj) {
@@ -259,7 +259,7 @@ export function decode(obj: unknown): unknown {
     return newMap;
   }
 
-  // 4. Set recursion
+  // 4. Set 재귀
   if (obj instanceof Set) {
     const newSet = new Set<unknown>();
     for (const v of obj) {
@@ -268,7 +268,7 @@ export function decode(obj: unknown): unknown {
     return newSet;
   }
 
-  // 5. Object recursion
+  // 5. 객체 재귀
   if (typeof obj === "object") {
     const record = obj as Record<string, unknown>;
     const result: Record<string, unknown> = {};

package/src/utils/wait.ts

@@ -1,19 +1,19 @@
 /**
- * Wait utility functions
+ * 대기 유틸리티 함수
  */
 import { TimeoutError } from "../errors/timeout-error";
 
 /**
- * Wait until a condition becomes true
- * @param forwarder Condition function
- * @param milliseconds Check interval (default: 100ms)
- * @param maxCount Maximum number of attempts (undefined for unlimited)
+ * 조건이 true가 될 때까지 대기
+ * @param forwarder 조건 함수
+ * @param milliseconds 확인 간격 (기본값: 100ms)
+ * @param maxCount 최대 시도 횟수 (undefined이면 무제한)
  *
- * @note Returns immediately if the condition is true on the first call.
+ * @note 첫 번째 호출에서 조건이 true이면 즉시 반환.
  * @example
- * // maxCount=3: checks condition up to 3 times, throws TimeoutError if all are false
+ * // maxCount=3: 최대 3번 조건 확인, 모두 false이면 TimeoutError 발생
  * await waitUntil(() => someCondition, 100, 3);
- * @throws TimeoutError when maximum number of attempts is exceeded
+ * @throws TimeoutError 최대 시도 횟수를 초과했을 때
  */
 export async function until(
   forwarder: () => boolean | Promise<boolean>,
@@ -32,8 +32,8 @@ export async function until(
 }
 
 /**
- * Wait for a specified amount of time
- * @param millisecond Wait time (ms)
+ * 지정된 시간만큼 대기
+ * @param millisecond 대기 시간 (ms)
  */
 export async function time(millisecond: number): Promise<void> {
   return new Promise<void>((resolve) => setTimeout(resolve, millisecond));