@simplysm/service-common 14.0.22 → 14.0.24

package/package.json

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

package/README.md

@@ -1,114 +0,0 @@
-# @simplysm/service-common
-
-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`.
-
-## Installation
-
-```bash
-npm install @simplysm/service-common
-```
-
-## 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],
-});
-
-// Decode received bytes
-const result = protocol.decode(receivedBytes);
-if (result.type === "complete") {
-  console.log(result.message);
-} else {
-  console.log(`Progress: ${result.completedSize}/${result.totalSize}`);
-}
-
-// Dispose when done
-protocol.dispose();
-```
-
-### Defining a Typed Event
-
-```typescript
-import { defineEvent } from "@simplysm/service-common";
-
-const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
-
-// Server: emit event
-await server.emitEvent(OrderUpdated, (info) => info.orderId === 123, { status: "shipped" });
-
-// Client: subscribe
-await client.addListener(OrderUpdated, { orderId: 123 }, async (data) => {
-  console.log(data.status);
-});
-```

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

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

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

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

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

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

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