@simplysm/service-client 14.0.51 → 14.0.52

package/package.json

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

package/README.md

@@ -1,115 +0,0 @@
-# @simplysm/service-client
-
-WebSocket 기반 서비스 서버 클라이언트로, 서비스 호출, 실시간 이벤트 구독/발행, 파일 업로드/다운로드, ORM 원격 실행을 지원한다.
-
-## Installation
-
-```bash
-npm install @simplysm/service-client
-```
-
-## API Overview
-
-### Main
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`ServiceClient`](./docs/main/service-client.md) | class | WebSocket 서비스 클라이언트 최상위 파사드 (연결, RPC, 이벤트, 파일, ORM 통합) |
-| [`ServiceProxy<T>`](./docs/main/service-client.md) | type | 서비스 메서드 반환 타입을 Promise로 래핑하는 타입 변환기 |
-| [`createServiceClient()`](./docs/main/service-client.md) | function | ServiceClient 인스턴스 생성 팩토리 함수 |
-
-### Transport
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`SocketProvider`](./docs/transport/socket-provider.md) | interface | WebSocket 래퍼 (connect, close, send, on, off, 하트비트·재연결 관리) |
-| [`SocketProviderEvents`](./docs/transport/socket-provider.md) | interface | SocketProvider 이벤트 맵 (message, state) |
-| [`createSocketProvider()`](./docs/transport/socket-provider.md) | function | SocketProvider 팩토리 |
-| [`ServiceTransport`](./docs/transport/service-transport.md) | interface | 요청-응답 매핑, progress 중계, 이벤트 디스패치 |
-| [`ServiceTransportEvents`](./docs/transport/service-transport.md) | interface | ServiceTransport 이벤트 맵 (event) |
-| [`createServiceTransport()`](./docs/transport/service-transport.md) | function | ServiceTransport 팩토리 |
-
-### Protocol
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`ClientProtocolWrapper`](./docs/protocol/client-protocol-wrapper.md) | interface | 메시지 인코딩/디코딩 (30KB 이상 시 Web Worker 오프로드) |
-| [`createClientProtocolWrapper()`](./docs/protocol/client-protocol-wrapper.md) | function | ClientProtocolWrapper 팩토리 |
-
-### Features
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`EventClient`](./docs/features/event-client.md) | interface | 서버 이벤트 구독/발행 관리 (재연결 시 자동 재구독) |
-| [`ClientEventProxy<T>`](./docs/features/event-client.md) | interface | 특정 이벤트에 대한 프록시 인터페이스 |
-| [`createEventClient()`](./docs/features/event-client.md) | function | EventClient 팩토리 |
-| [`FileClient`](./docs/features/file-client.md) | interface | 파일 업로드(POST)/다운로드(GET) |
-| [`createFileClient()`](./docs/features/file-client.md) | function | FileClient 팩토리 |
-| [`OrmClientConnector`](./docs/features/orm-client-connector.md) | interface | DbContext 원격 트랜잭션 연결 헬퍼 |
-| [`OrmConnectOptions<T>`](./docs/features/orm-client-connector.md) | interface | ORM 연결 설정 (DbClass, connOpt, dbContextOpt) |
-| [`createOrmClientConnector()`](./docs/features/orm-client-connector.md) | function | OrmClientConnector 팩토리 |
-| [`OrmClientDbContextExecutor`](./docs/features/orm-client-db-context-executor.md) | class | DbContextExecutor 구현체 (서버로 원격 호출) |
-
-### Types
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`ServiceConnectionOptions`](./docs/types/service-connection-options.md) | interface | 서버 연결 옵션 (host, port, ssl, maxReconnectCount) |
-| [`ServiceProgress`](./docs/types/service-progress.md) | interface | progress 콜백 인터페이스 (request, response, server) |
-| [`ServiceProgressState`](./docs/types/service-progress.md) | interface | progress 상태 (uuid, totalSize, completedSize) |
-| [`BlobInput`](./docs/types/blob-input.md) | type | `Blob \| Uint8Array \| ArrayBuffer \| string` (Blob 생성자 허용 타입) |
-| [`FileCollection`](./docs/types/file-collection.md) | interface | FileList 호환 컬렉션 인터페이스 |
-| [`BrowserWorker`](./docs/types/browser-worker.md) | interface | Web Worker 최소 인터페이스 (cross-env 타입 호환용) |
-| [`isBrowserWorkerSupported()`](./docs/types/browser-worker.md) | function | DOM Worker API 지원 여부 확인 |
-| [`isNodeWorkerSupported()`](./docs/types/browser-worker.md) | function | Node.js worker_threads 지원 여부 확인 |
-| [`isWorkerSupported()`](./docs/types/browser-worker.md) | function | Worker 오프로딩 지원 여부 확인 |
-
-## Usage Examples
-
-### 기본 연결 및 서비스 호출
-
-```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("jwt-token");
-
-// 타입 안전한 서비스 프록시
-const userSvc = client.getService<UserService>("User");
-const users = await userSvc.getAll();
-
-await client.close();
-```
-
-### 이벤트 구독
-
-```typescript
-// 이벤트 프록시 방식 (권장)
-const chatEvt = client.getEvent<typeof ChatEvent>("Chat");
-const key = await chatEvt.addListener({ roomId: "room-1" }, async (data) => {
-  console.log("메시지:", data.message);
-});
-await chatEvt.removeListener(key);
-
-// 발행
-await chatEvt.emit((info) => info.roomId === "room-1", { message: "hello" });
-```
-
-### ORM 원격 실행
-
-```typescript
-import { createOrmClientConnector } from "@simplysm/service-client";
-
-const connector = createOrmClientConnector(client);
-const result = await connector.connect(
-  { DbClass: MyDbContext, connOpt: { configName: "main" } },
-  async (db) => db.users.select().execute(),
-);
-```

package/docs/features/event-client.md

@@ -1,88 +0,0 @@
-# EventClient
-
-서버 이벤트 구독/발행 관리 인터페이스. 재연결 시 자동 재구독된다. 팩토리 함수 `createEventClient`로 생성한다.
-
-```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>;
-}
-```
-
-## Members
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `getEvent(eventName)` | method | `ClientEventProxy<TEventDef>` | 이벤트 이름과 타입을 캡처한 프록시 반환 |
-| `addListener(eventName, info, cb)` | method | `Promise<string>` | 이벤트 리스너 등록. 반환값은 `key` (제거 시 사용) |
-| `removeListener(key)` | method | `Promise<void>` | 등록된 이벤트 리스너 제거 |
-| `emit(eventName, infoSelector, data)` | method | `Promise<void>` | `infoSelector`가 참인 대상에게 데이터 발행 |
-| `resubscribeAll()` | method | `Promise<void>` | 재연결 시 모든 리스너를 서버에 재등록. `ServiceClient`가 자동 호출 |
-
-## Related Types
-
-### `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`가 참인 대상에게 데이터 발행 |
-
-## `createEventClient`
-
-`EventClient` 팩토리 함수.
-
-```typescript
-export function createEventClient(transport: ServiceTransport): EventClient;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `transport` | [`ServiceTransport`](../transport/service-transport.md) | 서비스 전송 계층 |
-
-## Usage
-
-```typescript
-// getEvent() 방식 (권장 — 이벤트 이름과 타입이 캡처됨)
-const chatEvt = client.getEvent<typeof ChatEvent>("Chat");
-const key = await chatEvt.addListener({ roomId: "room-1" }, async (data) => {
-  console.log("메시지:", data.message);
-});
-await chatEvt.removeListener(key);
-
-// 이벤트 발행
-await chatEvt.emit(
-  (info) => info.roomId === "room-1",
-  { message: "hello" },
-);
-```

package/docs/features/file-client.md

@@ -1,58 +0,0 @@
-# FileClient
-
-파일 업로드(POST)/다운로드(GET) 인터페이스. 팩토리 함수 `createFileClient`로 생성한다.
-
-```typescript
-export interface FileClient {
-  download(relPath: string): Promise<Bytes>;
-  upload(
-    files: File[] | FileCollection | { name: string; data: BlobInput }[],
-    authToken: string,
-  ): Promise<ServiceUploadResult[]>;
-}
-```
-
-## Members
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `download(relPath)` | method | `Promise<Bytes>` | `GET {hostUrl}{relPath}`로 파일 다운로드. `Uint8Array` 반환 |
-| `upload(files, authToken)` | method | `Promise<ServiceUploadResult[]>` | `POST {hostUrl}/upload`로 파일 업로드. `multipart/form-data` 사용 |
-
-### `upload` Parameters
-
-| 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` 헤더로 전송) |
-
-## Usage
-
-```typescript
-// 일반적으로 ServiceClient를 통해 간접 사용한다
-// 파일 업로드 (auth() 호출 후 사용)
-const results = await client.uploadFile([
-  new File(["content"], "file.txt", { type: "text/plain" }),
-]);
-
-// 커스텀 데이터 업로드
-const results2 = await client.uploadFile([
-  { name: "report.csv", data: "col1,col2\nval1,val2" },
-]);
-
-// 파일 다운로드
-const bytes = await client.downloadFileBuffer("/uploaded/file.txt");
-```

package/docs/features/orm-client-connector.md

@@ -1,83 +0,0 @@
-# OrmClientConnector
-
-`DbContext` 트랜잭션 연결을 원격 서버에서 실행하는 헬퍼 인터페이스. 팩토리 함수 `createOrmClientConnector`로 생성한다.
-
-```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>;
-}
-```
-
-## Members
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `connect(config, callback)` | method | `Promise<R>` | 트랜잭션 모드로 연결. FK 제약 위반 시 사용자 친화적 에러 메시지로 변환 |
-| `connectWithoutTransaction(config, callback)` | method | `Promise<R>` | 트랜잭션 없이 연결 |
-
-## Related Types
-
-### `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 | Required | Description |
-|-------|------|----------|-------------|
-| `DbClass` | `new (executor: DbContextExecutor, opt: { database: string; schema?: string }) => T` | required | 사용할 `DbContext` 서브클래스 생성자 |
-| `connOpt` | `DbConnOptions & { configName: string }` | required | DB 연결 옵션. `configName`은 서버 설정 키 |
-| `dbContextOpt` | `{ database: string; schema: string }` | optional | DB 컨텍스트 옵션. 생략하면 서버에서 조회한 `info.database`/`info.schema` 사용 |
-
-## `createOrmClientConnector`
-
-`OrmClientConnector` 팩토리 함수.
-
-```typescript
-export function createOrmClientConnector(serviceClient: ServiceClient): OrmClientConnector;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `serviceClient` | [`ServiceClient`](../main/service-client.md) | 이미 연결된 서비스 클라이언트 |
-
-## Usage
-
-```typescript
-import { createOrmClientConnector } from "@simplysm/service-client";
-
-const connector = createOrmClientConnector(client);
-
-// 트랜잭션 모드
-const result = await connector.connect(
-  {
-    DbClass: MyDbContext,
-    connOpt: { configName: "main", username: "user", password: "pass" },
-  },
-  async (db) => {
-    return db.myTable.select((item) => ({ id: item.id, name: item.name }));
-  },
-);
-
-// 트랜잭션 없이
-const result2 = await connector.connectWithoutTransaction(
-  { DbClass: MyDbContext, connOpt: { configName: "main" } },
-  async (db) => db.myTable.select(),
-);
-```

package/docs/features/orm-client-db-context-executor.md

@@ -1,26 +0,0 @@
-# OrmClientDbContextExecutor
-
-`DbContextExecutor` 인터페이스 구현체. `DbContext`의 쿼리 실행을 서버 `OrmService`에 원격 호출한다. 직접 사용보다 [`createOrmClientConnector`](./orm-client-connector.md)를 통해 사용하는 것을 권장한다.
-
-```typescript
-export class OrmClientDbContextExecutor implements DbContextExecutor {
-  constructor(
-    private readonly _client: ServiceClient,
-    private readonly _opt: DbConnOptions & { configName: string },
-  );
-}
-```
-
-## Members
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `getInfo()` | method | `Promise<{ dialect: Dialect; database?: string; schema?: string }>` | 서버에서 DB dialect, database, schema 조회 |
-| `connect()` | method | `Promise<void>` | 서버에서 DB 연결 생성. `_connId` 할당 |
-| `beginTransaction(isolationLevel?)` | method | `Promise<void>` | 트랜잭션 시작 |
-| `commitTransaction()` | method | `Promise<void>` | 트랜잭션 커밋 |
-| `rollbackTransaction()` | method | `Promise<void>` | 트랜잭션 롤백 |
-| `close()` | method | `Promise<void>` | DB 연결 종료 및 `_connId` 해제 |
-| `executeDefs(defs, options?)` | method | `Promise<T[][]>` | QueryDef 배열을 서버에서 실행 |
-| `executeParametrized(query, params?)` | method | `Promise<unknown[][]>` | 파라미터화된 쿼리를 서버에서 실행 |
-| `bulkInsert(tableName, columnDefs, records)` | method | `Promise<void>` | 대량 INSERT를 서버에서 실행 |

package/docs/main/service-client.md

@@ -1,147 +0,0 @@
-# ServiceClient
-
-WebSocket 기반 서비스 클라이언트의 최상위 파사드 클래스. [`SocketProvider`](../transport/socket-provider.md), [`ClientProtocolWrapper`](../protocol/client-protocol-wrapper.md), [`ServiceTransport`](../transport/service-transport.md), [`EventClient`](../features/event-client.md), [`FileClient`](../features/file-client.md)를 내부적으로 조합한다.
-
-```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>;
-  connect(): Promise<void>;
-  close(): Promise<void>;
-  send(
-    serviceName: string,
-    methodName: string,
-    params: unknown[],
-    progress?: ServiceProgress,
-  ): Promise<unknown>;
-  auth(token: string): Promise<void>;
-  addListener<TEventDef extends ServiceEventDef>(
-    eventName: string,
-    info: TEventDef["$info"],
-    cb: (data: TEventDef["$data"]) => PromiseLike<void>,
-  ): Promise<string>;
-  removeListener(key: string): Promise<void>;
-  emitEvent<TEventDef extends ServiceEventDef>(
-    eventName: string,
-    infoSelector: (item: TEventDef["$info"]) => boolean,
-    data: TEventDef["$data"],
-  ): Promise<void>;
-  uploadFile(
-    files: File[] | FileCollection | { name: string; data: BlobInput }[],
-  ): Promise<ServiceUploadResult[]>;
-  downloadFileBuffer(relPath: string): Promise<Bytes>;
-}
-```
-
-## Constructor Parameters
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `name` | `string` | 클라이언트 식별자 (WebSocket URL 파라미터 및 HTTP 헤더로 전달됨) |
-| `options` | [`ServiceConnectionOptions`](../types/service-connection-options.md) | 연결 옵션 |
-
-## Members
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `name` | property | `string` | 클라이언트 식별자 (읽기 전용) |
-| `options` | property | `ServiceConnectionOptions` | 연결 옵션 (읽기 전용) |
-| `connected` | getter | `boolean` | 현재 WebSocket 연결 상태 |
-| `hostUrl` | getter | `string` | HTTP 기본 URL (`http(s)://host:port`) |
-| `connect()` | method | `Promise<void>` | WebSocket 연결 시작 |
-| `close()` | method | `Promise<void>` | WebSocket 연결 종료 및 protocol dispose |
-| `auth(token)` | method | `Promise<void>` | 서버에 인증 토큰 전송. 재연결 시 자동 재인증됨 |
-| `getService<TService>(serviceName)` | method | `ServiceProxy<TService>` | 타입 안전한 서비스 프록시 반환 |
-| `getEvent<TEventDef>(eventName)` | method | `ClientEventProxy<TEventDef>` | 타입 안전한 이벤트 프록시 반환 |
-| `send(serviceName, methodName, params, progress?)` | method | `Promise<unknown>` | 서비스 메서드 원격 호출 |
-| `addListener(eventName, info, cb)` | method | `Promise<string>` | 서버 이벤트 구독. 연결 상태여야 함 |
-| `removeListener(key)` | method | `Promise<void>` | 서버 이벤트 구독 해제 |
-| `emitEvent(eventName, infoSelector, data)` | method | `Promise<void>` | 서버 이벤트 발행 |
-| `uploadFile(files)` | method | `Promise<ServiceUploadResult[]>` | 파일 업로드. `auth()` 호출 후 사용해야 함 |
-| `downloadFileBuffer(relPath)` | method | `Promise<Bytes>` | 파일 다운로드 (`Uint8Array` 반환) |
-
-## Events (EventEmitter)
-
-`ServiceClient`는 `EventEmitter<ServiceClientEvents>`를 상속한다. `.on()`/`.off()`로 이벤트를 구독한다.
-
-| Event | Data Type | Description |
-|-------|-----------|-------------|
-| `request-progress` | `ServiceProgressState` | 요청 전송 progress |
-| `response-progress` | `ServiceProgressState` | 응답 수신 progress |
-| `server-progress` | `ServiceProgressState` | 서버 내부 처리 progress |
-| `state` | `"connected" \| "closed" \| "reconnecting"` | 연결 상태 변경 |
-
-## Related Types
-
-### `ServiceProxy`
-
-`TService`의 모든 메서드 반환 타입을 `Promise`로 래핑하는 유틸리티 타입. `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` | 연결 옵션 |
-
-## Usage
-
-```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();
-
-// 이벤트 프록시 (권장)
-const chatEvt = client.getEvent<typeof ChatEvent>("Chat");
-const key = await chatEvt.addListener({ roomId: "room-1" }, async (data) => {
-  console.log("메시지:", data.message);
-});
-await chatEvt.removeListener(key);
-
-// 연결 상태 모니터링
-client.on("state", (state) => {
-  console.log("상태:", state); // "connected" | "closed" | "reconnecting"
-});
-
-// 파일 업로드
-const results = await client.uploadFile([{ name: "file.txt", data: "hello" }]);
-
-// 파일 다운로드
-const bytes = await client.downloadFileBuffer("/files/report.pdf");
-
-await client.close();
-```

package/docs/protocol/client-protocol-wrapper.md

@@ -1,59 +0,0 @@
-# ClientProtocolWrapper
-
-메시지 인코딩/디코딩 인터페이스. 데이터 크기가 30KB 이상이면 Web Worker로 처리를 오프로드한다. 팩토리 함수 `createClientProtocolWrapper`로 생성한다.
-
-```typescript
-export interface ClientProtocolWrapper {
-  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
-  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
-  dispose(): void;
-}
-```
-
-## Members
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `encode(uuid, message)` | method | `Promise<{ chunks: Bytes[]; totalSize: number }>` | 메시지를 바이너리 청크로 인코딩. 큰 데이터는 Worker로 오프로드 |
-| `decode(bytes)` | method | `Promise<ServiceMessageDecodeResult<ServiceMessage>>` | 바이너리를 메시지로 디코딩. 큰 데이터는 Worker로 오프로드 (zero-copy 전송) |
-| `dispose()` | method | `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가 지원되지 않는 환경에서는 메인 스레드에서 처리
-- Worker는 모듈 스코프 싱글턴으로 공유됨 (`createClientProtocolWrapper` 여러 번 호출해도 Worker는 하나)
-- Worker 작업은 60초 타임아웃 후 자동 reject (메모리 누수 방지)
-- `decode` 시 Worker로 `ArrayBuffer` 소유권 이전 (zero-copy)
-
-**Worker 생성 패턴 제약:**
-
-Worker 생성 시 반드시 `new Worker(new URL("...", import.meta.url))` 직접 패턴을 사용해야 한다. sd-cli의 esbuild Worker 번들링 플러그인(`sd-worker-bundle`)이 AST에서 이 패턴만 인식하여 Worker 파일을 별도 번들로 분리한다. 래퍼 함수로 감싸면 플러그인이 인식하지 못하고 브라우저에서 404 에러가 발생한다.
-
-## Usage
-
-```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: [] });
-// chunks: Bytes[] — 전송할 청크 배열
-// totalSize: number — 전체 크기 (progress 표시용)
-
-// 사용 완료 후 반드시 정리
-wrapper.dispose();
-```

package/docs/transport/service-transport.md

@@ -1,63 +0,0 @@
-# ServiceTransport
-
-요청-응답 매핑, progress 중계, 서버 이벤트 디스패치를 담당하는 인터페이스. 팩토리 함수 `createServiceTransport`로 생성한다.
-
-```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>;
-}
-```
-
-## Members
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `on(type, listener)` | method | `void` | 이벤트 리스너 등록 |
-| `off(type, listener)` | method | `void` | 이벤트 리스너 제거 |
-| `send(message, progress?)` | method | `Promise<unknown>` | 서버에 메시지 전송하고 응답 대기 |
-
-## Related Types
-
-### `ServiceTransportEvents`
-
-`ServiceTransport`에서 발생하는 이벤트 타입 맵.
-
-```typescript
-export interface ServiceTransportEvents {
-  event: { keys: string[]; data: unknown };
-}
-```
-
-| Event | Type | Description |
-|-------|------|-------------|
-| `event` | `{ keys: string[]; data: unknown }` | 서버에서 발행된 이벤트 수신 |
-
-## `createServiceTransport`
-
-`ServiceTransport` 팩토리 함수.
-
-```typescript
-export function createServiceTransport(
-  socket: SocketProvider,
-  protocol: ClientProtocolWrapper,
-): ServiceTransport;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `socket` | [`SocketProvider`](./socket-provider.md) | WebSocket 소켓 제공자 |
-| `protocol` | [`ClientProtocolWrapper`](../protocol/client-protocol-wrapper.md) | 인코딩/디코딩 래퍼 |
-
-내부 동작:
-- `uuid` 기반 요청-응답 `Map`으로 비동기 응답을 매핑
-- 소켓 `closed`/`reconnecting` 상태 시 대기 중인 모든 요청을 reject
-- 분할 메시지의 progress 상태를 추적하여 완료 시 100% 이벤트 전송
-- 소켓 `message` 이벤트를 수신하여 `progress`, `response`, `error`, `evt:on` 타입으로 분기 처리

package/docs/transport/socket-provider.md

@@ -1,95 +0,0 @@
-# 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>;
-}
-```
-
-## Members
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `clientName` | property | `string` | 클라이언트 식별자 (읽기 전용) |
-| `connected` | getter | `boolean` | 현재 연결 상태 |
-| `on(type, listener)` | method | `void` | 이벤트 리스너 등록 |
-| `off(type, listener)` | method | `void` | 이벤트 리스너 제거 |
-| `connect()` | method | `Promise<void>` | WebSocket 연결 시작 |
-| `close()` | method | `Promise<void>` | WebSocket 연결 종료 |
-| `send(data)` | method | `Promise<void>` | 바이너리 데이터 전송. 연결 복구 대기 후 전송 |
-
-## Related Types
-
-### `SocketProviderEvents`
-
-`SocketProvider`에서 발생하는 이벤트 타입 맵.
-
-```typescript
-export interface SocketProviderEvents {
-  message: Bytes;
-  state: "connected" | "closed" | "reconnecting";
-}
-```
-
-| Event | Type | Description |
-|-------|------|-------------|
-| `message` | `Bytes` | 서버로부터 바이너리 메시지 수신 |
-| `state` | `"connected" \| "closed" \| "reconnecting"` | 연결 상태 변경 |
-
-## `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 파라미터 `clientName`으로 전달됨) |
-| `maxReconnectCount` | `number` | 최대 재연결 횟수. `0`이면 재연결 안 함 |
-
-내부 동작:
-- 하트비트: 5초마다 ping 전송, 30초 응답 없으면 재연결 시도
-- 재연결: 연결 끊김 시 3초 간격으로 `maxReconnectCount`회 재시도
-- Node.js 환경에서 `globalThis.WebSocket`이 없으면 `ws` 패키지로 폴리필
-- ping/pong은 1바이트 패킷(ping: `0x01`, pong: `0x02`)으로 처리
-
-## Usage
-
-```typescript
-import { createSocketProvider } from "@simplysm/service-client";
-
-const socket = createSocketProvider("ws://localhost:3000/ws", "my-app", 10);
-
-socket.on("state", (state) => {
-  console.log("소켓 상태:", state); // "connected" | "closed" | "reconnecting"
-});
-
-socket.on("message", (bytes) => {
-  console.log("메시지 수신:", bytes.length, "bytes");
-});
-
-await socket.connect();
-await socket.send(new Uint8Array([1, 2, 3]));
-await socket.close();
-```

package/docs/types/blob-input.md

@@ -1,7 +0,0 @@
-# BlobInput
-
-Blob constructor가 허용하는 데이터 타입. DOM `BlobPart`를 대체하여 Node.js / 브라우저 양쪽에서 typecheck가 통과하도록 한다.
-
-```typescript
-export type BlobInput = Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | string;
-```

package/docs/types/browser-worker.md

@@ -1,47 +0,0 @@
-# BrowserWorker
-
-Web Worker 최소 인터페이스. DOM lib 없이도 타입체크가 통과하도록 하는 추상 타입이다.
-
-```typescript
-export interface BrowserWorker {
-  onmessage: ((event: MessageEvent) => void) | null;
-  onerror: ((event: Event) => void) | null;
-  postMessage(message: unknown, transfer?: unknown[]): void;
-  terminate(): void;
-}
-```
-
-## Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `onmessage` | `((event: MessageEvent) => void) \| null` | 메시지 수신 핸들러 |
-| `onerror` | `((event: Event) => void) \| null` | 에러 핸들러 |
-| `postMessage(message, transfer?)` | `void` | Worker에 메시지 전송 |
-| `terminate()` | `void` | Worker 종료 |
-
-## Related Functions
-
-### `isBrowserWorkerSupported`
-
-DOM Worker API 지원 여부를 확인한다. `"Worker" in globalThis`로 판별한다.
-
-```typescript
-export function isBrowserWorkerSupported(): boolean;
-```
-
-### `isNodeWorkerSupported`
-
-Node.js `worker_threads` 지원 여부를 확인한다. `process.versions.node` 존재 여부로 판별한다.
-
-```typescript
-export function isNodeWorkerSupported(): boolean;
-```
-
-### `isWorkerSupported`
-
-Worker 오프로딩 지원 여부를 확인한다. `isBrowserWorkerSupported() || isNodeWorkerSupported()`를 반환한다.
-
-```typescript
-export function isWorkerSupported(): boolean;
-```

package/docs/types/file-collection.md

@@ -1,21 +0,0 @@
-# FileCollection
-
-File 컬렉션 인터페이스. DOM `FileList`를 대체하며 브라우저 `FileList`와 구조적으로 호환된다.
-
-```typescript
-export interface FileCollection {
-  readonly length: number;
-  item(index: number): File | null;
-  [index: number]: File;
-  [Symbol.iterator](): IterableIterator<File>;
-}
-```
-
-## Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `length` | `number` | 파일 개수 (읽기 전용) |
-| `item(index)` | `File \| null` | 인덱스로 File 반환 |
-| `[index]` | `File` | 인덱스 접근자 |
-| `[Symbol.iterator]()` | `IterableIterator<File>` | for-of 이터레이션 지원 |

package/docs/types/service-connection-options.md

@@ -1,22 +0,0 @@
-# ServiceConnectionOptions
-
-서비스 서버에 연결할 때 사용하는 옵션 인터페이스.
-
-```typescript
-export interface ServiceConnectionOptions {
-  port: number;
-  host: string;
-  ssl?: boolean;
-  /** 0으로 설정하면 재연결을 비활성화하고 즉시 연결을 끊음 */
-  maxReconnectCount?: number;
-}
-```
-
-## Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `port` | `number` | required | 서버 포트 번호 |
-| `host` | `string` | required | 서버 호스트 주소 |
-| `ssl` | `boolean` | optional | HTTPS/WSS 사용 여부. 기본값 `false` |
-| `maxReconnectCount` | `number` | optional | 최대 재연결 횟수. `0`이면 재연결 비활성화. `ServiceClient` 기본값 `10` |

package/docs/types/service-progress.md

@@ -1,39 +0,0 @@
-# ServiceProgress
-
-요청/응답/서버 단계별 progress 콜백을 담는 컨테이너 인터페이스.
-
-```typescript
-export interface ServiceProgress {
-  request?: (s: ServiceProgressState) => void;
-  response?: (s: ServiceProgressState) => void;
-  server?: (s: ServiceProgressState) => void;
-}
-```
-
-## Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `request` | `(s: ServiceProgressState) => void` | optional | 클라이언트 → 서버 전송 progress |
-| `response` | `(s: ServiceProgressState) => void` | optional | 서버 → 클라이언트 수신 progress |
-| `server` | `(s: ServiceProgressState) => void` | optional | 서버 내부 처리 progress |
-
-## Related Types
-
-### `ServiceProgressState`
-
-progress 콜백에 전달되는 상태 객체.
-
-```typescript
-export interface ServiceProgressState {
-  uuid: string;
-  totalSize: number;
-  completedSize: number;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `uuid` | `string` | 요청 식별자 |
-| `totalSize` | `number` | 전체 크기 (bytes) |
-| `completedSize` | `number` | 완료된 크기 (bytes) |