@simplysm/orm-common 13.0.99 → 14.0.1

package/dist/exec/queryable.js

@@ -1,1270 +1,1376 @@
 import { TableBuilder } from "../schema/table-builder.js";
 import { ViewBuilder } from "../schema/view-builder.js";
-import {
-} from "../schema/factory/column-builder.js";
+import {} from "../schema/factory/column-builder.js";
 import { ExprUnit } from "../expr/expr-unit.js";
 import { ArgumentError, obj } from "@simplysm/core-common";
-import {
-  ForeignKeyBuilder,
-  ForeignKeyTargetBuilder,
-  RelationKeyBuilder,
-  RelationKeyTargetBuilder
-} from "../schema/factory/relation-builder.js";
+import { ForeignKeyBuilder, ForeignKeyTargetBuilder, RelationKeyBuilder, RelationKeyTargetBuilder, } from "../schema/factory/relation-builder.js";
 import { parseSearchQuery } from "./search-parser.js";
 import { expr } from "../expr/expr.js";
+/**
+ * JOIN query builder
+ *
+ * join/joinSingle 메서드 내부에서 조인할 table을 지정하는 데 사용
+ */
 class JoinQueryable {
-  constructor(_db, _joinAlias) {
-    this._db = _db;
-    this._joinAlias = _joinAlias;
-  }
-  /**
-   * Specify the table to join
-   *
-   * @param table - Table to join
-   * @returns Joined Queryable
-   */
-  from(table) {
-    return queryable(this._db, table, this._joinAlias)();
-  }
-  /**
-   * Directly specify columns in join result
-   *
-   * @param columns - Custom column definition
-   * @returns Queryable with custom columns applied
-   */
-  select(columns) {
-    return new Queryable({
-      db: this._db,
-      as: this._joinAlias,
-      columns,
-      isCustomColumns: true
-    });
-  }
-  /**
-   * Combine multiple Queryables with UNION
-   *
-   * @param queries - Array of Queryables to UNION (minimum 2)
-   * @returns UNION-ed Queryable
-   * @throws If less than 2 queryables are passed
-   */
-  union(...queries) {
-    if (queries.length < 2) {
-      throw new ArgumentError("union requires at least 2 queryables.", {
-        provided: queries.length,
-        minimum: 2
-      });
+    _db;
+    _joinAlias;
+    constructor(_db, _joinAlias) {
+        this._db = _db;
+        this._joinAlias = _joinAlias;
+    }
+    /**
+     * 조인할 table 지정
+     *
+     * @param table - 조인할 table
+     * @returns 조인된 Queryable
+     */
+    from(table) {
+        return queryable(this._db, table, this._joinAlias)();
+    }
+    /**
+     * 조인 결과의 column을 직접 지정
+     *
+     * @param columns - 커스텀 column 정의
+     * @returns 커스텀 column이 적용된 Queryable
+     */
+    select(columns) {
+        return new Queryable({
+            db: this._db,
+            as: this._joinAlias,
+            columns,
+            isCustomColumns: true,
+        });
+    }
+    /**
+     * 여러 Queryable을 UNION으로 결합
+     *
+     * @param queries - UNION할 Queryable 배열 (최소 2개)
+     * @returns UNION된 Queryable
+     * @throws 2개 미만의 queryable이 전달되면 에러
+     */
+    union(...queries) {
+        if (queries.length < 2) {
+            throw new ArgumentError("union은 최소 2개의 queryable이 필요합니다.", {
+                provided: queries.length,
+                minimum: 2,
+            });
+        }
+        const first = queries[0];
+        return new Queryable({
+            db: first.meta.db,
+            from: queries, // Queryable[] 배열로 저장
+            as: this._joinAlias,
+            columns: transformColumnsAlias(first.meta.columns, this._joinAlias, ""),
+        });
     }
-    const first = queries[0];
-    return new Queryable({
-      db: first.meta.db,
-      from: queries,
-      // stored as Queryable[] array
-      as: this._joinAlias,
-      columns: transformColumnsAlias(first.meta.columns, this._joinAlias, "")
-    });
-  }
 }
+/**
+ * 재귀 CTE (Common Table Expression) builder
+ *
+ * recursive() 메서드 내부에서 사용되며, 재귀 쿼리의 본문을 정의한다
+ *
+ * @template TBaseData - Base query data type
+ */
 class RecursiveQueryable {
-  constructor(_baseQr, _cteName) {
-    this._baseQr = _baseQr;
-    this._cteName = _cteName;
-  }
-  /**
-   * specify the target table for recursive query
-   *
-   * @param table - Target table to recurse
-   * @returns Queryable with self property added (for self-reference)
-   */
-  from(table) {
-    const selfAlias = `${this._cteName}.self`;
-    return queryable(this._baseQr.meta.db, table, this._cteName)().join(
-      "self",
-      () => new Queryable({
-        db: this._baseQr.meta.db,
-        from: this._cteName,
-        as: selfAlias,
-        columns: transformColumnsAlias(this._baseQr.meta.columns, selfAlias, ""),
-        isCustomColumns: false
-      })
-    );
-  }
-  /**
-   * Directly specify columns in recursive query
-   *
-   * @param columns - Custom column definition
-   * @returns Queryable with self property added
-   */
-  select(columns) {
-    const selfAlias = `${this._cteName}.self`;
-    return new Queryable({
-      db: this._baseQr.meta.db,
-      as: this._cteName,
-      columns,
-      isCustomColumns: true
-    }).join(
-      "self",
-      () => new Queryable({
-        db: this._baseQr.meta.db,
-        from: this._cteName,
-        as: selfAlias,
-        columns: transformColumnsAlias(this._baseQr.meta.columns, selfAlias, ""),
-        isCustomColumns: false
-      })
-    );
-  }
-  /**
-   * Combine multiple Queryables with UNION (for recursive query)
-   *
-   * @param queries - Array of Queryables to UNION (minimum 2)
-   * @returns UNION Queryable with self property added
-   * @throws If less than 2 queryables are passed
-   */
-  union(...queries) {
-    if (queries.length < 2) {
-      throw new ArgumentError("union requires at least 2 queryables.", {
-        provided: queries.length,
-        minimum: 2
-      });
+    _baseQr;
+    _cteName;
+    constructor(_baseQr, _cteName) {
+        this._baseQr = _baseQr;
+        this._cteName = _cteName;
     }
-    const first = queries[0];
-    const selfAlias = `${this._cteName}.self`;
-    return new Queryable({
-      db: first.meta.db,
-      from: queries,
-      // stored as Queryable[] array
-      as: this._cteName,
-      columns: transformColumnsAlias(first.meta.columns, this._cteName, "")
-    }).join(
-      "self",
-      () => new Queryable({
-        db: this._baseQr.meta.db,
-        from: this._cteName,
-        as: selfAlias,
-        columns: transformColumnsAlias(this._baseQr.meta.columns, selfAlias, ""),
-        isCustomColumns: false
-      })
-    );
-  }
-}
-class Queryable {
-  constructor(meta) {
-    this.meta = meta;
-  }
-  //#region ========== option - SELECT / DISTINCT / LOCK ==========
-  /**
-   * Specify columns to SELECT.
-   *
-   * @param fn - Column mapping function. Receives original columns and returns new column structure
-   * @returns Queryable with new column structure applied
-   *
-   * @example
-   * ```typescript
-   * db.user().select((u) => ({
-   *   userName: u.name,
-   *   userEmail: u.email,
-   * }))
-   * ```
-   */
-  select(fn) {
-    if (Array.isArray(this.meta.from)) {
-      const newFroms = this.meta.from.map((from) => from.select(fn));
-      return new Queryable({
-        ...this.meta,
-        from: newFroms,
-        columns: transformColumnsAlias(newFroms[0].meta.columns, this.meta.as, "")
-      });
+    /**
+     * 재귀 query의 대상 table 지정
+     *
+     * @param table - 재귀할 대상 table
+     * @returns self 속성이 추가된 Queryable (자기 참조용)
+     */
+    from(table) {
+        const selfAlias = `${this._cteName}.self`;
+        return queryable(this._baseQr.meta.db, table, this._cteName)().join("self", () => new Queryable({
+            db: this._baseQr.meta.db,
+            from: this._cteName,
+            as: selfAlias,
+            columns: transformColumnsAlias(this._baseQr.meta.columns, selfAlias, ""),
+            isCustomColumns: false,
+        }));
     }
-    const newColumns = fn(this.meta.columns);
-    return new Queryable({
-      ...this.meta,
-      columns: newColumns,
-      isCustomColumns: true
-    });
-  }
-  /**
-   * Apply DISTINCT option to remove duplicate rows
-   *
-   * @returns Queryable with DISTINCT applied
-   *
-   * @example
-   * ```typescript
-   * db.user()
-   *   .select((u) => ({ name: u.name }))
-   *   .distinct()
-   * ```
-   */
-  distinct() {
-    if (Array.isArray(this.meta.from)) {
-      const newFroms = this.meta.from.map((from) => from.distinct());
-      return new Queryable({
-        ...this.meta,
-        from: newFroms
-      });
+    /**
+     * 재귀 query의 column을 직접 지정
+     *
+     * @param columns - 커스텀 column 정의
+     * @returns self 속성이 추가된 Queryable
+     */
+    select(columns) {
+        const selfAlias = `${this._cteName}.self`;
+        return new Queryable({
+            db: this._baseQr.meta.db,
+            as: this._cteName,
+            columns,
+            isCustomColumns: true,
+        }).join("self", () => new Queryable({
+            db: this._baseQr.meta.db,
+            from: this._cteName,
+            as: selfAlias,
+            columns: transformColumnsAlias(this._baseQr.meta.columns, selfAlias, ""),
+            isCustomColumns: false,
+        }));
     }
-    return new Queryable({
-      ...this.meta,
-      distinct: true
-    });
-  }
-  /**
-   * Apply row lock (FOR UPDATE)
-   *
-   * Acquire exclusive lock on selected rows within transaction
-   *
-   * @returns Queryable with lock applied
-   *
-   * @example
-   * ```typescript
-   * await db.connect(async () => {
-   *   const user = await db.user()
-   *     .where((u) => [expr.eq(u.id, 1)])
-   *     .lock()
-   *     .single();
-   * });
-   * ```
-   */
-  lock() {
-    if (Array.isArray(this.meta.from)) {
-      const newFroms = this.meta.from.map((from) => from.lock());
-      return new Queryable({
-        ...this.meta,
-        from: newFroms
-      });
+    /**
+     * 여러 Queryable을 UNION으로 결합 (재귀 query용)
+     *
+     * @param queries - UNION할 Queryable 배열 (최소 2개)
+     * @returns self 속성이 추가된 UNION Queryable
+     * @throws 2개 미만의 queryable이 전달되면 에러
+     */
+    union(...queries) {
+        if (queries.length < 2) {
+            throw new ArgumentError("union은 최소 2개의 queryable이 필요합니다.", {
+                provided: queries.length,
+                minimum: 2,
+            });
+        }
+        const first = queries[0];
+        const selfAlias = `${this._cteName}.self`;
+        return new Queryable({
+            db: first.meta.db,
+            from: queries, // Queryable[] 배열로 저장
+            as: this._cteName,
+            columns: transformColumnsAlias(first.meta.columns, this._cteName, ""),
+        }).join("self", () => new Queryable({
+            db: this._baseQr.meta.db,
+            from: this._cteName,
+            as: selfAlias,
+            columns: transformColumnsAlias(this._baseQr.meta.columns, selfAlias, ""),
+            isCustomColumns: false,
+        }));
     }
-    return new Queryable({
-      ...this.meta,
-      lock: true
-    });
-  }
-  //#endregion
-  //#region ========== restrict - TOP / LIMIT ==========
-  /**
-   * Select only top N rows (can be used without ORDER BY)
-   *
-   * @param count - number of rows to select
-   * @returns Queryable with TOP applied
-   *
-   * @example
-   * ```typescript
-   * // Latest 10 users
-   * db.user()
-   *   .orderBy((u) => u.createdAt, "DESC")
-   *   .top(10)
-   * ```
-   */
-  top(count) {
-    if (Array.isArray(this.meta.from)) {
-      const newFroms = this.meta.from.map((from) => from.top(count));
-      return new Queryable({
-        ...this.meta,
-        from: newFroms
-      });
+}
+/**
+ * Query builder 클래스
+ *
+ * 체이닝 방식으로 table/view에 대한 SELECT, INSERT, UPDATE, DELETE query를 구성
+ *
+ * @template TData - Query 결과의 데이터 타입
+ * @template TFrom - 소스 table (CUD 연산에 필요)
+ *
+ * @example
+ * ```typescript
+ * // Basic query
+ * const users = await db.user()
+ *   .where((u) => [expr.eq(u.isActive, true)])
+ *   .orderBy((u) => u.name)
+ *   .execute();
+ *
+ * // JOIN query
+ * const posts = await db.post()
+ *   .include((p) => p.user)
+ *   .execute();
+ *
+ * // INSERT
+ * await db.user().insert([{ name: "Gildong Hong", email: "test@test.com" }]);
+ * ```
+ */
+export class Queryable {
+    meta;
+    constructor(meta) {
+        this.meta = meta;
     }
-    return new Queryable({
-      ...this.meta,
-      top: count
-    });
-  }
-  /**
-   * Set LIMIT/OFFSET for pagination.
-   * Must call orderBy() first.
-   *
-   * @param skip - number of rows to skip (OFFSET)
-   * @param take - number of rows to fetch (LIMIT)
-   * @returns Queryable with pagination applied
-   * @throws Error if no ORDER BY clause
-   *
-   * @example
-   * ```typescript
-   * db.user
-   *   .orderBy((u) => u.createdAt)
-   *   .limit(0, 20) // first 20
-   * ```
-   */
-  limit(skip, take) {
-    if (Array.isArray(this.meta.from)) {
-      const newFroms = this.meta.from.map((from) => from.limit(skip, take));
-      return new Queryable({
-        ...this.meta,
-        from: newFroms
-      });
+    //#region ========== option - SELECT / DISTINCT / LOCK ==========
+    /**
+     * SELECT할 column 지정.
+     *
+     * @param fn - Column 매핑 함수. 원본 column을 받아 새 column 구조를 반환
+     * @returns 새 column 구조가 적용된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.user().select((u) => ({
+     *   userName: u.name,
+     *   userEmail: u.email,
+     * }))
+     * ```
+     */
+    select(fn) {
+        if (Array.isArray(this.meta.from)) {
+            const newFroms = this.meta.from.map((from) => from.select(fn));
+            return new Queryable({
+                ...this.meta,
+                from: newFroms,
+                columns: transformColumnsAlias(newFroms[0].meta.columns, this.meta.as, ""),
+            });
+        }
+        const newColumns = fn(this.meta.columns);
+        return new Queryable({
+            ...this.meta,
+            columns: newColumns,
+            isCustomColumns: true,
+        });
     }
-    if (!this.meta.orderBy) {
-      throw new ArgumentError("limit() requires ORDER BY clause.", {
-        method: "limit",
-        required: "orderBy"
-      });
+    /**
+     * 중복 행 제거를 위한 DISTINCT 옵션 적용
+     *
+     * @returns DISTINCT가 적용된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.user()
+     *   .select((u) => ({ name: u.name }))
+     *   .distinct()
+     * ```
+     */
+    distinct() {
+        if (Array.isArray(this.meta.from)) {
+            const newFroms = this.meta.from.map((from) => from.distinct());
+            return new Queryable({
+                ...this.meta,
+                from: newFroms,
+            });
+        }
+        return new Queryable({
+            ...this.meta,
+            distinct: true,
+        });
     }
-    return new Queryable({
-      ...this.meta,
-      limit: [skip, take]
-    });
-  }
-  //#endregion
-  //#region ========== sorting - ORDER BY ==========
-  /**
-   * Add sorting condition. Multiple calls apply in order.
-   *
-   * @param fn - function returning columns to sort by
-   * @param orderBy - Sort direction (ASC/DESC). Default: ASC
-   * @returns Queryable with sorting conditions added
-   *
-   * @example
-   * ```typescript
-   * db.user
-   *   .orderBy((u) => u.name)           // name ASC
-   *   .orderBy((u) => u.age, "DESC")    // age DESC
-   * ```
-   */
-  orderBy(fn, orderBy) {
-    if (Array.isArray(this.meta.from)) {
-      const newFroms = this.meta.from.map((from) => from.orderBy(fn, orderBy));
-      return new Queryable({
-        ...this.meta,
-        from: newFroms
-      });
+    /**
+     * 행 잠금 적용 (FOR UPDATE)
+     *
+     * 트랜잭션 내에서 선택된 행에 대한 배타적 잠금 획득
+     *
+     * @returns 잠금이 적용된 Queryable
+     *
+     * @example
+     * ```typescript
+     * await db.connect(async () => {
+     *   const user = await db.user()
+     *     .where((u) => [expr.eq(u.id, 1)])
+     *     .lock()
+     *     .single();
+     * });
+     * ```
+     */
+    lock() {
+        if (Array.isArray(this.meta.from)) {
+            const newFroms = this.meta.from.map((from) => from.lock());
+            return new Queryable({
+                ...this.meta,
+                from: newFroms,
+            });
+        }
+        return new Queryable({
+            ...this.meta,
+            lock: true,
+        });
     }
-    const column = fn(this.meta.columns);
-    return new Queryable({
-      ...this.meta,
-      orderBy: [...this.meta.orderBy ?? [], [column, orderBy]]
-    });
-  }
-  //#endregion
-  //#region ========== Search - WHERE ==========
-  /**
-   * Add WHERE condition. Multiple calls are combined with AND.
-   *
-   * @param predicate - Function returning an array of conditions
-   * @returns Queryable with conditions added
-   *
-   * @example
-   * ```typescript
-   * db.user
-   *   .where((u) => [expr.eq(u.isActive, true)])
-   *   .where((u) => [expr.gte(u.age, 18)])
-   * ```
-   */
-  where(predicate) {
-    if (Array.isArray(this.meta.from)) {
-      const newFroms = this.meta.from.map((from) => from.where(predicate));
-      return new Queryable({
-        ...this.meta,
-        from: newFroms
-      });
+    //#endregion
+    //#region ========== restrict - TOP / LIMIT ==========
+    /**
+     * 상위 N개 행만 선택 (ORDER BY 없이도 사용 가능)
+     *
+     * @param count - 선택할 행 수
+     * @returns TOP이 적용된 Queryable
+     *
+     * @example
+     * ```typescript
+     * // Latest 10 users
+     * db.user()
+     *   .orderBy((u) => u.createdAt, "DESC")
+     *   .top(10)
+     * ```
+     */
+    top(count) {
+        if (Array.isArray(this.meta.from)) {
+            const newFroms = this.meta.from.map((from) => from.top(count));
+            return new Queryable({
+                ...this.meta,
+                from: newFroms,
+            });
+        }
+        return new Queryable({
+            ...this.meta,
+            top: count,
+        });
     }
-    const conditions = predicate(this.meta.columns);
-    return new Queryable({
-      ...this.meta,
-      where: [...this.meta.where ?? [], ...conditions]
-    });
-  }
-  /**
-   * Perform text search
-   *
-   * See {@link parseSearchQuery} for search syntax
-   * - Space-separated words are OR conditions
-   * - Words starting with `+` are required includes (AND condition)
-   * - Words starting with `-` are excludes (NOT condition)
-   *
-   * @param fn - Function returning target columns to search
-   * @param searchText - Search text
-   * @returns Queryable with search conditions added
-   *
-   * @example
-   * ```typescript
-   * db.user()
-   *   .search((u) => [u.name, u.email], "John Doe -withdrawn")
-   * ```
-   */
-  search(fn, searchText) {
-    if (Array.isArray(this.meta.from)) {
-      const newFroms = this.meta.from.map((from) => from.search(fn, searchText));
-      return new Queryable({
-        ...this.meta,
-        from: newFroms
-      });
+    /**
+     * 페이지네이션을 위한 LIMIT/OFFSET 설정.
+     * 먼저 orderBy()를 호출해야 함.
+     *
+     * @param skip - 건너뛸 행 수 (OFFSET)
+     * @param take - 가져올 행 수 (LIMIT)
+     * @returns 페이지네이션이 적용된 Queryable
+     * @throws ORDER BY 절이 없으면 에러
+     *
+     * @example
+     * ```typescript
+     * db.user
+     *   .orderBy((u) => u.createdAt)
+     *   .limit(0, 20) // first 20
+     * ```
+     */
+    limit(skip, take) {
+        if (Array.isArray(this.meta.from)) {
+            const newFroms = this.meta.from.map((from) => from.limit(skip, take));
+            return new Queryable({
+                ...this.meta,
+                from: newFroms,
+            });
+        }
+        if (!this.meta.orderBy) {
+            throw new ArgumentError("limit()은 ORDER BY 절이 필요합니다.", {
+                method: "limit",
+                required: "orderBy",
+            });
+        }
+        return new Queryable({
+            ...this.meta,
+            limit: [skip, take],
+        });
     }
-    if (searchText.trim() === "") {
-      return this;
+    //#endregion
+    //#region ========== sorting - ORDER BY ==========
+    /**
+     * 정렬 조건 추가. 여러 번 호출 시 순서대로 적용됨.
+     *
+     * @param fn - 정렬할 column을 반환하는 함수
+     * @param orderBy - 정렬 방향 (ASC/DESC). 기본값: ASC
+     * @returns 정렬 조건이 추가된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.user
+     *   .orderBy((u) => u.name)           // name ASC
+     *   .orderBy((u) => u.age, "DESC")    // age DESC
+     * ```
+     */
+    orderBy(fn, orderBy) {
+        if (Array.isArray(this.meta.from)) {
+            const newFroms = this.meta.from.map((from) => from.orderBy(fn, orderBy));
+            return new Queryable({
+                ...this.meta,
+                from: newFroms,
+            });
+        }
+        const column = fn(this.meta.columns);
+        return new Queryable({
+            ...this.meta,
+            orderBy: [...(this.meta.orderBy ?? []), [column, orderBy]],
+        });
     }
-    const columns = fn(this.meta.columns);
-    const parsed = parseSearchQuery(searchText);
-    const conditions = [];
-    if (parsed.or.length === 1) {
-      const pattern = parsed.or[0];
-      const columnMatches = columns.map((col) => expr.like(expr.lower(col), pattern.toLowerCase()));
-      conditions.push(expr.or(columnMatches));
-    } else if (parsed.or.length > 1) {
-      const orConditions = parsed.or.map((pattern) => {
-        const columnMatches = columns.map(
-          (col) => expr.like(expr.lower(col), pattern.toLowerCase())
-        );
-        return expr.or(columnMatches);
-      });
-      conditions.push(expr.or(orConditions));
+    //#endregion
+    //#region ========== Search - WHERE ==========
+    /**
+     * WHERE 조건 추가. 여러 번 호출 시 AND로 결합됨.
+     *
+     * @param predicate - 조건 배열을 반환하는 함수
+     * @returns 조건이 추가된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.user
+     *   .where((u) => [expr.eq(u.isActive, true)])
+     *   .where((u) => [expr.gte(u.age, 18)])
+     * ```
+     */
+    where(predicate) {
+        if (Array.isArray(this.meta.from)) {
+            const newFroms = this.meta.from.map((from) => from.where(predicate));
+            return new Queryable({
+                ...this.meta,
+                from: newFroms,
+            });
+        }
+        const conditions = predicate(this.meta.columns);
+        return new Queryable({
+            ...this.meta,
+            where: [...(this.meta.where ?? []), ...conditions],
+        });
     }
-    for (const pattern of parsed.must) {
-      const columnMatches = columns.map((col) => expr.like(expr.lower(col), pattern.toLowerCase()));
-      conditions.push(expr.or(columnMatches));
+    /**
+     * 텍스트 검색 수행
+     *
+     * 검색 구문은 {@link parseSearchQuery} 참조
+     * - 공백으로 구분된 단어는 OR 조건
+     * - `+`로 시작하는 단어는 필수 포함 (AND 조건)
+     * - `-`로 시작하는 단어는 제외 (NOT 조건)
+     *
+     * @param fn - 검색 대상 column을 반환하는 함수
+     * @param searchText - 검색 텍스트
+     * @returns 검색 조건이 추가된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.user()
+     *   .search((u) => [u.name, u.email], "John Doe -withdrawn")
+     * ```
+     */
+    search(fn, searchText) {
+        if (Array.isArray(this.meta.from)) {
+            const newFroms = this.meta.from.map((from) => from.search(fn, searchText));
+            return new Queryable({
+                ...this.meta,
+                from: newFroms,
+            });
+        }
+        if (searchText.trim() === "") {
+            return this;
+        }
+        const columns = fn(this.meta.columns);
+        const parsed = parseSearchQuery(searchText);
+        const conditions = [];
+        // OR 조건: 아무 column에서 아무 패턴이 매칭되면 일치
+        if (parsed.or.length === 1) {
+            const pattern = parsed.or[0];
+            const columnMatches = columns.map((col) => expr.like(expr.lower(col), pattern.toLowerCase()));
+            conditions.push(expr.or(columnMatches));
+        }
+        else if (parsed.or.length > 1) {
+            const orConditions = parsed.or.map((pattern) => {
+                const columnMatches = columns.map((col) => expr.like(expr.lower(col), pattern.toLowerCase()));
+                return expr.or(columnMatches);
+            });
+            conditions.push(expr.or(orConditions));
+        }
+        // MUST 조건: 각 패턴이 최소 하나의 column에서 매칭되어야 함 (AND)
+        for (const pattern of parsed.must) {
+            const columnMatches = columns.map((col) => expr.like(expr.lower(col), pattern.toLowerCase()));
+            conditions.push(expr.or(columnMatches));
+        }
+        // NOT 조건: 아무 column에서도 매칭되지 않아야 함 (AND NOT)
+        for (const pattern of parsed.not) {
+            const columnMatches = columns.map((col) => expr.like(expr.lower(col), pattern.toLowerCase()));
+            conditions.push(expr.not(expr.or(columnMatches)));
+        }
+        if (conditions.length === 0) {
+            return this;
+        }
+        return this.where(() => [expr.and(conditions)]);
     }
-    for (const pattern of parsed.not) {
-      const columnMatches = columns.map((col) => expr.like(expr.lower(col), pattern.toLowerCase()));
-      conditions.push(expr.not(expr.or(columnMatches)));
+    //#endregion
+    //#region ========== Group - GROUP BY / HAVING ==========
+    /**
+     * GROUP BY 절 추가
+     *
+     * @param fn - 그룹화할 column을 반환하는 함수
+     * @returns GROUP BY가 적용된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.order()
+     *   .select((o) => ({
+     *     userId: o.userId,
+     *     totalAmount: expr.sum(o.amount),
+     *   }))
+     *   .groupBy((o) => [o.userId])
+     * ```
+     */
+    groupBy(fn) {
+        if (Array.isArray(this.meta.from)) {
+            const newFroms = this.meta.from.map((from) => from.groupBy(fn));
+            return new Queryable({
+                ...this.meta,
+                from: newFroms,
+            });
+        }
+        const groupBy = fn(this.meta.columns);
+        return new Queryable({ ...this.meta, groupBy });
     }
-    if (conditions.length === 0) {
-      return this;
+    /**
+     * HAVING 절 추가 (GROUP BY 이후 필터링)
+     *
+     * @param predicate - 조건 배열을 반환하는 함수
+     * @returns HAVING이 적용된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.order()
+     *   .select((o) => ({
+     *     userId: o.userId,
+     *     totalAmount: expr.sum(o.amount),
+     *   }))
+     *   .groupBy((o) => [o.userId])
+     *   .having((o) => [expr.gte(o.totalAmount, 10000)])
+     * ```
+     */
+    having(predicate) {
+        if (Array.isArray(this.meta.from)) {
+            const newFroms = this.meta.from.map((from) => from.having(predicate));
+            return new Queryable({
+                ...this.meta,
+                from: newFroms,
+            });
+        }
+        const conditions = predicate(this.meta.columns);
+        return new Queryable({
+            ...this.meta,
+            having: [...(this.meta.having ?? []), ...conditions],
+        });
     }
-    return this.where(() => [expr.and(conditions)]);
-  }
-  //#endregion
-  //#region ========== Group - GROUP BY / HAVING ==========
-  /**
-   * Add GROUP BY clause
-   *
-   * @param fn - Function returning columns to group by
-   * @returns Queryable with GROUP BY applied
-   *
-   * @example
-   * ```typescript
-   * db.order()
-   *   .select((o) => ({
-   *     userId: o.userId,
-   *     totalAmount: expr.sum(o.amount),
-   *   }))
-   *   .groupBy((o) => [o.userId])
-   * ```
-   */
-  groupBy(fn) {
-    if (Array.isArray(this.meta.from)) {
-      const newFroms = this.meta.from.map((from) => from.groupBy(fn));
-      return new Queryable({
-        ...this.meta,
-        from: newFroms
-      });
+    //#endregion
+    //#region ========== join - JOIN / JOIN SINGLE ==========
+    /**
+     * 1:N 관계에 대한 LEFT OUTER JOIN 수행 (결과에 배열로 추가)
+     *
+     * @param as - 결과에 추가할 속성 이름
+     * @param fn - 조인 조건을 정의하는 콜백 함수
+     * @returns 조인 결과가 배열로 추가된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.user()
+     *   .join("posts", (qr, u) =>
+     *     qr.from(Post)
+     *       .where((p) => [expr.eq(p.userId, u.id)])
+     *   )
+     * // Result: { id, name, posts: [{ id, title }, ...] }
+     * ```
+     */
+    join(as, fn) {
+        if (Array.isArray(this.meta.from)) {
+            const newFroms = this.meta.from.map((from) => from.join(as, fn));
+            return new Queryable({
+                ...this.meta,
+                from: newFroms,
+                columns: transformColumnsAlias(newFroms[0].meta.columns, this.meta.as, ""),
+            });
+        }
+        // 1. join alias Generate
+        const joinAlias = `${this.meta.as}.${as}`;
+        // 2. Transform target → Queryable (pass alias)
+        const joinQr = new JoinQueryable(this.meta.db, joinAlias);
+        // 3. Execute fn (returns Queryable with conditions like where added)
+        const resultQr = fn(joinQr, this.meta.columns);
+        // 4. Add join result to new columns
+        const joinColumns = transformColumnsAlias(resultQr.meta.columns, joinAlias);
+        return new Queryable({
+            ...this.meta,
+            columns: {
+                ...this.meta.columns,
+                [as]: [joinColumns],
+            },
+            isCustomColumns: true,
+            joins: [...(this.meta.joins ?? []), { queryable: resultQr, isSingle: false }],
+        });
     }
-    const groupBy = fn(this.meta.columns);
-    return new Queryable({ ...this.meta, groupBy });
-  }
-  /**
-   * Add HAVING clause (filtering after GROUP BY)
-   *
-   * @param predicate - Function returning an array of conditions
-   * @returns Queryable with HAVING applied
-   *
-   * @example
-   * ```typescript
-   * db.order()
-   *   .select((o) => ({
-   *     userId: o.userId,
-   *     totalAmount: expr.sum(o.amount),
-   *   }))
-   *   .groupBy((o) => [o.userId])
-   *   .having((o) => [expr.gte(o.totalAmount, 10000)])
-   * ```
-   */
-  having(predicate) {
-    if (Array.isArray(this.meta.from)) {
-      const newFroms = this.meta.from.map((from) => from.having(predicate));
-      return new Queryable({
-        ...this.meta,
-        from: newFroms
-      });
+    /**
+     * N:1 또는 1:1 관계에 대한 LEFT OUTER JOIN 수행 (결과에 단일 객체로 추가)
+     *
+     * @param as - 결과에 추가할 속성 이름
+     * @param fn - 조인 조건을 정의하는 콜백 함수
+     * @returns 조인 결과가 단일 객체로 추가된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.post()
+     *   .joinSingle("user", (qr, p) =>
+     *     qr.from(User)
+     *       .where((u) => [expr.eq(u.id, p.userId)])
+     *   )
+     * // Result: { id, title, user: { id, name } | undefined }
+     * ```
+     */
+    joinSingle(as, fn) {
+        if (Array.isArray(this.meta.from)) {
+            const newFroms = this.meta.from.map((from) => from.joinSingle(as, fn));
+            return new Queryable({
+                ...this.meta,
+                from: newFroms,
+                columns: transformColumnsAlias(newFroms[0].meta.columns, this.meta.as, ""),
+            });
+        }
+        // 1. join alias Generate
+        const joinAlias = `${this.meta.as}.${as}`;
+        // 2. Transform target → Queryable (pass alias)
+        const joinQr = new JoinQueryable(this.meta.db, joinAlias);
+        // 3. Execute fn (returns Queryable with conditions like where added)
+        const resultQr = fn(joinQr, this.meta.columns);
+        // 4. Add join result to new columns
+        const joinColumns = transformColumnsAlias(resultQr.meta.columns, joinAlias);
+        return new Queryable({
+            ...this.meta,
+            columns: {
+                ...this.meta.columns,
+                [as]: joinColumns,
+            },
+            isCustomColumns: true,
+            joins: [...(this.meta.joins ?? []), { queryable: resultQr, isSingle: true }],
+        });
     }
-    const conditions = predicate(this.meta.columns);
-    return new Queryable({
-      ...this.meta,
-      having: [...this.meta.having ?? [], ...conditions]
-    });
-  }
-  //#endregion
-  //#region ========== join - JOIN / JOIN SINGLE ==========
-  /**
-   * Perform LEFT OUTER JOIN for 1:N relation (added as array to result)
-   *
-   * @param as - Property name to add to result
-   * @param fn - Callback function defining join conditions
-   * @returns Queryable with join result added as array
-   *
-   * @example
-   * ```typescript
-   * db.user()
-   *   .join("posts", (qr, u) =>
-   *     qr.from(Post)
-   *       .where((p) => [expr.eq(p.userId, u.id)])
-   *   )
-   * // Result: { id, name, posts: [{ id, title }, ...] }
-   * ```
-   */
-  join(as, fn) {
-    if (Array.isArray(this.meta.from)) {
-      const newFroms = this.meta.from.map((from) => from.join(as, fn));
-      return new Queryable({
-        ...this.meta,
-        from: newFroms,
-        columns: transformColumnsAlias(newFroms[0].meta.columns, this.meta.as, "")
-      });
+    //#endregion
+    //#region ========== join - INCLUDE ==========
+    /**
+     * 관련 table을 자동으로 JOIN.
+     * TableBuilder에 정의된 FK/FKT 관계를 기반으로 동작.
+     *
+     * @param fn - 포함할 관계를 선택하는 함수 (PathProxy를 통해 타입 체크)
+     * @returns JOIN이 추가된 Queryable
+     * @throws 관계가 정의되지 않은 경우 에러
+     *
+     * @example
+     * ```typescript
+     * // Single relationship include
+     * db.post.include((p) => p.user)
+     *
+     * // Nested relationship include
+     * db.post.include((p) => p.user.company)
+     *
+     * // Multiple relationship include
+     * db.user
+     *   .include((u) => u.company)
+     *   .include((u) => u.posts)
+     * ```
+     */
+    include(fn) {
+        if (Array.isArray(this.meta.from)) {
+            const newFroms = this.meta.from.map((from) => from.include(fn));
+            return new Queryable({
+                ...this.meta,
+                from: newFroms,
+                columns: transformColumnsAlias(newFroms[0].meta.columns, this.meta.as, ""),
+            });
+        }
+        const proxy = createPathProxy();
+        const result = fn(proxy);
+        const relationChain = result[PATH_SYMBOL].join(".");
+        return this._include(relationChain);
     }
-    const joinAlias = `${this.meta.as}.${as}`;
-    const joinQr = new JoinQueryable(this.meta.db, joinAlias);
-    const resultQr = fn(joinQr, this.meta.columns);
-    const joinColumns = transformColumnsAlias(resultQr.meta.columns, joinAlias);
-    return new Queryable({
-      ...this.meta,
-      columns: {
-        ...this.meta.columns,
-        [as]: [joinColumns]
-      },
-      isCustomColumns: true,
-      joins: [...this.meta.joins ?? [], { queryable: resultQr, isSingle: false }]
-    });
-  }
-  /**
-   * Perform LEFT OUTER JOIN for N:1 or 1:1 relation (added as single object to result)
-   *
-   * @param as - Property name to add to result
-   * @param fn - Callback function defining join conditions
-   * @returns Queryable with join result added as single object
-   *
-   * @example
-   * ```typescript
-   * db.post()
-   *   .joinSingle("user", (qr, p) =>
-   *     qr.from(User)
-   *       .where((u) => [expr.eq(u.id, p.userId)])
-   *   )
-   * // Result: { id, title, user: { id, name } | undefined }
-   * ```
-   */
-  joinSingle(as, fn) {
-    if (Array.isArray(this.meta.from)) {
-      const newFroms = this.meta.from.map((from) => from.joinSingle(as, fn));
-      return new Queryable({
-        ...this.meta,
-        from: newFroms,
-        columns: transformColumnsAlias(newFroms[0].meta.columns, this.meta.as, "")
-      });
+    _include(relationChain) {
+        const relationNames = relationChain.split(".");
+        let result = this;
+        let currentTable = this.meta.from;
+        const chainParts = [];
+        for (const relationName of relationNames) {
+            if (!(currentTable instanceof TableBuilder)) {
+                throw new Error("include()는 TableBuilder 기반 queryable에서만 사용할 수 있습니다.");
+            }
+            const parentChain = chainParts.join(".");
+            chainParts.push(relationName);
+            // 이미 JOIN된 경우 중복 추가 방지
+            const targetAlias = `${result.meta.as}.${chainParts.join(".")}`;
+            const existingJoin = result.meta.joins?.find((j) => j.queryable.meta.as === targetAlias);
+            if (existingJoin) {
+                // 기존 JOIN의 table로 currentTable 갱신 후 계속
+                const existingFrom = existingJoin.queryable.meta.from;
+                if (existingFrom instanceof TableBuilder) {
+                    currentTable = existingFrom;
+                }
+                continue;
+            }
+            const relationDef = currentTable.meta.relations?.[relationName];
+            if (relationDef == null) {
+                throw new Error(`관계 '${relationName}'을(를) 찾을 수 없습니다.`);
+            }
+            if (relationDef instanceof ForeignKeyBuilder || relationDef instanceof RelationKeyBuilder) {
+                // FK/RelationKey (N:1): Post.user → User
+                // condition: Post.userId = User.id
+                const targetTable = relationDef.meta.targetFn();
+                const fkColKeys = relationDef.meta.columns;
+                const targetPkColKeys = getMatchedPrimaryKeys(fkColKeys, targetTable);
+                result = result.joinSingle(chainParts.join("."), (joinQr, parentCols) => {
+                    const qr = joinQr.from(targetTable);
+                    // FKT join is stored as array, so use first element if array
+                    const srcColsRaw = parentChain ? parentCols[parentChain] : parentCols;
+                    const srcCols = (Array.isArray(srcColsRaw) ? srcColsRaw[0] : srcColsRaw);
+                    const conditions = [];
+                    for (let i = 0; i < fkColKeys.length; i++) {
+                        const fkCol = srcCols[fkColKeys[i]];
+                        const pkCol = qr.meta.columns[targetPkColKeys[i]];
+                        conditions.push(expr.eq(pkCol, fkCol));
+                    }
+                    return qr.where(() => conditions);
+                });
+                currentTable = targetTable;
+            }
+            else if (relationDef instanceof ForeignKeyTargetBuilder ||
+                relationDef instanceof RelationKeyTargetBuilder) {
+                // FKT/RelationKeyTarget (1:N or 1:1): User.posts → Post[]
+                // condition: Post.userId = User.id
+                const targetTable = relationDef.meta.targetTableFn();
+                const fkRelName = relationDef.meta.relationName;
+                const sourceFk = targetTable.meta.relations?.[fkRelName];
+                if (!(sourceFk instanceof ForeignKeyBuilder) && !(sourceFk instanceof RelationKeyBuilder)) {
+                    throw new Error(`'${relationName}'이(가) 참조하는 '${fkRelName}'은(는) ` +
+                        `${targetTable.meta.name} 테이블에서 유효한 ForeignKey/RelationKey가 아닙니다.`);
+                }
+                const sourceTable = targetTable;
+                const isSingle = relationDef.meta.isSingle ?? false;
+                const fkColKeys = sourceFk.meta.columns;
+                const pkColKeys = getMatchedPrimaryKeys(fkColKeys, currentTable);
+                const buildJoin = (joinQr, parentCols) => {
+                    const qr = joinQr.from(sourceTable);
+                    // FKT join is stored as array, so use first element if array
+                    const srcColsRaw = parentChain ? parentCols[parentChain] : parentCols;
+                    const srcCols = (Array.isArray(srcColsRaw) ? srcColsRaw[0] : srcColsRaw);
+                    const conditions = [];
+                    for (let i = 0; i < fkColKeys.length; i++) {
+                        const pkCol = srcCols[pkColKeys[i]];
+                        const fkCol = qr.meta.columns[fkColKeys[i]];
+                        conditions.push(expr.eq(fkCol, pkCol));
+                    }
+                    return qr.where(() => conditions);
+                };
+                result = isSingle
+                    ? result.joinSingle(chainParts.join("."), buildJoin)
+                    : result.join(chainParts.join("."), buildJoin);
+                currentTable = sourceTable;
+            }
+        }
+        return result;
     }
-    const joinAlias = `${this.meta.as}.${as}`;
-    const joinQr = new JoinQueryable(this.meta.db, joinAlias);
-    const resultQr = fn(joinQr, this.meta.columns);
-    const joinColumns = transformColumnsAlias(resultQr.meta.columns, joinAlias);
-    return new Queryable({
-      ...this.meta,
-      columns: {
-        ...this.meta.columns,
-        [as]: joinColumns
-      },
-      isCustomColumns: true,
-      joins: [...this.meta.joins ?? [], { queryable: resultQr, isSingle: true }]
-    });
-  }
-  //#endregion
-  //#region ========== join - INCLUDE ==========
-  /**
-   * Automatically JOIN related tables.
-   * Operates based on FK/FKT relations defined in TableBuilder.
-   *
-   * @param fn - Function selecting relations to include (type-checked via PathProxy)
-   * @returns Queryable with JOINs added
-   * @throws Error if relation is not defined
-   *
-   * @example
-   * ```typescript
-   * // Single relationship include
-   * db.post.include((p) => p.user)
-   *
-   * // Nested relationship include
-   * db.post.include((p) => p.user.company)
-   *
-   * // Multiple relationship include
-   * db.user
-   *   .include((u) => u.company)
-   *   .include((u) => u.posts)
-   * ```
-   */
-  include(fn) {
-    if (Array.isArray(this.meta.from)) {
-      const newFroms = this.meta.from.map((from) => from.include(fn));
-      return new Queryable({
-        ...this.meta,
-        from: newFroms,
-        columns: transformColumnsAlias(newFroms[0].meta.columns, this.meta.as, "")
-      });
+    //#endregion
+    //#region ========== Subquery - WRAP / UNION ==========
+    /**
+     * Wrap the current Queryable as a Subquery
+     *
+     * Required when using count() after distinct() or groupBy()
+     *
+     * @returns Queryable wrapped as a Subquery
+     *
+     * @example
+     * ```typescript
+     * // Count after DISTINCT
+     * const count = await db.user()
+     *   .select((u) => ({ name: u.name }))
+     *   .distinct()
+     *   .wrap()
+     *   .count();
+     * ```
+     */
+    wrap() {
+        // Wrap the current Queryable as a Subquery
+        const wrapAlias = this.meta.db.getNextAlias();
+        return new Queryable({
+            db: this.meta.db,
+            from: this,
+            as: wrapAlias,
+            columns: transformColumnsAlias(this.meta.columns, wrapAlias, ""),
+        });
     }
-    const proxy = createPathProxy();
-    const result = fn(proxy);
-    const relationChain = result[PATH_SYMBOL].join(".");
-    return this._include(relationChain);
-  }
-  _include(relationChain) {
-    var _a, _b, _c;
-    const relationNames = relationChain.split(".");
-    let result = this;
-    let currentTable = this.meta.from;
-    const chainParts = [];
-    for (const relationName of relationNames) {
-      if (!(currentTable instanceof TableBuilder)) {
-        throw new Error("include() can only be used on TableBuilder-based queryables.");
-      }
-      const parentChain = chainParts.join(".");
-      chainParts.push(relationName);
-      const targetAlias = `${result.meta.as}.${chainParts.join(".")}`;
-      const existingJoin = (_a = result.meta.joins) == null ? void 0 : _a.find((j) => j.queryable.meta.as === targetAlias);
-      if (existingJoin) {
-        const existingFrom = existingJoin.queryable.meta.from;
-        if (existingFrom instanceof TableBuilder) {
-          currentTable = existingFrom;
+    /**
+     * Combine multiple Queryables with UNION (remove duplicates)
+     *
+     * @param queries - Array of Queryables to UNION (minimum 2)
+     * @returns UNION-ed Queryable
+     * @throws If less than 2 queryables are passed
+     *
+     * @example
+     * ```typescript
+     * const combined = Queryable.union(
+     *   db.user().where((u) => [expr.eq(u.type, "admin")]),
+     *   db.user().where((u) => [expr.eq(u.type, "manager")]),
+     * );
+     * ```
+     */
+    static union(...queries) {
+        if (queries.length < 2) {
+            throw new ArgumentError("union은 최소 2개의 queryable이 필요합니다.", {
+                provided: queries.length,
+                minimum: 2,
+            });
         }
-        continue;
-      }
-      const relationDef = (_b = currentTable.meta.relations) == null ? void 0 : _b[relationName];
-      if (relationDef == null) {
-        throw new Error(`Relation '${relationName}' not found.`);
-      }
-      if (relationDef instanceof ForeignKeyBuilder || relationDef instanceof RelationKeyBuilder) {
-        const targetTable = relationDef.meta.targetFn();
-        const fkColKeys = relationDef.meta.columns;
-        const targetPkColKeys = getMatchedPrimaryKeys(fkColKeys, targetTable);
-        result = result.joinSingle(chainParts.join("."), (joinQr, parentCols) => {
-          const qr = joinQr.from(targetTable);
-          const srcColsRaw = parentChain ? parentCols[parentChain] : parentCols;
-          const srcCols = Array.isArray(srcColsRaw) ? srcColsRaw[0] : srcColsRaw;
-          const conditions = [];
-          for (let i = 0; i < fkColKeys.length; i++) {
-            const fkCol = srcCols[fkColKeys[i]];
-            const pkCol = qr.meta.columns[targetPkColKeys[i]];
-            conditions.push(expr.eq(pkCol, fkCol));
-          }
-          return qr.where(() => conditions);
+        const first = queries[0];
+        const unionAlias = first.meta.db.getNextAlias();
+        return new Queryable({
+            db: first.meta.db,
+            from: queries, // Queryable[] 배열로 저장
+            as: unionAlias,
+            columns: transformColumnsAlias(first.meta.columns, unionAlias, ""),
         });
-        currentTable = targetTable;
-      } else if (relationDef instanceof ForeignKeyTargetBuilder || relationDef instanceof RelationKeyTargetBuilder) {
-        const targetTable = relationDef.meta.targetTableFn();
-        const fkRelName = relationDef.meta.relationName;
-        const sourceFk = (_c = targetTable.meta.relations) == null ? void 0 : _c[fkRelName];
-        if (!(sourceFk instanceof ForeignKeyBuilder) && !(sourceFk instanceof RelationKeyBuilder)) {
-          throw new Error(
-            `'${fkRelName}' referenced by '${relationName}' is not a valid ForeignKey/RelationKey in ${targetTable.meta.name} table.`
-          );
+    }
+    //#endregion
+    //#region ========== recursive - WITH RECURSIVE ==========
+    /**
+     * Generate a recursive CTE (Common Table Expression)
+     *
+     * Used for querying hierarchical data (org charts, category trees, etc.)
+     *
+     * @param fn - Callback function that defines the recursive part
+     * @returns Queryable with the recursive CTE applied
+     *
+     * @example
+     * ```typescript
+     * // Query org chart hierarchy
+     * db.employee()
+     *   .where((e) => [expr.null(e.managerId)]) // Root nodes
+     *   .recursive((cte) =>
+     *     cte.from(Employee)
+     *       .where((e) => [expr.eq(e.managerId, e.self[0].id)])
+     *   )
+     * ```
+     */
+    recursive(fn) {
+        if (Array.isArray(this.meta.from)) {
+            const newFroms = this.meta.from.map((from) => from.recursive(fn));
+            return new Queryable({
+                ...this.meta,
+                from: newFroms,
+                columns: transformColumnsAlias(newFroms[0].meta.columns, this.meta.as, ""),
+            });
         }
-        const sourceTable = targetTable;
-        const isSingle = relationDef.meta.isSingle ?? false;
-        const fkColKeys = sourceFk.meta.columns;
-        const pkColKeys = getMatchedPrimaryKeys(fkColKeys, currentTable);
-        const buildJoin = (joinQr, parentCols) => {
-          const qr = joinQr.from(sourceTable);
-          const srcColsRaw = parentChain ? parentCols[parentChain] : parentCols;
-          const srcCols = Array.isArray(srcColsRaw) ? srcColsRaw[0] : srcColsRaw;
-          const conditions = [];
-          for (let i = 0; i < fkColKeys.length; i++) {
-            const pkCol = srcCols[pkColKeys[i]];
-            const fkCol = qr.meta.columns[fkColKeys[i]];
-            conditions.push(expr.eq(fkCol, pkCol));
-          }
-          return qr.where(() => conditions);
-        };
-        result = isSingle ? result.joinSingle(chainParts.join("."), buildJoin) : result.join(chainParts.join("."), buildJoin);
-        currentTable = sourceTable;
-      }
+        // Generate dynamic CTE name
+        const cteName = this.meta.db.getNextAlias();
+        // 2. Transform target to Queryable (pass CTE name)
+        const cteQr = new RecursiveQueryable(this, cteName);
+        // 3. Execute fn (returns Queryable with conditions like where added)
+        const resultQr = fn(cteQr);
+        return new Queryable({
+            db: this.meta.db,
+            as: this.meta.as,
+            from: cteName,
+            columns: transformColumnsAlias(this.meta.columns, this.meta.as, ""),
+            with: {
+                name: cteName,
+                base: this, // Block circular reference type inference
+                recursive: resultQr,
+            },
+        });
     }
-    return result;
-  }
-  //#endregion
-  //#region ========== Subquery - WRAP / UNION ==========
-  /**
-   * Wrap the current Queryable as a Subquery
-   *
-   * Required when using count() after distinct() or groupBy()
-   *
-   * @returns Queryable wrapped as a Subquery
-   *
-   * @example
-   * ```typescript
-   * // Count after DISTINCT
-   * const count = await db.user()
-   *   .select((u) => ({ name: u.name }))
-   *   .distinct()
-   *   .wrap()
-   *   .count();
-   * ```
-   */
-  wrap() {
-    const wrapAlias = this.meta.db.getNextAlias();
-    return new Queryable({
-      db: this.meta.db,
-      from: this,
-      as: wrapAlias,
-      columns: transformColumnsAlias(this.meta.columns, wrapAlias, "")
-    });
-  }
-  /**
-   * Combine multiple Queryables with UNION (remove duplicates)
-   *
-   * @param queries - Array of Queryables to UNION (minimum 2)
-   * @returns UNION-ed Queryable
-   * @throws If less than 2 queryables are passed
-   *
-   * @example
-   * ```typescript
-   * const combined = Queryable.union(
-   *   db.user().where((u) => [expr.eq(u.type, "admin")]),
-   *   db.user().where((u) => [expr.eq(u.type, "manager")]),
-   * );
-   * ```
-   */
-  static union(...queries) {
-    if (queries.length < 2) {
-      throw new ArgumentError("union requires at least 2 queryables.", {
-        provided: queries.length,
-        minimum: 2
-      });
+    //#endregion
+    //#region ========== [query] Select - SELECT ==========
+    /**
+     * Execute a SELECT query and return the result array
+     *
+     * @returns Query result array
+     *
+     * @example
+     * ```typescript
+     * const users = await db.user()
+     *   .where((u) => [expr.eq(u.isActive, true)])
+     *   .execute();
+     * ```
+     */
+    async execute() {
+        const results = await this.meta.db.executeDefs([this.getSelectQueryDef()], [this.getResultMeta()]);
+        return results[0];
     }
-    const first = queries[0];
-    const unionAlias = first.meta.db.getNextAlias();
-    return new Queryable({
-      db: first.meta.db,
-      from: queries,
-      // stored as Queryable[] array
-      as: unionAlias,
-      columns: transformColumnsAlias(first.meta.columns, unionAlias, "")
-    });
-  }
-  //#endregion
-  //#region ========== recursive - WITH RECURSIVE ==========
-  /**
-   * Generate a recursive CTE (Common Table Expression)
-   *
-   * Used for querying hierarchical data (org charts, category trees, etc.)
-   *
-   * @param fn - Callback function that defines the recursive part
-   * @returns Queryable with the recursive CTE applied
-   *
-   * @example
-   * ```typescript
-   * // Query org chart hierarchy
-   * db.employee()
-   *   .where((e) => [expr.null(e.managerId)]) // Root nodes
-   *   .recursive((cte) =>
-   *     cte.from(Employee)
-   *       .where((e) => [expr.eq(e.managerId, e.self[0].id)])
-   *   )
-   * ```
-   */
-  recursive(fn) {
-    if (Array.isArray(this.meta.from)) {
-      const newFroms = this.meta.from.map((from) => from.recursive(fn));
-      return new Queryable({
-        ...this.meta,
-        from: newFroms,
-        columns: transformColumnsAlias(newFroms[0].meta.columns, this.meta.as, "")
-      });
+    /**
+     * Return a single result (Error if more than 1)
+     *
+     * @returns Single result or undefined
+     * @throws When more than one result is returned
+     *
+     * @example
+     * ```typescript
+     * const user = await db.user()
+     *   .where((u) => [expr.eq(u.id, 1)])
+     *   .single();
+     * ```
+     */
+    async single() {
+        const result = await this.top(2).execute();
+        if (result.length > 1) {
+            throw new ArgumentError("단일 결과를 기대했으나 복수 결과가 반환되었습니다.", {
+                table: this._getSourceName(),
+                resultCount: result.length,
+            });
+        }
+        return result[0];
     }
-    const cteName = this.meta.db.getNextAlias();
-    const cteQr = new RecursiveQueryable(this, cteName);
-    const resultQr = fn(cteQr);
-    return new Queryable({
-      db: this.meta.db,
-      as: this.meta.as,
-      from: cteName,
-      columns: transformColumnsAlias(this.meta.columns, this.meta.as, ""),
-      with: {
-        name: cteName,
-        base: this,
-        // Block circular reference type inference
-        recursive: resultQr
-      }
-    });
-  }
-  //#endregion
-  //#region ========== [query] Select - SELECT ==========
-  /**
-   * Execute a SELECT query and return the result array
-   *
-   * @returns Query result array
-   *
-   * @example
-   * ```typescript
-   * const users = await db.user()
-   *   .where((u) => [expr.eq(u.isActive, true)])
-   *   .execute();
-   * ```
-   */
-  async execute() {
-    const results = await this.meta.db.executeDefs(
-      [this.getSelectQueryDef()],
-      [this.getResultMeta()]
-    );
-    return results[0];
-  }
-  /**
-   * Return a single result (Error if more than 1)
-   *
-   * @returns Single result or undefined
-   * @throws When more than one result is returned
-   *
-   * @example
-   * ```typescript
-   * const user = await db.user()
-   *   .where((u) => [expr.eq(u.id, 1)])
-   *   .single();
-   * ```
-   */
-  async single() {
-    const result = await this.top(2).execute();
-    if (result.length > 1) {
-      throw new ArgumentError("Expected single result but multiple results returned.", {
-        table: this._getSourceName(),
-        resultCount: result.length
-      });
+    /**
+     * Query 소스 이름 반환 (에러 메시지용)
+     */
+    _getSourceName() {
+        const from = this.meta.from;
+        if (from instanceof TableBuilder || from instanceof ViewBuilder) {
+            return from.meta.name;
+        }
+        if (typeof from === "string") {
+            return from;
+        }
+        return this.meta.as;
     }
-    return result[0];
-  }
-  /**
-   * Return query source name (for error messages)
-   */
-  _getSourceName() {
-    const from = this.meta.from;
-    if (from instanceof TableBuilder || from instanceof ViewBuilder) {
-      return from.meta.name;
+    /**
+     * Return the first result (only the first even if multiple exist)
+     *
+     * @returns First result or undefined
+     *
+     * @example
+     * ```typescript
+     * const latestUser = await db.user()
+     *   .orderBy((u) => u.createdAt, "DESC")
+     *   .first();
+     * ```
+     */
+    async first() {
+        const results = await this.top(1).execute();
+        return results[0];
     }
-    if (typeof from === "string") {
-      return from;
+    /**
+     * Return the number of result rows
+     *
+     * @param fn - Function to specify the column to count (optional)
+     * @returns Number of rows
+     * @throws Error when called directly after distinct() or groupBy() (use wrap() first)
+     *
+     * @example
+     * ```typescript
+     * const count = await db.user()
+     *   .where((u) => [expr.eq(u.isActive, true)])
+     *   .count();
+     * ```
+     */
+    async count(fn) {
+        if (this.meta.distinct) {
+            throw new Error("distinct() 이후에 count()를 사용할 수 없습니다. wrap()을 먼저 사용하세요.");
+        }
+        if (this.meta.groupBy) {
+            throw new Error("groupBy() 이후에 count()를 사용할 수 없습니다. wrap()을 먼저 사용하세요.");
+        }
+        const countQr = fn
+            ? this.select((c) => ({ cnt: expr.count(fn(c)) }))
+            : this.select(() => ({ cnt: expr.count() }));
+        const result = await countQr.single();
+        return result?.cnt ?? 0;
     }
-    return this.meta.as;
-  }
-  /**
-   * Return the first result (only the first even if multiple exist)
-   *
-   * @returns First result or undefined
-   *
-   * @example
-   * ```typescript
-   * const latestUser = await db.user()
-   *   .orderBy((u) => u.createdAt, "DESC")
-   *   .first();
-   * ```
-   */
-  async first() {
-    const results = await this.top(1).execute();
-    return results[0];
-  }
-  /**
-   * Return the number of result rows
-   *
-   * @param fn - Function to specify the column to count (optional)
-   * @returns Number of rows
-   * @throws Error when called directly after distinct() or groupBy() (use wrap() first)
-   *
-   * @example
-   * ```typescript
-   * const count = await db.user()
-   *   .where((u) => [expr.eq(u.isActive, true)])
-   *   .count();
-   * ```
-   */
-  async count(fn) {
-    if (this.meta.distinct) {
-      throw new Error("Cannot use count() after distinct(). Use wrap() first.");
+    /**
+     * Check whether data matching the conditions exists
+     *
+     * @returns true if exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const hasAdmin = await db.user()
+     *   .where((u) => [expr.eq(u.role, "admin")])
+     *   .exists();
+     * ```
+     */
+    async exists() {
+        const count = await this.count();
+        return count > 0;
     }
-    if (this.meta.groupBy) {
-      throw new Error("Cannot use count() after groupBy(). Use wrap() first.");
+    getSelectQueryDef() {
+        return obj.clearUndefined({
+            type: "select",
+            from: this._buildFromDef(),
+            as: this.meta.as,
+            select: this.meta.isCustomColumns ? this._buildSelectDef(this.meta.columns, "") : undefined,
+            distinct: this.meta.distinct,
+            top: this.meta.top,
+            lock: this.meta.lock,
+            where: this.meta.where?.map((w) => w.expr),
+            joins: this.meta.joins ? this._buildJoinDefs(this.meta.joins) : undefined,
+            orderBy: this.meta.orderBy?.map((o) => (o[1] ? [o[0].expr, o[1]] : [o[0].expr])),
+            limit: this.meta.limit,
+            groupBy: this.meta.groupBy?.map((g) => g.expr),
+            having: this.meta.having?.map((w) => w.expr),
+            with: this.meta.with
+                ? {
+                    name: this.meta.with.name,
+                    base: this.meta.with.base.getSelectQueryDef(),
+                    recursive: this.meta.with.recursive.getSelectQueryDef(),
+                }
+                : undefined,
+        });
     }
-    const countQr = fn ? this.select((c) => ({ cnt: expr.count(fn(c)) })) : this.select(() => ({ cnt: expr.count() }));
-    const result = await countQr.single();
-    return (result == null ? void 0 : result.cnt) ?? 0;
-  }
-  /**
-   * Check whether data matching the conditions exists
-   *
-   * @returns true if exists, false otherwise
-   *
-   * @example
-   * ```typescript
-   * const hasAdmin = await db.user()
-   *   .where((u) => [expr.eq(u.role, "admin")])
-   *   .exists();
-   * ```
-   */
-  async exists() {
-    const count = await this.count();
-    return count > 0;
-  }
-  getSelectQueryDef() {
-    var _a, _b, _c, _d;
-    return obj.clearUndefined({
-      type: "select",
-      from: this._buildFromDef(),
-      as: this.meta.as,
-      select: this.meta.isCustomColumns ? this._buildSelectDef(this.meta.columns, "") : void 0,
-      distinct: this.meta.distinct,
-      top: this.meta.top,
-      lock: this.meta.lock,
-      where: (_a = this.meta.where) == null ? void 0 : _a.map((w) => w.expr),
-      joins: this.meta.joins ? this._buildJoinDefs(this.meta.joins) : void 0,
-      orderBy: (_b = this.meta.orderBy) == null ? void 0 : _b.map((o) => o[1] ? [o[0].expr, o[1]] : [o[0].expr]),
-      limit: this.meta.limit,
-      groupBy: (_c = this.meta.groupBy) == null ? void 0 : _c.map((g) => g.expr),
-      having: (_d = this.meta.having) == null ? void 0 : _d.map((w) => w.expr),
-      with: this.meta.with ? {
-        name: this.meta.with.name,
-        base: this.meta.with.base.getSelectQueryDef(),
-        recursive: this.meta.with.recursive.getSelectQueryDef()
-      } : void 0
-    });
-  }
-  _buildFromDef() {
-    const from = this.meta.from;
-    if (from instanceof TableBuilder || from instanceof ViewBuilder) {
-      return this.meta.db.getQueryDefObjectName(from);
-    } else if (from instanceof Queryable) {
-      return from.getSelectQueryDef();
-    } else if (Array.isArray(from)) {
-      return from.map((qr) => qr.getSelectQueryDef());
+    _buildFromDef() {
+        const from = this.meta.from;
+        if (from instanceof TableBuilder || from instanceof ViewBuilder) {
+            return this.meta.db.getQueryDefObjectName(from);
+        }
+        else if (from instanceof Queryable) {
+            return from.getSelectQueryDef();
+        }
+        else if (Array.isArray(from)) {
+            return from.map((qr) => qr.getSelectQueryDef());
+        }
+        return from;
     }
-    return from;
-  }
-  _buildSelectDef(columns, prefix) {
-    const result = {};
-    for (const [key, val] of Object.entries(columns)) {
-      const fullKey = prefix ? `${prefix}.${key}` : key;
-      if (val instanceof ExprUnit) {
-        result[fullKey] = val.expr;
-      } else if (Array.isArray(val)) {
-        if (val.length > 0) {
-          Object.assign(result, this._buildSelectDef(val[0], fullKey));
+    _buildSelectDef(columns, prefix) {
+        const result = {};
+        for (const [key, val] of Object.entries(columns)) {
+            const fullKey = prefix ? `${prefix}.${key}` : key;
+            if (val instanceof ExprUnit) {
+                result[fullKey] = val.expr;
+            }
+            else if (Array.isArray(val)) {
+                if (val.length > 0) {
+                    Object.assign(result, this._buildSelectDef(val[0], fullKey));
+                }
+            }
+            else if (typeof val === "object" && val != null) {
+                Object.assign(result, this._buildSelectDef(val, fullKey));
+            }
+            else {
+                // 일반 값 (string, number, boolean 등) — Expr로 변환
+                result[fullKey] = expr.toExpr(val);
+            }
         }
-      } else if (typeof val === "object" && val != null) {
-        Object.assign(result, this._buildSelectDef(val, fullKey));
-      } else {
-        result[fullKey] = expr.toExpr(val);
-      }
+        return result;
     }
-    return result;
-  }
-  _buildJoinDefs(joins) {
-    const result = [];
-    for (const join of joins) {
-      const joinQr = join.queryable;
-      const selectDef = joinQr.getSelectQueryDef();
-      const joinDef = {
-        ...selectDef,
-        as: joinQr.meta.as,
-        isSingle: join.isSingle
-      };
-      result.push(joinDef);
+    _buildJoinDefs(joins) {
+        const result = [];
+        for (const join of joins) {
+            const joinQr = join.queryable;
+            const selectDef = joinQr.getSelectQueryDef();
+            const joinDef = {
+                ...selectDef,
+                as: joinQr.meta.as,
+                isSingle: join.isSingle,
+            };
+            result.push(joinDef);
+        }
+        return result;
     }
-    return result;
-  }
-  getResultMeta(outputColumns) {
-    const columns = {};
-    const joins = {};
-    const buildResultMeta = (cols, prefix) => {
-      for (const [key, val] of Object.entries(cols)) {
-        const fullKey = prefix ? `${prefix}.${key}` : key;
-        if (outputColumns && !outputColumns.includes(fullKey)) continue;
-        if (val instanceof ExprUnit) {
-          columns[fullKey] = val.dataType;
-        } else if (Array.isArray(val)) {
-          if (val.length > 0) {
-            joins[fullKey] = { isSingle: false };
-            buildResultMeta(val[0], fullKey);
-          }
-        } else if (typeof val === "object") {
-          joins[fullKey] = { isSingle: true };
-          buildResultMeta(val, fullKey);
+    getResultMeta(outputColumns) {
+        const columns = {};
+        const joins = {};
+        const buildResultMeta = (cols, prefix) => {
+            for (const [key, val] of Object.entries(cols)) {
+                const fullKey = prefix ? `${prefix}.${key}` : key;
+                if (outputColumns && !outputColumns.includes(fullKey))
+                    continue;
+                if (val instanceof ExprUnit) {
+                    // 원시 column
+                    columns[fullKey] = val.dataType;
+                }
+                else if (Array.isArray(val)) {
+                    // 배열 (1:N 관계)
+                    if (val.length > 0) {
+                        joins[fullKey] = { isSingle: false };
+                        buildResultMeta(val[0], fullKey);
+                    }
+                }
+                else if (typeof val === "object") {
+                    // 단일 객체 (N:1, 1:1 관계)
+                    joins[fullKey] = { isSingle: true };
+                    buildResultMeta(val, fullKey);
+                }
+            }
+        };
+        buildResultMeta(this.meta.columns, "");
+        return { columns, joins };
+    }
+    async insert(records, outputColumns) {
+        if (records.length === 0) {
+            return outputColumns ? [] : undefined;
+        }
+        // MSSQL의 1000행 제한을 위해 청크로 분할
+        const CHUNK_SIZE = 1000;
+        const allResults = [];
+        for (let i = 0; i < records.length; i += CHUNK_SIZE) {
+            const chunk = records.slice(i, i + CHUNK_SIZE);
+            const results = await this.meta.db.executeDefs([this.getInsertQueryDef(chunk, outputColumns)], outputColumns ? [this.getResultMeta(outputColumns)] : undefined);
+            if (outputColumns) {
+                allResults.push(...results[0]);
+            }
+        }
+        if (outputColumns) {
+            return allResults;
         }
-      }
-    };
-    buildResultMeta(this.meta.columns, "");
-    return { columns, joins };
-  }
-  async insert(records, outputColumns) {
-    if (records.length === 0) {
-      return outputColumns ? [] : void 0;
     }
-    const CHUNK_SIZE = 1e3;
-    const allResults = [];
-    for (let i = 0; i < records.length; i += CHUNK_SIZE) {
-      const chunk = records.slice(i, i + CHUNK_SIZE);
-      const results = await this.meta.db.executeDefs(
-        [this.getInsertQueryDef(chunk, outputColumns)],
-        outputColumns ? [this.getResultMeta(outputColumns)] : void 0
-      );
-      if (outputColumns) {
-        allResults.push(...results[0]);
-      }
+    async insertIfNotExists(record, outputColumns) {
+        const results = await this.meta.db.executeDefs([this.getInsertIfNotExistsQueryDef(record)], outputColumns ? [this.getResultMeta(outputColumns)] : undefined);
+        if (outputColumns) {
+            return results[0][0];
+        }
     }
-    if (outputColumns) {
-      return allResults;
+    async insertInto(targetTable, outputColumns) {
+        const results = await this.meta.db.executeDefs([this.getInsertIntoQueryDef(targetTable)], outputColumns ? [this.getResultMeta(outputColumns)] : undefined);
+        if (outputColumns) {
+            return results[0];
+        }
     }
-  }
-  async insertIfNotExists(record, outputColumns) {
-    const results = await this.meta.db.executeDefs(
-      [this.getInsertIfNotExistsQueryDef(record)],
-      outputColumns ? [this.getResultMeta(outputColumns)] : void 0
-    );
-    if (outputColumns) {
-      return results[0][0];
+    getInsertQueryDef(records, outputColumns) {
+        const from = this.meta.from;
+        const outputDef = this._getCudOutputDef();
+        // AI column에 명시적 값이 있으면 overrideIdentity 설정
+        const overrideIdentity = outputDef.aiColName != null &&
+            records.some((r) => r[outputDef.aiColName] !== undefined);
+        return obj.clearUndefined({
+            type: "insert",
+            table: this.meta.db.getQueryDefObjectName(from),
+            records,
+            overrideIdentity: overrideIdentity || undefined,
+            output: outputColumns
+                ? {
+                    columns: outputColumns,
+                    pkColNames: outputDef.pkColNames,
+                    aiColName: outputDef.aiColName,
+                }
+                : undefined,
+        });
     }
-  }
-  async insertInto(targetTable, outputColumns) {
-    const results = await this.meta.db.executeDefs(
-      [this.getInsertIntoQueryDef(targetTable)],
-      outputColumns ? [this.getResultMeta(outputColumns)] : void 0
-    );
-    if (outputColumns) {
-      return results[0];
+    getInsertIfNotExistsQueryDef(record, outputColumns) {
+        const from = this.meta.from;
+        const outputDef = this._getCudOutputDef();
+        const { select: _, ...existsSelectQuery } = this.getSelectQueryDef();
+        return obj.clearUndefined({
+            type: "insertIfNotExists",
+            table: this.meta.db.getQueryDefObjectName(from),
+            record,
+            existsSelectQuery,
+            output: outputColumns
+                ? {
+                    columns: outputColumns,
+                    pkColNames: outputDef.pkColNames,
+                    aiColName: outputDef.aiColName,
+                }
+                : undefined,
+        });
     }
-  }
-  getInsertQueryDef(records, outputColumns) {
-    const from = this.meta.from;
-    const outputDef = this._getCudOutputDef();
-    const overrideIdentity = outputDef.aiColName != null && records.some((r) => r[outputDef.aiColName] !== void 0);
-    return obj.clearUndefined({
-      type: "insert",
-      table: this.meta.db.getQueryDefObjectName(from),
-      records,
-      overrideIdentity: overrideIdentity || void 0,
-      output: outputColumns ? {
-        columns: outputColumns,
-        pkColNames: outputDef.pkColNames,
-        aiColName: outputDef.aiColName
-      } : void 0
-    });
-  }
-  getInsertIfNotExistsQueryDef(record, outputColumns) {
-    const from = this.meta.from;
-    const outputDef = this._getCudOutputDef();
-    const { select: _, ...existsSelectQuery } = this.getSelectQueryDef();
-    return obj.clearUndefined({
-      type: "insertIfNotExists",
-      table: this.meta.db.getQueryDefObjectName(from),
-      record,
-      existsSelectQuery,
-      output: outputColumns ? {
-        columns: outputColumns,
-        pkColNames: outputDef.pkColNames,
-        aiColName: outputDef.aiColName
-      } : void 0
-    });
-  }
-  getInsertIntoQueryDef(targetTable, outputColumns) {
-    const outputDef = this._getCudOutputDef();
-    return obj.clearUndefined({
-      type: "insertInto",
-      table: this.meta.db.getQueryDefObjectName(targetTable),
-      recordsSelectQuery: this.getSelectQueryDef(),
-      output: outputColumns ? {
-        columns: outputColumns,
-        pkColNames: outputDef.pkColNames,
-        aiColName: outputDef.aiColName
-      } : void 0
-    });
-  }
-  async update(recordFwd, outputColumns) {
-    const results = await this.meta.db.executeDefs(
-      [this.getUpdateQueryDef(recordFwd, outputColumns)],
-      outputColumns ? [this.getResultMeta(outputColumns)] : void 0
-    );
-    if (outputColumns) {
-      return results[0];
+    getInsertIntoQueryDef(targetTable, outputColumns) {
+        const outputDef = this._getCudOutputDef();
+        return obj.clearUndefined({
+            type: "insertInto",
+            table: this.meta.db.getQueryDefObjectName(targetTable),
+            recordsSelectQuery: this.getSelectQueryDef(),
+            output: outputColumns
+                ? {
+                    columns: outputColumns,
+                    pkColNames: outputDef.pkColNames,
+                    aiColName: outputDef.aiColName,
+                }
+                : undefined,
+        });
     }
-  }
-  async delete(outputColumns) {
-    const results = await this.meta.db.executeDefs(
-      [this.getDeleteQueryDef(outputColumns)],
-      outputColumns ? [this.getResultMeta(outputColumns)] : void 0
-    );
-    if (outputColumns) {
-      return results[0];
+    async update(recordFwd, outputColumns) {
+        const results = await this.meta.db.executeDefs([this.getUpdateQueryDef(recordFwd, outputColumns)], outputColumns ? [this.getResultMeta(outputColumns)] : undefined);
+        if (outputColumns) {
+            return results[0];
+        }
     }
-  }
-  getUpdateQueryDef(recordFwd, outputColumns) {
-    var _a;
-    const from = this.meta.from;
-    const outputDef = this._getCudOutputDef();
-    return obj.clearUndefined({
-      type: "update",
-      table: this.meta.db.getQueryDefObjectName(from),
-      as: this.meta.as,
-      record: this._buildSelectDef(recordFwd(this.meta.columns), ""),
-      top: this.meta.top,
-      where: (_a = this.meta.where) == null ? void 0 : _a.map((w) => w.expr),
-      joins: this.meta.joins ? this._buildJoinDefs(this.meta.joins) : void 0,
-      limit: this.meta.limit,
-      output: outputColumns ? {
-        columns: outputColumns,
-        pkColNames: outputDef.pkColNames,
-        aiColName: outputDef.aiColName
-      } : void 0
-    });
-  }
-  getDeleteQueryDef(outputColumns) {
-    var _a;
-    const from = this.meta.from;
-    const outputDef = this._getCudOutputDef();
-    return obj.clearUndefined({
-      type: "delete",
-      table: this.meta.db.getQueryDefObjectName(from),
-      as: this.meta.as,
-      top: this.meta.top,
-      where: (_a = this.meta.where) == null ? void 0 : _a.map((w) => w.expr),
-      joins: this.meta.joins ? this._buildJoinDefs(this.meta.joins) : void 0,
-      limit: this.meta.limit,
-      output: outputColumns ? {
-        columns: outputColumns,
-        pkColNames: outputDef.pkColNames,
-        aiColName: outputDef.aiColName
-      } : void 0
-    });
-  }
-  async upsert(updateFnOrInsertFn, insertFnOrOutputColumns, outputColumns) {
-    const updateRecordFn = updateFnOrInsertFn;
-    const insertRecordFn = insertFnOrOutputColumns instanceof Function ? insertFnOrOutputColumns : updateFnOrInsertFn;
-    const realOutputColumns = insertFnOrOutputColumns instanceof Function ? outputColumns : insertFnOrOutputColumns;
-    const results = await this.meta.db.executeDefs(
-      [this.getUpsertQueryDef(updateRecordFn, insertRecordFn, realOutputColumns)],
-      [realOutputColumns ? this.getResultMeta(realOutputColumns) : void 0]
-    );
-    if (realOutputColumns) {
-      return results[0];
+    async delete(outputColumns) {
+        const results = await this.meta.db.executeDefs([this.getDeleteQueryDef(outputColumns)], outputColumns ? [this.getResultMeta(outputColumns)] : undefined);
+        if (outputColumns) {
+            return results[0];
+        }
     }
-  }
-  getUpsertQueryDef(updateRecordFn, insertRecordFn, outputColumns) {
-    const from = this.meta.from;
-    const outputDef = this._getCudOutputDef();
-    const { select: _sel, ...existsSelectQuery } = this.getSelectQueryDef();
-    const updateQrRecord = updateRecordFn(this.meta.columns);
-    const updateRecord = {};
-    for (const [key, value] of Object.entries(updateQrRecord)) {
-      updateRecord[key] = expr.toExpr(value);
+    getUpdateQueryDef(recordFwd, outputColumns) {
+        const from = this.meta.from;
+        const outputDef = this._getCudOutputDef();
+        return obj.clearUndefined({
+            type: "update",
+            table: this.meta.db.getQueryDefObjectName(from),
+            as: this.meta.as,
+            record: this._buildSelectDef(recordFwd(this.meta.columns), ""),
+            top: this.meta.top,
+            where: this.meta.where?.map((w) => w.expr),
+            joins: this.meta.joins ? this._buildJoinDefs(this.meta.joins) : undefined,
+            limit: this.meta.limit,
+            output: outputColumns
+                ? {
+                    columns: outputColumns,
+                    pkColNames: outputDef.pkColNames,
+                    aiColName: outputDef.aiColName,
+                }
+                : undefined,
+        });
     }
-    const insertRecordRaw = insertRecordFn(updateQrRecord);
-    const insertRecord = Object.fromEntries(
-      Object.entries(insertRecordRaw).map(([key, value]) => [key, expr.toExpr(value)])
-    );
-    return obj.clearUndefined({
-      type: "upsert",
-      table: this.meta.db.getQueryDefObjectName(from),
-      existsSelectQuery,
-      updateRecord,
-      insertRecord,
-      output: outputColumns ? {
-        columns: outputColumns,
-        pkColNames: outputDef.pkColNames,
-        aiColName: outputDef.aiColName
-      } : void 0
-    });
-  }
-  //#endregion
-  //#region ========== DDL Helper ==========
-  /**
-   * FK constraint on/off (can be used within a transaction)
-   */
-  async switchFk(enabled) {
-    const from = this.meta.from;
-    if (!(from instanceof TableBuilder) && !(from instanceof ViewBuilder)) {
-      throw new Error(
-        "switchFk can only be used on TableBuilder or ViewBuilder based queryables."
-      );
+    getDeleteQueryDef(outputColumns) {
+        const from = this.meta.from;
+        const outputDef = this._getCudOutputDef();
+        return obj.clearUndefined({
+            type: "delete",
+            table: this.meta.db.getQueryDefObjectName(from),
+            as: this.meta.as,
+            top: this.meta.top,
+            where: this.meta.where?.map((w) => w.expr),
+            joins: this.meta.joins ? this._buildJoinDefs(this.meta.joins) : undefined,
+            limit: this.meta.limit,
+            output: outputColumns
+                ? {
+                    columns: outputColumns,
+                    pkColNames: outputDef.pkColNames,
+                    aiColName: outputDef.aiColName,
+                }
+                : undefined,
+        });
+    }
+    async upsert(updateFnOrInsertFn, insertFnOrOutputColumns, outputColumns) {
+        const updateRecordFn = updateFnOrInsertFn;
+        const insertRecordFn = (insertFnOrOutputColumns instanceof Function ? insertFnOrOutputColumns : updateFnOrInsertFn);
+        const realOutputColumns = insertFnOrOutputColumns instanceof Function ? outputColumns : insertFnOrOutputColumns;
+        const results = await this.meta.db.executeDefs([this.getUpsertQueryDef(updateRecordFn, insertRecordFn, realOutputColumns)], [realOutputColumns ? this.getResultMeta(realOutputColumns) : undefined]);
+        if (realOutputColumns) {
+            return results[0];
+        }
+    }
+    getUpsertQueryDef(updateRecordFn, insertRecordFn, outputColumns) {
+        const from = this.meta.from;
+        const outputDef = this._getCudOutputDef();
+        const { select: _sel, ...existsSelectQuery } = this.getSelectQueryDef();
+        // updateRecord 생성
+        const updateQrRecord = updateRecordFn(this.meta.columns);
+        const updateRecord = {};
+        for (const [key, value] of Object.entries(updateQrRecord)) {
+            updateRecord[key] = expr.toExpr(value);
+        }
+        // insertRecord 생성 (updateRecordRaw를 두 번째 인자로 전달)
+        const insertRecordRaw = insertRecordFn(updateQrRecord);
+        const insertRecord = Object.fromEntries(Object.entries(insertRecordRaw).map(([key, value]) => [key, expr.toExpr(value)]));
+        return obj.clearUndefined({
+            type: "upsert",
+            table: this.meta.db.getQueryDefObjectName(from),
+            existsSelectQuery,
+            updateRecord,
+            insertRecord,
+            output: outputColumns
+                ? {
+                    columns: outputColumns,
+                    pkColNames: outputDef.pkColNames,
+                    aiColName: outputDef.aiColName,
+                }
+                : undefined,
+        });
+    }
+    //#endregion
+    //#region ========== DDL Helper ==========
+    /**
+     * FK 제약조건 활성화/비활성화 (트랜잭션 내에서 사용 가능)
+     */
+    async switchFk(enabled) {
+        const from = this.meta.from;
+        if (!(from instanceof TableBuilder) && !(from instanceof ViewBuilder)) {
+            throw new Error("switchFk는 TableBuilder 또는 ViewBuilder 기반 queryable에서만 사용할 수 있습니다.");
+        }
+        await this.meta.db.switchFk(this.meta.db.getQueryDefObjectName(from), enabled);
     }
-    await this.meta.db.switchFk(this.meta.db.getQueryDefObjectName(from), enabled);
-  }
-  //#endregion
-  //#region ========== CUD Common ==========
-  _getCudOutputDef() {
-    const from = this.meta.from;
-    if (from instanceof TableBuilder) {
-      if (from.meta.columns == null) {
-        throw new Error(`Table '${from.meta.name}' has no Column definition.`);
-      }
-      let aiColName;
-      for (const [key, col] of Object.entries(from.meta.columns)) {
-        if (col.meta.autoIncrement) {
-          aiColName = key;
+    //#endregion
+    //#region ========== CUD Common ==========
+    _getCudOutputDef() {
+        const from = this.meta.from;
+        if (from instanceof TableBuilder) {
+            if (from.meta.columns == null) {
+                throw new Error(`테이블 '${from.meta.name}'에 Column 정의가 없습니다.`);
+            }
+            let aiColName;
+            for (const [key, col] of Object.entries(from.meta.columns)) {
+                if (col.meta.autoIncrement) {
+                    aiColName = key;
+                }
+            }
+            return {
+                pkColNames: from.meta.primaryKey ?? [],
+                aiColName,
+            };
         }
-      }
-      return {
-        pkColNames: from.meta.primaryKey ?? [],
-        aiColName
-      };
+        throw new Error("CUD 작업은 TableBuilder 기반 queryable에서만 사용할 수 있습니다.");
     }
-    throw new Error("CUD operations can only be used on TableBuilder-based queryables.");
-  }
-  //#endregion
 }
-function getMatchedPrimaryKeys(fkCols, targetTable) {
-  const pk = targetTable.meta.primaryKey;
-  if (pk == null || fkCols.length !== pk.length) {
-    throw new Error(
-      `FK/PK column count mismatch (target: ${targetTable.meta.name}, FK: ${fkCols.length}, PK: ${(pk == null ? void 0 : pk.length) ?? 0})`
-    );
-  }
-  return pk;
+//#region ========== Helper Functions ==========
+/**
+ * Match FK column array with the target Table's PK and return PK column name array
+ *
+ * @param fkCols - FK column name array
+ * @param targetTable - Target Table builder being referenced
+ * @returns Matched PK column name array
+ * @throws When FK/PK column count mismatch
+ */
+export function getMatchedPrimaryKeys(fkCols, targetTable) {
+    const pk = targetTable.meta.primaryKey;
+    if (pk == null || fkCols.length !== pk.length) {
+        throw new Error(`FK/PK column count mismatch (target: ${targetTable.meta.name}, FK: ${fkCols.length}, PK: ${pk?.length ?? 0})`);
+    }
+    return pk;
 }
+/**
+ * Common helper to transform nested columns structure to a new alias
+ *
+ * When wrapping as Subquery/JOIN, transforms existing alias to new alias while
+ * keeping nested keys (posts.userId) as flattened keys.
+ *
+ * e.g.: If the path of posts[0].userId column is ["T1.posts", "userId"],
+ *       transforming to new alias "T2" yields ["T2", "posts.userId"].
+ *
+ * @param columns - Column record to transform
+ * @param alias - New Table alias (e.g., "T2")
+ * @param keyPrefix - Current nested path (for recursive calls, default "")
+ * @returns Transformed column record
+ */
 function transformColumnsAlias(columns, alias, keyPrefix = "") {
-  const result = {};
-  for (const [key, value] of Object.entries(columns)) {
-    const fullKey = keyPrefix ? `${keyPrefix}.${key}` : key;
-    if (value instanceof ExprUnit) {
-      result[key] = expr.col(value.dataType, alias, fullKey);
-    } else if (Array.isArray(value)) {
-      if (value.length > 0) {
-        result[key] = [
-          transformColumnsAlias(value[0], alias, fullKey)
-        ];
-      }
-    } else if (typeof value === "object" && value != null) {
-      result[key] = transformColumnsAlias(value, alias, fullKey);
-    } else {
-      result[key] = value;
+    const result = {};
+    for (const [key, value] of Object.entries(columns)) {
+        const fullKey = keyPrefix ? `${keyPrefix}.${key}` : key;
+        if (value instanceof ExprUnit) {
+            result[key] = expr.col(value.dataType, alias, fullKey);
+        }
+        else if (Array.isArray(value)) {
+            if (value.length > 0) {
+                result[key] = [
+                    transformColumnsAlias(value[0], alias, fullKey),
+                ];
+            }
+        }
+        else if (typeof value === "object" && value != null) {
+            result[key] = transformColumnsAlias(value, alias, fullKey);
+        }
+        else {
+            result[key] = value;
+        }
     }
-  }
-  return result;
+    return result;
 }
-const PATH_SYMBOL = /* @__PURE__ */ Symbol("path");
+const PATH_SYMBOL = Symbol("path");
+/**
+ * PathProxy 인스턴스 생성
+ * Proxy를 사용하여 속성 접근을 가로채고 경로를 수집
+ */
 function createPathProxy(path = []) {
-  return new Proxy({}, {
-    get(_, prop) {
-      if (prop === PATH_SYMBOL) return path;
-      if (typeof prop === "symbol") return void 0;
-      return createPathProxy([...path, prop]);
-    }
-  });
+    return new Proxy({}, {
+        get(_, prop) {
+            if (prop === PATH_SYMBOL)
+                return path;
+            if (typeof prop === "symbol")
+                return undefined;
+            return createPathProxy([...path, prop]);
+        },
+    });
 }
-function queryable(db, tableOrView, as) {
-  return () => {
-    const finalAs = as ?? db.getNextAlias();
-    if (tableOrView instanceof TableBuilder && tableOrView.meta.columns != null) {
-      const columnDefs = tableOrView.meta.columns;
-      return new Queryable({
-        db,
-        from: tableOrView,
-        as: finalAs,
-        columns: Object.fromEntries(
-          Object.entries(columnDefs).map(([key, colDef]) => [
-            key,
-            expr.col(colDef.meta.type, finalAs, key)
-          ])
-        )
-      });
-    }
-    if (tableOrView instanceof ViewBuilder && tableOrView.meta.viewFn != null) {
-      const baseQr = tableOrView.meta.viewFn(db);
-      return new Queryable({
-        db,
-        from: tableOrView,
-        as: finalAs,
-        columns: transformColumnsAlias(baseQr.meta.columns, finalAs)
-      });
-    }
-    throw new Error(`Invalid Table/View Metadata: ${tableOrView.meta.name}`);
-  };
+//#endregion
+/**
+ * Table 또는 View용 Queryable factory 함수 생성
+ *
+ * DbContext에서 Table/View별 getter를 정의할 때 사용
+ *
+ * @param db - DbContext 인스턴스
+ * @param tableOrView - TableBuilder 또는 ViewBuilder 인스턴스
+ * @param as - Alias 지정 (선택, 미지정 시 자동 생성)
+ * @returns Queryable을 반환하는 factory 함수
+ *
+ * @example
+ * ```typescript
+ * class AppDbContext extends DbContext {
+ *   // 호출할 때마다 새 alias가 할당됨
+ *   user = queryable(this, User);
+ *
+ *   // 사용 예시
+ *   async getActiveUsers() {
+ *     return this.user()
+ *       .where((u) => [expr.eq(u.isActive, true)])
+ *       .execute();
+ *   }
+ * }
+ * ```
+ */
+export function queryable(db, tableOrView, as) {
+    return () => {
+        // as가 미지정이면 db.getNextAlias() 사용 (카운터 증가)
+        // as가 지정되면 그대로 사용 (카운터 증가 없음)
+        const finalAs = as ?? db.getNextAlias();
+        // TableBuilder + columns
+        if (tableOrView instanceof TableBuilder && tableOrView.meta.columns != null) {
+            const columnDefs = tableOrView.meta.columns;
+            return new Queryable({
+                db,
+                from: tableOrView,
+                as: finalAs,
+                columns: Object.fromEntries(Object.entries(columnDefs).map(([key, colDef]) => [
+                    key,
+                    expr.col(colDef.meta.type, finalAs, key),
+                ])),
+            });
+        }
+        // ViewBuilder + viewFn
+        if (tableOrView instanceof ViewBuilder && tableOrView.meta.viewFn != null) {
+            const baseQr = tableOrView.meta.viewFn(db);
+            // TFrom을 ViewBuilder로 설정하여 반환
+            return new Queryable({
+                db,
+                from: tableOrView,
+                as: finalAs,
+                columns: transformColumnsAlias(baseQr.meta.columns, finalAs),
+            });
+        }
+        throw new Error(`Invalid Table/View Metadata: ${tableOrView.meta.name}`);
+    };
 }
-export {
-  Queryable,
-  getMatchedPrimaryKeys,
-  queryable
-};
-//# sourceMappingURL=queryable.js.map
+//#endregion
+//# sourceMappingURL=queryable.js.map