@simplysm/service-client 13.0.0-beta.11

package/README.md

@@ -0,0 +1,397 @@
+# @simplysm/service-client
+
+A service client package for the Simplysm framework. Provides WebSocket communication with `@simplysm/service-server`, remote service invocation (RPC), event subscription, file upload/download, and ORM remote access.
+
+Works in both browser and Node.js environments, with built-in features like automatic message chunking/merging for large payloads, heartbeat-based connection monitoring, and automatic reconnection.
+
+## Installation
+
+```bash
+npm install @simplysm/service-client
+# or
+pnpm add @simplysm/service-client
+```
+
+### Dependencies
+
+| Package | Description |
+|--------|------|
+| `@simplysm/core-common` | Common utilities (EventEmitter, Uuid, etc.) |
+| `@simplysm/orm-common` | ORM query builder, schema definitions |
+| `@simplysm/service-common` | Service protocol, type definitions |
+
+## Main Modules
+
+### Core Classes
+
+| Class | Description |
+|--------|------|
+| `ServiceClient` | Main service client. Provides integrated connection management, RPC calls, events, files, and authentication. |
+| `ServiceTransport` | Message transport layer. Handles request/response matching, progress tracking, and protocol encoding/decoding. |
+| `SocketProvider` | WebSocket connection management. Handles heartbeat, auto-reconnection, and connection state events. |
+| `ClientProtocolWrapper` | Protocol wrapper. Automatically selects main thread/Web Worker for encoding/decoding based on data size. |
+
+### Feature Classes
+
+| Class | Description |
+|--------|------|
+| `EventClient` | Server event subscription/publishing. Supports automatic listener recovery on reconnection. |
+| `FileClient` | Handles HTTP-based file upload/download. |
+| `OrmClientConnector` | ORM remote connection connector. Supports transaction/non-transaction connections. |
+| `OrmClientDbContextExecutor` | ORM DbContext remote executor. Calls server's `OrmService` via RPC. |
+
+### Types/Interfaces
+
+| Type | Description |
+|------|------|
+| `ServiceConnectionConfig` | Server connection config (host, port, ssl, maxReconnectCount) |
+| `ServiceProgress` | Request/response progress callback |
+| `ServiceProgressState` | Progress state (uuid, totalSize, completedSize) |
+| `OrmConnectConfig<T>` | ORM connection config (DbContext type, connection options, DB/schema override) |
+| `RemoteService<T>` | Utility type that wraps all method return types of a service interface with `Promise` |
+
+## Usage
+
+### Basic Connection and Service Call
+
+```typescript
+import { ServiceClient } from "@simplysm/service-client";
+
+// Create client
+const client = new ServiceClient("my-app", {
+  host: "localhost",
+  port: 8080,
+  ssl: false,
+  maxReconnectCount: 10, // Max reconnection attempts (default: 10, 0 means no reconnection)
+});
+
+// Connect to server
+await client.connect();
+
+// Check connection status
+console.log(client.connected); // true
+console.log(client.hostUrl);   // "http://localhost:8080"
+
+// Direct RPC call
+const result = await client.send("MyService", "getUsers", [{ page: 1 }]);
+
+// Close connection
+await client.close();
+```
+
+### Type-Safe Service Call (getService)
+
+`getService<T>()` uses `Proxy` to provide type-safe remote calls to service interfaces.
+
+```typescript
+// Service interface definition (shared from service-common)
+interface UserService {
+  getUsers(filter: { page: number }): Promise<User[]>;
+  createUser(data: CreateUserDto): Promise<number>;
+  deleteUser(id: number): Promise<void>;
+}
+
+// Create type-safe proxy
+const userService = client.getService<UserService>("UserService");
+
+// Parameter/return types are automatically inferred on method calls
+const users = await userService.getUsers({ page: 1 }); // users: User[]
+const newId = await userService.createUser({ name: "test" }); // newId: number
+```
+
+`RemoteService<T>` wraps all method return types of the original interface with `Promise`. Methods already returning `Promise` are not double-wrapped.
+
+### Authentication
+
+```typescript
+// Send auth token after server connection
+await client.connect();
+await client.auth("jwt-token-here");
+
+// Automatically re-authenticated on reconnection
+```
+
+Tokens stored after `auth()` calls are automatically resent to the server on WebSocket reconnection.
+
+### Connection State Monitoring
+
+`ServiceClient` extends `EventEmitter` and supports the following events.
+
+| Event | Type | Description |
+|--------|------|------|
+| `state` | `"connected" \| "closed" \| "reconnecting"` | Connection state change |
+| `request-progress` | `ServiceProgressState` | Request transmission progress |
+| `response-progress` | `ServiceProgressState` | Response reception progress |
+| `reload` | `Set<string>` | File change notification from server (dev mode HMR) |
+
+```typescript
+// Monitor connection state changes
+client.on("state", (state) => {
+  if (state === "connected") {
+    console.log("Connected to server");
+  } else if (state === "reconnecting") {
+    console.log("Reconnection in progress...");
+  } else if (state === "closed") {
+    console.log("Connection closed");
+  }
+});
+
+// Monitor request/response progress (large messages)
+client.on("request-progress", (state) => {
+  const percent = Math.round((state.completedSize / state.totalSize) * 100);
+  console.log(`Sending: ${percent}%`);
+});
+
+client.on("response-progress", (state) => {
+  const percent = Math.round((state.completedSize / state.totalSize) * 100);
+  console.log(`Receiving: ${percent}%`);
+});
+```
+
+### Individual Request Progress Tracking
+
+Track progress of individual requests with the `progress` parameter of the `send()` method.
+
+```typescript
+const result = await client.send("DataService", "getLargeData", [query], {
+  request: (state) => {
+    console.log(`Request sending: ${state.completedSize}/${state.totalSize} bytes`);
+  },
+  response: (state) => {
+    console.log(`Response receiving: ${state.completedSize}/${state.totalSize} bytes`);
+  },
+});
+```
+
+### Event Subscription (Server -> Client)
+
+Subscribe to events from the server, and listeners are automatically recovered on reconnection.
+
+```typescript
+import { ServiceEventListener } from "@simplysm/service-common";
+
+// Event listener type definition (shared between server/client)
+class SharedDataChangeEvent extends ServiceEventListener<
+  { name: string; filter: unknown },
+  (string | number)[] | undefined
+> {
+  readonly eventName = "SharedDataChangeEvent";
+}
+
+// Subscribe to event
+const listenerKey = await client.addEventListener(
+  SharedDataChangeEvent,
+  { name: "users", filter: null },
+  async (data) => {
+    console.log("Data changed:", data);
+  },
+);
+
+// Unsubscribe from event
+await client.removeEventListener(listenerKey);
+```
+
+### Event Publishing (Client -> Server -> Other Clients)
+
+```typescript
+// Publish event to listeners matching specific conditions
+await client.emitToServer(
+  SharedDataChangeEvent,
+  (info) => info.name === "users", // Target filter
+  [1, 2, 3],                       // Data to send
+);
+```
+
+The server finds listeners matching the `infoSelector` condition in the registered listener list and delivers the event.
+
+### File Upload
+
+File upload is handled via HTTP POST requests and requires an authentication token.
+
+```typescript
+// Authentication required
+await client.auth("jwt-token");
+
+// Upload with browser File object
+const fileInput = document.querySelector("input[type=file]") as HTMLInputElement;
+const results = await client.uploadFile(fileInput.files!);
+
+// Upload with custom data
+const results = await client.uploadFile([
+  { name: "data.json", data: JSON.stringify({ key: "value" }) },
+  { name: "image.png", data: imageBlob },
+]);
+
+// Upload results
+for (const result of results) {
+  console.log(result.path);     // Server storage path
+  console.log(result.filename); // Original filename
+  console.log(result.size);     // File size (bytes)
+}
+```
+
+### File Download
+
+```typescript
+// Download file from server's relative path
+const buffer = await client.downloadFileBuffer("/uploads/2024/file.pdf");
+// buffer: Uint8Array
+```
+
+### ORM Remote Access
+
+Access the database through the server's ORM service. Transactions are automatically managed.
+
+```typescript
+import { OrmClientConnector } from "@simplysm/service-client";
+import type { OrmConnectConfig } from "@simplysm/service-client";
+import { DbContext } from "@simplysm/orm-common";
+
+const connector = new OrmClientConnector(client);
+
+// Connect with transaction (auto rollback on error)
+await connector.connect(
+  {
+    dbContextType: MyDbContext,
+    connOpt: { configName: "default" },
+    dbContextOpt: { database: "mydb", schema: "dbo" }, // Optional
+  },
+  async (db) => {
+    const users = await db.from(User).resultAsync();
+    await db.from(User).insert({ name: "test" });
+    // Auto commit on callback success
+  },
+);
+
+// Connect without transaction (suitable for read-only operations)
+await connector.connectWithoutTransaction(
+  {
+    dbContextType: MyDbContext,
+    connOpt: { configName: "default" },
+  },
+  async (db) => {
+    const users = await db.from(User).resultAsync();
+    return users;
+  },
+);
+```
+
+## Detailed API
+
+### ServiceConnectionConfig
+
+Server connection configuration interface.
+
+| Property | Type | Required | Description |
+|------|------|------|------|
+| `host` | `string` | Yes | Server host address |
+| `port` | `number` | Yes | Server port number |
+| `ssl` | `boolean` | No | SSL usage. If `true`, uses `wss://` / `https://` |
+| `maxReconnectCount` | `number` | No | Max reconnection attempts (default: 10). 0 means no reconnection |
+
+### ServiceClient
+
+| Method/Property | Return Type | Description |
+|-------------|----------|------|
+| `constructor(name, options)` | - | Create client instance. `name` is the client identifier |
+| `connected` | `boolean` | WebSocket connection status |
+| `hostUrl` | `string` | HTTP URL (e.g., `http://localhost:8080`) |
+| `connect()` | `Promise<void>` | Connect to server via WebSocket |
+| `close()` | `Promise<void>` | Close connection (Graceful Shutdown) |
+| `send(serviceName, methodName, params, progress?)` | `Promise<unknown>` | Remote call to service method |
+| `getService<T>(serviceName)` | `RemoteService<T>` | Create type-safe service proxy |
+| `auth(token)` | `Promise<void>` | Send auth token (auto re-auth on reconnection) |
+| `addEventListener(eventType, info, cb)` | `Promise<string>` | Register event listener. Returns listener key |
+| `removeEventListener(key)` | `Promise<void>` | Remove event listener |
+| `emitToServer(eventType, infoSelector, data)` | `Promise<void>` | Publish event to other clients through server |
+| `uploadFile(files)` | `Promise<ServiceUploadResult[]>` | File upload (auth required) |
+| `downloadFileBuffer(relPath)` | `Promise<Uint8Array>` | File download |
+
+### ServiceProgress / ServiceProgressState
+
+Interfaces for tracking progress of large message transmissions.
+
+```typescript
+interface ServiceProgress {
+  request?: (s: ServiceProgressState) => void;   // Request transmission progress
+  response?: (s: ServiceProgressState) => void;  // Response reception progress
+}
+
+interface ServiceProgressState {
+  uuid: string;          // Request unique identifier
+  totalSize: number;     // Total size (bytes)
+  completedSize: number; // Completed size (bytes)
+}
+```
+
+### OrmConnectConfig\<T\>
+
+ORM remote connection configuration interface.
+
+| Property | Type | Required | Description |
+|------|------|------|------|
+| `dbContextType` | `Type<T>` | Yes | DbContext class |
+| `connOpt` | `DbConnOptions & { configName: string }` | Yes | DB connection options (including server-side config name) |
+| `dbContextOpt` | `{ database: string; schema: string }` | No | Database/schema override |
+
+### SocketProvider
+
+Handles low-level management of WebSocket connections. Not typically used directly, but indirectly through `ServiceClient`.
+
+| Constant | Value | Description |
+|------|-----|------|
+| Heartbeat Timeout | 30s | Connection considered disconnected if no messages for this duration |
+| Heartbeat Interval | 5s | Ping transmission interval |
+| Reconnect Delay | 3s | Reconnection attempt interval |
+
+### ClientProtocolWrapper
+
+Handles message encoding/decoding. In browser environments, data exceeding 30KB is automatically processed in a Web Worker to prevent main thread blocking.
+
+| Threshold | Condition |
+|--------|------|
+| 30KB or less | Processed directly in main thread |
+| Over 30KB | Delegated to Web Worker (browser environments only) |
+
+Worker delegation conditions (during encoding):
+- `Uint8Array` data
+- Strings exceeding 30KB
+- Arrays exceeding 100 elements or arrays containing `Uint8Array`
+
+## Architecture
+
+```
+ServiceClient (integrated entry point)
+  |
+  +-- SocketProvider (WebSocket connection management)
+  |     +-- Heartbeat (Ping/Pong)
+  |     +-- Auto reconnection
+  |
+  +-- ServiceTransport (message send/receive)
+  |     +-- ClientProtocolWrapper (encoding/decoding)
+  |     |     +-- ServiceProtocol (main thread)
+  |     |     +-- Web Worker (large data)
+  |     +-- Request/response matching (UUID-based)
+  |     +-- Progress tracking
+  |
+  +-- EventClient (event subscription/publishing)
+  |     +-- Listener management (registration/removal)
+  |     +-- Auto recovery on reconnection
+  |
+  +-- FileClient (HTTP file transfer)
+        +-- Upload (FormData, POST)
+        +-- Download (GET)
+```
+
+## Caveats
+
+- **Auth Required**: You must authenticate with `auth()` before calling `uploadFile()`. An error occurs if not authenticated.
+- **Connection State Check**: `addEventListener()` can only be called when connected to the server. An error occurs if not connected.
+- **Auto Reconnection**: If the connection is lost, automatic reconnection is attempted up to `maxReconnectCount` times at 3-second intervals. On successful reconnection, auth tokens and event listeners are automatically recovered.
+- **Large Messages**: Large messages are automatically split/merged by `ServiceProtocol` from `@simplysm/service-common`. Progress can be tracked via `ServiceProgress` callbacks or `ServiceClient` events.
+- **Web Worker**: In browser environments, encoding/decoding of data exceeding 30KB is automatically handled in a Web Worker. In Node.js environments, it's always processed in the main thread.
+- **Foreign Key Error Conversion**: ORM connection errors due to foreign key constraint violations are automatically converted to user-friendly messages.
+
+## License
+
+Apache-2.0

package/dist/core-common/src/common.types.d.ts

@@ -0,0 +1,74 @@
+import { DateTime } from "./types/date-time";
+import { DateOnly } from "./types/date-only";
+import { Time } from "./types/time";
+import { Uuid } from "./types/uuid";
+/**
+ * Buffer 대신 사용하는 바이너리 타입
+ */
+export type Bytes = Uint8Array;
+/**
+ * Primitive 타입 매핑
+ * orm-common과 공유
+ */
+export type PrimitiveTypeMap = {
+    string: string;
+    number: number;
+    boolean: boolean;
+    DateTime: DateTime;
+    DateOnly: DateOnly;
+    Time: Time;
+    Uuid: Uuid;
+    Bytes: Bytes;
+};
+/**
+ * Primitive 타입 문자열 키
+ */
+export type PrimitiveTypeStr = keyof PrimitiveTypeMap;
+/**
+ * Primitive 타입 유니온
+ */
+export type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
+/**
+ * 깊은 Partial 타입
+ *
+ * 객체의 모든 속성을 재귀적으로 선택적(optional)으로 만듭니다.
+ * Primitive 타입(string, number, boolean 등)은 그대로 유지하고,
+ * 객체/배열 타입만 재귀적으로 Partial을 적용합니다.
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   name: string;
+ *   profile: {
+ *     age: number;
+ *     address: { city: string };
+ *   };
+ * }
+ *
+ * // 모든 깊이의 속성이 선택적이 됨
+ * const partial: DeepPartial<User> = {
+ *   profile: { address: {} }
+ * };
+ * ```
+ */
+export type DeepPartial<T> = Partial<{
+    [K in keyof T]: T[K] extends PrimitiveType ? T[K] : DeepPartial<T[K]>;
+}>;
+/**
+ * 생성자 타입
+ *
+ * 클래스 생성자를 타입으로 표현할 때 사용합니다.
+ * 주로 의존성 주입, 팩토리 패턴, instanceof 체크 등에서 활용됩니다.
+ *
+ * @example
+ * function create<T>(ctor: Type<T>): T {
+ *   return new ctor();
+ * }
+ *
+ * class MyClass { name = "test"; }
+ * const instance = create(MyClass); // MyClass 인스턴스
+ */
+export interface Type<T> extends Function {
+    new (...args: unknown[]): T;
+}
+//# sourceMappingURL=common.types.d.ts.map

package/dist/core-common/src/common.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.types.d.ts","sourceRoot":"","sources":["../../../../core-common/src/common.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAIpC;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG,UAAU,CAAC;AAM/B;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,gBAAgB,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,GAAG,SAAS,CAAC;AAM3E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC;KAClC,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACtE,CAAC,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,IAAI,CAAC,CAAC,CAAE,SAAQ,QAAQ;IACvC,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;CAC7B"}

package/dist/core-common/src/env.d.ts

@@ -0,0 +1,6 @@
+export declare const env: {
+    DEV: boolean;
+    VER?: string;
+    [key: string]: unknown;
+};
+//# sourceMappingURL=env.d.ts.map

package/dist/core-common/src/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../../core-common/src/env.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,GAAG,EAAE;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAKxB,CAAC"}

package/dist/core-common/src/errors/argument-error.d.ts

@@ -0,0 +1,25 @@
+import { SdError } from "./sd-error";
+/**
+ * 인수 오류
+ *
+ * 잘못된 인수를 받았을 때 발생시키는 에러이다.
+ * 인수 객체를 YAML 형식으로 메시지에 포함하여 디버깅을 용이하게 한다.
+ *
+ * @example
+ * // 인수 객체만 전달
+ * throw new ArgumentError({ userId: 123, name: null });
+ * // 결과 메시지: "인수가 잘못되었습니다.\n\nuserId: 123\nname: null"
+ *
+ * @example
+ * // 커스텀 메시지와 인수 객체 전달
+ * throw new ArgumentError("유효하지 않은 사용자", { userId: 123 });
+ * // 결과 메시지: "유효하지 않은 사용자\n\nuserId: 123"
+ */
+export declare class ArgumentError extends SdError {
+    /** 기본 메시지("인수가 잘못되었습니다.")와 함께 인수 객체를 YAML 형식으로 출력 */
+    constructor(argObj: Record<string, unknown>);
+    /** 커스텀 메시지와 함께 인수 객체를 YAML 형식으로 출력 */
+    constructor(message: string, argObj: Record<string, unknown>);
+    constructor(arg1: Record<string, unknown> | string, arg2?: Record<string, unknown>);
+}
+//# sourceMappingURL=argument-error.d.ts.map

package/dist/core-common/src/errors/argument-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"argument-error.d.ts","sourceRoot":"","sources":["../../../../../core-common/src/errors/argument-error.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,aAAc,SAAQ,OAAO;IACxC,qDAAqD;gBACzC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3C,sCAAsC;gBAC1B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAChD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAYnF"}

package/dist/core-common/src/errors/not-implemented-error.d.ts

@@ -0,0 +1,29 @@
+import { SdError } from "./sd-error";
+/**
+ * 미구현 오류
+ *
+ * 아직 구현되지 않은 기능을 호출했을 때 발생시키는 에러이다.
+ * 추상 메서드 스텁, 향후 구현 예정인 분기 등에 사용한다.
+ *
+ * @example
+ * // 추상 메서드 구현 전
+ * class BaseService {
+ *   process(): void {
+ *     throw new NotImplementedError("서브클래스에서 구현 필요");
+ *   }
+ * }
+ *
+ * @example
+ * // 향후 구현 예정 분기
+ * switch (type) {
+ *   case "A": return handleA();
+ *   case "B": throw new NotImplementedError(`타입 ${type} 처리`);
+ * }
+ */
+export declare class NotImplementedError extends SdError {
+    /**
+     * @param message 추가 설명 메시지
+     */
+    constructor(message?: string);
+}
+//# sourceMappingURL=not-implemented-error.d.ts.map

package/dist/core-common/src/errors/not-implemented-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-implemented-error.d.ts","sourceRoot":"","sources":["../../../../../core-common/src/errors/not-implemented-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,mBAAoB,SAAQ,OAAO;IAC9C;;OAEG;gBACS,OAAO,CAAC,EAAE,MAAM;CAI7B"}

package/dist/core-common/src/errors/sd-error.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 오류의 Tree 구조 구성이 가능한 오류 클래스
+ * ES2024 cause 속성 활용
+ *
+ * @example
+ * // 원인 에러를 감싸서 생성
+ * try {
+ *   await fetch(url);
+ * } catch (err) {
+ *   throw new SdError(err, "API 호출 실패", "사용자 로드 실패");
+ * }
+ * // 결과 메시지: "사용자 로드 실패 => API 호출 실패 => 원본 에러 메시지"
+ *
+ * @example
+ * // 메시지만으로 생성
+ * throw new SdError("잘못된 상태", "처리 불가");
+ * // 결과 메시지: "처리 불가 => 잘못된 상태"
+ */
+export declare class SdError extends Error {
+    cause?: Error;
+    /** 원인 에러를 감싸서 생성. 메시지는 역순으로 연결됨 (상위 메시지 => 하위 메시지 => 원인 메시지) */
+    constructor(cause: Error, ...messages: string[]);
+    /** 메시지만으로 생성. 메시지는 역순으로 연결됨 (상위 메시지 => 하위 메시지) */
+    constructor(...messages: string[]);
+    constructor(arg1?: unknown, ...messages: string[]);
+}
+//# sourceMappingURL=sd-error.d.ts.map

package/dist/core-common/src/errors/sd-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sd-error.d.ts","sourceRoot":"","sources":["../../../../../core-common/src/errors/sd-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,OAAQ,SAAQ,KAAK;IACvB,KAAK,CAAC,EAAE,KAAK,CAAC;IAEvB,gEAAgE;gBACpD,KAAK,EAAE,KAAK,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE;IAC/C,kDAAkD;gBACtC,GAAG,QAAQ,EAAE,MAAM,EAAE;gBACrB,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE;CA2BlD"}

package/dist/core-common/src/errors/timeout-error.d.ts

@@ -0,0 +1,31 @@
+import { SdError } from "./sd-error";
+/**
+ * 타임아웃 오류
+ *
+ * 대기 시간이 초과되었을 때 발생하는 에러이다.
+ * Wait.until() 등의 비동기 대기 함수에서 최대 시도 횟수를 초과하면 자동으로 발생한다.
+ *
+ * @example
+ * // Wait.until에서 자동 발생
+ * try {
+ *   await Wait.until(() => isReady, 100, 50); // 100ms 간격, 최대 50회
+ * } catch (err) {
+ *   if (err instanceof TimeoutError) {
+ *     console.log("시간 초과");
+ *   }
+ * }
+ *
+ * @example
+ * // 직접 발생
+ * if (elapsed > maxTime) {
+ *   throw new TimeoutError(undefined, "API 응답 대기 초과");
+ * }
+ */
+export declare class TimeoutError extends SdError {
+    /**
+     * @param count 시도 횟수
+     * @param message 추가 메시지
+     */
+    constructor(count?: number, message?: string);
+}
+//# sourceMappingURL=timeout-error.d.ts.map

package/dist/core-common/src/errors/timeout-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout-error.d.ts","sourceRoot":"","sources":["../../../../../core-common/src/errors/timeout-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAa,SAAQ,OAAO;IACvC;;;OAGG;gBACS,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAM7C"}

package/dist/core-common/src/extensions/arr-ext.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Array 확장 메서드
+ *
+ * @remarks 각 메서드의 TSDoc은 타입 정의 파일(arr-ext.types.ts) 참조
+ */
+import "./map-ext";
+import type { ReadonlyArrayExt, MutableArrayExt } from "./arr-ext.types";
+declare global {
+    interface ReadonlyArray<T> extends ReadonlyArrayExt<T> {
+    }
+    interface Array<T> extends ReadonlyArrayExt<T>, MutableArrayExt<T> {
+    }
+}
+export type { ArrayDiffsResult, ArrayDiffs2Result, TreeArray, ComparableType } from "./arr-ext.types";
+//# sourceMappingURL=arr-ext.d.ts.map

package/dist/core-common/src/extensions/arr-ext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arr-ext.d.ts","sourceRoot":"","sources":["../../../../../core-common/src/extensions/arr-ext.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,WAAW,CAAC;AAUnB,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EAIhB,MAAM,iBAAiB,CAAC;AA2uBzB,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,aAAa,CAAC,CAAC,CAAE,SAAQ,gBAAgB,CAAC,CAAC,CAAC;KAAG;IACzD,UAAU,KAAK,CAAC,CAAC,CAAE,SAAQ,gBAAgB,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC;KAAG;CACtE;AAID,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/core-common/src/extensions/arr-ext.helpers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Array 확장 헬퍼 함수
+ */
+import type { ComparableType } from "./arr-ext.types";
+/**
+ * DateTime, DateOnly, Time을 비교 가능한 primitive 값으로 변환
+ */
+export declare function toComparable(value: ComparableType): string | number | boolean | undefined;
+/**
+ * 정렬을 위한 비교 함수
+ *
+ * @param pp 비교 대상 1
+ * @param pn 비교 대상 2
+ * @param desc true: 내림차순, false: 오름차순
+ * @returns 음수: pp가 앞, 0: 같음, 양수: pn이 앞
+ * @note null/undefined 값은 오름차순 시 앞으로, 내림차순 시 뒤로 정렬됨
+ */
+export declare function compareForOrder(pp: ComparableType, pn: ComparableType, desc: boolean): number;
+//# sourceMappingURL=arr-ext.helpers.d.ts.map

package/dist/core-common/src/extensions/arr-ext.helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arr-ext.helpers.d.ts","sourceRoot":"","sources":["../../../../../core-common/src/extensions/arr-ext.helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAKzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAuB7F"}