@simplysm/service-common 13.0.0-beta.11

package/README.md

@@ -0,0 +1,336 @@
+# @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/SMTP/auto-update.
+
+## Installation
+
+```bash
+pnpm add @simplysm/service-common
+```
+
+### Dependencies
+
+| Package | Description |
+|--------|------|
+| `@simplysm/core-common` | Common utilities (`Uuid`, `LazyGcMap`, `jsonStringify`, `jsonParse`, etc.) |
+| `@simplysm/orm-common` | ORM types (`Dialect`, `IsolationLevel`, `QueryDef`, etc.) |
+
+## Main Modules
+
+### 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/crypto-service.types` | Crypto service interface and config |
+| `service-types/smtp-service.types` | SMTP service interface and email options |
+| `service-types/auto-update-service.types` | Auto-update service interface |
+| `types` | `ServiceEventListener`, `ServiceUploadResult` |
+
+---
+
+## ServiceProtocol
+
+The core class for encoding/decoding messages into binary format. Messages exceeding 3MB are automatically split into 300KB chunks, and the receiving side automatically assembles the chunks to restore the original message.
+
+### Binary Header Structure
+
+Each chunk consists of a 28-byte header and 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
+
+| 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 |
+| `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<T>` 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) |
+
+### Usage Example
+
+```typescript
+import { ServiceProtocol } from "@simplysm/service-common";
+import { Uuid } from "@simplysm/core-common";
+
+const protocol = new ServiceProtocol();
+
+// Encoding: Convert message to binary chunks
+const uuid = Uuid.new().toString();
+const { chunks, totalSize } = protocol.encode(uuid, {
+  name: "TestService.echo",
+  body: ["Hello, world!"],
+});
+
+// Decoding: Process received chunks one by one
+for (const chunk of chunks) {
+  const result = protocol.decode(chunk);
+  if (result.type === "complete") {
+    console.log(result.message);
+    // { name: "TestService.echo", body: ["Hello, world!"] }
+  } else {
+    // Split message in progress
+    const progress = (result.completedSize / result.totalSize) * 100;
+    console.log(`Reception progress: ${progress.toFixed(1)}%`);
+  }
+}
+
+// Clean up instance (release GC timer)
+protocol.dispose();
+```
+
+---
+
+## Protocol Constants (PROTOCOL_CONFIG)
+
+A constant object that controls protocol behavior.
+
+```typescript
+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 |
+| `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
+
+Type definitions for messages exchanged between client and server. `ServiceMessage` is a union of all message types.
+
+### 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
+
+#### 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 |
+| `ServiceAuthMessage` | `"auth"` | Client -> Server | `string` (token) | Authentication token transmission |
+
+#### 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 |
+
+#### 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 |
+
+---
+
+## ServiceEventListener
+
+An abstract class for defining event listener types. Used by inheriting when defining custom events.
+
+### Type Parameters
+
+| Parameter | Description |
+|---------|------|
+| `TInfo` | Additional information type for listener filtering |
+| `TData` | Data type passed when the event is emitted |
+
+### Properties
+
+| Property | Type | Description |
+|------|------|------|
+| `eventName` | `string` (abstract) | Mangle-safe event identifier. Must be implemented when inheriting |
+| `$info` | `TInfo` (declare) | For type extraction. Not used at runtime |
+| `$data` | `TData` (declare) | For type extraction. Not used at runtime |
+
+### Usage Example
+
+```typescript
+import { ServiceEventListener } from "@simplysm/service-common";
+
+// Custom event definition
+export class DataChangeEvent extends ServiceEventListener<
+  { tableName: string; filter: unknown },
+  (string | number)[] | undefined
+> {
+  readonly eventName = "DataChangeEvent";
+}
+
+// Register listener on client (using service-client)
+await client.addEventListener(
+  DataChangeEvent,
+  { tableName: "User", filter: null },
+  (data) => {
+    console.log("Changed records:", data);
+  },
+);
+```
+
+---
+
+## ServiceUploadResult
+
+An interface representing file upload results.
+
+| Field | Type | Description |
+|------|------|------|
+| `path` | `string` | Storage path on server |
+| `filename` | `string` | Original filename |
+| `size` | `number` | File size (bytes) |
+
+---
+
+## Service Interfaces
+
+Service interface definitions that are implemented on the server side and called by the client via RPC.
+
+### OrmService
+
+Defines database connection, transaction management, and query execution capabilities. Supports MySQL, MSSQL, PostgreSQL.
+
+| Method | Parameters | Return Type | Description |
+|--------|---------|-----------|------|
+| `getInfo` | `opt: DbConnOptions & { configName: string }` | `Promise<{ dialect, database?, schema? }>` | 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 |
+| `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, options?` | `Promise<unknown[][]>` | Execute queries with `QueryDef` array |
+| `bulkInsert` | `connId, tableName, columnDefs, records` | `Promise<void>` | Bulk data insertion |
+
+#### DbConnOptions
+
+| Field | Type | Description |
+|------|------|------|
+| `configName?` | `string` | Config name to reference in server settings |
+| `config?` | `Record<string, unknown>` | Directly passed connection config |
+
+### CryptoService
+
+Defines SHA256 hash generation and AES symmetric key encryption/decryption capabilities.
+
+| Method | Parameters | Return Type | Description |
+|--------|---------|-----------|------|
+| `encrypt` | `data: string \| Bytes` | `Promise<string>` | Generate SHA256 hash |
+| `encryptAes` | `data: Bytes` | `Promise<string>` | AES encryption |
+| `decryptAes` | `encText: string` | `Promise<Bytes>` | AES decryption |
+
+#### CryptoConfig
+
+| Field | Type | Description |
+|------|------|------|
+| `key` | `string` | AES encryption key |
+
+### SmtpService
+
+Defines email sending capabilities. Can send by directly passing SMTP settings or by referencing server config.
+
+| Method | Parameters | Return Type | Description |
+|--------|---------|-----------|------|
+| `send` | `options: SmtpSendOption` | `Promise<string>` | Send email with direct SMTP settings |
+| `sendByConfig` | `configName, options: SmtpSendByConfigOption` | `Promise<string>` | Send email by referencing server config |
+
+#### SmtpSendOption
+
+A type combining `SmtpConnectionOptions` and `SmtpEmailContentOptions`, with an additional `from` field.
+
+| Field | Type | Required | Description |
+|------|------|------|------|
+| `host` | `string` | Y | SMTP host |
+| `port` | `number` | N | SMTP port |
+| `secure` | `boolean` | N | TLS usage |
+| `user` | `string` | N | SMTP auth user |
+| `pass` | `string` | N | SMTP auth password |
+| `from` | `string` | Y | Sender address |
+| `to` | `string` | Y | Recipient address |
+| `cc` | `string` | N | CC |
+| `bcc` | `string` | N | BCC |
+| `subject` | `string` | Y | Subject |
+| `html` | `string` | Y | Body (HTML) |
+| `attachments` | `SmtpSendAttachment[]` | N | Attachment list |
+
+#### SmtpSendByConfigOption
+
+Same as `SmtpEmailContentOptions`. SMTP connection info is referenced from server config (`configName`).
+
+#### SmtpSendAttachment
+
+| Field | Type | Required | Description |
+|------|------|------|------|
+| `filename` | `string` | Y | Attachment filename |
+| `content` | `Bytes` | N | File content (binary). Specify one of `path` or `content` |
+| `path` | `string` | N | File path on server. Specify one of `path` or `content` |
+| `contentType` | `string` | N | MIME type (e.g., `"application/pdf"`) |
+
+#### SmtpConfig
+
+Server-side SMTP configuration type.
+
+| Field | Type | Required | Description |
+|------|------|------|------|
+| `host` | `string` | Y | SMTP host |
+| `port` | `number` | N | SMTP port |
+| `secure` | `boolean` | N | TLS usage |
+| `user` | `string` | N | SMTP auth user |
+| `pass` | `string` | N | SMTP auth password |
+| `senderName` | `string` | Y | Sender display name |
+| `senderEmail` | `string` | N | Sender email address |
+
+### AutoUpdateService
+
+Defines a service for querying the latest version information of a client application.
+
+| 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 |
+
+Pass values like `"win32"`, `"darwin"`, `"linux"` to `platform`.
+
+---
+
+## Caveats
+
+- `ServiceProtocol` instances 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`, `CryptoService`, etc.) only provide type definitions. Actual implementations are handled by the `@simplysm/service-server` package.
+- The `$info` and `$data` properties of `ServiceEventListener` are declared with `declare` and do not exist at runtime; they are only used for TypeScript type extraction.
+
+## 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"}