@simplysm/service-client 14.0.23 → 14.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-client",
-  "version": "14.0.23",
+  "version": "14.0.25",
   "description": "심플리즘 패키지 - 서비스 (client)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -14,15 +14,14 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src",
-    "docs"
+    "src"
   ],
   "sideEffects": false,
   "dependencies": {
     "consola": "^3.4.2",
-    "@simplysm/core-common": "14.0.23",
-    "@simplysm/orm-common": "14.0.23",
-    "@simplysm/service-common": "14.0.23"
+    "@simplysm/orm-common": "14.0.25",
+    "@simplysm/core-common": "14.0.25",
+    "@simplysm/service-common": "14.0.25"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1",

package/README.md

@@ -1,127 +0,0 @@
-# @simplysm/service-client
-
-WebSocket-based RPC client SDK with type-safe service proxy, event subscription, file upload/download, and ORM connector. Depends on `@simplysm/service-common` for protocol and shared types.
-
-## Installation
-
-```bash
-npm install @simplysm/service-client
-```
-
-## API Overview
-
-### Browser Compat Types
-| API | Type | Description |
-|-----|------|-------------|
-| `BlobInput` | `type` | Blob constructor data type (DOM BlobPart replacement) |
-| `FileCollection` | `interface` | File collection interface (DOM FileList replacement) |
-| `WorkerLike` | `interface` | Web Worker interface (DOM Worker replacement) |
-| `isWorkerSupported` | `function` | Checks Web Worker API availability |
-| `createBrowserWorker` | `function` | Creates a Web Worker (returns undefined if unsupported) |
-
--> See [docs/browser-compat-types.md](./docs/browser-compat-types.md) for details.
-
-### Connection Options
-| API | Type | Description |
-|-----|------|-------------|
-| `ServiceConnectionOptions` | `interface` | Connection options (host, port, SSL, reconnect) |
-
--> See [docs/connection-options.md](./docs/connection-options.md) for details.
-
-### Progress Types
-| API | Type | Description |
-|-----|------|-------------|
-| `ServiceProgress` | `interface` | Progress callback hooks for request/response/server |
-| `ServiceProgressState` | `interface` | Progress state (uuid, totalSize, completedSize) |
-
--> See [docs/progress-types.md](./docs/progress-types.md) for details.
-
-### Socket Provider
-| API | Type | Description |
-|-----|------|-------------|
-| `SocketProviderEvents` | `interface` | Socket provider event map |
-| `SocketProvider` | `interface` | Low-level WebSocket abstraction with auto-reconnect |
-| `createSocketProvider` | `function` | Creates a socket provider instance |
-
--> See [docs/socket-provider.md](./docs/socket-provider.md) for details.
-
-### Service Transport
-| API | Type | Description |
-|-----|------|-------------|
-| `ServiceTransportEvents` | `interface` | Transport event map |
-| `ServiceTransport` | `interface` | Service-level message transport |
-| `createServiceTransport` | `function` | Creates a service transport instance |
-
--> See [docs/service-transport.md](./docs/service-transport.md) for details.
-
-### Client Protocol Wrapper
-| API | Type | Description |
-|-----|------|-------------|
-| `ClientProtocolWrapper` | `interface` | Client-side protocol encoder/decoder with Web Worker offloading |
-| `createClientProtocolWrapper` | `function` | Creates a client protocol wrapper |
-
--> See [docs/client-protocol-wrapper.md](./docs/client-protocol-wrapper.md) for details.
-
-### Event/File/ORM Client
-| API | Type | Description |
-|-----|------|-------------|
-| `EventClient` | `interface` | Event subscription client |
-| `createEventClient` | `function` | Creates an event client |
-| `FileClient` | `interface` | File upload/download client |
-| `createFileClient` | `function` | Creates a file client |
-| `OrmConnectOptions` | `interface` | ORM connection options |
-| `OrmClientConnector` | `interface` | ORM client connector (with/without transaction) |
-| `createOrmClientConnector` | `function` | Creates an ORM client connector |
-| `OrmClientDbContextExecutor` | `class` | ORM DbContext executor for client-side use |
-
--> See [docs/features.md](./docs/features.md) for details.
-
-### Main ServiceClient
-| API | Type | Description |
-|-----|------|-------------|
-| `ServiceClient` | `class` | Main service client class with events, RPC, auth, file ops |
-| `ServiceProxy` | `type` | Type-safe service proxy mapping |
-| `createServiceClient` | `function` | Factory function to create a ServiceClient |
-
--> See [docs/service-client.md](./docs/service-client.md) for details.
-
-## Usage Examples
-
-```typescript
-import { createServiceClient } from "@simplysm/service-client";
-import { defineEvent } from "@simplysm/service-common";
-
-// 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
-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();
-```

package/docs/browser-compat-types.md

@@ -1,77 +0,0 @@
-# Browser Compat Types
-
-Cross-environment compatible types that replace DOM-only types (`FileList`, `BlobPart`, `Worker`, `Transferable`) so that typecheck passes in both Node.js and browser environments.
-
-## `BlobInput`
-
-Blob constructor data type replacing DOM `BlobPart`.
-
-```typescript
-export type BlobInput = Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | string;
-```
-
-## `FileCollection`
-
-File collection interface replacing DOM `FileList`. Structurally compatible with browser `FileList`.
-
-```typescript
-export interface FileCollection {
-  readonly length: number;
-  item(index: number): File | null;
-  [index: number]: File;
-  [Symbol.iterator](): IterableIterator<File>;
-}
-```
-
-| Member | Type | Description |
-|--------|------|-------------|
-| `length` | `number` (readonly) | Number of files in the collection |
-| `item(index)` | `(index: number) => File \| null` | Returns the file at the given index |
-| `[index]` | `File` | Index accessor |
-| `[Symbol.iterator]` | `() => IterableIterator<File>` | Iterable protocol support |
-
-## `WorkerLike`
-
-Web Worker interface replacing DOM `Worker`. Structurally compatible with browser `Worker`.
-
-```typescript
-export interface WorkerLike {
-  onmessage: ((ev: MessageEvent) => void) | null;
-  postMessage(message: unknown, transfer?: unknown[]): void;
-  terminate(): void;
-}
-```
-
-| Member | Type | Description |
-|--------|------|-------------|
-| `onmessage` | `((ev: MessageEvent) => void) \| null` | Message event handler |
-| `postMessage` | `(message: unknown, transfer?: unknown[]) => void` | Posts a message to the worker |
-| `terminate` | `() => void` | Terminates the worker |
-
-## `isWorkerSupported`
-
-Checks whether Web Worker API is available in the current environment.
-
-```typescript
-export function isWorkerSupported(): boolean;
-```
-
-**Returns:** `boolean` -- `true` if `Worker` exists in `globalThis`.
-
-## `createBrowserWorker`
-
-Creates a Web Worker instance. Returns `undefined` if the environment does not support workers.
-
-```typescript
-export function createBrowserWorker(
-  url: URL,
-  options: { type: string },
-): WorkerLike | undefined;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `url` | `URL` | Worker script URL |
-| `options` | `{ type: string }` | Worker options (e.g., `{ type: "module" }`) |
-
-**Returns:** `WorkerLike | undefined`

package/docs/client-protocol-wrapper.md

@@ -1,35 +0,0 @@
-# Client Protocol Wrapper
-
-## `ClientProtocolWrapper`
-
-Client-side protocol encoder/decoder wrapper. Automatically offloads heavy encode/decode operations to a Web Worker when available, falling back to main-thread processing for small messages or when workers are unsupported.
-
-```typescript
-export interface ClientProtocolWrapper {
-  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
-  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
-  dispose(): void;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `encode` | `uuid: string, message: ServiceMessage` | `Promise<{ chunks: Bytes[]; totalSize: number }>` | Encodes a message into binary chunks. Offloads to worker for large messages |
-| `decode` | `bytes: Bytes` | `Promise<ServiceMessageDecodeResult<ServiceMessage>>` | Decodes received binary data. Uses zero-copy transfer for large payloads |
-| `dispose` | none | `void` | Disposes the underlying protocol and worker resolver resources |
-
-## `createClientProtocolWrapper`
-
-Creates a `ClientProtocolWrapper` from a `ServiceProtocol` instance.
-
-```typescript
-export function createClientProtocolWrapper(
-  protocol: ServiceProtocol,
-): ClientProtocolWrapper;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `protocol` | `ServiceProtocol` | The base protocol encoder/decoder (from `@simplysm/service-common`) |
-
-Worker offloading threshold: 30KB. Messages below this size are processed on the main thread. The worker is a shared singleton across all `ClientProtocolWrapper` instances. Worker operations that exceed 60 seconds are automatically timed out and rejected.

package/docs/connection-options.md

@@ -1,21 +0,0 @@
-# Connection Options
-
-## `ServiceConnectionOptions`
-
-Connection options for the service client.
-
-```typescript
-export interface ServiceConnectionOptions {
-  port: number;
-  host: string;
-  ssl?: boolean;
-  maxReconnectCount?: number;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `port` | `number` | Server port |
-| `host` | `string` | Server hostname |
-| `ssl` | `boolean?` | Enable SSL/TLS (uses `wss://` and `https://` when true) |
-| `maxReconnectCount` | `number?` | Maximum reconnection attempts. Set to `0` to disable reconnection and disconnect immediately |

package/docs/features.md

@@ -1,147 +0,0 @@
-# Event/File/ORM Client
-
-## `EventClient`
-
-Event subscription client for the service event system.
-
-```typescript
-export 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: ServiceEventDef<TInfo, TData>, info: TInfo, cb: (data: TData) => PromiseLike<void>` | `Promise<string>` | Subscribes to an event. Returns a listener key (UUID) for later removal |
-| `removeListener` | `key: string` | `Promise<void>` | Unsubscribes by listener key |
-| `emit` | `eventDef: ServiceEventDef<TInfo, TData>, infoSelector: (item: TInfo) => boolean, data: TData` | `Promise<void>` | Queries matching listeners from the server, then emits the event to them |
-| `resubscribeAll` | none | `Promise<void>` | Re-registers all local listeners on the server (used after reconnection) |
-
-## `createEventClient`
-
-```typescript
-export function createEventClient(transport: ServiceTransport): EventClient;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `transport` | `ServiceTransport` | The service transport for sending event messages |
-
-## `FileClient`
-
-File upload and download client using HTTP `fetch`.
-
-```typescript
-export interface FileClient {
-  download(relPath: string): Promise<Bytes>;
-  upload(
-    files: File[] | FileCollection | { name: string; data: BlobInput }[],
-    authToken: string,
-  ): Promise<ServiceUploadResult[]>;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `download` | `relPath: string` | `Promise<Bytes>` | Downloads a file by relative path as `Uint8Array` |
-| `upload` | `files: File[] \| FileCollection \| { name: string; data: BlobInput }[], authToken: string` | `Promise<ServiceUploadResult[]>` | Uploads files via multipart form data with Bearer token authentication |
-
-## `createFileClient`
-
-```typescript
-export function createFileClient(hostUrl: string, clientName: string): FileClient;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `hostUrl` | `string` | Full host URL (e.g., `http://localhost:3000`) |
-| `clientName` | `string` | Client identifier sent in `x-sd-client-name` header |
-
-## `OrmConnectOptions`
-
-ORM connection options for client-side database context usage.
-
-```typescript
-export interface OrmConnectOptions<T extends DbContext> {
-  DbClass: new (executor: DbContextExecutor, opt: { database: string; schema?: string }) => T;
-  connOpt: DbConnOptions & { configName: string };
-  dbContextOpt?: {
-    database: string;
-    schema: string;
-  };
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `DbClass` | `new (executor: DbContextExecutor, opt: { database: string; schema?: string }) => T` | DbContext subclass constructor |
-| `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.
-
-```typescript
-export interface OrmClientConnector {
-  connect<T extends DbContext, R>(
-    config: OrmConnectOptions<T>,
-    callback: (db: T) => Promise<R> | R,
-  ): Promise<R>;
-  connectWithoutTransaction<T extends DbContext, R>(
-    config: OrmConnectOptions<T>,
-    callback: (db: T) => Promise<R> | R,
-  ): Promise<R>;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `connect` | `config: OrmConnectOptions<T>, callback: (db: T) => Promise<R> \| R` | `Promise<R>` | Opens a DB context with automatic transaction (begin/commit/rollback). Wraps foreign key constraint errors with a user-friendly message |
-| `connectWithoutTransaction` | `config: OrmConnectOptions<T>, callback: (db: T) => Promise<R> \| R` | `Promise<R>` | Opens a DB context without automatic transaction management |
-
-## `createOrmClientConnector`
-
-```typescript
-export function createOrmClientConnector(serviceClient: ServiceClient): OrmClientConnector;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `serviceClient` | `ServiceClient` | The service client instance for RPC communication |
-
-## `OrmClientDbContextExecutor`
-
-Implements `DbContextExecutor` (from `@simplysm/orm-common`) for client-side ORM usage over the service RPC layer. Proxies all database operations through the remote `OrmService`.
-
-```typescript
-export class OrmClientDbContextExecutor implements DbContextExecutor {
-  constructor(
-    client: ServiceClient,
-    opt: DbConnOptions & { configName: string },
-  );
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getInfo` | none | `Promise<{ dialect: Dialect; database?: string; schema?: string }>` | Gets database info via remote ORM service |
-| `connect` | none | `Promise<void>` | Opens a remote connection |
-| `beginTransaction` | `isolationLevel?: IsolationLevel` | `Promise<void>` | Begins a remote transaction |
-| `commitTransaction` | none | `Promise<void>` | Commits the remote transaction |
-| `rollbackTransaction` | none | `Promise<void>` | Rolls back the remote transaction |
-| `close` | none | `Promise<void>` | Closes the remote connection |
-| `executeDefs` | `defs: QueryDef[], options?: (ResultMeta \| undefined)[]` | `Promise<T[][]>` | Executes query definitions via remote ORM service |
-| `executeParametrized` | `query: string, params?: unknown[]` | `Promise<unknown[][]>` | Executes a parameterized query via remote ORM service |
-| `bulkInsert` | `tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]` | `Promise<void>` | Performs bulk insert via remote ORM service |

package/docs/progress-types.md

@@ -1,37 +0,0 @@
-# Progress Types
-
-## `ServiceProgress`
-
-Callback hooks for monitoring message progress at different stages.
-
-```typescript
-export interface ServiceProgress {
-  request?: (s: ServiceProgressState) => void;
-  response?: (s: ServiceProgressState) => void;
-  server?: (s: ServiceProgressState) => void;
-}
-```
-
-| 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 |
-
-## `ServiceProgressState`
-
-Progress state for a single message transfer.
-
-```typescript
-export interface ServiceProgressState {
-  uuid: string;
-  totalSize: number;
-  completedSize: number;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `uuid` | `string` | Message UUID |
-| `totalSize` | `number` | Total message size in bytes |
-| `completedSize` | `number` | Bytes transferred so far |

package/docs/service-client.md

@@ -1,89 +0,0 @@
-# Main ServiceClient
-
-## `ServiceClient`
-
-Main service client class. Extends `EventEmitter` with progress and state events. Composes `SocketProvider`, `ServiceTransport`, `EventClient`, `FileClient`, and `ClientProtocolWrapper` internally.
-
-```typescript
-export 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 (chunked messages) |
-| `response-progress` | `ServiceProgressState` | Response receiving progress (chunked messages) |
-| `server-progress` | `ServiceProgressState` | Server-side chunk reception progress |
-| `state` | `"connected" \| "closed" \| "reconnecting"` | Connection state change |
-
-### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `name` | `string` (readonly) | Client name |
-| `options` | `ServiceConnectionOptions` (readonly) | Connection options |
-| `connected` | `boolean` (readonly, getter) | Whether the client is currently connected |
-| `hostUrl` | `string` (readonly, getter) | Full host URL computed from options (e.g., `https://host:port`) |
-
-### Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `getService` | `getService<TService>(serviceName: string): ServiceProxy<TService>` | Returns a type-safe proxy that maps method calls to RPC requests |
-| `connect` | `connect(): Promise<void>` | Opens the WebSocket connection |
-| `close` | `close(): Promise<void>` | Closes the connection and disposes protocol resources |
-| `send` | `send(serviceName: string, methodName: string, params: unknown[], progress?: ServiceProgress): Promise<unknown>` | Sends an RPC call directly |
-| `auth` | `auth(token: string): Promise<void>` | Authenticates with a JWT token. Token is cached for reconnection |
-| `addListener` | `addListener<TInfo, TData>(eventDef: ServiceEventDef<TInfo, TData>, info: TInfo, cb: (data: TData) => PromiseLike<void>): Promise<string>` | Subscribes to an event. Returns listener key. Throws if not connected |
-| `removeListener` | `removeListener(key: string): Promise<void>` | Unsubscribes from an event by key |
-| `emitEvent` | `emitEvent<TInfo, TData>(eventDef: ServiceEventDef<TInfo, TData>, infoSelector: (item: TInfo) => boolean, data: TData): Promise<void>` | Emits an event to matching listeners |
-| `uploadFile` | `uploadFile(files: File[] \| FileCollection \| { name: string; data: BlobInput }[]): Promise<ServiceUploadResult[]>` | Uploads files. Requires prior `auth()` call |
-| `downloadFileBuffer` | `downloadFileBuffer(relPath: string): Promise<Bytes>` | Downloads a file as `Uint8Array` |
-
-### Reconnection Behavior
-
-On reconnection (`state === "connected"` after a disconnect):
-1. Re-authenticates with the cached token (if `auth()` was previously called)
-2. Re-subscribes all event listeners via `EventClient.resubscribeAll()`
-
-## `ServiceProxy`
-
-Type utility that wraps all methods of a service interface to return `Promise<Awaited<R>>`.
-
-```typescript
-export type ServiceProxy<TService> = {
-  [K in keyof TService]: TService[K] extends (...args: infer P) => infer R
-    ? (...args: P) => Promise<Awaited<R>>
-    : never;
-};
-```
-
-Non-function properties are mapped to `never`.
-
-## `createServiceClient`
-
-Factory function to create a `ServiceClient` instance.
-
-```typescript
-export function createServiceClient(
-  name: string,
-  options: ServiceConnectionOptions,
-): ServiceClient;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `name` | `string` | Client identifier name |
-| `options` | `ServiceConnectionOptions` | Connection options (host, port, SSL, maxReconnectCount) |
-
-**Returns:** `ServiceClient`
-
-Default `maxReconnectCount` is `10` if not specified in options.

package/docs/service-transport.md

@@ -1,60 +0,0 @@
-# Service Transport
-
-## `ServiceTransportEvents`
-
-Event map for the service transport.
-
-```typescript
-export interface ServiceTransportEvents {
-  event: { keys: string[]; data: unknown };
-}
-```
-
-| Event | Data Type | Description |
-|-------|-----------|-------------|
-| `event` | `{ keys: string[]; data: unknown }` | Server-side event broadcast received |
-
-## `ServiceTransport`
-
-Service-level message transport built on top of `SocketProvider` and `ClientProtocolWrapper`. Manages pending request/response correlation via UUIDs, handles progress notifications, and dispatches events.
-
-```typescript
-export 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: K, listener` | `void` | Subscribe to transport events |
-| `off` | `type: K, listener` | `void` | Unsubscribe from transport events |
-| `send` | `message: ServiceClientMessage, progress?: ServiceProgress` | `Promise<unknown>` | Sends a service message and awaits the server response. Returns the response body |
-
-## `createServiceTransport`
-
-Creates a `ServiceTransport` instance.
-
-```typescript
-export function createServiceTransport(
-  socket: SocketProvider,
-  protocol: ClientProtocolWrapper,
-): ServiceTransport;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `socket` | `SocketProvider` | The socket provider for sending/receiving binary data |
-| `protocol` | `ClientProtocolWrapper` | The protocol wrapper for encoding/decoding messages |
-
-Behavior:
-- Generates a UUID per `send()` call and registers a pending resolver
-- On socket disconnect (`closed`/`reconnecting`), rejects all pending requests
-- Routes server messages: `response` resolves, `error` rejects, `evt:on` emits event, `progress` invokes progress callbacks

package/docs/socket-provider.md

@@ -1,72 +0,0 @@
-# Socket Provider
-
-## `SocketProviderEvents`
-
-Event map for the socket provider.
-
-```typescript
-export interface SocketProviderEvents {
-  message: Bytes;
-  state: "connected" | "closed" | "reconnecting";
-}
-```
-
-| Event | Data Type | Description |
-|-------|-----------|-------------|
-| `message` | `Bytes` | Raw binary message received from server |
-| `state` | `"connected" \| "closed" \| "reconnecting"` | Connection state change |
-
-## `SocketProvider`
-
-Low-level WebSocket abstraction with automatic reconnection and heartbeat keepalive. Works in both browser and Node.js environments (uses `ws` package as polyfill in Node.js).
-
-```typescript
-export 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 (readonly) | Client identifier name |
-| `connected` | property (readonly) | Whether currently connected |
-| `on` | method | Subscribe to an event |
-| `off` | method | Unsubscribe from an event |
-| `connect` | method | Opens the WebSocket connection. Throws on initial connection failure |
-| `close` | method | Closes the connection gracefully |
-| `send` | method | Sends binary data. Waits for connection if not yet open |
-
-## `createSocketProvider`
-
-Creates a `SocketProvider` instance with auto-reconnect and heartbeat.
-
-```typescript
-export function createSocketProvider(
-  url: string,
-  clientName: string,
-  maxReconnectCount: number,
-): SocketProvider;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `url` | `string` | WebSocket URL (e.g., `ws://localhost:3000/ws`) |
-| `clientName` | `string` | Client identifier |
-| `maxReconnectCount` | `number` | Maximum reconnection attempts |
-
-Internal constants:
-- Heartbeat timeout: 30 seconds
-- Heartbeat interval: 5 seconds (sends ping `0x01`, expects pong `0x02`)
-- Reconnect delay: 3 seconds between attempts