@simplysm/orm-node 13.0.69 → 13.0.70

package/src/pooled-db-conn.ts

@@ -7,13 +7,13 @@ import { DB_CONN_ERRORS, type DbConn, type DbConnConfig } from "./types/db-conn"
 const logger = consola.withTag("pooled-db-conn");
 
 /**
- * 커넥션 풀에서 관리되는 DB 연결 래퍼
+ * DB connection wrapper managed by connection pool
  *
- * generic-pool 라이브러리를 사용하여 커넥션 풀링을 지원한다.
- * 실제 물리 연결은 풀에서 획득하고 반환한다.
+ * Supports connection pooling using the generic-pool library.
+ * Acquires and returns actual physical connections from/to the pool.
  */
 export class PooledDbConn extends EventEmitter<{ close: void }> implements DbConn {
-  // 풀에서 빌려온 실제 물리 커넥션
+  // Actual physical connection borrowed from pool
   private _rawConn?: DbConn;
 
   constructor(
@@ -40,16 +40,16 @@ export class PooledDbConn extends EventEmitter<{ close: void }> implements DbCon
   }
 
   /**
-   * 풀에서 DB 연결을 획득한다.
+   * Acquire DB connection from pool
    *
-   * @throws {SdError} 이미 연결된 상태일 때
+   * @throws {SdError} When already connected
    */
   async connect(): Promise<void> {
     if (this._rawConn != null) {
       throw new SdError(DB_CONN_ERRORS.ALREADY_CONNECTED);
     }
 
-    // 1. 풀에서 커넥션 획득
+    // 1. Acquire connection from pool
     try {
       this._rawConn = await this._pool.acquire();
     } catch (err) {
@@ -57,57 +57,57 @@ export class PooledDbConn extends EventEmitter<{ close: void }> implements DbCon
       const cause = this._getLastCreateError?.() ?? (err instanceof Error ? err : undefined);
       throw new SdError(
         ...(cause != null ? [cause] : []),
-        `DB 연결 실패 [${dialect}://${host}:${port ?? ""}/${database ?? ""}]`,
+        `DB connection failed [${dialect}://${host}:${port ?? ""}/${database ?? ""}]`,
       );
     }
 
-    // 2. 물리 연결이 (타임아웃 등으로) 끊어질 경우를 대비해 리스너 등록
-    //    만약 사용 중에 끊기면 PooledDbConn도 close 이벤트를 발생시켜야 함
+    // 2. Register listener to handle physical connection loss (timeout, etc.)
+    //    If connection disconnects while in use, PooledDbConn must emit close event
     this._rawConn.on("close", this._onRawConnClose);
   }
 
   /**
-   * 풀에 DB 연결을 반환한다. (실제 연결을 종료하지 않음)
+   * Return DB connection to pool (does not terminate actual connection)
    */
   async close(): Promise<void> {
     if (this._rawConn != null) {
-      // 1. 트랜잭션 진행 중이면 롤백하여 깨끗한 상태로 풀에 반환
+      // 1. If transaction is in progress, rollback to return clean state to pool
       if (this._rawConn.isInTransaction) {
         try {
           await this._rawConn.rollbackTransaction();
         } catch (err) {
-          // 롤백 실패 시 로그만 남기고 계속 진행 (연결이 이미 끊긴 경우 등)
-          logger.warn("풀 반환 시 롤백 실패", err instanceof Error ? err.message : String(err));
+          // Log failure and continue (connection may already be disconnected)
+          logger.warn("Rollback failed when returning to pool", err instanceof Error ? err.message : String(err));
         }
       }
 
-      // 2. 리스너 해제 (Pool에 돌아가서 다른 래퍼에 의해 재사용될 때 영향 주지 않도록)
+      // 2. Remove listener (so it won't affect reuse by other wrappers when returned to pool)
       this._rawConn.off("close", this._onRawConnClose);
 
-      // 3. 풀에 커넥션 반환 (실제로 끊지 않음)
+      // 3. Return connection to pool (does not actually close it)
       await this._pool.release(this._rawConn);
       this._rawConn = undefined;
 
-      // 4. 소비자에게 논리적으로 연결이 닫혔음을 알림
+      // 4. Notify consumer that connection is logically closed
       this.emit("close");
     }
   }
 
-  // 물리 연결이 끊겼을 때 처리 핸들러
+  // Handler for physical connection loss
   private readonly _onRawConnClose = () => {
-    // 물리 연결이 끊겼으므로 참조 제거 (Pool에서는 validate 시점에 걸러낼 것임)
+    // Remove reference since physical connection is lost (will be filtered during pool validation)
     this._rawConn = undefined;
-    // 소비자에게 알림
+    // Notify consumer
     this.emit("close");
   };
 
-  // --- 아래는 위임(Delegation) 메소드 ---
+  // --- Below are delegation methods ---
 
   /**
-   * 트랜잭션 시작
+   * Begin transaction
    *
-   * @param isolationLevel - 트랜잭션 격리 수준
-   * @throws {SdError} 연결이 획득되지 않은 상태일 때
+   * @param isolationLevel - Transaction isolation level
+   * @throws {SdError} When connection is not acquired
    */
   async beginTransaction(isolationLevel?: IsolationLevel): Promise<void> {
     const conn = this._requireRawConn();
@@ -115,9 +115,9 @@ export class PooledDbConn extends EventEmitter<{ close: void }> implements DbCon
   }
 
   /**
-   * 트랜잭션 커밋
+   * Commit transaction
    *
-   * @throws {SdError} 연결이 획득되지 않은 상태일 때
+   * @throws {SdError} When connection is not acquired
    */
   async commitTransaction(): Promise<void> {
     const conn = this._requireRawConn();
@@ -125,9 +125,9 @@ export class PooledDbConn extends EventEmitter<{ close: void }> implements DbCon
   }
 
   /**
-   * 트랜잭션 롤백
+   * Rollback transaction
    *
-   * @throws {SdError} 연결이 획득되지 않은 상태일 때
+   * @throws {SdError} When connection is not acquired
    */
   async rollbackTransaction(): Promise<void> {
     const conn = this._requireRawConn();
@@ -135,11 +135,11 @@ export class PooledDbConn extends EventEmitter<{ close: void }> implements DbCon
   }
 
   /**
-   * SQL 쿼리 실행
+   * Execute SQL query
    *
-   * @param queries - 실행할 SQL 쿼리 배열
-   * @returns 각 쿼리의 결과 배열
-   * @throws {SdError} 연결이 획득되지 않은 상태일 때
+   * @param queries - SQL query array to execute
+   * @returns Result array for each query
+   * @throws {SdError} When connection is not acquired
    */
   async execute(queries: string[]): Promise<Record<string, unknown>[][]> {
     const conn = this._requireRawConn();
@@ -147,12 +147,12 @@ export class PooledDbConn extends EventEmitter<{ close: void }> implements DbCon
   }
 
   /**
-   * 파라미터화된 SQL 쿼리 실행
+   * Execute parameterized SQL query
    *
-   * @param query - SQL 쿼리 문자열
-   * @param params - 쿼리 파라미터 배열
-   * @returns 쿼리 결과 배열
-   * @throws {SdError} 연결이 획득되지 않은 상태일 때
+   * @param query - SQL query string
+   * @param params - Query parameter array
+   * @returns Query result array
+   * @throws {SdError} When connection is not acquired
    */
   async executeParametrized(
     query: string,
@@ -163,12 +163,12 @@ export class PooledDbConn extends EventEmitter<{ close: void }> implements DbCon
   }
 
   /**
-   * 대량 데이터 삽입 (네이티브 벌크 API 사용)
+   * Bulk insert data (using native bulk API)
    *
-   * @param tableName - 대상 테이블명
-   * @param columnMetas - 컬럼 메타데이터
-   * @param records - 삽입할 레코드 배열
-   * @throws {SdError} 연결이 획득되지 않은 상태일 때
+   * @param tableName - Target table name
+   * @param columnMetas - Column metadata
+   * @param records - Record array to insert
+   * @throws {SdError} When connection is not acquired
    */
   async bulkInsert(
     tableName: string,

package/src/types/db-conn.ts

@@ -2,25 +2,25 @@ import type { EventEmitter } from "@simplysm/core-common";
 import type { ColumnMeta, Dialect, IsolationLevel } from "@simplysm/orm-common";
 
 // ============================================
-// 공통 상수
+// Common constants
 // ============================================
 
 /**
- * DB 연결 수립 타임아웃 (10초)
+ * DB connection establishment timeout (10 seconds)
  */
 export const DB_CONN_CONNECT_TIMEOUT = 10 * 1000;
 
 /**
- * DB 쿼리 기본 타임아웃 (10분)
+ * DB query default timeout (10 minutes)
  */
 export const DB_CONN_DEFAULT_TIMEOUT = 10 * 60 * 1000;
 
 /**
- * DB 연결 에러 메시지
+ * DB connection error messages
  */
 export const DB_CONN_ERRORS = {
-  NOT_CONNECTED: "'Connection'이 연결되어있지 않습니다.",
-  ALREADY_CONNECTED: "이미 'Connection'이 연결되어있습니다.",
+  NOT_CONNECTED: "'Connection' is not connected.",
+  ALREADY_CONNECTED: "'Connection' is already connected.",
 } as const;
 
 // ============================================
@@ -28,86 +28,86 @@ export const DB_CONN_ERRORS = {
 // ============================================
 
 /**
- * 저수준 DB 연결 인터페이스
+ * Low-level DB connection interface
  *
- * 각 DBMS별 구현체가 이 인터페이스를 구현합니다.
- * - {@link MysqlDbConn} - MySQL 연결
- * - {@link MssqlDbConn} - MSSQL 연결
- * - {@link PostgresqlDbConn} - PostgreSQL 연결
+ * Implementations for each DBMS implement this interface.
+ * - {@link MysqlDbConn} - MySQL connection
+ * - {@link MssqlDbConn} - MSSQL connection
+ * - {@link PostgresqlDbConn} - PostgreSQL connection
  *
  * @remarks
- * SdEventEmitter를 상속하여 'close' 이벤트를 발생시킵니다.
+ * Inherits from EventEmitter and emits 'close' events.
  */
 export interface DbConn extends EventEmitter<{ close: void }> {
   /**
-   * 연결 설정
+   * Connection configuration
    */
   config: DbConnConfig;
 
   /**
-   * 연결 여부
+   * Whether connected
    */
   isConnected: boolean;
 
   /**
-   * 트랜잭션 진행 여부
+   * Whether transaction is in progress
    */
   isInTransaction: boolean;
 
   /**
-   * DB 연결 수립
+   * Establish DB connection
    */
   connect(): Promise<void>;
 
   /**
-   * DB 연결 종료
+   * Close DB connection
    */
   close(): Promise<void>;
 
   /**
-   * 트랜잭션 시작
+   * Begin transaction
    *
-   * @param isolationLevel - 격리 수준 (선택)
+   * @param isolationLevel - Isolation level (optional)
    */
   beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
 
   /**
-   * 트랜잭션 커밋
+   * Commit transaction
    */
   commitTransaction(): Promise<void>;
 
   /**
-   * 트랜잭션 롤백
+   * Rollback transaction
    */
   rollbackTransaction(): Promise<void>;
 
   /**
-   * SQL 쿼리 배열 실행
+   * Execute SQL query array
    *
-   * @param queries - 실행할 SQL 문자열 배열
-   * @returns 각 쿼리별 결과 배열의 배열
+   * @param queries - SQL string array to execute
+   * @returns Array of result arrays for each query
    */
   execute(queries: string[]): Promise<Record<string, unknown>[][]>;
 
   /**
-   * 파라미터화된 쿼리 실행
+   * Execute parameterized query
    *
-   * @param query - SQL 쿼리 문자열
-   * @param params - 바인딩 파라미터 (선택)
-   * @returns 결과 배열의 배열
+   * @param query - SQL query string
+   * @param params - Binding parameters (optional)
+   * @returns Array of result arrays
    */
   executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>;
 
   /**
-   * 대량 INSERT (네이티브 벌크 API 사용)
+   * Bulk INSERT (using native bulk API)
    *
    * - MSSQL: tedious BulkLoad
-   * - MySQL: LOAD DATA LOCAL INFILE (임시 파일)
+   * - MySQL: LOAD DATA LOCAL INFILE (temporary file)
    * - PostgreSQL: COPY FROM STDIN
    *
-   * @param tableName - 테이블명 (database.table 또는 database.schema.table)
-   * @param columnMetas - 컬럼명 → ColumnMeta 매핑
-   * @param records - 삽입할 레코드 배열
+   * @param tableName - Table name (database.table or database.schema.table)
+   * @param columnMetas - Column name → ColumnMeta mapping
+   * @param records - Record array to insert
    */
   bulkInsert(
     tableName: string,
@@ -121,33 +121,33 @@ export interface DbConn extends EventEmitter<{ close: void }> {
 // ============================================
 
 /**
- * 커넥션 풀 설정
+ * Connection pool configuration
  *
  * @remarks
- * 각 값의 기본값:
- * - min: 1 (최소 연결 수)
- * - max: 10 (최대 연결 수)
- * - acquireTimeoutMillis: 30000 (연결 획득 타임아웃)
- * - idleTimeoutMillis: 30000 (유휴 연결 타임아웃)
+ * Default values for each setting:
+ * - min: 1 (minimum connection count)
+ * - max: 10 (maximum connection count)
+ * - acquireTimeoutMillis: 30000 (connection acquisition timeout)
+ * - idleTimeoutMillis: 30000 (idle connection timeout)
  */
 export interface DbPoolConfig {
-  /** 최소 연결 수 (기본: 1) */
+  /** Minimum connection count (default: 1) */
   min?: number;
-  /** 최대 연결 수 (기본: 10) */
+  /** Maximum connection count (default: 10) */
   max?: number;
-  /** 연결 획득 타임아웃 (밀리초, 기본: 30000) */
+  /** Connection acquisition timeout (milliseconds, default: 30000) */
   acquireTimeoutMillis?: number;
-  /** 유휴 연결 타임아웃 (밀리초, 기본: 30000) */
+  /** Idle connection timeout (milliseconds, default: 30000) */
   idleTimeoutMillis?: number;
 }
 
 /**
- * DB 연결 설정 타입 (dialect별 분기)
+ * DB connection configuration type (branching by dialect)
  */
 export type DbConnConfig = MysqlDbConnConfig | MssqlDbConnConfig | PostgresqlDbConnConfig;
 
 /**
- * MySQL 연결 설정
+ * MySQL connection configuration
  */
 export interface MysqlDbConnConfig {
   dialect: "mysql";
@@ -161,7 +161,7 @@ export interface MysqlDbConnConfig {
 }
 
 /**
- * MSSQL 연결 설정
+ * MSSQL connection configuration
  */
 export interface MssqlDbConnConfig {
   dialect: "mssql" | "mssql-azure";
@@ -176,7 +176,7 @@ export interface MssqlDbConnConfig {
 }
 
 /**
- * PostgreSQL 연결 설정
+ * PostgreSQL connection configuration
  */
 export interface PostgresqlDbConnConfig {
   dialect: "postgresql";
@@ -191,7 +191,7 @@ export interface PostgresqlDbConnConfig {
 }
 
 /**
- * DbConnConfig에서 Dialect 추출
+ * Extract Dialect from DbConnConfig
  */
 export function getDialectFromConfig(config: DbConnConfig): Dialect {
   if (config.dialect === "mssql-azure") {