@simplysm/service-common 14.0.51 → 14.0.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-common",
-  "version": "14.0.51",
+  "version": "14.0.53",
   "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/core-common": "14.0.51",
-    "@simplysm/orm-common": "14.0.51"
+    "@simplysm/core-common": "14.0.53",
+    "@simplysm/orm-common": "14.0.53"
   }
 }

package/README.md

@@ -1,142 +0,0 @@
-# @simplysm/service-common
-
-서비스 클라이언트와 서버가 공유하는 바이너리 프로토콜, 메시지 타입, 서비스 인터페이스, 앱 구조 정의 패키지.
-
-## 소비앱 설치 안내 (v14)
-
-v14에서는 `import type`으로 타입을 직접 가져올 수 있으므로, 이전 버전에서 클라이언트-서버 간 타입 공유를 위해 필요하던 중간 패키지(`@simplysm/service-common`, `@simplysm/orm-common`)는 **소비앱의 의존성으로 불필요**하다. 서버 패키지(`@simplysm/service-server`, `@simplysm/orm-node`)의 타입을 직접 import하여 사용한다.
-
-```typescript
-// v14: 서버 패키지에서 타입을 직접 import — common 패키지 의존성 불필요
-import type { ServiceMethods } from "@simplysm/service-server";
-```
-
-## Installation
-
-```bash
-npm install @simplysm/service-common
-```
-
-## API Overview
-
-### Protocol
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`PROTOCOL_CONFIG`](./docs/protocol/protocol-config.md) | const | 프로토콜 설정 상수 (최대 크기, 청킹 임계값, 청크 크기, GC 주기, 만료 시간) |
-| [`ServiceMessage`](./docs/protocol/service-message.md) | type | 양방향 메시지 유니언 (`ServiceClientMessage`, `ServiceServerMessage`, `ServiceServerRawMessage` 포함) |
-| [`ServiceProgressMessage`](./docs/protocol/service-progress-message.md) | interface | 청크 수신 진행 상태 알림 |
-| [`ServiceErrorMessage`](./docs/protocol/service-error-message.md) | interface | 서버 에러 알림 |
-| [`ServiceAuthMessage`](./docs/protocol/service-auth-message.md) | interface | 클라이언트 인증 메시지 (토큰) |
-| [`ServiceRequestMessage`](./docs/protocol/service-request-message.md) | interface | 서비스 메서드 요청 |
-| [`ServiceResponseMessage`](./docs/protocol/service-response-message.md) | interface | 서비스 메서드 응답 |
-| [`ServiceAddEventListenerMessage`](./docs/protocol/service-add-event-listener-message.md) | interface | 이벤트 리스너 추가 요청 |
-| [`ServiceRemoveEventListenerMessage`](./docs/protocol/service-remove-event-listener-message.md) | interface | 이벤트 리스너 제거 요청 |
-| [`ServiceGetEventListenerInfosMessage`](./docs/protocol/service-get-event-listener-infos-message.md) | interface | 이벤트 리스너 정보 목록 요청 |
-| [`ServiceEmitEventMessage`](./docs/protocol/service-emit-event-message.md) | interface | 이벤트 발생 요청 |
-| [`ServiceEventMessage`](./docs/protocol/service-event-message.md) | interface | 서버 이벤트 알림 |
-| [`createServiceProtocol`](./docs/protocol/create-service-protocol.md) | function | ServiceProtocol 인스턴스 생성 팩토리 (`ServiceProtocol`, `ServiceMessageDecodeResult` 포함) |
-
-### Service Types
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`OrmService`](./docs/service-types/orm-service.md) | interface | DB 연결, 트랜잭션, 쿼리 실행 서비스 인터페이스 (`DbConnOptions` 포함) |
-| [`AutoUpdateService`](./docs/service-types/auto-update-service.md) | interface | 클라이언트 최신 버전 조회 서비스 인터페이스 |
-| [`AppStructureService`](./docs/service-types/app-structure-service.md) | interface | 앱 구조 항목 조회 서비스 인터페이스 |
-
-### Types
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`ServiceUploadResult`](./docs/types/service-upload-result.md) | interface | 파일 업로드 결과 |
-
-### App Structure
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`AppStructureItem`](./docs/app-structure/app-structure-item.md) | type | 앱 구조 항목 유니언 (`AppStructureGroupItem`, `AppStructureLeafItem`, `AppStructureSubPermission`, `FlatPermission` 포함) |
-| [`isUsableModules`](./docs/app-structure/is-usable-modules.md) | function | 단일 항목의 모듈 접근 가능 여부 판단 |
-| [`isUsableModulesChain`](./docs/app-structure/is-usable-modules-chain.md) | function | 모듈 체인 전체의 접근 가능 여부 판단 |
-| [`getFlatPermissions`](./docs/app-structure/get-flat-permissions.md) | function | 앱 구조 트리를 플래트닝하여 권한 배열 반환 |
-
-### Events
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`defineEvent`](./docs/events/define-event.md) | function | 타입 안전 이벤트를 정의하는 팩토리 함수 (`ServiceEventDef` 포함) |
-
-## Usage Examples
-
-### 프로토콜 인코딩/디코딩
-
-```typescript
-import { createServiceProtocol } from "@simplysm/service-common";
-
-const protocol = createServiceProtocol();
-
-// 메시지 인코딩 (3MB 초과 시 자동 청킹)
-const { chunks, totalSize } = protocol.encode(uuid, {
-  name: "OrmService.connect",
-  body: [{ configName: "default" }],
-});
-
-// 메시지 디코딩 (청크 자동 재조립)
-for (const chunk of chunks) {
-  const result = protocol.decode(chunk);
-  if (result.type === "complete") {
-    // result.message: 재조립된 메시지
-  }
-}
-
-// 사용 후 반드시 해제
-protocol.dispose();
-```
-
-### 타입 안전 이벤트 정의
-
-```typescript
-import { defineEvent } from "@simplysm/service-common";
-
-// 서버에서 이벤트 정의 + 타입 export
-export const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
-
-// 서버에서 이벤트 발생 (제네릭 타입 파라미터 + 문자열 이름 패턴)
-await server.emitEvent<typeof OrderUpdated>("OrderUpdated", (info) => info.orderId === 123, { status: "shipped" });
-
-// 클라이언트에서 구독 (import type으로 타입만 가져옴)
-import type { OrderUpdated } from "@server-package";
-await client.addListener<typeof OrderUpdated>("OrderUpdated", { orderId: 123 }, async (data) => {
-  // data.status는 string으로 타입 추론됨
-});
-```
-
-### 앱 구조 권한 플래트닝
-
-```typescript
-import { getFlatPermissions, isUsableModules } from "@simplysm/service-common";
-import type { AppStructureItem } from "@simplysm/service-common";
-
-const items: AppStructureItem<string>[] = [
-  {
-    code: "admin",
-    title: "관리",
-    children: [
-      { code: "user", title: "사용자", perms: ["use", "edit"] },
-    ],
-  },
-  {
-    code: "report",
-    title: "리포트",
-    modules: ["moduleA"],
-    perms: ["use"],
-  },
-];
-
-// 활성 모듈 기준으로 권한 플래트닝
-const perms = getFlatPermissions(items, ["moduleA"]);
-// [{ codeChain: ["admin", "user", "use"], ... }, { codeChain: ["admin", "user", "edit"], ... }, ...]
-
-// 개별 모듈 접근 가능 여부 확인
-const canAccess = isUsableModules(["moduleA", "moduleB"], undefined, ["moduleA"]); // true (OR 조건)
-```

package/docs/app-structure/app-structure-item.md

@@ -1,107 +0,0 @@
-# AppStructureItem
-
-앱 구조 항목 유니언 타입. `children` 필드 유무로 그룹(`AppStructureGroupItem`)과 리프(`AppStructureLeafItem`)를 구분한다.
-
-```typescript
-export type AppStructureItem<TModule = unknown> =
-  | AppStructureGroupItem<TModule>
-  | AppStructureLeafItem<TModule>;
-```
-
-`TModule` 제네릭은 모듈 식별자 타입이다 (일반적으로 `string`).
-
-## Related Types
-
-### `AppStructureGroupItem`
-
-자식을 가진 그룹 메뉴 항목. `children` 필드로 하위 항목을 재귀적으로 포함한다.
-
-```typescript
-export interface AppStructureGroupItem<TModule> {
-  code: string;
-  title: string;
-  modules?: TModule[];
-  requiredModules?: TModule[];
-  icon?: string;
-  children: AppStructureItem<TModule>[];
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `code` | `string` | 항목 코드 (권한 코드 체인에 사용) |
-| `title` | `string` | 표시 이름 |
-| `modules` | `TModule[]?` | 접근에 필요한 모듈 목록 (OR 조건: 하나라도 있으면 접근 가능) |
-| `requiredModules` | `TModule[]?` | 접근에 필수인 모듈 목록 (AND 조건: 모두 있어야 접근 가능) |
-| `icon` | `string?` | 아이콘 식별자 |
-| `children` | `AppStructureItem<TModule>[]` | 하위 메뉴 항목 배열 |
-
-### `AppStructureLeafItem`
-
-말단 메뉴 항목. 실제 페이지 URL과 권한(`perms`)을 가진다.
-
-```typescript
-export interface AppStructureLeafItem<TModule> {
-  code: string;
-  title: string;
-  modules?: TModule[];
-  requiredModules?: TModule[];
-  perms?: ("use" | "edit")[];
-  subPerms?: AppStructureSubPermission<TModule>[];
-  icon?: string;
-  url?: string;
-  isNotMenu?: boolean;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `code` | `string` | 항목 코드 |
-| `title` | `string` | 표시 이름 |
-| `modules` | `TModule[]?` | 접근에 필요한 모듈 목록 (OR 조건) |
-| `requiredModules` | `TModule[]?` | 접근에 필수인 모듈 목록 (AND 조건) |
-| `perms` | `("use" \| "edit")[]?` | 이 항목에 부여 가능한 권한 종류 |
-| `subPerms` | `AppStructureSubPermission<TModule>[]?` | 하위 권한 정의 배열 |
-| `icon` | `string?` | 아이콘 식별자 |
-| `url` | `string?` | 페이지 URL |
-| `isNotMenu` | `boolean?` | `true`이면 메뉴에 표시하지 않음 |
-
-### `AppStructureSubPermission`
-
-리프 항목의 하위 권한 정의. 각 하위 권한도 모듈 접근 제어를 가진다.
-
-```typescript
-export interface AppStructureSubPermission<TModule> {
-  code: string;
-  title: string;
-  modules?: TModule[];
-  requiredModules?: TModule[];
-  perms: ("use" | "edit")[];
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `code` | `string` | 하위 권한 코드 |
-| `title` | `string` | 하위 권한 표시 이름 |
-| `modules` | `TModule[]?` | 접근에 필요한 모듈 목록 (OR 조건) |
-| `requiredModules` | `TModule[]?` | 접근에 필수인 모듈 목록 (AND 조건) |
-| `perms` | `("use" \| "edit")[]` | 부여 가능한 권한 종류 |
-
-### `FlatPermission`
-
-트리를 플래트닝한 권한 결과. [`getFlatPermissions`](./get-flat-permissions.md)의 반환 타입이다.
-
-```typescript
-export interface FlatPermission<TModule = unknown> {
-  titleChain: string[];
-  codeChain: string[];
-  modulesChain: TModule[][];
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `titleChain` | `string[]` | 루트부터 현재 권한까지의 표시 이름 체인 (예: `["관리", "사용자"]`) |
-| `codeChain` | `string[]` | 루트부터 현재 권한까지의 코드 체인 (예: `["admin", "user", "use"]`) |
-| `modulesChain` | `TModule[][]` | 각 레벨에서 필요한 모듈 목록의 체인 |

package/docs/app-structure/get-flat-permissions.md

@@ -1,57 +0,0 @@
-# getFlatPermissions
-
-앱 구조 트리를 BFS로 순회하며 모듈 조건을 필터링하여 [`FlatPermission`](./app-structure-item.md)`[]`으로 플래트닝한다.
-
-```typescript
-export function getFlatPermissions<TModule>(
-  items: AppStructureItem<TModule>[],
-  usableModules: TModule[] | undefined,
-): FlatPermission<TModule>[];
-```
-
-## Parameters
-
-| Param | Type | Description |
-|-------|------|-------------|
-| `items` | `AppStructureItem<TModule>[]` | 앱 구조 트리의 최상위 항목 배열 |
-| `usableModules` | `TModule[] \| undefined` | 사용자가 보유한 활성 모듈 목록. `undefined`이면 모듈 조건이 없는 항목만 포함 |
-
-## Returns
-
-`FlatPermission<TModule>[]` — 모듈 조건을 만족하는 모든 권한의 플랫 목록.
-
-처리 로직:
-1. BFS로 트리를 순회하며 각 레벨의 `modules`(OR)와 `requiredModules`(AND) 조건을 체크
-2. 조건 미충족 항목은 하위 트리 전체를 건너뜀
-3. `AppStructureLeafItem`의 `perms`를 `codeChain`에 추가하여 `FlatPermission` 생성
-4. `subPerms`도 개별 모듈 조건을 체크하여 `FlatPermission`으로 변환
-
-## Usage
-
-```typescript
-import { getFlatPermissions } from "@simplysm/service-common";
-import type { AppStructureItem } from "@simplysm/service-common";
-
-const items: AppStructureItem<string>[] = [
-  {
-    code: "admin",
-    title: "관리",
-    children: [
-      { code: "user", title: "사용자", perms: ["use", "edit"] },
-    ],
-  },
-  {
-    code: "report",
-    title: "리포트",
-    modules: ["moduleA"],
-    perms: ["use"],
-  },
-];
-
-const perms = getFlatPermissions(items, ["moduleA"]);
-// [
-//   { titleChain: ["관리", "사용자"], codeChain: ["admin", "user", "use"], modulesChain: [] },
-//   { titleChain: ["관리", "사용자"], codeChain: ["admin", "user", "edit"], modulesChain: [] },
-//   { titleChain: ["리포트"], codeChain: ["report", "use"], modulesChain: [["moduleA"]] },
-// ]
-```

package/docs/app-structure/is-usable-modules-chain.md

@@ -1,23 +0,0 @@
-# isUsableModulesChain
-
-모듈 체인 전체의 접근 가능 여부를 판단한다. 트리의 각 레벨에서 모듈 조건을 모두 만족해야 한다.
-
-```typescript
-export function isUsableModulesChain<TModule>(
-  modulesChain: TModule[][],
-  requiredModulesChain: TModule[][],
-  usableModules: TModule[] | undefined,
-): boolean;
-```
-
-## Parameters
-
-| Param | Type | Description |
-|-------|------|-------------|
-| `modulesChain` | `TModule[][]` | 각 레벨의 OR 조건 모듈 배열 |
-| `requiredModulesChain` | `TModule[][]` | 각 레벨의 AND 조건 모듈 배열 |
-| `usableModules` | `TModule[] \| undefined` | 사용자가 보유한 활성 모듈 목록 |
-
-## Returns
-
-`boolean` — 모든 레벨의 조건을 만족하면 `true`. 하나라도 실패하면 `false`.

package/docs/app-structure/is-usable-modules.md

@@ -1,42 +0,0 @@
-# isUsableModules
-
-단일 항목의 모듈 접근 가능 여부를 판단한다.
-
-```typescript
-export function isUsableModules<TModule>(
-  modules: TModule[] | undefined,
-  requiredModules: TModule[] | undefined,
-  usableModules: TModule[] | undefined,
-): boolean;
-```
-
-## Parameters
-
-| Param | Type | Description |
-|-------|------|-------------|
-| `modules` | `TModule[] \| undefined` | OR 조건 모듈 목록. 하나라도 `usableModules`에 포함되면 통과 |
-| `requiredModules` | `TModule[] \| undefined` | AND 조건 모듈 목록. 모두 `usableModules`에 포함되어야 통과 |
-| `usableModules` | `TModule[] \| undefined` | 사용자가 보유한 활성 모듈 목록 |
-
-## Returns
-
-`boolean` — `modules`와 `requiredModules` 조건을 모두 만족하면 `true`.
-
-- `modules`가 `undefined`이거나 빈 배열이면 OR 조건은 자동 통과
-- `requiredModules`가 `undefined`이거나 빈 배열이면 AND 조건은 자동 통과
-- `usableModules`가 `undefined`이면 `modules`가 있을 때 `false`
-
-## Usage
-
-```typescript
-import { isUsableModules } from "@simplysm/service-common";
-
-// OR 조건: moduleA 또는 moduleB 중 하나라도 있으면 true
-isUsableModules(["moduleA", "moduleB"], undefined, ["moduleA"]); // true
-
-// AND 조건: 모두 있어야 true
-isUsableModules(undefined, ["moduleA", "moduleB"], ["moduleA"]); // false
-
-// 모듈 없음: 자동 통과
-isUsableModules(undefined, undefined, undefined); // true
-```

package/docs/events/define-event.md

@@ -1,68 +0,0 @@
-# defineEvent
-
-타입 안전한 서비스 이벤트를 정의하는 팩토리 함수.
-
-```typescript
-export function defineEvent<TInfo = unknown, TData = unknown>(
-  eventName: string,
-): ServiceEventDef<TInfo, TData>;
-```
-
-## Parameters
-
-| Param | Type | Description |
-|-------|------|-------------|
-| `eventName` | `string` | 이벤트 이름 (고유해야 함) |
-
-| Type Parameter | Default | Description |
-|---------------|---------|-------------|
-| `TInfo` | `unknown` | 이벤트 필터링 조건의 타입. 구독 시 필터로 사용 |
-| `TData` | `unknown` | 이벤트 페이로드의 타입. 이벤트 발생/수신 시 데이터 타입 |
-
-## Returns
-
-`ServiceEventDef<TInfo, TData>` — 이벤트 정의 인스턴스.
-
-## Related Types
-
-### `ServiceEventDef`
-
-`defineEvent()`로 생성된 이벤트 정의. `$info`와 `$data`는 런타임에서 사용되지 않는 타입 전용 마커다.
-
-```typescript
-export interface ServiceEventDef<TInfo = unknown, TData = unknown> {
-  eventName: string;
-  readonly $info: TInfo;
-  readonly $data: TData;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `eventName` | `string` | 이벤트 이름 |
-| `$info` | `TInfo` | 타입 추출 전용 마커 (런타임에서 사용하지 않음). 이벤트 필터링 조건 타입 |
-| `$data` | `TData` | 타입 추출 전용 마커 (런타임에서 사용하지 않음). 이벤트 페이로드 타입 |
-
-## Usage
-
-```typescript
-import { defineEvent } from "@simplysm/service-common";
-
-// 서버에서 이벤트 정의 + 타입 export
-export const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
-
-// 서버에서 이벤트 발생 — getEvent() 프록시 방식 (권장)
-const orderEvt = server.getEvent<typeof OrderUpdated>("OrderUpdated");
-await orderEvt.emit((info) => info.orderId === 123, { status: "shipped" });
-
-// 클라이언트에서 구독 (import type으로 타입만 가져옴)
-import type { OrderUpdated } from "@server-package";
-const orderEvt = client.getEvent<typeof OrderUpdated>("OrderUpdated");
-const key = await orderEvt.addListener({ orderId: 123 }, async (data) => {
-  // data.status는 string으로 타입 추론됨
-});
-
-// 직접 호출 방식 (하위 호환)
-await server.emitEvent<typeof OrderUpdated>("OrderUpdated", (info) => info.orderId === 123, { status: "shipped" });
-await client.addListener<typeof OrderUpdated>("OrderUpdated", { orderId: 123 }, async (data) => { /* ... */ });
-```

package/docs/protocol/create-service-protocol.md

@@ -1,93 +0,0 @@
-# createServiceProtocol
-
-ServiceProtocol 인스턴스를 생성하는 팩토리 함수.
-
-```typescript
-export function createServiceProtocol(): ServiceProtocol;
-```
-
-내부에 `LazyGcMap` 기반 청크 누적기를 캡슐화한다. 미완성 메시지는 60초 후 GC로 자동 정리된다. 사용 후 반드시 `dispose()`를 호출하여 GC 타이머를 해제해야 한다.
-
-## Returns
-
-`ServiceProtocol` — 인코딩/디코딩/해제 메서드를 포함한 프로토콜 인스턴스.
-
-## Related Types
-
-### `ServiceProtocol`
-
-바이너리 프로토콜 V2 인코더/디코더 인터페이스.
-
-```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 }` | 메시지를 인코딩한다. 3MB 초과 시 300KB 청크로 자동 분할. `totalSize` > 100MB이면 `ArgumentError` 발생 |
-| `decode` | `bytes: Bytes` | `ServiceMessageDecodeResult<T>` | 청크를 디코딩한다. 청크가 모두 도착하면 `complete`, 아니면 `progress` 반환 |
-| `dispose` | 없음 | `void` | 내부 GC 타이머와 청크 누적기를 해제한다. 사용 후 반드시 호출 |
-
-헤더 구조 (28바이트, Big Endian):
-
-| Offset | Size | Field |
-|--------|------|-------|
-| 0 | 16 | UUID (바이너리) |
-| 16 | 8 | TotalSize (uint64, 상위 4바이트 = 0) |
-| 24 | 4 | Index (uint32) |
-
-### `ServiceMessageDecodeResult`
-
-메시지 디코딩 결과 유니언 타입. `type` 필드로 분기한다.
-
-```typescript
-export type ServiceMessageDecodeResult<TMessage extends ServiceMessage> =
-  | { type: "complete"; uuid: string; message: TMessage }
-  | { type: "progress"; uuid: string; totalSize: number; completedSize: number };
-```
-
-**Variant: `complete`** — 모든 청크가 도착하여 메시지 재조립이 완료된 상태.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `type` | `"complete"` | discriminant |
-| `uuid` | `string` | 메시지 UUID |
-| `message` | `TMessage` | 재조립된 메시지 |
-
-**Variant: `progress`** — 청크 메시지 수신 진행 중.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `type` | `"progress"` | discriminant |
-| `uuid` | `string` | 메시지 UUID |
-| `totalSize` | `number` | 전체 크기 (바이트) |
-| `completedSize` | `number` | 수신 완료된 크기 (바이트) |
-
-## Usage
-
-```typescript
-import { createServiceProtocol } from "@simplysm/service-common";
-
-const protocol = createServiceProtocol();
-
-// 메시지 인코딩 (3MB 초과 시 자동 청킹)
-const { chunks, totalSize } = protocol.encode(uuid, {
-  name: "OrmService.connect",
-  body: [{ configName: "default" }],
-});
-
-// 메시지 디코딩 (청크 자동 재조립)
-for (const chunk of chunks) {
-  const result = protocol.decode(chunk);
-  if (result.type === "complete") {
-    // result.message: 재조립된 메시지
-  }
-}
-
-// 사용 후 반드시 해제
-protocol.dispose();
-```

package/docs/protocol/protocol-config.md

@@ -1,21 +0,0 @@
-# PROTOCOL_CONFIG
-
-서비스 프로토콜 설정 상수.
-
-```typescript
-export const PROTOCOL_CONFIG = {
-  MAX_TOTAL_SIZE: 100 * 1024 * 1024,
-  SPLIT_MESSAGE_SIZE: 3 * 1024 * 1024,
-  CHUNK_SIZE: 300 * 1024,
-  GC_INTERVAL: 10 * 1000,
-  EXPIRE_TIME: 60 * 1000,
-} as const;
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `MAX_TOTAL_SIZE` | `number` | 단일 메시지의 최대 허용 크기 (100MB). 초과 시 `ArgumentError` 발생 |
-| `SPLIT_MESSAGE_SIZE` | `number` | 이 크기를 초과하면 자동으로 청크 분할 (3MB) |
-| `CHUNK_SIZE` | `number` | 분할된 각 청크의 크기 (300KB) |
-| `GC_INTERVAL` | `number` | 내부 청크 누적기의 가비지 컬렉션 주기 (10초, 밀리초 단위) |
-| `EXPIRE_TIME` | `number` | 미완성 청크 메시지의 만료 시간 (60초). 이 시간 내에 모든 청크가 도착하지 않으면 제거 |

package/docs/protocol/service-add-event-listener-message.md

@@ -1,23 +0,0 @@
-# ServiceAddEventListenerMessage
-
-클라이언트가 보내는 이벤트 리스너 추가 메시지.
-
-```typescript
-export interface ServiceAddEventListenerMessage {
-  name: "evt:add";
-  body: {
-    key: string;
-    name: string;
-    info: unknown;
-  };
-}
-```
-
-## Members
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `"evt:add"` | 고정 문자열 discriminant |
-| `body.key` | `string` | 리스너 키 (UUID). `ServiceRemoveEventListenerMessage`에서 사용 |
-| `body.name` | `string` | 이벤트 이름 (`ServiceEventDef.eventName`) |
-| `body.info` | `unknown` | 이벤트 발생 시 필터링을 위한 추가 리스너 정보 |

package/docs/protocol/service-auth-message.md

@@ -1,17 +0,0 @@
-# ServiceAuthMessage
-
-클라이언트가 보내는 인증 메시지.
-
-```typescript
-export interface ServiceAuthMessage {
-  name: "auth";
-  body: string;
-}
-```
-
-## Members
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `"auth"` | 고정 문자열 discriminant |
-| `body` | `string` | 인증 토큰 |

package/docs/protocol/service-emit-event-message.md

@@ -1,21 +0,0 @@
-# ServiceEmitEventMessage
-
-클라이언트가 보내는 이벤트 발생 메시지.
-
-```typescript
-export interface ServiceEmitEventMessage {
-  name: "evt:emit";
-  body: {
-    keys: string[];
-    data: unknown;
-  };
-}
-```
-
-## Members
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `"evt:emit"` | 고정 문자열 discriminant |
-| `body.keys` | `string[]` | 대상 리스너 키 목록 |
-| `body.data` | `unknown` | 이벤트 데이터 |

package/docs/protocol/service-error-message.md

@@ -1,29 +0,0 @@
-# ServiceErrorMessage
-
-서버가 보내는 에러 알림 메시지.
-
-```typescript
-export interface ServiceErrorMessage {
-  name: "error";
-  body: {
-    name: string;
-    message: string;
-    code: string;
-    stack?: string;
-    detail?: unknown;
-    cause?: unknown;
-  };
-}
-```
-
-## Members
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `"error"` | 고정 문자열 discriminant |
-| `body.name` | `string` | 에러 이름 (클래스명) |
-| `body.message` | `string` | 에러 메시지 |
-| `body.code` | `string` | 에러 코드 |
-| `body.stack` | `string?` | 스택 트레이스 (선택) |
-| `body.detail` | `unknown?` | 추가 상세 정보 (선택) |
-| `body.cause` | `unknown?` | 원인 에러 (선택) |

package/docs/protocol/service-event-message.md

@@ -1,21 +0,0 @@
-# ServiceEventMessage
-
-서버가 보내는 이벤트 알림 메시지.
-
-```typescript
-export interface ServiceEventMessage {
-  name: "evt:on";
-  body: {
-    keys: string[];
-    data: unknown;
-  };
-}
-```
-
-## Members
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `"evt:on"` | 고정 문자열 discriminant |
-| `body.keys` | `string[]` | 대상 리스너 키 목록 |
-| `body.data` | `unknown` | 이벤트 데이터 |

package/docs/protocol/service-get-event-listener-infos-message.md

@@ -1,19 +0,0 @@
-# ServiceGetEventListenerInfosMessage
-
-클라이언트가 보내는 이벤트 리스너 정보 목록 요청 메시지.
-
-```typescript
-export interface ServiceGetEventListenerInfosMessage {
-  name: "evt:gets";
-  body: {
-    name: string;
-  };
-}
-```
-
-## Members
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `"evt:gets"` | 고정 문자열 discriminant |
-| `body.name` | `string` | 조회할 이벤트 이름 |

package/docs/protocol/service-message.md

@@ -1,52 +0,0 @@
-# ServiceMessage
-
-모든 서비스 메시지의 유니언 타입. 클라이언트·서버 양방향 메시지를 모두 포함한다.
-
-```typescript
-export type ServiceMessage =
-  | ServiceRequestMessage
-  | ServiceAuthMessage
-  | ServiceProgressMessage
-  | ServiceResponseMessage
-  | ServiceErrorMessage
-  | ServiceAddEventListenerMessage
-  | ServiceRemoveEventListenerMessage
-  | ServiceGetEventListenerInfosMessage
-  | ServiceEmitEventMessage
-  | ServiceEventMessage;
-```
-
-## Related Types
-
-### `ServiceClientMessage`
-
-클라이언트 → 서버 메시지 유니언.
-
-```typescript
-export type ServiceClientMessage =
-  | ServiceRequestMessage
-  | ServiceAuthMessage
-  | ServiceAddEventListenerMessage
-  | ServiceRemoveEventListenerMessage
-  | ServiceGetEventListenerInfosMessage
-  | ServiceEmitEventMessage;
-```
-
-### `ServiceServerMessage`
-
-서버 → 클라이언트 메시지 유니언.
-
-```typescript
-export type ServiceServerMessage =
-  | ServiceResponseMessage
-  | ServiceErrorMessage
-  | ServiceEventMessage;
-```
-
-### `ServiceServerRawMessage`
-
-서버가 보내는 모든 메시지 (진행 상태 포함).
-
-```typescript
-export type ServiceServerRawMessage = ServiceProgressMessage | ServiceServerMessage;
-```

package/docs/protocol/service-progress-message.md

@@ -1,21 +0,0 @@
-# ServiceProgressMessage
-
-서버가 보내는 청크 수신 진행 상태 알림 메시지.
-
-```typescript
-export interface ServiceProgressMessage {
-  name: "progress";
-  body: {
-    totalSize: number;
-    completedSize: number;
-  };
-}
-```
-
-## Members
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `"progress"` | 고정 문자열 discriminant |
-| `body.totalSize` | `number` | 전체 메시지 크기 (바이트) |
-| `body.completedSize` | `number` | 현재까지 수신 완료된 크기 (바이트) |

package/docs/protocol/service-remove-event-listener-message.md

@@ -1,19 +0,0 @@
-# ServiceRemoveEventListenerMessage
-
-클라이언트가 보내는 이벤트 리스너 제거 메시지.
-
-```typescript
-export interface ServiceRemoveEventListenerMessage {
-  name: "evt:remove";
-  body: {
-    key: string;
-  };
-}
-```
-
-## Members
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `"evt:remove"` | 고정 문자열 discriminant |
-| `body.key` | `string` | 제거할 리스너 키 (UUID) |

package/docs/protocol/service-request-message.md

@@ -1,17 +0,0 @@
-# ServiceRequestMessage
-
-클라이언트가 보내는 서비스 메서드 요청 메시지.
-
-```typescript
-export interface ServiceRequestMessage {
-  name: `${string}.${string}`;
-  body: unknown[];
-}
-```
-
-## Members
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `` `${string}.${string}` `` | 서비스명.메서드명 형식 (예: `"OrmService.connect"`) |
-| `body` | `unknown[]` | 메서드 매개변수 배열 |

package/docs/protocol/service-response-message.md

@@ -1,17 +0,0 @@
-# ServiceResponseMessage
-
-서버가 보내는 서비스 메서드 응답 메시지.
-
-```typescript
-export interface ServiceResponseMessage {
-  name: "response";
-  body?: unknown;
-}
-```
-
-## Members
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `"response"` | 고정 문자열 discriminant |
-| `body` | `unknown?` | 메서드 실행 결과 (없으면 void) |

package/docs/service-types/app-structure-service.md

@@ -1,15 +0,0 @@
-# AppStructureService
-
-서버에 등록된 앱 구조 항목을 클라이언트명 기준 맵으로 조회하는 서비스 인터페이스.
-
-```typescript
-export interface AppStructureService {
-  getItems(): Record<string, AppStructureItem[]>;
-}
-```
-
-## Members
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getItems` | 없음 | `Record<string, AppStructureItem[]>` | 클라이언트명을 키로, 해당 클라이언트의 앱 구조 항목 배열을 값으로 하는 맵 반환 |

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

@@ -1,20 +0,0 @@
-# AutoUpdateService
-
-클라이언트 애플리케이션의 최신 버전 정보를 조회하는 서비스 인터페이스.
-
-```typescript
-export interface AutoUpdateService {
-  getLastVersion(platform: string): Promise<
-    | { version: string; downloadPath: string }
-    | undefined
-  >;
-}
-```
-
-## Members
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getLastVersion` | `platform: string` | `Promise<{ version: string; downloadPath: string } \| undefined>` | 지정된 플랫폼의 최신 버전 정보 조회. 버전이 없으면 `undefined` |
-
-`platform` 예시: `"win32"`, `"darwin"`, `"linux"`

package/docs/service-types/orm-service.md

@@ -1,61 +0,0 @@
-# OrmService
-
-데이터베이스 연결, 트랜잭션 관리, 쿼리 실행을 제공하는 서비스 인터페이스. MySQL, MSSQL, PostgreSQL을 지원한다. 이 패키지에는 구현체가 없으며, 서버(`service-server`)와 클라이언트(`service-client`)가 공유하는 타입 계약이다.
-
-```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>;
-}
-```
-
-## Members
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getInfo` | `opt: DbConnOptions & { configName: string }` | `Promise<{ dialect: Dialect; database?: string; schema?: string }>` | DB 연결 정보 조회 |
-| `connect` | `opt: DbConnOptions & { configName: string }` | `Promise<number>` | DB 연결을 생성하고 연결 ID 반환 |
-| `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[][]>` | QueryDef 배열로 쿼리 실행 |
-| `bulkInsert` | `connId: number, tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]` | `Promise<void>` | 대량 삽입 |
-
-사용 순서: `connect()` → `beginTransaction()` → `executeDefs()`/`executeParametrized()` → `commitTransaction()`/`rollbackTransaction()` → `close()`
-
-## Related Types
-
-### `DbConnOptions`
-
-데이터베이스 연결 옵션.
-
-```typescript
-export type DbConnOptions = { configName?: string; config?: Record<string, unknown> };
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `configName` | `string?` | 서버에 등록된 DB 설정 이름 |
-| `config` | `Record<string, unknown>?` | 직접 지정하는 DB 연결 설정 |

package/docs/types/service-upload-result.md

@@ -1,19 +0,0 @@
-# ServiceUploadResult
-
-파일 업로드 결과. 서버에 업로드된 파일의 정보를 포함한다.
-
-```typescript
-export interface ServiceUploadResult {
-  path: string;
-  filename: string;
-  size: number;
-}
-```
-
-## Members
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `path` | `string` | 서버 내 저장 경로 |
-| `filename` | `string` | 원본 파일명 |
-| `size` | `number` | 파일 크기 (바이트) |