@simplysm/orm-common 13.0.99 → 14.0.1

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

@@ -8,22 +8,22 @@ import type { DataRecord } from "../../types/db";
 // ============================================
 
 /**
- * Column definition builder
+ * Column 정의 builder
  *
- * Define column type, nullable, autoIncrement, default, and description via Fluent API
- * Used in TableBuilder.columns()
+ * Fluent API로 column 타입, nullable, autoIncrement, default, description을 정의
+ * TableBuilder.columns()에서 사용
  *
- * @template TValue - Column value type
- * @template TMeta - Column Metadata type
+ * @template TValue - Column 값 타입
+ * @template TMeta - Column 메타데이터 타입
  *
  * @example
  * ```typescript
  * Table("User")
  *   .columns((c) => ({
- *     id: c.bigint().autoIncrement(),           // bigint, auto increment
- *     name: c.varchar(100),                     // varchar(100), required
+ *     id: c.bigint().autoIncrement(),           // bigint, 자동 증가
+ *     name: c.varchar(100),                     // varchar(100), 필수
  *     email: c.varchar(200).nullable(),         // varchar(200), nullable
- *     status: c.varchar(20).default("active"),  // varchar(20), default value
+ *     status: c.varchar(20).default("active"),  // varchar(20), 기본값
  *     createdAt: c.datetime().description("created datetime"),
  *   }));
  * ```
@@ -33,16 +33,16 @@ import type { DataRecord } from "../../types/db";
  */
 export class ColumnBuilder<TValue extends ColumnPrimitive, TMeta extends ColumnMeta> {
   /**
-   * @param meta - Column Metadata
+   * @param meta - Column 메타데이터
    */
   constructor(readonly meta: TMeta) {}
 
   /**
-   * Auto Increment configuration
+   * Auto Increment 설정
    *
-   * Auto increments on INSERT. Treated as optional in INSERT Type inference
+   * INSERT 시 자동 증가. INSERT 타입 추론에서 선택적(optional)으로 처리됨
    *
-   * @returns new ColumnBuilder instance
+   * @returns 새 ColumnBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -54,11 +54,11 @@ export class ColumnBuilder<TValue extends ColumnPrimitive, TMeta extends ColumnM
   }
 
   /**
-   * Nullable configuration
+   * Nullable 설정
    *
-   * Allow NULL. Adds undefined to the value type
+   * NULL 허용. 값 타입에 undefined가 추가됨
    *
-   * @returns new ColumnBuilder instance
+   * @returns 새 ColumnBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -70,12 +70,12 @@ export class ColumnBuilder<TValue extends ColumnPrimitive, TMeta extends ColumnM
   }
 
   /**
-   * Default value configuration
+   * 기본값 설정
    *
-   * Used when no value is specified on INSERT. Treated as optional in INSERT Type inference
+   * INSERT 시 값이 지정되지 않으면 사용됨. INSERT 타입 추론에서 선택적(optional)으로 처리됨
    *
-   * @param value - Default value
-   * @returns new ColumnBuilder instance
+   * @param value - 기본값
+   * @returns 새 ColumnBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -90,10 +90,10 @@ export class ColumnBuilder<TValue extends ColumnPrimitive, TMeta extends ColumnM
   }
 
   /**
-   * column set description
+   * Column 설명 설정
    *
-   * @param desc - Column description (used as DDL Comment)
-   * @returns new ColumnBuilder instance
+   * @param desc - Column 설명 (DDL Comment로 사용됨)
+   * @returns 새 ColumnBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -110,85 +110,85 @@ export class ColumnBuilder<TValue extends ColumnPrimitive, TMeta extends ColumnM
 // ============================================
 
 /**
- * Column builder factory creation
+ * Column builder factory 생성
  *
- * Column type factory used in TableBuilder.columns()
- * Provides builder creation methods for all basic data types
+ * TableBuilder.columns()에서 사용하는 column 타입 factory
+ * 모든 기본 데이터 타입에 대한 builder 생성 메서드를 제공
  *
- * @returns Object containing builder creation methods for each Column type
+ * @returns 각 Column 타입별 builder 생성 메서드를 포함하는 객체
  *
  * @example
  * ```typescript
  * Table("User")
  *   .columns((c) => ({
- *     // Number type
+ *     // 숫자 타입
  *     id: c.bigint().autoIncrement(),
  *     count: c.int(),
  *     price: c.decimal(10, 2),
  *
- *     // String type
+ *     // 문자열 타입
  *     name: c.varchar(100),
  *     code: c.char(10),
  *     content: c.text(),
  *
- *     // Date/time type
+ *     // 날짜/시간 타입
  *     createdAt: c.datetime(),
  *     birthDate: c.date(),
  *     startTime: c.time(),
  *
- *     // Other type
+ *     // 기타 타입
  *     isActive: c.boolean(),
  *     data: c.binary(),
  *     uuid: c.uuid(),
  *   }));
  * ```
  *
- * @see {@link ColumnBuilder} Column builder class
+ * @see {@link ColumnBuilder} Column builder 클래스
  */
 export function createColumnFactory() {
   return {
     /**
-     * INT column (4 bytes, -2^31 ~ 2^31-1)
+     * INT column (4바이트, -2^31 ~ 2^31-1)
      *
-     * @returns ColumnBuilder instance
+     * @returns ColumnBuilder 인스턴스
      */
     int(): ColumnBuilder<number, { type: "number"; dataType: { type: "int" } }> {
       return new ColumnBuilder({ type: "number", dataType: { type: "int" } });
     },
 
     /**
-     * BIGINT column (8 bytes, -2^63 ~ 2^63-1)
+     * BIGINT column (8바이트, -2^63 ~ 2^63-1)
      *
-     * @returns ColumnBuilder instance
+     * @returns ColumnBuilder 인스턴스
      */
     bigint(): ColumnBuilder<number, { type: "number"; dataType: { type: "bigint" } }> {
       return new ColumnBuilder({ type: "number", dataType: { type: "bigint" } });
     },
 
     /**
-     * FLOAT column (4 bytes, single-precision floating point)
+     * FLOAT column (4바이트, 단정밀도 부동소수점)
      *
-     * @returns ColumnBuilder instance
+     * @returns ColumnBuilder 인스턴스
      */
     float(): ColumnBuilder<number, { type: "number"; dataType: { type: "float" } }> {
       return new ColumnBuilder({ type: "number", dataType: { type: "float" } });
     },
 
     /**
-     * DOUBLE column (8 bytes, double-precision floating point)
+     * DOUBLE column (8바이트, 배정밀도 부동소수점)
      *
-     * @returns ColumnBuilder instance
+     * @returns ColumnBuilder 인스턴스
      */
     double(): ColumnBuilder<number, { type: "number"; dataType: { type: "double" } }> {
       return new ColumnBuilder({ type: "number", dataType: { type: "double" } });
     },
 
     /**
-     * DECIMAL column (fixed-point)
+     * DECIMAL column (고정 소수점)
      *
-     * @param precision - Total number of digits
-     * @param scale - Number of digits after the decimal point (optional)
-     * @returns ColumnBuilder instance
+     * @param precision - 전체 자릿수
+     * @param scale - 소수점 이하 자릿수 (선택)
+     * @returns ColumnBuilder 인스턴스
      *
      * @example
      * ```typescript
@@ -206,10 +206,10 @@ export function createColumnFactory() {
     },
 
     /**
-     * VARCHAR column (variable-length string)
+     * VARCHAR column (가변 길이 문자열)
      *
-     * @param length - Maximum length
-     * @returns ColumnBuilder instance
+     * @param length - 최대 길이
+     * @returns ColumnBuilder 인스턴스
      *
      * @example
      * ```typescript
@@ -223,10 +223,10 @@ export function createColumnFactory() {
     },
 
     /**
-     * CHAR column (fixed-length string)
+     * CHAR column (고정 길이 문자열)
      *
-     * @param length - Fixed length
-     * @returns ColumnBuilder instance
+     * @param length - 고정 길이
+     * @returns ColumnBuilder 인스턴스
      *
      * @example
      * ```typescript
@@ -240,20 +240,20 @@ export function createColumnFactory() {
     },
 
     /**
-     * TEXT column (large text)
+     * TEXT column (대용량 텍스트)
      *
-     * @returns ColumnBuilder instance
+     * @returns ColumnBuilder 인스턴스
      */
     text(): ColumnBuilder<string, { type: "string"; dataType: { type: "text" } }> {
       return new ColumnBuilder({ type: "string", dataType: { type: "text" } });
     },
 
     /**
-     * BINARY column (binary data)
+     * BINARY column (바이너리 데이터)
      *
-     * Per DBMS: MySQL=LONGBLOB, MSSQL=VARBINARY(MAX), PostgreSQL=BYTEA
+     * DBMS별: MySQL=LONGBLOB, MSSQL=VARBINARY(MAX), PostgreSQL=BYTEA
      *
-     * @returns ColumnBuilder instance
+     * @returns ColumnBuilder 인스턴스
      */
     binary(): ColumnBuilder<Bytes, { type: "Bytes"; dataType: { type: "binary" } }> {
       return new ColumnBuilder({ type: "Bytes", dataType: { type: "binary" } });
@@ -262,36 +262,36 @@ export function createColumnFactory() {
     /**
      * BOOLEAN column
      *
-     * Per DBMS: MySQL=TINYINT(1), MSSQL=BIT, PostgreSQL=BOOLEAN
+     * DBMS별: MySQL=TINYINT(1), MSSQL=BIT, PostgreSQL=BOOLEAN
      *
-     * @returns ColumnBuilder instance
+     * @returns ColumnBuilder 인스턴스
      */
     boolean(): ColumnBuilder<boolean, { type: "boolean"; dataType: { type: "boolean" } }> {
       return new ColumnBuilder({ type: "boolean", dataType: { type: "boolean" } });
     },
 
     /**
-     * DATETIME column (date + time)
+     * DATETIME column (날짜 + 시간)
      *
-     * @returns ColumnBuilder instance
+     * @returns ColumnBuilder 인스턴스
      */
     datetime(): ColumnBuilder<DateTime, { type: "DateTime"; dataType: { type: "datetime" } }> {
       return new ColumnBuilder({ type: "DateTime", dataType: { type: "datetime" } });
     },
 
     /**
-     * DATE column (date only)
+     * DATE column (날짜만)
      *
-     * @returns ColumnBuilder instance
+     * @returns ColumnBuilder 인스턴스
      */
     date(): ColumnBuilder<DateOnly, { type: "DateOnly"; dataType: { type: "date" } }> {
       return new ColumnBuilder({ type: "DateOnly", dataType: { type: "date" } });
     },
 
     /**
-     * TIME column (time only)
+     * TIME column (시간만)
      *
-     * @returns ColumnBuilder instance
+     * @returns ColumnBuilder 인스턴스
      */
     time(): ColumnBuilder<Time, { type: "Time"; dataType: { type: "time" } }> {
       return new ColumnBuilder({ type: "Time", dataType: { type: "time" } });
@@ -300,9 +300,9 @@ export function createColumnFactory() {
     /**
      * UUID column
      *
-     * Per DBMS: MySQL=BINARY(16), MSSQL=UNIQUEIDENTIFIER, PostgreSQL=UUID
+     * DBMS별: MySQL=BINARY(16), MSSQL=UNIQUEIDENTIFIER, PostgreSQL=UUID
      *
-     * @returns ColumnBuilder instance
+     * @returns ColumnBuilder 인스턴스
      */
     uuid(): ColumnBuilder<Uuid, { type: "Uuid"; dataType: { type: "uuid" } }> {
       return new ColumnBuilder({ type: "Uuid", dataType: { type: "uuid" } });
@@ -311,24 +311,24 @@ export function createColumnFactory() {
 }
 
 // ============================================
-// ColumnDefRecord - Column builder record
+// ColumnDefRecord - Column builder 레코드
 // ============================================
 
 /**
- * Column builder record type
+ * Column builder 레코드 타입
  *
- * Used as the return type of TableBuilder.columns()
+ * TableBuilder.columns()의 반환 타입으로 사용됨
  */
 export type ColumnBuilderRecord = Record<string, ColumnBuilder<ColumnPrimitive, ColumnMeta>>;
 
 // ============================================
-// Infer - Type inference utilities
+// Infer - 타입 추론 유틸리티
 // ============================================
 
 /**
- * Infer actual value types from a Column builder record
+ * Column builder 레코드에서 실제 값 타입을 추론
  *
- * @template T - Column builder record type
+ * @template T - Column builder 레코드 타입
  *
  * @example
  * ```typescript
@@ -341,20 +341,20 @@ export type InferColumns<TBuilders extends ColumnBuilderRecord> = {
 };
 
 /**
- * Infer expression input types from a Column builder record
+ * Column builder 레코드에서 expression 입력 타입을 추론
  *
- * @template T - Column builder record type
+ * @template T - Column builder 레코드 타입
  */
 export type InferColumnExprs<TBuilders extends ColumnBuilderRecord> = {
   [K in keyof TBuilders]: TBuilders[K] extends ColumnBuilder<infer V, any> ? ExprInput<V> : never;
 };
 
 /**
- * Extract required column keys for INSERT
+ * INSERT용 필수 column key 추출
  *
- * Only columns without autoIncrement, nullable, or default are required
+ * autoIncrement, nullable, default가 없는 column만 필수
  *
- * @template T - Column builder record type
+ * @template T - Column builder 레코드 타입
  */
 export type RequiredInsertKeys<TBuilders extends ColumnBuilderRecord> = {
   [K in keyof TBuilders]: TBuilders[K]["meta"] extends infer M extends ColumnMeta
@@ -369,11 +369,11 @@ export type RequiredInsertKeys<TBuilders extends ColumnBuilderRecord> = {
 }[keyof TBuilders];
 
 /**
- * Extract optional column keys for INSERT
+ * INSERT용 선택적 column key 추출
  *
- * Columns with autoIncrement, nullable, or default are optional
+ * autoIncrement, nullable, default가 있는 column은 선택적(optional)
  *
- * @template T - Column builder record type
+ * @template T - Column builder 레코드 타입
  */
 export type OptionalInsertKeys<TBuilders extends ColumnBuilderRecord> = Exclude<
   keyof TBuilders,
@@ -381,11 +381,11 @@ export type OptionalInsertKeys<TBuilders extends ColumnBuilderRecord> = Exclude<
 >;
 
 /**
- * INSERT Type inference
+ * INSERT 타입 추론
  *
- * Required columns are required, optional columns are Partial
+ * 필수 column은 필수, 선택적 column은 Partial
  *
- * @template T - Column builder record type
+ * @template T - Column builder 레코드 타입
  *
  * @example
  * ```typescript
@@ -400,20 +400,20 @@ export type InferInsertColumns<TBuilders extends ColumnBuilderRecord> = Pick<
   Partial<Pick<InferColumns<TBuilders>, OptionalInsertKeys<TBuilders>>>;
 
 /**
- * UPDATE Type inference
+ * UPDATE 타입 추론
  *
- * All columns are optional
+ * 모든 column이 선택적(optional)
  *
- * @template T - Column builder record type
+ * @template T - Column builder 레코드 타입
  */
 export type InferUpdateColumns<TBuilders extends ColumnBuilderRecord> = Partial<
   InferColumns<TBuilders>
 >;
 
 /**
- * Transform from data record to Column builder record
+ * 데이터 레코드에서 Column builder 레코드로 변환
  *
- * @template TData - data record type
+ * @template TData - 데이터 레코드 타입
  */
 export type DataToColumnBuilderRecord<TData extends DataRecord> = {
   [K in keyof TData as TData[K] extends ColumnPrimitive ? K : never]: ColumnBuilder<

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

@@ -3,12 +3,12 @@
 // ============================================
 
 /**
- * Index definition builder
+ * Index 정의 builder
  *
- * Define Index columns, uniqueness, and sort order via Fluent API
- * Used in TableBuilder.indexes()
+ * Fluent API로 index column, 유니크 여부, 정렬 순서를 정의
+ * TableBuilder.indexes()에서 사용
  *
- * @template TKeys - Index column key array type
+ * @template TKeys - Index column key 배열 타입
  *
  * @example
  * ```typescript
@@ -20,13 +20,13 @@
  *     createdAt: c.datetime(),
  *   }))
  *   .indexes((i) => [
- *     // Unique index
+ *     // 유니크 index
  *     i.index("email").unique(),
  *
- *     // Composite index + sort order
+ *     // 복합 index + 정렬 순서
  *     i.index("name", "createdAt").orderBy("ASC", "DESC"),
  *
- *     // Custom name
+ *     // 커스텀 이름
  *     i.index("createdAt").name("IX_User_CreatedAt"),
  *   ]);
  * ```
@@ -36,12 +36,12 @@
  */
 export class IndexBuilder<TKeys extends string[]> {
   /**
-   * @param meta - Index Metadata
-   * @param meta.columns - Index column array
-   * @param meta.name - Index name (optional)
-   * @param meta.unique - Whether it is a unique index
-   * @param meta.orderBy - Sort order per column
-   * @param meta.description - Index description
+   * @param meta - Index 메타데이터
+   * @param meta.columns - Index column 배열
+   * @param meta.name - Index 이름 (선택)
+   * @param meta.unique - 유니크 index 여부
+   * @param meta.orderBy - column별 정렬 순서
+   * @param meta.description - Index 설명
    */
   constructor(
     readonly meta: {
@@ -54,10 +54,10 @@ export class IndexBuilder<TKeys extends string[]> {
   ) {}
 
   /**
-   * Index set name
+   * Index 이름 설정
    *
-   * @param name - Index name
-   * @returns new IndexBuilder instance
+   * @param name - Index 이름
+   * @returns 새 IndexBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -69,9 +69,9 @@ export class IndexBuilder<TKeys extends string[]> {
   }
 
   /**
-   * Unique index configuration
+   * 유니크 index 설정
    *
-   * @returns new IndexBuilder instance
+   * @returns 새 IndexBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -83,19 +83,19 @@ export class IndexBuilder<TKeys extends string[]> {
   }
 
   /**
-   * Sort order configuration
+   * 정렬 순서 설정
    *
-   * Specify ASC or DESC for each column
+   * 각 column에 ASC 또는 DESC를 지정
    *
-   * @param orderBy - Sort order per column (must match the number of columns)
-   * @returns new IndexBuilder instance
+   * @param orderBy - column별 정렬 순서 (column 수와 일치해야 함)
+   * @returns 새 IndexBuilder 인스턴스
    *
    * @example
    * ```typescript
-   * // Single column
+   * // 단일 column
    * i.index("createdAt").orderBy("DESC")
    *
-   * // Composite column
+   * // 복합 column
    * i.index("status", "createdAt").orderBy("ASC", "DESC")
    * ```
    */
@@ -104,10 +104,10 @@ export class IndexBuilder<TKeys extends string[]> {
   }
 
   /**
-   * Index set description
+   * Index 설명 설정
    *
-   * @param description - Index description (used as DDL Comment)
-   * @returns new IndexBuilder instance
+   * @param description - Index 설명 (DDL Comment로 사용됨)
+   * @returns 새 IndexBuilder 인스턴스
    */
   description(description: string): IndexBuilder<TKeys> {
     return new IndexBuilder({ ...this.meta, description });
@@ -119,12 +119,12 @@ export class IndexBuilder<TKeys extends string[]> {
 // ============================================
 
 /**
- * Index builder factory creation
+ * Index builder factory 생성
  *
- * Index factory used in TableBuilder.indexes()
+ * TableBuilder.indexes()에서 사용하는 index factory
  *
- * @template TColumnKey - Table column key type
- * @returns Object containing Index creation methods
+ * @template TColumnKey - Table column key 타입
+ * @returns Index 생성 메서드를 포함하는 객체
  *
  * @example
  * ```typescript
@@ -140,21 +140,21 @@ export class IndexBuilder<TKeys extends string[]> {
  *   ]);
  * ```
  *
- * @see {@link IndexBuilder} Index builder class
+ * @see {@link IndexBuilder} Index builder 클래스
  */
 export function createIndexFactory<TColumnKey extends string>() {
   return {
     /**
-     * Index Generate
+     * Index 생성
      *
-     * @template TKeys - Index column key array type
-     * @param columns - Index column names
-     * @returns IndexBuilder instance
+     * @template TKeys - Index column key 배열 타입
+     * @param columns - Index column 이름들
+     * @returns IndexBuilder 인스턴스
      *
      * @example
      * ```typescript
-     * i.index("email")          // Single column
-     * i.index("name", "email")  // Composite column
+     * i.index("email")          // 단일 column
+     * i.index("name", "email")  // 복합 column
      * ```
      */
     index<TKeys extends TColumnKey[]>(...columns: [...TKeys]): IndexBuilder<TKeys> {