@simplysm/service-client 13.0.97 → 13.0.98

package/README.md

@@ -0,0 +1,82 @@
+# @simplysm/service-client
+
+Service module (client) -- WebSocket-based service client for communicating with `@simplysm/service-server`.
+
+## Installation
+
+```bash
+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
+
+```typescript
+import { createServiceClient } from "@simplysm/service-client";
+
+const client = createServiceClient("my-app", {
+  host: "localhost",
+  port: 3000,
+});
+
+await client.connect();
+
+// Authenticate
+await client.auth(token);
+
+// Call a service method
+const service = client.getService<MyServiceType>("MyService");
+const result = await service.someMethod("arg1", "arg2");
+
+// Listen for events
+await client.addListener(SomeEvent, { id: 1 }, async (data) => {
+  // handle event
+});
+
+// Upload files
+const results = await client.uploadFile(fileList);
+
+// Close
+await client.close();
+```
+
+## Documentation
+
+- [Types](docs/types.md)
+- [Transport](docs/transport.md)
+- [Protocol](docs/protocol.md)
+- [Features](docs/features.md)
+- [ServiceClient](docs/service-client.md)

package/docs/features.md

@@ -0,0 +1,142 @@
+# Features
+
+## EventClient
+
+Client-side event subscription manager. Handles adding/removing event listeners and auto-resubscription on reconnect.
+
+### `EventClient`
+
+```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>;
+}
+```
+
+### `createEventClient`
+
+```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
+
+HTTP-based file upload/download client.
+
+### `FileClient`
+
+```typescript
+interface FileClient {
+  download(relPath: string): Promise<Bytes>;
+  upload(
+    files: File[] | FileList | { name: string; data: BlobPart }[],
+    authToken: string,
+  ): Promise<ServiceUploadResult[]>;
+}
+```
+
+### `createFileClient`
+
+```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
+
+### `OrmConnectOptions`
+
+Configuration for ORM database connections via the service client.
+
+```typescript
+interface OrmConnectOptions<TDef extends DbContextDef<any, any, any>> {
+  dbContextDef: TDef;
+  connOpt: DbConnOptions & { configName: string };
+  dbContextOpt?: {
+    database: string;
+    schema: string;
+  };
+}
+```
+
+### `OrmClientConnector`
+
+Manages ORM database connections 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>;
+}
+```
+
+### `createOrmClientConnector`
+
+```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`
+
+Implements `DbContextExecutor` by delegating all database operations to the remote `OrmService` via WebSocket.
+
+```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>;
+}
+```

package/docs/protocol.md

@@ -0,0 +1,39 @@
+# Protocol
+
+Client-side protocol wrapper that handles message encoding/decoding with optional Web Worker offloading for large payloads.
+
+## `ClientProtocolWrapper`
+
+```typescript
+interface ClientProtocolWrapper {
+  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
+  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
+}
+```
+
+## `createClientProtocolWrapper`
+
+Create a client protocol wrapper instance.
+
+```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`)

package/docs/service-client.md

@@ -0,0 +1,210 @@
+# ServiceClient
+
+Main client class that orchestrates all service communication modules.
+
+```typescript
+import { ServiceClient, createServiceClient, type ServiceProxy } from "@simplysm/service-client";
+```
+
+## `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;
+};
+```
+
+## Class: `ServiceClient`
+
+Extends `EventEmitter<ServiceClientEvents>`.
+
+### Events
+
+```typescript
+interface ServiceClientEvents {
+  "request-progress": ServiceProgressState;
+  "response-progress": ServiceProgressState;
+  "state": "connected" | "closed" | "reconnecting";
+  "reload": Set<string>;
+}
+```
+
+### 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`
+
+Create a type-safe proxy for calling remote service methods.
+
+```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>;
+```
+
+## `createServiceClient`
+
+Factory function.
+
+```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();
+```

package/docs/transport.md

@@ -0,0 +1,102 @@
+# Transport
+
+The transport layer handles WebSocket connections and message routing.
+
+## SocketProvider
+
+Low-level WebSocket connection manager with automatic reconnection and heartbeat keep-alive.
+
+### `SocketProviderEvents`
+
+```typescript
+interface SocketProviderEvents {
+  message: Bytes;
+  state: "connected" | "closed" | "reconnecting";
+}
+```
+
+### `SocketProvider`
+
+```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>;
+}
+```
+
+### `createSocketProvider`
+
+Create a SocketProvider instance.
+
+```typescript
+function createSocketProvider(
+  url: string,
+  clientName: string,
+  maxReconnectCount: number,
+): 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
+
+---
+
+## ServiceTransport
+
+Higher-level transport that handles message encoding/decoding, request-response correlation, and event dispatching.
+
+### `ServiceTransportEvents`
+
+```typescript
+interface ServiceTransportEvents {
+  reload: Set<string>;
+  event: { keys: string[]; data: unknown };
+}
+```
+
+### `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>;
+}
+```
+
+### `createServiceTransport`
+
+Create a ServiceTransport instance.
+
+```typescript
+function createServiceTransport(
+  socket: SocketProvider,
+  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

@@ -0,0 +1,38 @@
+# Types
+
+## ServiceConnectionOptions
+
+WebSocket connection configuration.
+
+```typescript
+interface ServiceConnectionOptions {
+  port: number;
+  host: string;
+  ssl?: boolean;
+  /** Set to 0 to disable reconnect; disconnects immediately */
+  maxReconnectCount?: number;
+}
+```
+
+## ServiceProgress
+
+Progress callback interface for tracking request/response transfer progress.
+
+```typescript
+interface ServiceProgress {
+  request?: (s: ServiceProgressState) => void;
+  response?: (s: ServiceProgressState) => void;
+}
+```
+
+## ServiceProgressState
+
+Transfer progress state.
+
+```typescript
+interface ServiceProgressState {
+  uuid: string;
+  totalSize: number;
+  completedSize: number;
+}
+```

package/package.json

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