@simplysm/orm-common 13.0.99 → 14.0.1

package/src/types/db.ts

@@ -3,11 +3,11 @@ import type { QueryDef } from "./query-def";
 import type { DbContextBase, DbContextDdlMethods } from "./db-context-def";
 
 // ============================================
-// Database Types
+// Database 타입
 // ============================================
 
 /**
- * Supported Database dialects
+ * 지원하는 Database dialect
  *
  * - `mysql`: MySQL 8.0.14+
  * - `mssql`: Microsoft SQL Server 2012+
@@ -16,9 +16,9 @@ import type { DbContextBase, DbContextDdlMethods } from "./db-context-def";
 export type Dialect = "mysql" | "mssql" | "postgresql";
 
 /**
- * List of all supported Database dialects
+ * 지원하는 모든 Database dialect 목록
  *
- * Used for per-dialect validation in testing
+ * 테스트에서 dialect별 검증에 사용
  *
  * @example
  * ```typescript
@@ -31,16 +31,16 @@ export type Dialect = "mysql" | "mssql" | "postgresql";
 export const dialects: Dialect[] = ["mysql", "mssql", "postgresql"];
 
 /**
- * QueryBuilder.build() return type
+ * QueryBuilder.build() 반환 타입
  *
- * Built SQL string and metadata for multiple result set processing
+ * 빌드된 SQL 문자열과 다중 결과 셋 처리를 위한 메타데이터
  *
- * @property sql - Built SQL string
- * @property resultSetIndex - Result set index to fetch results from (default: 0)
- *   - MySQL INSERT with OUTPUT: 1 (SELECT from INSERT + SELECT)
- * @property resultSetStride - Extract every Nth result set from multiple results
- *   - Example: index=1, stride=2 -> returns result sets 1, 3, 5, 7...
- *   - MySQL multiple INSERT: INSERT;SELECT; x N -> 1, 3, 5...
+ * @property sql - 빌드된 SQL 문자열
+ * @property resultSetIndex - 결과를 가져올 결과 셋 index (기본값: 0)
+ *   - MySQL INSERT with OUTPUT: 1 (INSERT + SELECT에서 SELECT)
+ * @property resultSetStride - 다중 결과에서 N번째마다 결과 셋 추출
+ *   - 예: index=1, stride=2 -> 결과 셋 1, 3, 5, 7... 반환
+ *   - MySQL 다중 INSERT: INSERT;SELECT; x N -> 1, 3, 5...
  */
 export interface QueryBuildResult {
   sql: string;
@@ -49,12 +49,12 @@ export interface QueryBuildResult {
 }
 
 /**
- * Transaction isolation level
+ * 트랜잭션 격리 수준
  *
- * - `READ_UNCOMMITTED`: Can read uncommitted data (Dirty Read)
- * - `READ_COMMITTED`: Read only committed data (default)
- * - `REPEATABLE_READ`: Guarantees same query returns same result within transaction
- * - `SERIALIZABLE`: Full serialization (most strict)
+ * - `READ_UNCOMMITTED`: 커밋되지 않은 데이터 읽기 가능 (Dirty Read)
+ * - `READ_COMMITTED`: 커밋된 데이터만 읽기 (기본값)
+ * - `REPEATABLE_READ`: 트랜잭션 내 동일 query가 동일 결과 반환 보장
+ * - `SERIALIZABLE`: 완전 직렬화 (가장 엄격)
  */
 export type IsolationLevel =
   | "READ_UNCOMMITTED"
@@ -63,25 +63,25 @@ export type IsolationLevel =
   | "SERIALIZABLE";
 
 // ============================================
-// DataRecord - Result data type (recursive, nesting allowed)
+// DataRecord - 결과 데이터 타입 (재귀적, 중첩 허용)
 // ============================================
 
 /**
- * Query result data record type
+ * Query 결과 데이터 레코드 타입
  *
- * Represents nested relation (include) results with recursive structure
+ * 재귀적 구조로 중첩 관계(include) 결과를 표현
  *
  * @example
  * ```typescript
- * // Simple record
+ * // 단순 레코드
  * type User = { id: number; name: string; }
  *
- * // Nested relation include
+ * // 중첩 관계 include
  * type UserWithPosts = {
  *   id: number;
  *   name: string;
- *   posts: { id: number; title: string; }[]  // 1:N relationship
- *   company: { id: number; name: string; }   // N:1 relationship
+ *   posts: { id: number; title: string; }[]  // 1:N 관계
+ *   company: { id: number; name: string; }   // N:1 관계
  * }
  * ```
  */
@@ -90,18 +90,18 @@ export type DataRecord = {
 };
 
 // ============================================
-// Executor Interface
+// Executor 인터페이스
 // ============================================
 
 /**
- * DbContext executor interface
+ * DbContext executor 인터페이스
  *
- * Responsible for actual DB connection and query execution
- * Implemented by NodeDbContextExecutor (server) or SdOrmServiceClientDbContextExecutor (client)
+ * 실제 DB 연결과 query 실행을 담당
+ * NodeDbContextExecutor(서버) 또는 SdOrmServiceClientDbContextExecutor(클라이언트)로 구현
  *
  * @example
  * ```typescript
- * // Server-side implementation example
+ * // 서버 측 구현 예시
  * class NodeDbContextExecutor implements IDbContextExecutor {
  *   async connect(): Promise<void> {
  *     await this.connection.connect();
@@ -110,43 +110,43 @@ export type DataRecord = {
  * }
  * ```
  *
- * @see {@link DbContext} Used in DbContext
+ * @see {@link DbContext} DbContext에서 사용
  */
 export interface DbContextExecutor {
   /**
-   * Establish DB connection
+   * DB 연결 수립
    */
   connect(): Promise<void>;
 
   /**
-   * Close DB connection
+   * DB 연결 종료
    */
   close(): Promise<void>;
 
   /**
-   * Begin transaction
+   * 트랜잭션 시작
    *
-   * @param isolationLevel - Isolation level (optional)
+   * @param isolationLevel - 격리 수준 (선택)
    */
   beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
 
   /**
-   * Commit transaction
+   * 트랜잭션 커밋
    */
   commitTransaction(): Promise<void>;
 
   /**
-   * Rollback transaction
+   * 트랜잭션 롤백
    */
   rollbackTransaction(): Promise<void>;
 
   /**
-   * Execute QueryDef array
+   * QueryDef 배열 실행
    *
-   * @template T - Result record type
-   * @param defs - QueryDef array to execute
-   * @param resultMetas - Metadata for result transformation (optional)
-   * @returns Array of result arrays per QueryDef
+   * @template T - 결과 레코드 타입
+   * @param defs - 실행할 QueryDef 배열
+   * @param resultMetas - 결과 변환용 메타데이터 (선택)
+   * @returns QueryDef별 결과 배열의 배열
    */
   executeDefs<T = DataRecord>(
     defs: QueryDef[],
@@ -155,12 +155,12 @@ export interface DbContextExecutor {
 }
 
 /**
- * Metadata for query result transformation
+ * Query 결과 변환용 메타데이터
  *
- * Used when transforming SELECT results into TypeScript objects
+ * SELECT 결과를 TypeScript 객체로 변환할 때 사용
  *
- * @property columns - Column name -> ColumnPrimitiveStr mapping
- * @property joins - JOIN alias -> single/array indicator
+ * @property columns - Column 이름 -> ColumnPrimitiveStr 매핑
+ * @property joins - JOIN alias -> 단일/배열 구분자
  */
 export interface ResultMeta {
   columns: Record<string, ColumnPrimitiveStr>;
@@ -172,12 +172,12 @@ export interface ResultMeta {
 // ============================================
 
 /**
- * Database migration definition
+ * Database migration 정의
  *
- * Version-control schema changes
+ * Schema 변경을 버전 관리
  *
- * @property name - Unique Migration name (timestamp recommended)
- * @property up - Migration execution function
+ * @property name - 고유 Migration 이름 (타임스탬프 권장)
+ * @property up - Migration 실행 함수
  *
  * @example
  * ```typescript
@@ -200,7 +200,7 @@ export interface ResultMeta {
  * ];
  * ```
  *
- * @see {@link DbContext.initialize} migration execution
+ * @see {@link DbContext.initialize} migration 실행
  */
 export interface Migration {
   name: string;