@simplysm/service-client 13.0.100 → 14.0.4

package/README.md

@@ -1,126 +1,440 @@
 # @simplysm/service-client
 
-Simplysm package - Service module (client)
+Service client SDK -- WebSocket-based RPC client with type-safe service proxy, event subscription, file upload/download, and ORM connector.
 
-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.
+Depends on `@simplysm/service-common` for protocol and shared types.
 
-## Installation
+## API
 
-```bash
-npm install @simplysm/service-client
+| 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 |
+
+## Usage
+
+```ts
+import { createServiceClient } from "@simplysm/service-client";
+
+// Create and connect
+const client = createServiceClient("my-app", {
+  host: "localhost",
+  port: 3000,
+  ssl: false,
+});
+await client.connect();
+
+// Type-safe RPC calls via proxy
+interface MyService {
+  greet(name: string): Promise<string>;
+}
+const myService = client.getService<MyService>("MyService");
+const result = await myService.greet("world");
+
+// Authenticate
+await client.auth(token);
+
+// File upload
+const uploadResults = await client.uploadFile(fileList);
+
+// File download
+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
+});
+await client.removeListener(listenerKey);
+
+// Clean up
+await client.close();
 ```
 
-## API Overview
+## Types
 
-### 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) |
+### ServiceConnectionOptions
 
--> See [docs/types.md](./docs/types.md) for details.
+```ts
+interface ServiceConnectionOptions {
+  port: number;
+  host: string;
+  ssl?: boolean;
+  maxReconnectCount?: number;
+}
+```
 
-### 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 |
+| 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. |
 
--> See [docs/transport.md](./docs/transport.md) for details.
+### ServiceProgress
 
-### Protocol
-| API | Type | Description |
-|-----|------|-------------|
-| `ClientProtocolWrapper` | interface | Protocol wrapper with Web Worker offloading |
-| `createClientProtocolWrapper` | function | Create protocol wrapper |
+Callback hooks for monitoring message progress.
 
--> See [docs/protocol.md](./docs/protocol.md) for details.
+```ts
+interface ServiceProgress {
+  request?: (s: ServiceProgressState) => void;
+  response?: (s: ServiceProgressState) => void;
+  server?: (s: ServiceProgressState) => void;
+}
+```
 
-### 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 |
+| 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 |
 
--> See [docs/features.md](./docs/features.md) for details.
+### ServiceProgressState
 
-### 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 |
+```ts
+interface ServiceProgressState {
+  uuid: string;
+  totalSize: number;
+  completedSize: number;
+}
+```
 
--> See [docs/service-client.md](./docs/service-client.md) for details.
+| Field | Type | Description |
+|-------|------|-------------|
+| `uuid` | `string` | Message UUID |
+| `totalSize` | `number` | Total message size in bytes |
+| `completedSize` | `number` | Bytes transferred so far |
 
-## Usage Examples
+## Transport
 
-### Connect and Call Service Methods
+### SocketProviderEvents
 
-```typescript
-import { createServiceClient } from "@simplysm/service-client";
+```ts
+interface SocketProviderEvents {
+  message: Bytes;
+  state: "connected" | "closed" | "reconnecting";
+}
+```
 
-const client = createServiceClient("my-app", {
-  host: "localhost",
-  port: 3000,
-});
+| Event | Data Type | Description |
+|-------|-----------|-------------|
+| `message` | `Bytes` | Raw binary message received |
+| `state` | `"connected" \| "closed" \| "reconnecting"` | Connection state change |
 
-await client.connect();
-await client.auth(jwtToken);
+### SocketProvider
 
-// Type-safe service proxy
-interface UserService {
-  getProfile(): Promise<{ name: string; email: string }>;
-  updateName(name: string): Promise<void>;
+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 |
 
-const userService = client.getService<UserService>("User");
-const profile = await userService.getProfile();
-await userService.updateName("New Name");
+### createSocketProvider
+
+```ts
+function createSocketProvider(url: string, clientName: string, maxReconnectCount: number): SocketProvider;
 ```
 
-### Client-Side ORM
+| 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
 
-```typescript
-import { createOrmClientConnector } from "@simplysm/service-client";
+Service-level message transport built on top of `SocketProvider`.
 
-const orm = createOrmClientConnector(client);
+```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
 
-const users = await orm.connect(
-  { dbContextDef: MyDb, connOpt: { configName: "main" } },
-  async (db) => {
-    return db.user().where((u) => [expr.eq(u.status, "active")]).execute();
-  },
-);
+```ts
+function createServiceTransport(socket: SocketProvider, protocol: ClientProtocolWrapper): ServiceTransport;
 ```
 
-### Event Subscription
+## Protocol
 
-```typescript
-import { defineEvent } from "@simplysm/service-common";
+### 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;
+}
+```
 
-const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
+| 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 |
 
-const key = await client.addListener(
-  OrderUpdated,
-  { orderId: 123 },
-  async (data) => {
-    console.log("Order status:", data.status);
-  },
-);
+### createClientProtocolWrapper
 
-// Later: unsubscribe
-await client.removeListener(key);
+```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/dist/features/event-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-client.d.ts","sourceRoot":"","sources":["..\\..\\src\\features\\event-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAKvE,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,KAAK,EAAE,KAAK,EACtB,QAAQ,EAAE,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,EACvC,IAAI,EAAE,KAAK,EACX,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,WAAW,CAAC,IAAI,CAAC,GACrC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,KAAK,EAAE,KAAK,EACf,QAAQ,EAAE,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,EACvC,YAAY,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,EACtC,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,gBAAgB,GAAG,WAAW,CAsG1E"}
+{"version":3,"file":"event-client.d.ts","sourceRoot":"","sources":["..\\..\\src\\features\\event-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAKvE,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,KAAK,EAAE,KAAK,EACtB,QAAQ,EAAE,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,EACvC,IAAI,EAAE,KAAK,EACX,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,WAAW,CAAC,IAAI,CAAC,GACrC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,KAAK,EAAE,KAAK,EACf,QAAQ,EAAE,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,EACvC,YAAY,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,EACtC,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,gBAAgB,GAAG,WAAW,CAwG1E"}