@simplysm/core-common 13.0.100 → 14.0.4

package/src/utils/date-format.ts

@@ -1,5 +1,5 @@
 /**
- * Result of year/month/day normalization when setting month
+ * 월 설정 시 연/월/일 정규화 결과
  */
 export interface DtNormalizedMonth {
   year: number;
@@ -8,27 +8,27 @@ export interface DtNormalizedMonth {
 }
 
 /**
- * Normalize year/month/day when setting month
- * - Adjust year if month is outside 1-12 range
- * - Adjust to last day of target month if current day is greater than the number of days in the target month
+ * 월 설정 시 연/월/일 정규화
+ * - 월이 1-12 범위를 벗어나면 연도 조정
+ * - 현재 일이 대상 월의 일수보다 크면 해당 월의 마지막 일로 조정
  *
- * @param year Base year
- * @param month Month to set (values outside 1-12 range allowed)
- * @param day Base day
- * @returns Normalized year, month, day
+ * @param year 기준 연도
+ * @param month 설정할 월 (1-12 범위 밖의 값 허용)
+ * @param day 기준 일
+ * @returns 정규화된 연도, 월, 일
  *
  * @example
  * normalizeMonth(2025, 13, 15) // { year: 2026, month: 1, day: 15 }
  * normalizeMonth(2025, 2, 31)  // { year: 2025, month: 2, day: 28 }
  */
 export function normalizeMonth(year: number, month: number, day: number): DtNormalizedMonth {
-  // Normalize month overflow/underflow
-  // Adjust year if month is outside 1-12 range
+  // 월 오버플로우/언더플로우 정규화
+  // 월이 1-12 범위를 벗어나면 연도 조정
   const normalizedYear = year + Math.floor((month - 1) / 12);
-  // JavaScript % operator returns negative for negative, so use (% 12 + 12) % 12 pattern to ensure 0-11 range, then convert to 1-12
+  // JavaScript % 연산자는 음수에 대해 음수를 반환하므로 (% 12 + 12) % 12 패턴으로 0-11 범위를 보장한 후 1-12로 변환
   const normalizedMonth = ((((month - 1) % 12) + 12) % 12) + 1;
 
-  // Get last day of target month
+  // 대상 월의 마지막 일 조회
   const lastDay = new Date(normalizedYear, normalizedMonth, 0).getDate();
   const normalizedDay = Math.min(day, lastDay);
 
@@ -36,13 +36,13 @@ export function normalizeMonth(year: number, month: number, day: number): DtNorm
 }
 
 /**
- * Convert 12-hour format to 24-hour format
+ * 12시간 형식을 24시간 형식으로 변환
  * - 12:00 AM = 0:00, 12:00 PM = 12:00
  * - 1-11 AM = 1-11, 1-11 PM = 13-23
  *
- * @param rawHour 12-hour format hour (1-12)
- * @param isPM Whether PM
- * @returns 24-hour format hour (0-23)
+ * @param rawHour 12시간 형식의 시 (1-12)
+ * @param isPM 오후 여부
+ * @returns 24시간 형식의 시 (0-23)
  */
 export function convert12To24(rawHour: number, isPM: boolean): number {
   if (rawHour === 12) {
@@ -51,15 +51,15 @@ export function convert12To24(rawHour: number, isPM: boolean): number {
   return isPM ? rawHour + 12 : rawHour;
 }
 
-//#region Regex caching (created once at module load)
+//#region 정규식 캐싱 (모듈 로드 시 한 번만 생성)
 
 /**
- * Format pattern regex
+ * 형식 패턴 정규식
  *
- * Order is important:
- * In the dtFormat() function, longer patterns (yyyy, MM, dd, etc.) must be processed first
- * to prevent shorter patterns (y, M, d, etc.) from being partially matched.
- * Example: If "yyyy" is not processed first, "yy" may be matched twice
+ * 순서가 중요함:
+ * dtFormat() 함수에서 긴 패턴(yyyy, MM, dd 등)이 먼저 처리되어야
+ * 짧은 패턴(y, M, d 등)이 부분적으로 매칭되는 것을 방지함.
+ * 예: "yyyy"가 먼저 처리되지 않으면 "yy"가 두 번 매칭될 수 있음
  */
 const patterns = {
   yyyy: /yyyy/g,
@@ -91,38 +91,38 @@ const weekStrings = ["일", "월", "화", "수", "목", "금", "토"];
 //#endregion
 
 /**
- * Convert date/time to string according to format string
+ * 형식 문자열에 따라 날짜/시간을 문자열로 변환
  *
- * @param formatString Format string
- * @param args Date/time components
+ * @param formatString 형식 문자열
+ * @param args 날짜/시간 구성요소
  *
  * @remarks
- * Supports the same format strings as C#:
+ * C#과 동일한 형식 문자열을 지원:
  *
- * | Format | Description | Example |
- * |--------|-------------|---------|
- * | yyyy | 4-digit year | 2024 |
- * | yy | 2-digit year | 24 |
- * | MM | Zero-padded month | 01~12 |
- * | M | Month | 1~12 |
- * | ddd | Day of week | Sun, Mon, Tue, Wed, Thu, Fri, Sat |
- * | dd | Zero-padded day | 01~31 |
- * | d | Day | 1~31 |
- * | tt | AM/PM | AM, PM |
- * | hh | Zero-padded 12-hour | 01~12 |
- * | h | 12-hour | 1~12 |
- * | HH | Zero-padded 24-hour | 00~23 |
- * | H | 24-hour | 0~23 |
- * | mm | Zero-padded minute | 00~59 |
- * | m | Minute | 0~59 |
- * | ss | Zero-padded second | 00~59 |
- * | s | Second | 0~59 |
- * | fff | Milliseconds (3 digits) | 000~999 |
- * | ff | Milliseconds (2 digits) | 00~99 |
- * | f | Milliseconds (1 digit) | 0~9 |
- * | zzz | Timezone offset (±HH:mm) | +09:00 |
- * | zz | Timezone offset (±HH) | +09 |
- * | z | Timezone offset (±H) | +9 |
+ * | 형식 | 설명 | 예시 |
+ * |------|------|------|
+ * | yyyy | 4자리 연도 | 2024 |
+ * | yy | 2자리 연도 | 24 |
+ * | MM | 0 채움 월 | 01~12 |
+ * | M | 월 | 1~12 |
+ * | ddd | 요일 | 일, 월, 화, 수, 목, 금, 토 |
+ * | dd | 0 채움 일 | 01~31 |
+ * | d | 일 | 1~31 |
+ * | tt | 오전/오후 | AM, PM |
+ * | hh | 0 채움 12시간 | 01~12 |
+ * | h | 12시간 | 1~12 |
+ * | HH | 0 채움 24시간 | 00~23 |
+ * | H | 24시간 | 0~23 |
+ * | mm | 0 채움 분 | 00~59 |
+ * | m | 분 | 0~59 |
+ * | ss | 0 채움 초 | 00~59 |
+ * | s | 초 | 0~59 |
+ * | fff | 밀리초 (3자리) | 000~999 |
+ * | ff | 밀리초 (2자리) | 00~99 |
+ * | f | 밀리초 (1자리) | 0~9 |
+ * | zzz | 타임존 오프셋 (±HH:mm) | +09:00 |
+ * | zz | 타임존 오프셋 (±HH) | +09 |
+ * | z | 타임존 오프셋 (±H) | +9 |
  *
  * @example
  * ```typescript
@@ -165,33 +165,33 @@ export function format(
 
   let result = formatString;
 
-  // Year
+  // 연도
   if (year !== undefined) {
     const yearStr = year.toString();
     result = result.replace(patterns.yyyy, yearStr);
     result = result.replace(patterns.yy, yearStr.substring(2, 4));
   }
 
-  // Month
+  // 월
   if (month !== undefined) {
     const monthStr = month.toString();
     result = result.replace(patterns.MM, monthStr.padStart(2, "0"));
     result = result.replace(patterns.M, monthStr);
   }
 
-  // Day of week
+  // 요일
   if (week !== undefined) {
     result = result.replace(patterns.ddd, weekStrings[week]);
   }
 
-  // Day
+  // 일
   if (day !== undefined) {
     const dayStr = day.toString();
     result = result.replace(patterns.dd, dayStr.padStart(2, "0"));
     result = result.replace(patterns.d, dayStr);
   }
 
-  // Hour
+  // 시
   if (hour !== undefined) {
     result = result.replace(patterns.tt, hour < 12 ? "AM" : "PM");
 
@@ -205,21 +205,21 @@ export function format(
     result = result.replace(patterns.H, hourStr);
   }
 
-  // Minute
+  // 분
   if (minute !== undefined) {
     const minuteStr = minute.toString();
     result = result.replace(patterns.mm, minuteStr.padStart(2, "0"));
     result = result.replace(patterns.m, minuteStr);
   }
 
-  // Second
+  // 초
   if (second !== undefined) {
     const secondStr = second.toString();
     result = result.replace(patterns.ss, secondStr.padStart(2, "0"));
     result = result.replace(patterns.s, secondStr);
   }
 
-  // Millisecond
+  // 밀리초
   if (millisecond !== undefined) {
     const msStr = millisecond.toString().padStart(3, "0");
     result = result.replace(patterns.fff, msStr);
@@ -227,7 +227,7 @@ export function format(
     result = result.replace(patterns.f, msStr.substring(0, 1));
   }
 
-  // Timezone
+  // 타임존
   if (offsetSign !== undefined && offsetHour !== undefined && offsetMinute !== undefined) {
     result = result.replace(
       patterns.zzz,

package/src/utils/error.ts

@@ -1,10 +1,10 @@
 /**
- * Utility to extract message from unknown type error.
+ * unknown 타입 에러에서 메시지를 추출하는 유틸리티.
  *
- * Returns the message property if it's an Error instance, otherwise returns String conversion.
+ * Error 인스턴스이면 message 속성을 반환하고, 그렇지 않으면 String 변환 결과를 반환.
  *
- * @param err - Unknown error from catch block
- * @returns Error message string
+ * @param err - catch 블록의 unknown 에러
+ * @returns 에러 메시지 문자열
  */
 export function message(err: unknown): string {
   return err instanceof Error ? err.message : String(err);

package/src/utils/json.ts

@@ -1,6 +1,6 @@
 /**
- * JSON conversion utility
- * JSON serialization/deserialization supporting custom types (DateTime, DateOnly, Time, Uuid, etc.)
+ * JSON 변환 유틸리티
+ * 커스텀 타입(DateTime, DateOnly, Time, Uuid 등)을 지원하는 JSON 직렬화/역직렬화
  */
 import { DateTime } from "../types/date-time";
 import { DateOnly } from "../types/date-only";
@@ -19,19 +19,19 @@ interface TypedObject {
 //#region stringify
 
 /**
- * Serialize object to JSON string
- * Supports custom types like DateTime, DateOnly, Time, Uuid, Set, Map, Error, Uint8Array, etc.
+ * 객체를 JSON 문자열로 직렬화
+ * DateTime, DateOnly, Time, Uuid, Set, Map, Error, Uint8Array 등 커스텀 타입 지원.
  *
- * @param obj Object to serialize
- * @param options Serialization options
- * @param options.space JSON indentation (number: number of spaces, string: indentation string)
- * @param options.replacer Custom replacer function. Called before default type conversion
- * @param options.redactBytes If true, replace Uint8Array contents with "__hidden__" (for logging). Results serialized with this option cannot restore original Uint8Array via jsonParse()
+ * @param obj 직렬화할 객체
+ * @param options 직렬화 옵션
+ * @param options.space JSON 들여쓰기 (숫자: 공백 수, 문자열: 들여쓰기 문자열)
+ * @param options.replacer 커스텀 replacer 함수. 기본 타입 변환 전에 호출됨
+ * @param options.redactBytes true이면 Uint8Array 내용을 "__hidden__"으로 대체 (로깅용). 이 옵션으로 직렬화된 결과는 jsonParse()로 원래 Uint8Array를 복원할 수 없음
  *
  * @remarks
- * - Objects with circular references throw TypeError
- * - If object has toJSON method, it is called and the result is used (except for custom types like Date, DateTime)
- * - Safe in Worker environments as global prototypes are not modified
+ * - 순환 참조가 있는 객체는 TypeError를 발생시킴
+ * - 객체에 toJSON 메서드가 있으면 호출하여 결과를 사용 (Date, DateTime 같은 커스텀 타입 제외)
+ * - 전역 프로토타입을 수정하지 않으므로 Worker 환경에서 안전
  */
 export function stringify(
   obj: unknown,
@@ -41,21 +41,21 @@ export function stringify(
     redactBytes?: boolean;
   },
 ): string {
-  // WeakSet for circular reference detection
+  // 순환 참조 감지용 WeakSet
   const seen = new WeakSet<object>();
 
   /**
-   * Recursively traverse object and convert special types to __type__ format
+   * 객체를 재귀적으로 순회하며 특수 타입을 __type__ 형식으로 변환
    *
-   * JSON.stringify's replacer receives values after toJSON call,
-   * so types like Date must be converted beforehand for proper handling.
-   * This approach is safe in Worker environments as global prototypes are not modified.
+   * JSON.stringify의 replacer는 toJSON 호출 후의 값을 받으므로,
+   * Date 같은 타입은 사전에 변환해야 올바르게 처리됨.
+   * 전역 프로토타입을 수정하지 않으므로 Worker 환경에서 안전.
    *
-   * @param key Key of current value (root is undefined)
-   * @param value Value to convert
+   * @param key 현재 값의 key (루트는 undefined)
+   * @param value 변환할 값
    */
   const convertSpecialTypes = (key: string | undefined, value: unknown): unknown => {
-    // Apply custom replacer
+    // 커스텀 replacer 적용
     const currValue = options?.replacer !== undefined ? options.replacer(key, value) : value;
 
     if (currValue instanceof Date) {
@@ -108,9 +108,9 @@ export function stringify(
       return { __type__: "Uint8Array", data: toHex(currValue) };
     }
 
-    // Array processing
+    // Array 처리
     if (Array.isArray(currValue)) {
-      // Detect circular reference
+      // 순환 참조 감지
       if (seen.has(currValue)) {
         throw new TypeError("Converting circular structure to JSON");
       }
@@ -120,15 +120,15 @@ export function stringify(
       return result;
     }
 
-    // Generic object processing
+    // 일반 객체 처리
     if (currValue !== null && typeof currValue === "object") {
-      // Detect circular reference
+      // 순환 참조 감지
       if (seen.has(currValue)) {
         throw new TypeError("Converting circular structure to JSON");
       }
       seen.add(currValue);
 
-      // Call toJSON method if present (custom types like Date, DateTime already handled above)
+      // toJSON 메서드가 있으면 호출 (Date, DateTime 같은 커스텀 타입은 위에서 이미 처리됨)
       if (
         "toJSON" in currValue &&
         typeof (currValue as { toJSON: unknown }).toJSON === "function"
@@ -141,7 +141,7 @@ export function stringify(
       const result: Record<string, unknown> = {};
       for (const [k, v] of Object.entries(currValue)) {
         const converted = convertSpecialTypes(k, v);
-        // undefined is excluded from JSON
+        // undefined는 JSON에서 제외됨
         if (converted !== undefined) {
           result[k] = converted;
         }
@@ -153,8 +153,8 @@ export function stringify(
     return currValue;
   };
 
-  // Convert entire object first, then call JSON.stringify
-  // This approach is safe in concurrent environments as Date.prototype.toJSON is not modified
+  // 전체 객체를 먼저 변환한 후 JSON.stringify 호출
+  // Date.prototype.toJSON을 수정하지 않으므로 동시성 환경에서 안전
   const converted = convertSpecialTypes(undefined, obj);
   return JSON.stringify(converted, null, options?.space);
 }
@@ -164,25 +164,25 @@ export function stringify(
 //#region parse
 
 /**
- * Deserialize JSON string to object
- * Restore custom types like DateTime, DateOnly, Time, Uuid, Set, Map, Error, Uint8Array, etc.
+ * JSON 문자열을 객체로 역직렬화
+ * DateTime, DateOnly, Time, Uuid, Set, Map, Error, Uint8Array 등 커스텀 타입 복원.
  *
  * @remarks
- * Objects with `__type__` and `data` keys are used for type restoration.
- * Be careful if user data contains objects with `{ __type__: "Date" | "DateTime" | "DateOnly" | "Time" | "Uuid" | "Set" | "Map" | "Error" | "Uint8Array", data: ... }`
- * format as they may be unintentionally converted to types.
- * All JSON null values are converted to undefined.
- * This is intentional for the simplysm framework's null-free convention.
+ * `__type__`과 `data` key를 가진 객체가 타입 복원에 사용됨.
+ * 사용자 데이터에 `{ __type__: "Date" | "DateTime" | "DateOnly" | "Time" | "Uuid" | "Set" | "Map" | "Error" | "Uint8Array", data: ... }`
+ * 형식의 객체가 포함되어 있으면 의도치 않게 타입으로 변환될 수 있으므로 주의.
+ * 모든 JSON null 값은 undefined로 변환됨.
+ * 이는 simplysm 프레임워크의 null-free 규칙을 위한 의도적인 동작.
  *
- * @security In development mode (`__DEV__`), the error message includes the entire JSON string.
- * In production mode, only JSON length is included.
+ * @security 개발 모드(`__DEV__`)에서는 에러 메시지에 전체 JSON 문자열이 포함됨.
+ * 운영 모드에서는 JSON 길이만 포함됨.
  */
 export function parse<TResult = unknown>(json: string): TResult {
   try {
     return nullToUndefined(
       JSON.parse(json, (_key, value: unknown) => {
         if (value != null && typeof value === "object") {
-          // Restore types based on __type__ marker
+          // __type__ 마커 기반 타입 복원
           if ("__type__" in value && "data" in value) {
             const typed = value as TypedObject;
             if (typed.__type__ === "Date" && typeof typed.data === "string") {
@@ -215,7 +215,7 @@ export function parse<TResult = unknown>(json: string): TResult {
             if (typed.__type__ === "Uint8Array" && typeof typed.data === "string") {
               if (typed.data === "__hidden__") {
                 throw new SdError(
-                  "Uint8Array serialized with redactBytes option cannot be restored via parse",
+                  "redactBytes 옵션으로 직렬화된 Uint8Array는 parse로 복원할 수 없습니다",
                 );
               }
               return fromHex(typed.data);
@@ -228,9 +228,9 @@ export function parse<TResult = unknown>(json: string): TResult {
     ) as TResult;
   } catch (err) {
     if (env.DEV) {
-      throw new SdError(err, "JSON parsing error: \n" + json);
+      throw new SdError(err, "JSON 파싱 오류: \n" + json);
     }
-    throw new SdError(err, `JSON parsing error (length: ${json.length})`);
+    throw new SdError(err, `JSON 파싱 오류 (길이: ${json.length})`);
   }
 }
 

package/src/utils/num.ts

@@ -1,17 +1,17 @@
 /**
- * Number utility functions
+ * 숫자 유틸리티 함수
  */
 
 //#region parseInt / parseFloat / parseRoundedInt
 
 /**
- * Parse string to integer
- * Remove non-numeric characters (except 0-9, -, .) before parsing
+ * 문자열을 정수로 파싱
+ * 파싱 전 비숫자 문자(0-9, -, . 제외) 제거
  *
- * @note Strings with decimal points return only the integer part (e.g., '12.34' → 12).
- *       Use {@link parseRoundedInt} if rounding is needed.
- * @note Hyphens (-) in the middle of the string are preserved, which may result in unintended negative numbers.
- *       Example: `"A-123B"` → `-123`
+ * @note 소수점이 있는 문자열은 정수 부분만 반환 (예: '12.34' → 12).
+ *       반올림이 필요하면 {@link parseRoundedInt} 사용.
+ * @note 문자열 중간의 하이픈(-)은 유지되므로 의도치 않은 음수가 될 수 있음.
+ *       예: `"A-123B"` → `-123`
  */
 export function parseInt(text: unknown): number | undefined {
   if (typeof text === "number") return Math.trunc(text);
@@ -24,7 +24,7 @@ export function parseInt(text: unknown): number | undefined {
 }
 
 /**
- * Parse string to float, then round and return integer
+ * 문자열을 float로 파싱한 후 반올림하여 정수 반환
  */
 export function parseRoundedInt(text: unknown): number | undefined {
   const float = parseFloat(text);
@@ -32,8 +32,8 @@ export function parseRoundedInt(text: unknown): number | undefined {
 }
 
 /**
- * Parse string to float
- * Remove non-numeric characters before parsing
+ * 문자열을 float로 파싱
+ * 파싱 전 비숫자 문자 제거
  */
 export function parseFloat(text: unknown): number | undefined {
   if (typeof text === "number") return text;
@@ -50,13 +50,13 @@ export function parseFloat(text: unknown): number | undefined {
 //#region isNullOrEmpty
 
 /**
- * Check undefined, null, 0 (type guard)
+ * undefined, null, 0 검사 (타입 가드)
  *
- * Acts as a type guard, guaranteeing that if true is returned, `val` is `0 | undefined`.
- * If false is returned, `val` is guaranteed to be a valid non-zero number.
+ * 타입 가드로 동작하여, true를 반환하면 `val`이 `0 | undefined`임을 보장.
+ * false를 반환하면 `val`이 유효한 0이 아닌 숫자임을 보장.
  *
- * @param val Value to check
- * @returns true if undefined, null, or 0
+ * @param val 검사할 값
+ * @returns undefined, null, 또는 0이면 true
  * @example
  * const count: number | undefined = getValue();
  * if (isNullOrEmpty(count)) {
@@ -76,11 +76,11 @@ export function isNullOrEmpty(val: number | undefined): val is 0 | undefined {
 //#region format
 
 /**
- * Format number to string with thousand separators
- * @param val Number to format
- * @param digit Decimal place options
- * @param digit.max Maximum decimal places
- * @param digit.min Minimum decimal places (pad with 0 if insufficient)
+ * 숫자를 천 단위 구분자가 포함된 문자열로 포맷
+ * @param val 포맷할 숫자
+ * @param digit 소수점 옵션
+ * @param digit.max 최대 소수점 자릿수
+ * @param digit.min 최소 소수점 자릿수 (부족하면 0으로 채움)
  * @example
  * format(1234.567, { max: 2 }) // "1,234.57"
  * format(1234, { min: 2 }) // "1,234.00"