@simplysm/orm-common 14.0.1 → 14.0.5

package/src/query-builder/postgresql/postgresql-query-builder.ts

@@ -38,25 +38,25 @@ import { PostgresqlExprRenderer } from "./postgresql-expr-renderer";
 /**
  * PostgreSQL QueryBuilder
  *
- * PostgreSQL specifics:
- * - OUTPUT: uses RETURNING clause (native support)
- * - TRUNCATE: RESTART IDENTITY option required
- * - UPSERT: CTE approach (INSERT ... ON CONFLICT only supports single unique constraint)
- * - AUTO_INCREMENT: GENERATED BY DEFAULT AS IDENTITY (allows explicit value assignment)
- * - Separate index generation needed when adding FK (unlike MySQL)
+ * PostgreSQL 고유 사항:
+ * - OUTPUT: RETURNING 절 사용 (네이티브 지원)
+ * - TRUNCATE: RESTART IDENTITY 옵션 필요
+ * - UPSERT: CTE 방식 (INSERT ... ON CONFLICT는 단일 유니크 제약조건만 지원)
+ * - AUTO_INCREMENT: GENERATED BY DEFAULT AS IDENTITY (명시적 값 할당 가능)
+ * - FK 추가 시 별도 인덱스 생성 필요 (MySQL과 다름)
  */
 export class PostgresqlQueryBuilder extends QueryBuilderBase {
   protected expr = new PostgresqlExprRenderer((def) => this.select(def).sql);
 
   //#region ========== Utilities ==========
 
-  /** Render table name (PostgreSQL: database is handled by connection, uses schema.table only) */
+  /** 테이블명 렌더링 (PostgreSQL: database는 연결에서 처리, schema.table만 사용) */
   protected tableName(obj: QueryDefObjectName): string {
     const schema = obj.schema ?? "public";
     return `${this.expr.wrap(schema)}.${this.expr.wrap(obj.name)}`;
   }
 
-  /** Render LIMIT...OFFSET clause */
+  /** LIMIT...OFFSET 절 렌더링 */
   protected renderLimit(limit: [number, number] | undefined, top: number | undefined): string {
     if (limit != null) {
       const [offset, count] = limit;
@@ -71,15 +71,15 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
   protected renderJoin(join: SelectQueryDefJoin): string {
     const alias = this.expr.wrap(join.as);
 
-    // Detect if LATERAL JOIN is needed
+    // LATERAL JOIN이 필요한지 감지
     if (this.needsLateral(join)) {
-      // If from is an array (UNION ALL), use renderFrom(join.from),
-      // otherwise (orderBy, top, select, etc.) use renderFrom(join) to generate subquery
+      // from이 배열(UNION ALL)이면 renderFrom(join.from) 사용,
+      // 그 외(orderBy, top, select 등)이면 renderFrom(join)으로 서브쿼리 생성
       const from = Array.isArray(join.from) ? this.renderFrom(join.from) : this.renderFrom(join);
       return ` LEFT OUTER JOIN LATERAL ${from} AS ${alias} ON TRUE`;
     }
 
-    // Normal JOIN
+    // 일반 JOIN
     const from = this.renderFrom(join.from);
     const where =
       join.where != null && join.where.length > 0
@@ -140,7 +140,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
     // LIMIT
     sql += this.renderLimit(def.limit, def.top);
 
-    // LOCK (FOR UPDATE at end)
+    // LOCK (끝에 FOR UPDATE 추가)
     if (def.lock) {
       sql += " FOR UPDATE";
     }
@@ -169,14 +169,14 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
 
     let sql = `INSERT INTO ${table} (${colList})`;
 
-    // GENERATED BY DEFAULT AS IDENTITY, so no additional clause needed for explicit value insertion
-    // overrideIdentity parameter is kept for MSSQL (SET IDENTITY_INSERT) compatibility, but
-    // PostgreSQL's GENERATED BY DEFAULT automatically allows explicit values
-    // (note: OVERRIDING SYSTEM VALUE would be needed if GENERATED ALWAYS was used)
+    // GENERATED BY DEFAULT AS IDENTITY이므로 명시적 값 삽입에 추가 구문 불필요
+    // overrideIdentity 파라미터는 MSSQL (SET IDENTITY_INSERT) 호환성을 위해 유지하지만
+    // PostgreSQL의 GENERATED BY DEFAULT는 자동으로 명시적 값을 허용
+    // (참고: GENERATED ALWAYS를 사용했다면 OVERRIDING SYSTEM VALUE가 필요)
 
     sql += ` VALUES ${valuesList.join(", ")}`;
 
-    // RETURNING (PostgreSQL native support)
+    // RETURNING (PostgreSQL 네이티브 지원)
     if (def.output != null) {
       const outputCols = def.output.columns.map((c) => this.expr.wrap(c)).join(", ");
       sql += ` RETURNING ${outputCols}`;
@@ -192,7 +192,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
     const colList = columns.map((c) => this.expr.wrap(c)).join(", ");
     const values = columns.map((c) => this.expr.escapeValue(def.record[c])).join(", ");
 
-    // Render existsSelectQuery as SELECT 1 AS _
+    // existsSelectQuery를 SELECT 1 AS _로 렌더링
     const existsQuerySql = this.select({
       ...def.existsSelectQuery,
       select: { _: { type: "value", value: 1 } },
@@ -200,7 +200,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
 
     let sql = `INSERT INTO ${table} (${colList}) SELECT ${values} WHERE NOT EXISTS (${existsQuerySql})`;
 
-    // RETURNING
+    // RETURNING 절
     if (def.output != null) {
       const outputCols = def.output.columns.map((c) => this.expr.wrap(c)).join(", ");
       sql += ` RETURNING ${outputCols}`;
@@ -213,7 +213,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
     const table = this.tableName(def.table);
     const selectSql = this.select(def.recordsSelectQuery).sql;
 
-    // Extract columns from INSERT INTO SELECT
+    // INSERT INTO SELECT에서 column 추출
     const selectDef = def.recordsSelectQuery;
     const colList =
       selectDef.select != null
@@ -224,7 +224,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
 
     let sql = `INSERT INTO ${table} (${colList}) ${selectSql}`;
 
-    // RETURNING
+    // RETURNING 절
     if (def.output != null) {
       const outputCols = def.output.columns.map((c) => this.expr.wrap(c)).join(", ");
       sql += ` RETURNING ${outputCols}`;
@@ -248,7 +248,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
 
     let sql = `UPDATE ${table} AS ${alias} SET ${setParts.join(", ")}`;
 
-    // PostgreSQL: JOINs are handled via FROM clause
+    // PostgreSQL: JOIN은 FROM 절로 처리
     if (def.joins != null && def.joins.length > 0) {
       const joinTables = def.joins.map((j) => {
         const from = this.renderFrom(j.from);
@@ -256,7 +256,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
       });
       sql += ` FROM ${joinTables.join(", ")}`;
 
-      // Add JOIN ON conditions to WHERE
+      // JOIN ON 조건을 WHERE에 추가
       const joinConditions = def.joins
         .filter((j) => j.where != null && j.where.length > 0)
         .map((j) => this.expr.renderWhere(j.where!));
@@ -273,7 +273,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
       sql += this.renderWhere(def.where);
     }
 
-    // RETURNING
+    // RETURNING 절
     if (def.output != null) {
       const outputCols = def.output.columns.map((c) => `${alias}.${this.expr.wrap(c)}`).join(", ");
       sql += ` RETURNING ${outputCols}`;
@@ -292,7 +292,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
 
     let sql = `DELETE FROM ${table} AS ${alias}`;
 
-    // PostgreSQL: JOINs are handled via USING clause
+    // PostgreSQL: JOIN은 USING 절로 처리
     if (def.joins != null && def.joins.length > 0) {
       const joinTables = def.joins.map((j) => {
         const from = this.renderFrom(j.from);
@@ -300,7 +300,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
       });
       sql += ` USING ${joinTables.join(", ")}`;
 
-      // Add JOIN ON conditions to WHERE
+      // JOIN ON 조건을 WHERE에 추가
       const joinConditions = def.joins
         .filter((j) => j.where != null && j.where.length > 0)
         .map((j) => this.expr.renderWhere(j.where!));
@@ -317,7 +317,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
       sql += this.renderWhere(def.where);
     }
 
-    // RETURNING (PostgreSQL: also supported for DELETE)
+    // RETURNING (PostgreSQL: DELETE에서도 지원)
     if (def.output != null) {
       const outputCols = def.output.columns.map((c) => this.expr.wrap(c)).join(", ");
       sql += ` RETURNING ${outputCols}`;
@@ -331,31 +331,31 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
   //#region ========== DML - UPSERT ==========
 
   protected upsert(def: UpsertQueryDef): QueryBuildResult {
-    // PostgreSQL: CTE approach (uses CTE for generality since ON CONFLICT only supports single unique constraint)
+    // PostgreSQL: CTE 방식 (ON CONFLICT는 단일 유니크 제약조건만 지원하므로 범용성을 위해 CTE 사용)
     const table = this.tableName(def.table);
     const alias = this.expr.wrap(def.existsSelectQuery.as);
 
-    // UPDATE SET part
+    // UPDATE SET 부분
     const updateSetParts = Object.entries(def.updateRecord).map(
       ([col, e]) => `${this.expr.wrap(col)} = ${this.expr.render(e)}`,
     );
 
-    // INSERT part
+    // INSERT 부분
     const insertColumns = Object.keys(def.insertRecord);
     const insertColList = insertColumns.map((c) => this.expr.wrap(c)).join(", ");
     const insertValues = insertColumns.map((c) => this.expr.render(def.insertRecord[c])).join(", ");
 
-    // WHERE condition
+    // WHERE 조건
     const whereCondition =
       def.existsSelectQuery.where != null && def.existsSelectQuery.where.length > 0
         ? this.expr.renderWhere(def.existsSelectQuery.where)
         : "TRUE";
 
-    // OUTPUT column
+    // OUTPUT column 정의
     const outputCols =
       def.output != null ? def.output.columns.map((c) => this.expr.wrap(c)).join(", ") : "*";
 
-    // CTE-based UPSERT
+    // CTE 기반 UPSERT
     let sql = `WITH matched AS (\n`;
     sql += `  SELECT ${alias}.* FROM ${table} AS ${alias} WHERE ${whereCondition}\n`;
     sql += `),\n`;
@@ -385,7 +385,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
     const colDefs = def.columns.map((col) => {
       let colSql = `${this.expr.wrap(col.name)} ${this.expr.renderDataType(col.dataType)}`;
 
-      // nullable: true → NULL, else → NOT NULL
+      // nullable: true → NULL, 아니면 → NOT NULL
       if (col.nullable === true) {
         colSql += " NULL";
       } else {
@@ -403,7 +403,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
       return colSql;
     });
 
-    // Primary Key with CONSTRAINT name
+    // CONSTRAINT 이름이 포함된 Primary Key
     if (def.primaryKey != null && def.primaryKey.length > 0) {
       const pkCols = def.primaryKey.map((c) => this.expr.wrap(c)).join(", ");
       const pkName = this.expr.wrap(`PK_${def.table.name}`);
@@ -424,7 +424,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
   }
 
   protected truncate(def: TruncateQueryDef): QueryBuildResult {
-    // PostgreSQL: reset sequence with RESTART IDENTITY
+    // PostgreSQL: RESTART IDENTITY로 시퀀스 초기화
     return { sql: `TRUNCATE TABLE ${this.tableName(def.table)} RESTART IDENTITY` };
   }
 
@@ -466,22 +466,22 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
     const table = this.tableName(def.table);
     const col = def.column;
 
-    // PostgreSQL: ALTER COLUMN requires multiple ALTER statements
+    // PostgreSQL: ALTER COLUMN은 여러 ALTER 문이 필요
     const parts: string[] = [];
 
-    // Change TYPE
+    // TYPE 변경
     parts.push(
       `ALTER COLUMN ${this.expr.wrap(col.name)} TYPE ${this.expr.renderDataType(col.dataType)}`,
     );
 
-    // Change NULL constraint
+    // NULL 제약조건 변경
     if (col.nullable === false) {
       parts.push(`ALTER COLUMN ${this.expr.wrap(col.name)} SET NOT NULL`);
     } else {
       parts.push(`ALTER COLUMN ${this.expr.wrap(col.name)} DROP NOT NULL`);
     }
 
-    // Change DEFAULT
+    // DEFAULT 변경
     if (col.default !== undefined) {
       parts.push(
         `ALTER COLUMN ${this.expr.wrap(col.name)} SET DEFAULT ${this.expr.escapeValue(col.default)}`,
@@ -526,7 +526,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
 
     let sql = `ALTER TABLE ${table} ADD CONSTRAINT ${this.expr.wrap(fk.name)} FOREIGN KEY (${fkCols}) REFERENCES ${targetTable} (${targetCols})`;
 
-    // PostgreSQL: separate index generation needed for FK
+    // PostgreSQL: FK에 대한 별도 인덱스 생성 필요
     const idxName = `IDX_${def.table.name}_${fk.name.replace(/^FK_/, "")}`;
     sql += `;\nCREATE INDEX ${this.expr.wrap(idxName)} ON ${table} (${fkCols});`;
 
@@ -548,7 +548,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
   }
 
   protected dropIndex(def: DropIndexQueryDef): QueryBuildResult {
-    // PostgreSQL: indexes are unique at schema level so table name is not needed, but schema must be specified
+    // PostgreSQL: 인덱스는 스키마 수준에서 고유하므로 테이블명은 불필요하지만 스키마 지정 필요
     const schema = def.table.schema ?? "public";
     return { sql: `DROP INDEX ${this.expr.wrap(schema)}.${this.expr.wrap(def.index)}` };
   }
@@ -570,7 +570,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
   protected createProc(def: CreateProcQueryDef): QueryBuildResult {
     const proc = this.tableName(def.procedure);
 
-    // Process params
+    // 파라미터 처리
     const paramList =
       def.params
         ?.map((p) => {
@@ -582,7 +582,7 @@ export class PostgresqlQueryBuilder extends QueryBuilderBase {
         })
         .join(", ") ?? "";
 
-    // Process returns
+    // 반환 타입 처리
     let returnClause = "VOID";
     if (def.returns && def.returns.length > 0) {
       const returnFields = def.returns
@@ -675,10 +675,10 @@ END $$`,
   protected switchFk(def: SwitchFkQueryDef): QueryBuildResult {
     const table = this.tableName(def.table);
     if (def.enabled) {
-      // PostgreSQL: enable all FK triggers on the table
+      // PostgreSQL: 테이블의 모든 FK 트리거 활성화
       return { sql: `ALTER TABLE ${table} ENABLE TRIGGER ALL` };
     }
-    // PostgreSQL: disable all FK triggers on the table
+    // PostgreSQL: 테이블의 모든 FK 트리거 비활성화
     return { sql: `ALTER TABLE ${table} DISABLE TRIGGER ALL` };
   }
 

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

@@ -139,7 +139,7 @@ export class ForeignKeyTargetBuilder<
 }
 
 // ============================================
-// RelationKeyBuilder (same as FK but does not register FK in DB)
+// RelationKeyBuilder (FK와 동일하지만 DB에 FK를 등록하지 않음)
 // ============================================
 
 /**
@@ -153,15 +153,15 @@ export class ForeignKeyTargetBuilder<
  *
  * @example
  * ```typescript
- * // Relation definition from View to Table
+ * // View에서 Table로의 관계 정의
  * const UserSummary = View("UserSummary")
  *   .query((db: MyDb) => db.user().select(...))
  *   .relations((r) => ({
- *     // View → Table (no FK creation)
+ *     // View → Table (FK 미생성)
  *     company: r.relationKey(["companyId"], () => Company),
  *   }));
  *
- * // Relation definition from Table without FK
+ * // FK 없는 Table 관계 정의
  * const Report = Table("Report")
  *   .columns((c) => ({ userId: c.bigint() }))
  *   .relations((r) => ({
@@ -216,7 +216,7 @@ export class RelationKeyBuilder<
  * const Company = Table("Company")
  *   .columns((c) => ({ id: c.bigint() }))
  *   .relations((r) => ({
- *     // Reverse-reference (no FK creation)
+ *     // 역참조 (FK 미생성)
  *     employees: r.relationKeyTarget(() => UserSummary, "company"),
  *   }));
  * ```
@@ -321,21 +321,21 @@ type RelationRkFactory<
  *
  * @example
  * ```typescript
- * // Table - both FK and RelationKey available
+ * // Table - FK와 RelationKey 모두 사용 가능
  * const Post = Table("Post")
  *   .columns((c) => ({
  *     id: c.bigint(),
  *     authorId: c.bigint(),
  *   }))
  *   .relations((r) => ({
- *     author: r.foreignKey(["authorId"], () => User),  // FK Generate
+ *     author: r.foreignKey(["authorId"], () => User),  // FK 생성
  *   }));
  *
- * // View - only RelationKey available
+ * // View - RelationKey만 사용 가능
  * const UserSummary = View("UserSummary")
  *   .query(...)
  *   .relations((r) => ({
- *     posts: r.relationKeyTarget(() => Post, "author"),  // No FK creation
+ *     posts: r.relationKeyTarget(() => Post, "author"),  // FK 미생성
  *   }));
  * ```
  */

package/src/schema/view-builder.ts

@@ -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)),

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
@@ -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
  */