@simplysm/service-client 14.0.4 → 14.0.5

package/README.md

@@ -1,40 +1,95 @@
 # @simplysm/service-client
 
-Service client SDK -- WebSocket-based RPC client with type-safe service proxy, event subscription, file upload/download, and ORM connector.
+WebSocket-based RPC client SDK with type-safe service proxy, event subscription, file upload/download, and ORM connector. Depends on `@simplysm/service-common` for protocol and shared types.
 
-Depends on `@simplysm/service-common` for protocol and shared types.
+## Installation
 
-## API
+```bash
+npm install @simplysm/service-client
+```
+
+## API Overview
+
+### Browser Compat Types
+| API | Type | Description |
+|-----|------|-------------|
+| `BlobInput` | `type` | Blob constructor data type (DOM BlobPart replacement) |
+| `FileCollection` | `interface` | File collection interface (DOM FileList replacement) |
+| `WorkerLike` | `interface` | Web Worker interface (DOM Worker replacement) |
+| `isWorkerSupported` | `function` | Checks Web Worker API availability |
+| `createBrowserWorker` | `function` | Creates a Web Worker (returns undefined if unsupported) |
+
+-> See [docs/browser-compat-types.md](./docs/browser-compat-types.md) for details.
+
+### Connection Options
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceConnectionOptions` | `interface` | Connection options (host, port, SSL, reconnect) |
+
+-> See [docs/connection-options.md](./docs/connection-options.md) for details.
+
+### Progress Types
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceProgress` | `interface` | Progress callback hooks for request/response/server |
+| `ServiceProgressState` | `interface` | Progress state (uuid, totalSize, completedSize) |
+
+-> See [docs/progress-types.md](./docs/progress-types.md) for details.
+
+### Socket Provider
+| API | Type | Description |
+|-----|------|-------------|
+| `SocketProviderEvents` | `interface` | Socket provider event map |
+| `SocketProvider` | `interface` | Low-level WebSocket abstraction with auto-reconnect |
+| `createSocketProvider` | `function` | Creates a socket provider instance |
 
-| Export | Kind | Category | Description |
-|--------|------|----------|-------------|
-| `ServiceConnectionOptions` | interface | Types | Connection options (host, port, SSL, reconnect) |
-| `ServiceProgress` | interface | Types | Progress callback hooks for request/response/server |
-| `ServiceProgressState` | interface | Types | Progress state (uuid, totalSize, completedSize) |
-| `SocketProviderEvents` | interface | Transport | Socket provider event map |
-| `SocketProvider` | interface | Transport | Low-level WebSocket abstraction |
-| `createSocketProvider` | function | Transport | Create a socket provider instance |
-| `ServiceTransportEvents` | interface | Transport | Transport event map |
-| `ServiceTransport` | interface | Transport | Service-level message transport |
-| `createServiceTransport` | function | Transport | Create a service transport instance |
-| `ClientProtocolWrapper` | interface | Protocol | Client-side protocol encoder/decoder wrapper |
-| `createClientProtocolWrapper` | function | Protocol | Create a client protocol wrapper |
-| `EventClient` | interface | Features | Event subscription client |
-| `createEventClient` | function | Features | Create an event client |
-| `FileClient` | interface | Features | File upload/download client |
-| `createFileClient` | function | Features | Create a file client |
-| `OrmConnectOptions` | interface | Features | ORM connection options |
-| `OrmClientConnector` | interface | Features | ORM client connector (with/without transaction) |
-| `createOrmClientConnector` | function | Features | Create an ORM client connector |
-| `OrmClientDbContextExecutor` | class | Features | ORM DbContext executor for client-side use |
-| `ServiceClient` | class | Main | Main service client class |
-| `ServiceProxy` | type | Main | Type-safe service proxy mapping |
-| `createServiceClient` | function | Main | Create a ServiceClient instance |
+-> See [docs/socket-provider.md](./docs/socket-provider.md) for details.
 
-## Usage
+### Service Transport
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceTransportEvents` | `interface` | Transport event map |
+| `ServiceTransport` | `interface` | Service-level message transport |
+| `createServiceTransport` | `function` | Creates a service transport instance |
 
-```ts
+-> See [docs/service-transport.md](./docs/service-transport.md) for details.
+
+### Client Protocol Wrapper
+| API | Type | Description |
+|-----|------|-------------|
+| `ClientProtocolWrapper` | `interface` | Client-side protocol encoder/decoder with Web Worker offloading |
+| `createClientProtocolWrapper` | `function` | Creates a client protocol wrapper |
+
+-> See [docs/client-protocol-wrapper.md](./docs/client-protocol-wrapper.md) for details.
+
+### Event/File/ORM Client
+| API | Type | Description |
+|-----|------|-------------|
+| `EventClient` | `interface` | Event subscription client |
+| `createEventClient` | `function` | Creates an event client |
+| `FileClient` | `interface` | File upload/download client |
+| `createFileClient` | `function` | Creates a file client |
+| `OrmConnectOptions` | `interface` | ORM connection options |
+| `OrmClientConnector` | `interface` | ORM client connector (with/without transaction) |
+| `createOrmClientConnector` | `function` | Creates an ORM client connector |
+| `OrmClientDbContextExecutor` | `class` | ORM DbContext executor for client-side use |
+
+-> See [docs/features.md](./docs/features.md) for details.
+
+### Main ServiceClient
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceClient` | `class` | Main service client class with events, RPC, auth, file ops |
+| `ServiceProxy` | `type` | Type-safe service proxy mapping |
+| `createServiceClient` | `function` | Factory function to create a ServiceClient |
+
+-> See [docs/service-client.md](./docs/service-client.md) for details.
+
+## Usage Examples
+
+```typescript
 import { createServiceClient } from "@simplysm/service-client";
+import { defineEvent } from "@simplysm/service-common";
 
 // Create and connect
 const client = createServiceClient("my-app", {
@@ -61,9 +116,7 @@ const uploadResults = await client.uploadFile(fileList);
 const bytes = await client.downloadFileBuffer("uploads/file.txt");
 
 // Event subscription
-import { defineEvent } from "@simplysm/service-common";
 const ChatEvent = defineEvent<{ roomId: number }, { text: string }>("ChatEvent");
-
 const listenerKey = await client.addListener(ChatEvent, { roomId: 1 }, async (data) => {
   // handle event
 });
@@ -72,369 +125,3 @@ await client.removeListener(listenerKey);
 // Clean up
 await client.close();
 ```
-
-## Types
-
-### ServiceConnectionOptions
-
-```ts
-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 |
-| `maxReconnectCount` | `number?` | Max reconnection attempts. Set to `0` to disable reconnection and disconnect immediately. |
-
-### ServiceProgress
-
-Callback hooks for monitoring message progress.
-
-```ts
-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
-
-```ts
-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 |
-
-## Transport
-
-### SocketProviderEvents
-
-```ts
-interface SocketProviderEvents {
-  message: Bytes;
-  state: "connected" | "closed" | "reconnecting";
-}
-```
-
-| Event | Data Type | Description |
-|-------|-----------|-------------|
-| `message` | `Bytes` | Raw binary message received |
-| `state` | `"connected" \| "closed" \| "reconnecting"` | Connection state change |
-
-### SocketProvider
-
-Low-level WebSocket abstraction with auto-reconnect.
-
-```ts
-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 | Client identifier name |
-| `connected` | property | Whether currently connected |
-| `on` | method | Subscribe to an event |
-| `off` | method | Unsubscribe from an event |
-| `connect` | method | Open the WebSocket connection |
-| `close` | method | Close the connection |
-| `send` | method | Send binary data |
-
-### createSocketProvider
-
-```ts
-function createSocketProvider(url: string, clientName: string, maxReconnectCount: number): SocketProvider;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `url` | `string` | WebSocket URL |
-| `clientName` | `string` | Client identifier |
-| `maxReconnectCount` | `number` | Maximum reconnection attempts |
-
-### ServiceTransportEvents
-
-```ts
-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`.
-
-```ts
-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`, `listener` | `void` | Subscribe to transport events |
-| `off` | `type`, `listener` | `void` | Unsubscribe from transport events |
-| `send` | `message: ServiceClientMessage`, `progress?: ServiceProgress` | `Promise<unknown>` | Send a service message and await the response |
-
-### createServiceTransport
-
-```ts
-function createServiceTransport(socket: SocketProvider, protocol: ClientProtocolWrapper): ServiceTransport;
-```
-
-## Protocol
-
-### ClientProtocolWrapper
-
-Client-side protocol encoder/decoder wrapper.
-
-```ts
-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 }>` | Encode a message into binary chunks |
-| `decode` | `bytes: Bytes` | `Promise<ServiceMessageDecodeResult<ServiceMessage>>` | Decode received binary data |
-| `dispose` | -- | `void` | Clean up resources |
-
-### createClientProtocolWrapper
-
-```ts
-function createClientProtocolWrapper(protocol: ServiceProtocol): ClientProtocolWrapper;
-```
-
-Creates a `ClientProtocolWrapper` from a `ServiceProtocol` instance.
-
-## Features
-
-### EventClient
-
-Event subscription client for the service event system.
-
-```ts
-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`, `info: TInfo`, `cb` | `Promise<string>` | Subscribe to an event; returns listener key |
-| `removeListener` | `key: string` | `Promise<void>` | Unsubscribe by listener key |
-| `emit` | `eventDef`, `infoSelector`, `data: TData` | `Promise<void>` | Emit an event to matching listeners |
-| `resubscribeAll` | -- | `Promise<void>` | Resubscribe all listeners (e.g., after reconnect) |
-
-### createEventClient
-
-```ts
-function createEventClient(transport: ServiceTransport): EventClient;
-```
-
-### FileClient
-
-File upload and download client.
-
-```ts
-interface FileClient {
-  download(relPath: string): Promise<Bytes>;
-  upload(files: File[] | FileList | { name: string; data: BlobPart }[], authToken: string): Promise<ServiceUploadResult[]>;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `download` | `relPath: string` | `Promise<Bytes>` | Download a file by relative path |
-| `upload` | `files`, `authToken: string` | `Promise<ServiceUploadResult[]>` | Upload files with authentication |
-
-### createFileClient
-
-```ts
-function createFileClient(hostUrl: string, clientName: string): FileClient;
-```
-
-### OrmConnectOptions\<TDef\>
-
-```ts
-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.
-
-```ts
-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`, `callback` | `Promise<R>` | Open a DB context with automatic transaction (begin/commit/rollback) |
-| `connectWithoutTransaction` | `config`, `callback` | `Promise<R>` | Open a DB context without automatic transaction management |
-
-### createOrmClientConnector
-
-```ts
-function createOrmClientConnector(serviceClient: ServiceClient): OrmClientConnector;
-```
-
-### OrmClientDbContextExecutor
-
-Implements `DbContextExecutor` for client-side ORM usage over the service RPC layer.
-
-```ts
-class OrmClientDbContextExecutor implements DbContextExecutor {
-  constructor(client: ServiceClient, opt: DbConnOptions & { configName: string });
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getInfo` | -- | `Promise<{ dialect; database?; schema? }>` | Get database info |
-| `connect` | -- | `Promise<void>` | Open the connection |
-| `beginTransaction` | `isolationLevel?: IsolationLevel` | `Promise<void>` | Begin a transaction |
-| `commitTransaction` | -- | `Promise<void>` | Commit the transaction |
-| `rollbackTransaction` | -- | `Promise<void>` | Rollback the transaction |
-| `close` | -- | `Promise<void>` | Close the connection |
-| `executeDefs` | `defs: QueryDef[]`, `options?: (ResultMeta \| undefined)[]` | `Promise<T[][]>` | Execute query definitions |
-| `executeParametrized` | `query: string`, `params?: unknown[]` | `Promise<unknown[][]>` | Execute a parameterized query |
-| `bulkInsert` | `tableName: string`, `columnDefs: Record<string, ColumnMeta>`, `records: Record<string, unknown>[]` | `Promise<void>` | Bulk insert records |
-
-## Main
-
-### ServiceClient
-
-Main service client class. Extends `EventEmitter` with progress and state events.
-
-```ts
-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 |
-| `response-progress` | `ServiceProgressState` | Response receiving progress |
-| `server-progress` | `ServiceProgressState` | Server-side chunk progress |
-| `state` | `"connected" \| "closed" \| "reconnecting"` | Connection state change |
-
-#### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `name` | `string` | Client name |
-| `options` | `ServiceConnectionOptions` | Connection options |
-| `connected` | `boolean` | Whether the client is connected |
-| `hostUrl` | `string` | Full host URL (computed from options) |
-
-#### Methods
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getService<TService>` | `serviceName: string` | `ServiceProxy<TService>` | Get a type-safe service proxy |
-| `connect` | -- | `Promise<void>` | Open the WebSocket connection |
-| `close` | -- | `Promise<void>` | Close the connection |
-| `send` | `serviceName`, `methodName`, `params`, `progress?` | `Promise<unknown>` | Send an RPC call |
-| `auth` | `token: string` | `Promise<void>` | Authenticate with a JWT token |
-| `addListener` | `eventDef`, `info`, `cb` | `Promise<string>` | Subscribe to an event |
-| `removeListener` | `key: string` | `Promise<void>` | Unsubscribe from an event |
-| `emitEvent` | `eventDef`, `infoSelector`, `data` | `Promise<void>` | Emit an event |
-| `uploadFile` | `files` | `Promise<ServiceUploadResult[]>` | Upload files |
-| `downloadFileBuffer` | `relPath: string` | `Promise<Bytes>` | Download a file |
-
-### ServiceProxy\<TService\>
-
-Maps service method signatures to async versions. Every method returns `Promise<Awaited<R>>`.
-
-```ts
-type ServiceProxy<TService> = {
-  [K in keyof TService]: TService[K] extends (...args: infer P) => infer R
-    ? (...args: P) => Promise<Awaited<R>>
-    : never;
-};
-```
-
-### createServiceClient
-
-```ts
-function createServiceClient(name: string, options: ServiceConnectionOptions): ServiceClient;
-```
-
-Factory function to create a `ServiceClient` instance.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `name` | `string` | Client identifier name |
-| `options` | `ServiceConnectionOptions` | Connection options |

package/docs/browser-compat-types.md

@@ -0,0 +1,77 @@
+# Browser Compat Types
+
+Cross-environment compatible types that replace DOM-only types (`FileList`, `BlobPart`, `Worker`, `Transferable`) so that typecheck passes in both Node.js and browser environments.
+
+## `BlobInput`
+
+Blob constructor data type replacing DOM `BlobPart`.
+
+```typescript
+export type BlobInput = Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | string;
+```
+
+## `FileCollection`
+
+File collection interface replacing DOM `FileList`. Structurally compatible with browser `FileList`.
+
+```typescript
+export interface FileCollection {
+  readonly length: number;
+  item(index: number): File | null;
+  [index: number]: File;
+  [Symbol.iterator](): IterableIterator<File>;
+}
+```
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `length` | `number` (readonly) | Number of files in the collection |
+| `item(index)` | `(index: number) => File \| null` | Returns the file at the given index |
+| `[index]` | `File` | Index accessor |
+| `[Symbol.iterator]` | `() => IterableIterator<File>` | Iterable protocol support |
+
+## `WorkerLike`
+
+Web Worker interface replacing DOM `Worker`. Structurally compatible with browser `Worker`.
+
+```typescript
+export interface WorkerLike {
+  onmessage: ((ev: MessageEvent) => void) | null;
+  postMessage(message: unknown, transfer?: unknown[]): void;
+  terminate(): void;
+}
+```
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `onmessage` | `((ev: MessageEvent) => void) \| null` | Message event handler |
+| `postMessage` | `(message: unknown, transfer?: unknown[]) => void` | Posts a message to the worker |
+| `terminate` | `() => void` | Terminates the worker |
+
+## `isWorkerSupported`
+
+Checks whether Web Worker API is available in the current environment.
+
+```typescript
+export function isWorkerSupported(): boolean;
+```
+
+**Returns:** `boolean` -- `true` if `Worker` exists in `globalThis`.
+
+## `createBrowserWorker`
+
+Creates a Web Worker instance. Returns `undefined` if the environment does not support workers.
+
+```typescript
+export function createBrowserWorker(
+  url: URL,
+  options: { type: string },
+): WorkerLike | undefined;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `URL` | Worker script URL |
+| `options` | `{ type: string }` | Worker options (e.g., `{ type: "module" }`) |
+
+**Returns:** `WorkerLike | undefined`

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.4",
+  "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.4",
-    "@simplysm/orm-common": "14.0.4",
-    "@simplysm/service-common": "14.0.4"
+    "@simplysm/core-common": "14.0.5",
+    "@simplysm/orm-common": "14.0.5",
+    "@simplysm/service-common": "14.0.5"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1",