@simplysm/service-client 13.0.100 → 14.0.4

package/src/types/browser-compat.ts

@@ -0,0 +1,47 @@
+/**
+ * Cross-environment compatible types for browser globals.
+ * DOM-only 타입(FileList, BlobPart, Worker, Transferable)을 대체하여
+ * Node.js / browser 양쪽 환경에서 typecheck가 통과하도록 한다.
+ */
+
+/** Blob constructor가 허용하는 데이터 타입 (DOM BlobPart 대체) */
+export type BlobInput = Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | string;
+
+/**
+ * File 컬렉션 인터페이스 (DOM FileList 대체).
+ * 브라우저 FileList와 구조적으로 호환됨.
+ */
+export interface FileCollection {
+  readonly length: number;
+  item(index: number): File | null;
+  [index: number]: File;
+  [Symbol.iterator](): IterableIterator<File>;
+}
+
+/**
+ * Web Worker 인터페이스 (DOM Worker 대체).
+ * 브라우저 Worker와 구조적으로 호환됨.
+ */
+export interface WorkerLike {
+  onmessage: ((ev: MessageEvent) => void) | null;
+  postMessage(message: unknown, transfer?: unknown[]): void;
+  terminate(): void;
+}
+
+/** Web Worker API 지원 여부 확인 */
+export function isWorkerSupported(): boolean {
+  return "Worker" in globalThis;
+}
+
+/** Web Worker 생성 (미지원 환경이면 undefined) */
+export function createBrowserWorker(
+  url: URL,
+  options: { type: string },
+): WorkerLike | undefined {
+  if (!isWorkerSupported()) return undefined;
+  const ctor = (globalThis as Record<string, unknown>)["Worker"] as new (
+    url: URL,
+    opts: { type: string },
+  ) => WorkerLike;
+  return new ctor(url, options);
+}

package/src/types/connection-options.ts

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

package/src/types/progress.types.ts

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

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

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

package/docs/features.md

@@ -1,143 +0,0 @@
-# Features
-
-## `EventClient`
-
-Client-side event management interface. Handles event listener registration, removal, emission, and auto-recovery on reconnect.
-
-```typescript
-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 | Description |
-|--------|-------------|
-| `addListener()` | Register an event listener on the server, returns listener key |
-| `removeListener()` | Remove an event listener by key |
-| `emit()` | Emit an event to matching listeners (server-side filtering) |
-| `resubscribeAll()` | Re-register all listeners on reconnect |
-
-## `createEventClient`
-
-Create an event client instance.
-
-```typescript
-function createEventClient(transport: ServiceTransport): EventClient;
-```
-
-## `FileClient`
-
-File upload/download client interface.
-
-```typescript
-interface FileClient {
-  download(relPath: string): Promise<Bytes>;
-  upload(
-    files: File[] | FileList | { name: string; data: BlobPart }[],
-    authToken: string,
-  ): Promise<ServiceUploadResult[]>;
-}
-```
-
-| Method | Description |
-|--------|-------------|
-| `download()` | Download a file by relative path, returns binary data |
-| `upload()` | Upload files via multipart form, returns upload results |
-
-## `createFileClient`
-
-Create a file client instance.
-
-```typescript
-function createFileClient(hostUrl: string, clientName: string): FileClient;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `hostUrl` | `string` | Server base URL (http:// or https://) |
-| `clientName` | `string` | Client name for request headers |
-
-## `OrmConnectOptions`
-
-ORM connection options for client-side database access.
-
-```typescript
-interface OrmConnectOptions<TDef extends DbContextDef<any, any, any>> {
-  dbContextDef: TDef;
-  connOpt: DbConnOptions & { configName: string };
-  dbContextOpt?: {
-    database: string;
-    schema: string;
-  };
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `dbContextDef` | `TDef` | DbContext definition |
-| `connOpt` | `DbConnOptions & { configName: string }` | Connection options with config name |
-| `dbContextOpt` | `{ database: string; schema: string }` | Override database/schema from server config |
-
-## `OrmClientConnector`
-
-Client-side ORM connector interface. Creates DbContext instances that execute queries via the service protocol.
-
-```typescript
-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 | Description |
-|--------|-------------|
-| `connect()` | Connect with transaction (auto commit/rollback) |
-| `connectWithoutTransaction()` | Connect without transaction |
-
-## `createOrmClientConnector`
-
-Create an ORM client connector.
-
-```typescript
-function createOrmClientConnector(serviceClient: ServiceClient): OrmClientConnector;
-```
-
-## `OrmClientDbContextExecutor`
-
-Client-side DbContext executor. Implements `DbContextExecutor` by delegating to the ORM service over the service protocol.
-
-```typescript
-class OrmClientDbContextExecutor implements DbContextExecutor {
-  constructor(
-    private readonly _client: ServiceClient,
-    private readonly _opt: DbConnOptions & { configName: string },
-  );
-
-  getInfo(): Promise<{ dialect: Dialect; database?: string; schema?: string }>;
-  connect(): Promise<void>;
-  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
-  commitTransaction(): Promise<void>;
-  rollbackTransaction(): Promise<void>;
-  close(): Promise<void>;
-  executeDefs<T>(defs: QueryDef[], options?: (ResultMeta | undefined)[]): Promise<T[][]>;
-  executeParametrized(query: string, params?: unknown[]): Promise<unknown[][]>;
-  bulkInsert(tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]): Promise<void>;
-}
-```

package/docs/protocol.md

@@ -1,29 +0,0 @@
-# Protocol
-
-## `ClientProtocolWrapper`
-
-Client-side protocol wrapper interface. Handles message encoding/decoding with optional Web Worker offloading for large payloads (>30KB).
-
-```typescript
-interface ClientProtocolWrapper {
-  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
-  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
-}
-```
-
-| Method | Description |
-|--------|-------------|
-| `encode()` | Encode a message (delegates to Web Worker for large payloads) |
-| `decode()` | Decode a message (delegates to Web Worker for large payloads) |
-
-## `createClientProtocolWrapper`
-
-Create a client protocol wrapper instance. Automatically offloads heavy encoding/decoding to a Web Worker when available and payload exceeds 30KB.
-
-```typescript
-function createClientProtocolWrapper(protocol: ServiceProtocol): ClientProtocolWrapper;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `protocol` | `ServiceProtocol` | Base protocol instance from `createServiceProtocol()` |

package/docs/service-client.md

@@ -1,93 +0,0 @@
-# ServiceClient
-
-## `ServiceClient`
-
-Main client class that orchestrates all service communication modules. Extends `EventEmitter`.
-
-```typescript
-class ServiceClient extends EventEmitter<ServiceClientEvents> {
-  readonly name: string;
-  readonly options: ServiceConnectionOptions;
-  get connected(): boolean;
-  get hostUrl(): string;
-
-  constructor(name: string, options: ServiceConnectionOptions);
-
-  getService<TService>(serviceName: string): ServiceProxy<TService>;
-  connect(): Promise<void>;
-  close(): Promise<void>;
-  send(serviceName: string, methodName: string, params: unknown[], progress?: ServiceProgress): Promise<unknown>;
-  auth(token: string): Promise<void>;
-  addListener<TInfo, TData>(
-    eventDef: ServiceEventDef<TInfo, TData>,
-    info: TInfo,
-    cb: (data: TData) => PromiseLike<void>,
-  ): Promise<string>;
-  removeListener(key: string): Promise<void>;
-  emitEvent<TInfo, TData>(
-    eventDef: ServiceEventDef<TInfo, TData>,
-    infoSelector: (item: TInfo) => boolean,
-    data: TData,
-  ): Promise<void>;
-  uploadFile(files: File[] | FileList | { name: string; data: BlobPart }[]): Promise<ServiceUploadResult[]>;
-  downloadFileBuffer(relPath: string): Promise<Bytes>;
-}
-```
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `name` | `string` | Client name |
-| `options` | `ServiceConnectionOptions` | Connection options |
-| `connected` | `boolean` | Whether connected |
-| `hostUrl` | `string` | HTTP(S) base URL |
-
-| Method | Description |
-|--------|-------------|
-| `getService()` | Create a typed service proxy for calling remote methods |
-| `connect()` | Establish WebSocket connection |
-| `close()` | Close connection |
-| `send()` | Send a service method request |
-| `auth()` | Authenticate with JWT token |
-| `addListener()` | Add event listener |
-| `removeListener()` | Remove event listener |
-| `emitEvent()` | Emit event to matching listeners |
-| `uploadFile()` | Upload files (requires prior auth) |
-| `downloadFileBuffer()` | Download file as binary |
-
-## `ServiceClientEvents`
-
-Events emitted by `ServiceClient`.
-
-```typescript
-interface ServiceClientEvents {
-  "request-progress": ServiceProgressState;
-  "response-progress": ServiceProgressState;
-  "state": "connected" | "closed" | "reconnecting";
-  "reload": Set<string>;
-}
-```
-
-## `ServiceProxy`
-
-Type transformer that wraps all method return types of a service with `Promise`.
-
-```typescript
-type ServiceProxy<TService> = {
-  [K in keyof TService]: TService[K] extends (...args: infer P) => infer R
-    ? (...args: P) => Promise<Awaited<R>>
-    : never;
-};
-```
-
-## `createServiceClient`
-
-Factory function to create a `ServiceClient` instance.
-
-```typescript
-function createServiceClient(name: string, options: ServiceConnectionOptions): ServiceClient;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `name` | `string` | Client name identifier |
-| `options` | `ServiceConnectionOptions` | Connection options |

package/docs/transport.md

@@ -1,96 +0,0 @@
-# Transport
-
-## `SocketProvider`
-
-WebSocket connection provider interface. Manages connection lifecycle, heartbeat, and auto-reconnect.
-
-```typescript
-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>;
-}
-```
-
-| Property/Method | Description |
-|-----------------|-------------|
-| `clientName` | Client name identifier |
-| `connected` | Whether WebSocket is currently open |
-| `on()` | Register event listener |
-| `off()` | Remove event listener |
-| `connect()` | Establish WebSocket connection |
-| `close()` | Close connection (graceful shutdown) |
-| `send()` | Send binary data |
-
-## `SocketProviderEvents`
-
-Events emitted by `SocketProvider`.
-
-```typescript
-interface SocketProviderEvents {
-  message: Bytes;
-  state: "connected" | "closed" | "reconnecting";
-}
-```
-
-## `createSocketProvider`
-
-Create a WebSocket provider with heartbeat and auto-reconnect.
-
-```typescript
-function createSocketProvider(
-  url: string,
-  clientName: string,
-  maxReconnectCount: number,
-): SocketProvider;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `url` | `string` | WebSocket URL (ws:// or wss://) |
-| `clientName` | `string` | Client name identifier |
-| `maxReconnectCount` | `number` | Max reconnect attempts |
-
-## `ServiceTransport`
-
-Service transport interface. Handles message routing and request/response correlation.
-
-```typescript
-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 | Description |
-|--------|-------------|
-| `on()` | Register event listener (reload, event) |
-| `off()` | Remove event listener |
-| `send()` | Send a client message and await response |
-
-## `ServiceTransportEvents`
-
-Events emitted by `ServiceTransport`.
-
-```typescript
-interface ServiceTransportEvents {
-  reload: Set<string>;
-  event: { keys: string[]; data: unknown };
-}
-```
-
-## `createServiceTransport`
-
-Create a service transport instance.
-
-```typescript
-function createServiceTransport(
-  socket: SocketProvider,
-  protocol: ClientProtocolWrapper,
-): ServiceTransport;
-```

package/docs/types.md

@@ -1,55 +0,0 @@
-# Types
-
-## `ServiceConnectionOptions`
-
-Connection options for `ServiceClient`.
-
-```typescript
-interface ServiceConnectionOptions {
-  port: number;
-  host: string;
-  ssl?: boolean;
-  maxReconnectCount?: number;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `port` | `number` | Server port |
-| `host` | `string` | Server hostname |
-| `ssl` | `boolean` | Use SSL/TLS (wss:// and https://) |
-| `maxReconnectCount` | `number` | Max reconnect attempts (0 to disable, default: 10) |
-
-## `ServiceProgress`
-
-Progress callback configuration for service requests.
-
-```typescript
-interface ServiceProgress {
-  request?: (s: ServiceProgressState) => void;
-  response?: (s: ServiceProgressState) => void;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `request` | `(s: ServiceProgressState) => void` | Request upload progress callback |
-| `response` | `(s: ServiceProgressState) => void` | Response download progress callback |
-
-## `ServiceProgressState`
-
-Progress state for chunked message transfers.
-
-```typescript
-interface ServiceProgressState {
-  uuid: string;
-  totalSize: number;
-  completedSize: number;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `uuid` | `string` | Request UUID |
-| `totalSize` | `number` | Total message size in bytes |
-| `completedSize` | `number` | Completed size in bytes |