@simplysm/orm-common 13.0.100 → 14.0.4

package/src/schema/table-builder.ts

@@ -17,13 +17,13 @@ import {
 // ============================================
 
 /**
- * Database Table definition builder
+ * Database Table 정의 builder
  *
- * Define Table columns, PK, indexes, and relations via Fluent API
- * Use with DbContext's queryable() for type-safe query composition
+ * Fluent API로 Table column, PK, index, 관계를 정의
+ * DbContext의 queryable()과 함께 사용하여 타입 안전한 query 구성
  *
- * @template TColumns - Column definition record type
- * @template TRelations - Relation definition record type
+ * @template TColumns - Column 정의 레코드 타입
+ * @template TRelations - 관계 정의 레코드 타입
  *
  * @example
  * ```typescript
@@ -45,37 +45,37 @@ import {
  * }
  * ```
  *
- * @see {@link Table} factory function
- * @see {@link queryable} Queryable Generate
+ * @see {@link Table} factory 함수
+ * @see {@link queryable} Queryable 생성
  */
 export class TableBuilder<
   TColumns extends ColumnBuilderRecord,
   TRelations extends RelationBuilderRecord,
 > {
-  /** Column definition (type for inference) */
+  /** Column 정의 (타입 추론용) */
   readonly $columns!: TColumns;
-  /** Relation definition (type for inference) */
+  /** 관계 정의 (타입 추론용) */
   readonly $relations!: TRelations;
 
-  /** Full Type inference (column + relation) */
+  /** 전체 타입 추론 (column + 관계) */
   readonly $inferSelect!: InferColumns<TColumns> & InferDeepRelations<TRelations>;
-  /** Column-only Type inference */
+  /** Column 전용 타입 추론 */
   readonly $inferColumns!: InferColumns<TColumns>;
-  /** INSERT Type inference (autoIncrement excluded, nullable/default are optional) */
+  /** INSERT 타입 추론 (autoIncrement 제외, nullable/default는 optional) */
   readonly $inferInsert!: InferInsertColumns<TColumns>;
-  /** UPDATE Type inference (all fields optional) */
+  /** UPDATE 타입 추론 (모든 필드 optional) */
   readonly $inferUpdate!: InferUpdateColumns<TColumns>;
 
   /**
-   * @param meta - Table Metadata
-   * @param meta.name - Table name
-   * @param meta.description - Table description (comment)
-   * @param meta.database - Database name
-   * @param meta.schema - Schema name (MSSQL/PostgreSQL)
-   * @param meta.columns - Column definition
-   * @param meta.primaryKey - PK column array
-   * @param meta.relations - Relation definition
-   * @param meta.indexes - Index definition
+   * @param meta - Table 메타데이터
+   * @param meta.name - Table 이름
+   * @param meta.description - Table 설명 (comment)
+   * @param meta.database - Database 이름
+   * @param meta.schema - Schema 이름 (MSSQL/PostgreSQL)
+   * @param meta.columns - Column 정의
+   * @param meta.primaryKey - PK column 배열
+   * @param meta.relations - 관계 정의
+   * @param meta.indexes - Index 정의
    */
   constructor(
     readonly meta: {
@@ -92,20 +92,20 @@ export class TableBuilder<
   ) {}
 
   /**
-   * Table set description
+   * Table 설명 설정
    *
-   * @param desc - Table description (used as DDL Comment)
-   * @returns new TableBuilder instance
+   * @param desc - Table 설명 (DDL Comment로 사용됨)
+   * @returns 새 TableBuilder 인스턴스
    */
   description(desc: string) {
     return new TableBuilder({ ...this.meta, description: desc });
   }
 
   /**
-   * Database set name
+   * Database 이름 설정
    *
-   * @param db - Database name
-   * @returns new TableBuilder instance
+   * @param db - Database 이름
+   * @returns 새 TableBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -117,12 +117,12 @@ export class TableBuilder<
   }
 
   /**
-   * schema set name
+   * Schema 이름 설정
    *
-   * Used in MSSQL, PostgreSQL
+   * MSSQL, PostgreSQL에서 사용
    *
-   * @param schema - Schema name (MSSQL: dbo, PostgreSQL: public)
-   * @returns new TableBuilder instance
+   * @param schema - Schema 이름 (MSSQL: dbo, PostgreSQL: public)
+   * @returns 새 TableBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -136,13 +136,13 @@ export class TableBuilder<
   }
 
   /**
-   * Column definition
+   * Column 정의
    *
-   * Type-safe Column definition through column factory
+   * Column factory를 통한 타입 안전한 column 정의
    *
-   * @template TNewColumnDefs - New Column definition type
-   * @param fn - Function that receives a Column factory and returns Column definitions
-   * @returns new TableBuilder instance
+   * @template TNewColumnDefs - 새 Column 정의 타입
+   * @param fn - Column factory를 받아 column 정의를 반환하는 함수
+   * @returns 새 TableBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -165,19 +165,19 @@ export class TableBuilder<
   }
 
   /**
-   * Primary Key configuration
+   * Primary Key 설정
    *
-   * @param columns - Column names composing the PK (composite PK supported)
-   * @returns new TableBuilder instance
+   * @param columns - PK를 구성하는 column 이름 (복합 PK 지원)
+   * @returns 새 TableBuilder 인스턴스
    *
    * @example
    * ```typescript
-   * // Single PK
+   * // 단일 PK
    * const User = Table("User")
    *   .columns((c) => ({ id: c.bigint() }))
    *   .primaryKey("id");
    *
-   * // Composite PK
+   * // 복합 PK
    * const UserRole = Table("UserRole")
    *   .columns((c) => ({
    *     userId: c.bigint(),
@@ -194,10 +194,10 @@ export class TableBuilder<
   }
 
   /**
-   * Index definition
+   * Index 정의
    *
-   * @param fn - Function that receives an Index factory and returns an Index array
-   * @returns new TableBuilder instance
+   * @param fn - Index factory를 받아 index 배열을 반환하는 함수
+   * @returns 새 TableBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -225,13 +225,13 @@ export class TableBuilder<
   }
 
   /**
-   * Relation definition
+   * 관계 정의
    *
-   * Set up FK, reverse-references, and other inter-Table relations
+   * FK, 역참조 등 Table 간 관계를 설정
    *
-   * @template T - Relation definition type
-   * @param fn - Function that receives a relation factory and returns relation definitions
-   * @returns new TableBuilder instance
+   * @template T - 관계 정의 타입
+   * @param fn - 관계 factory를 받아 관계 정의를 반환하는 함수
+   * @returns 새 TableBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -273,16 +273,16 @@ export class TableBuilder<
 }
 
 // ============================================
-// Table function
+// Table 함수
 // ============================================
 
 /**
- * Table builder factory function
+ * Table builder factory 함수
  *
- * Creates a TableBuilder for defining Table schema via Fluent API
+ * Fluent API로 Table schema를 정의하기 위한 TableBuilder를 생성
  *
- * @param name - Table name
- * @returns TableBuilder instance
+ * @param name - Table 이름
+ * @returns TableBuilder 인스턴스
  *
  * @example
  * ```typescript
@@ -312,7 +312,7 @@ export class TableBuilder<
  *   }));
  * ```
  *
- * @see {@link TableBuilder} builder class
+ * @see {@link TableBuilder} builder 클래스
  */
 export function Table(name: string) {
   return new TableBuilder({ name });

package/src/schema/view-builder.ts

@@ -12,14 +12,14 @@ import {
 // ============================================
 
 /**
- * Database View definition builder
+ * Database View 정의 builder
  *
- * Define View query and relations via Fluent API
- * Use with DbContext's queryable() for type-safe query composition
+ * Fluent API로 View query와 관계를 정의
+ * DbContext의 queryable()과 함께 사용하여 타입 안전한 query 구성
  *
- * @template TDbContext - DbContext type
- * @template TData - View data record type
- * @template TRelations - Relation definition record type
+ * @template TDbContext - DbContext 타입
+ * @template TData - View 데이터 레코드 타입
+ * @template TRelations - 관계 정의 레코드 타입
  *
  * @example
  * ```typescript
@@ -44,27 +44,27 @@ import {
  * }
  * ```
  *
- * @see {@link View} factory function
- * @see {@link queryable} Queryable Generate
+ * @see {@link View} factory 함수
+ * @see {@link queryable} Queryable 생성
  */
 export class ViewBuilder<
   TDbContext extends DbContextBase,
   TData extends DataRecord,
   TRelations extends RelationBuilderRecord,
 > {
-  /** Relation definition (type for inference) */
+  /** 관계 정의 (타입 추론용) */
   readonly $relations!: TRelations;
-  /** Full Type inference */
+  /** 전체 타입 추론 */
   readonly $inferSelect!: TData;
 
   /**
-   * @param meta - View Metadata
-   * @param meta.name - View name
-   * @param meta.description - View description (comment)
-   * @param meta.database - Database name
-   * @param meta.schema - Schema name (MSSQL/PostgreSQL)
-   * @param meta.viewFn - View Query definition function
-   * @param meta.relations - Relation definition
+   * @param meta - View 메타데이터
+   * @param meta.name - View 이름
+   * @param meta.description - View 설명 (comment)
+   * @param meta.database - Database 이름
+   * @param meta.schema - Schema 이름 (MSSQL/PostgreSQL)
+   * @param meta.viewFn - View query 정의 함수
+   * @param meta.relations - 관계 정의
    */
   constructor(
     readonly meta: {
@@ -78,20 +78,20 @@ export class ViewBuilder<
   ) {}
 
   /**
-   * View set description
+   * View 설명 설정
    *
-   * @param desc - View description (used as DDL Comment)
-   * @returns new ViewBuilder instance
+   * @param desc - View 설명 (DDL Comment로 사용됨)
+   * @returns 새 ViewBuilder 인스턴스
    */
   description(desc: string): ViewBuilder<TDbContext, TData, TRelations> {
     return new ViewBuilder({ ...this.meta, description: desc });
   }
 
   /**
-   * Database set name
+   * Database 이름 설정
    *
-   * @param db - Database name
-   * @returns new ViewBuilder instance
+   * @param db - Database 이름
+   * @returns 새 ViewBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -103,26 +103,26 @@ export class ViewBuilder<
   }
 
   /**
-   * schema set name
+   * Schema 이름 설정
    *
-   * Used in MSSQL, PostgreSQL
+   * MSSQL, PostgreSQL에서 사용
    *
-   * @param schema - Schema name (MSSQL: dbo, PostgreSQL: public)
-   * @returns new ViewBuilder instance
+   * @param schema - Schema 이름 (MSSQL: dbo, PostgreSQL: public)
+   * @returns 새 ViewBuilder 인스턴스
    */
   schema(schema: string): ViewBuilder<TDbContext, TData, TRelations> {
     return new ViewBuilder({ ...this.meta, schema });
   }
 
   /**
-   * View Query definition
+   * View query 정의
    *
-   * Define the View's data source through a SELECT query
+   * SELECT query를 통해 View의 데이터 소스를 정의
    *
-   * @template TViewData - View data type
-   * @template TDb - DbContext type
-   * @param viewFn - Function that receives a DbContext and returns a Queryable
-   * @returns new ViewBuilder instance
+   * @template TViewData - View 데이터 타입
+   * @template TDb - DbContext 타입
+   * @param viewFn - DbContext를 받아 Queryable을 반환하는 함수
+   * @returns 새 ViewBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -146,13 +146,13 @@ export class ViewBuilder<
   }
 
   /**
-   * Relation definition
+   * 관계 정의
    *
-   * Set up relations with other Tables/Views
+   * 다른 Table/View와의 관계를 설정
    *
-   * @template T - Relation definition type
-   * @param fn - Function that receives a relation factory and returns relation definitions
-   * @returns new ViewBuilder instance
+   * @template T - 관계 정의 타입
+   * @param fn - 관계 factory를 받아 관계 정의를 반환하는 함수
+   * @returns 새 ViewBuilder 인스턴스
    *
    * @example
    * ```typescript
@@ -169,8 +169,8 @@ export class ViewBuilder<
   relations<T extends RelationBuilderRecord>(
     fn: (r: ReturnType<typeof createRelationFactory<this, keyof TData & string>>) => T,
   ): ViewBuilder<TDbContext, TData & InferDeepRelations<T>, TRelations> {
-    // Casting is unavoidable due to TypeScript generic type inference limitations
-    // Resolves type mismatch between TRelations type parameter and newly created relation type T
+    // TypeScript 제네릭 타입 추론 한계로 인해 캐스팅이 불가피
+    // TRelations 타입 파라미터와 새로 생성된 관계 타입 T 간의 타입 불일치 해결
     return new ViewBuilder({
       ...this.meta,
       relations: fn(createRelationFactory<this, keyof TData & string>(() => this)),
@@ -179,16 +179,16 @@ export class ViewBuilder<
 }
 
 // ============================================
-// View function
+// View 함수
 // ============================================
 
 /**
- * View builder factory function
+ * View builder factory 함수
  *
- * Creates a ViewBuilder for defining View schema via Fluent API
+ * Fluent API로 View schema를 정의하기 위한 ViewBuilder를 생성
  *
- * @param name - View name
- * @returns ViewBuilder instance
+ * @param name - View 이름
+ * @returns ViewBuilder 인스턴스
  *
  * @example
  * ```typescript
@@ -201,7 +201,7 @@ export class ViewBuilder<
  *       .select(u => ({ id: u.id, name: u.name }))
  *   );
  *
- * // aggregation View
+ * // 집계 View
  * const UserStats = View("UserStats")
  *   .database("mydb")
  *   .query((db: MyDb) =>
@@ -214,7 +214,7 @@ export class ViewBuilder<
  *   );
  * ```
  *
- * @see {@link ViewBuilder} builder class
+ * @see {@link ViewBuilder} builder 클래스
  */
 export function View(name: string) {
   return new ViewBuilder({ name });

package/src/types/column.ts

@@ -1,13 +1,13 @@
 import { DateOnly, DateTime, Time, Uuid, type Bytes } from "@simplysm/core-common";
 
 // ============================================
-// DataType (SQL type definition)
+// DataType (SQL 타입 정의)
 // ============================================
 
 /**
- * SQL data type definition
+ * SQL 데이터 타입 정의
  *
- * DBMS Mapping:
+ * DBMS 매핑:
  * - `int`: INT (4 bytes)
  * - `bigint`: BIGINT (8 bytes)
  * - `float`: FLOAT/REAL (4 bytes)
@@ -47,13 +47,13 @@ export type DataType =
   | { type: "uuid" };
 
 // ============================================
-// ColumnPrimitive (TypeScript Type)
+// ColumnPrimitive (TypeScript 타입)
 // ============================================
 
 /**
- * Column primitive type mapping
+ * Column 원시 타입 매핑
  *
- * TypeScript type name (string) → Actual TypeScript type mapping
+ * TypeScript 타입 이름 (문자열) → 실제 TypeScript 타입 매핑
  *
  * @example
  * ```typescript
@@ -73,7 +73,7 @@ export type ColumnPrimitiveMap = {
 };
 
 /**
- * Column primitive type name (string)
+ * Column 원시 타입 이름 (문자열)
  *
  * @example
  * ```typescript
@@ -84,9 +84,9 @@ export type ColumnPrimitiveMap = {
 export type ColumnPrimitiveStr = keyof ColumnPrimitiveMap;
 
 /**
- * All primitive types that can be stored in columns
+ * Column에 저장 가능한 모든 원시 타입
  *
- * undefined represents NULL
+ * undefined는 NULL을 나타냄
  */
 export type ColumnPrimitive = ColumnPrimitiveMap[ColumnPrimitiveStr] | undefined;
 
@@ -95,7 +95,7 @@ export type ColumnPrimitive = ColumnPrimitiveMap[ColumnPrimitiveStr] | undefined
 // ============================================
 
 /**
- * SQL DataType → TypeScript type name mapping
+ * SQL DataType → TypeScript 타입 이름 매핑
  *
  * @example
  * ```typescript
@@ -121,7 +121,7 @@ export const dataTypeStrToColumnPrimitiveStr = {
 };
 
 /**
- * TypeScript Type inference from DataType
+ * DataType으로부터 TypeScript 타입 추론
  *
  * @template T - DataType
  *
@@ -135,11 +135,11 @@ export type InferColumnPrimitiveFromDataType<TDataType extends DataType> =
   ColumnPrimitiveMap[(typeof dataTypeStrToColumnPrimitiveStr)[TDataType["type"]]];
 
 /**
- * Infer ColumnPrimitiveStr from runtime value
+ * 런타임 값에서 ColumnPrimitiveStr 추론
  *
- * @param value - Column value
- * @returns ColumnPrimitiveStr type name
- * @throws Error if value type is unknown
+ * @param value - Column 값
+ * @returns ColumnPrimitiveStr 타입 이름
+ * @throws 값 타입이 알 수 없을 때 Error
  *
  * @example
  * ```typescript
@@ -157,7 +157,7 @@ export function inferColumnPrimitiveStr(value: ColumnPrimitive): ColumnPrimitive
   if (value instanceof Time) return "Time";
   if (value instanceof Uuid) return "Uuid";
   if (value instanceof Uint8Array) return "Bytes";
-  throw new Error(`Unknown value type: ${typeof value}`);
+  throw new Error(`알 수 없는 값 타입: ${typeof value}`);
 }
 
 // ============================================
@@ -165,16 +165,16 @@ export function inferColumnPrimitiveStr(value: ColumnPrimitive): ColumnPrimitive
 // ============================================
 
 /**
- * Column metadata
+ * Column 메타데이터
  *
- * Generated by ColumnBuilder and passed to TableBuilder
+ * ColumnBuilder에서 생성되어 TableBuilder에 전달됨
  *
- * @property type - TypeScript type name (ColumnPrimitiveStr)
- * @property dataType - SQL data type
- * @property autoIncrement - Whether to auto-increment
- * @property nullable - Whether to allow NULL
- * @property default - Default value
- * @property description - Column description (DDL comment)
+ * @property type - TypeScript 타입 이름 (ColumnPrimitiveStr)
+ * @property dataType - SQL 데이터 타입
+ * @property autoIncrement - 자동 증가 여부
+ * @property nullable - NULL 허용 여부
+ * @property default - 기본값
+ * @property description - Column 설명 (DDL 코멘트)
  *
  * @see {@link ColumnBuilder} Column builder
  */

package/src/types/db-context-def.ts

@@ -8,11 +8,11 @@ import type { DataRecord, IsolationLevel, Migration, ResultMeta } from "./db";
 import type { QueryDef, QueryDefObjectName } from "./query-def";
 
 /**
- * DbContext core interface
+ * DbContext 핵심 인터페이스
  *
- * Internal interface used by Queryable, Executable, and ViewBuilder.
- * Both the old DbContext class and new createDbContext return objects
- * that satisfy this interface.
+ * Queryable, Executable, ViewBuilder에서 사용하는 내부 인터페이스.
+ * 기존 DbContext 클래스와 새로운 createDbContext 반환 객체 모두
+ * 이 인터페이스를 만족함.
  */
 export interface DbContextBase {
   status: DbContextStatus;
@@ -33,9 +33,9 @@ export interface DbContextBase {
 export type DbContextStatus = "ready" | "connect" | "transact";
 
 /**
- * DbContext definition (blueprint)
+ * DbContext 정의 (blueprint)
  *
- * Created by defineDbContext(). Contains schema metadata but no runtime state.
+ * defineDbContext()로 생성됨. Schema 메타데이터만 포함하며 런타임 상태는 없음.
  */
 export interface DbContextDef<
   TTables extends Record<string, TableBuilder<any, any>>,
@@ -51,35 +51,35 @@ export interface DbContextDef<
 }
 
 /**
- * Full DbContext instance type (created by createDbContext)
+ * 전체 DbContext 인스턴스 타입 (createDbContext로 생성)
  *
- * Extends DbContextBase with queryable accessors, DDL methods,
- * and connection/transaction management.
+ * DbContextBase를 queryable 접근자, DDL 메서드,
+ * 연결/트랜잭션 관리로 확장.
  */
 export type DbContextInstance<TDef extends DbContextDef<any, any, any>> = DbContextBase &
   DbContextConnectionMethods &
   DbContextDdlMethods & {
-    // Auto-mapped table queryable accessors
+    // 자동 매핑된 table queryable 접근자
     [K in keyof TDef["meta"]["tables"]]: () => import("../exec/queryable").Queryable<
       TDef["meta"]["tables"][K]["$inferSelect"],
       TDef["meta"]["tables"][K]
     >;
   } & {
-    // Auto-mapped view queryable accessors
+    // 자동 매핑된 view queryable 접근자
     [K in keyof TDef["meta"]["views"]]: () => import("../exec/queryable").Queryable<
       TDef["meta"]["views"][K]["$inferSelect"],
       never
     >;
   } & {
-    // Auto-mapped procedure executable accessors
+    // 자동 매핑된 procedure executable 접근자
     [K in keyof TDef["meta"]["procedures"]]: () => import("../exec/executable").Executable<
       TDef["meta"]["procedures"][K]["$params"],
       TDef["meta"]["procedures"][K]["$returns"]
     >;
   } & {
-    // System table
+    // 시스템 table
     _migration: () => import("../exec/queryable").Queryable<{ code: string }, any>;
-    // Initialization
+    // 초기화
     initialize(options?: { dbs?: string[]; force?: boolean }): Promise<void>;
   };
 
@@ -123,7 +123,7 @@ export interface DbContextDdlMethods {
   schemaExists(database: string, schema?: string): Promise<boolean>;
   truncate(table: QueryDefObjectName): Promise<void>;
   switchFk(table: QueryDefObjectName, enabled: boolean): Promise<void>;
-  // QueryDef generators
+  // QueryDef 생성기
   getCreateTableQueryDef(table: TableBuilder<any, any>): QueryDef;
   getCreateViewQueryDef(view: ViewBuilder<any, any, any>): QueryDef;
   getCreateProcQueryDef(procedure: ProcedureBuilder<any, any>): QueryDef;