@simplysm/service-client 14.0.1 → 14.0.5

package/docs/client-protocol-wrapper.md

@@ -0,0 +1,35 @@
+# Client Protocol Wrapper
+
+## `ClientProtocolWrapper`
+
+Client-side protocol encoder/decoder wrapper. Automatically offloads heavy encode/decode operations to a Web Worker when available, falling back to main-thread processing for small messages or when workers are unsupported.
+
+```typescript
+export interface ClientProtocolWrapper {
+  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
+  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
+  dispose(): void;
+}
+```
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `encode` | `uuid: string, message: ServiceMessage` | `Promise<{ chunks: Bytes[]; totalSize: number }>` | Encodes a message into binary chunks. Offloads to worker for large messages |
+| `decode` | `bytes: Bytes` | `Promise<ServiceMessageDecodeResult<ServiceMessage>>` | Decodes received binary data. Uses zero-copy transfer for large payloads |
+| `dispose` | none | `void` | Disposes the underlying protocol and worker resolver resources |
+
+## `createClientProtocolWrapper`
+
+Creates a `ClientProtocolWrapper` from a `ServiceProtocol` instance.
+
+```typescript
+export function createClientProtocolWrapper(
+  protocol: ServiceProtocol,
+): ClientProtocolWrapper;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `protocol` | `ServiceProtocol` | The base protocol encoder/decoder (from `@simplysm/service-common`) |
+
+Worker offloading threshold: 30KB. Messages below this size are processed on the main thread. The worker is a shared singleton across all `ClientProtocolWrapper` instances. Worker operations that exceed 60 seconds are automatically timed out and rejected.

package/docs/connection-options.md

@@ -0,0 +1,21 @@
+# Connection Options
+
+## `ServiceConnectionOptions`
+
+Connection options for the service client.
+
+```typescript
+export interface ServiceConnectionOptions {
+  port: number;
+  host: string;
+  ssl?: boolean;
+  maxReconnectCount?: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `port` | `number` | Server port |
+| `host` | `string` | Server hostname |
+| `ssl` | `boolean?` | Enable SSL/TLS (uses `wss://` and `https://` when true) |
+| `maxReconnectCount` | `number?` | Maximum reconnection attempts. Set to `0` to disable reconnection and disconnect immediately |

package/docs/features.md

@@ -0,0 +1,147 @@
+# Event/File/ORM Client
+
+## `EventClient`
+
+Event subscription client for the service event system.
+
+```typescript
+export interface EventClient {
+  addListener<TInfo, TData>(
+    eventDef: ServiceEventDef<TInfo, TData>,
+    info: TInfo,
+    cb: (data: TData) => PromiseLike<void>,
+  ): Promise<string>;
+  removeListener(key: string): Promise<void>;
+  emit<TInfo, TData>(
+    eventDef: ServiceEventDef<TInfo, TData>,
+    infoSelector: (item: TInfo) => boolean,
+    data: TData,
+  ): Promise<void>;
+  resubscribeAll(): Promise<void>;
+}
+```
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `addListener` | `eventDef: ServiceEventDef<TInfo, TData>, info: TInfo, cb: (data: TData) => PromiseLike<void>` | `Promise<string>` | Subscribes to an event. Returns a listener key (UUID) for later removal |
+| `removeListener` | `key: string` | `Promise<void>` | Unsubscribes by listener key |
+| `emit` | `eventDef: ServiceEventDef<TInfo, TData>, infoSelector: (item: TInfo) => boolean, data: TData` | `Promise<void>` | Queries matching listeners from the server, then emits the event to them |
+| `resubscribeAll` | none | `Promise<void>` | Re-registers all local listeners on the server (used after reconnection) |
+
+## `createEventClient`
+
+```typescript
+export function createEventClient(transport: ServiceTransport): EventClient;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `transport` | `ServiceTransport` | The service transport for sending event messages |
+
+## `FileClient`
+
+File upload and download client using HTTP `fetch`.
+
+```typescript
+export interface FileClient {
+  download(relPath: string): Promise<Bytes>;
+  upload(
+    files: File[] | FileCollection | { name: string; data: BlobInput }[],
+    authToken: string,
+  ): Promise<ServiceUploadResult[]>;
+}
+```
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `download` | `relPath: string` | `Promise<Bytes>` | Downloads a file by relative path as `Uint8Array` |
+| `upload` | `files: File[] \| FileCollection \| { name: string; data: BlobInput }[], authToken: string` | `Promise<ServiceUploadResult[]>` | Uploads files via multipart form data with Bearer token authentication |
+
+## `createFileClient`
+
+```typescript
+export function createFileClient(hostUrl: string, clientName: string): FileClient;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `hostUrl` | `string` | Full host URL (e.g., `http://localhost:3000`) |
+| `clientName` | `string` | Client identifier sent in `x-sd-client-name` header |
+
+## `OrmConnectOptions`
+
+ORM connection options for client-side database context usage.
+
+```typescript
+export interface OrmConnectOptions<TDef extends DbContextDef<any, any, any>> {
+  dbContextDef: TDef;
+  connOpt: DbConnOptions & { configName: string };
+  dbContextOpt?: {
+    database: string;
+    schema: string;
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `dbContextDef` | `TDef` | Database context definition |
+| `connOpt` | `DbConnOptions & { configName: string }` | Connection options with required config name |
+| `dbContextOpt` | `{ database: string; schema: string }?` | Optional database/schema override |
+
+## `OrmClientConnector`
+
+ORM client connector that opens a database context over the service RPC layer.
+
+```typescript
+export interface OrmClientConnector {
+  connect<TDef extends DbContextDef<any, any, any>, R>(
+    config: OrmConnectOptions<TDef>,
+    callback: (db: DbContextInstance<TDef>) => Promise<R> | R,
+  ): Promise<R>;
+  connectWithoutTransaction<TDef extends DbContextDef<any, any, any>, R>(
+    config: OrmConnectOptions<TDef>,
+    callback: (db: DbContextInstance<TDef>) => Promise<R> | R,
+  ): Promise<R>;
+}
+```
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `connect` | `config: OrmConnectOptions<TDef>, callback: (db: DbContextInstance<TDef>) => Promise<R> \| R` | `Promise<R>` | Opens a DB context with automatic transaction (begin/commit/rollback). Wraps foreign key constraint errors with a user-friendly message |
+| `connectWithoutTransaction` | `config: OrmConnectOptions<TDef>, callback: (db: DbContextInstance<TDef>) => Promise<R> \| R` | `Promise<R>` | Opens a DB context without automatic transaction management |
+
+## `createOrmClientConnector`
+
+```typescript
+export function createOrmClientConnector(serviceClient: ServiceClient): OrmClientConnector;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `serviceClient` | `ServiceClient` | The service client instance for RPC communication |
+
+## `OrmClientDbContextExecutor`
+
+Implements `DbContextExecutor` (from `@simplysm/orm-common`) for client-side ORM usage over the service RPC layer. Proxies all database operations through the remote `OrmService`.
+
+```typescript
+export class OrmClientDbContextExecutor implements DbContextExecutor {
+  constructor(
+    client: ServiceClient,
+    opt: DbConnOptions & { configName: string },
+  );
+}
+```
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `getInfo` | none | `Promise<{ dialect: Dialect; database?: string; schema?: string }>` | Gets database info via remote ORM service |
+| `connect` | none | `Promise<void>` | Opens a remote connection |
+| `beginTransaction` | `isolationLevel?: IsolationLevel` | `Promise<void>` | Begins a remote transaction |
+| `commitTransaction` | none | `Promise<void>` | Commits the remote transaction |
+| `rollbackTransaction` | none | `Promise<void>` | Rolls back the remote transaction |
+| `close` | none | `Promise<void>` | Closes the remote connection |
+| `executeDefs` | `defs: QueryDef[], options?: (ResultMeta \| undefined)[]` | `Promise<T[][]>` | Executes query definitions via remote ORM service |
+| `executeParametrized` | `query: string, params?: unknown[]` | `Promise<unknown[][]>` | Executes a parameterized query via remote ORM service |
+| `bulkInsert` | `tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]` | `Promise<void>` | Performs bulk insert via remote ORM service |

package/docs/progress-types.md

@@ -0,0 +1,37 @@
+# Progress Types
+
+## `ServiceProgress`
+
+Callback hooks for monitoring message progress at different stages.
+
+```typescript
+export interface ServiceProgress {
+  request?: (s: ServiceProgressState) => void;
+  response?: (s: ServiceProgressState) => void;
+  server?: (s: ServiceProgressState) => void;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `request` | `(s: ServiceProgressState) => void` | Called during request encoding/sending progress |
+| `response` | `(s: ServiceProgressState) => void` | Called during response decoding progress |
+| `server` | `(s: ServiceProgressState) => void` | Called when server reports chunk receive progress |
+
+## `ServiceProgressState`
+
+Progress state for a single message transfer.
+
+```typescript
+export interface ServiceProgressState {
+  uuid: string;
+  totalSize: number;
+  completedSize: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `uuid` | `string` | Message UUID |
+| `totalSize` | `number` | Total message size in bytes |
+| `completedSize` | `number` | Bytes transferred so far |

package/docs/service-client.md

@@ -0,0 +1,89 @@
+# Main ServiceClient
+
+## `ServiceClient`
+
+Main service client class. Extends `EventEmitter` with progress and state events. Composes `SocketProvider`, `ServiceTransport`, `EventClient`, `FileClient`, and `ClientProtocolWrapper` internally.
+
+```typescript
+export class ServiceClient extends EventEmitter<{
+  "request-progress": ServiceProgressState;
+  "response-progress": ServiceProgressState;
+  "server-progress": ServiceProgressState;
+  "state": "connected" | "closed" | "reconnecting";
+}> {
+  constructor(name: string, options: ServiceConnectionOptions);
+}
+```
+
+### Events
+
+| Event | Data Type | Description |
+|-------|-----------|-------------|
+| `request-progress` | `ServiceProgressState` | Request sending progress (chunked messages) |
+| `response-progress` | `ServiceProgressState` | Response receiving progress (chunked messages) |
+| `server-progress` | `ServiceProgressState` | Server-side chunk reception progress |
+| `state` | `"connected" \| "closed" \| "reconnecting"` | Connection state change |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` (readonly) | Client name |
+| `options` | `ServiceConnectionOptions` (readonly) | Connection options |
+| `connected` | `boolean` (readonly, getter) | Whether the client is currently connected |
+| `hostUrl` | `string` (readonly, getter) | Full host URL computed from options (e.g., `https://host:port`) |
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getService` | `getService<TService>(serviceName: string): ServiceProxy<TService>` | Returns a type-safe proxy that maps method calls to RPC requests |
+| `connect` | `connect(): Promise<void>` | Opens the WebSocket connection |
+| `close` | `close(): Promise<void>` | Closes the connection and disposes protocol resources |
+| `send` | `send(serviceName: string, methodName: string, params: unknown[], progress?: ServiceProgress): Promise<unknown>` | Sends an RPC call directly |
+| `auth` | `auth(token: string): Promise<void>` | Authenticates with a JWT token. Token is cached for reconnection |
+| `addListener` | `addListener<TInfo, TData>(eventDef: ServiceEventDef<TInfo, TData>, info: TInfo, cb: (data: TData) => PromiseLike<void>): Promise<string>` | Subscribes to an event. Returns listener key. Throws if not connected |
+| `removeListener` | `removeListener(key: string): Promise<void>` | Unsubscribes from an event by key |
+| `emitEvent` | `emitEvent<TInfo, TData>(eventDef: ServiceEventDef<TInfo, TData>, infoSelector: (item: TInfo) => boolean, data: TData): Promise<void>` | Emits an event to matching listeners |
+| `uploadFile` | `uploadFile(files: File[] \| FileCollection \| { name: string; data: BlobInput }[]): Promise<ServiceUploadResult[]>` | Uploads files. Requires prior `auth()` call |
+| `downloadFileBuffer` | `downloadFileBuffer(relPath: string): Promise<Bytes>` | Downloads a file as `Uint8Array` |
+
+### Reconnection Behavior
+
+On reconnection (`state === "connected"` after a disconnect):
+1. Re-authenticates with the cached token (if `auth()` was previously called)
+2. Re-subscribes all event listeners via `EventClient.resubscribeAll()`
+
+## `ServiceProxy`
+
+Type utility that wraps all methods of a service interface to return `Promise<Awaited<R>>`.
+
+```typescript
+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 mapped to `never`.
+
+## `createServiceClient`
+
+Factory function to create a `ServiceClient` instance.
+
+```typescript
+export function createServiceClient(
+  name: string,
+  options: ServiceConnectionOptions,
+): ServiceClient;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Client identifier name |
+| `options` | `ServiceConnectionOptions` | Connection options (host, port, SSL, maxReconnectCount) |
+
+**Returns:** `ServiceClient`
+
+Default `maxReconnectCount` is `10` if not specified in options.

package/docs/service-transport.md

@@ -0,0 +1,60 @@
+# Service Transport
+
+## `ServiceTransportEvents`
+
+Event map for the service transport.
+
+```typescript
+export interface ServiceTransportEvents {
+  event: { keys: string[]; data: unknown };
+}
+```
+
+| Event | Data Type | Description |
+|-------|-----------|-------------|
+| `event` | `{ keys: string[]; data: unknown }` | Server-side event broadcast received |
+
+## `ServiceTransport`
+
+Service-level message transport built on top of `SocketProvider` and `ClientProtocolWrapper`. Manages pending request/response correlation via UUIDs, handles progress notifications, and dispatches events.
+
+```typescript
+export interface ServiceTransport {
+  on<K extends keyof ServiceTransportEvents & string>(
+    type: K,
+    listener: (data: ServiceTransportEvents[K]) => void,
+  ): void;
+  off<K extends keyof ServiceTransportEvents & string>(
+    type: K,
+    listener: (data: ServiceTransportEvents[K]) => void,
+  ): void;
+  send(message: ServiceClientMessage, progress?: ServiceProgress): Promise<unknown>;
+}
+```
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `on` | `type: K, listener` | `void` | Subscribe to transport events |
+| `off` | `type: K, listener` | `void` | Unsubscribe from transport events |
+| `send` | `message: ServiceClientMessage, progress?: ServiceProgress` | `Promise<unknown>` | Sends a service message and awaits the server response. Returns the response body |
+
+## `createServiceTransport`
+
+Creates a `ServiceTransport` instance.
+
+```typescript
+export function createServiceTransport(
+  socket: SocketProvider,
+  protocol: ClientProtocolWrapper,
+): ServiceTransport;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `socket` | `SocketProvider` | The socket provider for sending/receiving binary data |
+| `protocol` | `ClientProtocolWrapper` | The protocol wrapper for encoding/decoding messages |
+
+Behavior:
+- Generates a UUID per `send()` call and registers a pending resolver
+- On socket disconnect (`closed`/`reconnecting`), rejects all pending requests
+- Routes server messages: `response` resolves, `error` rejects, `evt:on` emits event, `progress` invokes progress callbacks

package/docs/socket-provider.md

@@ -0,0 +1,72 @@
+# Socket Provider
+
+## `SocketProviderEvents`
+
+Event map for the socket provider.
+
+```typescript
+export interface SocketProviderEvents {
+  message: Bytes;
+  state: "connected" | "closed" | "reconnecting";
+}
+```
+
+| Event | Data Type | Description |
+|-------|-----------|-------------|
+| `message` | `Bytes` | Raw binary message received from server |
+| `state` | `"connected" \| "closed" \| "reconnecting"` | Connection state change |
+
+## `SocketProvider`
+
+Low-level WebSocket abstraction with automatic reconnection and heartbeat keepalive. Works in both browser and Node.js environments (uses `ws` package as polyfill in Node.js).
+
+```typescript
+export interface SocketProvider {
+  readonly clientName: string;
+  readonly connected: boolean;
+  on<K extends keyof SocketProviderEvents & string>(
+    type: K,
+    listener: (data: SocketProviderEvents[K]) => void,
+  ): void;
+  off<K extends keyof SocketProviderEvents & string>(
+    type: K,
+    listener: (data: SocketProviderEvents[K]) => void,
+  ): void;
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  send(data: Bytes): Promise<void>;
+}
+```
+
+| Member | Kind | Description |
+|--------|------|-------------|
+| `clientName` | property (readonly) | Client identifier name |
+| `connected` | property (readonly) | Whether currently connected |
+| `on` | method | Subscribe to an event |
+| `off` | method | Unsubscribe from an event |
+| `connect` | method | Opens the WebSocket connection. Throws on initial connection failure |
+| `close` | method | Closes the connection gracefully |
+| `send` | method | Sends binary data. Waits for connection if not yet open |
+
+## `createSocketProvider`
+
+Creates a `SocketProvider` instance with auto-reconnect and heartbeat.
+
+```typescript
+export function createSocketProvider(
+  url: string,
+  clientName: string,
+  maxReconnectCount: number,
+): SocketProvider;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | WebSocket URL (e.g., `ws://localhost:3000/ws`) |
+| `clientName` | `string` | Client identifier |
+| `maxReconnectCount` | `number` | Maximum reconnection attempts |
+
+Internal constants:
+- Heartbeat timeout: 30 seconds
+- Heartbeat interval: 5 seconds (sends ping `0x01`, expects pong `0x02`)
+- Reconnect delay: 3 seconds between attempts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-client",
-  "version": "14.0.1",
+  "version": "14.0.5",
   "description": "심플리즘 패키지 - 서비스 (client)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -14,14 +14,15 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "docs"
   ],
   "sideEffects": false,
   "dependencies": {
     "consola": "^3.4.2",
-    "@simplysm/core-common": "14.0.1",
-    "@simplysm/orm-common": "14.0.1",
-    "@simplysm/service-common": "14.0.1"
+    "@simplysm/core-common": "14.0.5",
+    "@simplysm/orm-common": "14.0.5",
+    "@simplysm/service-common": "14.0.5"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1",

package/src/features/file-client.ts

@@ -1,10 +1,11 @@
 import type { Bytes } from "@simplysm/core-common";
 import type { ServiceUploadResult } from "@simplysm/service-common";
+import type { BlobInput, FileCollection } from "../types/browser-compat";
 
 export interface FileClient {
   download(relPath: string): Promise<Bytes>;
   upload(
-    files: File[] | FileList | { name: string; data: BlobPart }[],
+    files: File[] | FileCollection | { name: string; data: BlobInput }[],
     authToken: string,
   ): Promise<ServiceUploadResult[]>;
 }
@@ -24,13 +25,13 @@ export function createFileClient(hostUrl: string, clientName: string): FileClien
   }
 
   async function upload(
-    files: File[] | FileList | { name: string; data: BlobPart }[],
+    files: File[] | FileCollection | { name: string; data: BlobInput }[],
     authToken: string,
   ): Promise<ServiceUploadResult[]> {
     const formData = new FormData();
-    const fileList = files instanceof FileList ? Array.from(files) : files;
+    const fileArr = Array.isArray(files) ? files : Array.from(files);
 
-    for (const file of fileList) {
+    for (const file of fileArr) {
       if ("data" in file) {
         // 커스텀 객체 ({ name, data })
         const blob = file.data instanceof Blob ? file.data : new Blob([file.data]);
@@ -54,7 +55,7 @@ export function createFileClient(hostUrl: string, clientName: string): FileClien
       throw new Error(`업로드 실패: ${res.statusText}`);
     }
 
-    return res.json();
+    return (await res.json()) as ServiceUploadResult[];
   }
 
   return {

package/src/index.ts

@@ -1,4 +1,5 @@
 // 타입
+export * from "./types/browser-compat";
 export * from "./types/connection-options";
 export * from "./types/progress.types";
 

package/src/protocol/client-protocol-wrapper.ts

@@ -5,6 +5,8 @@ import type {
   ServiceMessage,
   ServiceProtocol,
 } from "@simplysm/service-common";
+import type { WorkerLike } from "../types/browser-compat";
+import { isWorkerSupported, createBrowserWorker } from "../types/browser-compat";
 
 export interface ClientProtocolWrapper {
   encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
@@ -13,7 +15,7 @@ export interface ClientProtocolWrapper {
 }
 
 // 공유 worker 상태 (싱글턴 패턴)
-let worker: Worker | undefined;
+let worker: WorkerLike | undefined;
 const workerResolvers = new LazyGcMap<
   string,
   { resolve: (res: unknown) => void; reject: (err: Error) => void }
@@ -30,12 +32,12 @@ let workerAvailable: boolean | undefined;
 
 function isWorkerAvailable(): boolean {
   if (workerAvailable === undefined) {
-    workerAvailable = typeof Worker !== "undefined";
+    workerAvailable = isWorkerSupported();
   }
   return workerAvailable;
 }
 
-function getWorker(): Worker | undefined {
+function getWorker(): WorkerLike | undefined {
   if (!isWorkerAvailable()) {
     return undefined;
   }
@@ -43,9 +45,11 @@ function getWorker(): Worker | undefined {
   if (!worker) {
     // 모던 번들러 (Vite/Esbuild/Webpack)가 이 구문을 사용하여 Worker를 별도 파일로 분리/로드함
     // 참고: import.meta.resolve 대신 상대 경로 사용 (Vite 호환성)
-    worker = new Worker(new URL("../workers/client-protocol.worker.ts", import.meta.url), {
-      type: "module",
-    });
+    worker = createBrowserWorker(
+      new URL("../workers/client-protocol.worker.ts", import.meta.url),
+      { type: "module" },
+    );
+    if (worker == null) return undefined;
 
     worker.onmessage = (event: MessageEvent) => {
       const { id, type, result, error } = event.data as {
@@ -78,14 +82,14 @@ function getWorker(): Worker | undefined {
 async function runWorker(
   type: "encode" | "decode",
   data: unknown,
-  transferables: Transferable[] = [],
+  transferables: ArrayBuffer[] = [],
 ): Promise<unknown> {
   return new Promise((resolve, reject) => {
     const id = Uuid.generate().toString();
 
     workerResolvers.set(id, { resolve, reject });
     // workerAvailable 확인 후 호출되므로 worker는 항상 존재
-    getWorker()!.postMessage({ id, type, data }, { transfer: transferables });
+    getWorker()!.postMessage({ id, type, data }, transferables);
   });
 }
 
@@ -135,7 +139,7 @@ export function createClientProtocolWrapper(protocol: ServiceProtocol): ClientPr
 
     // [Worker]
     // Zero-copy 전송 (버퍼 소유권이 Worker로 이동)
-    const rawResult = await runWorker("decode", bytes, [bytes.buffer]);
+    const rawResult = await runWorker("decode", bytes, [bytes.buffer as ArrayBuffer]);
 
     // Worker의 plain object 결과에서 클래스 인스턴스 복원 (DateTime 등)
     return transfer.decode(rawResult) as ServiceMessageDecodeResult<ServiceMessage>;

package/src/service-client.ts

@@ -3,6 +3,7 @@ import { EventEmitter } from "@simplysm/core-common";
 import type { ServiceEventDef } from "@simplysm/service-common";
 import { createServiceProtocol } from "@simplysm/service-common";
 
+import type { BlobInput, FileCollection } from "./types/browser-compat";
 import type { ServiceConnectionOptions } from "./types/connection-options";
 import type { ServiceProgress, ServiceProgressState } from "./types/progress.types";
 import { createServiceTransport, type ServiceTransport } from "./transport/service-transport";
@@ -18,7 +19,6 @@ interface ServiceClientEvents {
   "response-progress": ServiceProgressState;
   "server-progress": ServiceProgressState;
   "state": "connected" | "closed" | "reconnecting";
-  "reload": Set<string>;
 }
 
 export class ServiceClient extends EventEmitter<ServiceClientEvents> {
@@ -74,9 +74,6 @@ export class ServiceClient extends EventEmitter<ServiceClientEvents> {
       }
     });
 
-    this._transport.on("reload", (changedFiles) => {
-      this.emit("reload", changedFiles);
-    });
   }
 
   // 타입 안전성을 위한 프록시 생성 메서드
@@ -154,7 +151,7 @@ export class ServiceClient extends EventEmitter<ServiceClientEvents> {
     await this._eventClient.emit(eventDef, infoSelector, data);
   }
 
-  async uploadFile(files: File[] | FileList | { name: string; data: BlobPart }[]) {
+  async uploadFile(files: File[] | FileCollection | { name: string; data: BlobInput }[]) {
     if (this._authToken == null) {
       throw new Error(
         "인증 토큰이 없습니다. 파일 업로드 전에 auth()를 호출하여 인증해 주세요.",

package/src/transport/service-transport.ts

@@ -10,7 +10,6 @@ import type { ServiceProgress } from "../types/progress.types";
 import type { SocketProvider } from "./socket-provider";
 
 export interface ServiceTransportEvents {
-  reload: Set<string>;
   event: { keys: string[]; data: unknown };
 }
 
@@ -61,7 +60,7 @@ export function createServiceTransport(
       pendingRequests.set(uuid, { resolve, reject, progress });
     });
 
-    // Promise가 고아가 되었을 때 unhandled rejection 방지 (예: HMR 정리 중)
+    // Promise가 고아가 되었을 때 unhandled rejection 방지 (예: 소켓 연결 끊김 시)
     responsePromise.catch(() => {});
 
     // 요청 전송
@@ -139,11 +138,6 @@ export function createServiceTransport(
           pendingRequests.delete(decoded.uuid);
 
           listenerInfo?.reject(toError(decoded.message.body));
-        } else if (decoded.message.name === "reload") {
-          const body = decoded.message.body as { clientName: string; changedFileSet: Set<string> };
-          if (socket.clientName === body.clientName) {
-            emitter.emit("reload", body.changedFileSet);
-          }
         } else if (decoded.message.name === "evt:on") {
           const body = decoded.message.body as { keys: string[]; data: unknown };
           emitter.emit("event", { keys: body.keys, data: body.data });