@simplysm/orm-common 13.0.99 → 14.0.1

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

@@ -7,13 +7,13 @@ import type { ViewBuilder } from "../view-builder";
 // ============================================
 
 /**
- * Foreign Key relation builder (N:1)
+ * Foreign Key 관계 builder (N:1)
  *
- * Define FK relation from current Table to target Table
- * Creates actual FK constraint in the DB
+ * 현재 Table에서 대상 Table로의 FK 관계를 정의
+ * DB에 실제 FK 제약조건을 생성
  *
- * @template TOwner - Owner Table builder type
- * @template TTargetFn - Target Table builder factory type
+ * @template TOwner - 소유 Table builder 타입
+ * @template TTargetFn - 대상 Table builder factory 타입
  *
  * @example
  * ```typescript
@@ -29,19 +29,19 @@ import type { ViewBuilder } from "../view-builder";
  *   }));
  * ```
  *
- * @see {@link ForeignKeyTargetBuilder} Reverse-reference builder
- * @see {@link RelationKeyBuilder} Relation without DB FK
+ * @see {@link ForeignKeyTargetBuilder} 역참조 builder
+ * @see {@link RelationKeyBuilder} DB FK 없는 관계
  */
 export class ForeignKeyBuilder<
   TOwner extends TableBuilder<any, any>,
   TTargetFn extends () => TableBuilder<any, any>,
 > {
   /**
-   * @param meta - FK Metadata
-   * @param meta.ownerFn - Owner Table factory
-   * @param meta.columns - FK column name array
-   * @param meta.targetFn - Target Table factory
-   * @param meta.description - Relation description
+   * @param meta - FK 메타데이터
+   * @param meta.ownerFn - 소유 Table factory
+   * @param meta.columns - FK column 이름 배열
+   * @param meta.targetFn - 대상 Table factory
+   * @param meta.description - 관계 설명
    */
   constructor(
     readonly meta: {
@@ -53,10 +53,10 @@ export class ForeignKeyBuilder<
   ) {}
 
   /**
-   * Set relation description
+   * 관계 설명 설정
    *
-   * @param desc - Relation description
-   * @returns New ForeignKeyBuilder instance
+   * @param desc - 관계 설명
+   * @returns 새 ForeignKeyBuilder 인스턴스
    */
   description(desc: string): ForeignKeyBuilder<TOwner, TTargetFn> {
     return new ForeignKeyBuilder({ ...this.meta, description: desc });
@@ -64,13 +64,13 @@ export class ForeignKeyBuilder<
 }
 
 /**
- * Foreign Key reverse-reference builder (1:N)
+ * Foreign Key 역참조 builder (1:N)
  *
- * Define reverse-reference for FK from another Table referencing current Table
- * Loaded as array on include() (single object when single() is called)
+ * 다른 Table이 현재 Table을 참조하는 FK의 역참조를 정의
+ * include() 시 배열로 로드됨 (single() 호출 시 단일 객체)
  *
- * @template TTargetTableFn - Referencing Table builder factory type
- * @template TIsSingle - Whether it is a single object
+ * @template TTargetTableFn - 참조하는 Table builder factory 타입
+ * @template TIsSingle - 단일 객체 여부
  *
  * @example
  * ```typescript
@@ -96,11 +96,11 @@ export class ForeignKeyTargetBuilder<
   TIsSingle extends boolean,
 > {
   /**
-   * @param meta - FK reverse-reference Metadata
-   * @param meta.targetTableFn - Referencing Table factory
-   * @param meta.relationName - FK relation name of the referencing Table
-   * @param meta.description - Relation description
-   * @param meta.isSingle - Whether it is a single object
+   * @param meta - FK 역참조 메타데이터
+   * @param meta.targetTableFn - 참조하는 Table factory
+   * @param meta.relationName - 참조하는 Table의 FK 관계 이름
+   * @param meta.description - 관계 설명
+   * @param meta.isSingle - 단일 객체 여부
    */
   constructor(
     readonly meta: {
@@ -112,21 +112,21 @@ export class ForeignKeyTargetBuilder<
   ) {}
 
   /**
-   * Set relation description
+   * 관계 설명 설정
    *
-   * @param desc - Relation description
-   * @returns New ForeignKeyTargetBuilder instance
+   * @param desc - 관계 설명
+   * @returns 새 ForeignKeyTargetBuilder 인스턴스
    */
   description(desc: string): ForeignKeyTargetBuilder<TTargetTableFn, TIsSingle> {
     return new ForeignKeyTargetBuilder({ ...this.meta, description: desc });
   }
 
   /**
-   * Set as single object relation (1:1)
+   * 단일 객체 관계로 설정 (1:1)
    *
-   * Default is array (1:N), single object when single() is called
+   * 기본값은 배열(1:N), single() 호출 시 단일 객체
    *
-   * @returns New ForeignKeyTargetBuilder instance (isSingle=true)
+   * @returns 새 ForeignKeyTargetBuilder 인스턴스 (isSingle=true)
    *
    * @example
    * ```typescript
@@ -143,13 +143,13 @@ export class ForeignKeyTargetBuilder<
 // ============================================
 
 /**
- * Logical relation builder (N:1) - No DB FK creation
+ * 논리적 관계 builder (N:1) - DB FK 미생성
  *
- * Same as ForeignKeyBuilder but does not create FK constraints in the DB
- * Can also be used in Views
+ * ForeignKeyBuilder와 동일하지만 DB에 FK 제약조건을 생성하지 않음
+ * View에서도 사용 가능
  *
- * @template TOwner - Owner Table/View builder type
- * @template TTargetFn - Target Table/View builder factory type
+ * @template TOwner - 소유 Table/View builder 타입
+ * @template TTargetFn - 대상 Table/View builder factory 타입
  *
  * @example
  * ```typescript
@@ -169,18 +169,18 @@ export class ForeignKeyTargetBuilder<
  *   }));
  * ```
  *
- * @see {@link ForeignKeyBuilder} DB FK creation version
+ * @see {@link ForeignKeyBuilder} DB FK 생성 버전
  */
 export class RelationKeyBuilder<
   TOwner extends TableBuilder<any, any> | ViewBuilder<any, any, any>,
   TTargetFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>,
 > {
   /**
-   * @param meta - Relation Metadata
-   * @param meta.ownerFn - Owner Table/View factory
-   * @param meta.columns - Relation column name array
-   * @param meta.targetFn - Target Table/View factory
-   * @param meta.description - Relation description
+   * @param meta - 관계 메타데이터
+   * @param meta.ownerFn - 소유 Table/View factory
+   * @param meta.columns - 관계 column 이름 배열
+   * @param meta.targetFn - 대상 Table/View factory
+   * @param meta.description - 관계 설명
    */
   constructor(
     readonly meta: {
@@ -192,10 +192,10 @@ export class RelationKeyBuilder<
   ) {}
 
   /**
-   * Set relation description
+   * 관계 설명 설정
    *
-   * @param desc - Relation description
-   * @returns New RelationKeyBuilder instance
+   * @param desc - 관계 설명
+   * @returns 새 RelationKeyBuilder 인스턴스
    */
   description(desc: string): RelationKeyBuilder<TOwner, TTargetFn> {
     return new RelationKeyBuilder({ ...this.meta, description: desc });
@@ -203,13 +203,13 @@ export class RelationKeyBuilder<
 }
 
 /**
- * Logical relation reverse-reference builder (1:N) - No DB FK creation
+ * 논리적 관계 역참조 builder (1:N) - DB FK 미생성
  *
- * Same as ForeignKeyTargetBuilder but does not create FK constraints in the DB
- * Can also be used in Views
+ * ForeignKeyTargetBuilder와 동일하지만 DB에 FK 제약조건을 생성하지 않음
+ * View에서도 사용 가능
  *
- * @template TTargetTableFn - Referencing Table/View builder factory type
- * @template TIsSingle - Whether it is a single object
+ * @template TTargetTableFn - 참조하는 Table/View builder factory 타입
+ * @template TIsSingle - 단일 객체 여부
  *
  * @example
  * ```typescript
@@ -221,18 +221,18 @@ export class RelationKeyBuilder<
  *   }));
  * ```
  *
- * @see {@link ForeignKeyTargetBuilder} DB FK creation version
+ * @see {@link ForeignKeyTargetBuilder} DB FK 생성 버전
  */
 export class RelationKeyTargetBuilder<
   TTargetTableFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>,
   TIsSingle extends boolean,
 > {
   /**
-   * @param meta - Relation reverse-reference Metadata
-   * @param meta.targetTableFn - Referencing Table/View factory
-   * @param meta.relationName - Relation name of the referencing Table/View
-   * @param meta.description - Relation description
-   * @param meta.isSingle - Whether it is a single object
+   * @param meta - 관계 역참조 메타데이터
+   * @param meta.targetTableFn - 참조하는 Table/View factory
+   * @param meta.relationName - 참조하는 Table/View의 관계 이름
+   * @param meta.description - 관계 설명
+   * @param meta.isSingle - 단일 객체 여부
    */
   constructor(
     readonly meta: {
@@ -244,21 +244,21 @@ export class RelationKeyTargetBuilder<
   ) {}
 
   /**
-   * Set relation description
+   * 관계 설명 설정
    *
-   * @param desc - Relation description
-   * @returns New RelationKeyTargetBuilder instance
+   * @param desc - 관계 설명
+   * @returns 새 RelationKeyTargetBuilder 인스턴스
    */
   description(desc: string): RelationKeyTargetBuilder<TTargetTableFn, TIsSingle> {
     return new RelationKeyTargetBuilder({ ...this.meta, description: desc });
   }
 
   /**
-   * Set as single object relation (1:1)
+   * 단일 객체 관계로 설정 (1:1)
    *
-   * Default is array (1:N), single object when single() is called
+   * 기본값은 배열(1:N), single() 호출 시 단일 객체
    *
-   * @returns New RelationKeyTargetBuilder instance (isSingle=true)
+   * @returns 새 RelationKeyTargetBuilder 인스턴스 (isSingle=true)
    */
   single(): RelationKeyTargetBuilder<TTargetTableFn, true> {
     return new RelationKeyTargetBuilder({ ...this.meta, isSingle: true });
@@ -266,18 +266,18 @@ export class RelationKeyTargetBuilder<
 }
 
 /**
- * FK relation factory type (table only)
+ * FK 관계 factory 타입 (table 전용)
  *
- * @template TOwner - Owner Table builder type
- * @template TColumnKey - Column key type
+ * @template TOwner - 소유 Table builder 타입
+ * @template TColumnKey - Column key 타입
  */
 type RelationFkFactory<TOwner extends TableBuilder<any, any>, TColumnKey extends string> = {
-  /** N:1 FK relationship definition (DB FK Create) */
+  /** N:1 FK 관계 정의 (DB FK 생성) */
   foreignKey<TTargetFn extends () => TableBuilder<any, any>>(
     columns: TColumnKey[],
     targetFn: TTargetFn,
   ): ForeignKeyBuilder<TOwner, TTargetFn>;
-  /** 1:N FK reverse-reference definition */
+  /** 1:N FK 역참조 정의 */
   foreignKeyTarget<TTargetTableFn extends () => TableBuilder<any, any>>(
     targetTableFn: TTargetTableFn,
     relationName: string,
@@ -285,21 +285,21 @@ type RelationFkFactory<TOwner extends TableBuilder<any, any>, TColumnKey extends
 };
 
 /**
- * Logical relation factory type (shared for table/View)
+ * 논리적 관계 factory 타입 (table/View 공용)
  *
- * @template TOwner - Owner Table/View builder type
- * @template TColumnKey - Column key type
+ * @template TOwner - 소유 Table/View builder 타입
+ * @template TColumnKey - Column key 타입
  */
 type RelationRkFactory<
   TOwner extends TableBuilder<any, any> | ViewBuilder<any, any, any>,
   TColumnKey extends string,
 > = {
-  /** N:1 logical relation definition (no DB FK creation) */
+  /** N:1 논리적 관계 정의 (DB FK 미생성) */
   relationKey<TTargetFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>>(
     columns: TColumnKey[],
     targetFn: TTargetFn,
   ): RelationKeyBuilder<TOwner, TTargetFn>;
-  /** 1:N logical reverse-reference definition */
+  /** 1:N 논리적 역참조 정의 */
   relationKeyTarget<
     TTargetTableFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>,
   >(
@@ -309,15 +309,15 @@ type RelationRkFactory<
 };
 
 /**
- * Relation builder factory creation
+ * 관계 builder factory 생성
  *
- * Used in TableBuilder.relations() and ViewBuilder.relations()
- * Table can use both FK + RelationKey, View can only use RelationKey
+ * TableBuilder.relations()와 ViewBuilder.relations()에서 사용
+ * Table은 FK + RelationKey 모두 사용 가능, View는 RelationKey만 사용 가능
  *
- * @template TOwner - Owner Table/View builder type
- * @template TColumnKey - Column key type
- * @param ownerFn - Owner Table/View factory function
- * @returns Relation builder factory
+ * @template TOwner - 소유 Table/View builder 타입
+ * @template TColumnKey - Column key 타입
+ * @param ownerFn - 소유 Table/View factory 함수
+ * @returns 관계 builder factory
  *
  * @example
  * ```typescript
@@ -374,13 +374,13 @@ export function createRelationFactory<
 }
 
 // ============================================
-// builder record
+// builder 레코드
 // ============================================
 
 /**
- * relationship builder record type
+ * 관계 builder 레코드 타입
  *
- * Return type of TableBuilder.relations() and ViewBuilder.relations()
+ * TableBuilder.relations()와 ViewBuilder.relations()의 반환 타입
  */
 export type RelationBuilderRecord = Record<
   string,
@@ -391,15 +391,15 @@ export type RelationBuilderRecord = Record<
 >;
 
 // ============================================
-// Infer - relationship Type inference
+// Infer - 관계 타입 추론
 // ============================================
 
 /**
- * Extract target type from FK/RelationKey (single object)
+ * FK/RelationKey에서 대상 타입 추출 (단일 객체)
  *
- * Target type of N:1 relation
+ * N:1 관계의 대상 타입
  *
- * @template T - FK or RelationKey builder type
+ * @template T - FK 또는 RelationKey builder 타입
  */
 export type ExtractRelationTarget<TRelation> = TRelation extends
   | ForeignKeyBuilder<any, infer TTargetFn>
@@ -412,12 +412,12 @@ export type ExtractRelationTarget<TRelation> = TRelation extends
   : never;
 
 /**
- * Extract target type from FKTarget/RelationKeyTarget (array or single object)
+ * FKTarget/RelationKeyTarget에서 대상 타입 추출 (배열 또는 단일 객체)
  *
- * Target type of 1:N relation (single object when single() is called)
- * TTargetTableFn: () => Post form for lazy evaluation to prevent circular references
+ * 1:N 관계의 대상 타입 (single() 호출 시 단일 객체)
+ * TTargetTableFn: 순환 참조 방지를 위한 지연 평가용 () => Post 형태
  *
- * @template T - FKTarget or RelationKeyTarget builder type
+ * @template T - FKTarget 또는 RelationKeyTarget builder 타입
  */
 export type ExtractRelationTargetResult<TRelation> = TRelation extends
   | ForeignKeyTargetBuilder<infer TTargetTableFn, infer TIsSingle>
@@ -434,11 +434,11 @@ export type ExtractRelationTargetResult<TRelation> = TRelation extends
   : never;
 
 /**
- * Deep relation Type inference from relation definitions
+ * 관계 정의에서 심층 관계 타입 추론
  *
- * Makes all relations optional so accessing without include() results in undefined
+ * include() 없이 접근 시 undefined가 되도록 모든 관계를 optional로 설정
  *
- * @template TRelations - Relation builder record type
+ * @template TRelations - 관계 builder 레코드 타입
  *
  * @example
  * ```typescript

package/src/schema/procedure-builder.ts

@@ -5,13 +5,13 @@ import { type ColumnBuilderRecord, createColumnFactory } from "./factory/column-
 // ============================================
 
 /**
- * Stored Procedure definition builder
+ * Stored Procedure 정의 builder
  *
- * Define Procedure parameters, return type, and body via Fluent API
- * Use with DbContext's executable() for type-safe Procedure invocation
+ * Fluent API로 Procedure 파라미터, 반환 타입, 본문을 정의
+ * DbContext의 executable()과 함께 사용하여 타입 안전한 Procedure 호출
  *
- * @template TParams - Parameter Column definition type
- * @template TReturns - Return Column definition type
+ * @template TParams - 파라미터 Column 정의 타입
+ * @template TReturns - 반환 Column 정의 타입
  *
  * @example
  * ```typescript
@@ -37,27 +37,27 @@ import { type ColumnBuilderRecord, createColumnFactory } from "./factory/column-
  * const users = await db.getUserById({ userId: 1n }).execute();
  * ```
  *
- * @see {@link Procedure} factory function
- * @see {@link executable} Executable Generate
+ * @see {@link Procedure} factory 함수
+ * @see {@link executable} Executable 생성
  */
 export class ProcedureBuilder<
   TParams extends ColumnBuilderRecord,
   TReturns extends ColumnBuilderRecord,
 > {
-  /** Parameter definition (type for inference) */
+  /** 파라미터 정의 (타입 추론용) */
   readonly $params!: TParams;
-  /** return type definition (type for inference) */
+  /** 반환 타입 정의 (타입 추론용) */
   readonly $returns!: TReturns;
 
   /**
-   * @param meta - Procedure Metadata
-   * @param meta.name - Procedure name
-   * @param meta.description - Procedure description (comment)
-   * @param meta.database - Database name
-   * @param meta.schema - Schema name (MSSQL/PostgreSQL)
-   * @param meta.params - Parameter definition
-   * @param meta.returns - Return type definition
-   * @param meta.query - Procedure body SQL
+   * @param meta - Procedure 메타데이터
+   * @param meta.name - Procedure 이름
+   * @param meta.description - Procedure 설명 (comment)
+   * @param meta.database - Database 이름
+   * @param meta.schema - Schema 이름 (MSSQL/PostgreSQL)
+   * @param meta.params - 파라미터 정의
+   * @param meta.returns - 반환 타입 정의
+   * @param meta.query - Procedure 본문 SQL
    */
   constructor(
     readonly meta: {
@@ -72,20 +72,20 @@ export class ProcedureBuilder<
   ) {}
 
   /**
-   * Procedure set description
+   * Procedure 설명 설정
    *
-   * @param desc - Procedure description (used as DDL Comment)
-   * @returns new ProcedureBuilder instance
+   * @param desc - Procedure 설명 (DDL Comment로 사용됨)
+   * @returns 새 ProcedureBuilder 인스턴스
    */
   description(desc: string): ProcedureBuilder<TParams, TReturns> {
     return new ProcedureBuilder({ ...this.meta, description: desc });
   }
 
   /**
-   * Database set name
+   * Database 이름 설정
    *
-   * @param db - Database name
-   * @returns new ProcedureBuilder instance
+   * @param db - Database 이름
+   * @returns 새 ProcedureBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -97,26 +97,26 @@ export class ProcedureBuilder<
   }
 
   /**
-   * schema set name
+   * Schema 이름 설정
    *
-   * MSSQL, PostgreSQLused in
+   * MSSQL, PostgreSQL에서 사용
    *
-   * @param schema - Schema name (MSSQL: dbo, PostgreSQL: public)
-   * @returns new ProcedureBuilder instance
+   * @param schema - Schema 이름 (MSSQL: dbo, PostgreSQL: public)
+   * @returns 새 ProcedureBuilder 인스턴스
    */
   schema(schema: string): ProcedureBuilder<TParams, TReturns> {
     return new ProcedureBuilder({ ...this.meta, schema });
   }
 
   /**
-   * Parameter definition
+   * 파라미터 정의
    *
-   * Define Procedure input parameters
-   * Note DBMS-specific parameter syntax differences (MSSQL: @param, MySQL/PostgreSQL: param)
+   * Procedure 입력 파라미터를 정의
+   * DBMS별 파라미터 구문 차이에 주의 (MSSQL: @param, MySQL/PostgreSQL: param)
    *
-   * @template T - New parameter definition type
-   * @param fn - Function that receives a Column factory and returns parameter definitions
-   * @returns new ProcedureBuilder instance
+   * @template T - 새 파라미터 정의 타입
+   * @param fn - Column factory를 받아 파라미터 정의를 반환하는 함수
+   * @returns 새 ProcedureBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -134,13 +134,13 @@ export class ProcedureBuilder<
   }
 
   /**
-   * Return type definition
+   * 반환 타입 정의
    *
-   * Define Procedure return result columns
+   * Procedure 반환 결과 column을 정의
    *
-   * @template T - New return type definition
-   * @param fn - Function that receives a Column factory and returns Column definitions
-   * @returns new ProcedureBuilder instance
+   * @template T - 새 반환 타입 정의
+   * @param fn - Column factory를 받아 column 정의를 반환하는 함수
+   * @returns 새 ProcedureBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -160,15 +160,15 @@ export class ProcedureBuilder<
   }
 
   /**
-   * Set Procedure body SQL
+   * Procedure 본문 SQL 설정
    *
-   * Note DBMS-specific SQL syntax differences:
-   * - MySQL: parameter name as-is (userId)
-   * - MSSQL: @ prefix (@userId)
-   * - PostgreSQL: RETURN QUERY required
+   * DBMS별 SQL 구문 차이에 주의:
+   * - MySQL: 파라미터 이름 그대로 (userId)
+   * - MSSQL: @ 접두사 (@userId)
+   * - PostgreSQL: RETURN QUERY 필요
    *
-   * @param sql - Procedure body SQL
-   * @returns new ProcedureBuilder instance
+   * @param sql - Procedure 본문 SQL
+   * @returns 새 ProcedureBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -189,16 +189,16 @@ export class ProcedureBuilder<
 }
 
 // ============================================
-// Procedure function
+// Procedure 함수
 // ============================================
 
 /**
- * Procedure builder factory function
+ * Procedure builder factory 함수
  *
- * Creates a ProcedureBuilder for defining stored Procedure schema via Fluent API
+ * Fluent API로 stored Procedure schema를 정의하기 위한 ProcedureBuilder를 생성
  *
- * @param name - Procedure name
- * @returns ProcedureBuilder instance
+ * @param name - Procedure 이름
+ * @returns ProcedureBuilder 인스턴스
  *
  * @example
  * ```typescript
@@ -215,7 +215,7 @@ export class ProcedureBuilder<
  *   }))
  *   .body("SELECT id, name, email FROM User WHERE id = userId");
  *
- * // Procedure without parameters
+ * // 파라미터 없는 Procedure
  * const GetAllActiveUsers = Procedure("GetAllActiveUsers")
  *   .database("mydb")
  *   .returns((c) => ({
@@ -225,7 +225,7 @@ export class ProcedureBuilder<
  *   .body("SELECT id, name FROM User WHERE status = 'active'");
  * ```
  *
- * @see {@link ProcedureBuilder} builder class
+ * @see {@link ProcedureBuilder} builder 클래스
  */
 export function Procedure(name: string): ProcedureBuilder<never, never> {
   return new ProcedureBuilder({ name });