@simplysm/service-common 13.0.69 → 13.0.70

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@simplysm/service-common",
-  "version": "13.0.69",
-  "description": "심플리즘 패키지 - 서비스 모듈 (common)",
-  "author": "김석래",
+  "version": "13.0.70",
+  "description": "Simplysm package - Service module (common)",
+  "author": "simplysm",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -14,11 +14,12 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "tests"
   ],
   "sideEffects": false,
   "dependencies": {
-    "@simplysm/core-common": "13.0.69",
-    "@simplysm/orm-common": "13.0.69"
+    "@simplysm/core-common": "13.0.70",
+    "@simplysm/orm-common": "13.0.70"
   }
 }

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

@@ -11,52 +11,52 @@ 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
- * - 자동 청킹: 3MB 초과 시 300KB 단위 분할
- * - 최대 메시지: 100MB
+ * - Auto chunking: splits into 300KB chunks when exceeding 3MB
+ * - Max message size: 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.
    *
-   * 내부 청크 누적기의 GC 타이머를 해제하고 메모리를 정리한다.
-   * 프로토콜 인스턴스 사용이 끝나면 반드시 호출해야 한다.
+   * Releases the internal chunk accumulator's GC timer and frees memory.
+   * Must be called when the protocol instance is no longer needed.
    */
   dispose(): void;
 }
 
 /**
- * 메시지 디코딩 결과 타입 (유니온)
+ * Message decode result type (union)
  *
- * - `type: "complete"`: 모든 청크가 수신되어 메시지 조립이 완료됨
- * - `type: "progress"`: 분할 메시지 수신 중 (일부 청크만 도착)
+ * - `type: "complete"`: all chunks received and message reassembly is complete
+ * - `type: "progress"`: chunked message in progress (only some chunks arrived)
  */
 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
- * - 자동 청킹: 3MB 초과 시 300KB 단위 분할
- * - 최대 메시지: 100MB
+ * - Auto chunking: splits into 300KB chunks when exceeding 3MB
+ * - Max message size: 100MB
  */
 export function createServiceProtocol(): ServiceProtocol {
   // -------------------------------------------------------------------
@@ -80,9 +80,9 @@ export function createServiceProtocol(): ServiceProtocol {
   // -------------------------------------------------------------------
 
   /**
-   * 메시지 청크 인코딩 (헤더 + 바디)
+   * Encode a message chunk (header + body)
    *
-   * 헤더 구조 (28 bytes, Big Endian):
+   * Header structure (28 bytes, Big Endian):
    * ```
    * Offset  Size  Field
    * ------  ----  -----
@@ -128,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("메시지 크기가 제한을 초과했습니다.", {
+        throw new ArgumentError("Message size exceeds the limit.", {
           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;
@@ -161,13 +161,13 @@ export function createServiceProtocol(): ServiceProtocol {
 
     decode<T extends ServiceMessage>(bytes: Bytes): ServiceMessageDecodeResult<T> {
       if (bytes.length < 28) {
-        throw new ArgumentError("버퍼 크기가 헤더 크기보다 작습니다.", {
+        throw new ArgumentError("Buffer size is smaller than header size.", {
           bufferSize: bytes.length,
           minimumSize: 28,
         });
       }
 
-      // 1. 헤더 읽기
+      // 1. Read header
 
       // UUID
       const uuidBytes = bytes.subarray(0, 16);
@@ -178,9 +178,9 @@ export function createServiceProtocol(): ServiceProtocol {
       const totalSize = Number(headerView.getBigUint64(16, false));
       const index = headerView.getUint32(24, false);
 
-      // 전체 사이즈 제한 체크 (가장 먼저 수행)
+      // Total size limit check (performed first)
       if (totalSize > PROTOCOL_CONFIG.MAX_TOTAL_SIZE) {
-        throw new ArgumentError("메시지 크기가 제한을 초과했습니다.", {
+        throw new ArgumentError("Message size exceeds the limit.", {
           totalSize,
           maxSize: PROTOCOL_CONFIG.MAX_TOTAL_SIZE,
         });
@@ -194,7 +194,7 @@ export function createServiceProtocol(): ServiceProtocol {
         chunks: [],
       }));
       if (accItem.chunks[index] == null) {
-        // 패킷중복 방어
+        // Duplicate packet guard
         accItem.chunks[index] = bodyBytes;
         accItem.completedSize += bodyBytes.length;
       }
@@ -207,14 +207,14 @@ export function createServiceProtocol(): ServiceProtocol {
           completedSize: accItem.completedSize,
         };
       } else {
-        accumulator.delete(uuid); // 메모리 해제
+        accumulator.delete(uuid); // Free memory
 
         const resultBytes = bytesConcat(accItem.chunks.filterExists());
         let messageArr: [string, unknown];
         try {
           messageArr = jsonParse<[string, unknown]>(new TextDecoder().decode(resultBytes));
         } catch (err) {
-          throw new ArgumentError("메시지 디코딩에 실패했습니다.", { uuid, cause: err });
+          throw new ArgumentError("Failed to decode message.", { uuid, cause: err });
         }
         return {
           type: "complete",

package/src/protocol/protocol.types.ts

@@ -2,17 +2,17 @@
 // Protocol Constants
 // ----------------------------------------------------------------------
 
-/** 서비스 프로토콜 설정 */
+/** Service protocol configuration */
 export const PROTOCOL_CONFIG = {
-  /** 최대 메시지 크기 (100MB) */
+  /** Max message size (100MB) */
   MAX_TOTAL_SIZE: 100 * 1024 * 1024,
-  /** 청킹 임계값 (3MB) */
+  /** Chunking threshold (3MB) */
   SPLIT_MESSAGE_SIZE: 3 * 1024 * 1024,
-  /** 청크 크기 (300KB) */
+  /** Chunk size (300KB) */
   CHUNK_SIZE: 300 * 1024,
-  /** GC 주기 (10초) */
+  /** GC interval (10s) */
   GC_INTERVAL: 10 * 1000,
-  /** 미완성 메시지 만료 시간 (60초) */
+  /** Incomplete message expiry time (60s) */
   EXPIRE_TIME: 60 * 1000,
 } as const;
 
@@ -34,10 +34,10 @@ export type ServiceMessage =
   | ServiceEventMessage;
 
 export type ServiceServerMessage =
-  | ServiceReloadMessage // 알림
+  | ServiceReloadMessage // Notification
   | ServiceResponseMessage
   | ServiceErrorMessage
-  | ServiceEventMessage; // 알림
+  | ServiceEventMessage; // Notification
 
 export type ServiceServerRawMessage = ServiceProgressMessage | ServiceServerMessage;
 
@@ -50,28 +50,28 @@ export type ServiceClientMessage =
   | ServiceEmitEventMessage;
 
 // ----------------------------------------------------------------------
-// System 공통
+// System (common)
 // ----------------------------------------------------------------------
 
-/** 서버: 클라이언트에게 reload 명령 */
+/** Server: reload command to client */
 export interface ServiceReloadMessage {
   name: "reload";
   body: {
-    clientName: string | undefined; // 클라이언트명
-    changedFileSet: Set<string>; // 변경파일목록
+    clientName: string | undefined; // Client name
+    changedFileSet: Set<string>; // Changed file list
   };
 }
 
-/** 서버: 받은 분할메시지에 대한 progress 알림 */
+/** Server: progress notification for received chunked message */
 export interface ServiceProgressMessage {
   name: "progress";
   body: {
-    totalSize: number; // 총 크기 (Bytes)
-    completedSize: number; // 완료된 크기 (Bytes)
+    totalSize: number; // Total size (bytes)
+    completedSize: number; // Completed size (bytes)
   };
 }
 
-/** 서버: 에러 발생 알림 */
+/** Server: error notification */
 export interface ServiceErrorMessage {
   name: "error";
   body: {
@@ -84,72 +84,72 @@ export interface ServiceErrorMessage {
   };
 }
 
-/** 클라: 인증 메시지 */
+/** Client: authentication message */
 export interface ServiceAuthMessage {
   name: "auth";
-  body: string; // 토큰
+  body: string; // Token
 }
 
 // ----------------------------------------------------------------------
 // Service.Method
 // ----------------------------------------------------------------------
 
-/** 클라: ServiceMethod 요청 */
+/** Client: service method request */
 export interface ServiceRequestMessage {
   name: `${string}.${string}`; // ${service}.${method}
   body: unknown[]; // params
 }
 
-/** 서버: ServiceMethod 응답 */
+/** Server: service method response */
 export interface ServiceResponseMessage {
   name: "response";
   body?: unknown; // result
 }
 
 // ----------------------------------------------------------------------
-// 이벤트
+// Events
 // ----------------------------------------------------------------------
 
-/** 클라: 이벤트 리스너 등록 */
+/** Client: add event listener */
 export interface ServiceAddEventListenerMessage {
   name: "evt:add";
   body: {
-    key: string; // 리스너키 (uuid) - 차후 removeEventListener를 위해서라도 필요함
-    name: string; // 이벤트명 (Type.name)
-    info: unknown; // 이벤트 발생시, 리스너 필터링이 가능하도록 하기 위한 "추가 리스너 정보"
+    key: string; // Listener key (uuid) - needed for removeEventListener
+    name: string; // Event name (Type.name)
+    info: unknown; // Additional listener info for filtering when events fire
   };
 }
 
-/** 클라: 이벤트 리스너 제거 */
+/** Client: remove event listener */
 export interface ServiceRemoveEventListenerMessage {
   name: "evt:remove";
   body: {
-    key: string; // 리스너키 (uuid)
+    key: string; // Listener key (uuid)
   };
 }
 
-/** 클라: 이벤트 리스너 정보 목록 요청 */
+/** Client: request event listener info list */
 export interface ServiceGetEventListenerInfosMessage {
   name: "evt:gets";
   body: {
-    name: string; // 이벤트명
+    name: string; // Event name
   };
 }
 
-/** 클라: 이벤트 발생 */
+/** Client: emit event */
 export interface ServiceEmitEventMessage {
   name: "evt:emit";
   body: {
-    keys: string[]; // 리스너키 목록
-    data: unknown; // 데이터
+    keys: string[]; // Listener key list
+    data: unknown; // Data
   };
 }
 
-/** 서버: 이벤트 발생 알림 */
+/** Server: event notification */
 export interface ServiceEventMessage {
   name: "evt:on";
   body: {
-    keys: string[]; // 리스너키 목록
-    data: unknown; // 데이터
+    keys: string[]; // Listener key list
+    data: unknown; // Data
   };
 }

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 {
   /**
-   * 지정된 플랫폼의 최신 버전 정보를 조회한다.
-   * @param platform 대상 플랫폼 (예: "win32", "darwin", "linux")
-   * @returns 최신 버전 정보. 버전이 없으면 undefined
+   * 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
    */
   getLastVersion(platform: string): Promise<
     | {

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

@@ -7,10 +7,10 @@ import type {
 } from "@simplysm/orm-common";
 
 /**
- * ORM 서비스 인터페이스
+ * ORM service interface
  *
- * 데이터베이스 연결, 트랜잭션 관리, 쿼리 실행 기능을 제공한다.
- * MySQL, MSSQL, PostgreSQL을 지원한다.
+ * Provides database connection, transaction management, and query execution.
+ * Supports MySQL, MSSQL, and PostgreSQL.
  */
 export interface OrmService {
   getInfo(opt: DbConnOptions & { configName: string }): Promise<{
@@ -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;
-  /** 파일 크기 (bytes) */
+  /** File size (bytes) */
   size: number;
 }

package/tests/define-event.spec.ts

@@ -0,0 +1,21 @@
+// packages/service-common/tests/define-event.spec.ts
+import { describe, it, expect } from "vitest";
+import { defineEvent } from "@simplysm/service-common";
+
+describe("defineEvent", () => {
+  it("create event definition with given name", () => {
+    const evt = defineEvent<{ channel: string }, string>("OrderUpdated");
+    expect(evt.eventName).toBe("OrderUpdated");
+  });
+
+  it("can be used for type inference (checked at compile time)", () => {
+    const _evt = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
+
+    // Type level verification — fails at compile time if incorrect
+    const info: typeof _evt.$info = { orderId: 123 };
+    const data: typeof _evt.$data = { status: "shipped" };
+
+    expect(info.orderId).toBe(123);
+    expect(data.status).toBe("shipped");
+  });
+});