@simplysm/core-common 13.0.69 → 13.0.71

package/src/extensions/map-ext.ts

@@ -1,53 +1,53 @@
 /**
- * Map 확장 메서드
+ * Map extension methods
  */
 
 declare global {
   interface Map<K, V> {
     /**
-     * 키에 해당하는 값이 없으면 새 값을 설정하고 반환
+     * If no value exists for key, set new value and return it
      *
      * @remarks
-     * **주의**: V 타입이 함수인 경우(예: `Map<string, () => void>`),
-     * 두 번째 인자로 함수를 직접 전달하면 팩토리로 인식되어 호출됩니다.
-     * 함수 자체를 값으로 저장하려면 팩토리로 감싸세요.
+     * **Caution**: If V type is a function (e.g., `Map<string, () => void>`),
+     * passing the function directly as the second argument will be recognized as a factory and called.
+     * To store the function itself as a value, wrap it in a factory.
      *
      * @example
      * ```typescript
-     * // 일반 값
+     * // Regular values
      * map.getOrCreate("key", 0);
      * map.getOrCreate("key", []);
      *
-     * // 팩토리 함수 (계산 비용이 큰 경우)
+     * // Factory function (for expensive computations)
      * map.getOrCreate("key", () => expensiveComputation());
      *
-     * // 함수를 값으로 저장하는 경우
+     * // Storing function as value
      * const fnMap = new Map<string, () => void>();
      * const myFn = () => console.log("hello");
-     * fnMap.getOrCreate("key", () => myFn);  // 팩토리로 감싸기
+     * fnMap.getOrCreate("key", () => myFn);  // Wrap in factory
      * ```
      */
     getOrCreate(key: K, newValue: V): V;
     getOrCreate(key: K, newValueFn: () => V): V;
 
     /**
-     * 키에 해당하는 값을 함수로 업데이트한다
+     * Update value for key using function
      *
-     * @param key 업데이트할 키
-     * @param updateFn 현재 값을 받아 새 값을 반환하는 함수 (키가 없으면 undefined 전달)
+     * @param key Key to update
+     * @param updateFn Function that receives current value and returns new value (undefined if key doesn't exist)
      *
      * @remarks
-     * 키가 존재하지 않아도 updateFn이 호출되어 새 값이 설정된다.
-     * 기존 값 기반 계산이 필요한 경우 (카운터 증가, 배열에 추가 등) 유용하다.
+     * updateFn is called even if key doesn't exist, setting new value.
+     * Useful for calculations based on existing value (counter increment, add to array, etc).
      *
      * @example
      * ```typescript
      * const countMap = new Map<string, number>();
      *
-     * // 카운터 증가
+     * // Increment counter
      * countMap.update("key", (v) => (v ?? 0) + 1);
      *
-     * // 배열에 항목 추가
+     * // Add item to array
      * const arrayMap = new Map<string, string[]>();
      * arrayMap.update("key", (v) => [...(v ?? []), "item"]);
      * ```

package/src/extensions/set-ext.ts

@@ -1,34 +1,34 @@
 /**
- * Set 확장 메서드
+ * Set extension methods
  */
 
 declare global {
   interface Set<T> {
     /**
-     * 여러 값을 한 번에 추가
+     * Add multiple values at once
      */
     adds(...values: T[]): this;
 
     /**
-     * 값을 토글한다 (있으면 제거, 없으면 추가)
+     * Toggle value (remove if exists, add if not)
      *
-     * @param value 토글할 값
-     * @param addOrDel 강제로 추가("add") 또는 제거("del") 지정 (생략 시 자동 토글)
-     * @returns this (메서드 체이닝 가능)
+     * @param value Value to toggle
+     * @param addOrDel Force add ("add") or remove ("del") (if omitted, toggle automatically)
+     * @returns this (method chaining available)
      *
      * @remarks
-     * addOrDel 파라미터로 조건부 추가/제거를 간결하게 표현할 수 있다.
+     * addOrDel parameter allows concise expression of conditional add/remove.
      *
      * @example
      * ```typescript
      * const set = new Set<number>([1, 2, 3]);
      *
-     * set.toggle(2);  // 2가 있으므로 제거 → {1, 3}
-     * set.toggle(4);  // 4가 없으므로 추가 → {1, 3, 4}
+     * set.toggle(2);  // 2 exists, so remove → {1, 3}
+     * set.toggle(4);  // 4 doesn't exist, so add → {1, 3, 4}
      *
-     * // 조건부 토글
+     * // Conditional toggle
      * const isAdmin = true;
-     * set.toggle(5, isAdmin ? "add" : "del");  // 강제 추가
+     * set.toggle(5, isAdmin ? "add" : "del");  // Force add
      * ```
      */
     toggle(value: T, addOrDel?: "add" | "del"): this;

package/src/features/debounce-queue.ts

@@ -1,21 +1,23 @@
 /**
- * 비동기 함수 디바운스 큐
+ * Asynchronous debounce queue
  *
- * 짧은 시간 내에 여러 번 호출되면 마지막 요청만 실행하고 이전 요청은 무시합니다.
- * 입력 필드 자동완성, 연속적인 상태 변경 배치 처리 등에 유용합니다.
+ * When called multiple times within a short time, only the last request is executed
+ * and previous requests are ignored. Useful for input field auto-complete,
+ * batching consecutive state changes, and more.
  *
  * @remarks
- * 실행 중에 추가된 요청은 디바운스 지연 없이 현재 실행이 완료된 직후 처리됩니다.
- * 이는 실행 완료 전에 들어온 요청이 누락되지 않도록 하기 위한 의도적 설계입니다.
+ * Requests added during execution are processed immediately after the current execution
+ * completes without debounce delay. This is an intentional design to ensure that
+ * requests arriving before execution completes are not missed.
  *
  * @example
- * const queue = new DebounceQueue(300); // 300ms 딜레이
- * queue.run(() => console.log("1")); // 무시됨
- * queue.run(() => console.log("2")); // 무시됨
- * queue.run(() => console.log("3")); // 300ms 후 실행됨
+ * const queue = new DebounceQueue(300); // 300ms delay
+ * queue.run(() => console.log("1")); // ignored
+ * queue.run(() => console.log("2")); // ignored
+ * queue.run(() => console.log("3")); // executed after 300ms
  *
  * @example
- * // 에러 처리
+ * // Error handling
  * queue.on("error", (err) => console.error(err));
  */
 import { SdError } from "../errors/sd-error";
@@ -35,14 +37,14 @@ export class DebounceQueue extends EventEmitter<DebounceQueueEvents> {
   private _timer: ReturnType<typeof setTimeout> | undefined;
 
   /**
-   * @param _delay 디바운스 지연 시간 (밀리초). 생략 시 즉시 실행 (다음 이벤트 루프)
+   * @param _delay Debounce delay time (milliseconds). If omitted, executes immediately (next event loop)
    */
   constructor(private readonly _delay?: number) {
     super();
   }
 
   /**
-   * 대기 중인 작업과 타이머 정리
+   * Clean up pending tasks and timers
    */
   override dispose(): void {
     this._isDisposed = true;
@@ -55,15 +57,15 @@ export class DebounceQueue extends EventEmitter<DebounceQueueEvents> {
   }
 
   /**
-   * using 문 지원
+   * Supports using statement
    */
   override [Symbol.dispose](): void {
     this.dispose();
   }
 
   /**
-   * 함수를 큐에 추가
-   * 이전에 추가된 함수가 있으면 대체됨
+   * Add a function to the queue
+   * If there was a previously added function, it will be replaced
    */
   run(fn: () => void | Promise<void>): void {
     if (this._isDisposed) return;
@@ -89,8 +91,8 @@ export class DebounceQueue extends EventEmitter<DebounceQueueEvents> {
     this._timer = undefined;
 
     try {
-      // 실행 중에 새 요청이 들어오면 디바운스 지연 없이 즉시 처리
-      // 이는 "실행 완료 전에 들어온 요청은 실행 직후 바로 처리"하는 의도적 설계
+      // If a new request comes in during execution, process it immediately without debounce delay
+      // This is an intentional design to process requests that arrived before execution completes immediately after execution
       while (this._pendingFn) {
         const currentFn = this._pendingFn;
         this._pendingFn = undefined;
@@ -99,9 +101,9 @@ export class DebounceQueue extends EventEmitter<DebounceQueueEvents> {
           await currentFn();
         } catch (err) {
           const error = err instanceof Error ? err : new Error(String(err));
-          const sdError = new SdError(error, "작업 실행 중 오류 발생");
+          const sdError = new SdError(error, "Error occurred while executing task");
 
-          // 리스너가 있으면 이벤트로 전달, 없으면 로깅
+          // If there are listeners, emit as event; otherwise log
           if (this.listenerCount("error") > 0) {
             this.emit("error", sdError);
           } else {

package/src/features/event-emitter.ts

@@ -1,10 +1,10 @@
 /**
- * EventTarget 래퍼 - EventEmitter와 유사한 API 제공
+ * EventTarget wrapper - provides EventEmitter-like API
  *
- * 브라우저와 Node.js 모두에서 사용 가능한 타입 안전한 이벤트 에미터이다.
- * 내부적으로 EventTarget을 사용하여 구현되어 있다.
+ * A type-safe event emitter that can be used in both browsers and Node.js.
+ * Internally implemented using EventTarget.
  *
- * @typeParam TEvents 이벤트 타입 맵. 키는 이벤트 이름, 값은 이벤트 데이터 타입
+ * @typeParam TEvents Event type map. Keys are event names, values are event data types
  *
  * @example
  * interface MyEvents {
@@ -18,32 +18,32 @@
  * const emitter = new MyEmitter();
  * emitter.on("data", (data) => console.log(data)); // data: string
  * emitter.emit("data", "hello");
- * emitter.emit("done"); // void 타입은 인자 없이 호출
+ * emitter.emit("done"); // void type is called without arguments
  */
 export class EventEmitter<
   TEvents extends { [K in keyof TEvents]: unknown } = Record<string, unknown>,
 > {
   private readonly _target = new EventTarget();
-  // 이벤트 타입별로 리스너 맵 관리 (같은 리스너를 다른 이벤트에 등록 가능)
-  // 다형적 리스너 관리를 위해 Function 타입 사용
+  // Manage listener maps by event type (same listener can be registered to different events)
+  // Use Function type for polymorphic listener management
   private readonly _listenerMap = new Map<string, Map<Function, (e: Event) => void>>();
 
   /**
-   * 이벤트 리스너 등록
+   * Register an event listener
    *
-   * @param type 이벤트 타입
-   * @param listener 이벤트 핸들러
-   * @note 같은 리스너를 같은 이벤트에 중복 등록하면 무시됨
+   * @param type Event type
+   * @param listener Event handler
+   * @note Duplicate registration of the same listener to the same event is ignored
    */
   on<K extends keyof TEvents & string>(type: K, listener: (data: TEvents[K]) => void): void {
-    // 이벤트 타입별 맵 가져오거나 생성
+    // Get or create map for event type
     let typeMap = this._listenerMap.get(type);
     if (!typeMap) {
       typeMap = new Map();
       this._listenerMap.set(type, typeMap);
     }
 
-    // 이미 해당 이벤트에 등록된 리스너면 무시 (중복 등록 방지)
+    // If listener is already registered to this event, ignore it (prevent duplicate registration)
     if (typeMap.has(listener)) return;
 
     const wrappedListener = (e: Event) => listener((e as CustomEvent).detail);
@@ -52,10 +52,10 @@ export class EventEmitter<
   }
 
   /**
-   * 이벤트 리스너 제거
+   * Remove an event listener
    *
-   * @param type 이벤트 타입
-   * @param listener 제거할 이벤트 핸들러
+   * @param type Event type
+   * @param listener Event handler to remove
    */
   off<K extends keyof TEvents & string>(type: K, listener: (data: TEvents[K]) => void): void {
     const typeMap = this._listenerMap.get(type);
@@ -66,7 +66,7 @@ export class EventEmitter<
       this._target.removeEventListener(type, wrappedListener);
       typeMap.delete(listener);
 
-      // 빈 맵 정리
+      // Clean up empty map
       if (typeMap.size === 0) {
         this._listenerMap.delete(type);
       }
@@ -74,10 +74,10 @@ export class EventEmitter<
   }
 
   /**
-   * 이벤트 발생
+   * Emit an event
    *
-   * @param type 이벤트 타입
-   * @param args 이벤트 데이터 (void 타입이면 생략)
+   * @param type Event type
+   * @param args Event data (omitted if void type)
    */
   emit<K extends keyof TEvents & string>(
     type: K,
@@ -87,17 +87,17 @@ export class EventEmitter<
   }
 
   /**
-   * 특정 이벤트의 리스너 수 반환
+   * Return the number of listeners for a specific event
    *
-   * @param type 이벤트 타입
-   * @returns 등록된 리스너 수
+   * @param type Event type
+   * @returns Number of registered listeners
    */
   listenerCount<K extends keyof TEvents & string>(type: K): number {
     return this._listenerMap.get(type)?.size ?? 0;
   }
 
   /**
-   * 모든 이벤트 리스너를 제거한다.
+   * Remove all event listeners
    */
   dispose(): void {
     for (const [type, typeMap] of this._listenerMap) {
@@ -109,7 +109,7 @@ export class EventEmitter<
   }
 
   /**
-   * using 문 지원
+   * Supports using statement
    */
   [Symbol.dispose](): void {
     this.dispose();

package/src/features/serial-queue.ts

@@ -1,18 +1,18 @@
 /**
- * 비동기 함수 직렬 큐
+ * Asynchronous serial queue
  *
- * 큐에 추가된 함수들을 순서대로 실행합니다.
- * 한 작업이 완료되어야 다음 작업이 시작됩니다.
- * 에러가 발생해도 후속 작업은 계속 실행됩니다.
+ * Functions added to the queue are executed sequentially.
+ * The next task starts only after one task completes.
+ * Subsequent tasks continue to execute even if an error occurs.
  *
  * @example
  * const queue = new SerialQueue();
  * queue.run(async () => { await fetch("/api/1"); });
- * queue.run(async () => { await fetch("/api/2"); }); // 1번 완료 후 실행
- * queue.run(async () => { await fetch("/api/3"); }); // 2번 완료 후 실행
+ * queue.run(async () => { await fetch("/api/2"); }); // executed after 1 completes
+ * queue.run(async () => { await fetch("/api/3"); }); // executed after 2 completes
  *
  * @example
- * // 에러 처리
+ * // Error handling
  * queue.on("error", (err) => console.error(err));
  */
 import { SdError } from "../errors/sd-error";
@@ -31,14 +31,14 @@ export class SerialQueue extends EventEmitter<SerialQueueEvents> {
   private _isQueueRunning = false;
 
   /**
-   * @param _gap 각 작업 사이의 간격 (ms)
+   * @param _gap Gap between each task (ms)
    */
   constructor(private readonly _gap: number = 0) {
     super();
   }
 
   /**
-   * 대기 중인 큐 비우기 (현재 실행 중인 작업은 완료됨)
+   * Clear pending queue (currently executing task will complete)
    */
   override dispose(): void {
     this._queue.length = 0;
@@ -46,14 +46,14 @@ export class SerialQueue extends EventEmitter<SerialQueueEvents> {
   }
 
   /**
-   * using 문 지원
+   * Supports using statement
    */
   override [Symbol.dispose](): void {
     this.dispose();
   }
 
   /**
-   * 함수를 큐에 추가하고 실행
+   * Add a function to the queue and execute it
    */
   run(fn: () => void | Promise<void>): void {
     this._queue.push(fn);
@@ -73,9 +73,9 @@ export class SerialQueue extends EventEmitter<SerialQueueEvents> {
           await fn();
         } catch (err) {
           const error = err instanceof Error ? err : new Error(String(err));
-          const sdError = new SdError(error, "큐 작업 실행 중 오류 발생");
+          const sdError = new SdError(error, "Error occurred while executing queue task");
 
-          // 리스너가 있으면 이벤트로 전달, 없으면 로깅
+          // If there are listeners, emit as event; otherwise log
           if (this.listenerCount("error") > 0) {
             this.emit("error", sdError);
           } else {

package/src/globals.ts

@@ -1,9 +1,9 @@
 /**
- * 개발 모드 여부
+ * Whether development mode is enabled
  *
- * 빌드 시점에 치환됨:
- * - 라이브러리 빌드: 치환하지 않음 (그대로 유지)
- * - client/server 빌드: `define: { '__DEV__': 'true/false' }`로 치환
+ * Substituted at build time:
+ * - Library build: Not substituted (kept as-is)
+ * - Client/Server build: Substituted with `define: { '__DEV__': 'true/false' }`
  */
 export {};
 

package/src/index.ts

@@ -1,5 +1,5 @@
 // @simplysm/core-common
-// 공통 유틸리티 패키지
+// Common utility package
 
 import "./extensions/arr-ext";
 import "./extensions/set-ext";