@simplysm/orm-node 14.0.49 → 14.0.50

package/docs/types/db-conn-config.md

@@ -0,0 +1,91 @@
+# DbConnConfig
+
+DB 연결 설정 discriminated union. `dialect` 필드로 구현체를 분기한다.
+
+```typescript
+type DbConnConfig = MysqlDbConnConfig | MssqlDbConnConfig | PostgresqlDbConnConfig;
+```
+
+## Related Types
+
+### `MysqlDbConnConfig`
+
+MySQL 연결 설정.
+
+```typescript
+interface MysqlDbConnConfig {
+  dialect: "mysql";
+  host: string;
+  port?: number;
+  username: string;
+  password: string;
+  database?: string;
+  defaultIsolationLevel?: IsolationLevel;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `dialect` | `"mysql"` | Discriminant. 항상 `"mysql"` |
+| `host` | `string` | 호스트 주소 |
+| `port` | `number?` | 포트 (생략 시 mysql2 기본값 사용) |
+| `username` | `string` | 사용자 이름 |
+| `password` | `string` | 비밀번호 |
+| `database` | `string?` | 데이터베이스 이름 |
+| `defaultIsolationLevel` | `IsolationLevel?` | 기본 격리 수준 (미지정 시 `READ_UNCOMMITTED`) |
+
+### `MssqlDbConnConfig`
+
+MSSQL/Azure SQL 연결 설정.
+
+```typescript
+interface MssqlDbConnConfig {
+  dialect: "mssql" | "mssql-azure";
+  host: string;
+  port?: number;
+  username: string;
+  password: string;
+  database?: string;
+  schema?: string;
+  defaultIsolationLevel?: IsolationLevel;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `dialect` | `"mssql" \| "mssql-azure"` | Discriminant. `"mssql-azure"`인 경우 암호화 연결(`encrypt: true`)을 사용한다 |
+| `host` | `string` | 호스트 주소 |
+| `port` | `number?` | 포트 |
+| `username` | `string` | 사용자 이름 |
+| `password` | `string` | 비밀번호 |
+| `database` | `string?` | 데이터베이스 이름 |
+| `schema` | `string?` | 스키마 이름 |
+| `defaultIsolationLevel` | `IsolationLevel?` | 기본 격리 수준 (미지정 시 `READ_UNCOMMITTED`) |
+
+### `PostgresqlDbConnConfig`
+
+PostgreSQL 연결 설정.
+
+```typescript
+interface PostgresqlDbConnConfig {
+  dialect: "postgresql";
+  host: string;
+  port?: number;
+  username: string;
+  password: string;
+  database?: string;
+  schema?: string;
+  defaultIsolationLevel?: IsolationLevel;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `dialect` | `"postgresql"` | Discriminant. 항상 `"postgresql"` |
+| `host` | `string` | 호스트 주소 |
+| `port` | `number?` | 포트 (미지정 시 `5432`) |
+| `username` | `string` | 사용자 이름 |
+| `password` | `string` | 비밀번호 |
+| `database` | `string?` | 데이터베이스 이름 |
+| `schema` | `string?` | 스키마 이름 |
+| `defaultIsolationLevel` | `IsolationLevel?` | 기본 격리 수준 (미지정 시 `READ_UNCOMMITTED`) |

package/docs/types/db-conn-constants.md

@@ -0,0 +1,33 @@
+# DB_CONN_CONNECT_TIMEOUT
+
+DB 연결 수립 타임아웃 (10초).
+
+```typescript
+const DB_CONN_CONNECT_TIMEOUT = 10 * 1000; // 10_000ms
+```
+
+## Related Types
+
+### `DB_CONN_DEFAULT_TIMEOUT`
+
+DB 쿼리 기본 타임아웃 (10분). 유휴 연결 자동 종료 타이머는 이 값의 2배 후 `close()`를 호출한다.
+
+```typescript
+const DB_CONN_DEFAULT_TIMEOUT = 10 * 60 * 1000; // 600_000ms
+```
+
+### `DB_CONN_ERRORS`
+
+DB 연결 관련 오류 메시지 상수.
+
+```typescript
+const DB_CONN_ERRORS = {
+  NOT_CONNECTED: "'Connection'이 연결되어 있지 않습니다.",
+  ALREADY_CONNECTED: "'Connection'이 이미 연결되어 있습니다.",
+} as const;
+```
+
+| Key | Value |
+|-----|-------|
+| `NOT_CONNECTED` | `"'Connection'이 연결되어 있지 않습니다."` |
+| `ALREADY_CONNECTED` | `"'Connection'이 이미 연결되어 있습니다."` |

package/docs/types/db-conn.md

@@ -0,0 +1,55 @@
+# DbConn
+
+저수준 DB 연결 인터페이스. 각 DBMS 구현체(`MssqlDbConn`, `MysqlDbConn`, `PostgresqlDbConn`)가 이 인터페이스를 구현한다.
+
+```typescript
+interface DbConn extends EventEmitter<{ close: void }> {
+  config: DbConnConfig;
+  isConnected: boolean;
+  isInTransaction: boolean;
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
+  commitTransaction(): Promise<void>;
+  rollbackTransaction(): Promise<void>;
+  execute(queries: string[]): Promise<Record<string, unknown>[][]>;
+  executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>;
+  bulkInsert(
+    tableName: string,
+    columnMetas: Record<string, ColumnMeta>,
+    records: Record<string, unknown>[],
+  ): Promise<void>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `config` | property | `DbConnConfig` | 연결 설정 |
+| `isConnected` | property | `boolean` | 연결 여부 |
+| `isInTransaction` | property | `boolean` | 트랜잭션 진행 여부 |
+| `connect()` | method | `Promise<void>` | DB 연결을 수립한다 |
+| `close()` | method | `Promise<void>` | DB 연결을 종료한다 |
+| `beginTransaction(isolationLevel?)` | method | `Promise<void>` | 트랜잭션을 시작한다 |
+| `commitTransaction()` | method | `Promise<void>` | 트랜잭션을 커밋한다 |
+| `rollbackTransaction()` | method | `Promise<void>` | 트랜잭션을 롤백한다 |
+| `execute(queries)` | method | `Promise<Record<string, unknown>[][]>` | SQL 쿼리 배열을 실행한다 |
+| `executeParametrized(query, params?)` | method | `Promise<Record<string, unknown>[][]>` | 파라미터화된 쿼리를 실행한다 |
+| `bulkInsert(tableName, columnMetas, records)` | method | `Promise<void>` | 네이티브 bulk API를 사용하여 대량 삽입한다 |
+
+`EventEmitter<{ close: void }>`를 상속하므로 연결 종료 시 `'close'` 이벤트를 수신할 수 있다.
+
+## Usage
+
+```typescript
+conn.on("close", () => {
+  // 연결이 종료됨
+});
+
+await conn.connect();
+await conn.beginTransaction();
+await conn.execute(["INSERT INTO users (name) VALUES ('Alice')"]);
+await conn.commitTransaction();
+await conn.close();
+```

package/docs/types/get-dialect-from-config.md

@@ -0,0 +1,17 @@
+# getDialectFromConfig
+
+`DbConnConfig`에서 정규화된 `Dialect`를 추출한다.
+
+```typescript
+function getDialectFromConfig(config: DbConnConfig): Dialect;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `config` | `DbConnConfig` | DB 연결 설정 |
+
+## Returns
+
+`Dialect` — 정규화된 dialect 값. `"mssql-azure"` → `"mssql"`로 변환하고, 나머지(`"mysql"`, `"mssql"`, `"postgresql"`)는 `config.dialect`를 그대로 반환한다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/orm-node",
-  "version": "14.0.49",
+  "version": "14.0.50",
   "description": "심플리즘 패키지 - ORM (node)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -20,8 +20,8 @@
   "sideEffects": false,
   "dependencies": {
     "consola": "^3.4.2",
-    "@simplysm/core-common": "14.0.49",
-    "@simplysm/orm-common": "14.0.49"
+    "@simplysm/core-common": "14.0.50",
+    "@simplysm/orm-common": "14.0.50"
   },
   "devDependencies": {
     "@types/pg": "^8.20.0",

package/src/connections/mssql-db-conn.ts

@@ -68,7 +68,7 @@ export class MssqlDbConn extends EventEmitter<{ close: void }> implements DbConn
         requestTimeout: this._timeout,
         trustServerCertificate: true,
         connectTimeout: DB_CONN_CONNECT_TIMEOUT,
-      } as tediousType.ConnectionOptions,
+      },
     });
 
     conn.on("infoMessage", (info) => {

package/src/connections/mysql-db-conn.ts

@@ -142,7 +142,7 @@ export class MysqlDbConn extends EventEmitter<{ close: void }> implements DbConn
       const [queryResults] = await conn.query({
         sql: query,
         timeout: this._timeout,
-        values: params as ({} | null)[] | undefined,
+        values: params,
       });
 
       this._startTimeout();

package/src/node-db-context-executor.ts

@@ -132,7 +132,7 @@ export class NodeDbContextExecutor implements DbContextExecutor {
     if (resultMetas != null && resultMetas.every((item) => item == null)) {
       const combinedSql = defs.map((def) => builder.build(def).sql).join("\n");
       await conn.execute([combinedSql]);
-      return defs.map(() => []) as T[][];
+      return defs.map(() => []);
     }
 
     // 각 def를 개별적으로 실행

package/docs/connections.md

@@ -1,137 +0,0 @@
-# Connections
-
-세 연결 클래스(`MssqlDbConn`, `MysqlDbConn`, `PostgresqlDbConn`)는 모두 `EventEmitter<{ close: void }>`를 상속하고 `DbConn` 인터페이스를 구현한다.
-
-일반적으로 직접 생성하지 않고 `createDbConn()`을 통해 인스턴스를 얻는다. 직접 생성은 테스트 코드에서 네이티브 라이브러리를 주입할 때 사용한다.
-
-## `MssqlDbConn`
-
-tedious 라이브러리를 사용하여 MSSQL/Azure SQL 연결을 관리하는 클래스.
-
-```typescript
-class MssqlDbConn extends EventEmitter<{ close: void }> implements DbConn {
-  isConnected: boolean;
-  isInTransaction: boolean;
-  readonly config: MssqlDbConnConfig;
-
-  constructor(
-    tedious: typeof import("tedious"),
-    config: MssqlDbConnConfig,
-  );
-
-  connect(): Promise<void>;
-  close(): Promise<void>;
-  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
-  commitTransaction(): Promise<void>;
-  rollbackTransaction(): Promise<void>;
-  execute(queries: string[]): Promise<Record<string, unknown>[][]>;
-  executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>;
-  bulkInsert(
-    tableName: string,
-    columnMetas: Record<string, ColumnMeta>,
-    records: Record<string, unknown>[],
-  ): Promise<void>;
-}
-```
-
-**생성자**: tedious 라이브러리 모듈을 첫 번째 인수로 직접 주입받는다. `createDbConn()`이 동적 import 후 전달한다.
-
-**`connect()`**: `config.dialect === "mssql-azure"`인 경우 `encrypt: true`로 연결한다. 연결 성공 시 유휴 타임아웃 타이머(`DB_CONN_DEFAULT_TIMEOUT * 2`)를 시작한다.
-
-**`close()`**: 진행 중인 요청을 취소(`cancel()`)하고 30초 내에 완료될 때까지 대기한 뒤 연결을 종료한다.
-
-**`bulkInsert()`**: tedious `BulkLoad` API를 사용한다. 값 변환 규칙:
-- `Uuid` → `toString()`
-- `Uint8Array` → `Buffer.from(val)` (tedious 라이브러리 요구사항으로 인한 예외적 허용)
-- `DateTime` / `DateOnly` → `.date` (native Date 객체)
-- `Time` → `"HH:mm:ss"` 포맷 문자열
-
-**`executeParametrized()`**: 파라미터가 있으면 `conn.execSql()`, 없으면 `conn.execSqlBatch()`를 사용한다. 쿼리 오류 시 오류 발생 줄을 `==> ` 접두사로 표시하여 에러 메시지에 포함한다.
-
-## `MysqlDbConn`
-
-mysql2/promise 라이브러리를 사용하여 MySQL 연결을 관리하는 클래스.
-
-```typescript
-class MysqlDbConn extends EventEmitter<{ close: void }> implements DbConn {
-  isConnected: boolean;
-  isInTransaction: boolean;
-  readonly config: MysqlDbConnConfig;
-
-  constructor(
-    mysql2: typeof import("mysql2/promise"),
-    config: MysqlDbConnConfig,
-  );
-
-  connect(): Promise<void>;
-  close(): Promise<void>;
-  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
-  commitTransaction(): Promise<void>;
-  rollbackTransaction(): Promise<void>;
-  execute(queries: string[]): Promise<Record<string, unknown>[][]>;
-  executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>;
-  bulkInsert(
-    tableName: string,
-    columnMetas: Record<string, ColumnMeta>,
-    records: Record<string, unknown>[],
-  ): Promise<void>;
-}
-```
-
-**생성자**: mysql2/promise 라이브러리 모듈을 첫 번째 인수로 직접 주입받는다.
-
-**`connect()`**: `username === "root"`인 경우 `database` 옵션을 전달하지 않는다 (모든 데이터베이스에 접근 가능하도록 관리 작업용). `multipleStatements: true`, `charset: "utf8mb4"`로 연결한다.
-
-**`beginTransaction()`**: `SET SESSION TRANSACTION ISOLATION LEVEL {level}` 후 `BEGIN`을 실행한다. MySQL은 트랜잭션 시작 전에 격리 수준을 설정해야 한다.
-
-**`bulkInsert()`**: `LOAD DATA LOCAL INFILE`을 사용한다. 처리 흐름:
-1. `os.tmpdir()`에 UUID 기반 임시 CSV 파일 생성 (TAB 구분)
-2. UUID/binary 컬럼은 hex 문자열로 기록, `SET` 절에서 `UNHEX()` 변환
-3. `LOAD DATA LOCAL INFILE` 실행
-4. `finally` 블록에서 임시 파일 삭제
-
-**`executeParametrized()`**: 결과 형식에 따라 처리:
-- single SELECT → flat `RowDataPacket[]`를 단일 결과 집합으로 반환
-- single INSERT/UPDATE/DELETE → `ResultSetHeader`이므로 빈 결과 집합 반환
-- multi-statement → 각 statement의 결과를 별도 결과 집합으로 분리
-
-## `PostgresqlDbConn`
-
-pg + pg-copy-streams 라이브러리를 사용하여 PostgreSQL 연결을 관리하는 클래스.
-
-```typescript
-class PostgresqlDbConn extends EventEmitter<{ close: void }> implements DbConn {
-  isConnected: boolean;
-  isInTransaction: boolean;
-  readonly config: PostgresqlDbConnConfig;
-
-  constructor(
-    pg: typeof import("pg"),
-    pgCopyStreams: typeof import("pg-copy-streams"),
-    config: PostgresqlDbConnConfig,
-  );
-
-  connect(): Promise<void>;
-  close(): Promise<void>;
-  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
-  commitTransaction(): Promise<void>;
-  rollbackTransaction(): Promise<void>;
-  execute(queries: string[]): Promise<Record<string, unknown>[][]>;
-  executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>;
-  bulkInsert(
-    tableName: string,
-    columnMetas: Record<string, ColumnMeta>,
-    records: Record<string, unknown>[],
-  ): Promise<void>;
-}
-```
-
-**생성자**: pg와 pg-copy-streams 라이브러리 모듈을 첫 번째, 두 번째 인수로 직접 주입받는다.
-
-**`connect()`**: 기본 포트는 `5432`. `connectionTimeoutMillis: DB_CONN_CONNECT_TIMEOUT`, `query_timeout: DB_CONN_DEFAULT_TIMEOUT`으로 연결한다.
-
-**`beginTransaction()`**: `BEGIN` 후 `SET TRANSACTION ISOLATION LEVEL {level}`을 실행한다.
-
-**`bulkInsert()`**: `COPY FROM STDIN`(CSV 형식)을 사용한다. `pg-copy-streams`의 `from()` 함수로 스트림을 생성하고, `Readable.from(csvContent)`를 파이프한다. binary 컬럼은 PostgreSQL bytea hex 형식(`\x{hex}`)으로 변환한다.
-
-**`executeParametrized()`**: PostgreSQL은 단일 결과 집합을 반환하므로 `[result.rows]`로 래핑하여 반환한다.

package/docs/core.md

@@ -1,131 +0,0 @@
-# Core
-
-## `createDbConn`
-
-dialect 기반 DbConn 팩토리. 네이티브 드라이버를 지연 로딩하여 DbConn 인스턴스를 생성한다.
-
-```typescript
-async function createDbConn(config: DbConnConfig): Promise<DbConn>;
-```
-
-`config.dialect`에 따라 적절한 DbConn 구현체를 생성한다:
-
-| dialect | 반환 타입 | 로드하는 패키지 |
-|---------|-----------|----------------|
-| `"mysql"` | `MysqlDbConn` | `mysql2/promise` |
-| `"postgresql"` | `PostgresqlDbConn` | `pg`, `pg-copy-streams` |
-| `"mssql"` / `"mssql-azure"` | `MssqlDbConn` | `tedious` |
-
-네이티브 드라이버 패키지는 최초 호출 시에만 동적 import로 로드하고 모듈 수준 캐시에 보관한다. 이후 호출에서는 캐시된 모듈을 재사용한다.
-
-반환된 `DbConn`은 아직 연결되지 않은 상태이므로 `connect()`를 별도로 호출해야 한다.
-
-```typescript
-const conn = await createDbConn({ dialect: "mysql", host: "...", username: "...", password: "..." });
-await conn.connect(); // 연결 수립
-```
-
-## `NodeDbContextExecutor`
-
-`orm-common`의 `DbContextExecutor` 인터페이스를 구현하는 Node.js 환경용 실행자. `DbContext`에서 내부적으로 사용한다.
-
-```typescript
-class NodeDbContextExecutor implements DbContextExecutor {
-  constructor(config: DbConnConfig);
-
-  connect(): Promise<void>;
-  close(): Promise<void>;
-  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
-  commitTransaction(): Promise<void>;
-  rollbackTransaction(): Promise<void>;
-  executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>;
-  bulkInsert(
-    tableName: string,
-    columnMetas: Record<string, ColumnMeta>,
-    records: DataRecord[],
-  ): Promise<void>;
-  executeDefs<T = DataRecord>(
-    defs: QueryDef[],
-    resultMetas?: (ResultMeta | undefined)[],
-  ): Promise<T[][]>;
-}
-```
-
-내부적으로 `createDbConn()`으로 DB 연결을 생성하고 관리한다.
-
-**`executeDefs()`**: `QueryDef` 배열을 SQL로 변환하여 실행한다. 처리 방식:
-- `resultMetas`가 모두 `undefined`이면 쿼리를 단일 문자열로 결합하여 한 번의 요청으로 실행한다 (결과 불필요 최적화).
-- 그 외에는 각 def를 개별 실행하고 `ResultMeta`가 있으면 `parseQueryResult()`로 결과를 파싱한다.
-- `buildResult.resultSetIndex`가 지정된 경우 해당 인덱스의 결과 집합을 사용한다.
-
-일반적으로 직접 사용하지 않는다. `createOrm()`이 내부적으로 이 클래스를 생성하여 `DbContext`에 전달한다.
-
-## `createOrm`
-
-Node.js ORM 팩토리 함수. `DbContext` 서브클래스와 DB 연결 설정을 받아 트랜잭션을 관리하는 `Orm<T>` 인스턴스를 반환한다.
-
-```typescript
-function createOrm<T extends DbContext>(
-  DbClass: new (executor: DbContextExecutor, opt: { database: string; schema?: string }) => T,
-  config: DbConnConfig,
-  options?: OrmOptions,
-): Orm<T>;
-```
-
-`options.database` / `options.schema`는 `config`의 동일 필드보다 우선 적용된다. `database`는 필수이며, `config`와 `options` 양쪽 모두 `database`가 없으면 에러를 throw한다.
-
-```typescript
-class MyDb extends DbContext {
-  user = this.queryable(User);
-}
-
-const orm = createOrm(MyDb, {
-  dialect: "mysql",
-  host: "localhost",
-  username: "root",
-  password: "password",
-  database: "mydb",
-});
-
-await orm.connect(async (db) => {
-  return db.user().execute();
-});
-```
-
-## `Orm`
-
-`createOrm()`에서 반환하는 객체의 타입.
-
-```typescript
-interface Orm<T extends DbContext> {
-  readonly DbClass: new (executor: DbContextExecutor, opt: { database: string; schema?: string }) => T;
-  readonly config: DbConnConfig;
-  readonly options?: OrmOptions;
-  connect<R>(callback: (conn: T) => Promise<R>, isolationLevel?: IsolationLevel): Promise<R>;
-  connectWithoutTransaction<R>(callback: (conn: T) => Promise<R>): Promise<R>;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `DbClass` | constructor | DbContext 서브클래스 생성자 |
-| `config` | `DbConnConfig` | DB 연결 설정 |
-| `options` | `OrmOptions?` | ORM 옵션 |
-| `connect(callback, isolationLevel?)` | `Promise<R>` | 트랜잭션 내에서 콜백을 실행한다. 콜백 완료 후 자동 커밋, 예외 발생 시 자동 롤백 |
-| `connectWithoutTransaction(callback)` | `Promise<R>` | 트랜잭션 없이 콜백을 실행한다 |
-
-## `OrmOptions`
-
-`createOrm()`의 세 번째 인수로 전달하는 옵션. `DbConnConfig`의 동일 필드보다 우선 적용된다.
-
-```typescript
-interface OrmOptions {
-  database?: string;
-  schema?: string;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `database` | `string?` | 데이터베이스 이름. `DbConnConfig`의 `database` 대신 사용된다 |
-| `schema` | `string?` | 스키마 이름 (MSSQL: `dbo`, PostgreSQL: `public`). `DbConnConfig`의 `schema` 대신 사용된다 |

package/docs/types.md

@@ -1,173 +0,0 @@
-# Types
-
-## `DbConn`
-
-저수준 DB 연결 인터페이스. 각 DBMS 구현체(`MssqlDbConn`, `MysqlDbConn`, `PostgresqlDbConn`)가 이 인터페이스를 구현한다.
-
-```typescript
-interface DbConn extends EventEmitter<{ close: void }> {
-  config: DbConnConfig;
-  isConnected: boolean;
-  isInTransaction: boolean;
-  connect(): Promise<void>;
-  close(): Promise<void>;
-  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
-  commitTransaction(): Promise<void>;
-  rollbackTransaction(): Promise<void>;
-  execute(queries: string[]): Promise<Record<string, unknown>[][]>;
-  executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>;
-  bulkInsert(
-    tableName: string,
-    columnMetas: Record<string, ColumnMeta>,
-    records: Record<string, unknown>[],
-  ): Promise<void>;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `config` | `DbConnConfig` | 연결 설정 |
-| `isConnected` | `boolean` | 연결 여부 |
-| `isInTransaction` | `boolean` | 트랜잭션 진행 여부 |
-| `connect()` | `Promise<void>` | DB 연결을 수립한다 |
-| `close()` | `Promise<void>` | DB 연결을 종료한다 |
-| `beginTransaction(isolationLevel?)` | `Promise<void>` | 트랜잭션을 시작한다 |
-| `commitTransaction()` | `Promise<void>` | 트랜잭션을 커밋한다 |
-| `rollbackTransaction()` | `Promise<void>` | 트랜잭션을 롤백한다 |
-| `execute(queries)` | `Promise<Record<string, unknown>[][]>` | SQL 쿼리 배열을 실행한다 |
-| `executeParametrized(query, params?)` | `Promise<Record<string, unknown>[][]>` | 파라미터화된 쿼리를 실행한다 |
-| `bulkInsert(tableName, columnMetas, records)` | `Promise<void>` | 네이티브 bulk API를 사용하여 대량 삽입한다 |
-
-`EventEmitter<{ close: void }>`를 상속하므로 연결 종료 시 `'close'` 이벤트를 수신할 수 있다.
-
-## `DbConnConfig`
-
-DB 연결 설정 discriminated union. `dialect` 필드로 구현체를 분기한다.
-
-```typescript
-type DbConnConfig = MysqlDbConnConfig | MssqlDbConnConfig | PostgresqlDbConnConfig;
-```
-
-## `MysqlDbConnConfig`
-
-MySQL 연결 설정.
-
-```typescript
-interface MysqlDbConnConfig {
-  dialect: "mysql";
-  host: string;
-  port?: number;
-  username: string;
-  password: string;
-  database?: string;
-  defaultIsolationLevel?: IsolationLevel;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `dialect` | `"mysql"` | Discriminant. 항상 `"mysql"` |
-| `host` | `string` | 호스트 주소 |
-| `port` | `number?` | 포트 (생략 시 mysql2 기본값 사용) |
-| `username` | `string` | 사용자 이름 |
-| `password` | `string` | 비밀번호 |
-| `database` | `string?` | 데이터베이스 이름 |
-| `defaultIsolationLevel` | `IsolationLevel?` | 기본 격리 수준 (미지정 시 `READ_UNCOMMITTED`) |
-
-## `MssqlDbConnConfig`
-
-MSSQL/Azure SQL 연결 설정.
-
-```typescript
-interface MssqlDbConnConfig {
-  dialect: "mssql" | "mssql-azure";
-  host: string;
-  port?: number;
-  username: string;
-  password: string;
-  database?: string;
-  schema?: string;
-  defaultIsolationLevel?: IsolationLevel;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `dialect` | `"mssql" \| "mssql-azure"` | Discriminant. `"mssql-azure"`인 경우 암호화 연결(encrypt)을 사용한다 |
-| `host` | `string` | 호스트 주소 |
-| `port` | `number?` | 포트 |
-| `username` | `string` | 사용자 이름 |
-| `password` | `string` | 비밀번호 |
-| `database` | `string?` | 데이터베이스 이름 |
-| `schema` | `string?` | 스키마 이름 |
-| `defaultIsolationLevel` | `IsolationLevel?` | 기본 격리 수준 (미지정 시 `READ_UNCOMMITTED`) |
-
-## `PostgresqlDbConnConfig`
-
-PostgreSQL 연결 설정.
-
-```typescript
-interface PostgresqlDbConnConfig {
-  dialect: "postgresql";
-  host: string;
-  port?: number;
-  username: string;
-  password: string;
-  database?: string;
-  schema?: string;
-  defaultIsolationLevel?: IsolationLevel;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `dialect` | `"postgresql"` | Discriminant. 항상 `"postgresql"` |
-| `host` | `string` | 호스트 주소 |
-| `port` | `number?` | 포트 (미지정 시 `5432`) |
-| `username` | `string` | 사용자 이름 |
-| `password` | `string` | 비밀번호 |
-| `database` | `string?` | 데이터베이스 이름 |
-| `schema` | `string?` | 스키마 이름 |
-| `defaultIsolationLevel` | `IsolationLevel?` | 기본 격리 수준 (미지정 시 `READ_UNCOMMITTED`) |
-
-## `DB_CONN_CONNECT_TIMEOUT`
-
-DB 연결 수립 타임아웃 (10초).
-
-```typescript
-const DB_CONN_CONNECT_TIMEOUT = 10 * 1000; // 10_000ms
-```
-
-## `DB_CONN_DEFAULT_TIMEOUT`
-
-DB 쿼리 기본 타임아웃 (10분). 유휴 연결 자동 종료 타이머는 이 값의 2배 후 `close()`를 호출한다.
-
-```typescript
-const DB_CONN_DEFAULT_TIMEOUT = 10 * 60 * 1000; // 600_000ms
-```
-
-## `DB_CONN_ERRORS`
-
-DB 연결 관련 오류 메시지 상수.
-
-```typescript
-const DB_CONN_ERRORS = {
-  NOT_CONNECTED: "'Connection'이 연결되어 있지 않습니다.",
-  ALREADY_CONNECTED: "'Connection'이 이미 연결되어 있습니다.",
-} as const;
-```
-
-| Key | Value |
-|-----|-------|
-| `NOT_CONNECTED` | `"'Connection'이 연결되어 있지 않습니다."` |
-| `ALREADY_CONNECTED` | `"'Connection'이 이미 연결되어 있습니다."` |
-
-## `getDialectFromConfig`
-
-`DbConnConfig`에서 정규화된 `Dialect`를 추출한다.
-
-```typescript
-function getDialectFromConfig(config: DbConnConfig): Dialect;
-```
-
-`"mssql-azure"` → `"mssql"`로 변환하고, 나머지(`"mysql"`, `"mssql"`, `"postgresql"`)는 `config.dialect`를 그대로 반환한다.