@simplysm/core-common 13.0.99 → 14.0.1

package/src/features/debounce-queue.ts

@@ -1,23 +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 delay
- * queue.run(() => console.log("1")); // ignored
- * queue.run(() => console.log("2")); // ignored
- * queue.run(() => console.log("3")); // executed after 300ms
+ * const queue = new DebounceQueue(300); // 300ms 지연
+ * queue.run(() => console.log("1")); // 무시됨
+ * queue.run(() => console.log("2")); // 무시됨
+ * queue.run(() => console.log("3")); // 300ms 후 실행
  *
  * @example
- * // Error handling
+ * // 에러 처리
  * queue.on("error", (err) => console.error(err));
  */
 import { SdError } from "../errors/sd-error";
@@ -37,18 +37,18 @@ export class DebounceQueue extends EventEmitter<DebounceQueueEvents> {
   private _timer: ReturnType<typeof setTimeout> | undefined;
 
   /**
-   * @param _delay Debounce delay time (milliseconds). If omitted, executes immediately (next event loop)
+   * @param _delay 디바운스 지연 시간 (밀리초). 생략 시 즉시 실행 (다음 이벤트 루프)
    */
   constructor(private readonly _delay?: number) {
     super();
   }
 
   /**
-   * Clean up pending tasks and timers
+   * 대기 중인 작업과 타이머 정리
    */
   override dispose(): void {
     this._isDisposed = true;
-    if (this._timer) {
+    if (this._timer != null) {
       clearTimeout(this._timer);
       this._timer = undefined;
     }
@@ -57,22 +57,22 @@ export class DebounceQueue extends EventEmitter<DebounceQueueEvents> {
   }
 
   /**
-   * Supports using statement
+   * using 문 지원
    */
   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;
 
     this._pendingFn = fn;
 
-    if (this._timer) {
+    if (this._timer != null) {
       clearTimeout(this._timer);
       this._timer = undefined;
     }
@@ -91,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;
@@ -101,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, "Error occurred while executing task");
+          const sdError = new SdError(error, "작업 실행 중 오류 발생");
 
-          // 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 wrapper - provides EventEmitter-like API
+ * EventTarget 래퍼 - EventEmitter와 유사한 API 제공
  *
- * A type-safe event emitter that can be used in both browsers and Node.js.
- * Internally implemented using EventTarget.
+ * 브라우저와 Node.js 모두에서 사용 가능한 타입 안전한 이벤트 이미터.
+ * 내부적으로 EventTarget을 사용하여 구현됨.
  *
- * @typeParam TEvents Event type map. Keys are event names, values are event data types
+ * @typeParam TEvents 이벤트 타입 맵. key는 이벤트 이름, value는 이벤트 데이터 타입
  *
  * @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 type is called without arguments
+ * emitter.emit("done"); // void 타입은 인자 없이 호출
  */
 export class EventEmitter<
   TEvents extends { [K in keyof TEvents]: unknown } = Record<string, unknown>,
 > {
   private readonly _target = new EventTarget();
-  // Manage listener maps by event type (same listener can be registered to different events)
-  // Use Function type for polymorphic listener management
+  // 이벤트 타입별 리스너 맵 관리 (같은 리스너를 다른 이벤트에 등록 가능)
+  // 다형성 리스너 관리를 위해 Function 타입 사용
   private readonly _listenerMap = new Map<string, Map<Function, (e: Event) => void>>();
 
   /**
-   * Register an event listener
+   * 이벤트 리스너 등록
    *
-   * @param type Event type
-   * @param listener Event handler
-   * @note Duplicate registration of the same listener to the same event is ignored
+   * @param type 이벤트 타입
+   * @param listener 이벤트 핸들러
+   * @note 같은 리스너를 같은 이벤트에 중복 등록하면 무시됨
    */
   on<TEventName extends keyof TEvents & string>(type: TEventName, listener: (data: TEvents[TEventName]) => 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 Event type
-   * @param listener Event handler to remove
+   * @param type 이벤트 타입
+   * @param listener 제거할 이벤트 핸들러
    */
   off<TEventName extends keyof TEvents & string>(type: TEventName, listener: (data: TEvents[TEventName]) => 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 Event type
-   * @param args Event data (omitted if void type)
+   * @param type 이벤트 타입
+   * @param args 이벤트 데이터 (void 타입이면 생략)
    */
   emit<TEventName extends keyof TEvents & string>(
     type: TEventName,
@@ -87,17 +87,17 @@ export class EventEmitter<
   }
 
   /**
-   * Return the number of listeners for a specific event
+   * 특정 이벤트의 리스너 수 반환
    *
-   * @param type Event type
-   * @returns Number of registered listeners
+   * @param type 이벤트 타입
+   * @returns 등록된 리스너 수
    */
   listenerCount<TEventName extends keyof TEvents & string>(type: TEventName): 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<
   }
 
   /**
-   * Supports using statement
+   * using 문 지원
    */
   [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"); }); // executed after 1 completes
- * queue.run(async () => { await fetch("/api/3"); }); // executed after 2 completes
+ * queue.run(async () => { await fetch("/api/2"); }); // 1 완료 후 실행
+ * queue.run(async () => { await fetch("/api/3"); }); // 2 완료 후 실행
  *
  * @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 Gap between each task (ms)
+   * @param _gap 각 작업 사이의 간격 (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> {
   }
 
   /**
-   * Supports using statement
+   * using 문 지원
    */
   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, "Error occurred while executing queue task");
+          const sdError = new SdError(error, "큐 작업 실행 중 오류 발생");
 
-          // 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
+ * 개발 모드 활성화 여부
  *
- * Substituted at build time:
- * - Library build: Not substituted (kept as-is)
- * - Client/Server build: Substituted with `define: { '__DEV__': 'true/false' }`
+ * 빌드 시점에 치환됨:
+ * - 라이브러리 빌드: 치환되지 않음 (그대로 유지)
+ * - 클라이언트/서버 빌드: `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";
@@ -7,7 +7,7 @@ import "./extensions/map-ext";
 
 export * from "./env";
 
-// arr-extension re-export
+// arr-extension 재내보내기
 export * from "./extensions/arr-ext";
 
 //#region errors
@@ -31,7 +31,7 @@ export * from "./features/serial-queue";
 export * from "./features/event-emitter";
 //#endregion
 
-//#region utils (namespace exports)
+//#region utils (네임스페이스 내보내기)
 export * as obj from "./utils/obj";
 export * as str from "./utils/str";
 export * as num from "./utils/num";
@@ -46,11 +46,11 @@ export * as dt from "./utils/date-format";
 export * as primitive from "./utils/primitive";
 //#endregion
 
-//#region utils (direct exports)
+//#region utils (직접 내보내기)
 export * from "./utils/template-strings";
 export * from "./utils/zip";
 //#endregion
 
-//#region type utilities
+//#region 타입 유틸리티
 export * from "./common.types";
 //#endregion