@simplysm/service-client 14.0.47 → 14.0.49

package/docs/features.md

@@ -0,0 +1,217 @@
+# Features
+
+## `ClientEventProxy`
+
+`getEvent()`가 반환하는 이벤트 프록시 인터페이스. 이벤트 이름과 제네릭 타입이 캡처되어 있어 호출 시 반복 지정이 불필요하다.
+
+```typescript
+export interface ClientEventProxy<TEventDef extends ServiceEventDef> {
+  addListener(
+    info: TEventDef["$info"],
+    cb: (data: TEventDef["$data"]) => PromiseLike<void>,
+  ): Promise<string>;
+  removeListener(key: string): Promise<void>;
+  emit(
+    infoSelector: (item: TEventDef["$info"]) => boolean,
+    data: TEventDef["$data"],
+  ): Promise<void>;
+}
+```
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `addListener(info, cb)` | `Promise<string>` | 이벤트 리스너 등록. 반환값은 `key` (제거 시 사용) |
+| `removeListener(key)` | `Promise<void>` | 등록된 이벤트 리스너 제거 |
+| `emit(infoSelector, data)` | `Promise<void>` | `infoSelector`가 참인 대상에게 데이터 발행 |
+
+## `EventClient`
+
+서버 이벤트 구독/발행 인터페이스. 재연결 시 자동 재구독된다.
+
+```typescript
+export interface EventClient {
+  getEvent<TEventDef extends ServiceEventDef>(
+    eventName: string,
+  ): ClientEventProxy<TEventDef>;
+  addListener<TEventDef extends ServiceEventDef>(
+    eventName: string,
+    info: TEventDef["$info"],
+    cb: (data: TEventDef["$data"]) => PromiseLike<void>,
+  ): Promise<string>;
+  removeListener(key: string): Promise<void>;
+  emit<TEventDef extends ServiceEventDef>(
+    eventName: string,
+    infoSelector: (item: TEventDef["$info"]) => boolean,
+    data: TEventDef["$data"],
+  ): Promise<void>;
+  resubscribeAll(): Promise<void>;
+}
+```
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `getEvent(eventName)` | `ClientEventProxy<TEventDef>` | 이벤트 이름과 타입을 캡처한 프록시 반환. `getService()` 패턴과 동일 |
+| `addListener(eventName, info, cb)` | `Promise<string>` | 이벤트 리스너 등록. 제네릭 `TEventDef`로 `info`/`data` 타입 추론. 반환값은 `key` (제거 시 사용) |
+| `removeListener(key)` | `Promise<void>` | 등록된 이벤트 리스너 제거 |
+| `emit(eventName, infoSelector, data)` | `Promise<void>` | 서버의 이벤트 리스너 중 `infoSelector`가 참인 대상에게 데이터 발행. 제네릭 `TEventDef`로 타입 안전성 보장 |
+| `resubscribeAll()` | `Promise<void>` | 재연결 시 모든 리스너를 서버에 재등록. `ServiceClient`가 자동 호출 |
+
+## `createEventClient`
+
+`EventClient` 팩토리 함수.
+
+```typescript
+export function createEventClient(transport: ServiceTransport): EventClient;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `transport` | `ServiceTransport` | 서비스 전송 계층 |
+
+## `FileClient`
+
+파일 업로드(POST)/다운로드(GET) 인터페이스.
+
+```typescript
+export interface FileClient {
+  download(relPath: string): Promise<Bytes>;
+  upload(
+    files: File[] | FileCollection | { name: string; data: BlobInput }[],
+    authToken: string,
+  ): Promise<ServiceUploadResult[]>;
+}
+```
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `download(relPath)` | `Promise<Bytes>` | `GET {hostUrl}{relPath}`로 파일 다운로드. `Uint8Array` 반환 |
+| `upload(files, authToken)` | `Promise<ServiceUploadResult[]>` | `POST {hostUrl}/upload`로 파일 업로드. `multipart/form-data` 사용 |
+
+`upload` 파라미터:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `files` | `File[] \| FileCollection \| { name: string; data: BlobInput }[]` | 업로드할 파일 목록 |
+| `authToken` | `string` | 인증 토큰 (`Authorization: Bearer {token}` 헤더로 전송) |
+
+## `createFileClient`
+
+`FileClient` 팩토리 함수.
+
+```typescript
+export function createFileClient(hostUrl: string, clientName: string): FileClient;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `hostUrl` | `string` | 서버 기본 URL (`http://host:port` 형식) |
+| `clientName` | `string` | 클라이언트 식별자 (`x-sd-client-name` 헤더로 전송) |
+
+## `OrmConnectOptions`
+
+ORM 원격 연결에 필요한 옵션 인터페이스.
+
+```typescript
+export interface OrmConnectOptions<T extends DbContext> {
+  DbClass: new (executor: DbContextExecutor, opt: { database: string; schema?: string }) => T;
+  connOpt: DbConnOptions & { configName: string };
+  dbContextOpt?: {
+    database: string;
+    schema: string;
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `DbClass` | `new (...) => T` | 사용할 `DbContext` 서브클래스 생성자 |
+| `connOpt` | `DbConnOptions & { configName: string }` | DB 연결 옵션. `configName`은 서버 설정 키 |
+| `dbContextOpt` | `{ database: string; schema: string }?` | DB 컨텍스트 옵션. 생략하면 서버에서 조회한 `info.database`/`info.schema` 사용 |
+
+## `OrmClientConnector`
+
+`DbContext` 트랜잭션 연결을 원격 서버에서 실행하는 헬퍼 인터페이스.
+
+```typescript
+export interface OrmClientConnector {
+  connect<T extends DbContext, R>(
+    config: OrmConnectOptions<T>,
+    callback: (db: T) => Promise<R> | R,
+  ): Promise<R>;
+  connectWithoutTransaction<T extends DbContext, R>(
+    config: OrmConnectOptions<T>,
+    callback: (db: T) => Promise<R> | R,
+  ): Promise<R>;
+}
+```
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `connect(config, callback)` | `Promise<R>` | 트랜잭션 모드로 연결. FK 제약 위반 시 사용자 친화적 에러 메시지로 변환 |
+| `connectWithoutTransaction(config, callback)` | `Promise<R>` | 트랜잭션 없이 연결 |
+
+## `createOrmClientConnector`
+
+`OrmClientConnector` 팩토리 함수.
+
+```typescript
+export function createOrmClientConnector(serviceClient: ServiceClient): OrmClientConnector;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `serviceClient` | `ServiceClient` | 이미 연결된 서비스 클라이언트 |
+
+사용 예:
+
+```typescript
+const connector = createOrmClientConnector(client);
+
+const result = await connector.connect(
+  { DbClass: MyDbContext, connOpt: { configName: "main" } },
+  async (db) => {
+    return db.myTable.select((item) => ({ id: item.id, name: item.name }));
+  },
+);
+```
+
+## `OrmClientDbContextExecutor`
+
+`DbContextExecutor` 인터페이스 구현체. `DbContext`의 쿼리 실행을 서버 `OrmService`에 원격 호출한다. 직접 사용보다 `createOrmClientConnector`를 통해 사용하는 것을 권장한다.
+
+```typescript
+export class OrmClientDbContextExecutor implements DbContextExecutor {
+  constructor(
+    private readonly _client: ServiceClient,
+    private readonly _opt: DbConnOptions & { configName: string },
+  );
+  async getInfo(): Promise<{ dialect: Dialect; database?: string; schema?: string }>;
+  async connect(): Promise<void>;
+  async beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
+  async commitTransaction(): Promise<void>;
+  async rollbackTransaction(): Promise<void>;
+  async close(): Promise<void>;
+  async executeDefs<T = Record<string, unknown>>(
+    defs: QueryDef[],
+    options?: (ResultMeta | undefined)[],
+  ): Promise<T[][]>;
+  async executeParametrized(query: string, params?: unknown[]): Promise<unknown[][]>;
+  async bulkInsert(
+    tableName: string,
+    columnDefs: Record<string, ColumnMeta>,
+    records: Record<string, unknown>[],
+  ): Promise<void>;
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `getInfo()` | 서버에서 DB dialect, database, schema 조회 |
+| `connect()` | 서버에서 DB 연결 생성. `_connId` 할당 |
+| `beginTransaction(isolationLevel?)` | 트랜잭션 시작 |
+| `commitTransaction()` | 트랜잭션 커밋 |
+| `rollbackTransaction()` | 트랜잭션 롤백 |
+| `close()` | DB 연결 종료 및 `_connId` 해제 |
+| `executeDefs(defs, options?)` | QueryDef 배열을 서버에서 실행 |
+| `executeParametrized(query, params?)` | 파라미터화된 쿼리를 서버에서 실행 |
+| `bulkInsert(tableName, columnDefs, records)` | 대량 INSERT를 서버에서 실행 |

package/docs/main.md

@@ -0,0 +1,148 @@
+# Main
+
+## `ServiceClient`
+
+WebSocket 기반 서비스 클라이언트의 최상위 파사드 클래스. `SocketProvider`, `ClientProtocolWrapper`, `ServiceTransport`, `EventClient`, `FileClient`를 내부적으로 조합한다.
+
+```typescript
+export class ServiceClient extends EventEmitter<ServiceClientEvents> {
+  constructor(
+    public readonly name: string,
+    public readonly options: ServiceConnectionOptions,
+  );
+  get connected(): boolean;
+  get hostUrl(): string;
+  getService<TService>(serviceName: string): ServiceProxy<TService>;
+  getEvent<TEventDef extends ServiceEventDef>(eventName: string): ClientEventProxy<TEventDef>;
+  async connect(): Promise<void>;
+  async close(): Promise<void>;
+  async send(
+    serviceName: string,
+    methodName: string,
+    params: unknown[],
+    progress?: ServiceProgress,
+  ): Promise<unknown>;
+  async auth(token: string): Promise<void>;
+  async addListener<TEventDef extends ServiceEventDef>(
+    eventName: string,
+    info: TEventDef["$info"],
+    cb: (data: TEventDef["$data"]) => PromiseLike<void>,
+  ): Promise<string>;
+  async removeListener(key: string): Promise<void>;
+  async emitEvent<TEventDef extends ServiceEventDef>(
+    eventName: string,
+    infoSelector: (item: TEventDef["$info"]) => boolean,
+    data: TEventDef["$data"],
+  ): Promise<void>;
+  async uploadFile(
+    files: File[] | FileCollection | { name: string; data: BlobInput }[],
+  ): Promise<ServiceUploadResult[]>;
+  async downloadFileBuffer(relPath: string): Promise<Bytes>;
+}
+```
+
+`ServiceClient`가 발생시키는 이벤트 (`EventEmitter<ServiceClientEvents>`):
+
+| Event | Data Type | Description |
+|-------|-----------|-------------|
+| `request-progress` | `ServiceProgressState` | 요청 전송 progress |
+| `response-progress` | `ServiceProgressState` | 응답 수신 progress |
+| `server-progress` | `ServiceProgressState` | 서버 내부 처리 progress |
+| `state` | `"connected" \| "closed" \| "reconnecting"` | 연결 상태 변경 |
+
+생성자 파라미터:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | 클라이언트 식별자 (WebSocket URL 파라미터 및 HTTP 헤더로 전달됨) |
+| `options` | `ServiceConnectionOptions` | 연결 옵션 (host, port, ssl, maxReconnectCount) |
+
+주요 메서드:
+
+| Method | Description |
+|--------|-------------|
+| `connect()` | WebSocket 연결 시작 |
+| `close()` | WebSocket 연결 종료 및 protocol dispose |
+| `auth(token)` | 서버에 인증 토큰 전송. 재연결 시 자동 재인증됨 |
+| `getService<TService>(serviceName)` | 타입 안전한 서비스 프록시 반환 |
+| `getEvent<TEventDef>(eventName)` | 타입 안전한 이벤트 프록시 반환. `ClientEventProxy<TEventDef>`를 반환하며 이벤트 이름과 타입이 캡처됨 |
+| `send(serviceName, methodName, params, progress?)` | 서비스 메서드 원격 호출 |
+| `addListener(eventName, info, cb)` | 서버 이벤트 구독. 제네릭 `TEventDef`로 타입 안전성 보장. 연결 상태여야 함 |
+| `removeListener(key)` | 서버 이벤트 구독 해제 |
+| `emitEvent(eventName, infoSelector, data)` | 서버 이벤트 발행. 제네릭 `TEventDef`로 타입 안전성 보장 |
+| `uploadFile(files)` | 파일 업로드. `auth()` 호출 후 사용해야 함 |
+| `downloadFileBuffer(relPath)` | 파일 다운로드 (`Uint8Array` 반환) |
+
+접근자:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `connected` | `boolean` | 현재 WebSocket 연결 상태 |
+| `hostUrl` | `string` | HTTP 기본 URL (`http(s)://host:port`) |
+
+## `ServiceProxy`
+
+`TService`의 모든 메서드 반환 타입을 `Promise`로 래핑하는 유틸리티 타입. `ServiceClient.getService<TService>()`의 반환 타입으로 사용된다.
+
+```typescript
+export type ServiceProxy<TService> = {
+  [K in keyof TService]: TService[K] extends (...args: infer P) => infer R
+    ? (...args: P) => Promise<Awaited<R>>
+    : never;
+};
+```
+
+함수가 아닌 속성(`never`)은 타입에서 제외된다.
+
+## `createServiceClient`
+
+`ServiceClient` 팩토리 함수. `new ServiceClient(name, options)`와 동일하다.
+
+```typescript
+export function createServiceClient(name: string, options: ServiceConnectionOptions): ServiceClient;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | 클라이언트 식별자 |
+| `options` | `ServiceConnectionOptions` | 연결 옵션 |
+
+사용 예:
+
+```typescript
+import { ServiceClient } from "@simplysm/service-client";
+
+const client = new ServiceClient("my-app", {
+  host: "localhost",
+  port: 3000,
+  ssl: false,
+  maxReconnectCount: 10,
+});
+
+await client.connect();
+await client.auth("my-auth-token");
+
+// 타입 안전한 서비스 호출
+const userSvc = client.getService<UserService>("User");
+const users = await userSvc.getList();
+
+// 이벤트 프록시 방식 (권장 — getService()와 동일한 패턴)
+const chatEvt = client.getEvent<typeof ChatEvent>("Chat");
+const key = await chatEvt.addListener({ roomId: "room-1" }, async (data) => {
+  // data.message는 string으로 타입 추론
+});
+await chatEvt.removeListener(key);
+
+// 직접 호출 방식 (하위 호환)
+const key2 = await client.addListener<typeof ChatEvent>("Chat", { roomId: "room-1" }, async (data) => {
+  // data.message
+});
+
+// 파일 업로드
+const results = await client.uploadFile([{ name: "file.txt", data: "hello" }]);
+
+// 파일 다운로드
+const bytes = await client.downloadFileBuffer("/files/report.pdf");
+
+await client.close();
+```

package/docs/protocol.md

@@ -0,0 +1,56 @@
+# Protocol
+
+## `ClientProtocolWrapper`
+
+메시지 인코딩/디코딩 인터페이스. 데이터 크기가 30KB 이상이면 Web Worker로 처리를 오프로드한다.
+
+```typescript
+export interface ClientProtocolWrapper {
+  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
+  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
+  dispose(): void;
+}
+```
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `encode(uuid, message)` | `Promise<{ chunks: Bytes[]; totalSize: number }>` | 메시지를 바이너리 청크로 인코딩. 큰 데이터는 Worker로 오프로드 |
+| `decode(bytes)` | `Promise<ServiceMessageDecodeResult<ServiceMessage>>` | 바이너리를 메시지로 디코딩. 큰 데이터는 Worker로 오프로드 (zero-copy 전송) |
+| `dispose()` | `void` | 내부 `ServiceProtocol`과 Worker resolver 맵 정리 |
+
+## `createClientProtocolWrapper`
+
+`ClientProtocolWrapper` 팩토리 함수.
+
+```typescript
+export function createClientProtocolWrapper(protocol: ServiceProtocol): ClientProtocolWrapper;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `protocol` | `ServiceProtocol` | `@simplysm/service-common`의 `createServiceProtocol()`로 생성한 프로토콜 인스턴스 |
+
+내부 동작:
+- 임계값: 30KB (`30 * 1024` bytes)
+- Worker가 지원되지 않는 환경(Node.js)에서는 메인 스레드에서 처리
+- Worker는 싱글턴 패턴으로 공유됨 (`createClientProtocolWrapper` 여러 번 호출해도 Worker는 하나)
+- Worker 작업은 60초 타임아웃 후 자동 reject (메모리 누수 방지)
+- `decode` 시 Worker로 `ArrayBuffer` 소유권 이전 (zero-copy), 결과에서 `DateTime` 등 클래스 인스턴스 복원
+
+**CRITICAL — Worker 생성 패턴 제약:**
+Worker 생성 시 반드시 `new Worker(new URL("...", import.meta.url))` 직접 패턴을 사용해야 한다. sd-cli의 esbuild Worker 번들링 플러그인(`sd-worker-bundle`)이 AST에서 `new Worker(new URL(..., import.meta.url))` 패턴만 인식하여 Worker 파일을 별도 번들로 분리한다. 래퍼 함수(예: `createBrowserWorker(new URL(...))`)로 감싸면 `CallExpression`이 되어 플러그인이 인식하지 못하고, Worker 파일이 번들에 포함되지 않아 브라우저에서 404 에러가 발생한다.
+
+사용 예:
+
+```typescript
+import { createClientProtocolWrapper } from "@simplysm/service-client";
+import { createServiceProtocol } from "@simplysm/service-common";
+
+const protocol = createServiceProtocol();
+const wrapper = createClientProtocolWrapper(protocol);
+
+const { chunks, totalSize } = await wrapper.encode("uuid-1", { name: "User.getList", body: [] });
+
+// 사용 완료 후 정리
+wrapper.dispose();
+```

package/docs/transport.md

@@ -0,0 +1,131 @@
+# Transport
+
+## `SocketProviderEvents`
+
+`SocketProvider`에서 발생하는 이벤트 타입 맵.
+
+```typescript
+export interface SocketProviderEvents {
+  message: Bytes;
+  state: "connected" | "closed" | "reconnecting";
+}
+```
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `message` | `Bytes` | 서버로부터 바이너리 메시지 수신 |
+| `state` | `"connected" \| "closed" \| "reconnecting"` | 연결 상태 변경 |
+
+## `SocketProvider`
+
+WebSocket 연결, 재연결, 하트비트를 관리하는 인터페이스. 팩토리 함수 `createSocketProvider`로 생성한다.
+
+```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 | Type | Description |
+|--------|------|-------------|
+| `clientName` | `string` | 클라이언트 식별자 (읽기 전용) |
+| `connected` | `boolean` | 현재 연결 상태 (읽기 전용) |
+| `on(type, listener)` | `void` | 이벤트 리스너 등록 |
+| `off(type, listener)` | `void` | 이벤트 리스너 제거 |
+| `connect()` | `Promise<void>` | WebSocket 연결 시작 |
+| `close()` | `Promise<void>` | WebSocket 연결 종료 |
+| `send(data)` | `Promise<void>` | 바이너리 데이터 전송. 연결 복구 대기 후 전송 |
+
+## `createSocketProvider`
+
+`SocketProvider` 팩토리 함수.
+
+```typescript
+export function createSocketProvider(
+  url: string,
+  clientName: string,
+  maxReconnectCount: number,
+): SocketProvider;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | WebSocket 서버 URL (`ws://` 또는 `wss://`) |
+| `clientName` | `string` | 클라이언트 식별자 (URL 파라미터로 전달됨) |
+| `maxReconnectCount` | `number` | 최대 재연결 횟수. `0`이면 재연결 안 함 |
+
+내부 동작:
+- 하트비트: 5초마다 ping 전송, 30초 응답 없으면 재연결 시도
+- 재연결: 연결 끊김 시 3초 간격으로 `maxReconnectCount`회 재시도
+- Node.js 환경에서 `globalThis.WebSocket`이 없으면 `ws` 패키지로 폴리필
+
+## `ServiceTransportEvents`
+
+`ServiceTransport`에서 발생하는 이벤트 타입 맵.
+
+```typescript
+export interface ServiceTransportEvents {
+  event: { keys: string[]; data: unknown };
+}
+```
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `event` | `{ keys: string[]; data: unknown }` | 서버에서 발행된 이벤트 수신 |
+
+## `ServiceTransport`
+
+요청-응답 매핑, progress 중계, 서버 이벤트 디스패치를 담당하는 인터페이스.
+
+```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>;
+}
+```
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `on(type, listener)` | `void` | 이벤트 리스너 등록 |
+| `off(type, listener)` | `void` | 이벤트 리스너 제거 |
+| `send(message, progress?)` | `Promise<unknown>` | 서버에 메시지 전송하고 응답 대기 |
+
+## `createServiceTransport`
+
+`ServiceTransport` 팩토리 함수.
+
+```typescript
+export function createServiceTransport(
+  socket: SocketProvider,
+  protocol: ClientProtocolWrapper,
+): ServiceTransport;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `socket` | `SocketProvider` | WebSocket 소켓 제공자 |
+| `protocol` | `ClientProtocolWrapper` | 인코딩/디코딩 래퍼 |
+
+내부 동작:
+- `uuid` 기반 요청-응답 `Map`으로 비동기 응답을 매핑
+- 소켓 `closed`/`reconnecting` 상태 시 대기 중인 모든 요청을 reject
+- 분할 메시지의 progress 상태를 추적하여 완료 시 100% 이벤트 전송

package/docs/types.md

@@ -0,0 +1,93 @@
+# Types
+
+## `BlobInput`
+
+Blob constructor가 허용하는 데이터 타입. DOM `BlobPart`를 대체하여 Node.js / 브라우저 양쪽에서 typecheck가 통과하도록 한다.
+
+```typescript
+export type BlobInput = Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | string;
+```
+
+## `FileCollection`
+
+File 컬렉션 인터페이스. DOM `FileList`를 대체하며 브라우저 `FileList`와 구조적으로 호환된다.
+
+```typescript
+export interface FileCollection {
+  readonly length: number;
+  item(index: number): File | null;
+  [index: number]: File;
+  [Symbol.iterator](): IterableIterator<File>;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `length` | `number` | 파일 개수 |
+| `item(index)` | `File \| null` | 인덱스로 File 반환 |
+| `[index]` | `File` | 인덱스 접근자 |
+| `[Symbol.iterator]()` | `IterableIterator<File>` | for-of 이터레이션 지원 |
+
+## `isWorkerSupported`
+
+Web Worker API 지원 여부를 확인한다. `globalThis.Worker` 존재 여부로 판별한다.
+
+```typescript
+export function isWorkerSupported(): boolean;
+```
+
+## `ServiceConnectionOptions`
+
+서비스 서버에 연결할 때 사용하는 옵션 인터페이스.
+
+```typescript
+export interface ServiceConnectionOptions {
+  port: number;
+  host: string;
+  ssl?: boolean;
+  maxReconnectCount?: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `port` | `number` | 서버 포트 번호 |
+| `host` | `string` | 서버 호스트 주소 |
+| `ssl` | `boolean?` | HTTPS/WSS 사용 여부 |
+| `maxReconnectCount` | `number?` | 최대 재연결 횟수. `0`이면 재연결 비활성화. 기본값 `10` |
+
+## `ServiceProgress`
+
+요청/응답/서버 단계별 progress 콜백을 담는 컨테이너 인터페이스.
+
+```typescript
+export interface ServiceProgress {
+  request?: (s: ServiceProgressState) => void;
+  response?: (s: ServiceProgressState) => void;
+  server?: (s: ServiceProgressState) => void;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `request` | `((s: ServiceProgressState) => void)?` | 클라이언트 → 서버 전송 progress |
+| `response` | `((s: ServiceProgressState) => void)?` | 서버 → 클라이언트 수신 progress |
+| `server` | `((s: ServiceProgressState) => void)?` | 서버 내부 처리 progress |
+
+## `ServiceProgressState`
+
+progress 콜백에 전달되는 상태 객체.
+
+```typescript
+export interface ServiceProgressState {
+  uuid: string;
+  totalSize: number;
+  completedSize: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `uuid` | `string` | 요청 식별자 |
+| `totalSize` | `number` | 전체 크기 (bytes) |
+| `completedSize` | `number` | 완료된 크기 (bytes) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-client",
-  "version": "14.0.47",
+  "version": "14.0.49",
   "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.47",
-    "@simplysm/orm-common": "14.0.47",
-    "@simplysm/service-common": "14.0.47"
+    "@simplysm/core-common": "14.0.49",
+    "@simplysm/service-common": "14.0.49",
+    "@simplysm/orm-common": "14.0.49"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1",