@simplysm/service-client 13.0.82 → 13.0.84

package/README.md

@@ -0,0 +1,68 @@
+# @simplysm/service-client
+
+WebSocket-based service client for communicating with `@simplysm/service-server`. Provides RPC-style service calls, real-time event subscriptions, file upload/download, and ORM database access -- all over a single persistent connection with automatic reconnection and heartbeat monitoring.
+
+## Installation
+
+```bash
+npm install @simplysm/service-client
+```
+
+## Quick Start
+
+```typescript
+import { createServiceClient } from "@simplysm/service-client";
+
+// Create and connect
+const client = createServiceClient("my-app", {
+  host: "localhost",
+  port: 3000,
+});
+await client.connect();
+
+// Authenticate
+await client.auth(token);
+
+// Call a remote service method
+const userService = client.getService<UserService>("User");
+const users = await userService.getList();
+
+// Upload files
+const results = await client.uploadFile(fileList);
+
+// Listen to real-time events
+const key = await client.addListener(myEventDef, { roomId: 1 }, async (data) => {
+  console.log("Event received:", data);
+});
+
+// Clean up
+await client.removeListener(key);
+await client.close();
+```
+
+## Documentation
+
+| Category | File | Description |
+|----------|------|-------------|
+| Service Client | [docs/service-client.md](docs/service-client.md) | Main `ServiceClient` class and factory function |
+| Types | [docs/types.md](docs/types.md) | Connection options, progress types |
+| Transport | [docs/transport.md](docs/transport.md) | Socket provider and service transport layer |
+| Protocol | [docs/protocol.md](docs/protocol.md) | Client protocol wrapper with Web Worker offloading |
+| Features | [docs/features.md](docs/features.md) | Event client, file client, ORM connector |
+
+## Architecture
+
+```
+ServiceClient (main facade)
+  |-- SocketProvider          WebSocket connection + heartbeat + reconnection
+  |-- ServiceTransport        Request/response multiplexing over socket
+  |     \-- ClientProtocolWrapper   Encode/decode with optional Web Worker
+  |-- EventClient             Server-sent event subscriptions
+  \-- FileClient              HTTP file upload/download
+```
+
+## Dependencies
+
+- `@simplysm/core-common` -- EventEmitter, Uuid, transfer utilities
+- `@simplysm/service-common` -- Protocol definitions, message types
+- `@simplysm/orm-common` -- ORM types (for ORM connector feature)

package/docs/features.md

@@ -0,0 +1,190 @@
+# Features
+
+Higher-level feature modules for events, file operations, and ORM database access.
+
+## Event Client
+
+### `EventClient`
+
+**Interface** -- manages server-sent event subscriptions with automatic 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>;
+}
+```
+
+### Methods
+
+#### `addListener(eventDef, info, cb)`
+
+Registers an event listener on the server and stores it locally for reconnect recovery.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `eventDef` | `ServiceEventDef<TInfo, TData>` | Event definition (from `@simplysm/service-common`) |
+| `info` | `TInfo` | Metadata attached to this listener (used for filtering) |
+| `cb` | `(data: TData) => PromiseLike<void>` | Callback invoked when the event fires |
+
+**Returns:** A unique key string for removing this listener later.
+
+#### `removeListener(key)`
+
+Removes a listener locally and notifies the server. Safe to call even when disconnected (the server auto-cleans on disconnect).
+
+#### `emit(eventDef, infoSelector, data)`
+
+Emits an event to other connected clients. Queries the server for registered listeners matching `eventDef`, filters them with `infoSelector`, and sends data to the matching subset.
+
+#### `resubscribeAll()`
+
+Re-registers all locally stored listeners with the server. Called automatically by `ServiceClient` on reconnection.
+
+### `createEventClient()`
+
+```typescript
+function createEventClient(transport: ServiceTransport): EventClient
+```
+
+---
+
+## File Client
+
+### `FileClient`
+
+**Interface** -- HTTP-based file upload and download.
+
+```typescript
+interface FileClient {
+  download(relPath: string): Promise<Bytes>;
+  upload(
+    files: File[] | FileList | { name: string; data: BlobPart }[],
+    authToken: string,
+  ): Promise<ServiceUploadResult[]>;
+}
+```
+
+### Methods
+
+#### `download(relPath)`
+
+Downloads a file from the server via HTTP GET.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `relPath` | `string` | Relative file path on the server |
+
+**Returns:** `Uint8Array` containing the file contents.
+
+#### `upload(files, authToken)`
+
+Uploads one or more files via HTTP POST (`multipart/form-data`). Accepts browser `File` objects, a `FileList`, or plain objects with `name` and `data` properties.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `files` | `File[] \| FileList \| { name: string; data: BlobPart }[]` | Files to upload |
+| `authToken` | `string` | Bearer token sent in the `Authorization` header |
+
+**Returns:** `ServiceUploadResult[]` -- array of `{ path, filename, size }` for each uploaded file.
+
+### `createFileClient()`
+
+```typescript
+function createFileClient(hostUrl: string, clientName: string): FileClient
+```
+
+---
+
+## ORM Client
+
+Utilities for accessing databases through the service server's ORM service.
+
+### `OrmConnectOptions<TDef>`
+
+**Interface** -- configuration for an ORM connection via the service client.
+
+```typescript
+interface OrmConnectOptions<TDef extends DbContextDef<any, any, any>> {
+  dbContextDef: TDef;
+  connOpt: DbConnOptions & { configName: string };
+  dbContextOpt?: {
+    database: string;
+    schema: string;
+  };
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `dbContextDef` | `TDef` | Database context definition (from `@simplysm/orm-common`) |
+| `connOpt` | `DbConnOptions & { configName: string }` | Connection options including the named config |
+| `dbContextOpt` | `{ database: string; schema: string }` | Optional database/schema overrides |
+
+---
+
+### `OrmClientConnector`
+
+**Interface** -- high-level API for executing ORM operations through the service client.
+
+```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>;
+}
+```
+
+#### `connect(config, callback)`
+
+Opens a transactional database connection, executes the callback, and automatically commits or rolls back.
+
+Foreign key constraint violations are caught and re-thrown with a user-friendly message.
+
+#### `connectWithoutTransaction(config, callback)`
+
+Same as `connect()` but without transaction wrapping. Useful for read-only operations or when manual transaction control is needed.
+
+### `createOrmClientConnector()`
+
+```typescript
+function createOrmClientConnector(serviceClient: ServiceClient): OrmClientConnector
+```
+
+---
+
+### `OrmClientDbContextExecutor`
+
+**Class** -- implements `DbContextExecutor` from `@simplysm/orm-common` by delegating all database operations to the server's `OrmService` via RPC.
+
+```typescript
+class OrmClientDbContextExecutor implements DbContextExecutor {
+  constructor(client: ServiceClient, 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>;
+}
+```
+
+All methods require an active connection (obtained via `connect()`). Calling any method before connecting throws an error.

package/docs/protocol.md

@@ -0,0 +1,69 @@
+# Protocol
+
+Client-side protocol wrapper that optionally offloads encoding/decoding to a Web Worker for large payloads.
+
+## `ClientProtocolWrapper`
+
+**Interface** -- encodes outgoing messages into binary chunks and decodes incoming binary data.
+
+```typescript
+interface ClientProtocolWrapper {
+  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
+  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
+}
+```
+
+### Methods
+
+#### `encode(uuid, message)`
+
+Encodes a service message into one or more binary chunks for transmission.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `uuid` | `string` | Request identifier |
+| `message` | `ServiceMessage` | The message to encode |
+
+**Returns:** `{ chunks: Bytes[]; totalSize: number }`
+
+#### `decode(bytes)`
+
+Decodes a binary chunk received from the server.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `bytes` | `Bytes` | Raw binary data |
+
+**Returns:** `ServiceMessageDecodeResult<ServiceMessage>`
+
+---
+
+## `createClientProtocolWrapper()`
+
+**Factory function** -- creates a `ClientProtocolWrapper` that delegates to a Web Worker for large payloads.
+
+```typescript
+function createClientProtocolWrapper(
+  protocol: ServiceProtocol,
+): ClientProtocolWrapper
+```
+
+### Worker Offloading Strategy
+
+The wrapper applies a **30 KB threshold** to decide whether to process on the main thread or offload to a dedicated Web Worker:
+
+**Encode** (main thread when any of these are false):
+- Message body is a `Uint8Array`
+- Message body is a string longer than 30 KB
+- Message body is an array with more than 100 elements, or contains `Uint8Array` items
+
+**Decode** (main thread when):
+- Payload size is 30 KB or less
+
+When a Web Worker is unavailable (e.g., in environments without `Worker` support), all processing falls back to the main thread.
+
+### Worker Lifecycle
+
+- A single shared `Worker` instance is created lazily on first use (singleton pattern).
+- Worker tasks are tracked with a `LazyGcMap` that auto-expires entries after 60 seconds, preventing memory leaks from orphaned requests.
+- For decode operations, binary data is transferred via zero-copy (`Transferable`) to avoid cloning overhead.

package/docs/service-client.md

@@ -0,0 +1,176 @@
+# Service Client
+
+The main entry point for connecting to and communicating with a `@simplysm/service-server` instance.
+
+## `ServiceClient`
+
+**Class** -- extends `EventEmitter<ServiceClientEvents>`
+
+The primary facade that orchestrates WebSocket connectivity, RPC calls, authentication, event subscriptions, and file operations.
+
+### Constructor
+
+```typescript
+new ServiceClient(name: string, options: ServiceConnectionOptions)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Client identifier (sent to server on connection) |
+| `options` | `ServiceConnectionOptions` | Connection configuration (see [Types](types.md)) |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | Client name (readonly) |
+| `options` | `ServiceConnectionOptions` | Connection options (readonly) |
+| `connected` | `boolean` | Whether the WebSocket is currently open |
+| `hostUrl` | `string` | Computed HTTP(S) base URL (e.g. `https://localhost:3000`) |
+
+### Methods
+
+#### `connect()`
+
+Opens the WebSocket connection to the server.
+
+```typescript
+await client.connect();
+```
+
+#### `close()`
+
+Gracefully closes the WebSocket connection.
+
+```typescript
+await client.close();
+```
+
+#### `auth(token)`
+
+Authenticates the connection with the server. The token is stored internally and automatically re-sent on reconnection.
+
+```typescript
+await client.auth(token: string): Promise<void>
+```
+
+#### `getService<TService>(serviceName)`
+
+Creates a type-safe proxy for calling remote service methods. Every property access on the returned proxy returns an async function that sends an RPC request to the server.
+
+```typescript
+const proxy = client.getService<MyService>("MyService");
+const result = await proxy.someMethod(arg1, arg2);
+```
+
+**Returns:** `ServiceProxy<TService>` -- all methods wrapped to return `Promise<Awaited<R>>`
+
+#### `send(serviceName, methodName, params, progress?)`
+
+Low-level method to send an RPC request. Prefer `getService()` for type safety.
+
+```typescript
+await client.send(
+  serviceName: string,
+  methodName: string,
+  params: unknown[],
+  progress?: ServiceProgress,
+): Promise<unknown>
+```
+
+#### `addListener(eventDef, info, cb)`
+
+Subscribes to a server-sent event. Automatically re-subscribes on reconnection.
+
+```typescript
+const key = await client.addListener<TInfo, TData>(
+  eventDef: ServiceEventDef<TInfo, TData>,
+  info: TInfo,
+  cb: (data: TData) => PromiseLike<void>,
+): Promise<string>
+```
+
+**Returns:** A unique listener key for later removal.
+
+**Throws:** `Error` if not connected.
+
+#### `removeListener(key)`
+
+Unsubscribes from a previously registered event listener.
+
+```typescript
+await client.removeListener(key: string): Promise<void>
+```
+
+#### `emitEvent(eventDef, infoSelector, data)`
+
+Emits an event to other connected clients that match the selector.
+
+```typescript
+await client.emitEvent<TInfo, TData>(
+  eventDef: ServiceEventDef<TInfo, TData>,
+  infoSelector: (item: TInfo) => boolean,
+  data: TData,
+): Promise<void>
+```
+
+#### `uploadFile(files)`
+
+Uploads files to the server via HTTP POST. Requires prior authentication via `auth()`.
+
+```typescript
+const results = await client.uploadFile(
+  files: File[] | FileList | { name: string; data: BlobPart }[],
+): Promise<ServiceUploadResult[]>
+```
+
+**Throws:** `Error` if no auth token is set.
+
+#### `downloadFileBuffer(relPath)`
+
+Downloads a file from the server as a `Uint8Array`.
+
+```typescript
+const bytes = await client.downloadFileBuffer(relPath: string): Promise<Bytes>
+```
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `state` | `"connected" \| "closed" \| "reconnecting"` | Connection state changes |
+| `reload` | `Set<string>` | Server-triggered reload with changed file paths |
+| `request-progress` | `ServiceProgressState` | Upload/request progress updates |
+| `response-progress` | `ServiceProgressState` | Download/response progress updates |
+
+### Reconnection Behavior
+
+- On reconnect, `auth()` is automatically re-called if a token was previously set.
+- All event listeners registered via `addListener()` are automatically re-subscribed.
+
+---
+
+## `createServiceClient()`
+
+**Factory function** -- convenience wrapper for the constructor.
+
+```typescript
+function createServiceClient(
+  name: string,
+  options: ServiceConnectionOptions,
+): ServiceClient
+```
+
+---
+
+## `ServiceProxy<TService>`
+
+**Type** -- transforms a service interface so that all methods return `Promise<Awaited<R>>`. Non-function properties are excluded.
+
+```typescript
+type ServiceProxy<TService> = {
+  [K in keyof TService]: TService[K] extends (...args: infer P) => infer R
+    ? (...args: P) => Promise<Awaited<R>>
+    : never;
+};
+```

package/docs/transport.md

@@ -0,0 +1,88 @@
+# Transport
+
+Low-level transport layer that manages the WebSocket connection and request/response multiplexing. These are internal building blocks used by `ServiceClient`; most consumers will not interact with them directly.
+
+## `SocketProvider`
+
+**Interface** -- abstraction over a reconnecting WebSocket connection with heartbeat monitoring.
+
+```typescript
+interface SocketProvider {
+  readonly clientName: string;
+  readonly connected: boolean;
+  on<K extends keyof SocketProviderEvents>(type: K, listener: (data: SocketProviderEvents[K]) => void): void;
+  off<K extends keyof SocketProviderEvents>(type: K, listener: (data: SocketProviderEvents[K]) => void): void;
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  send(data: Bytes): Promise<void>;
+}
+```
+
+### Events (`SocketProviderEvents`)
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `message` | `Bytes` | Raw binary message received from server |
+| `state` | `"connected" \| "closed" \| "reconnecting"` | Connection state change |
+
+---
+
+## `createSocketProvider()`
+
+**Factory function** -- creates a `SocketProvider` implementation backed by the browser `WebSocket` API.
+
+```typescript
+function createSocketProvider(
+  url: string,
+  clientName: string,
+  maxReconnectCount: number,
+): SocketProvider
+```
+
+### Behavior
+
+- **Heartbeat**: Sends a ping (`0x01`) every 5 seconds. If no message is received for 30 seconds, the connection is considered lost and reconnection begins.
+- **Reconnection**: On unexpected disconnect, retries up to `maxReconnectCount` times with a 3-second delay between attempts. Emits `"reconnecting"` state on each attempt and `"connected"` on success.
+- **Graceful close**: `close()` sets a manual-close flag to suppress reconnection and waits up to 30 seconds for the socket to fully close.
+- **Binary mode**: WebSocket is configured with `binaryType: "arraybuffer"`.
+
+---
+
+## `ServiceTransport`
+
+**Interface** -- multiplexes named request/response pairs over a single `SocketProvider`.
+
+```typescript
+interface ServiceTransport {
+  on<K extends keyof ServiceTransportEvents>(type: K, listener: (data: ServiceTransportEvents[K]) => void): void;
+  off<K extends keyof ServiceTransportEvents>(type: K, listener: (data: ServiceTransportEvents[K]) => void): void;
+  send(message: ServiceClientMessage, progress?: ServiceProgress): Promise<unknown>;
+}
+```
+
+### Events (`ServiceTransportEvents`)
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `reload` | `Set<string>` | Server-initiated reload notification with changed file paths |
+| `event` | `{ keys: string[]; data: unknown }` | Server-pushed event data |
+
+---
+
+## `createServiceTransport()`
+
+**Factory function** -- creates a `ServiceTransport` that encodes/decodes messages through a protocol wrapper.
+
+```typescript
+function createServiceTransport(
+  socket: SocketProvider,
+  protocol: ClientProtocolWrapper,
+): ServiceTransport
+```
+
+### Behavior
+
+- Each `send()` call assigns a unique UUID, registers a pending-response listener, and encodes the message into one or more binary chunks.
+- Progress callbacks are invoked for multi-chunk transfers.
+- When the socket disconnects, all pending requests are rejected with `"Request canceled: Socket connection lost"`.
+- Incoming messages are decoded and dispatched based on their name: `response`, `error`, `progress`, `reload`, or `evt:on`.

package/docs/types.md

@@ -0,0 +1,61 @@
+# Types
+
+Shared type definitions used across the service-client package.
+
+## `ServiceConnectionOptions`
+
+**Interface** -- configuration for connecting to a service server.
+
+```typescript
+interface ServiceConnectionOptions {
+  port: number;
+  host: string;
+  ssl?: boolean;
+  maxReconnectCount?: number;
+}
+```
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `port` | `number` | -- | Server port number |
+| `host` | `string` | -- | Server hostname or IP |
+| `ssl` | `boolean` | `undefined` | Use `wss://` and `https://` when `true` |
+| `maxReconnectCount` | `number` | `10` | Maximum reconnection attempts. Set to `0` to disable reconnection (disconnects immediately). |
+
+---
+
+## `ServiceProgress`
+
+**Interface** -- callbacks for monitoring request/response transfer progress.
+
+```typescript
+interface ServiceProgress {
+  request?: (s: ServiceProgressState) => void;
+  response?: (s: ServiceProgressState) => void;
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `request` | `(s: ServiceProgressState) => void` | Called as request chunks are sent |
+| `response` | `(s: ServiceProgressState) => void` | Called as response chunks are received |
+
+---
+
+## `ServiceProgressState`
+
+**Interface** -- progress snapshot for a single transfer operation.
+
+```typescript
+interface ServiceProgressState {
+  uuid: string;
+  totalSize: number;
+  completedSize: number;
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `uuid` | `string` | Unique identifier for the request |
+| `totalSize` | `number` | Total payload size in bytes |
+| `completedSize` | `number` | Bytes transferred so far |

package/package.json

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