@simplysm/orm-common 13.0.99 → 14.0.1

package/dist/exec/queryable.d.ts

@@ -10,39 +10,39 @@ import { ExprUnit } from "../expr/expr-unit";
 /**
  * JOIN query builder
  *
- * Used internally by join/joinSingle methods to specify the table to join
+ * join/joinSingle 메서드 내부에서 조인할 table을 지정하는 데 사용
  */
 declare class JoinQueryable {
     private readonly _db;
     private readonly _joinAlias;
     constructor(_db: DbContextBase, _joinAlias: string);
     /**
-     * Specify the table to join
+     * 조인할 table 지정
      *
-     * @param table - Table to join
-     * @returns Joined Queryable
+     * @param table - 조인할 table
+     * @returns 조인된 Queryable
      */
     from<T extends TableBuilder<any, any>>(table: T): Queryable<T["$inferSelect"], T>;
     /**
-     * Directly specify columns in join result
+     * 조인 결과의 column을 직접 지정
      *
-     * @param columns - Custom column definition
-     * @returns Queryable with custom columns applied
+     * @param columns - 커스텀 column 정의
+     * @returns 커스텀 column이 적용된 Queryable
      */
     select<R extends DataRecord>(columns: QueryableRecord<R>): Queryable<R, never>;
     /**
-     * Combine multiple Queryables with UNION
+     * 여러 Queryable을 UNION으로 결합
      *
-     * @param queries - Array of Queryables to UNION (minimum 2)
-     * @returns UNION-ed Queryable
-     * @throws If less than 2 queryables are passed
+     * @param queries - UNION할 Queryable 배열 (최소 2개)
+     * @returns UNION된 Queryable
+     * @throws 2개 미만의 queryable이 전달되면 에러
      */
     union<TData extends DataRecord>(...queries: Queryable<TData, any>[]): Queryable<TData, never>;
 }
 /**
- * Recursive CTE (Common Table Expression) builder
+ * 재귀 CTE (Common Table Expression) builder
  *
- * used internally in recursive() method, Defines the body of a recursive query
+ * recursive() 메서드 내부에서 사용되며, 재귀 쿼리의 본문을 정의한다
  *
  * @template TBaseData - Base query data type
  */
@@ -51,41 +51,41 @@ declare class RecursiveQueryable<TBaseData extends DataRecord> {
     private readonly _cteName;
     constructor(_baseQr: Queryable<TBaseData, any>, _cteName: string);
     /**
-     * specify the target table for recursive query
+     * 재귀 query의 대상 table 지정
      *
-     * @param table - Target table to recurse
-     * @returns Queryable with self property added (for self-reference)
+     * @param table - 재귀할 대상 table
+     * @returns self 속성이 추가된 Queryable (자기 참조용)
      */
     from<T extends TableBuilder<any, any>>(table: T): Queryable<T["$inferSelect"] & {
         self?: TBaseData[];
     }, T>;
     /**
-     * Directly specify columns in recursive query
+     * 재귀 query의 column을 직접 지정
      *
-     * @param columns - Custom column definition
-     * @returns Queryable with self property added
+     * @param columns - 커스텀 column 정의
+     * @returns self 속성이 추가된 Queryable
      */
     select<R extends DataRecord>(columns: QueryableRecord<R>): Queryable<R & {
         self?: TBaseData[];
     }, never>;
     /**
-     * Combine multiple Queryables with UNION (for recursive query)
+     * 여러 Queryable을 UNION으로 결합 (재귀 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
+     * @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>;
 }
 /**
- * Query builder class
+ * Query builder 클래스
  *
- * Construct SELECT, INSERT, UPDATE, DELETE queries on tables/views in a chaining manner
+ * 체이닝 방식으로 table/view에 대한 SELECT, INSERT, UPDATE, DELETE query를 구성
  *
- * @template TData - Data type of query result
- * @template TFrom - Source table (needed for CUD operations)
+ * @template TData - Query 결과의 데이터 타입
+ * @template TFrom - 소스 table (CUD 연산에 필요)
  *
  * @example
  * ```typescript
@@ -108,10 +108,10 @@ export declare class Queryable<TData extends DataRecord, TFrom extends TableBuil
     readonly meta: QueryableMeta<TData>;
     constructor(meta: QueryableMeta<TData>);
     /**
-     * Specify columns to SELECT.
+     * SELECT할 column 지정.
      *
-     * @param fn - Column mapping function. Receives original columns and returns new column structure
-     * @returns Queryable with new column structure applied
+     * @param fn - Column 매핑 함수. 원본 column을 받아 새 column 구조를 반환
+     * @returns 새 column 구조가 적용된 Queryable
      *
      * @example
      * ```typescript
@@ -123,9 +123,9 @@ export declare class Queryable<TData extends DataRecord, TFrom extends TableBuil
      */
     select<R extends Record<string, any>>(fn: (columns: QueryableRecord<TData>) => R): Queryable<UnwrapQueryableRecord<R>, never>;
     /**
-     * Apply DISTINCT option to remove duplicate rows
+     * 중복 행 제거를 위한 DISTINCT 옵션 적용
      *
-     * @returns Queryable with DISTINCT applied
+     * @returns DISTINCT가 적용된 Queryable
      *
      * @example
      * ```typescript
@@ -136,11 +136,11 @@ export declare class Queryable<TData extends DataRecord, TFrom extends TableBuil
      */
     distinct(): Queryable<TData, never>;
     /**
-     * Apply row lock (FOR UPDATE)
+     * 행 잠금 적용 (FOR UPDATE)
      *
-     * Acquire exclusive lock on selected rows within transaction
+     * 트랜잭션 내에서 선택된 행에 대한 배타적 잠금 획득
      *
-     * @returns Queryable with lock applied
+     * @returns 잠금이 적용된 Queryable
      *
      * @example
      * ```typescript
@@ -154,10 +154,10 @@ export declare class Queryable<TData extends DataRecord, TFrom extends TableBuil
      */
     lock(): Queryable<TData, TFrom>;
     /**
-     * Select only top N rows (can be used without ORDER BY)
+     * 상위 N개 행만 선택 (ORDER BY 없이도 사용 가능)
      *
-     * @param count - number of rows to select
-     * @returns Queryable with TOP applied
+     * @param count - 선택할 행 수
+     * @returns TOP이 적용된 Queryable
      *
      * @example
      * ```typescript
@@ -169,13 +169,13 @@ export declare class Queryable<TData extends DataRecord, TFrom extends TableBuil
      */
     top(count: number): Queryable<TData, TFrom>;
     /**
-     * Set LIMIT/OFFSET for pagination.
-     * Must call orderBy() first.
+     * 페이지네이션을 위한 LIMIT/OFFSET 설정.
+     * 먼저 orderBy()를 호출해야 함.
      *
-     * @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
+     * @param skip - 건너뛸 행 수 (OFFSET)
+     * @param take - 가져올 행 수 (LIMIT)
+     * @returns 페이지네이션이 적용된 Queryable
+     * @throws ORDER BY 절이 없으면 에러
      *
      * @example
      * ```typescript
@@ -186,11 +186,11 @@ export declare class Queryable<TData extends DataRecord, TFrom extends TableBuil
      */
     limit(skip: number, take: number): Queryable<TData, TFrom>;
     /**
-     * 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
+     * @param fn - 정렬할 column을 반환하는 함수
+     * @param orderBy - 정렬 방향 (ASC/DESC). 기본값: ASC
+     * @returns 정렬 조건이 추가된 Queryable
      *
      * @example
      * ```typescript
@@ -201,10 +201,10 @@ export declare class Queryable<TData extends DataRecord, TFrom extends TableBuil
      */
     orderBy(fn: (columns: QueryableRecord<TData>) => ExprUnit<ColumnPrimitive>, orderBy?: "ASC" | "DESC"): Queryable<TData, TFrom>;
     /**
-     * Add WHERE condition. Multiple calls are combined with AND.
+     * WHERE 조건 추가. 여러 번 호출 시 AND로 결합됨.
      *
-     * @param predicate - Function returning an array of conditions
-     * @returns Queryable with conditions added
+     * @param predicate - 조건 배열을 반환하는 함수
+     * @returns 조건이 추가된 Queryable
      *
      * @example
      * ```typescript
@@ -215,16 +215,16 @@ export declare class Queryable<TData extends DataRecord, TFrom extends TableBuil
      */
     where(predicate: (columns: QueryableRecord<TData>) => WhereExprUnit[]): Queryable<TData, TFrom>;
     /**
-     * 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)
+     * 검색 구문은 {@link parseSearchQuery} 참조
+     * - 공백으로 구분된 단어는 OR 조건
+     * - `+`로 시작하는 단어는 필수 포함 (AND 조건)
+     * - `-`로 시작하는 단어는 제외 (NOT 조건)
      *
-     * @param fn - Function returning target columns to search
-     * @param searchText - Search text
-     * @returns Queryable with search conditions added
+     * @param fn - 검색 대상 column을 반환하는 함수
+     * @param searchText - 검색 텍스트
+     * @returns 검색 조건이 추가된 Queryable
      *
      * @example
      * ```typescript
@@ -234,10 +234,10 @@ export declare class Queryable<TData extends DataRecord, TFrom extends TableBuil
      */
     search(fn: (columns: QueryableRecord<TData>) => ExprUnit<string | undefined>[], searchText: string): Queryable<TData, TFrom>;
     /**
-     * Add GROUP BY clause
+     * GROUP BY 절 추가
      *
-     * @param fn - Function returning columns to group by
-     * @returns Queryable with GROUP BY applied
+     * @param fn - 그룹화할 column을 반환하는 함수
+     * @returns GROUP BY가 적용된 Queryable
      *
      * @example
      * ```typescript
@@ -251,10 +251,10 @@ export declare class Queryable<TData extends DataRecord, TFrom extends TableBuil
      */
     groupBy(fn: (columns: QueryableRecord<TData>) => ExprUnit<ColumnPrimitive>[]): Queryable<TData, never>;
     /**
-     * Add HAVING clause (filtering after GROUP BY)
+     * HAVING 절 추가 (GROUP BY 이후 필터링)
      *
-     * @param predicate - Function returning an array of conditions
-     * @returns Queryable with HAVING applied
+     * @param predicate - 조건 배열을 반환하는 함수
+     * @returns HAVING이 적용된 Queryable
      *
      * @example
      * ```typescript
@@ -269,11 +269,11 @@ export declare class Queryable<TData extends DataRecord, TFrom extends TableBuil
      */
     having(predicate: (columns: QueryableRecord<TData>) => WhereExprUnit[]): Queryable<TData, never>;
     /**
-     * Perform LEFT OUTER JOIN for 1:N relation (added as array to result)
+     * 1:N 관계에 대한 LEFT OUTER JOIN 수행 (결과에 배열로 추가)
      *
-     * @param as - Property name to add to result
-     * @param fn - Callback function defining join conditions
-     * @returns Queryable with join result added as array
+     * @param as - 결과에 추가할 속성 이름
+     * @param fn - 조인 조건을 정의하는 콜백 함수
+     * @returns 조인 결과가 배열로 추가된 Queryable
      *
      * @example
      * ```typescript
@@ -289,11 +289,11 @@ export declare class Queryable<TData extends DataRecord, TFrom extends TableBuil
         [K in A]?: R[];
     }, TFrom>;
     /**
-     * Perform LEFT OUTER JOIN for N:1 or 1:1 relation (added as single object to result)
+     * N:1 또는 1:1 관계에 대한 LEFT OUTER JOIN 수행 (결과에 단일 객체로 추가)
      *
-     * @param as - Property name to add to result
-     * @param fn - Callback function defining join conditions
-     * @returns Queryable with join result added as single object
+     * @param as - 결과에 추가할 속성 이름
+     * @param fn - 조인 조건을 정의하는 콜백 함수
+     * @returns 조인 결과가 단일 객체로 추가된 Queryable
      *
      * @example
      * ```typescript
@@ -311,12 +311,12 @@ export declare class Queryable<TData extends DataRecord, TFrom extends TableBuil
         [K in A]?: R;
     }, TFrom>;
     /**
-     * Automatically JOIN related tables.
-     * Operates based on FK/FKT relations defined in TableBuilder.
+     * 관련 table을 자동으로 JOIN.
+     * TableBuilder에 정의된 FK/FKT 관계를 기반으로 동작.
      *
-     * @param fn - Function selecting relations to include (type-checked via PathProxy)
-     * @returns Queryable with JOINs added
-     * @throws Error if relation is not defined
+     * @param fn - 포함할 관계를 선택하는 함수 (PathProxy를 통해 타입 체크)
+     * @returns JOIN이 추가된 Queryable
+     * @throws 관계가 정의되지 않은 경우 에러
      *
      * @example
      * ```typescript
@@ -416,7 +416,7 @@ export declare class Queryable<TData extends DataRecord, TFrom extends TableBuil
      */
     single(): Promise<TData | undefined>;
     /**
-     * Return query source name (for error messages)
+     * Query 소스 이름 반환 (에러 메시지용)
      */
     private _getSourceName;
     /**
@@ -610,7 +610,7 @@ export declare class Queryable<TData extends DataRecord, TFrom extends TableBuil
     upsert<U extends QueryableWriteRecord<TFrom["$inferUpdate"]>, K extends keyof TFrom["$inferColumns"] & string>(updateFn: (cols: QueryableRecord<TData>) => U, insertFn: (updateRecord: U) => QueryableWriteRecord<TFrom["$inferInsert"]>, outputColumns?: K[]): Promise<Pick<TFrom["$inferColumns"], K>[]>;
     getUpsertQueryDef<U extends QueryableWriteRecord<TFrom["$inferUpdate"]>>(updateRecordFn: (cols: QueryableRecord<TData>) => U, insertRecordFn: (updateRecord: U) => QueryableWriteRecord<TFrom["$inferInsert"]>, outputColumns?: (keyof TFrom["$inferColumns"] & string)[]): UpsertQueryDef;
     /**
-     * FK constraint on/off (can be used within a transaction)
+     * FK 제약조건 활성화/비활성화 (트랜잭션 내에서 사용 가능)
      */
     switchFk(enabled: boolean): Promise<void>;
     private _getCudOutputDef;
@@ -659,33 +659,33 @@ export type NullableQueryableRecord<TData extends DataRecord> = {
     [K in keyof TData]: TData[K] extends ColumnPrimitive ? ExprUnit<TData[K] | undefined> : TData[K] extends (infer U)[] ? U extends DataRecord ? NullableQueryableRecord<U>[] : never : TData[K] extends (infer U)[] | undefined ? U extends DataRecord ? NullableQueryableRecord<U>[] | undefined : never : TData[K] extends DataRecord ? NullableQueryableRecord<TData[K]> : TData[K] extends DataRecord | undefined ? NullableQueryableRecord<Exclude<TData[K], undefined>> | undefined : never;
 };
 /**
- * Reverse-transform from QueryableRecord to DataRecord
+ * QueryableRecord에서 DataRecord로 역변환
  *
- * Unwraps ExprUnit<T> to T, recursively unwrapping nested objects/arrays
+ * ExprUnit<T>를 T로 언래핑, 중첩 객체/배열을 재귀적으로 언래핑
  */
 export type UnwrapQueryableRecord<R> = {
     [K in keyof R]: R[K] extends ExprUnit<infer T> ? T : NonNullable<R[K]> extends (infer U)[] ? U extends Record<string, any> ? UnwrapQueryableRecord<U>[] | Extract<R[K], undefined> : never : NonNullable<R[K]> extends Record<string, any> ? UnwrapQueryableRecord<NonNullable<R[K]>> | Extract<R[K], undefined> : never;
 };
 /**
- * Proxy type for specifying relationship paths in include() in a type-safe manner
- * Only non-ColumnPrimitive fields (FK, FKT relationships) are accessible
+ * include()에서 타입 안전하게 관계 경로를 지정하기 위한 Proxy 타입
+ * non-ColumnPrimitive 필드(FK, FKT 관계)만 접근 가능
  *
  * @example
  * ```typescript
- * // Accessing item.user.company internally collects path ["user", "company"]
+ * // item.user.company 접근 시 내부적으로 경로 ["user", "company"]를 수집
  * db.post.include(item => item.user.company)
  *
- * // item.title is string (ColumnPrimitive), so this is a compile error
- * db.post.include(item => item.title) // compile error
+ * // item.title은 string(ColumnPrimitive)이므로 컴파일 에러
+ * db.post.include(item => item.title) // 컴파일 에러
  * ```
  */
 /**
- * Extract element type if array
+ * 배열이면 요소 타입 추출
  */
 type UnwrapArray<TArray> = TArray extends (infer TElement)[] ? TElement : TArray;
 declare const PATH_SYMBOL: unique symbol;
 /**
- * Type-safe path proxy for include()
+ * include()용 타입 안전 path proxy
  */
 export type PathProxy<TObject> = {
     [K in keyof TObject as TObject[K] extends ColumnPrimitive ? never : K]-?: PathProxy<UnwrapArray<TObject[K]>>;
@@ -693,22 +693,22 @@ export type PathProxy<TObject> = {
     readonly [PATH_SYMBOL]: string[];
 };
 /**
- * Generate a Queryable factory function for a Table or View
+ * Table 또는 View용 Queryable factory 함수 생성
  *
- * Used when defining per-Table/View getters in DbContext
+ * DbContext에서 Table/View별 getter를 정의할 때 사용
  *
- * @param db - DbContext instance
- * @param tableOrView - TableBuilder or ViewBuilder instance
- * @param as - Alias specification (optional, auto-created if not specified)
- * @returns Factory function that returns a Queryable
+ * @param db - DbContext 인스턴스
+ * @param tableOrView - TableBuilder 또는 ViewBuilder 인스턴스
+ * @param as - Alias 지정 (선택, 미지정 시 자동 생성)
+ * @returns Queryable을 반환하는 factory 함수
  *
  * @example
  * ```typescript
  * class AppDbContext extends DbContext {
- *   // A new alias is assigned on each call
+ *   // 호출할 때마다 새 alias가 할당됨
  *   user = queryable(this, User);
  *
- *   // Usage example
+ *   // 사용 예시
  *   async getActiveUsers() {
  *     return this.user()
  *       .where((u) => [expr.eq(u.isActive, true)])