@simplysm/service-common 13.0.100 → 14.0.4

package/src/define-event.ts

@@ -1,25 +1,25 @@
 /**
- * Event definition created by defineEvent().
- * $info and $data are type-only markers (not used at runtime).
+ * defineEvent()로 생성된 이벤트 정의.
+ * $info와 $data는 타입 전용 마커임 (런타임에서는 사용되지 않음).
  */
 export interface ServiceEventDef<TInfo = unknown, TData = unknown> {
   eventName: string;
-  /** Type extraction only (not used at runtime) */
+  /** 타입 추출 전용 (런타임에서는 사용되지 않음) */
   readonly $info: TInfo;
-  /** Type extraction only (not used at runtime) */
+  /** 타입 추출 전용 (런타임에서는 사용되지 않음) */
   readonly $data: TData;
 }
 
 /**
- * Define a service event with type-safe info and data.
+ * 타입 안전한 info와 data를 가진 서비스 이벤트를 정의한다.
  *
  * @example
  * const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
  *
- * // Server emit
+ * // 서버에서 이벤트 발생
  * ctx.socket?.emitEvent(OrderUpdated, { orderId: 123 }, { status: "shipped" });
  *
- * // Client subscribe
+ * // 클라이언트에서 구독
  * await client.addEventListener(OrderUpdated, { orderId: 123 }, (data) => {
  *   console.log(data.status); // typed
  * });

package/src/index.ts

@@ -1,14 +1,12 @@
-// Protocol
+// 프로토콜
 export * from "./protocol/protocol.types";
 export * from "./protocol/create-service-protocol";
 
-// Service Types
+// 서비스 타입
 export * from "./service-types/orm-service.types";
 export * from "./service-types/auto-update-service.types";
-export * from "./service-types/smtp-client-service.types";
-
-// Types
+// 타입
 export * from "./types";
 
-// Define
+// 정의
 export * from "./define-event";

package/src/protocol/create-service-protocol.ts

@@ -10,56 +10,56 @@ import {
 import { PROTOCOL_CONFIG, type ServiceMessage } from "./protocol.types";
 
 /**
- * Service protocol interface
+ * 서비스 프로토콜 인터페이스
  *
- * Binary Protocol V2:
- * - Header: 28 bytes (UUID 16 + TotalSize 8 + Index 4)
- * - Body: JSON
- * - Auto chunking: splits into 300KB chunks when exceeding 3MB
- * - Max message size: 100MB
+ * 바이너리 프로토콜 V2:
+ * - 헤더: 28바이트 (UUID 16 + TotalSize 8 + Index 4)
+ * - 본문: JSON
+ * - 자동 청킹: 3MB 초과 시 300KB 청크로 분할
+ * - 최대 메시지 크기: 100MB
  */
 export interface ServiceProtocol {
   /**
-   * Encode a message (auto-split if needed)
+   * 메시지를 인코딩한다 (필요 시 자동 분할)
    */
   encode(uuid: string, message: ServiceMessage): { chunks: Bytes[]; totalSize: number };
 
   /**
-   * Decode a message (auto-reassemble chunked packets)
+   * 메시지를 디코딩한다 (청크 패킷 자동 재조립)
    */
   decode<T extends ServiceMessage>(bytes: Bytes): ServiceMessageDecodeResult<T>;
 
   /**
-   * Dispose the protocol instance.
+   * 프로토콜 인스턴스를 해제한다.
    *
-   * Releases the internal chunk accumulator's GC timer and frees memory.
-   * Must be called when the protocol instance is no longer needed.
+   * 내부 청크 누적기의 GC 타이머를 해제하고 메모리를 반환한다.
+   * 프로토콜 인스턴스가 더 이상 필요하지 않을 때 반드시 호출해야 한다.
    */
   dispose(): void;
 }
 
 /**
- * Message decode result type (union)
+ * 메시지 디코딩 결과 타입 (유니언)
  *
- * - `type: "complete"`: all chunks received and message reassembly is complete
- * - `type: "progress"`: chunked message in progress (only some chunks arrived)
+ * - `type: "complete"`: 모든 청크를 수신하여 메시지 재조립이 완료됨
+ * - `type: "progress"`: 청크 메시지 진행 중 (일부 청크만 도착)
  */
 export type ServiceMessageDecodeResult<TMessage extends ServiceMessage> =
   | { type: "complete"; uuid: string; message: TMessage }
   | { type: "progress"; uuid: string; totalSize: number; completedSize: number };
 
 /**
- * Create a service protocol encoder/decoder
+ * 서비스 프로토콜 인코더/디코더를 생성한다
  *
- * Binary Protocol V2:
- * - Header: 28 bytes (UUID 16 + TotalSize 8 + Index 4)
- * - Body: JSON
- * - Auto chunking: splits into 300KB chunks when exceeding 3MB
- * - Max message size: 100MB
+ * 바이너리 프로토콜 V2:
+ * - 헤더: 28바이트 (UUID 16 + TotalSize 8 + Index 4)
+ * - 본문: JSON
+ * - 자동 청킹: 3MB 초과 시 300KB 청크로 분할
+ * - 최대 메시지 크기: 100MB
  */
 export function createServiceProtocol(): ServiceProtocol {
   // -------------------------------------------------------------------
-  // State
+  // 상태
   // -------------------------------------------------------------------
 
   const accumulator = new LazyGcMap<
@@ -75,17 +75,17 @@ export function createServiceProtocol(): ServiceProtocol {
   });
 
   // -------------------------------------------------------------------
-  // Encoding Helper
+  // 인코딩 헬퍼
   // -------------------------------------------------------------------
 
   /**
-   * Encode a message chunk (header + body)
+   * 메시지 청크를 인코딩한다 (헤더 + 본문)
    *
-   * Header structure (28 bytes, Big Endian):
+   * 헤더 구조 (28바이트, Big Endian):
    * ```
    * Offset  Size  Field
    * ------  ----  -----
-   *   0     16    UUID (binary)
+   *   0     16    UUID (바이너리)
    *  16      8    TotalSize (uint64)
    *  24      4    Index (uint32)
    * ```
@@ -110,14 +110,15 @@ export function createServiceProtocol(): ServiceProtocol {
       headerBytes.byteOffset,
       headerBytes.byteLength,
     );
-    headerView.setBigUint64(16, BigInt(header.totalSize), false);
+    headerView.setUint32(16, 0, false); // 상위 4바이트 = 0 (MAX_TOTAL_SIZE < 2^32)
+    headerView.setUint32(20, header.totalSize, false); // 하위 4바이트 = totalSize
     headerView.setUint32(24, header.index, false);
 
     return bytesU.concat([headerBytes, ...(bodyBytes ? [bodyBytes] : [])]);
   }
 
   // -------------------------------------------------------------------
-  // Public API
+  // 공개 API
   // -------------------------------------------------------------------
 
   return {
@@ -127,20 +128,20 @@ export function createServiceProtocol(): ServiceProtocol {
 
       const totalSize = msgBytes.length;
 
-      // Total size limit check (performed first)
+      // 전체 크기 제한 확인 (우선 수행)
       if (totalSize > PROTOCOL_CONFIG.MAX_TOTAL_SIZE) {
-        throw new ArgumentError("Message size exceeds the limit.", {
+        throw new ArgumentError("메시지 크기가 제한을 초과했습니다.", {
           totalSize,
           maxSize: PROTOCOL_CONFIG.MAX_TOTAL_SIZE,
         });
       }
 
-      // Return as-is if small enough
+      // 충분히 작으면 그대로 반환
       if (totalSize <= PROTOCOL_CONFIG.SPLIT_MESSAGE_SIZE) {
         return { chunks: [encodeChunk({ uuid, totalSize, index: 0 }, msgBytes)], totalSize };
       }
 
-      // Split into chunks
+      // 청크로 분할
       const chunks: Bytes[] = [];
       let offset = 0;
       let index = 0;
@@ -160,13 +161,13 @@ export function createServiceProtocol(): ServiceProtocol {
 
     decode<T extends ServiceMessage>(bytes: Bytes): ServiceMessageDecodeResult<T> {
       if (bytes.length < 28) {
-        throw new ArgumentError("Buffer size is smaller than header size.", {
+        throw new ArgumentError("버퍼 크기가 헤더 크기보다 작습니다.", {
           bufferSize: bytes.length,
           minimumSize: 28,
         });
       }
 
-      // 1. Read header
+      // 1. 헤더 읽기
 
       // UUID
       const uuidBytes = bytes.subarray(0, 16);
@@ -174,12 +175,12 @@ export function createServiceProtocol(): ServiceProtocol {
 
       // TOTAL_SIZE, INDEX
       const headerView = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-      const totalSize = Number(headerView.getBigUint64(16, false));
+      const totalSize = headerView.getUint32(20, false); // 하위 4바이트만 읽기
       const index = headerView.getUint32(24, false);
 
-      // Total size limit check (performed first)
+      // 전체 크기 제한 확인 (우선 수행)
       if (totalSize > PROTOCOL_CONFIG.MAX_TOTAL_SIZE) {
-        throw new ArgumentError("Message size exceeds the limit.", {
+        throw new ArgumentError("메시지 크기가 제한을 초과했습니다.", {
           totalSize,
           maxSize: PROTOCOL_CONFIG.MAX_TOTAL_SIZE,
         });
@@ -193,7 +194,7 @@ export function createServiceProtocol(): ServiceProtocol {
         chunks: [],
       }));
       if (accItem.chunks[index] == null) {
-        // Duplicate packet guard
+        // 중복 패킷 방어
         accItem.chunks[index] = bodyBytes;
         accItem.completedSize += bodyBytes.length;
       }
@@ -205,15 +206,15 @@ export function createServiceProtocol(): ServiceProtocol {
           totalSize: totalSize,
           completedSize: accItem.completedSize,
         };
-      } else {
-        accumulator.delete(uuid); // Free memory
+      } else if (accItem.completedSize === accItem.totalSize) {
+        accumulator.delete(uuid); // 메모리 해제
 
         const resultBytes = bytesU.concat(accItem.chunks.filterExists());
         let messageArr: [string, unknown];
         try {
           messageArr = json.parse<[string, unknown]>(new TextDecoder().decode(resultBytes));
         } catch (err) {
-          throw new ArgumentError("Failed to decode message.", { uuid, cause: err });
+          throw new ArgumentError("메시지 디코딩에 실패했습니다.", { uuid, cause: err });
         }
         return {
           type: "complete",
@@ -223,6 +224,13 @@ export function createServiceProtocol(): ServiceProtocol {
             body: messageArr[1],
           } as T,
         };
+      } else {
+        accumulator.delete(uuid);
+        throw new ArgumentError("프로토콜 무결성 위반: completedSize가 totalSize를 초과했습니다.", {
+          uuid,
+          completedSize: accItem.completedSize,
+          totalSize: accItem.totalSize,
+        });
       }
     },
 

package/src/protocol/protocol.types.ts

@@ -1,27 +1,26 @@
 // ----------------------------------------------------------------------
-// Protocol Constants
+// 프로토콜 상수
 // ----------------------------------------------------------------------
 
-/** Service protocol configuration */
+/** 서비스 프로토콜 설정 */
 export const PROTOCOL_CONFIG = {
-  /** Max message size (100MB) */
+  /** 최대 메시지 크기 (100MB) */
   MAX_TOTAL_SIZE: 100 * 1024 * 1024,
-  /** Chunking threshold (3MB) */
+  /** 청킹 임계값 (3MB) */
   SPLIT_MESSAGE_SIZE: 3 * 1024 * 1024,
-  /** Chunk size (300KB) */
+  /** 청크 크기 (300KB) */
   CHUNK_SIZE: 300 * 1024,
-  /** GC interval (10s) */
+  /** GC 주기 (10초) */
   GC_INTERVAL: 10 * 1000,
-  /** Incomplete message expiry time (60s) */
+  /** 미완성 메시지 만료 시간 (60초) */
   EXPIRE_TIME: 60 * 1000,
 } as const;
 
 // ----------------------------------------------------------------------
-// Message Types
+// 메시지 타입
 // ----------------------------------------------------------------------
 
 export type ServiceMessage =
-  | ServiceReloadMessage
   | ServiceRequestMessage
   | ServiceAuthMessage
   | ServiceProgressMessage
@@ -34,10 +33,9 @@ export type ServiceMessage =
   | ServiceEventMessage;
 
 export type ServiceServerMessage =
-  | ServiceReloadMessage // Notification
   | ServiceResponseMessage
   | ServiceErrorMessage
-  | ServiceEventMessage; // Notification
+  | ServiceEventMessage; // 알림
 
 export type ServiceServerRawMessage = ServiceProgressMessage | ServiceServerMessage;
 
@@ -50,28 +48,19 @@ export type ServiceClientMessage =
   | ServiceEmitEventMessage;
 
 // ----------------------------------------------------------------------
-// System (common)
+// 시스템 (공통)
 // ----------------------------------------------------------------------
 
-/** Server: reload command to client */
-export interface ServiceReloadMessage {
-  name: "reload";
-  body: {
-    clientName: string | undefined; // Client name
-    changedFileSet: Set<string>; // Changed file list
-  };
-}
-
-/** Server: progress notification for received chunked message */
+/** 서버: 수신된 청크 메시지의 진행 상태 알림 */
 export interface ServiceProgressMessage {
   name: "progress";
   body: {
-    totalSize: number; // Total size (bytes)
-    completedSize: number; // Completed size (bytes)
+    totalSize: number; // 전체 크기 (바이트)
+    completedSize: number; // 완료된 크기 (바이트)
   };
 }
 
-/** Server: error notification */
+/** 서버: 에러 알림 */
 export interface ServiceErrorMessage {
   name: "error";
   body: {
@@ -84,72 +73,72 @@ export interface ServiceErrorMessage {
   };
 }
 
-/** Client: authentication message */
+/** 클라이언트: 인증 메시지 */
 export interface ServiceAuthMessage {
   name: "auth";
-  body: string; // Token
+  body: string; // 토큰
 }
 
 // ----------------------------------------------------------------------
 // Service.Method
 // ----------------------------------------------------------------------
 
-/** Client: service method request */
+/** 클라이언트: 서비스 메서드 요청 */
 export interface ServiceRequestMessage {
   name: `${string}.${string}`; // ${service}.${method}
-  body: unknown[]; // params
+  body: unknown[]; // 매개변수
 }
 
-/** Server: service method response */
+/** 서버: 서비스 메서드 응답 */
 export interface ServiceResponseMessage {
   name: "response";
-  body?: unknown; // result
+  body?: unknown; // 결과
 }
 
 // ----------------------------------------------------------------------
-// Events
+// 이벤트
 // ----------------------------------------------------------------------
 
-/** Client: add event listener */
+/** 클라이언트: 이벤트 리스너 추가 */
 export interface ServiceAddEventListenerMessage {
   name: "evt:add";
   body: {
-    key: string; // Listener key (uuid) - needed for removeEventListener
-    name: string; // Event name (Type.name)
-    info: unknown; // Additional listener info for filtering when events fire
+    key: string; // 리스너 키 (uuid) - removeEventListener에 필요
+    name: string; // 이벤트 이름 (Type.name)
+    info: unknown; // 이벤트 발생 시 필터링을 위한 추가 리스너 정보
   };
 }
 
-/** Client: remove event listener */
+/** 클라이언트: 이벤트 리스너 제거 */
 export interface ServiceRemoveEventListenerMessage {
   name: "evt:remove";
   body: {
-    key: string; // Listener key (uuid)
+    key: string; // 리스너 키 (uuid)
   };
 }
 
-/** Client: request event listener info list */
+/** 클라이언트: 이벤트 리스너 정보 목록 요청 */
 export interface ServiceGetEventListenerInfosMessage {
   name: "evt:gets";
   body: {
-    name: string; // Event name
+    name: string; // 이벤트 이름
   };
 }
 
-/** Client: emit event */
+/** 클라이언트: 이벤트 발생 */
 export interface ServiceEmitEventMessage {
   name: "evt:emit";
   body: {
-    keys: string[]; // Listener key list
-    data: unknown; // Data
+    keys: string[]; // 리스너 키 목록
+    data: unknown; // 데이터
   };
 }
 
-/** Server: event notification */
+/** 서버: 이벤트 알림 */
 export interface ServiceEventMessage {
   name: "evt:on";
   body: {
-    keys: string[]; // Listener key list
-    data: unknown; // Data
+    keys: string[]; // 리스너 키 목록
+    data: unknown; // 데이터
   };
 }

package/src/service-types/auto-update-service.types.ts

@@ -1,13 +1,13 @@
 /**
- * Auto-update service interface
+ * 자동 업데이트 서비스 인터페이스
  *
- * Retrieves the latest version info for client applications.
+ * 클라이언트 애플리케이션의 최신 버전 정보를 조회한다.
  */
 export interface AutoUpdateService {
   /**
-   * Retrieve the latest version info for the specified platform.
-   * @param platform Target platform (e.g., "win32", "darwin", "linux")
-   * @returns Latest version info, or undefined if no version exists
+   * 지정된 플랫폼의 최신 버전 정보를 조회한다.
+   * @param platform 대상 플랫폼 (예: "win32", "darwin", "linux")
+   * @returns 최신 버전 정보, 버전이 없으면 undefined
    */
   getLastVersion(platform: string): Promise<
     | {

package/src/service-types/orm-service.types.ts

@@ -7,10 +7,10 @@ import type {
 } from "@simplysm/orm-common";
 
 /**
- * ORM service interface
+ * ORM 서비스 인터페이스
  *
- * Provides database connection, transaction management, and query execution.
- * Supports MySQL, MSSQL, and PostgreSQL.
+ * 데이터베이스 연결, 트랜잭션 관리, 쿼리 실행을 제공한다.
+ * MySQL, MSSQL, PostgreSQL을 지원한다.
  */
 export interface OrmService {
   getInfo(opt: DbConnOptions & { configName: string }): Promise<{
@@ -19,7 +19,7 @@ export interface OrmService {
     schema?: string;
   }>;
 
-  connect(opt: Record<string, unknown>): Promise<number>;
+  connect(opt: DbConnOptions & { configName: string }): Promise<number>;
 
   close(connId: number): Promise<void>;
 
@@ -45,5 +45,5 @@ export interface OrmService {
   ): Promise<void>;
 }
 
-/** Database connection options */
+/** 데이터베이스 연결 옵션 */
 export type DbConnOptions = { configName?: string; config?: Record<string, unknown> };

package/src/types.ts

@@ -1,13 +1,13 @@
 /**
- * File upload result
+ * 파일 업로드 결과
  *
- * Contains information about a file uploaded to the server.
+ * 서버에 업로드된 파일의 정보를 포함한다.
  */
 export interface ServiceUploadResult {
-  /** Storage path on the server */
+  /** 서버 내 저장 경로 */
   path: string;
-  /** Original filename */
+  /** 원본 파일명 */
   filename: string;
-  /** File size (bytes) */
+  /** 파일 크기 (바이트) */
   size: number;
 }

package/dist/service-types/smtp-client-service.types.d.ts

@@ -1,38 +0,0 @@
-export interface SmtpClientSendAttachment {
-    filename: string;
-    content?: string | Uint8Array;
-    path?: any;
-    contentType?: string;
-}
-export interface SmtpClientSendByDefaultOption {
-    to: string;
-    cc?: string;
-    bcc?: string;
-    subject: string;
-    html: string;
-    attachments?: SmtpClientSendAttachment[];
-}
-export interface SmtpClientSendOption {
-    host: string;
-    port?: number;
-    secure?: boolean;
-    user?: string;
-    pass?: string;
-    from: string;
-    to: string;
-    cc?: string;
-    bcc?: string;
-    subject: string;
-    html: string;
-    attachments?: SmtpClientSendAttachment[];
-}
-export interface SmtpClientDefaultOptions {
-    senderName: string;
-    senderEmail?: string;
-    user?: string;
-    pass?: string;
-    host: string;
-    port?: number;
-    secure?: boolean;
-}
-//# sourceMappingURL=smtp-client-service.types.d.ts.map

package/dist/service-types/smtp-client-service.types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"smtp-client-service.types.d.ts","sourceRoot":"","sources":["..\\..\\src\\service-types\\smtp-client-service.types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC9B,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,6BAA6B;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}

package/dist/service-types/smtp-client-service.types.js

@@ -1 +0,0 @@
-//# sourceMappingURL=smtp-client-service.types.js.map

package/dist/service-types/smtp-client-service.types.js.map

@@ -1,6 +0,0 @@
-{
-  "version": 3,
-  "sources": [],
-  "mappings": "",
-  "names": []
-}

package/docs/events.md

@@ -1,51 +0,0 @@
-# Event Definition
-
-## `ServiceEventDef`
-
-Event definition created by `defineEvent()`. `$info` and `$data` are type-only markers (not used at runtime).
-
-```typescript
-interface ServiceEventDef<TInfo = unknown, TData = unknown> {
-  eventName: string;
-  readonly $info: TInfo;
-  readonly $data: TData;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `eventName` | `string` | Event name |
-| `$info` | `TInfo` | Type extraction only (listener filter info type) |
-| `$data` | `TData` | Type extraction only (event data type) |
-
-## `defineEvent`
-
-Define a service event with type-safe info and data.
-
-```typescript
-function defineEvent<TInfo = unknown, TData = unknown>(
-  eventName: string,
-): ServiceEventDef<TInfo, TData>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `eventName` | `string` | Event name |
-
-## `ServiceUploadResult`
-
-File upload result. Contains information about a file uploaded to the server.
-
-```typescript
-interface ServiceUploadResult {
-  path: string;
-  filename: string;
-  size: number;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `path` | `string` | Storage path on the server |
-| `filename` | `string` | Original filename |
-| `size` | `number` | File size (bytes) |