@simplysm/core-common 13.0.69 → 13.0.71

package/src/types/lazy-gc-map.ts

@@ -1,20 +1,20 @@
 import consola from "consola";
 
 /**
- * 자동 만료 기능이 있는 Map
- * LRU 방식으로 접근 시간 갱신, 일정 시간 미접근 시 자동 삭제
+ * Map with automatic expiration feature
+ * Updates access time in LRU manner, auto-deletes if not accessed for specified time
  *
- * @note 인스턴스 사용 후 반드시 dispose()를 호출하거나 using 문을 사용해야 함.
- *       그렇지 않으면 GC 타이머가 계속 동작하여 메모리 누수 발생.
+ * @note Must call dispose() or use 'using' statement after use.
+ *       Otherwise GC timer continues running and causes memory leak.
  *
  * @example
- * // using 문 사용 (권장)
+ * // using statement (recommended)
  * using map = new LazyGcMap({ gcInterval: 10000, expireTime: 60000 });
  *
- * // 또는 명시적 dispose() 호출
+ * // Or explicit dispose() call
  * const map = new LazyGcMap({ gcInterval: 10000, expireTime: 60000 });
  * try {
- *   // ... 사용
+ *   // ... usage
  * } finally {
  *   map.dispose();
  * }
@@ -22,21 +22,21 @@ import consola from "consola";
 export class LazyGcMap<TKey, TValue> {
   private static readonly _logger = consola.withTag("LazyGcMap");
 
-  // 실제 데이터와 마지막 접근 시간을 함께 저장
+  // Store actual data and last access time together
   private readonly _map = new Map<TKey, { value: TValue; lastAccess: number }>();
 
-  // GC 타이머
+  // GC timer
   private _gcTimer?: ReturnType<typeof setInterval>;
-  // GC 실행 중 플래그 (중복 실행 방지)
+  // Flag to prevent duplicate GC runs
   private _isGcRunning = false;
-  // destroy 호출 여부
+  // Whether dispose() has been called
   private _isDestroyed = false;
 
   /**
-   * @param _options 설정 옵션
-   * @param _options.gcInterval GC 주기 (밀리초). 기본값: expireTime의 1/10 (최소 1000ms)
-   * @param _options.expireTime 만료 시간 (밀리초). 마지막 접근 후 이 시간이 지나면 삭제됨. 예: 60000 (60초)
-   * @param _options.onExpire 만료 시 호출되는 콜백. 비동기 함수도 가능하며, 에러 발생 시 로깅 후 계속 진행됨
+   * @param _options Configuration options
+   * @param _options.gcInterval GC interval in milliseconds. Default: 1/10 of expireTime (minimum 1000ms)
+   * @param _options.expireTime Expiration time in milliseconds. Deleted after this time since last access. Example: 60000 (60 seconds)
+   * @param _options.onExpire Callback called on expiration. Can be async function, errors are logged and continue execution
    */
   constructor(
     private readonly _options: {
@@ -46,48 +46,48 @@ export class LazyGcMap<TKey, TValue> {
     },
   ) {}
 
-  /** 저장된 항목 수 */
+  /** Number of stored items */
   get size(): number {
     return this._map.size;
   }
 
-  /** 키 존재 여부 확인 (접근 시간 갱신 안함) */
+  /** Check if key exists (does not update access time) */
   has(key: TKey): boolean {
     if (this._isDestroyed) return false;
     return this._map.has(key);
   }
 
-  /** 값 조회 (접근 시간 갱신됨) */
+  /** Get value (updates access time) */
   get(key: TKey): TValue | undefined {
     if (this._isDestroyed) return undefined;
     const item = this._map.get(key);
     if (item == null) return undefined;
 
-    // 접근 시 시간 갱신 (LRU)
+    // Update access time on retrieval (LRU)
     item.lastAccess = Date.now();
     return item.value;
   }
 
-  /** 값 저장 (접근 시간 설정 및 GC 타이머 시작) */
+  /** Store value (sets access time and starts GC timer) */
   set(key: TKey, value: TValue): void {
     if (this._isDestroyed) return;
     this._map.set(key, { value, lastAccess: Date.now() });
-    // 데이터가 들어왔으므로 GC 타이머 가동
+    // Start GC timer when data is added
     this._startGc();
   }
 
-  /** 항목 삭제 (비었으면 GC 타이머 중지) */
+  /** Delete item (stops GC timer if empty) */
   delete(key: TKey): boolean {
     if (this._isDestroyed) return false;
     const result = this._map.delete(key);
-    // 비었으면 타이머 중지
+    // Stop timer if empty
     if (this._map.size === 0) {
       this._stopGc();
     }
     return result;
   }
 
-  /** 인스턴스 정리 (GC 타이머 중지 및 데이터 삭제) */
+  /** Clean up instance (stop GC timer and delete data) */
   dispose(): void {
     if (this._isDestroyed) return;
     this._isDestroyed = true;
@@ -95,13 +95,13 @@ export class LazyGcMap<TKey, TValue> {
     this._stopGc();
   }
 
-  /** using 문 지원 */
+  /** Support for 'using' statement */
   [Symbol.dispose](): void {
     this.dispose();
   }
 
   /**
-   * 모든 항목 삭제 (인스턴스는 계속 사용 가능)
+   * Delete all items (instance can still be used)
    */
   clear(): void {
     if (this._isDestroyed) return;
@@ -110,14 +110,14 @@ export class LazyGcMap<TKey, TValue> {
   }
 
   /**
-   * 키에 해당하는 값을 반환하고, 없으면 factory로 생성 후 저장하여 반환
-   * @param key 조회할 키
-   * @param factory 키가 없을 때 값을 생성하는 함수
-   * @returns 기존 값 또는 새로 생성된 값
+   * Return value for key, or create and store via factory if not found
+   * @param key Key to look up
+   * @param factory Function to create value if key not found
+   * @returns Existing or newly created value
    */
   getOrCreate(key: TKey, factory: () => TValue): TValue {
     if (this._isDestroyed) {
-      throw new Error("LazyGcMap이 이미 dispose되었습니다.");
+      throw new Error("LazyGcMap has already been disposed.");
     }
     const item = this._map.get(key);
     if (item == null) {
@@ -130,7 +130,7 @@ export class LazyGcMap<TKey, TValue> {
     return item.value;
   }
 
-  /** 값들만 순회 (Iterator) */
+  /** Iterate over values only (Iterator) */
   *values(): IterableIterator<TValue> {
     if (this._isDestroyed) return;
     for (const item of this._map.values()) {
@@ -138,13 +138,13 @@ export class LazyGcMap<TKey, TValue> {
     }
   }
 
-  /** 키들만 순회 (Iterator) */
+  /** Iterate over keys only (Iterator) */
   *keys(): IterableIterator<TKey> {
     if (this._isDestroyed) return;
     yield* this._map.keys();
   }
 
-  /** 엔트리 순회 (Iterator) */
+  /** Iterate over entries (Iterator) */
   *entries(): IterableIterator<[TKey, TValue]> {
     if (this._isDestroyed) return;
     for (const [key, item] of this._map.entries()) {
@@ -152,7 +152,7 @@ export class LazyGcMap<TKey, TValue> {
     }
   }
 
-  //#region GC 로직
+  //#region GC logic
 
   private _startGc(): void {
     if (this._isDestroyed) return;
@@ -165,14 +165,14 @@ export class LazyGcMap<TKey, TValue> {
   }
 
   private async _runGc(): Promise<void> {
-    // 이미 실행 중이면 스킵 (onExpire 콜백이 오래 걸리는 경우 중복 실행 방지)
+    // Skip if already running (prevent duplicate runs when onExpire callback takes time)
     if (this._isGcRunning) return;
     this._isGcRunning = true;
 
     try {
       const now = Date.now();
 
-      // 1. 만료된 항목 수집 (삭제 전)
+      // 1. Collect expired items (before deletion)
       const expiredEntries: { key: TKey; item: { value: TValue; lastAccess: number } }[] = [];
       for (const [key, item] of this._map) {
         if (now - item.lastAccess > this._options.expireTime) {
@@ -180,33 +180,33 @@ export class LazyGcMap<TKey, TValue> {
         }
       }
 
-      // 2. 각 항목에 대해 콜백 실행 후 삭제
+      // 2. Run callback then delete each item
       for (const { key, item } of expiredEntries) {
-        // 콜백 실행 전 현재 상태 확인 (이미 다른 값으로 교체되었거나 삭제되었으면 스킵)
+        // Check current state before callback (skip if already replaced or deleted)
         const currentItem = this._map.get(key);
         if (currentItem !== item) {
           continue;
         }
 
-        // 만료 콜백 실행
+        // Run expiration callback
         if (this._options.onExpire != null) {
           try {
             await this._options.onExpire(key, item.value);
           } catch (err) {
-            LazyGcMap._logger.error("onExpire 콜백 에러", err);
+            LazyGcMap._logger.error("onExpire callback error", err);
           }
         }
 
-        // 콜백 후 재등록 여부 확인
-        // 시나리오: onExpire 콜백에서 동일 키로 새 값을 set()한 경우,
-        // 새로 등록된 항목을 삭제하면 안 됨. item 참조가 같으면 재등록되지 않은 것이므로 삭제 진행.
+        // Check if item was re-registered after callback
+        // Scenario: onExpire callback calls set() with same key,
+        // we should not delete newly registered item. If item reference is same, not re-registered, so delete.
         const afterItem = this._map.get(key);
         if (afterItem === item) {
           this._map.delete(key);
         }
       }
 
-      // GC 후 비었으면 끄기
+      // Stop GC if empty after cleanup
       if (this._map.size === 0) {
         this._stopGc();
       }

package/src/types/time.ts

@@ -2,10 +2,10 @@ import { ArgumentError } from "../errors/argument-error";
 import { convert12To24, formatDate } from "../utils/date-format";
 
 /**
- * 시간 클래스 (날짜제외: HH:mm:ss.fff, 불변)
+ * Time class (without date: HH:mm:ss.fff, immutable)
  *
- * 날짜 정보 없이 시간만 저장하는 불변 클래스이다.
- * 24시간을 초과하거나 음수인 경우 자동으로 정규화된다.
+ * An immutable class that stores only time without date information.
+ * Values exceeding 24 hours or negative values are automatically normalized.
  *
  * @example
  * const now = new Time();
@@ -17,13 +17,13 @@ export class Time {
 
   private readonly _tick: number;
 
-  /** 현재 시간으로 생성 */
+  /** Create with current time */
   constructor();
-  /** 시분초밀리초로 생성 */
+  /** Create with hour, minute, second, millisecond */
   constructor(hour: number, minute: number, second?: number, millisecond?: number);
-  /** tick (밀리초)으로 생성 */
+  /** Create from tick (millisecond) */
   constructor(tick: number);
-  /** Date 객체에서 시간 부분만 추출하여 생성 */
+  /** Create by extracting time part only from Date object */
   constructor(date: Date);
   constructor(arg1?: number | Date, arg2?: number, arg3?: number, arg4?: number) {
     if (arg1 === undefined) {
@@ -55,23 +55,23 @@ export class Time {
   }
 
   /**
-   * 문자열을 파싱하여 Time 인스턴스를 생성
+   * Parse a string to create Time instance
    *
-   * @param str 시간 문자열
-   * @returns 파싱된 Time 인스턴스
-   * @throws ArgumentError 지원하지 않는 형식인 경우
+   * @param str Time string
+   * @returns Parsed Time instance
+   * @throws ArgumentError If unsupported format
    *
    * @example
    * Time.parse("10:30:00")           // HH:mm:ss
    * Time.parse("10:30:00.123")       // HH:mm:ss.fff
-   * Time.parse("오전 10:30:00")       // 오전/오후 HH:mm:ss
-   * Time.parse("2025-01-15T10:30:00") // ISO 8601 (시간 부분만 추출)
+   * Time.parse("AM 10:30:00")        // AM/PM HH:mm:ss
+   * Time.parse("2025-01-15T10:30:00") // ISO 8601 (extract time part only)
    */
   static parse(str: string): Time {
-    const match1 = /(오전|오후) ([0-9]{1,2}):([0-9]{1,2}):([0-9]{1,2})(\.([0-9]{1,3}))?$/.exec(str);
+    const match1 = /(AM|PM) ([0-9]{1,2}):([0-9]{1,2}):([0-9]{1,2})(\.([0-9]{1,3}))?$/i.exec(str);
     if (match1 != null) {
       const rawHour = Number(match1[2]);
-      const isPM = match1[1] === "오후";
+      const isPM = match1[1].toUpperCase() === "PM";
       const hour = convert12To24(rawHour, isPM);
       return new Time(
         hour,
@@ -91,8 +91,8 @@ export class Time {
       );
     }
 
-    // ISO 8601 형식 (예: 2025-01-15T10:30:00.123Z, 2025-01-15T10:30:00+09:00)
-    // Date 객체를 사용하여 타임존 변환 처리
+    // ISO 8601 format (e.g., 2025-01-15T10:30:00.123Z, 2025-01-15T10:30:00+09:00)
+    // Use Date object to handle timezone conversion
     const isoMatch = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.exec(str);
     if (isoMatch != null) {
       const date = new Date(str);
@@ -107,12 +107,12 @@ export class Time {
     }
 
     throw new ArgumentError(
-      `시간 형식을 파싱할 수 없습니다. 지원 형식: 'HH:mm:ss', 'HH:mm:ss.fff', '오전/오후 HH:mm:ss', ISO 8601`,
+      `Failed to parse time format. Supported formats: 'HH:mm:ss', 'HH:mm:ss.fff', 'AM/PM HH:mm:ss', ISO 8601`,
       { input: str },
     );
   }
 
-  //#region Getters (읽기 전용)
+  //#region Getters (read-only)
 
   get hour(): number {
     return Math.floor(this._tick / (60 * 60 * 1000));
@@ -134,61 +134,61 @@ export class Time {
     return this._tick;
   }
 
-  /** 시간 세팅이 제대로 되었는지 여부 */
+  /** Whether time is set correctly */
   get isValid(): boolean {
     return !Number.isNaN(this._tick);
   }
 
   //#endregion
 
-  //#region 불변 변환 메서드 (새 인스턴스 반환)
+  //#region Immutable transformation methods (returns new instance)
 
-  /** 지정된 시로 새 인스턴스 반환 */
+  /** Return new instance with specified hour */
   setHour(hour: number): Time {
     return new Time(hour, this.minute, this.second, this.millisecond);
   }
 
-  /** 지정된 분으로 새 인스턴스 반환 */
+  /** Return new instance with specified minute */
   setMinute(minute: number): Time {
     return new Time(this.hour, minute, this.second, this.millisecond);
   }
 
-  /** 지정된 초로 새 인스턴스 반환 */
+  /** Return new instance with specified second */
   setSecond(second: number): Time {
     return new Time(this.hour, this.minute, second, this.millisecond);
   }
 
-  /** 지정된 밀리초로 새 인스턴스 반환 */
+  /** Return new instance with specified millisecond */
   setMillisecond(millisecond: number): Time {
     return new Time(this.hour, this.minute, this.second, millisecond);
   }
 
   //#endregion
 
-  //#region 산술 메서드 (새 인스턴스 반환)
+  //#region Arithmetic methods (returns new instance)
 
-  /** 지정된 시간을 더한 새 인스턴스 반환 (24시간 순환) */
+  /** Return new instance with specified hours added (24-hour wraparound) */
   addHours(hours: number): Time {
     let newTick = (this._tick + hours * 60 * 60 * 1000) % Time.MS_PER_DAY;
     if (newTick < 0) newTick += Time.MS_PER_DAY;
     return new Time(newTick);
   }
 
-  /** 지정된 분을 더한 새 인스턴스 반환 (24시간 순환) */
+  /** Return new instance with specified minutes added (24-hour wraparound) */
   addMinutes(minutes: number): Time {
     let newTick = (this._tick + minutes * 60 * 1000) % Time.MS_PER_DAY;
     if (newTick < 0) newTick += Time.MS_PER_DAY;
     return new Time(newTick);
   }
 
-  /** 지정된 초를 더한 새 인스턴스 반환 (24시간 순환) */
+  /** Return new instance with specified seconds added (24-hour wraparound) */
   addSeconds(seconds: number): Time {
     let newTick = (this._tick + seconds * 1000) % Time.MS_PER_DAY;
     if (newTick < 0) newTick += Time.MS_PER_DAY;
     return new Time(newTick);
   }
 
-  /** 지정된 밀리초를 더한 새 인스턴스 반환 (24시간 순환) */
+  /** Return new instance with specified milliseconds added (24-hour wraparound) */
   addMilliseconds(milliseconds: number): Time {
     let newTick = (this._tick + milliseconds) % Time.MS_PER_DAY;
     if (newTick < 0) newTick += Time.MS_PER_DAY;
@@ -197,12 +197,12 @@ export class Time {
 
   //#endregion
 
-  //#region 포맷팅
+  //#region Formatting
 
   /**
-   * 지정된 포맷으로 문자열 변환
-   * @param format 포맷 문자열
-   * @see dtFormat 지원 포맷 문자열 참조
+   * Convert to string with specified format
+   * @param format Format string
+   * @see dtFormat for supported format strings
    */
   toFormatString(formatStr: string): string {
     return formatDate(formatStr, {

package/src/types/uuid.ts

@@ -2,16 +2,16 @@ import type { Bytes } from "../common.types";
 import { ArgumentError } from "../errors/argument-error";
 
 /**
- * UUID v4 클래스
+ * UUID v4 class
  *
- * crypto.getRandomValues 기반으로 암호학적으로 안전한 UUID를 생성한다. (Chrome 79+, Node.js 공용)
+ * Generates cryptographically secure UUIDs based on crypto.getRandomValues. (Chrome 79+, Node.js compatible)
  *
  * @example
  * const id = Uuid.new();
  * const fromStr = new Uuid("550e8400-e29b-41d4-a716-446655440000");
  */
 export class Uuid {
-  // 0x00 ~ 0xFF에 대한 hex 문자열 미리 계산 (256개)
+  // Pre-calculate hex strings for 0x00 ~ 0xFF (256 entries)
   private static readonly _hexTable: string[] = Array.from({ length: 256 }, (_, i) =>
     i.toString(16).padStart(2, "0"),
   );
@@ -19,7 +19,7 @@ export class Uuid {
   private static readonly _uuidRegex =
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-  /** 16바이트 배열을 UUID 문자열로 변환 */
+  /** Convert 16-byte array to UUID string */
   private static _bytesToUuidStr(bytes: Uint8Array): string {
     const h = Uuid._hexTable;
     return (
@@ -46,12 +46,12 @@ export class Uuid {
     );
   }
 
-  /** 새 UUID v4 인스턴스 생성 */
+  /** Create new UUID v4 instance */
   static new(): Uuid {
     const bytes = new Uint8Array(16);
     crypto.getRandomValues(bytes);
 
-    // UUID v4 설정
+    // Set UUID v4 bits
     bytes[6] = (bytes[6] & 0x0f) | 0x40;
     bytes[8] = (bytes[8] & 0x3f) | 0x80;
 
@@ -59,13 +59,13 @@ export class Uuid {
   }
 
   /**
-   * 16바이트 Uint8Array에서 UUID 생성
-   * @param bytes 16바이트 배열
-   * @throws {ArgumentError} 바이트 크기가 16이 아닌 경우
+   * Create UUID from 16-byte Uint8Array
+   * @param bytes 16-byte array
+   * @throws {ArgumentError} If byte size is not 16
    */
   static fromBytes(bytes: Bytes): Uuid {
     if (bytes.length !== 16) {
-      throw new ArgumentError("UUID 바이트 크기는 16이어야 합니다.", { length: bytes.length });
+      throw new ArgumentError("UUID byte size must be 16.", { length: bytes.length });
     }
 
     return new Uuid(Uuid._bytesToUuidStr(bytes));
@@ -74,26 +74,26 @@ export class Uuid {
   private readonly _uuid: string;
 
   /**
-   * @param uuid UUID 문자열 (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 형식)
-   * @throws {ArgumentError} 형식이 올바르지 않은 경우
+   * @param uuid UUID string (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
+   * @throws {ArgumentError} If format is invalid
    */
   constructor(uuid: string) {
     if (!Uuid._uuidRegex.test(uuid)) {
-      throw new ArgumentError("UUID 형식이 올바르지 않습니다.", { uuid });
+      throw new ArgumentError("Invalid UUID format.", { uuid });
     }
     this._uuid = uuid;
   }
 
-  /** UUID를 문자열로 변환 */
+  /** Convert UUID to string */
   toString(): string {
     return this._uuid;
   }
 
-  /** UUID를 16바이트 Uint8Array로 변환 */
+  /** Convert UUID to 16-byte Uint8Array */
   toBytes(): Bytes {
     const u = this._uuid;
-    // UUID 형식: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (8-4-4-4-12)
-    // 하이픈 위치: 8, 13, 18, 23
+    // UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (8-4-4-4-12)
+    // Hyphen positions: 8, 13, 18, 23
     return new Uint8Array([
       Number.parseInt(u.substring(0, 2), 16),
       Number.parseInt(u.substring(2, 4), 16),