@simplysm/service-client 14.0.49 → 14.0.51

package/docs/features.md

@@ -1,217 +0,0 @@
-# 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/transport.md

@@ -1,131 +0,0 @@
-# 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

@@ -1,93 +0,0 @@
-# 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) |