@simplysm/service-common 13.0.29 → 13.0.31

package/README.md

@@ -1,6 +1,6 @@
 # @simplysm/service-common
 
-A package that provides shared communication protocols, message types, and service interface definitions between the service client (`service-client`) and server (`service-server`). It includes binary protocol-based message encoding/decoding, automatic message chunking for large payloads, event system types, and service interfaces for ORM/encryption/auto-update.
+A package that provides shared communication protocols, message types, and service interface definitions between the service client (`service-client`) and server (`service-server`). It includes binary protocol-based message encoding/decoding, automatic message chunking for large payloads, event system types, and service interfaces for ORM and auto-update.
 
 ## Installation
 
@@ -15,46 +15,48 @@ pnpm add @simplysm/service-common
 ### Module Structure
 
 | Module Path | Description |
-|-----------|------|
+|-------------|-------------|
 | `protocol/protocol.types` | Protocol constants, message type definitions |
-| `protocol/service-protocol` | Message encoding/decoding class |
-| `service-types/orm-service.types` | ORM service interface and DB connection options |
-| `service-types/auto-update-service.types` | Auto-update service interface |
-| `types` | `ServiceUploadResult` |
-| `define-event` | `defineEvent`, `ServiceEventDef` |
+| `protocol/service-protocol` | `ServiceProtocol` interface, `ServiceMessageDecodeResult` type, `createServiceProtocol()` factory |
+| `service-types/orm-service.types` | `OrmService` interface and `DbConnOptions` type |
+| `service-types/auto-update-service.types` | `AutoUpdateService` interface |
+| `types` | `ServiceUploadResult` interface |
+| `define-event` | `defineEvent()` function, `ServiceEventDef` interface |
 
-## ServiceProtocol
+## Protocol
 
-The core interface for encoding/decoding messages into binary format. Created via the `createServiceProtocol()` factory function. Messages exceeding 3MB are automatically split into 300KB chunks, and the receiving side automatically assembles the chunks to restore the original message.
+### ServiceProtocol
 
-### Binary Header Structure
+The core interface for encoding and decoding messages in binary format. Created via the `createServiceProtocol()` factory function. Messages exceeding 3MB are automatically split into 300KB chunks, and the receiving side automatically assembles the chunks to restore the original message.
 
-Each chunk consists of a 28-byte header and body (Big Endian).
+#### Binary Header Structure
+
+Each chunk consists of a 28-byte header followed by a JSON body (Big Endian).
 
 | Offset | Size | Field | Description |
-|--------|------|------|------|
+|--------|------|-------|-------------|
 | 0 | 16 bytes | UUID | Message identifier (binary) |
 | 16 | 8 bytes | TotalSize | Total message size (uint64) |
 | 24 | 4 bytes | Index | Chunk index (uint32) |
 
-### API
+#### API
 
 | Method | Return Type | Description |
-|--------|-----------|------|
-| `encode(uuid, message)` | `{ chunks: Bytes[]; totalSize: number }` | Encodes the message and automatically splits if necessary |
-| `decode<T>(bytes)` | `ServiceMessageDecodeResult<T>` | Decodes binary chunks and automatically assembles split messages |
+|--------|-------------|-------------|
+| `encode(uuid, message)` | `{ chunks: Bytes[]; totalSize: number }` | Encodes the message and automatically splits into chunks if it exceeds `SPLIT_MESSAGE_SIZE` |
+| `decode<TMessage extends ServiceMessage>(bytes)` | `ServiceMessageDecodeResult<TMessage>` | Decodes binary chunks and automatically assembles split messages |
 | `dispose()` | `void` | Releases the GC timer of the internal chunk accumulator. Must be called when the instance is no longer used |
 
-### Decode Result Type
+#### ServiceMessageDecodeResult
 
-`ServiceMessageDecodeResult<T>` is a union type with two states.
+`ServiceMessageDecodeResult<TMessage extends ServiceMessage>` is a union type with two states.
 
 | `type` | Fields | Description |
-|--------|------|------|
-| `"complete"` | `uuid`, `message: T` | All chunks received and message assembly complete |
-| `"progress"` | `uuid`, `totalSize`, `completedSize` | Split message in progress (only some chunks arrived) |
+|--------|--------|-------------|
+| `"complete"` | `uuid: string`, `message: TMessage` | All chunks received and message assembly complete |
+| `"progress"` | `uuid: string`, `totalSize: number`, `completedSize: number` | Split message in progress (only some chunks have arrived) |
 
-### Usage Example
+#### Usage Example
 
 ```typescript
 import { createServiceProtocol } from "@simplysm/service-common";
@@ -86,7 +88,7 @@ for (const chunk of chunks) {
 protocol.dispose();
 ```
 
-## Protocol Constants (PROTOCOL_CONFIG)
+### PROTOCOL_CONFIG
 
 A constant object that controls protocol behavior.
 
@@ -95,80 +97,80 @@ import { PROTOCOL_CONFIG } from "@simplysm/service-common";
 ```
 
 | Constant | Value | Description |
-|------|----|------|
+|----------|-------|-------------|
 | `MAX_TOTAL_SIZE` | 100MB (104,857,600 bytes) | Maximum size for a single message. `ArgumentError` thrown if exceeded |
-| `SPLIT_MESSAGE_SIZE` | 3MB (3,145,728 bytes) | Chunking threshold. Automatically split if this size is exceeded |
+| `SPLIT_MESSAGE_SIZE` | 3MB (3,145,728 bytes) | Chunking threshold. Messages larger than this are automatically split |
 | `CHUNK_SIZE` | 300KB (307,200 bytes) | Body size of each chunk when split |
 | `GC_INTERVAL` | 10s (10,000ms) | Garbage collection cycle for incomplete messages |
 | `EXPIRE_TIME` | 60s (60,000ms) | Expiration time for incomplete messages. Removed from memory if exceeded |
 
-## Message Types
+### Message Types
 
 Type definitions for messages exchanged between client and server. `ServiceMessage` is a union of all message types.
 
-### Classification by Message Direction
+#### Classification by Message Direction
 
 | Union Type | Direction | Included Messages |
-|------------|------|------------|
+|------------|-----------|-------------------|
 | `ServiceClientMessage` | Client -> Server | Request, Auth, event-related messages |
 | `ServiceServerMessage` | Server -> Client | Reload, Response, Error, Event |
 | `ServiceServerRawMessage` | Server -> Client (raw) | Progress + `ServiceServerMessage` |
 | `ServiceMessage` | Bidirectional (all) | Union of all message types |
 
-### Individual Message Types
+#### Individual Message Types
 
-#### System Messages
+##### System Messages
 
 | Type | `name` | Direction | `body` Type | Description |
-|------|--------|------|-------------|------|
+|------|--------|-----------|-------------|-------------|
 | `ServiceReloadMessage` | `"reload"` | Server -> Client | `{ clientName: string \| undefined; changedFileSet: Set<string> }` | Client reload command |
 | `ServiceProgressMessage` | `"progress"` | Server -> Client | `{ totalSize: number; completedSize: number }` | Split message reception progress |
-| `ServiceErrorMessage` | `"error"` | Server -> Client | `{ name, message, code, stack?, detail?, cause? }` | Error notification |
+| `ServiceErrorMessage` | `"error"` | Server -> Client | `{ name: string; message: string; code: string; stack?: string; detail?: unknown; cause?: unknown }` | Error notification |
 | `ServiceAuthMessage` | `"auth"` | Client -> Server | `string` (token) | Authentication token transmission |
 
-#### Service Method Call Messages
+##### Service Method Call Messages
 
 | Type | `name` | Direction | `body` Type | Description |
-|------|--------|------|-------------|------|
-| `ServiceRequestMessage` | `` `${service}.${method}` `` | Client -> Server | `unknown[]` (parameter array) | RPC method call request |
-| `ServiceResponseMessage` | `"response"` | Server -> Client | `unknown` (return value) | Method call response |
+|------|--------|-----------|-------------|-------------|
+| `ServiceRequestMessage` | `` `${string}.${string}` `` | Client -> Server | `unknown[]` (parameter array) | RPC method call request |
+| `ServiceResponseMessage` | `"response"` | Server -> Client | `unknown \| undefined` (optional return value) | Method call response |
 
-#### Event Messages
+##### Event Messages
 
 | Type | `name` | Direction | `body` Type | Description |
-|------|--------|------|-------------|------|
-| `ServiceAddEventListenerMessage` | `"evt:add"` | Client -> Server | `{ key, name, info }` | Event listener registration |
-| `ServiceRemoveEventListenerMessage` | `"evt:remove"` | Client -> Server | `{ key }` | Event listener removal |
-| `ServiceGetEventListenerInfosMessage` | `"evt:gets"` | Client -> Server | `{ name }` | Event listener info list query |
-| `ServiceEmitEventMessage` | `"evt:emit"` | Client -> Server | `{ keys, data }` | Event emission |
-| `ServiceEventMessage` | `"evt:on"` | Server -> Client | `{ keys, data }` | Event notification |
+|------|--------|-----------|-------------|-------------|
+| `ServiceAddEventListenerMessage` | `"evt:add"` | Client -> Server | `{ key: string; name: string; info: unknown }` | Event listener registration |
+| `ServiceRemoveEventListenerMessage` | `"evt:remove"` | Client -> Server | `{ key: string }` | Event listener removal |
+| `ServiceGetEventListenerInfosMessage` | `"evt:gets"` | Client -> Server | `{ name: string }` | Event listener info list query |
+| `ServiceEmitEventMessage` | `"evt:emit"` | Client -> Server | `{ keys: string[]; data: unknown }` | Event emission |
+| `ServiceEventMessage` | `"evt:on"` | Server -> Client | `{ keys: string[]; data: unknown }` | Event notification |
 
 ## defineEvent / ServiceEventDef
 
-A function for defining event types. Events are used to publish real-time notifications from server to client.
+A function for defining type-safe service events. Events are used to publish real-time notifications from server to client.
 
 ### API
 
 ```typescript
 function defineEvent<TInfo = unknown, TData = unknown>(
-  eventName: string
+  eventName: string,
 ): ServiceEventDef<TInfo, TData>
 ```
 
 ### Type Parameters
 
 | Parameter | Description |
-|---------|------|
+|-----------|-------------|
 | `TInfo` | Additional information type for listener filtering |
 | `TData` | Data type passed when the event is emitted |
 
 ### ServiceEventDef Properties
 
 | Property | Type | Description |
-|------|------|------|
+|----------|------|-------------|
 | `eventName` | `string` | Unique event identifier |
-| `$info` | `TInfo` (declare) | For type extraction. Not used at runtime |
-| `$data` | `TData` (declare) | For type extraction. Not used at runtime |
+| `$info` | `TInfo` (declare) | For TypeScript type extraction only. Not used at runtime |
+| `$data` | `TData` (declare) | For TypeScript type extraction only. Not used at runtime |
 
 ### Usage Example
 
@@ -195,9 +197,13 @@ await client.addEventListener(
 
 An interface representing file upload results.
 
+```typescript
+import { ServiceUploadResult } from "@simplysm/service-common";
+```
+
 | Field | Type | Description |
-|------|------|------|
-| `path` | `string` | Storage path on server |
+|-------|------|-------------|
+| `path` | `string` | Storage path on the server |
 | `filename` | `string` | Original filename |
 | `size` | `number` | File size (bytes) |
 
@@ -207,24 +213,32 @@ Service interface definitions that are implemented on the server side and called
 
 ### OrmService
 
-Defines database connection, transaction management, and query execution capabilities. Supports MySQL, MSSQL, PostgreSQL.
+Defines database connection, transaction management, and query execution capabilities. Supports MySQL, MSSQL, and PostgreSQL.
+
+```typescript
+import type { OrmService } from "@simplysm/service-common";
+```
 
 | Method | Parameters | Return Type | Description |
-|--------|---------|-----------|------|
-| `getInfo` | `opt: DbConnOptions & { configName: string }` | `Promise<{ dialect, database?, schema? }>` | Query DB connection info |
+|--------|------------|-------------|-------------|
+| `getInfo` | `opt: DbConnOptions & { configName: string }` | `Promise<{ dialect: Dialect; database?: string; schema?: string }>` | Query DB connection info |
 | `connect` | `opt: Record<string, unknown>` | `Promise<number>` | Create DB connection, return connection ID |
 | `close` | `connId: number` | `Promise<void>` | Close DB connection |
-| `beginTransaction` | `connId, isolationLevel?` | `Promise<void>` | Begin transaction |
+| `beginTransaction` | `connId: number, isolationLevel?: IsolationLevel` | `Promise<void>` | Begin transaction |
 | `commitTransaction` | `connId: number` | `Promise<void>` | Commit transaction |
 | `rollbackTransaction` | `connId: number` | `Promise<void>` | Rollback transaction |
-| `executeParametrized` | `connId, query, params?` | `Promise<unknown[][]>` | Execute parameterized query |
-| `executeDefs` | `connId, defs: QueryDef[], options?: (ResultMeta \| undefined)[]` | `Promise<unknown[][]>` | Execute queries with `QueryDef` array |
-| `bulkInsert` | `connId, tableName, columnDefs: Record<string, ColumnMeta>, records` | `Promise<void>` | Bulk data insertion |
+| `executeParametrized` | `connId: number, query: string, params?: unknown[]` | `Promise<unknown[][]>` | Execute a parameterized query |
+| `executeDefs` | `connId: number, defs: QueryDef[], options?: (ResultMeta \| undefined)[]` | `Promise<unknown[][]>` | Execute queries defined as `QueryDef` array |
+| `bulkInsert` | `connId: number, tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]` | `Promise<void>` | Bulk data insertion |
 
 #### DbConnOptions
 
+```typescript
+import type { DbConnOptions } from "@simplysm/service-common";
+```
+
 | Field | Type | Description |
-|------|------|------|
+|-------|------|-------------|
 | `configName?` | `string` | Config name to reference in server settings |
 | `config?` | `Record<string, unknown>` | Directly passed connection config |
 
@@ -232,18 +246,23 @@ Defines database connection, transaction management, and query execution capabil
 
 Defines a service for querying the latest version information of a client application.
 
+```typescript
+import type { AutoUpdateService } from "@simplysm/service-common";
+```
+
 | Method | Parameters | Return Type | Description |
-|--------|---------|-----------|------|
-| `getLastVersion` | `platform: string` | `Promise<{ version: string; downloadPath: string } \| undefined>` | Query latest version info for the specified platform. Returns `undefined` if none |
+|--------|------------|-------------|-------------|
+| `getLastVersion` | `platform: string` | `Promise<{ version: string; downloadPath: string } \| undefined>` | Query latest version info for the specified platform. Returns `undefined` if none exists |
 
-Pass values like `"win32"`, `"darwin"`, `"linux"` to `platform`.
+Pass values like `"win32"`, `"darwin"`, or `"linux"` to `platform`.
 
 ## Caveats
 
-- `ServiceProtocol` instances are created via `createServiceProtocol()` factory function and internally use `LazyGcMap` to manage incomplete split messages. After use, you must call `dispose()` to release the GC timer.
+- `ServiceProtocol` instances are created via the `createServiceProtocol()` factory function and internally use `LazyGcMap` to manage incomplete split messages. After use, you must call `dispose()` to release the GC timer.
 - Encoding or decoding messages exceeding `PROTOCOL_CONFIG.MAX_TOTAL_SIZE` (100MB) will throw an `ArgumentError`.
-- Passing binary data less than 28 bytes during decoding will throw an `ArgumentError`.
-- Service interfaces (`OrmService`, `AutoUpdateService`, etc.) only provide type definitions. Actual implementations are handled by the `@simplysm/service-server` package.
+- Passing binary data less than 28 bytes to `decode()` will throw an `ArgumentError`.
+- `ServiceResponseMessage.body` is optional (`body?: unknown`) — the server may return `undefined` for void methods.
+- Service interfaces (`OrmService`, `AutoUpdateService`) only provide type definitions. Actual implementations are handled by the `@simplysm/service-server` package.
 - The `$info` and `$data` properties of `ServiceEventDef` are declared with `declare` and do not exist at runtime; they are only used for TypeScript type extraction.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-common",
-  "version": "13.0.29",
+  "version": "13.0.31",
   "description": "심플리즘 패키지 - 서비스 모듈 (common)",
   "author": "김석래",
   "license": "Apache-2.0",
@@ -18,7 +18,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@simplysm/core-common": "13.0.29",
-    "@simplysm/orm-common": "13.0.29"
+    "@simplysm/core-common": "13.0.31",
+    "@simplysm/orm-common": "13.0.31"
   }
 }