@simplysm/service-client 13.0.99 → 14.0.1

package/docs/features.md

@@ -1,143 +0,0 @@
-# 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

@@ -1,29 +0,0 @@
-# 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

@@ -1,93 +0,0 @@
-# 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

@@ -1,96 +0,0 @@
-# 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

@@ -1,55 +0,0 @@
-# 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 |