@simplysm/orm-common 14.0.48 → 14.0.50

package/src/schema/factory/relation-builder.ts

@@ -36,8 +36,8 @@ import type { ViewBuilder } from "../view-builder";
  * @see {@link RelationKeyBuilder} DB FK 없는 관계
  */
 export class ForeignKeyBuilder<
-  TOwner extends TableBuilder<any, any>,
-  TTargetFn extends () => TableBuilder<any, any>,
+  TOwner extends TableBuilder<any, any, any>,
+  TTargetFn extends () => TableBuilder<any, any, any>,
 > {
   /**
    * @param meta - FK 메타데이터
@@ -91,7 +91,7 @@ export class ForeignKeyBuilder<
  * @see {@link ForeignKeyBuilder} FK builder
  */
 export class ForeignKeyTargetBuilder<
-  TTargetTableFn extends () => TableBuilder<any, any>,
+  TTargetTableFn extends () => TableBuilder<any, any, any>,
   TIsSingle extends boolean,
 > {
   /**
@@ -140,8 +140,8 @@ export class ForeignKeyTargetBuilder<
  * @see {@link ForeignKeyBuilder} DB FK 생성 버전
  */
 export class RelationKeyBuilder<
-  TOwner extends TableBuilder<any, any> | ViewBuilder<any, any, any>,
-  TTargetFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>,
+  TOwner extends TableBuilder<any, any, any> | ViewBuilder<any, any, any>,
+  TTargetFn extends () => TableBuilder<any, any, any> | ViewBuilder<any, any, any>,
 > {
   /**
    * @param meta - 관계 메타데이터
@@ -186,7 +186,7 @@ export class RelationKeyBuilder<
  * @see {@link ForeignKeyTargetBuilder} DB FK 생성 버전
  */
 export class RelationKeyTargetBuilder<
-  TTargetTableFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>,
+  TTargetTableFn extends () => TableBuilder<any, any, any> | ViewBuilder<any, any, any>,
   TIsSingle extends boolean,
 > {
   /**
@@ -212,20 +212,20 @@ export class RelationKeyTargetBuilder<
  * @template TOwner - 소유 Table builder 타입
  * @template TColumnKey - Column key 타입
  */
-type RelationFkFactory<TOwner extends TableBuilder<any, any>, TColumnKey extends string> = {
+type RelationFkFactory<TOwner extends TableBuilder<any, any, any>, TColumnKey extends string> = {
   /** N:1 FK 관계 정의 (DB FK 생성) */
-  foreignKey<TTargetFn extends () => TableBuilder<any, any>>(
+  foreignKey<TTargetFn extends () => TableBuilder<any, any, any>>(
     columns: TColumnKey[],
     targetFn: TTargetFn,
     opts?: { description?: string },
   ): ForeignKeyBuilder<TOwner, TTargetFn>;
   /** 1:N FK 역참조 정의 (single: true → 단일 객체) */
-  foreignKeyTarget<TTargetTableFn extends () => TableBuilder<any, any>>(
+  foreignKeyTarget<TTargetTableFn extends () => TableBuilder<any, any, any>>(
     targetTableFn: TTargetTableFn,
     relationName: string,
     opts: { single: true; description?: string },
   ): ForeignKeyTargetBuilder<TTargetTableFn, true>;
-  foreignKeyTarget<TTargetTableFn extends () => TableBuilder<any, any>>(
+  foreignKeyTarget<TTargetTableFn extends () => TableBuilder<any, any, any>>(
     targetTableFn: TTargetTableFn,
     relationName: string,
     opts?: { single?: false; description?: string },
@@ -239,25 +239,25 @@ type RelationFkFactory<TOwner extends TableBuilder<any, any>, TColumnKey extends
  * @template TColumnKey - Column key 타입
  */
 type RelationRkFactory<
-  TOwner extends TableBuilder<any, any> | ViewBuilder<any, any, any>,
+  TOwner extends TableBuilder<any, any, any> | ViewBuilder<any, any, any>,
   TColumnKey extends string,
 > = {
   /** N:1 논리적 관계 정의 (DB FK 미생성) */
-  relationKey<TTargetFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>>(
+  relationKey<TTargetFn extends () => TableBuilder<any, any, any> | ViewBuilder<any, any, any>>(
     columns: TColumnKey[],
     targetFn: TTargetFn,
     opts?: { description?: string },
   ): RelationKeyBuilder<TOwner, TTargetFn>;
   /** 1:N 논리적 역참조 정의 (single: true → 단일 객체) */
   relationKeyTarget<
-    TTargetTableFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>,
+    TTargetTableFn extends () => TableBuilder<any, any, any> | ViewBuilder<any, any, any>,
   >(
     targetTableFn: TTargetTableFn,
     relationName: string,
     opts: { single: true; description?: string },
   ): RelationKeyTargetBuilder<TTargetTableFn, true>;
   relationKeyTarget<
-    TTargetTableFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>,
+    TTargetTableFn extends () => TableBuilder<any, any, any> | ViewBuilder<any, any, any>,
   >(
     targetTableFn: TTargetTableFn,
     relationName: string,
@@ -297,17 +297,17 @@ type RelationRkFactory<
  * ```
  */
 export function createRelationFactory<
-  TOwner extends TableBuilder<any, any> | ViewBuilder<any, any, any>,
+  TOwner extends TableBuilder<any, any, any> | ViewBuilder<any, any, any>,
   TColumnKey extends string,
 >(
   ownerFn: () => TOwner,
-): TOwner extends TableBuilder<any, any>
+): TOwner extends TableBuilder<any, any, any>
   ? RelationFkFactory<TOwner, TColumnKey> & RelationRkFactory<TOwner, TColumnKey>
   : RelationRkFactory<TOwner, TColumnKey> {
   return {
     foreignKey(columns, targetFn, opts?) {
       return new ForeignKeyBuilder({
-        ownerFn: ownerFn as () => TableBuilder<any, any>,
+        ownerFn: ownerFn as () => TableBuilder<any, any, any>,
         columns,
         targetFn,
         description: opts?.description,
@@ -337,7 +337,7 @@ export function createRelationFactory<
         isSingle: opts?.single,
       });
     },
-  } as TOwner extends TableBuilder<any, any>
+  } as TOwner extends TableBuilder<any, any, any>
     ? RelationFkFactory<TOwner, TColumnKey> & RelationRkFactory<TOwner, TColumnKey>
     : RelationRkFactory<TOwner, TColumnKey>;
 }
@@ -370,13 +370,15 @@ export type RelationBuilderRecord = Record<
  *
  * @template T - FK 또는 RelationKey builder 타입
  */
-export type ExtractRelationTarget<TRelation> = TRelation extends
+export type ExtractRelationTarget<TRelation, TVisited extends string = never> = TRelation extends
   | ForeignKeyBuilder<any, infer TTargetFn>
   | RelationKeyBuilder<any, infer TTargetFn>
-  ? ReturnType<TTargetFn> extends TableBuilder<infer TCols, infer TRels>
-    ? InferColumns<TCols> & InferDeepRelations<TRels>
+  ? ReturnType<TTargetFn> extends TableBuilder<infer TName, infer TCols, infer TRels>
+    ? TName extends TVisited
+      ? InferColumns<TCols>
+      : InferColumns<TCols> & InferDeepRelations<TRels, TVisited | TName>
     : ReturnType<TTargetFn> extends ViewBuilder<any, infer TData, infer TRels>
-      ? TData & InferDeepRelations<TRels>
+      ? TData & InferDeepRelations<TRels, TVisited>
       : never
   : never;
 
@@ -388,19 +390,24 @@ export type ExtractRelationTarget<TRelation> = TRelation extends
  *
  * @template T - FKTarget 또는 RelationKeyTarget builder 타입
  */
-export type ExtractRelationTargetResult<TRelation> = TRelation extends
-  | ForeignKeyTargetBuilder<infer TTargetTableFn, infer TIsSingle>
-  | RelationKeyTargetBuilder<infer TTargetTableFn, infer TIsSingle>
-  ? ReturnType<TTargetTableFn> extends TableBuilder<infer TCols, infer TRels>
-    ? TIsSingle extends true
-      ? InferColumns<TCols> & InferDeepRelations<TRels>
-      : (InferColumns<TCols> & InferDeepRelations<TRels>)[]
-    : ReturnType<TTargetTableFn> extends ViewBuilder<any, infer TData, infer TRels>
-      ? TIsSingle extends true
-        ? TData & InferDeepRelations<TRels>
-        : (TData & InferDeepRelations<TRels>)[]
-      : never
-  : never;
+export type ExtractRelationTargetResult<TRelation, TVisited extends string = never> =
+  TRelation extends
+    | ForeignKeyTargetBuilder<infer TTargetTableFn, infer TIsSingle>
+    | RelationKeyTargetBuilder<infer TTargetTableFn, infer TIsSingle>
+    ? ReturnType<TTargetTableFn> extends TableBuilder<infer TName, infer TCols, infer TRels>
+      ? TName extends TVisited
+        ? TIsSingle extends true
+          ? InferColumns<TCols>
+          : InferColumns<TCols>[]
+        : TIsSingle extends true
+          ? InferColumns<TCols> & InferDeepRelations<TRels, TVisited | TName>
+          : (InferColumns<TCols> & InferDeepRelations<TRels, TVisited | TName>)[]
+      : ReturnType<TTargetTableFn> extends ViewBuilder<any, infer TData, infer TRels>
+        ? TIsSingle extends true
+          ? TData & InferDeepRelations<TRels, TVisited>
+          : (TData & InferDeepRelations<TRels, TVisited>)[]
+        : never
+    : never;
 
 /**
  * 관계 정의에서 심층 관계 타입 추론
@@ -415,8 +422,8 @@ export type ExtractRelationTargetResult<TRelation> = TRelation extends
  * // { posts?: Post[]; profile?: Profile; }
  * ```
  */
-export type InferDeepRelations<TRelations extends RelationBuilderRecord> = {
+export type InferDeepRelations<TRelations extends RelationBuilderRecord, TVisited extends string = never> = {
   [K in keyof TRelations]?:
-    | ExtractRelationTarget<TRelations[K]>
-    | ExtractRelationTargetResult<TRelations[K]>;
+    | ExtractRelationTarget<TRelations[K], TVisited>
+    | ExtractRelationTargetResult<TRelations[K], TVisited>;
 };

package/src/schema/table-builder.ts

@@ -49,6 +49,7 @@ import {
  * @see {@link queryable} Queryable 생성
  */
 export class TableBuilder<
+  TName extends string,
   TColumns extends ColumnBuilderRecord,
   TRelations extends RelationBuilderRecord,
 > {
@@ -57,7 +58,7 @@ export class TableBuilder<
   /** 관계 정의 (타입 추론용) */
   readonly $relations!: TRelations;
 
-  /** 전체 타입 추론 (column + 관계) */
+  /** 전체 타입 추론 (column + 관계) — 순환 감지: 같은 테이블 재방문 시 끊김 */
   readonly $inferSelect!: InferColumns<TColumns> & InferDeepRelations<TRelations>;
   /** Column 전용 타입 추론 */
   readonly $inferColumns!: InferColumns<TColumns>;
@@ -79,7 +80,7 @@ export class TableBuilder<
    */
   constructor(
     readonly meta: {
-      name: string;
+      name: TName;
       description?: string;
       database?: string;
       schema?: string;
@@ -97,7 +98,7 @@ export class TableBuilder<
    * @param desc - Table 설명 (DDL Comment로 사용됨)
    * @returns 새 TableBuilder 인스턴스
    */
-  description(desc: string) {
+  description(desc: string): TableBuilder<TName, TColumns, TRelations> {
     return new TableBuilder({ ...this.meta, description: desc });
   }
 
@@ -112,7 +113,7 @@ export class TableBuilder<
    * const User = Table("User").database("mydb");
    * ```
    */
-  database(db: string) {
+  database(db: string): TableBuilder<TName, TColumns, TRelations> {
     return new TableBuilder({ ...this.meta, database: db });
   }
 
@@ -131,7 +132,7 @@ export class TableBuilder<
    *   .schema("custom_schema");
    * ```
    */
-  schema(schema: string) {
+  schema(schema: string): TableBuilder<TName, TColumns, TRelations> {
     return new TableBuilder({ ...this.meta, schema });
   }
 
@@ -157,8 +158,8 @@ export class TableBuilder<
    */
   columns<TNewColumnDefs extends ColumnBuilderRecord>(
     fn: (c: ReturnType<typeof createColumnFactory>) => TNewColumnDefs,
-  ) {
-    return new TableBuilder<TNewColumnDefs, TRelations>({
+  ): TableBuilder<TName, TNewColumnDefs, TRelations> {
+    return new TableBuilder<TName, TNewColumnDefs, TRelations>({
       ...this.meta,
       columns: fn(createColumnFactory()),
     });
@@ -186,7 +187,7 @@ export class TableBuilder<
    *   .primaryKey("userId", "roleId");
    * ```
    */
-  primaryKey(...columns: (keyof TColumns & string)[]) {
+  primaryKey(...columns: (keyof TColumns & string)[]): TableBuilder<TName, TColumns, TRelations> {
     return new TableBuilder({
       ...this.meta,
       primaryKey: columns,
@@ -217,7 +218,7 @@ export class TableBuilder<
     fn: (
       i: ReturnType<typeof createIndexFactory<keyof TColumns & string>>,
     ) => IndexBuilder<string[]>[],
-  ) {
+  ): TableBuilder<TName, TColumns, TRelations> {
     return new TableBuilder({
       ...this.meta,
       indexes: fn(createIndexFactory<keyof TColumns & string>()),
@@ -264,7 +265,7 @@ export class TableBuilder<
    */
   relations<T extends RelationBuilderRecord>(
     fn: (r: ReturnType<typeof createRelationFactory<this, keyof TColumns & string>>) => T,
-  ): TableBuilder<TColumns, T> {
+  ): TableBuilder<TName, TColumns, T> {
     return new TableBuilder({
       ...this.meta,
       relations: fn(createRelationFactory<this, keyof TColumns & string>(() => this)),
@@ -314,6 +315,6 @@ export class TableBuilder<
  *
  * @see {@link TableBuilder} builder 클래스
  */
-export function Table(name: string) {
-  return new TableBuilder({ name });
+export function Table<TName extends string>(name: TName) {
+  return new TableBuilder<TName, ColumnBuilderRecord, RelationBuilderRecord>({ name });
 }

package/src/types/db-context-def.ts

@@ -24,7 +24,7 @@ export interface DbContextBase {
     resultMetas?: (ResultMeta | undefined)[],
   ): Promise<T[][]>;
   getQueryDefObjectName(
-    tableOrView: TableBuilder<any, any> | ViewBuilder<any, any, any>,
+    tableOrView: TableBuilder<any, any, any> | ViewBuilder<any, any, any>,
   ): QueryDefObjectName;
   switchFk(table: QueryDefObjectName, enabled: boolean): Promise<void>;
 }
@@ -32,7 +32,7 @@ export interface DbContextBase {
 export type DbContextStatus = "ready" | "connect" | "transact";
 
 export interface DbContextDdlMethods {
-  createTable(table: TableBuilder<any, any>): Promise<void>;
+  createTable(table: TableBuilder<any, any, any>): Promise<void>;
   dropTable(table: QueryDefObjectName): Promise<void>;
   renameTable(table: QueryDefObjectName, newName: string): Promise<void>;
   createView(view: ViewBuilder<any, any, any>): Promise<void>;
@@ -66,11 +66,11 @@ export interface DbContextDdlMethods {
   truncate(table: QueryDefObjectName): Promise<void>;
   switchFk(table: QueryDefObjectName, enabled: boolean): Promise<void>;
   // QueryDef 생성기
-  getCreateTableQueryDef(table: TableBuilder<any, any>): QueryDef;
+  getCreateTableQueryDef(table: TableBuilder<any, any, any>): QueryDef;
   getCreateViewQueryDef(view: ViewBuilder<any, any, any>): QueryDef;
   getCreateProcQueryDef(procedure: ProcedureBuilder<any, any>): QueryDef;
   getCreateObjectQueryDef(
-    builder: TableBuilder<any, any> | ViewBuilder<any, any, any> | ProcedureBuilder<any, any>,
+    builder: TableBuilder<any, any, any> | ViewBuilder<any, any, any> | ProcedureBuilder<any, any>,
   ): QueryDef;
   getDropTableQueryDef(table: QueryDefObjectName): QueryDef;
   getRenameTableQueryDef(table: QueryDefObjectName, newName: string): QueryDef;

package/src/utils/result-parser.ts

@@ -16,11 +16,11 @@ declare function setImmediate(callback: () => void): void;
  * @returns 파싱된 값
  * @throws 파싱 실패 시 Error
  */
-function parseValue(value: unknown, type: ColumnPrimitiveStr): unknown {
-  // undefined는 key 제거 대상으로 남기고, null은 SQL 결과값으로 보존한다.
-  if (value == null) {
-    return value;
-  }
+function parseValue(value: unknown, type: ColumnPrimitiveStr): unknown {
+  // undefined는 key 제거 대상으로 남기고, null은 SQL 결과값으로 보존한다.
+  if (value == null) {
+    return value;
+  }
 
   switch (type) {
     case "number": {
@@ -93,11 +93,11 @@ function flatToNested(
   const result: Record<string, unknown> = {};
 
   for (const { key, type, parts } of columnInfos) {
-    const rawValue = record[key];
-    if (typeof rawValue === "undefined") continue;
-    const parsedValue = parseValue(rawValue, type);
-
-    if (parts != null) {
+    const rawValue = record[key];
+    if (typeof rawValue === "undefined") continue;
+    const parsedValue = parseValue(rawValue, type);
+
+    if (parts != null) {
       // 중첩 key: "posts.id" → { posts: { id: ... } }
       let current = result;
       for (let i = 0; i < parts.length - 1; i++) {
@@ -120,45 +120,45 @@ function flatToNested(
 /**
  * 객체가 비어있는지 확인 (모든 값이 undefined)
  */
-function isEmptyObject(record: Record<string, unknown>): boolean {
-  return Object.keys(record).length === 0;
-}
-
-/**
- * JOIN 결과 객체가 실질적으로 비어있는지 확인
- *
- * 모든 값이 null/undefined 이거나, 중첩 객체도 재귀적으로 비어있으면 비어있는 JOIN으로 간주한다.
- */
-function isEmptyJoinObject(record: Record<string, unknown>): boolean {
-  const entries = Object.entries(record);
-  if (entries.length === 0) {
-    return true;
-  }
-
-  for (const [, value] of entries) {
-    if (value == null) {
-      continue;
-    }
-
-    if (Array.isArray(value)) {
-      if (value.length > 0) {
-        return false;
-      }
-      continue;
-    }
-
-    if (typeof value === "object") {
-      if (!isEmptyJoinObject(value as Record<string, unknown>)) {
-        return false;
-      }
-      continue;
-    }
-
-    return false;
-  }
-
-  return true;
-}
+function isEmptyObject(record: Record<string, unknown>): boolean {
+  return Object.keys(record).length === 0;
+}
+
+/**
+ * JOIN 결과 객체가 실질적으로 비어있는지 확인
+ *
+ * 모든 값이 null/undefined 이거나, 중첩 객체도 재귀적으로 비어있으면 비어있는 JOIN으로 간주한다.
+ */
+function isEmptyJoinObject(record: Record<string, unknown>): boolean {
+  const entries = Object.entries(record);
+  if (entries.length === 0) {
+    return true;
+  }
+
+  for (const [, value] of entries) {
+    if (value == null) {
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      if (value.length > 0) {
+        return false;
+      }
+      continue;
+    }
+
+    if (typeof value === "object") {
+      if (!isEmptyJoinObject(value as Record<string, unknown>)) {
+        return false;
+      }
+      continue;
+    }
+
+    return false;
+  }
+
+  return true;
+}
 
 // ============================================
 // 메인 함수
@@ -401,10 +401,10 @@ function groupRecordsRecursively(
         const localKey = currentPath === "" ? joinKey : joinKey.slice(currentPath.length + 1);
         const joinData = newGroup[localKey] as Record<string, unknown> | undefined;
 
-        if (joinData != null && !isEmptyJoinObject(joinData)) {
-          if (!joinsConfig[joinKey].isSingle) {
-            // 배열로 변환 (hashSet은 첫 merge 시 초기화)
-            newGroup[localKey] = [joinData];
+        if (joinData != null && !isEmptyJoinObject(joinData)) {
+          if (!joinsConfig[joinKey].isSingle) {
+            // 배열로 변환 (hashSet은 첫 merge 시 초기화)
+            newGroup[localKey] = [joinData];
           }
         } else {
           // 데이터가 비어있으면 key 삭제
@@ -500,16 +500,16 @@ function mergeJoinData(
 ): void {
   const newJoinData = newRecord[localKey] as Record<string, unknown> | undefined;
 
-  if (newJoinData == null || isEmptyJoinObject(newJoinData)) {
-    return; // 병합할 데이터 없음
-  }
+  if (newJoinData == null || isEmptyJoinObject(newJoinData)) {
+    return; // 병합할 데이터 없음
+  }
 
   const existingJoinData = existingGroup[localKey];
 
   if (isSingle) {
     // isSingle: true - 데이터가 존재하고 값이 다르면 에러
     if (existingJoinData != null) {
-      if (!obj.equal(existingJoinData as Record<string, unknown>, newJoinData)) {
+      if (!obj.equal(existingJoinData, newJoinData)) {
         throw new Error(`isSingle 관계 '${localKey}'에 여러 개의 다른 결과가 있습니다.`);
       }
     } else {

package/docs/core.md

@@ -1,188 +0,0 @@
-# Core
-
-## `DbContext`
-
-DB 연결/트랜잭션/DDL/초기화를 제공하는 추상 클래스. `queryable()`/`executable()`로 테이블/프로시저를 등록한다. 각 프로퍼티가 독립 직렬화되어 40+ 테이블에서도 TS7056이 발생하지 않는다.
-
-```typescript
-export abstract class DbContext implements DbContextBase {
-  status: DbContextStatus;
-  migrations: Migration[];
-
-  constructor(
-    executor: DbContextExecutor,
-    opt: { database: string; schema?: string },
-  );
-
-  // 등록 메서드
-  protected queryable<T extends TableBuilder | ViewBuilder>(builder: T): () => Queryable;
-  protected executable<T extends ProcedureBuilder>(builder: T): () => Executable;
-
-  // 연결 관리
-  connect<TResult>(fn: () => Promise<TResult>, isolationLevel?: IsolationLevel): Promise<TResult>;
-  connectWithoutTransaction<TResult>(callback: () => Promise<TResult>): Promise<TResult>;
-  transaction<TResult>(fn: () => Promise<TResult>, isolationLevel?: IsolationLevel): Promise<TResult>;
-
-  // DDL 실행 메서드
-  createTable(table: TableBuilder): Promise<void>;
-  dropTable(table: QueryDefObjectName): Promise<void>;
-  renameTable(table: QueryDefObjectName, newName: string): Promise<void>;
-  createView(view: ViewBuilder): Promise<void>;
-  dropView(view: QueryDefObjectName): Promise<void>;
-  createProc(procedure: ProcedureBuilder): Promise<void>;
-  dropProc(procedure: QueryDefObjectName): Promise<void>;
-  addColumn(table: QueryDefObjectName, columnName: string, column: ColumnBuilder): Promise<void>;
-  dropColumn(table: QueryDefObjectName, column: string): Promise<void>;
-  modifyColumn(table: QueryDefObjectName, columnName: string, column: ColumnBuilder): Promise<void>;
-  renameColumn(table: QueryDefObjectName, column: string, newName: string): Promise<void>;
-  addPrimaryKey(table: QueryDefObjectName, columns: string[]): Promise<void>;
-  dropPrimaryKey(table: QueryDefObjectName): Promise<void>;
-  addForeignKey(table: QueryDefObjectName, relationName: string, relationDef: ForeignKeyBuilder): Promise<void>;
-  addIndex(table: QueryDefObjectName, indexBuilder: IndexBuilder): Promise<void>;
-  dropForeignKey(table: QueryDefObjectName, relationName: string): Promise<void>;
-  dropIndex(table: QueryDefObjectName, columns: string[]): Promise<void>;
-  clearSchema(params: { database: string; schema?: string }): Promise<void>;
-  schemaExists(database: string, schema?: string): Promise<boolean>;
-  truncate(table: QueryDefObjectName): Promise<void>;
-  switchFk(table: QueryDefObjectName, enabled: boolean): Promise<void>;
-
-  // DDL QueryDef 생성기 (getCreateTableQueryDef, getDropTableQueryDef, ... 등 동일 시그니처)
-  getCreateTableQueryDef(table: TableBuilder): QueryDef;
-  getCreateViewQueryDef(view: ViewBuilder): QueryDef;
-  getCreateProcQueryDef(procedure: ProcedureBuilder): QueryDef;
-  getCreateObjectQueryDef(builder: TableBuilder | ViewBuilder | ProcedureBuilder): QueryDef;
-  getDropTableQueryDef(table: QueryDefObjectName): QueryDef;
-  getRenameTableQueryDef(table: QueryDefObjectName, newName: string): QueryDef;
-  getDropViewQueryDef(view: QueryDefObjectName): QueryDef;
-  getDropProcQueryDef(procedure: QueryDefObjectName): QueryDef;
-  getAddColumnQueryDef(table: QueryDefObjectName, columnName: string, column: ColumnBuilder): QueryDef;
-  getDropColumnQueryDef(table: QueryDefObjectName, column: string): QueryDef;
-  getModifyColumnQueryDef(table: QueryDefObjectName, columnName: string, column: ColumnBuilder): QueryDef;
-  getRenameColumnQueryDef(table: QueryDefObjectName, column: string, newName: string): QueryDef;
-  getAddPrimaryKeyQueryDef(table: QueryDefObjectName, columns: string[]): QueryDef;
-  getDropPrimaryKeyQueryDef(table: QueryDefObjectName): QueryDef;
-  getAddForeignKeyQueryDef(table: QueryDefObjectName, relationName: string, relationDef: ForeignKeyBuilder): QueryDef;
-  getAddIndexQueryDef(table: QueryDefObjectName, indexBuilder: IndexBuilder): QueryDef;
-  getDropForeignKeyQueryDef(table: QueryDefObjectName, relationName: string): QueryDef;
-  getDropIndexQueryDef(table: QueryDefObjectName, columns: string[]): QueryDef;
-  getClearSchemaQueryDef(params: { database: string; schema?: string }): QueryDef;
-  getSchemaExistsQueryDef(database: string, schema?: string): QueryDef;
-  getTruncateQueryDef(table: QueryDefObjectName): QueryDef;
-  getSwitchFkQueryDef(table: QueryDefObjectName, enabled: boolean): QueryDef;
-
-  // 초기화
-  initialize(options?: { dbs?: string[]; force?: boolean }): Promise<boolean>;
-
-  // DbContextBase 구현
-  get database(): string | undefined;
-  get schema(): string | undefined;
-  getNextAlias(): string;
-  resetAliasCounter(): void;
-  executeDefs<T>(defs: QueryDef[], resultMetas?: (ResultMeta | undefined)[]): Promise<T[][]>;
-  getQueryDefObjectName(tableOrView: TableBuilder | ViewBuilder): QueryDefObjectName;
-}
-```
-
-### 연결/트랜잭션 패턴
-
-| 메서드 | 용도 |
-|--------|------|
-| `connect(fn)` | 연결 -> 트랜잭션 시작 -> fn -> 커밋 -> 종료. 일반 DML 작업에 사용 |
-| `connectWithoutTransaction(fn)` | 연결 -> fn -> 종료. 트랜잭션 없는 DDL/읽기 전용 작업에 사용 |
-| `transaction(fn)` | 이미 연결된 상태에서 부분 트랜잭션 시작. `connectWithoutTransaction` 내부에서 사용 |
-
-- `connect()`/`connectWithoutTransaction()`은 status가 `"ready"`가 아니면 에러를 던진다 (재진입 방지).
-- 트랜잭션 중 DDL 실행은 런타임 에러를 발생시킨다.
-- 롤백 실패 시 원래 에러의 `cause`에 롤백 에러를 첨부하여 전파한다.
-
-## `SD_BUILDER`
-
-DbContext의 queryable/executable 프로퍼티에 부착된 builder 참조용 Symbol.
-
-```typescript
-export const SD_BUILDER: unique symbol;
-```
-
-## `DbContextBase`
-
-Queryable, Executable, ViewBuilder에서 사용하는 DbContext 내부 인터페이스. DbContext class가 이 인터페이스를 구현한다.
-
-```typescript
-export interface DbContextBase {
-  status: DbContextStatus;
-  readonly database: string | undefined;
-  readonly schema: string | undefined;
-  getNextAlias(): string;
-  resetAliasCounter(): void;
-  executeDefs<T = DataRecord>(defs: QueryDef[], resultMetas?: (ResultMeta | undefined)[]): Promise<T[][]>;
-  getQueryDefObjectName(tableOrView: TableBuilder | ViewBuilder): QueryDefObjectName;
-  switchFk(table: QueryDefObjectName, enabled: boolean): Promise<void>;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `status` | `DbContextStatus` | 현재 연결 상태 |
-| `database` | `string \| undefined` | 데이터베이스 이름 |
-| `schema` | `string \| undefined` | 스키마 이름 |
-
-## `DbContextStatus`
-
-DbContext 상태를 나타내는 문자열 리터럴 유니온.
-
-```typescript
-export type DbContextStatus = "ready" | "connect" | "transact";
-```
-
-## `DbContextDdlMethods`
-
-DDL 실행 메서드 인터페이스. DbContext에서 사용하는 모든 DDL 메서드 시그니처를 정의한다. DDL 실행 메서드와 DDL QueryDef 생성 메서드를 모두 포함한다.
-
-```typescript
-export interface DbContextDdlMethods {
-  createTable(table: TableBuilder): Promise<void>;
-  dropTable(table: QueryDefObjectName): Promise<void>;
-  // ... (DbContext의 DDL 메서드와 동일한 시그니처)
-}
-```
-
-## `DbErrorCode`
-
-트랜잭션 관련 에러 코드. DBMS별 네이티브 에러 코드를 추상화한다.
-
-```typescript
-export enum DbErrorCode {
-  NO_ACTIVE_TRANSACTION = "NO_ACTIVE_TRANSACTION",
-  TRANSACTION_ALREADY_STARTED = "TRANSACTION_ALREADY_STARTED",
-  DEADLOCK = "DEADLOCK",
-  LOCK_TIMEOUT = "LOCK_TIMEOUT",
-}
-```
-
-| Value | Description |
-|-------|-------------|
-| `NO_ACTIVE_TRANSACTION` | 활성 트랜잭션 없음 (ROLLBACK 시) |
-| `TRANSACTION_ALREADY_STARTED` | 트랜잭션 이미 시작됨 |
-| `DEADLOCK` | 데드락 발생 |
-| `LOCK_TIMEOUT` | 잠금 타임아웃 |
-
-## `DbTransactionError`
-
-DBMS별 네이티브 에러를 표준화된 에러 코드로 래핑하는 에러 클래스.
-
-```typescript
-export class DbTransactionError extends Error {
-  override readonly name = "DbTransactionError";
-
-  constructor(
-    public readonly code: DbErrorCode,
-    message: string,
-    public readonly originalError?: unknown,
-  );
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `code` | `DbErrorCode` | 표준화된 에러 코드 |
-| `originalError` | `unknown \| undefined` | 원본 DBMS 에러 (디버깅용) |