@simplysm/service-client 13.0.98 → 13.0.99

package/README.md

@@ -1,6 +1,8 @@
 # @simplysm/service-client
 
-Service module (client) -- WebSocket-based service client for communicating with `@simplysm/service-server`.
+Simplysm package - Service module (client)
+
+WebSocket-based service client for communicating with `@simplysm/service-server`. Provides type-safe service method calls, event pub/sub, file upload/download, and client-side ORM connectivity.
 
 ## Installation
 
@@ -8,41 +10,64 @@ Service module (client) -- WebSocket-based service client for communicating with
 npm install @simplysm/service-client
 ```
 
-## Exports
-
-```typescript
-import {
-  // Main
-  ServiceClient,
-  createServiceClient,
-  type ServiceProxy,
-  // Types
-  type ServiceConnectionOptions,
-  type ServiceProgress,
-  type ServiceProgressState,
-  // Transport
-  type SocketProvider,
-  type SocketProviderEvents,
-  createSocketProvider,
-  type ServiceTransport,
-  type ServiceTransportEvents,
-  createServiceTransport,
-  // Protocol
-  type ClientProtocolWrapper,
-  createClientProtocolWrapper,
-  // Features
-  type EventClient,
-  createEventClient,
-  type FileClient,
-  createFileClient,
-  type OrmConnectOptions,
-  type OrmClientConnector,
-  createOrmClientConnector,
-  OrmClientDbContextExecutor,
-} from "@simplysm/service-client";
-```
-
-## Quick Start
+## API Overview
+
+### Types
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceConnectionOptions` | interface | Connection options (host, port, ssl, reconnect) |
+| `ServiceProgress` | interface | Progress callback config for requests |
+| `ServiceProgressState` | interface | Progress state (uuid, totalSize, completedSize) |
+
+-> See [docs/types.md](./docs/types.md) for details.
+
+### Transport
+| API | Type | Description |
+|-----|------|-------------|
+| `SocketProvider` | interface | WebSocket connection provider |
+| `SocketProviderEvents` | interface | Socket events (message, state) |
+| `createSocketProvider` | function | Create socket with heartbeat and auto-reconnect |
+| `ServiceTransport` | interface | Message routing and request/response correlation |
+| `ServiceTransportEvents` | interface | Transport events (reload, event) |
+| `createServiceTransport` | function | Create transport instance |
+
+-> See [docs/transport.md](./docs/transport.md) for details.
+
+### Protocol
+| API | Type | Description |
+|-----|------|-------------|
+| `ClientProtocolWrapper` | interface | Protocol wrapper with Web Worker offloading |
+| `createClientProtocolWrapper` | function | Create protocol wrapper |
+
+-> See [docs/protocol.md](./docs/protocol.md) for details.
+
+### Features (Event, File, ORM)
+| API | Type | Description |
+|-----|------|-------------|
+| `EventClient` | interface | Event listener management |
+| `createEventClient` | function | Create event client |
+| `FileClient` | interface | File upload/download |
+| `createFileClient` | function | Create file client |
+| `OrmConnectOptions` | interface | ORM connection options |
+| `OrmClientConnector` | interface | Client-side ORM connector |
+| `createOrmClientConnector` | function | Create ORM connector |
+| `OrmClientDbContextExecutor` | class | DbContext executor via service protocol |
+
+-> See [docs/features.md](./docs/features.md) for details.
+
+### Main
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceClient` | class | Main client (connect, auth, service calls, events, files) |
+| `ServiceClientEvents` | interface | Client events (progress, state, reload) |
+| `ServiceProxy` | type | Type wrapper for remote service methods |
+| `createServiceClient` | function | Factory to create ServiceClient |
+
+-> See [docs/service-client.md](./docs/service-client.md) for details.
+
+## Usage Examples
+
+### Connect and Call Service Methods
 
 ```typescript
 import { createServiceClient } from "@simplysm/service-client";
@@ -53,30 +78,49 @@ const client = createServiceClient("my-app", {
 });
 
 await client.connect();
+await client.auth(jwtToken);
 
-// Authenticate
-await client.auth(token);
+// Type-safe service proxy
+interface UserService {
+  getProfile(): Promise<{ name: string; email: string }>;
+  updateName(name: string): Promise<void>;
+}
 
-// Call a service method
-const service = client.getService<MyServiceType>("MyService");
-const result = await service.someMethod("arg1", "arg2");
+const userService = client.getService<UserService>("User");
+const profile = await userService.getProfile();
+await userService.updateName("New Name");
+```
 
-// Listen for events
-await client.addListener(SomeEvent, { id: 1 }, async (data) => {
-  // handle event
-});
+### Client-Side ORM
 
-// Upload files
-const results = await client.uploadFile(fileList);
+```typescript
+import { createOrmClientConnector } from "@simplysm/service-client";
+
+const orm = createOrmClientConnector(client);
 
-// Close
-await client.close();
+const users = await orm.connect(
+  { dbContextDef: MyDb, connOpt: { configName: "main" } },
+  async (db) => {
+    return db.user().where((u) => [expr.eq(u.status, "active")]).execute();
+  },
+);
 ```
 
-## Documentation
+### Event Subscription
+
+```typescript
+import { defineEvent } from "@simplysm/service-common";
 
-- [Types](docs/types.md)
-- [Transport](docs/transport.md)
-- [Protocol](docs/protocol.md)
-- [Features](docs/features.md)
-- [ServiceClient](docs/service-client.md)
+const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
+
+const key = await client.addListener(
+  OrderUpdated,
+  { orderId: 123 },
+  async (data) => {
+    console.log("Order status:", data.status);
+  },
+);
+
+// Later: unsubscribe
+await client.removeListener(key);
+```

package/docs/features.md

@@ -1,10 +1,8 @@
 # Features
 
-## EventClient
+## `EventClient`
 
-Client-side event subscription manager. Handles adding/removing event listeners and auto-resubscription on reconnect.
-
-### `EventClient`
+Client-side event management interface. Handles event listener registration, removal, emission, and auto-recovery on reconnect.
 
 ```typescript
 interface EventClient {
@@ -13,38 +11,34 @@ interface EventClient {
     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>;
 }
 ```
 
-### `createEventClient`
+| 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;
 ```
 
-**Behavior:**
-- `addListener` registers on the server and stores locally for reconnect recovery
-- `removeListener` removes from local map and sends removal request to server
-- `emit` queries the server for matching listener infos, then sends event to matching keys
-- `resubscribeAll` re-registers all local listeners on the server (called on reconnect)
-
----
-
-## FileClient
+## `FileClient`
 
-HTTP-based file upload/download client.
-
-### `FileClient`
+File upload/download client interface.
 
 ```typescript
 interface FileClient {
@@ -56,23 +50,27 @@ interface FileClient {
 }
 ```
 
-### `createFileClient`
+| 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;
 ```
 
-**Behavior:**
-- `download` fetches a file via HTTP GET and returns it as `Uint8Array`
-- `upload` sends files via multipart form POST to `/upload` with auth token in headers
-
----
-
-## ORM Features
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `hostUrl` | `string` | Server base URL (http:// or https://) |
+| `clientName` | `string` | Client name for request headers |
 
-### `OrmConnectOptions`
+## `OrmConnectOptions`
 
-Configuration for ORM database connections via the service client.
+ORM connection options for client-side database access.
 
 ```typescript
 interface OrmConnectOptions<TDef extends DbContextDef<any, any, any>> {
@@ -85,9 +83,15 @@ interface OrmConnectOptions<TDef extends DbContextDef<any, any, any>> {
 }
 ```
 
-### `OrmClientConnector`
+| 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 |
 
-Manages ORM database connections through the service client.
+## `OrmClientConnector`
+
+Client-side ORM connector interface. Creates DbContext instances that execute queries via the service protocol.
 
 ```typescript
 interface OrmClientConnector {
@@ -95,7 +99,6 @@ interface OrmClientConnector {
     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,
@@ -103,40 +106,38 @@ interface OrmClientConnector {
 }
 ```
 
-### `createOrmClientConnector`
+| 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;
 ```
 
-**Behavior:**
-- `connect` creates a database context and executes the callback within a transaction
-- `connectWithoutTransaction` creates a database context without transaction wrapping
-- Foreign key constraint violations are caught and re-thrown with a user-friendly message
+## `OrmClientDbContextExecutor`
 
-### `OrmClientDbContextExecutor`
-
-Implements `DbContextExecutor` by delegating all database operations to the remote `OrmService` via WebSocket.
+Client-side DbContext executor. Implements `DbContextExecutor` by delegating to the ORM service over the service protocol.
 
 ```typescript
 class OrmClientDbContextExecutor implements DbContextExecutor {
-  constructor(client: ServiceClient, 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>;
+  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,9 +1,9 @@
 # Protocol
 
-Client-side protocol wrapper that handles message encoding/decoding with optional Web Worker offloading for large payloads.
-
 ## `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 }>;
@@ -11,29 +11,19 @@ interface ClientProtocolWrapper {
 }
 ```
 
+| 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.
+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;
 ```
 
-**Parameters:**
-- `protocol` -- A `ServiceProtocol` instance (from `@simplysm/service-common`)
-
-**Behavior:**
-- Messages smaller than 30KB are processed on the main thread
-- Larger messages are offloaded to a Web Worker for encoding/decoding
-- Worker is automatically initialized as a lazy singleton
-- Worker tasks that do not complete within 60s are rejected (prevents memory leaks)
-- Falls back to main-thread processing when `Worker` is not available (e.g., SSR)
-
-**Worker delegation heuristics for encoding:**
-- `Uint8Array` body: always use worker
-- String body longer than 30KB: use worker
-- Array body with >100 elements or containing `Uint8Array`: use worker
-
-**Worker delegation heuristics for decoding:**
-- Byte size > 30KB: use worker
-- After worker decoding, `transfer.decode()` is applied to restore class instances (e.g., `DateTime`)
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `protocol` | `ServiceProtocol` | Base protocol instance from `createServiceProtocol()` |

package/docs/service-client.md

@@ -1,28 +1,62 @@
 # ServiceClient
 
-Main client class that orchestrates all service communication modules.
-
-```typescript
-import { ServiceClient, createServiceClient, type ServiceProxy } from "@simplysm/service-client";
+## `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>;
+}
 ```
 
-## `ServiceProxy<TService>`
-
-Type transformer that wraps all method return types of `TService` with `Promise`.
-
-```typescript
-type ServiceProxy<TService> = {
-  [K in keyof TService]: TService[K] extends (...args: infer P) => infer R
-    ? (...args: P) => Promise<Awaited<R>>
-    : never;
-};
-```
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | Client name |
+| `options` | `ServiceConnectionOptions` | Connection options |
+| `connected` | `boolean` | Whether connected |
+| `hostUrl` | `string` | HTTP(S) base URL |
 
-## Class: `ServiceClient`
+| 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 |
 
-Extends `EventEmitter<ServiceClientEvents>`.
+## `ServiceClientEvents`
 
-### Events
+Events emitted by `ServiceClient`.
 
 ```typescript
 interface ServiceClientEvents {
@@ -33,178 +67,27 @@ interface ServiceClientEvents {
 }
 ```
 
-### Constructor
-
-```typescript
-constructor(name: string, options: ServiceConnectionOptions)
-```
-
-- `name` -- Client name (used for identification on the server)
-- `options` -- Connection options
-
-### Properties
-
-#### `connected`
-
-```typescript
-get connected(): boolean;
-```
-
-#### `hostUrl`
-
-```typescript
-get hostUrl(): string;
-```
-
-Returns the HTTP(S) URL of the server (e.g., `"https://localhost:3000"`).
-
-### Methods
-
-#### `connect`
-
-Connect to the server via WebSocket.
-
-```typescript
-async connect(): Promise<void>;
-```
-
-#### `close`
-
-Close the WebSocket connection.
-
-```typescript
-async close(): Promise<void>;
-```
-
-#### `auth`
-
-Authenticate with the server using a JWT token.
-
-```typescript
-async auth(token: string): Promise<void>;
-```
-
-#### `getService`
+## `ServiceProxy`
 
-Create a type-safe proxy for calling remote service methods.
+Type transformer that wraps all method return types of a service with `Promise`.
 
 ```typescript
-getService<TService>(serviceName: string): ServiceProxy<TService>;
-```
-
-**Example:**
-```typescript
-const userService = client.getService<UserServiceType>("User");
-const profile = await userService.getProfile();
-```
-
-#### `send`
-
-Send a raw service method call.
-
-```typescript
-async send(
-  serviceName: string,
-  methodName: string,
-  params: unknown[],
-  progress?: ServiceProgress,
-): Promise<unknown>;
-```
-
-#### `addListener`
-
-Add a server-side event listener.
-
-```typescript
-async addListener<TInfo, TData>(
-  eventDef: ServiceEventDef<TInfo, TData>,
-  info: TInfo,
-  cb: (data: TData) => PromiseLike<void>,
-): Promise<string>;
-```
-
-Returns a listener key (UUID) that can be used with `removeListener`.
-
-#### `removeListener`
-
-Remove a server-side event listener.
-
-```typescript
-async removeListener(key: string): Promise<void>;
-```
-
-#### `emitEvent`
-
-Emit an event to matching server-side listeners.
-
-```typescript
-async emitEvent<TInfo, TData>(
-  eventDef: ServiceEventDef<TInfo, TData>,
-  infoSelector: (item: TInfo) => boolean,
-  data: TData,
-): Promise<void>;
-```
-
-#### `uploadFile`
-
-Upload files to the server. Requires prior authentication via `auth()`.
-
-```typescript
-async uploadFile(
-  files: File[] | FileList | { name: string; data: BlobPart }[],
-): Promise<ServiceUploadResult[]>;
-```
-
-#### `downloadFileBuffer`
-
-Download a file from the server as bytes.
-
-```typescript
-async downloadFileBuffer(relPath: string): Promise<Bytes>;
+type ServiceProxy<TService> = {
+  [K in keyof TService]: TService[K] extends (...args: infer P) => infer R
+    ? (...args: P) => Promise<Awaited<R>>
+    : never;
+};
 ```
 
 ## `createServiceClient`
 
-Factory function.
+Factory function to create a `ServiceClient` instance.
 
 ```typescript
 function createServiceClient(name: string, options: ServiceConnectionOptions): ServiceClient;
 ```
 
-## Example
-
-```typescript
-import { createServiceClient, type ServiceProxy } from "@simplysm/service-client";
-import { defineEvent } from "@simplysm/service-common";
-
-// Define event
-const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
-
-// Create client
-const client = createServiceClient("my-app", {
-  host: "localhost",
-  port: 3000,
-});
-
-// Connect and authenticate
-await client.connect();
-await client.auth(jwtToken);
-
-// Call service
-const orderService = client.getService<OrderServiceType>("Order");
-const orders = await orderService.getAll();
-
-// Listen for events
-const key = await client.addListener(OrderUpdated, { orderId: 123 }, async (data) => {
-  console.log(data.status);
-});
-
-// Track progress
-client.on("request-progress", (state) => {
-  console.log(`Upload: ${state.completedSize}/${state.totalSize}`);
-});
-
-// Cleanup
-await client.removeListener(key);
-await client.close();
-```
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Client name identifier |
+| `options` | `ServiceConnectionOptions` | Connection options |

package/docs/transport.md

@@ -1,43 +1,45 @@
 # Transport
 
-The transport layer handles WebSocket connections and message routing.
+## `SocketProvider`
 
-## SocketProvider
-
-Low-level WebSocket connection manager with automatic reconnection and heartbeat keep-alive.
-
-### `SocketProviderEvents`
-
-```typescript
-interface SocketProviderEvents {
-  message: Bytes;
-  state: "connected" | "closed" | "reconnecting";
-}
-```
-
-### `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;
+  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>;
 }
 ```
 
-### `createSocketProvider`
+| 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`
 
-Create a SocketProvider instance.
+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(
@@ -47,46 +49,44 @@ function createSocketProvider(
 ): SocketProvider;
 ```
 
-**Behavior:**
-- Heartbeat: sends ping every 5s, considers disconnected if no message for 30s
-- Reconnect: retries every 3s up to `maxReconnectCount` times
-- Binary protocol: uses `ArrayBuffer` for data transfer
-- Ping/Pong: `0x01` = ping, `0x02` = pong
-
----
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | WebSocket URL (ws:// or wss://) |
+| `clientName` | `string` | Client name identifier |
+| `maxReconnectCount` | `number` | Max reconnect attempts |
 
-## ServiceTransport
+## `ServiceTransport`
 
-Higher-level transport that handles message encoding/decoding, request-response correlation, and event dispatching.
-
-### `ServiceTransportEvents`
+Service transport interface. Handles message routing and request/response correlation.
 
 ```typescript
-interface ServiceTransportEvents {
-  reload: Set<string>;
-  event: { keys: string[]; data: unknown };
+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>;
 }
 ```
 
-### `ServiceTransport`
+| 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 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>;
+interface ServiceTransportEvents {
+  reload: Set<string>;
+  event: { keys: string[]; data: unknown };
 }
 ```
 
-### `createServiceTransport`
+## `createServiceTransport`
 
-Create a ServiceTransport instance.
+Create a service transport instance.
 
 ```typescript
 function createServiceTransport(
@@ -94,9 +94,3 @@ function createServiceTransport(
   protocol: ClientProtocolWrapper,
 ): ServiceTransport;
 ```
-
-**Behavior:**
-- Each `send()` call generates a unique UUID and registers a pending request
-- Incoming messages are correlated by UUID and resolved/rejected accordingly
-- Progress callbacks are invoked for chunked message transfers
-- All pending requests are rejected when the socket disconnects

package/docs/types.md

@@ -1,22 +1,28 @@
 # Types
 
-## ServiceConnectionOptions
+## `ServiceConnectionOptions`
 
-WebSocket connection configuration.
+Connection options for `ServiceClient`.
 
 ```typescript
 interface ServiceConnectionOptions {
   port: number;
   host: string;
   ssl?: boolean;
-  /** Set to 0 to disable reconnect; disconnects immediately */
   maxReconnectCount?: number;
 }
 ```
 
-## ServiceProgress
+| 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) |
 
-Progress callback interface for tracking request/response transfer progress.
+## `ServiceProgress`
+
+Progress callback configuration for service requests.
 
 ```typescript
 interface ServiceProgress {
@@ -25,9 +31,14 @@ interface ServiceProgress {
 }
 ```
 
-## ServiceProgressState
+| Field | Type | Description |
+|-------|------|-------------|
+| `request` | `(s: ServiceProgressState) => void` | Request upload progress callback |
+| `response` | `(s: ServiceProgressState) => void` | Response download progress callback |
+
+## `ServiceProgressState`
 
-Transfer progress state.
+Progress state for chunked message transfers.
 
 ```typescript
 interface ServiceProgressState {
@@ -36,3 +47,9 @@ interface ServiceProgressState {
   completedSize: number;
 }
 ```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `uuid` | `string` | Request UUID |
+| `totalSize` | `number` | Total message size in bytes |
+| `completedSize` | `number` | Completed size in bytes |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-client",
-  "version": "13.0.98",
+  "version": "13.0.99",
   "description": "Simplysm package - Service module (client)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -20,9 +20,9 @@
   "sideEffects": false,
   "dependencies": {
     "consola": "^3.4.2",
-    "@simplysm/core-common": "13.0.98",
-    "@simplysm/orm-common": "13.0.98",
-    "@simplysm/service-common": "13.0.98"
+    "@simplysm/core-common": "13.0.99",
+    "@simplysm/service-common": "13.0.99",
+    "@simplysm/orm-common": "13.0.99"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1",