@simplysm/service-common 14.0.4 → 14.0.5

package/README.md

@@ -1,233 +1,114 @@
 # @simplysm/service-common
 
-Shared service protocol and types -- binary protocol V2 with chunking, message types, service event definitions.
-
-This package provides the platform-neutral foundation shared by both `@simplysm/service-client` and `@simplysm/service-server`.
-
-## API
-
-| Export | Kind | Category | Description |
-|--------|------|----------|-------------|
-| `PROTOCOL_CONFIG` | const | Protocol | Protocol configuration constants (max size, chunk size, GC interval, expiry) |
-| `ServiceMessage` | type | Protocol | Union of all message types (client + server) |
-| `ServiceServerMessage` | type | Protocol | Union of server-to-client message types |
-| `ServiceServerRawMessage` | type | Protocol | Server raw message (includes progress) |
-| `ServiceClientMessage` | type | Protocol | Union of client-to-server message types |
-| `ServiceProgressMessage` | interface | Protocol | Chunk receive progress notification |
-| `ServiceErrorMessage` | interface | Protocol | Error notification from server |
-| `ServiceAuthMessage` | interface | Protocol | Authentication message from client |
-| `ServiceRequestMessage` | interface | Protocol | Service method request from client |
-| `ServiceResponseMessage` | interface | Protocol | Service method response from server |
-| `ServiceAddEventListenerMessage` | interface | Protocol | Add event listener request |
-| `ServiceRemoveEventListenerMessage` | interface | Protocol | Remove event listener request |
-| `ServiceGetEventListenerInfosMessage` | interface | Protocol | Get event listener info list request |
-| `ServiceEmitEventMessage` | interface | Protocol | Emit event request |
-| `ServiceEventMessage` | interface | Protocol | Event notification from server |
-| `ServiceProtocol` | interface | Protocol | Protocol encoder/decoder interface |
-| `ServiceMessageDecodeResult` | type | Protocol | Decode result (complete or progress) |
-| `createServiceProtocol` | function | Protocol | Create a protocol encoder/decoder instance |
-| `OrmService` | interface | Service Types | ORM service interface (connect, transaction, query) |
-| `DbConnOptions` | type | Service Types | Database connection options |
-| `AutoUpdateService` | interface | Service Types | Auto-update service interface |
-| `ServiceUploadResult` | interface | Types | File upload result |
-| `ServiceEventDef` | interface | Definitions | Event definition created by `defineEvent()` |
-| `defineEvent` | function | Definitions | Define a typed service event |
-
-## Protocol
-
-### PROTOCOL_CONFIG
-
-Protocol configuration constants.
-
-```ts
-import { PROTOCOL_CONFIG } from "@simplysm/service-common";
-```
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `MAX_TOTAL_SIZE` | `number` | `104,857,600` (100 MB) | Maximum message size |
-| `SPLIT_MESSAGE_SIZE` | `number` | `3,145,728` (3 MB) | Chunking threshold -- messages larger than this are split |
-| `CHUNK_SIZE` | `number` | `307,200` (300 KB) | Size of each chunk |
-| `GC_INTERVAL` | `number` | `10,000` (10 s) | Garbage collection interval for incomplete messages |
-| `EXPIRE_TIME` | `number` | `60,000` (60 s) | Expiry time for incomplete chunked messages |
-
-### Message Types
-
-All messages exchanged between client and server are strongly typed.
-
-#### Client-to-Server Messages
-
-| Interface | `name` Field | Description |
-|-----------|-------------|-------------|
-| `ServiceAuthMessage` | `"auth"` | Authenticate with a token string |
-| `ServiceRequestMessage` | `` `${service}.${method}` `` | Call a service method with parameters |
-| `ServiceAddEventListenerMessage` | `"evt:add"` | Register an event listener with key, event name, and filter info |
-| `ServiceRemoveEventListenerMessage` | `"evt:remove"` | Unregister an event listener by key |
-| `ServiceGetEventListenerInfosMessage` | `"evt:gets"` | Query listener info list for an event name |
-| `ServiceEmitEventMessage` | `"evt:emit"` | Emit an event to specific listener keys |
-
-#### Server-to-Client Messages
-
-| Interface | `name` Field | Description |
-|-----------|-------------|-------------|
-| `ServiceProgressMessage` | `"progress"` | Chunk receive progress (`totalSize`, `completedSize`) |
-| `ServiceResponseMessage` | `"response"` | Service method return value |
-| `ServiceErrorMessage` | `"error"` | Error with name, message, code, optional stack/detail/cause |
-| `ServiceEventMessage` | `"evt:on"` | Event broadcast to listener keys with data |
-
-### ServiceProtocol
-
-Binary protocol V2 interface. Header: 28 bytes (UUID 16 + TotalSize 8 + Index 4), body: JSON. Auto-chunks messages exceeding 3 MB into 300 KB chunks. Maximum message size: 100 MB.
-
-```ts
-interface ServiceProtocol {
-  encode(uuid: string, message: ServiceMessage): { chunks: Bytes[]; totalSize: number };
-  decode<T extends ServiceMessage>(bytes: Bytes): ServiceMessageDecodeResult<T>;
-  dispose(): void;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `encode` | `uuid: string`, `message: ServiceMessage` | `{ chunks: Bytes[]; totalSize: number }` | Encode a message into binary chunks |
-| `decode` | `bytes: Bytes` | `ServiceMessageDecodeResult<T>` | Decode received bytes; returns `"complete"` or `"progress"` |
-| `dispose` | -- | `void` | Clean up internal GC timers |
-
-### ServiceMessageDecodeResult\<TMessage\>
-
-```ts
-type ServiceMessageDecodeResult<TMessage extends ServiceMessage> =
-  | { type: "complete"; uuid: string; message: TMessage }
-  | { type: "progress"; uuid: string; totalSize: number; completedSize: number };
-```
-
-- `"complete"` -- all chunks received; the full message is available.
-- `"progress"` -- chunked message still in progress.
+Shared types and protocol for the Simplysm service framework. Provides the binary protocol V2 encoder/decoder, message type definitions, service interface contracts (ORM, auto-update), and event definition utilities used by both `@simplysm/service-client` and `@simplysm/service-server`.
 
-### createServiceProtocol
+## Installation
 
-```ts
-function createServiceProtocol(): ServiceProtocol;
+```bash
+npm install @simplysm/service-common
 ```
 
-Creates a binary protocol V2 encoder/decoder instance.
-
-## Service Types
-
-### OrmService
-
-ORM service interface. Supports MySQL, MSSQL, and PostgreSQL.
-
-```ts
-interface OrmService {
-  getInfo(opt: DbConnOptions & { configName: string }): Promise<{ dialect: Dialect; database?: string; schema?: string }>;
-  connect(opt: DbConnOptions & { configName: string }): Promise<number>;
-  close(connId: number): Promise<void>;
-  beginTransaction(connId: number, isolationLevel?: IsolationLevel): Promise<void>;
-  commitTransaction(connId: number): Promise<void>;
-  rollbackTransaction(connId: number): Promise<void>;
-  executeParametrized(connId: number, query: string, params?: unknown[]): Promise<unknown[][]>;
-  executeDefs(connId: number, defs: QueryDef[], options?: (ResultMeta | undefined)[]): Promise<unknown[][]>;
-  bulkInsert(connId: number, tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]): Promise<void>;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getInfo` | `opt: DbConnOptions & { configName: string }` | `Promise<{ dialect; database?; schema? }>` | Get database dialect and schema info |
-| `connect` | `opt: DbConnOptions & { configName: string }` | `Promise<number>` | Open a connection; returns connection ID |
-| `close` | `connId: number` | `Promise<void>` | Close a connection |
-| `beginTransaction` | `connId: number`, `isolationLevel?: IsolationLevel` | `Promise<void>` | Begin a transaction |
-| `commitTransaction` | `connId: number` | `Promise<void>` | Commit the current transaction |
-| `rollbackTransaction` | `connId: number` | `Promise<void>` | Rollback the current transaction |
-| `executeParametrized` | `connId: number`, `query: string`, `params?: unknown[]` | `Promise<unknown[][]>` | Execute a parameterized query |
-| `executeDefs` | `connId: number`, `defs: QueryDef[]`, `options?: (ResultMeta \| undefined)[]` | `Promise<unknown[][]>` | Execute query definitions |
-| `bulkInsert` | `connId: number`, `tableName: string`, `columnDefs: Record<string, ColumnMeta>`, `records: Record<string, unknown>[]` | `Promise<void>` | Bulk insert records |
-
-### DbConnOptions
-
-```ts
-type DbConnOptions = { configName?: string; config?: Record<string, unknown> };
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `configName` | `string?` | Configuration name to look up |
-| `config` | `Record<string, unknown>?` | Inline configuration object |
-
-### AutoUpdateService
-
-Auto-update service interface. Retrieves the latest version information for client applications.
-
-```ts
-interface AutoUpdateService {
-  getLastVersion(platform: string): Promise<{ version: string; downloadPath: string } | undefined>;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getLastVersion` | `platform: string` | `Promise<{ version: string; downloadPath: string } \| undefined>` | Get latest version info for a platform |
-
-## Types
-
-### ServiceUploadResult
-
-File upload result containing server-side storage information.
-
-```ts
-interface ServiceUploadResult {
-  path: string;
-  filename: string;
-  size: number;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `path` | `string` | Server-side storage path |
-| `filename` | `string` | Original file name |
-| `size` | `number` | File size in bytes |
-
-## Definitions
-
-### ServiceEventDef\<TInfo, TData\>
-
-Event definition created by `defineEvent()`. The `$info` and `$data` fields are type-only markers (not used at runtime).
+## API Overview
+
+### Protocol Types
+| API | Type | Description |
+|-----|------|-------------|
+| `PROTOCOL_CONFIG` | `const` | Protocol configuration constants (max size, chunk size, GC interval, expiry) |
+| `ServiceMessage` | `type` | Union of all message types |
+| `ServiceServerMessage` | `type` | Union of server-to-client message types |
+| `ServiceServerRawMessage` | `type` | Union of progress + server message types |
+| `ServiceClientMessage` | `type` | Union of client-to-server message types |
+| `ServiceProgressMessage` | `interface` | Chunked message progress notification |
+| `ServiceErrorMessage` | `interface` | Error notification from server |
+| `ServiceAuthMessage` | `interface` | Authentication message from client |
+| `ServiceRequestMessage` | `interface` | Service method request from client |
+| `ServiceResponseMessage` | `interface` | Service method response from server |
+| `ServiceAddEventListenerMessage` | `interface` | Add event listener request |
+| `ServiceRemoveEventListenerMessage` | `interface` | Remove event listener request |
+| `ServiceGetEventListenerInfosMessage` | `interface` | Get event listener infos request |
+| `ServiceEmitEventMessage` | `interface` | Emit event request |
+| `ServiceEventMessage` | `interface` | Event notification from server |
+
+-> See [docs/protocol-types.md](./docs/protocol-types.md) for details.
+
+### Service Protocol
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceProtocol` | `interface` | Binary protocol encoder/decoder interface |
+| `ServiceMessageDecodeResult` | `type` | Decode result union (complete or progress) |
+| `createServiceProtocol` | `function` | Creates a protocol encoder/decoder instance |
+
+-> See [docs/service-protocol.md](./docs/service-protocol.md) for details.
+
+### ORM Service Types
+| API | Type | Description |
+|-----|------|-------------|
+| `OrmService` | `interface` | ORM service interface for DB operations |
+| `DbConnOptions` | `type` | Database connection options |
+
+-> See [docs/orm-service-types.md](./docs/orm-service-types.md) for details.
+
+### Auto-Update Service Types
+| API | Type | Description |
+|-----|------|-------------|
+| `AutoUpdateService` | `interface` | Auto-update service interface |
+
+-> See [docs/auto-update-service-types.md](./docs/auto-update-service-types.md) for details.
+
+### Common Types
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceUploadResult` | `interface` | File upload result containing path, filename, and size |
+
+-> See [docs/common-types.md](./docs/common-types.md) for details.
+
+### Events
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceEventDef` | `interface` | Type-safe event definition with info and data markers |
+| `defineEvent` | `function` | Creates a typed service event definition |
+
+-> See [docs/events.md](./docs/events.md) for details.
+
+## Usage Examples
+
+### Creating a Protocol Instance
+
+```typescript
+import { createServiceProtocol } from "@simplysm/service-common";
+
+const protocol = createServiceProtocol();
+
+// Encode a message
+const { chunks, totalSize } = protocol.encode("some-uuid", {
+  name: "SomeService.someMethod",
+  body: [arg1, arg2],
+});
 
-```ts
-interface ServiceEventDef<TInfo = unknown, TData = unknown> {
-  eventName: string;
-  readonly $info: TInfo;
-  readonly $data: TData;
+// Decode received bytes
+const result = protocol.decode(receivedBytes);
+if (result.type === "complete") {
+  console.log(result.message);
+} else {
+  console.log(`Progress: ${result.completedSize}/${result.totalSize}`);
 }
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `eventName` | `string` | Event name identifier |
-| `$info` | `TInfo` | Type-only marker for listener filter info |
-| `$data` | `TData` | Type-only marker for event payload data |
-
-### defineEvent
 
-```ts
-function defineEvent<TInfo = unknown, TData = unknown>(eventName: string): ServiceEventDef<TInfo, TData>;
+// Dispose when done
+protocol.dispose();
 ```
 
-Define a typed service event for use with the event system.
+### Defining a Typed Event
 
-```ts
+```typescript
 import { defineEvent } from "@simplysm/service-common";
 
-// Define an event with typed info and data
-const MyEvent = defineEvent<{ userId: number }, { message: string }>("MyEvent");
+const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
 
-// Server: emit the event
-await server.emitEvent(MyEvent, (info) => info.userId === 123, { message: "hello" });
+// Server: emit event
+await server.emitEvent(OrderUpdated, (info) => info.orderId === 123, { status: "shipped" });
 
-// Client: subscribe to the event
-await client.addListener(MyEvent, { userId: 123 }, async (data) => {
-  console.log(data.message);
+// Client: subscribe
+await client.addListener(OrderUpdated, { orderId: 123 }, async (data) => {
+  console.log(data.status);
 });
 ```

package/docs/auto-update-service-types.md

@@ -0,0 +1,21 @@
+# Auto-Update Service Types
+
+## `AutoUpdateService`
+
+Auto-update service interface for querying the latest client application version.
+
+```typescript
+export interface AutoUpdateService {
+  getLastVersion(platform: string): Promise<
+    | {
+        version: string;
+        downloadPath: string;
+      }
+    | undefined
+  >;
+}
+```
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `getLastVersion` | `platform: string` | `Promise<{ version: string; downloadPath: string } \| undefined>` | Returns the latest version info for the given platform (e.g., `"win32"`, `"darwin"`, `"linux"`, `"android"`). Returns `undefined` if no version is available |

package/docs/common-types.md

@@ -0,0 +1,19 @@
+# Common Types
+
+## `ServiceUploadResult`
+
+File upload result containing information about the uploaded file.
+
+```typescript
+export interface ServiceUploadResult {
+  path: string;
+  filename: string;
+  size: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `path` | `string` | Server-side storage path (relative) |
+| `filename` | `string` | Original filename |
+| `size` | `number` | File size in bytes |

package/docs/events.md

@@ -0,0 +1,58 @@
+# Events
+
+## `ServiceEventDef`
+
+Type-safe event definition created by `defineEvent()`. The `$info` and `$data` fields are type-only markers not used at runtime.
+
+```typescript
+export interface ServiceEventDef<TInfo = unknown, TData = unknown> {
+  eventName: string;
+  readonly $info: TInfo;
+  readonly $data: TData;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `eventName` | `string` | Event name identifier |
+| `$info` | `TInfo` | Type-only marker for event filter info (not used at runtime) |
+| `$data` | `TData` | Type-only marker for event data (not used at runtime) |
+
+## `defineEvent`
+
+Creates a type-safe service event definition with typed info and data.
+
+```typescript
+export function defineEvent<TInfo = unknown, TData = unknown>(
+  eventName: string,
+): ServiceEventDef<TInfo, TData>;
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `eventName` | `string` | Event name identifier |
+
+**Type Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `TInfo` | Type of the event filter info |
+| `TData` | Type of the event data payload |
+
+**Returns:** `ServiceEventDef<TInfo, TData>`
+
+**Example:**
+
+```typescript
+const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
+
+// Server: emit event
+ctx.socket?.emitEvent(OrderUpdated, { orderId: 123 }, { status: "shipped" });
+
+// Client: subscribe
+await client.addEventListener(OrderUpdated, { orderId: 123 }, (data) => {
+  console.log(data.status); // typed as string
+});
+```

package/docs/orm-service-types.md

@@ -0,0 +1,57 @@
+# ORM Service Types
+
+## `OrmService`
+
+ORM service interface providing database connection, transaction management, and query execution. Supports MySQL, MSSQL, and PostgreSQL.
+
+```typescript
+export interface OrmService {
+  getInfo(opt: DbConnOptions & { configName: string }): Promise<{
+    dialect: Dialect;
+    database?: string;
+    schema?: string;
+  }>;
+  connect(opt: DbConnOptions & { configName: string }): Promise<number>;
+  close(connId: number): Promise<void>;
+  beginTransaction(connId: number, isolationLevel?: IsolationLevel): Promise<void>;
+  commitTransaction(connId: number): Promise<void>;
+  rollbackTransaction(connId: number): Promise<void>;
+  executeParametrized(connId: number, query: string, params?: unknown[]): Promise<unknown[][]>;
+  executeDefs(
+    connId: number,
+    defs: QueryDef[],
+    options?: (ResultMeta | undefined)[],
+  ): Promise<unknown[][]>;
+  bulkInsert(
+    connId: number,
+    tableName: string,
+    columnDefs: Record<string, ColumnMeta>,
+    records: Record<string, unknown>[],
+  ): Promise<void>;
+}
+```
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `getInfo` | `opt: DbConnOptions & { configName: string }` | `Promise<{ dialect: Dialect; database?: string; schema?: string }>` | Gets database connection info |
+| `connect` | `opt: DbConnOptions & { configName: string }` | `Promise<number>` | Opens a connection, returns connection ID |
+| `close` | `connId: number` | `Promise<void>` | Closes a connection |
+| `beginTransaction` | `connId: number, isolationLevel?: IsolationLevel` | `Promise<void>` | Begins a transaction |
+| `commitTransaction` | `connId: number` | `Promise<void>` | Commits a transaction |
+| `rollbackTransaction` | `connId: number` | `Promise<void>` | Rolls back a transaction |
+| `executeParametrized` | `connId: number, query: string, params?: unknown[]` | `Promise<unknown[][]>` | Executes a parameterized query |
+| `executeDefs` | `connId: number, defs: QueryDef[], options?: (ResultMeta \| undefined)[]` | `Promise<unknown[][]>` | Executes query definitions |
+| `bulkInsert` | `connId: number, tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]` | `Promise<void>` | Performs bulk insert |
+
+## `DbConnOptions`
+
+Database connection options.
+
+```typescript
+export type DbConnOptions = { configName?: string; config?: Record<string, unknown> };
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `configName` | `string?` | Configuration name to look up from server config |
+| `config` | `Record<string, unknown>?` | Additional configuration overrides |

package/docs/protocol-types.md

@@ -0,0 +1,268 @@
+# Protocol Types
+
+## `PROTOCOL_CONFIG`
+
+Protocol configuration constants for message size limits and timing.
+
+```typescript
+export const PROTOCOL_CONFIG: {
+  readonly MAX_TOTAL_SIZE: 104857600;   // 100MB
+  readonly SPLIT_MESSAGE_SIZE: 3145728; // 3MB
+  readonly CHUNK_SIZE: 307200;          // 300KB
+  readonly GC_INTERVAL: 10000;          // 10s
+  readonly EXPIRE_TIME: 60000;          // 60s
+};
+```
+
+| Field | Value | Description |
+|-------|-------|-------------|
+| `MAX_TOTAL_SIZE` | `104857600` (100MB) | Maximum total message size |
+| `SPLIT_MESSAGE_SIZE` | `3145728` (3MB) | Threshold above which messages are split into chunks |
+| `CHUNK_SIZE` | `307200` (300KB) | Size of each chunk when splitting |
+| `GC_INTERVAL` | `10000` (10s) | Garbage collection interval for incomplete messages |
+| `EXPIRE_TIME` | `60000` (60s) | Expiration time for incomplete messages |
+
+## `ServiceMessage`
+
+Union of all service message types.
+
+```typescript
+export type ServiceMessage =
+  | ServiceRequestMessage
+  | ServiceAuthMessage
+  | ServiceProgressMessage
+  | ServiceResponseMessage
+  | ServiceErrorMessage
+  | ServiceAddEventListenerMessage
+  | ServiceRemoveEventListenerMessage
+  | ServiceGetEventListenerInfosMessage
+  | ServiceEmitEventMessage
+  | ServiceEventMessage;
+```
+
+## `ServiceServerMessage`
+
+Union of message types sent from server to client.
+
+```typescript
+export type ServiceServerMessage =
+  | ServiceResponseMessage
+  | ServiceErrorMessage
+  | ServiceEventMessage;
+```
+
+## `ServiceServerRawMessage`
+
+Union of server raw messages including progress notifications.
+
+```typescript
+export type ServiceServerRawMessage = ServiceProgressMessage | ServiceServerMessage;
+```
+
+## `ServiceClientMessage`
+
+Union of message types sent from client to server.
+
+```typescript
+export type ServiceClientMessage =
+  | ServiceRequestMessage
+  | ServiceAuthMessage
+  | ServiceAddEventListenerMessage
+  | ServiceRemoveEventListenerMessage
+  | ServiceGetEventListenerInfosMessage
+  | ServiceEmitEventMessage;
+```
+
+## `ServiceProgressMessage`
+
+Server notification about chunked message reception progress.
+
+```typescript
+export interface ServiceProgressMessage {
+  name: "progress";
+  body: {
+    totalSize: number;
+    completedSize: number;
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"progress"` | Message type discriminator |
+| `body.totalSize` | `number` | Total size in bytes |
+| `body.completedSize` | `number` | Completed size in bytes |
+
+## `ServiceErrorMessage`
+
+Server error notification.
+
+```typescript
+export interface ServiceErrorMessage {
+  name: "error";
+  body: {
+    name: string;
+    message: string;
+    code: string;
+    stack?: string;
+    detail?: unknown;
+    cause?: unknown;
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"error"` | Message type discriminator |
+| `body.name` | `string` | Error name |
+| `body.message` | `string` | Error message |
+| `body.code` | `string` | Error code (e.g., `"BAD_MESSAGE"`, `"INTERNAL_ERROR"`) |
+| `body.stack` | `string?` | Stack trace (dev mode only) |
+| `body.detail` | `unknown?` | Additional error detail |
+| `body.cause` | `unknown?` | Error cause |
+
+## `ServiceAuthMessage`
+
+Client authentication message.
+
+```typescript
+export interface ServiceAuthMessage {
+  name: "auth";
+  body: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"auth"` | Message type discriminator |
+| `body` | `string` | Authentication token |
+
+## `ServiceRequestMessage`
+
+Client service method request.
+
+```typescript
+export interface ServiceRequestMessage {
+  name: `${string}.${string}`;
+  body: unknown[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `` `${string}.${string}` `` | `${serviceName}.${methodName}` format |
+| `body` | `unknown[]` | Method parameters |
+
+## `ServiceResponseMessage`
+
+Server service method response.
+
+```typescript
+export interface ServiceResponseMessage {
+  name: "response";
+  body?: unknown;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"response"` | Message type discriminator |
+| `body` | `unknown?` | Method return value |
+
+## `ServiceAddEventListenerMessage`
+
+Client request to add an event listener.
+
+```typescript
+export interface ServiceAddEventListenerMessage {
+  name: "evt:add";
+  body: {
+    key: string;
+    name: string;
+    info: unknown;
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"evt:add"` | Message type discriminator |
+| `body.key` | `string` | Listener key (UUID) for removal |
+| `body.name` | `string` | Event name |
+| `body.info` | `unknown` | Additional listener info for event filtering |
+
+## `ServiceRemoveEventListenerMessage`
+
+Client request to remove an event listener.
+
+```typescript
+export interface ServiceRemoveEventListenerMessage {
+  name: "evt:remove";
+  body: {
+    key: string;
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"evt:remove"` | Message type discriminator |
+| `body.key` | `string` | Listener key (UUID) |
+
+## `ServiceGetEventListenerInfosMessage`
+
+Client request to get event listener information.
+
+```typescript
+export interface ServiceGetEventListenerInfosMessage {
+  name: "evt:gets";
+  body: {
+    name: string;
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"evt:gets"` | Message type discriminator |
+| `body.name` | `string` | Event name |
+
+## `ServiceEmitEventMessage`
+
+Client request to emit an event to specific listeners.
+
+```typescript
+export interface ServiceEmitEventMessage {
+  name: "evt:emit";
+  body: {
+    keys: string[];
+    data: unknown;
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"evt:emit"` | Message type discriminator |
+| `body.keys` | `string[]` | Target listener keys |
+| `body.data` | `unknown` | Event data |
+
+## `ServiceEventMessage`
+
+Server event notification to client.
+
+```typescript
+export interface ServiceEventMessage {
+  name: "evt:on";
+  body: {
+    keys: string[];
+    data: unknown;
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"evt:on"` | Message type discriminator |
+| `body.keys` | `string[]` | Target listener keys |
+| `body.data` | `unknown` | Event data |

package/docs/service-protocol.md

@@ -0,0 +1,58 @@
+# Service Protocol
+
+## `ServiceProtocol`
+
+Binary protocol encoder/decoder interface. Uses a 28-byte header (UUID 16 + TotalSize 8 + Index 4) with JSON body. Automatically chunks messages larger than 3MB into 300KB chunks. Maximum message size is 100MB.
+
+```typescript
+export interface ServiceProtocol {
+  encode(uuid: string, message: ServiceMessage): { chunks: Bytes[]; totalSize: number };
+  decode<T extends ServiceMessage>(bytes: Bytes): ServiceMessageDecodeResult<T>;
+  dispose(): void;
+}
+```
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `encode` | `uuid: string, message: ServiceMessage` | `{ chunks: Bytes[]; totalSize: number }` | Encodes a message, auto-splitting if needed |
+| `decode` | `bytes: Bytes` | `ServiceMessageDecodeResult<T>` | Decodes a message, auto-reassembling chunks |
+| `dispose` | none | `void` | Releases the internal chunk accumulator GC timer. Must be called when the instance is no longer needed |
+
+## `ServiceMessageDecodeResult`
+
+Decode result union type. Either a complete message or a progress indicator for chunked messages.
+
+```typescript
+export type ServiceMessageDecodeResult<TMessage extends ServiceMessage> =
+  | { type: "complete"; uuid: string; message: TMessage }
+  | { type: "progress"; uuid: string; totalSize: number; completedSize: number };
+```
+
+When `type` is `"complete"`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"complete"` | All chunks received, message reassembled |
+| `uuid` | `string` | Message UUID |
+| `message` | `TMessage` | Decoded message |
+
+When `type` is `"progress"`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"progress"` | Partial chunks received |
+| `uuid` | `string` | Message UUID |
+| `totalSize` | `number` | Total size in bytes |
+| `completedSize` | `number` | Completed size in bytes |
+
+## `createServiceProtocol`
+
+Creates a service protocol encoder/decoder instance.
+
+```typescript
+export function createServiceProtocol(): ServiceProtocol;
+```
+
+**Returns:** `ServiceProtocol` -- A new protocol instance with encode/decode/dispose methods.
+
+The instance maintains an internal `LazyGcMap` accumulator for reassembling chunked messages. The GC timer runs every 10 seconds and expires incomplete messages after 60 seconds.

package/package.json

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