@simplysm/service-client 13.0.100 → 14.0.1

package/src/service-client.ts

@@ -9,27 +9,29 @@ import { createServiceTransport, type ServiceTransport } from "./transport/servi
 import { createSocketProvider, type SocketProvider } from "./transport/socket-provider";
 import { createEventClient, type EventClient } from "./features/event-client";
 import { createFileClient, type FileClient } from "./features/file-client";
-import { createClientProtocolWrapper } from "./protocol/client-protocol-wrapper";
+import { createClientProtocolWrapper, type ClientProtocolWrapper } from "./protocol/client-protocol-wrapper";
 
 const logger = consola.withTag("service-client:ServiceClient");
 
 interface ServiceClientEvents {
   "request-progress": ServiceProgressState;
   "response-progress": ServiceProgressState;
+  "server-progress": ServiceProgressState;
   "state": "connected" | "closed" | "reconnecting";
   "reload": Set<string>;
 }
 
 export class ServiceClient extends EventEmitter<ServiceClientEvents> {
-  // Modules
+  // 모듈
   private readonly _socket: SocketProvider;
   private readonly _transport: ServiceTransport;
   private readonly _eventClient: EventClient;
   private readonly _fileClient: FileClient;
 
+  private readonly _protocolWrapper: ClientProtocolWrapper;
   private _authToken?: string;
 
-  // State accessors
+  // 상태 접근자
   get connected() {
     return this._socket.connected;
   }
@@ -47,27 +49,27 @@ export class ServiceClient extends EventEmitter<ServiceClientEvents> {
     const wsProtocol = options.ssl ? "wss" : "ws";
     const wsUrl = `${wsProtocol}://${options.host}:${options.port}/ws`;
 
-    // Initialize modules
+    // 모듈 초기화
     this._socket = createSocketProvider(wsUrl, this.name, this.options.maxReconnectCount ?? 10);
     const protocol = createServiceProtocol();
-    const protocolWrapper = createClientProtocolWrapper(protocol);
-    this._transport = createServiceTransport(this._socket, protocolWrapper);
+    this._protocolWrapper = createClientProtocolWrapper(protocol);
+    this._transport = createServiceTransport(this._socket, this._protocolWrapper);
     this._eventClient = createEventClient(this._transport);
     this._fileClient = createFileClient(this.hostUrl, this.name);
 
-    // Event bindings
+    // 이벤트 바인딩
     this._socket.on("state", async (state) => {
       this.emit("state", state);
 
-      // Auto-recover event listeners on reconnect
+      // 재연결 시 이벤트 리스너 자동 복구
       if (state === "connected") {
         try {
           if (this._authToken != null) {
-            await this.auth(this._authToken); // Re-authenticate
+            await this.auth(this._authToken); // 재인증
           }
           await this._eventClient.resubscribeAll();
         } catch (err) {
-          logger.error("Failed to recover event listeners", err);
+          logger.error("이벤트 리스너 복구 실패", err);
         }
       }
     });
@@ -77,7 +79,7 @@ export class ServiceClient extends EventEmitter<ServiceClientEvents> {
     });
   }
 
-  // Proxy creation method for type safety
+  // 타입 안전성을 위한 프록시 생성 메서드
   getService<TService>(serviceName: string): ServiceProxy<TService> {
     return new Proxy({} as ServiceProxy<TService>, {
       get: (_target, prop) => {
@@ -95,6 +97,7 @@ export class ServiceClient extends EventEmitter<ServiceClientEvents> {
 
   async close(): Promise<void> {
     await this._socket.close();
+    this._protocolWrapper.dispose();
   }
 
   async send(
@@ -117,6 +120,10 @@ export class ServiceClient extends EventEmitter<ServiceClientEvents> {
           this.emit("response-progress", state);
           progress?.response?.(state);
         },
+        server: (state) => {
+          this.emit("server-progress", state);
+          progress?.server?.(state);
+        },
       },
     );
   }
@@ -131,7 +138,7 @@ export class ServiceClient extends EventEmitter<ServiceClientEvents> {
     info: TInfo,
     cb: (data: TData) => PromiseLike<void>,
   ): Promise<string> {
-    if (!this.connected) throw new Error("Not connected to the server.");
+    if (!this.connected) throw new Error("서버에 연결되지 않았습니다.");
     return this._eventClient.addListener(eventDef, info, cb);
   }
 
@@ -150,7 +157,7 @@ export class ServiceClient extends EventEmitter<ServiceClientEvents> {
   async uploadFile(files: File[] | FileList | { name: string; data: BlobPart }[]) {
     if (this._authToken == null) {
       throw new Error(
-        "No authentication token found. Call auth() to authenticate before uploading files.",
+        "인증 토큰이 없습니다. 파일 업로드 전에 auth()를 호출하여 인증해 주세요.",
       );
     }
     return this._fileClient.upload(files, this._authToken);
@@ -161,11 +168,11 @@ export class ServiceClient extends EventEmitter<ServiceClientEvents> {
   }
 }
 
-// Type transformer that wraps all method return types of TService with Promise
+// TService의 모든 메서드 반환 타입을 Promise로 래핑하는 타입 변환기
 export type ServiceProxy<TService> = {
   [K in keyof TService]: TService[K] extends (...args: infer P) => infer R
     ? (...args: P) => Promise<Awaited<R>>
-    : never; // Non-function properties are excluded
+    : never; // 함수가 아닌 속성은 제외
 };
 
 export function createServiceClient(name: string, options: ServiceConnectionOptions): ServiceClient {

package/src/transport/service-transport.ts

@@ -41,34 +41,34 @@ export function createServiceTransport(
     }
   >();
 
-  // Store response progress totalSize (for emitting 100% on complete)
+  // 응답 progress totalSize 저장 (완료 시 100% 전송용)
   const responseProgressTotalSize = new Map<string, number>();
 
   socket.on("message", onMessage);
 
-  // When socket disconnects, reject all pending requests to free memory
+  // 소켓 연결 끊김 시 메모리 해제를 위해 모든 대기 중인 요청을 reject
   socket.on("state", (state) => {
     if (state === "closed" || state === "reconnecting") {
-      cancelAllRequests("Socket connection lost");
+      cancelAllRequests("소켓 연결이 끊어졌습니다");
     }
   });
 
   async function send(message: ServiceClientMessage, progress?: ServiceProgress): Promise<unknown> {
     const uuid = Uuid.generate().toString();
 
-    // Start awaiting response (register listener before sending request for safety)
+    // 응답 대기 시작 (안전을 위해 요청 전송 전에 리스너 등록)
     const responsePromise = new Promise((resolve, reject) => {
       pendingRequests.set(uuid, { resolve, reject, progress });
     });
 
-    // Prevent unhandled rejection when the promise is orphaned (e.g., during HMR cleanup)
+    // Promise가 고아가 되었을 때 unhandled rejection 방지 (예: HMR 정리 중)
     responsePromise.catch(() => {});
 
-    // Send request
+    // 요청 전송
     try {
       const { chunks, totalSize } = await protocol.encode(uuid, message);
 
-      // Initialize progress
+      // progress 초기화
       if (chunks.length > 1) {
         progress?.request?.({
           uuid,
@@ -77,18 +77,18 @@ export function createServiceTransport(
         });
       }
 
-      // Send
+      // 전송
       for (const chunk of chunks) {
         await socket.send(chunk);
       }
     } catch (err) {
-      // Clean up immediately on send failure
+      // 전송 실패 시 즉시 정리
       pendingRequests.get(uuid)?.reject(err as Error);
       pendingRequests.delete(uuid);
       throw err;
     }
 
-    // Return response result
+    // 응답 결과 반환
     return responsePromise;
   }
 
@@ -99,7 +99,7 @@ export function createServiceTransport(
 
     try {
       if (decoded.type === "progress") {
-        // Remember totalSize (for emitting 100% on complete)
+        // totalSize 기억 (완료 시 100% 전송용)
         responseProgressTotalSize.set(decoded.uuid, decoded.totalSize);
 
         listenerInfo?.progress?.response?.({
@@ -110,13 +110,13 @@ export function createServiceTransport(
       } else {
         if (decoded.message.name === "progress") {
           const body = decoded.message.body as { totalSize: number; completedSize: number };
-          listenerInfo?.progress?.request?.({
+          listenerInfo?.progress?.server?.({
             uuid: decoded.uuid,
             totalSize: body.totalSize,
             completedSize: body.completedSize,
           });
         } else if (decoded.message.name === "response") {
-          // Emit 100% progress if it was a split message
+          // 분할 메시지였을 경우 100% progress 전송
           const totalSize = responseProgressTotalSize.get(decoded.uuid);
           if (totalSize != null) {
             responseProgressTotalSize.delete(decoded.uuid);
@@ -127,15 +127,15 @@ export function createServiceTransport(
             });
           }
 
-          // Remove from Map since response received
+          // 응답 수신으로 Map에서 제거
           pendingRequests.delete(decoded.uuid);
 
           listenerInfo?.resolve(decoded.message.body as ServiceResponseMessage);
         } else if (decoded.message.name === "error") {
-          // Clean up progress totalSize
+          // progress totalSize 정리
           responseProgressTotalSize.delete(decoded.uuid);
 
-          // Remove from Map since error received
+          // 에러 수신으로 Map에서 제거
           pendingRequests.delete(decoded.uuid);
 
           listenerInfo?.reject(toError(decoded.message.body));
@@ -148,7 +148,7 @@ export function createServiceTransport(
           const body = decoded.message.body as { keys: string[]; data: unknown };
           emitter.emit("event", { keys: body.keys, data: body.data });
         } else {
-          throw new Error("Invalid message received from server.");
+          throw new Error("서버로부터 잘못된 메시지를 수신했습니다.");
         }
       }
     } catch (err) {
@@ -156,10 +156,10 @@ export function createServiceTransport(
     }
   }
 
-  // Cancel all pending requests
+  // 모든 대기 중인 요청 취소
   function cancelAllRequests(reason: string): void {
     for (const listenerInfo of pendingRequests.values()) {
-      listenerInfo.reject(new Error(`Request canceled: ${reason}`));
+      listenerInfo.reject(new Error(`요청 취소됨: ${reason}`));
     }
     pendingRequests.clear();
     responseProgressTotalSize.clear();

package/src/transport/socket-provider.ts

@@ -30,15 +30,15 @@ export function createSocketProvider(
   clientName: string,
   maxReconnectCount: number,
 ): SocketProvider {
-  // Configuration constants
-  const HEARTBEAT_TIMEOUT = 30000; // Consider disconnected if no message for 30s
-  const HEARTBEAT_INTERVAL = 5000; // Send ping every 5s
-  const RECONNECT_DELAY = 3000; // Retry reconnect every 3s
+  // 설정 상수
+  const HEARTBEAT_TIMEOUT = 30000; // 30초 동안 메시지가 없으면 연결 끊김으로 간주
+  const HEARTBEAT_INTERVAL = 5000; // 5초마다 ping 전송
+  const RECONNECT_DELAY = 3000; // 3초마다 재연결 시도
 
-  // Pre-allocate 1-byte buffer (saves memory)
+  // 1바이트 버퍼 사전 할당 (메모리 절약)
   const PING_PACKET = new Uint8Array([0x01]);
 
-  // State
+  // 상태
   let ws: WebSocket | undefined;
   let isManualClose = false;
   let reconnectCount = 0;
@@ -58,10 +58,10 @@ export function createSocketProvider(
     try {
       await createSocket();
       startHeartbeat();
-      reconnectCount = 0; // Reset count on successful connection
+      reconnectCount = 0; // 연결 성공 시 카운트 초기화
       emitter.emit("state", "connected");
     } catch (err) {
-      // Throw on initial connection failure (so the caller can handle it)
+      // 초기 연결 실패 시 예외를 던짐 (호출자가 처리할 수 있도록)
       throw err;
     }
   }
@@ -72,7 +72,7 @@ export function createSocketProvider(
     const currentWs = ws;
     if (currentWs != null) {
       currentWs.close();
-      // Wait until fully closed (graceful shutdown)
+      // 완전히 닫힐 때까지 대기 (정상 종료)
       await wait.until(() => currentWs.readyState === WebSocket.CLOSED, 100, 30).catch(() => {});
     }
     emitter.emit("state", "closed");
@@ -82,11 +82,11 @@ export function createSocketProvider(
     try {
       await wait.until(() => isConnected(), undefined, 50);
     } catch {
-      throw new Error("Not connected to the server. Please check your internet connection.");
+      throw new Error("서버에 연결되지 않았습니다. 인터넷 연결을 확인해 주세요.");
     }
     const currentWs = ws;
     if (currentWs == null) {
-      throw new Error("WebSocket is not connected.");
+      throw new Error("WebSocket이 연결되지 않았습니다.");
     }
     currentWs.send(data);
   }
@@ -109,7 +109,7 @@ export function createSocketProvider(
       };
 
       newWs.onerror = (event: Event) => {
-        // Reject on error during connection
+        // 연결 중 에러 발생 시 reject
         if (!isConnected()) {
           const errorEvent = event as ErrorEvent;
           const msg = errorEvent.message;
@@ -118,21 +118,21 @@ export function createSocketProvider(
       };
     });
 
-    // At this point ws is always assigned (assigned in ws.onopen)
+    // 이 시점에서 ws는 항상 할당됨 (ws.onopen에서 할당됨)
     const currentWs = ws;
     if (currentWs == null) {
-      throw new Error("WebSocket initialization failed");
+      throw new Error("WebSocket 초기화 실패");
     }
 
     currentWs.onmessage = (event) => {
-      lastHeartbeatTime = Date.now(); // Update heartbeat
+      lastHeartbeatTime = Date.now(); // 하트비트 갱신
 
       const data = event.data as ArrayBuffer;
       const bytes = new Uint8Array(data);
 
-      // Raw Ping/Pong handling (checked first)
-      // If 1 byte and first byte is 0x02 (Pong), ignore
-      // (only heartbeat timestamp was updated, nothing else to do)
+      // Raw Ping/Pong 처리 (먼저 확인)
+      // 1바이트이고 첫 번째 바이트가 0x02 (Pong)이면 무시
+      // (하트비트 타임스탬프만 갱신되었으므로 추가 작업 불필요)
       if (bytes.length === 1 && bytes[0] === 0x02) return;
 
       emitter.emit("message", bytes);
@@ -147,11 +147,11 @@ export function createSocketProvider(
   }
 
   async function tryReconnect(): Promise<void> {
-    // Loop-based reconnect (used instead of recursion for stack safety)
+    // 루프 기반 재연결 (스택 안전성을 위해 재귀 대신 사용)
     while (reconnectCount < maxReconnectCount) {
       reconnectCount++;
       emitter.emit("state", "reconnecting");
-      logger.warn("WebSocket disconnected. Attempting reconnect...", {
+      logger.warn("WebSocket 연결 끊김. 재연결 시도 중...", {
         reconnectCount,
         maxReconnectCount,
       });
@@ -162,16 +162,16 @@ export function createSocketProvider(
         await createSocket();
         startHeartbeat();
         reconnectCount = 0;
-        emitter.emit("state", "connected"); // Notify reconnect success
-        logger.info("WebSocket reconnected successfully");
-        return; // Exit on successful reconnect
+        emitter.emit("state", "connected"); // 재연결 성공 알림
+        logger.info("WebSocket 재연결 성공");
+        return; // 재연결 성공 시 루프 종료
       } catch {
-        // Continue loop on failure
+        // 실패 시 루프 계속
       }
     }
 
-    // Max retry count exceeded
-    logger.error("Reconnect retry limit exceeded. Giving up.");
+    // 최대 재시도 횟수 초과
+    logger.error("재연결 재시도 한도 초과. 연결을 포기합니다.");
     emitter.emit("state", "closed");
   }
 
@@ -180,32 +180,32 @@ export function createSocketProvider(
     lastHeartbeatTime = Date.now();
 
     heartbeatTimer = setInterval(() => {
-      // Timeout check
+      // 타임아웃 확인
       if (Date.now() - lastHeartbeatTime > HEARTBEAT_TIMEOUT) {
-        logger.warn("Heartbeat Timeout. Connection lost.");
+        logger.warn("하트비트 타임아웃. 연결이 끊어졌습니다.");
 
-        // Stop the timer immediately on timeout to prevent repeated execution.
+        // 반복 실행 방지를 위해 타임아웃 시 즉시 타이머 중지
         stopHeartbeat();
 
-        // Don't wait for socket close (onclose may not fire); force cleanup and reconnect.
+        // 소켓 종료를 기다리지 않음 (onclose가 발생하지 않을 수 있음); 강제 정리 후 재연결
         if (ws != null) {
           const tempWs = ws;
-          ws = undefined; // Consider connection as disconnected
+          ws = undefined; // 연결 끊김으로 간주
 
-          // Remove event handlers from old socket
-          // Prevent duplicate reconnect from late onclose events
+          // 이전 소켓에서 이벤트 핸들러 제거
+          // 늦게 발생하는 onclose 이벤트로 인한 중복 재연결 방지
           tempWs.onclose = null;
           tempWs.onerror = null;
           tempWs.onmessage = null;
 
-          // Attempt to close socket (ignore errors)
+          // 소켓 닫기 시도 (에러 무시)
           try {
             tempWs.close();
           } catch {
-            // ignore
+            // 무시
           }
 
-          // Force reconnect logic if not a manual close
+          // 수동 종료가 아닌 경우 강제 재연결 로직 실행
           if (!isManualClose) {
             void tryReconnect();
           }
@@ -213,13 +213,13 @@ export function createSocketProvider(
         return;
       }
 
-      // Send ping
+      // ping 전송
       const currentWs = ws;
       if (isConnected() && currentWs != null) {
         try {
           currentWs.send(PING_PACKET);
         } catch (err) {
-          logger.warn("Ping send failed", err);
+          logger.warn("ping 전송 실패", err);
         }
       }
     }, HEARTBEAT_INTERVAL);

package/src/types/connection-options.ts

@@ -2,6 +2,6 @@ export interface ServiceConnectionOptions {
   port: number;
   host: string;
   ssl?: boolean;
-  /** Set to 0 to disable reconnect; disconnects immediately */
+  /** 0으로 설정하면 재연결을 비활성화하고 즉시 연결을 끊음 */
   maxReconnectCount?: number;
 }

package/src/types/progress.types.ts

@@ -1,6 +1,7 @@
 export interface ServiceProgress {
   request?: (s: ServiceProgressState) => void;
   response?: (s: ServiceProgressState) => void;
+  server?: (s: ServiceProgressState) => void;
 }
 
 export interface ServiceProgressState {

package/src/workers/client-protocol.worker.ts

@@ -17,34 +17,34 @@ self.onmessage = (event: MessageEvent) => {
     let transferList: Transferable[] = [];
 
     if (type === "encode") {
-      // [Main -> Worker] Encode request (data: { uuid, message })
-      // message is already a Plain Object (via Structured Clone)
+      // [Main -> Worker] 인코딩 요청 (data: { uuid, message })
+      // message는 이미 Plain Object임 (Structured Clone을 통해 전달)
       const { uuid, message } = data as {
         uuid: string;
         message: Parameters<typeof protocol.encode>[1];
       };
       const { chunks } = protocol.encode(uuid, message);
 
-      // Buffer[] is transferable, return as result
+      // Buffer[]는 전송 가능하므로 결과로 반환
       result = chunks;
-      // Add internal ArrayBuffers of result chunks to transfer list
+      // 결과 chunk의 내부 ArrayBuffer를 전송 목록에 추가
       transferList = chunks.map((chunk) => chunk.buffer as ArrayBuffer);
     } else {
-      // [Main -> Worker] Decode request (data: Uint8Array)
-      // data arrives as Uint8Array
+      // [Main -> Worker] 디코딩 요청 (data: Uint8Array)
+      // data는 Uint8Array로 전달됨
       const bytes = new Uint8Array(data as ArrayBuffer);
       const decodeResult = protocol.decode(bytes);
 
-      // Convert result object to transferable form (prepare for zero-copy)
+      // 결과 객체를 전송 가능한 형태로 변환 (zero-copy 준비)
       const encoded = transfer.encode(decodeResult);
       result = encoded.result;
       transferList = encoded.transferList;
     }
 
-    // [Worker -> Main] Success response
+    // [Worker -> Main] 성공 응답
     self.postMessage({ id, type: "success", result }, { transfer: transferList });
   } catch (err) {
-    // [Worker -> Main] Error response
+    // [Worker -> Main] 에러 응답
     self.postMessage({
       id,
       type: "error",

package/README.md

@@ -1,126 +0,0 @@
-# @simplysm/service-client
-
-Simplysm package - Service module (client)
-
-WebSocket-based service client for communicating with `@simplysm/service-server`. Provides type-safe service method calls, event pub/sub, file upload/download, and client-side ORM connectivity.
-
-## Installation
-
-```bash
-npm install @simplysm/service-client
-```
-
-## API Overview
-
-### Types
-| API | Type | Description |
-|-----|------|-------------|
-| `ServiceConnectionOptions` | interface | Connection options (host, port, ssl, reconnect) |
-| `ServiceProgress` | interface | Progress callback config for requests |
-| `ServiceProgressState` | interface | Progress state (uuid, totalSize, completedSize) |
-
--> See [docs/types.md](./docs/types.md) for details.
-
-### Transport
-| API | Type | Description |
-|-----|------|-------------|
-| `SocketProvider` | interface | WebSocket connection provider |
-| `SocketProviderEvents` | interface | Socket events (message, state) |
-| `createSocketProvider` | function | Create socket with heartbeat and auto-reconnect |
-| `ServiceTransport` | interface | Message routing and request/response correlation |
-| `ServiceTransportEvents` | interface | Transport events (reload, event) |
-| `createServiceTransport` | function | Create transport instance |
-
--> See [docs/transport.md](./docs/transport.md) for details.
-
-### Protocol
-| API | Type | Description |
-|-----|------|-------------|
-| `ClientProtocolWrapper` | interface | Protocol wrapper with Web Worker offloading |
-| `createClientProtocolWrapper` | function | Create protocol wrapper |
-
--> See [docs/protocol.md](./docs/protocol.md) for details.
-
-### Features (Event, File, ORM)
-| API | Type | Description |
-|-----|------|-------------|
-| `EventClient` | interface | Event listener management |
-| `createEventClient` | function | Create event client |
-| `FileClient` | interface | File upload/download |
-| `createFileClient` | function | Create file client |
-| `OrmConnectOptions` | interface | ORM connection options |
-| `OrmClientConnector` | interface | Client-side ORM connector |
-| `createOrmClientConnector` | function | Create ORM connector |
-| `OrmClientDbContextExecutor` | class | DbContext executor via service protocol |
-
--> See [docs/features.md](./docs/features.md) for details.
-
-### Main
-| API | Type | Description |
-|-----|------|-------------|
-| `ServiceClient` | class | Main client (connect, auth, service calls, events, files) |
-| `ServiceClientEvents` | interface | Client events (progress, state, reload) |
-| `ServiceProxy` | type | Type wrapper for remote service methods |
-| `createServiceClient` | function | Factory to create ServiceClient |
-
--> See [docs/service-client.md](./docs/service-client.md) for details.
-
-## Usage Examples
-
-### Connect and Call Service Methods
-
-```typescript
-import { createServiceClient } from "@simplysm/service-client";
-
-const client = createServiceClient("my-app", {
-  host: "localhost",
-  port: 3000,
-});
-
-await client.connect();
-await client.auth(jwtToken);
-
-// Type-safe service proxy
-interface UserService {
-  getProfile(): Promise<{ name: string; email: string }>;
-  updateName(name: string): Promise<void>;
-}
-
-const userService = client.getService<UserService>("User");
-const profile = await userService.getProfile();
-await userService.updateName("New Name");
-```
-
-### Client-Side ORM
-
-```typescript
-import { createOrmClientConnector } from "@simplysm/service-client";
-
-const orm = createOrmClientConnector(client);
-
-const users = await orm.connect(
-  { dbContextDef: MyDb, connOpt: { configName: "main" } },
-  async (db) => {
-    return db.user().where((u) => [expr.eq(u.status, "active")]).execute();
-  },
-);
-```
-
-### Event Subscription
-
-```typescript
-import { defineEvent } from "@simplysm/service-common";
-
-const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
-
-const key = await client.addListener(
-  OrderUpdated,
-  { orderId: 123 },
-  async (data) => {
-    console.log("Order status:", data.status);
-  },
-);
-
-// Later: unsubscribe
-await client.removeListener(key);
-```