@simplysm/service-client 13.0.97 → 13.0.99

package/README.md

@@ -0,0 +1,126 @@
+# @simplysm/service-client
+
+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
+
+```bash
+npm install @simplysm/service-client
+```
+
+## 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";
+
+const client = createServiceClient("my-app", {
+  host: "localhost",
+  port: 3000,
+});
+
+await client.connect();
+await client.auth(jwtToken);
+
+// Type-safe service proxy
+interface UserService {
+  getProfile(): Promise<{ name: string; email: string }>;
+  updateName(name: string): Promise<void>;
+}
+
+const userService = client.getService<UserService>("User");
+const profile = await userService.getProfile();
+await userService.updateName("New Name");
+```
+
+### Client-Side ORM
+
+```typescript
+import { createOrmClientConnector } from "@simplysm/service-client";
+
+const orm = createOrmClientConnector(client);
+
+const users = await orm.connect(
+  { dbContextDef: MyDb, connOpt: { configName: "main" } },
+  async (db) => {
+    return db.user().where((u) => [expr.eq(u.status, "active")]).execute();
+  },
+);
+```
+
+### Event Subscription
+
+```typescript
+import { defineEvent } from "@simplysm/service-common";
+
+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

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

package/docs/protocol.md

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

package/docs/service-client.md

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

package/docs/transport.md

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

package/docs/types.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-client",
-  "version": "13.0.97",
+  "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.97",
-    "@simplysm/orm-common": "13.0.97",
-    "@simplysm/service-common": "13.0.97"
+    "@simplysm/core-common": "13.0.99",
+    "@simplysm/service-common": "13.0.99",
+    "@simplysm/orm-common": "13.0.99"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1",