@simplysm/orm-node 13.0.0-beta.6

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

@@ -0,0 +1,162 @@
+import { SdError } from "@simplysm/core-common";
+import type {
+  DbContextExecutor,
+  IsolationLevel,
+  QueryDef,
+  ResultMeta,
+  Dialect,
+  ColumnMeta,
+  DataRecord,
+} from "@simplysm/orm-common";
+import { createQueryBuilder, parseQueryResult } from "@simplysm/orm-common";
+import type { DbConn, DbConnConfig } from "./types/db-conn";
+import { DB_CONN_ERRORS, getDialectFromConfig } from "./types/db-conn";
+import { DbConnFactory } from "./db-conn-factory";
+
+/**
+ * Node.js 환경용 DbContextExecutor
+ *
+ * DbContext에서 사용하는 실행기로, 실제 DB 연결을 담당한다.
+ */
+export class NodeDbContextExecutor implements DbContextExecutor {
+  private _conn?: DbConn;
+  private readonly _dialect: Dialect;
+
+  constructor(private readonly _config: DbConnConfig) {
+    this._dialect = getDialectFromConfig(_config);
+  }
+
+  /**
+   * DB 연결 수립
+   *
+   * 커넥션 풀에서 연결을 획득하고 연결 상태를 활성화한다.
+   */
+  async connect(): Promise<void> {
+    this._conn = await DbConnFactory.create(this._config);
+    await this._conn.connect();
+  }
+
+  /**
+   * DB 연결 종료
+   *
+   * 커넥션 풀에 연결을 반환한다.
+   *
+   * @throws {Error} 연결되지 않은 상태일 때
+   */
+  async close(): Promise<void> {
+    const conn = this._requireConn();
+    await conn.close();
+    this._conn = undefined;
+  }
+
+  /**
+   * 트랜잭션 시작
+   *
+   * @param isolationLevel - 트랜잭션 격리 수준
+   * @throws {Error} 연결되지 않은 상태일 때
+   */
+  async beginTransaction(isolationLevel?: IsolationLevel): Promise<void> {
+    const conn = this._requireConn();
+    await conn.beginTransaction(isolationLevel);
+  }
+
+  /**
+   * 트랜잭션 커밋
+   *
+   * @throws {Error} 연결되지 않은 상태일 때
+   */
+  async commitTransaction(): Promise<void> {
+    const conn = this._requireConn();
+    await conn.commitTransaction();
+  }
+
+  /**
+   * 트랜잭션 롤백
+   *
+   * @throws {Error} 연결되지 않은 상태일 때
+   */
+  async rollbackTransaction(): Promise<void> {
+    const conn = this._requireConn();
+    await conn.rollbackTransaction();
+  }
+
+  /**
+   * 파라미터화된 쿼리 실행
+   *
+   * @param query - SQL 쿼리 문자열
+   * @param params - 쿼리 파라미터 배열
+   * @returns 쿼리 결과 배열
+   * @throws {Error} 연결되지 않은 상태일 때
+   */
+  async executeParametrized(query: string, params?: unknown[]): Promise<unknown[][]> {
+    const conn = this._requireConn();
+    return conn.executeParametrized(query, params);
+  }
+
+  /**
+   * 대량 데이터 삽입 (네이티브 벌크 API 사용)
+   *
+   * @param tableName - 대상 테이블명
+   * @param columnMetas - 컬럼 메타데이터
+   * @param records - 삽입할 레코드 배열
+   * @throws {Error} 연결되지 않은 상태일 때
+   */
+  async bulkInsert(tableName: string, columnMetas: Record<string, ColumnMeta>, records: DataRecord[]): Promise<void> {
+    const conn = this._requireConn();
+    await conn.bulkInsert(tableName, columnMetas, records);
+  }
+
+  /**
+   * QueryDef 배열 실행
+   *
+   * QueryDef를 SQL로 변환하여 실행하고, ResultMeta를 사용하여 결과를 파싱한다.
+   *
+   * @param defs - 실행할 QueryDef 배열
+   * @param resultMetas - 결과 파싱용 메타데이터 배열 (타입 변환에 사용)
+   * @returns 각 QueryDef의 실행 결과 배열
+   * @throws {Error} 연결되지 않은 상태일 때
+   */
+  async executeDefs<T = DataRecord>(defs: QueryDef[], resultMetas?: (ResultMeta | undefined)[]): Promise<T[][]> {
+    const conn = this._requireConn();
+
+    const builder = createQueryBuilder(this._dialect);
+
+    // 가져올 데이터가 없는 것으로 옵션 설정을 했을 때, 하나의 쿼리로 한번의 요청 보냄
+    // 결과가 필요 없으므로 defs.length개의 빈 배열을 반환하여 인터페이스 계약 유지
+    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[][];
+    }
+
+    // 각 def를 개별 실행
+    const results: T[][] = [];
+    for (let i = 0; i < defs.length; i++) {
+      const def = defs[i];
+      const meta = resultMetas?.[i];
+      const buildResult = builder.build(def);
+
+      const rawResults = await conn.execute([buildResult.sql]);
+
+      // resultSetIndex가 지정된 경우 해당 인덱스의 결과셋 사용
+      const targetResultSet =
+        buildResult.resultSetIndex != null ? rawResults[buildResult.resultSetIndex] : rawResults[0];
+
+      if (meta != null) {
+        const parsed = await parseQueryResult<T>(targetResultSet as Record<string, unknown>[], meta);
+        results.push(parsed ?? []);
+      } else {
+        results.push(targetResultSet as T[]);
+      }
+    }
+
+    return results;
+  }
+
+  private _requireConn(): DbConn {
+    if (this._conn == null) {
+      throw new SdError(DB_CONN_ERRORS.NOT_CONNECTED);
+    }
+    return this._conn;
+  }
+}

package/src/pooled-db-conn.ts

@@ -0,0 +1,175 @@
+import { createConsola } from "consola";
+import { SdError, EventEmitter } from "@simplysm/core-common";
+import type { Pool } from "generic-pool";
+import type { ColumnMeta, IsolationLevel } from "@simplysm/orm-common";
+import { DB_CONN_ERRORS, type DbConn, type DbConnConfig } from "./types/db-conn";
+
+const logger = createConsola().withTag("pooled-db-conn");
+
+/**
+ * 커넥션 풀에서 관리되는 DB 연결 래퍼
+ *
+ * generic-pool 라이브러리를 사용하여 커넥션 풀링을 지원한다.
+ * 실제 물리 연결은 풀에서 획득하고 반환한다.
+ */
+export class PooledDbConn extends EventEmitter<{ close: void }> implements DbConn {
+  // 풀에서 빌려온 실제 물리 커넥션
+  private _rawConn?: DbConn;
+
+  constructor(
+    private readonly _pool: Pool<DbConn>,
+    private readonly _initialConfig: DbConnConfig,
+  ) {
+    super();
+  }
+
+  // [Property] config
+  get config(): DbConnConfig {
+    return this._rawConn?.config ?? this._initialConfig;
+  }
+
+  // [Property] isConnected
+  get isConnected(): boolean {
+    return this._rawConn?.isConnected ?? false;
+  }
+
+  // [Property] isOnTransaction
+  get isOnTransaction(): boolean {
+    return this._rawConn?.isOnTransaction ?? false;
+  }
+
+  /**
+   * 풀에서 DB 연결을 획득한다.
+   *
+   * @throws {SdError} 이미 연결된 상태일 때
+   */
+  async connect(): Promise<void> {
+    if (this._rawConn != null) {
+      throw new SdError(DB_CONN_ERRORS.ALREADY_CONNECTED);
+    }
+
+    // 1. 풀에서 커넥션 획득
+    this._rawConn = await this._pool.acquire();
+
+    // 2. 물리 연결이 (타임아웃 등으로) 끊어질 경우를 대비해 리스너 등록
+    //    만약 사용 중에 끊기면 PooledDbConn도 close 이벤트를 발생시켜야 함
+    this._rawConn.on("close", this._onRawConnClose);
+  }
+
+  /**
+   * 풀에 DB 연결을 반환한다. (실제 연결을 종료하지 않음)
+   */
+  async close(): Promise<void> {
+    if (this._rawConn != null) {
+      // 1. 트랜잭션 진행 중이면 롤백하여 깨끗한 상태로 풀에 반환
+      if (this._rawConn.isOnTransaction) {
+        try {
+          await this._rawConn.rollbackTransaction();
+        } catch (err) {
+          // 롤백 실패 시 로그만 남기고 계속 진행 (연결이 이미 끊긴 경우 등)
+          logger.warn("풀 반환 시 롤백 실패", err instanceof Error ? err.message : String(err));
+        }
+      }
+
+      // 2. 리스너 해제 (Pool에 돌아가서 다른 래퍼에 의해 재사용될 때 영향 주지 않도록)
+      this._rawConn.off("close", this._onRawConnClose);
+
+      // 3. 풀에 커넥션 반환 (실제로 끊지 않음)
+      await this._pool.release(this._rawConn);
+      this._rawConn = undefined;
+
+      // 4. 소비자에게 논리적으로 연결이 닫혔음을 알림
+      this.emit("close");
+    }
+  }
+
+  // 물리 연결이 끊겼을 때 처리 핸들러
+  private readonly _onRawConnClose = () => {
+    // 물리 연결이 끊겼으므로 참조 제거 (Pool에서는 validate 시점에 걸러낼 것임)
+    this._rawConn = undefined;
+    // 소비자에게 알림
+    this.emit("close");
+  };
+
+  // --- 아래는 위임(Delegation) 메소드 ---
+
+  /**
+   * 트랜잭션 시작
+   *
+   * @param isolationLevel - 트랜잭션 격리 수준
+   * @throws {SdError} 연결이 획득되지 않은 상태일 때
+   */
+  async beginTransaction(isolationLevel?: IsolationLevel): Promise<void> {
+    const conn = this._requireRawConn();
+    await conn.beginTransaction(isolationLevel);
+  }
+
+  /**
+   * 트랜잭션 커밋
+   *
+   * @throws {SdError} 연결이 획득되지 않은 상태일 때
+   */
+  async commitTransaction(): Promise<void> {
+    const conn = this._requireRawConn();
+    await conn.commitTransaction();
+  }
+
+  /**
+   * 트랜잭션 롤백
+   *
+   * @throws {SdError} 연결이 획득되지 않은 상태일 때
+   */
+  async rollbackTransaction(): Promise<void> {
+    const conn = this._requireRawConn();
+    await conn.rollbackTransaction();
+  }
+
+  /**
+   * SQL 쿼리 실행
+   *
+   * @param queries - 실행할 SQL 쿼리 배열
+   * @returns 각 쿼리의 결과 배열
+   * @throws {SdError} 연결이 획득되지 않은 상태일 때
+   */
+  async execute(queries: string[]): Promise<unknown[][]> {
+    const conn = this._requireRawConn();
+    return conn.execute(queries);
+  }
+
+  /**
+   * 파라미터화된 SQL 쿼리 실행
+   *
+   * @param query - SQL 쿼리 문자열
+   * @param params - 쿼리 파라미터 배열
+   * @returns 쿼리 결과 배열
+   * @throws {SdError} 연결이 획득되지 않은 상태일 때
+   */
+  async executeParametrized(query: string, params?: unknown[]): Promise<unknown[][]> {
+    const conn = this._requireRawConn();
+    return conn.executeParametrized(query, params);
+  }
+
+  /**
+   * 대량 데이터 삽입 (네이티브 벌크 API 사용)
+   *
+   * @param tableName - 대상 테이블명
+   * @param columnMetas - 컬럼 메타데이터
+   * @param records - 삽입할 레코드 배열
+   * @throws {SdError} 연결이 획득되지 않은 상태일 때
+   */
+  async bulkInsert(
+    tableName: string,
+    columnMetas: Record<string, ColumnMeta>,
+    records: Record<string, unknown>[],
+  ): Promise<void> {
+    const conn = this._requireRawConn();
+    await conn.bulkInsert(tableName, columnMetas, records);
+  }
+
+  private _requireRawConn(): DbConn {
+    if (this._rawConn == null) {
+      throw new SdError(`${DB_CONN_ERRORS.NOT_CONNECTED} (Pool Connection is not acquired)`);
+    }
+    return this._rawConn;
+  }
+}

package/src/sd-orm.ts

@@ -0,0 +1,102 @@
+import type { DbContext, IsolationLevel } from "@simplysm/orm-common";
+import type { Type } from "@simplysm/core-common";
+import type { DbConnConfig } from "./types/db-conn";
+import { NodeDbContextExecutor } from "./node-db-context-executor";
+
+/**
+ * SdOrm 옵션
+ *
+ * DbConnConfig보다 우선 적용되는 DbContext 옵션
+ */
+export interface SdOrmOptions {
+  /**
+   * 데이터베이스 이름 (DbConnConfig의 database 대신 사용)
+   */
+  database?: string;
+
+  /**
+   * 스키마 이름 (MSSQL: dbo, PostgreSQL: public)
+   */
+  schema?: string;
+}
+
+/**
+ * Node.js ORM 클래스
+ *
+ * DbContext와 DB 연결을 관리하는 최상위 클래스입니다.
+ * DbContext 타입과 연결 설정을 받아 트랜잭션을 관리합니다.
+ *
+ * @example
+ * ```typescript
+ * class MyDb extends DbContext {
+ *   readonly user = queryable(this, User);
+ * }
+ *
+ * const orm = new SdOrm(MyDb, {
+ *   dialect: "mysql",
+ *   host: "localhost",
+ *   port: 3306,
+ *   username: "root",
+ *   password: "password",
+ *   database: "mydb",
+ * });
+ *
+ * // 트랜잭션 내에서 실행
+ * await orm.connect(async (db) => {
+ *   const users = await db.user().result();
+ *   return users;
+ * });
+ *
+ * // 트랜잭션 없이 실행
+ * await orm.connectWithoutTransaction(async (db) => {
+ *   const users = await db.user().result();
+ *   return users;
+ * });
+ * ```
+ */
+export class SdOrm<T extends DbContext> {
+  constructor(
+    readonly dbContextType: Type<T>,
+    readonly config: DbConnConfig,
+    readonly options?: SdOrmOptions,
+  ) {}
+
+  /**
+   * 트랜잭션 내에서 콜백 실행
+   *
+   * @param callback - DB 연결 후 실행할 콜백
+   * @param isolationLevel - 트랜잭션 격리 수준
+   * @returns 콜백 결과
+   */
+  async connect<R>(callback: (conn: T) => Promise<R>, isolationLevel?: IsolationLevel): Promise<R> {
+    const db = this._createDbContext();
+    return db.connect(async () => callback(db), isolationLevel);
+  }
+
+  /**
+   * 트랜잭션 없이 콜백 실행
+   *
+   * @param callback - DB 연결 후 실행할 콜백
+   * @returns 콜백 결과
+   */
+  async connectWithoutTransaction<R>(callback: (conn: T) => Promise<R>): Promise<R> {
+    const db = this._createDbContext();
+    return db.connectWithoutTransaction(async () => callback(db));
+  }
+
+  /**
+   * DbContext 인스턴스 생성
+   */
+  private _createDbContext(): T {
+    // database는 options에서 우선, 없으면 config에서
+    const database = this.options?.database ?? ("database" in this.config ? this.config.database : undefined);
+
+    // schema는 options에서 우선, 없으면 config에서
+    const schema = this.options?.schema ?? ("schema" in this.config ? this.config.schema : undefined);
+
+    return new this.dbContextType(new NodeDbContextExecutor(this.config), {
+      database,
+      schema,
+    });
+  }
+}

package/src/types/db-conn.ts

@@ -0,0 +1,196 @@
+import type { EventEmitter } from "@simplysm/core-common";
+import type { ColumnMeta, Dialect, IsolationLevel } from "@simplysm/orm-common";
+
+// ============================================
+// 공통 상수
+// ============================================
+
+/**
+ * DB 연결 기본 타임아웃 (10분)
+ */
+export const DB_CONN_DEFAULT_TIMEOUT = 10 * 60 * 1000;
+
+/**
+ * DB 연결 에러 메시지
+ */
+export const DB_CONN_ERRORS = {
+  NOT_CONNECTED: "'Connection'이 연결되어있지 않습니다.",
+  ALREADY_CONNECTED: "이미 'Connection'이 연결되어있습니다.",
+} as const;
+
+// ============================================
+// IDbConn Interface
+// ============================================
+
+/**
+ * 저수준 DB 연결 인터페이스
+ *
+ * 각 DBMS별 구현체가 이 인터페이스를 구현합니다.
+ * - {@link MysqlDbConn} - MySQL 연결
+ * - {@link MssqlDbConn} - MSSQL 연결
+ * - {@link PostgresqlDbConn} - PostgreSQL 연결
+ *
+ * @remarks
+ * SdEventEmitter를 상속하여 'close' 이벤트를 발생시킵니다.
+ */
+export interface DbConn extends EventEmitter<{ close: void }> {
+  /**
+   * 연결 설정
+   */
+  config: DbConnConfig;
+
+  /**
+   * 연결 여부
+   */
+  isConnected: boolean;
+
+  /**
+   * 트랜잭션 진행 여부
+   */
+  isOnTransaction: boolean;
+
+  /**
+   * DB 연결 수립
+   */
+  connect(): Promise<void>;
+
+  /**
+   * DB 연결 종료
+   */
+  close(): Promise<void>;
+
+  /**
+   * 트랜잭션 시작
+   *
+   * @param isolationLevel - 격리 수준 (선택)
+   */
+  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
+
+  /**
+   * 트랜잭션 커밋
+   */
+  commitTransaction(): Promise<void>;
+
+  /**
+   * 트랜잭션 롤백
+   */
+  rollbackTransaction(): Promise<void>;
+
+  /**
+   * SQL 쿼리 배열 실행
+   *
+   * @param queries - 실행할 SQL 문자열 배열
+   * @returns 각 쿼리별 결과 배열의 배열
+   */
+  execute(queries: string[]): Promise<unknown[][]>;
+
+  /**
+   * 파라미터화된 쿼리 실행
+   *
+   * @param query - SQL 쿼리 문자열
+   * @param params - 바인딩 파라미터 (선택)
+   * @returns 결과 배열의 배열
+   */
+  executeParametrized(query: string, params?: unknown[]): Promise<unknown[][]>;
+
+  /**
+   * 대량 INSERT (네이티브 벌크 API 사용)
+   *
+   * - MSSQL: tedious BulkLoad
+   * - MySQL: LOAD DATA LOCAL INFILE (임시 파일)
+   * - PostgreSQL: COPY FROM STDIN
+   *
+   * @param tableName - 테이블명 (database.table 또는 database.schema.table)
+   * @param columnMetas - 컬럼명 → ColumnMeta 매핑
+   * @param records - 삽입할 레코드 배열
+   */
+  bulkInsert(
+    tableName: string,
+    columnMetas: Record<string, ColumnMeta>,
+    records: Record<string, unknown>[],
+  ): Promise<void>;
+}
+
+// ============================================
+// DbConnConfig Types
+// ============================================
+
+/**
+ * 커넥션 풀 설정
+ *
+ * @remarks
+ * 각 값의 기본값:
+ * - min: 1 (최소 연결 수)
+ * - max: 10 (최대 연결 수)
+ * - acquireTimeoutMillis: 30000 (연결 획득 타임아웃)
+ * - idleTimeoutMillis: 30000 (유휴 연결 타임아웃)
+ */
+export interface DbPoolConfig {
+  /** 최소 연결 수 (기본: 1) */
+  min?: number;
+  /** 최대 연결 수 (기본: 10) */
+  max?: number;
+  /** 연결 획득 타임아웃 (밀리초, 기본: 30000) */
+  acquireTimeoutMillis?: number;
+  /** 유휴 연결 타임아웃 (밀리초, 기본: 30000) */
+  idleTimeoutMillis?: number;
+}
+
+/**
+ * DB 연결 설정 타입 (dialect별 분기)
+ */
+export type DbConnConfig = MysqlDbConnConfig | MssqlDbConnConfig | PostgresqlDbConnConfig;
+
+/**
+ * MySQL 연결 설정
+ */
+export interface MysqlDbConnConfig {
+  dialect: "mysql";
+  host: string;
+  port?: number;
+  username: string;
+  password: string;
+  database?: string;
+  defaultIsolationLevel?: IsolationLevel;
+  pool?: DbPoolConfig;
+}
+
+/**
+ * MSSQL 연결 설정
+ */
+export interface MssqlDbConnConfig {
+  dialect: "mssql" | "mssql-azure";
+  host: string;
+  port?: number;
+  username: string;
+  password: string;
+  database?: string;
+  schema?: string;
+  defaultIsolationLevel?: IsolationLevel;
+  pool?: DbPoolConfig;
+}
+
+/**
+ * PostgreSQL 연결 설정
+ */
+export interface PostgresqlDbConnConfig {
+  dialect: "postgresql";
+  host: string;
+  port?: number;
+  username: string;
+  password: string;
+  database?: string;
+  schema?: string;
+  defaultIsolationLevel?: IsolationLevel;
+  pool?: DbPoolConfig;
+}
+
+/**
+ * DbConnConfig에서 Dialect 추출
+ */
+export function getDialectFromConfig(config: DbConnConfig): Dialect {
+  if (config.dialect === "mssql-azure") {
+    return "mssql";
+  }
+  return config.dialect;
+}