@simplysm/orm-node 13.0.0-beta.11

package/dist/orm-common/src/exec/queryable.d.ts

@@ -0,0 +1,708 @@
+import { TableBuilder } from "../schema/table-builder";
+import { ViewBuilder } from "../schema/view-builder";
+import type { DataRecord, ResultMeta } from "../types/db";
+import type { DeleteQueryDef, InsertIfNotExistsQueryDef, InsertIntoQueryDef, InsertQueryDef, SelectQueryDef, UpdateQueryDef, UpsertQueryDef } from "../types/query-def";
+import type { DbContext } from "../db-context";
+import { type DataToColumnBuilderRecord } from "../schema/factory/column-builder";
+import type { ColumnPrimitive } from "../types/column";
+import type { WhereExprUnit } from "../expr/expr-unit";
+import { ExprUnit } from "../expr/expr-unit";
+/**
+ * JOIN 쿼리 빌더
+ *
+ * join/joinSingle 메서드 내부에서 사용되며, 조인 대상 테이블을 지정하는 역할을 수행
+ */
+declare class JoinQueryable {
+    private readonly _db;
+    private readonly _joinAlias;
+    constructor(_db: DbContext, _joinAlias: string);
+    /**
+     * 조인할 테이블을 지정
+     *
+     * @param table - 조인 대상 테이블
+     * @returns 조인된 Queryable
+     */
+    from<T extends TableBuilder<any, any>>(table: T): Queryable<T["$infer"], T>;
+    /**
+     * 조인 결과의 컬럼을 직접 지정
+     *
+     * @param columns - 커스텀 컬럼 정의
+     * @returns 커스텀 컬럼이 적용된 Queryable
+     */
+    select<R extends DataRecord>(columns: QueryableRecord<R>): Queryable<R, never>;
+    /**
+     * 여러 Queryable을 UNION으로 결합
+     *
+     * @param queries - UNION할 Queryable 배열 (최소 2개)
+     * @returns UNION된 Queryable
+     * @throws 2개 미만의 queryable이 전달된 경우
+     */
+    union<TData extends DataRecord>(...queries: Queryable<TData, any>[]): Queryable<TData, never>;
+}
+/**
+ * 재귀 CTE(Common Table Expression) 빌더
+ *
+ * recursive() 메서드 내부에서 사용되며, 재귀 쿼리의 본문을 정의하는 역할을 수행
+ *
+ * @template TBaseData - 기본 쿼리의 데이터 타입
+ */
+declare class RecursiveQueryable<TBaseData extends DataRecord> {
+    private readonly _baseQr;
+    private readonly _cteName;
+    constructor(_baseQr: Queryable<TBaseData, any>, _cteName: string);
+    /**
+     * 재귀 쿼리의 대상 테이블을 지정
+     *
+     * @param table - 재귀할 대상 테이블
+     * @returns self 속성이 추가된 Queryable (자기 참조용)
+     */
+    from<T extends TableBuilder<any, any>>(table: T): Queryable<T["$infer"] & {
+        self?: TBaseData[];
+    }, T>;
+    /**
+     * 재귀 쿼리의 컬럼을 직접 지정
+     *
+     * @param columns - 커스텀 컬럼 정의
+     * @returns self 속성이 추가된 Queryable
+     */
+    select<R extends DataRecord>(columns: QueryableRecord<R>): Queryable<R & {
+        self?: TBaseData[];
+    }, never>;
+    /**
+     * 여러 Queryable을 UNION으로 결합 (재귀 쿼리용)
+     *
+     * @param queries - UNION할 Queryable 배열 (최소 2개)
+     * @returns self 속성이 추가된 UNION Queryable
+     * @throws 2개 미만의 queryable이 전달된 경우
+     */
+    union<TData extends DataRecord>(...queries: Queryable<TData, any>[]): Queryable<TData & {
+        self?: TBaseData[];
+    }, never>;
+}
+/**
+ * 쿼리 빌더 클래스
+ *
+ * 테이블/뷰에 대한 SELECT, INSERT, UPDATE, DELETE 등의 쿼리를 체이닝 방식으로 구성
+ *
+ * @template TData - 쿼리 결과의 데이터 타입
+ * @template TFrom - 원본 테이블 (CUD 작업에 필요)
+ *
+ * @example
+ * ```typescript
+ * // 기본 조회
+ * const users = await db.user()
+ *   .where((u) => [expr.eq(u.isActive, true)])
+ *   .orderBy((u) => u.name)
+ *   .result();
+ *
+ * // JOIN 조회
+ * const posts = await db.post()
+ *   .include((p) => p.user)
+ *   .result();
+ *
+ * // INSERT
+ * await db.user().insert([{ name: "홍길동", email: "test@test.com" }]);
+ * ```
+ */
+export declare class Queryable<TData extends DataRecord, TFrom extends TableBuilder<any, any> | never> {
+    readonly meta: QueryableMeta<TData>;
+    constructor(meta: QueryableMeta<TData>);
+    /**
+     * SELECT할 컬럼을 지정합니다.
+     *
+     * @param fn - 컬럼 매핑 함수. 원본 컬럼을 받아 새 컬럼 구조를 반환
+     * @returns 새로운 컬럼 구조가 적용된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.user().select((u) => ({
+     *   userName: u.name,
+     *   userEmail: u.email,
+     * }))
+     * ```
+     */
+    select<R extends DataRecord>(fn: (columns: QueryableRecord<TData>) => QueryableRecord<R>): Queryable<R, never>;
+    /**
+     * DISTINCT 옵션을 적용하여 중복 행을 제거
+     *
+     * @returns DISTINCT가 적용된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.user()
+     *   .select((u) => ({ name: u.name }))
+     *   .distinct()
+     * ```
+     */
+    distinct(): Queryable<TData, never>;
+    /**
+     * 행 잠금(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(): Queryable<TData, TFrom>;
+    /**
+     * 상위 N개의 행만 조회 (ORDER BY 없이 사용 가능)
+     *
+     * @param count - 조회할 행 수
+     * @returns TOP이 적용된 Queryable
+     *
+     * @example
+     * ```typescript
+     * // 최신 사용자 10명
+     * db.user()
+     *   .orderBy((u) => u.createdAt, "DESC")
+     *   .top(10)
+     * ```
+     */
+    top(count: number): Queryable<TData, TFrom>;
+    /**
+     * 페이지네이션을 위한 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) // 첫 20개
+     * ```
+     */
+    limit(skip: number, take: number): Queryable<TData, TFrom>;
+    /**
+     * 정렬 조건을 추가합니다. 여러 번 호출하면 순서대로 적용됩니다.
+     *
+     * @param fn - 정렬 기준 컬럼을 반환하는 함수
+     * @param orderBy - 정렬 방향 (ASC/DESC). 기본값: ASC
+     * @returns 정렬 조건이 추가된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.user
+     *   .orderBy((u) => u.name)           // 이름 ASC
+     *   .orderBy((u) => u.age, "DESC")    // 나이 DESC
+     * ```
+     */
+    orderBy(fn: (columns: QueryableRecord<TData>) => ExprUnit<ColumnPrimitive>, orderBy?: "ASC" | "DESC"): Queryable<TData, TFrom>;
+    /**
+     * 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: (columns: QueryableRecord<TData>) => WhereExprUnit[]): Queryable<TData, TFrom>;
+    /**
+     * 텍스트 검색을 수행
+     *
+     * 검색 문법은 {@link parseSearchQuery}를 참조
+     * - 공백으로 구분된 단어는 OR 조건
+     * - `+`로 시작하는 단어는 필수 포함 (AND 조건)
+     * - `-`로 시작하는 단어는 제외 (NOT 조건)
+     *
+     * @param fn - 검색 대상 컬럼을 반환하는 함수
+     * @param searchText - 검색 텍스트
+     * @returns 검색 조건이 추가된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.user()
+     *   .search((u) => [u.name, u.email], "홍길동 -탈퇴")
+     * ```
+     */
+    search(fn: (columns: QueryableRecord<TData>) => ExprUnit<string | undefined>[], searchText: string): Queryable<TData, TFrom>;
+    /**
+     * GROUP BY 절을 추가
+     *
+     * @param fn - 그룹화 기준 컬럼을 반환하는 함수
+     * @returns GROUP BY가 적용된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.order()
+     *   .select((o) => ({
+     *     userId: o.userId,
+     *     totalAmount: expr.sum(o.amount),
+     *   }))
+     *   .groupBy((o) => [o.userId])
+     * ```
+     */
+    groupBy(fn: (columns: QueryableRecord<TData>) => ExprUnit<ColumnPrimitive>[]): Queryable<TData, never>;
+    /**
+     * 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: (columns: QueryableRecord<TData>) => WhereExprUnit[]): Queryable<TData, never>;
+    /**
+     * 1:N 관계의 LEFT OUTER JOIN을 수행 (배열로 결과 추가)
+     *
+     * @param as - 결과에 추가할 속성 이름
+     * @param fwd - 조인 조건을 정의하는 콜백 함수
+     * @returns 조인 결과가 배열로 추가된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.user()
+     *   .join("posts", (qr, u) =>
+     *     qr.from(Post)
+     *       .where((p) => [expr.eq(p.userId, u.id)])
+     *   )
+     * // 결과: { id, name, posts: [{ id, title }, ...] }
+     * ```
+     */
+    join<A extends string, R extends DataRecord>(as: A, fwd: (qr: JoinQueryable, cols: QueryableRecord<TData>) => Queryable<R, any>): Queryable<TData & {
+        [K in A]?: R[];
+    }, TFrom>;
+    /**
+     * N:1 또는 1:1 관계의 LEFT OUTER JOIN을 수행 (단일 객체로 결과 추가)
+     *
+     * @param as - 결과에 추가할 속성 이름
+     * @param fwd - 조인 조건을 정의하는 콜백 함수
+     * @returns 조인 결과가 단일 객체로 추가된 Queryable
+     *
+     * @example
+     * ```typescript
+     * db.post()
+     *   .joinSingle("user", (qr, p) =>
+     *     qr.from(User)
+     *       .where((u) => [expr.eq(u.id, p.userId)])
+     *   )
+     * // 결과: { id, title, user: { id, name } | undefined }
+     * ```
+     */
+    joinSingle<A extends string, R extends DataRecord>(as: A, fwd: (qr: JoinQueryable, cols: QueryableRecord<TData>) => Queryable<R, any>): Queryable<{
+        [K in keyof TData as K extends A ? never : K]: TData[K];
+    } & {
+        [K in A]?: R;
+    }, TFrom>;
+    /**
+     * 관계된 테이블을 자동으로 JOIN합니다.
+     * TableBuilder에 정의된 FK/FKT 관계를 기반으로 동작합니다.
+     *
+     * @param fn - 포함할 관계를 선택하는 함수 (PathProxy를 통해 타입 체크됨)
+     * @returns JOIN이 추가된 Queryable
+     * @throws 관계가 정의되지 않은 경우 에러
+     *
+     * @example
+     * ```typescript
+     * // 단일 관계 포함
+     * db.post.include((p) => p.user)
+     *
+     * // 중첩 관계 포함
+     * db.post.include((p) => p.user.company)
+     *
+     * // 다중 관계 포함
+     * db.user
+     *   .include((u) => u.company)
+     *   .include((u) => u.posts)
+     * ```
+     */
+    include(fn: (item: PathProxy<TData>) => PathProxy<any>): Queryable<TData, TFrom>;
+    private _include;
+    /**
+     * 현재 Queryable을 서브쿼리로 감싸기
+     *
+     * distinct() 또는 groupBy() 후 count() 사용 시 필요
+     *
+     * @returns 서브쿼리로 감싸진 Queryable
+     *
+     * @example
+     * ```typescript
+     * // DISTINCT 후 카운트
+     * const count = await db.user()
+     *   .select((u) => ({ name: u.name }))
+     *   .distinct()
+     *   .wrap()
+     *   .count();
+     * ```
+     */
+    wrap(): Queryable<TData, never>;
+    /**
+     * 여러 Queryable을 UNION으로 결합 (중복 제거)
+     *
+     * @param queries - UNION할 Queryable 배열 (최소 2개)
+     * @returns UNION된 Queryable
+     * @throws 2개 미만의 queryable이 전달된 경우
+     *
+     * @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<TData extends DataRecord>(...queries: Queryable<TData, any>[]): Queryable<TData, never>;
+    /**
+     * 재귀 CTE(Common Table Expression)를 생성
+     *
+     * 계층 구조 데이터(조직도, 카테고리 트리 등)를 조회할 때 사용
+     *
+     * @param fwd - 재귀 부분을 정의하는 콜백 함수
+     * @returns 재귀 CTE가 적용된 Queryable
+     *
+     * @example
+     * ```typescript
+     * // 조직도 계층 조회
+     * db.employee()
+     *   .where((e) => [expr.null(e.managerId)]) // 루트 노드
+     *   .recursive((cte) =>
+     *     cte.from(Employee)
+     *       .where((e) => [expr.eq(e.managerId, e.self[0].id)])
+     *   )
+     * ```
+     */
+    recursive(fwd: (qr: RecursiveQueryable<TData>) => Queryable<TData, any>): Queryable<TData, never>;
+    /**
+     * SELECT 쿼리를 실행하고 결과 배열을 반환
+     *
+     * @returns 쿼리 결과 배열
+     *
+     * @example
+     * ```typescript
+     * const users = await db.user()
+     *   .where((u) => [expr.eq(u.isActive, true)])
+     *   .result();
+     * ```
+     */
+    result(): Promise<TData[]>;
+    /**
+     * 단일 결과를 반환 (2개 이상이면 에러)
+     *
+     * @returns 단일 결과 또는 undefined
+     * @throws 2개 이상의 결과가 반환된 경우
+     *
+     * @example
+     * ```typescript
+     * const user = await db.user()
+     *   .where((u) => [expr.eq(u.id, 1)])
+     *   .single();
+     * ```
+     */
+    single(): Promise<TData | undefined>;
+    /**
+     * 쿼리 소스 이름 반환 (에러 메시지용)
+     */
+    private _getSourceName;
+    /**
+     * 첫 번째 결과를 반환 (여러 개여도 첫 번째만)
+     *
+     * @returns 첫 번째 결과 또는 undefined
+     *
+     * @example
+     * ```typescript
+     * const latestUser = await db.user()
+     *   .orderBy((u) => u.createdAt, "DESC")
+     *   .first();
+     * ```
+     */
+    first(): Promise<TData | undefined>;
+    /**
+     * 결과 행 수를 반환
+     *
+     * @param fwd - 카운트할 컬럼을 지정하는 함수 (선택)
+     * @returns 행 수
+     * @throws distinct() 또는 groupBy() 후 직접 호출 시 에러 (wrap() 필요)
+     *
+     * @example
+     * ```typescript
+     * const count = await db.user()
+     *   .where((u) => [expr.eq(u.isActive, true)])
+     *   .count();
+     * ```
+     */
+    count(fwd?: (cols: QueryableRecord<TData>) => ExprUnit<ColumnPrimitive>): Promise<number>;
+    /**
+     * 조건에 맞는 데이터 존재 여부를 확인
+     *
+     * @returns 존재하면 true, 없으면 false
+     *
+     * @example
+     * ```typescript
+     * const hasAdmin = await db.user()
+     *   .where((u) => [expr.eq(u.role, "admin")])
+     *   .exists();
+     * ```
+     */
+    exists(): Promise<boolean>;
+    getSelectQueryDef(): SelectQueryDef;
+    private _buildFromDef;
+    private _buildSelectDef;
+    private _buildJoinDefs;
+    getResultMeta(outputColumns?: string[]): ResultMeta;
+    /**
+     * INSERT 쿼리를 실행
+     *
+     * MSSQL의 1000개 제한을 위해 자동으로 1000개씩 청크로 분할하여 실행
+     *
+     * @param records - 삽입할 레코드 배열
+     * @param outputColumns - 반환받을 컬럼 이름 배열 (선택)
+     * @returns outputColumns 지정 시 삽입된 레코드 배열 반환
+     *
+     * @example
+     * ```typescript
+     * // 단순 삽입
+     * await db.user().insert([
+     *   { name: "홍길동", email: "hong@test.com" },
+     * ]);
+     *
+     * // 삽입 후 ID 반환
+     * const [inserted] = await db.user().insert(
+     *   [{ name: "홍길동" }],
+     *   ["id"],
+     * );
+     * ```
+     */
+    insert(records: TFrom["$inferInsert"][]): Promise<void>;
+    insert<K extends keyof TFrom["$inferColumns"] & string>(records: TFrom["$inferInsert"][], outputColumns: K[]): Promise<Pick<TFrom["$inferColumns"], K>[]>;
+    /**
+     * WHERE 조건에 맞는 데이터가 없으면 INSERT
+     *
+     * @param record - 삽입할 레코드
+     * @param outputColumns - 반환받을 컬럼 이름 배열 (선택)
+     * @returns outputColumns 지정 시 삽입된 레코드 반환
+     *
+     * @example
+     * ```typescript
+     * await db.user()
+     *   .where((u) => [expr.eq(u.email, "test@test.com")])
+     *   .insertIfNotExists({ name: "테스트", email: "test@test.com" });
+     * ```
+     */
+    insertIfNotExists(record: TFrom["$inferInsert"]): Promise<void>;
+    insertIfNotExists<K extends keyof TFrom["$inferColumns"] & string>(record: TFrom["$inferInsert"], outputColumns: K[]): Promise<Pick<TFrom["$inferColumns"], K>>;
+    /**
+     * INSERT INTO ... SELECT (현재 SELECT 결과를 다른 테이블에 INSERT)
+     *
+     * @param targetTable - 삽입 대상 테이블
+     * @param outputColumns - 반환받을 컬럼 이름 배열 (선택)
+     * @returns outputColumns 지정 시 삽입된 레코드 배열 반환
+     *
+     * @example
+     * ```typescript
+     * await db.user()
+     *   .select((u) => ({ name: u.name, createdAt: u.createdAt }))
+     *   .where((u) => [expr.eq(u.isArchived, false)])
+     *   .insertInto(ArchivedUser);
+     * ```
+     */
+    insertInto<TTable extends TableBuilder<DataToColumnBuilderRecord<TData>, any>>(targetTable: TTable): Promise<void>;
+    insertInto<TTable extends TableBuilder<DataToColumnBuilderRecord<TData>, any>, TOut extends keyof TTable["$inferColumns"] & string>(targetTable: TTable, outputColumns: TOut[]): Promise<Pick<TData, TOut>[]>;
+    getInsertQueryDef(records: TFrom["$inferInsert"][], outputColumns?: (keyof TFrom["$inferColumns"] & string)[]): InsertQueryDef;
+    getInsertIfNotExistsQueryDef(record: TFrom["$inferInsert"], outputColumns?: (keyof TFrom["$inferColumns"] & string)[]): InsertIfNotExistsQueryDef;
+    getInsertIntoQueryDef<TTable extends TableBuilder<DataToColumnBuilderRecord<TData>, any>>(targetTable: TTable, outputColumns?: (keyof TTable["$inferColumns"] & string)[]): InsertIntoQueryDef;
+    /**
+     * UPDATE 쿼리를 실행
+     *
+     * @param recordFwd - 업데이트할 컬럼과 값을 반환하는 함수
+     * @param outputColumns - 반환받을 컬럼 이름 배열 (선택)
+     * @returns outputColumns 지정 시 업데이트된 레코드 배열 반환
+     *
+     * @example
+     * ```typescript
+     * // 단순 업데이트
+     * await db.user()
+     *   .where((u) => [expr.eq(u.id, 1)])
+     *   .update((u) => ({
+     *     name: expr.val("string", "새이름"),
+     *     updatedAt: expr.val("DateTime", DateTime.now()),
+     *   }));
+     *
+     * // 기존 값 참조
+     * await db.product()
+     *   .update((p) => ({
+     *     price: expr.mul(p.price, expr.val("number", 1.1)),
+     *   }));
+     * ```
+     */
+    update(recordFwd: (cols: QueryableRecord<TData>) => QueryableRecord<TFrom["$inferUpdate"]>): Promise<void>;
+    update<K extends keyof TFrom["$columns"] & string>(recordFwd: (cols: QueryableRecord<TData>) => QueryableRecord<TFrom["$inferUpdate"]>, outputColumns: K[]): Promise<Pick<TFrom["$columns"], K>[]>;
+    /**
+     * DELETE 쿼리를 실행
+     *
+     * @param outputColumns - 반환받을 컬럼 이름 배열 (선택)
+     * @returns outputColumns 지정 시 삭제된 레코드 배열 반환
+     *
+     * @example
+     * ```typescript
+     * // 단순 삭제
+     * await db.user()
+     *   .where((u) => [expr.eq(u.id, 1)])
+     *   .delete();
+     *
+     * // 삭제된 데이터 반환
+     * const deleted = await db.user()
+     *   .where((u) => [expr.eq(u.isExpired, true)])
+     *   .delete(["id", "name"]);
+     * ```
+     */
+    delete(): Promise<void>;
+    delete<K extends keyof TFrom["$columns"] & string>(outputColumns: K[]): Promise<Pick<TFrom["$columns"], K>[]>;
+    getUpdateQueryDef(recordFwd: (cols: QueryableRecord<TData>) => QueryableRecord<TFrom["$inferUpdate"]>, outputColumns?: (keyof TFrom["$inferColumns"] & string)[]): UpdateQueryDef;
+    getDeleteQueryDef(outputColumns?: (keyof TFrom["$inferColumns"] & string)[]): DeleteQueryDef;
+    /**
+     * UPSERT (UPDATE or INSERT) 쿼리를 실행
+     *
+     * WHERE 조건에 맞는 데이터가 있으면 UPDATE, 없으면 INSERT
+     *
+     * @param updateFwd - 업데이트할 컬럼과 값을 반환하는 함수
+     * @param insertFwd - 삽입할 레코드를 반환하는 함수 (선택, 미지정 시 updateFwd와 동일)
+     * @param outputColumns - 반환받을 컬럼 이름 배열 (선택)
+     * @returns outputColumns 지정 시 영향받은 레코드 배열 반환
+     *
+     * @example
+     * ```typescript
+     * // UPDATE/INSERT 동일 데이터
+     * await db.user()
+     *   .where((u) => [expr.eq(u.email, "test@test.com")])
+     *   .upsert(() => ({
+     *     name: expr.val("string", "테스트"),
+     *     email: expr.val("string", "test@test.com"),
+     *   }));
+     *
+     * // UPDATE/INSERT 다른 데이터
+     * await db.user()
+     *   .where((u) => [expr.eq(u.email, "test@test.com")])
+     *   .upsert(
+     *     () => ({ loginCount: expr.val("number", 1) }),
+     *     (update) => ({ ...update, email: expr.val("string", "test@test.com") }),
+     *   );
+     * ```
+     */
+    upsert(updateFwd: (cols: QueryableRecord<TData>) => QueryableRecord<TFrom["$inferUpdate"]>): Promise<void>;
+    upsert<K extends keyof TFrom["$inferColumns"] & string>(insertFwd: (cols: QueryableRecord<TData>) => QueryableRecord<TFrom["$inferInsert"]>, outputColumns?: K[]): Promise<Pick<TFrom["$inferColumns"], K>[]>;
+    upsert<U extends QueryableRecord<TFrom["$inferUpdate"]>>(updateFwd: (cols: QueryableRecord<TData>) => U, insertFwd: (updateRecord: U) => QueryableRecord<TFrom["$inferInsert"]>): Promise<void>;
+    upsert<U extends QueryableRecord<TFrom["$inferUpdate"]>, K extends keyof TFrom["$inferColumns"] & string>(updateFwd: (cols: QueryableRecord<TData>) => U, insertFwd: (updateRecord: U) => QueryableRecord<TFrom["$inferInsert"]>, outputColumns?: K[]): Promise<Pick<TFrom["$inferColumns"], K>[]>;
+    getUpsertQueryDef<U extends QueryableRecord<TFrom["$inferUpdate"]>>(updateRecordFwd: (cols: QueryableRecord<TData>) => U, insertRecordFwd: (updateRecord: U) => QueryableRecord<TFrom["$inferInsert"]>, outputColumns?: (keyof TFrom["$inferColumns"] & string)[]): UpsertQueryDef;
+    /**
+     * FK 제약조건 on/off (트랜잭션 내 사용 가능)
+     */
+    switchFk(switch_: "on" | "off"): Promise<void>;
+    private _getCudOutputDef;
+}
+/**
+ * FK 컬럼 배열과 대상 테이블의 PK를 매칭하여 PK 컬럼명 배열을 반환
+ *
+ * @param fkCols - FK 컬럼명 배열
+ * @param targetTable - 참조 대상 테이블 빌더
+ * @returns 매칭된 PK 컬럼명 배열
+ * @throws FK/PK 컬럼 수 불일치 시
+ */
+export declare function getMatchedPrimaryKeys(fkCols: string[], targetTable: TableBuilder<any, any>): string[];
+interface QueryableMeta<TData extends DataRecord> {
+    db: DbContext;
+    from?: TableBuilder<any, any> | ViewBuilder<any, any, any> | Queryable<any, any> | Queryable<TData, any>[] | string;
+    as: string;
+    columns: QueryableRecord<TData>;
+    isCustomColumns?: boolean;
+    distinct?: boolean;
+    top?: number;
+    lock?: boolean;
+    where?: WhereExprUnit[];
+    joins?: QueryableMetaJoin[];
+    orderBy?: [ExprUnit<ColumnPrimitive>, ("ASC" | "DESC")?][];
+    limit?: [number, number];
+    groupBy?: ExprUnit<ColumnPrimitive>[];
+    having?: WhereExprUnit[];
+    with?: {
+        name: string;
+        base: Queryable<any, any>;
+        recursive: Queryable<any, any>;
+    };
+}
+interface QueryableMetaJoin {
+    queryable: Queryable<any, any>;
+    isSingle: boolean;
+}
+export type QueryableRecord<TData extends DataRecord> = {
+    [K in keyof TData]: TData[K] extends ColumnPrimitive ? ExprUnit<TData[K]> : TData[K] extends (infer U)[] ? U extends DataRecord ? QueryableRecord<U>[] : never : TData[K] extends (infer U)[] | undefined ? U extends DataRecord ? QueryableRecord<U>[] | undefined : never : TData[K] extends DataRecord ? QueryableRecord<TData[K]> : TData[K] extends DataRecord | undefined ? QueryableRecord<Exclude<TData[K], undefined>> | undefined : never;
+};
+/**
+ * include()에서 관계 경로를 타입 안전하게 지정하기 위한 Proxy 타입
+ * ColumnPrimitive가 아닌 필드(FK, FKT 관계)만 접근 가능
+ *
+ * @example
+ * ```typescript
+ * // item.user.company 접근 시 내부적으로 ["user", "company"] 경로 수집
+ * db.post.include(item => item.user.company)
+ *
+ * // item.title은 string(ColumnPrimitive)이므로 컴파일 에러
+ * db.post.include(item => item.title) // ❌ 에러
+ * ```
+ */
+/**
+ * 배열이면 요소 타입 추출
+ */
+type UnwrapArray<T> = T extends (infer U)[] ? U : T;
+declare const PATH_SYMBOL: unique symbol;
+/**
+ * include()용 타입 안전 경로 프록시
+ */
+export type PathProxy<T> = {
+    [K in keyof T as T[K] extends ColumnPrimitive ? never : K]-?: PathProxy<UnwrapArray<T[K]>>;
+} & {
+    readonly [PATH_SYMBOL]: string[];
+};
+/**
+ * 테이블 또는 뷰에 대한 Queryable 팩토리 함수를 생성
+ *
+ * DbContext에서 테이블/뷰별 getter를 정의할 때 사용
+ *
+ * @param db - DbContext 인스턴스
+ * @param tableOrView - TableBuilder 또는 ViewBuilder 인스턴스
+ * @param as - alias 지정 (선택, 미지정 시 자동 생성)
+ * @returns Queryable을 반환하는 팩토리 함수
+ *
+ * @example
+ * ```typescript
+ * class AppDbContext extends DbContext {
+ *   // 호출 시마다 새로운 alias 할당
+ *   user = queryable(this, User);
+ *
+ *   // 사용 예시
+ *   async getActiveUsers() {
+ *     return this.user()
+ *       .where((u) => [expr.eq(u.isActive, true)])
+ *       .result();
+ *   }
+ * }
+ * ```
+ */
+export declare function queryable<T extends TableBuilder<any, any> | ViewBuilder<any, any, any>>(db: DbContext, tableOrView: T, as?: string): () => Queryable<T["$infer"], T extends TableBuilder<any, any> ? T : never>;
+export {};
+//# sourceMappingURL=queryable.d.ts.map