sonamu 0.7.4 → 0.7.5

package/src/database/puri.types.ts

@@ -1,27 +1,50 @@
 /** biome-ignore-all lint/suspicious/noExplicitAny: Puri.types.ts는 다양한 타입을 사용하고 있습니다. */
 
 import type { QueryResult } from "pg";
-import type { DatabaseSchemaExtend } from "../types/types";
+import type { DatabaseForeignKeys, DatabaseSchemaExtend } from "../types/types";
 import type { Puri } from "./puri";
 import type { PuriWrapper } from "./puri-wrapper";
 
-// 메타데이터 컬럼 유틸
-type MetadataColumns = "__fulltext__" | "__virtual__";
+// ============================================
+// 내부 타입 키 (메타데이터)
+// ============================================
+type FulltextKey = "__fulltext__";
+type VirtualKey = "__virtual__";
+type LeftJoinedKey = "__leftJoined__";
+type HasDefault = "__hasDefault__";
+type GeneratedKey = "__generated__";
+
+type InternalTypeKeys = FulltextKey | VirtualKey | LeftJoinedKey | HasDefault | GeneratedKey;
+
+// ============================================
+// 타입 유틸리티
+// ============================================
+
+// 테이블명 타입
+export type TableName<TSchema> = keyof TSchema & string;
 
 // virtual 컬럼 타입 추출
-type VirtualKeys<T> = T extends { __virtual__: readonly (infer V)[] } ? V & string : never;
+type VirtualKeys<T> = T extends { [K in VirtualKey]: readonly (infer V)[] } ? V & string : never;
 
 // virtual 컬럼 제거
 type StripVirtual<T> = Omit<T, VirtualKeys<T>>;
 
+// LEFT JOIN 마커 - nullable FK로 조인된 테이블
+// 이 마커는 nullable FK + leftJoin 조합에서만 붙습니다.
+// join + FK nullable -> 안 붙음
+// join + FK non-nullable -> 안 붙음
+// leftJoin + FK non-nullable -> 안 붙음
+// leftJoin + FK nullable -> 붙음!
+export type LeftJoinedMarker = { [K in LeftJoinedKey]: true };
+
 // 메타데이터 필드 제외한 실제 엔티티 컬럼
-export type ColumnKeys<T> = Exclude<keyof StripVirtual<T>, MetadataColumns> & string;
+export type ColumnKeys<T> = Exclude<keyof StripVirtual<T>, InternalTypeKeys> & string;
 
-// virtual 컬럼 제거 후 __fulltext__ 메타데이터 유지
-export type PuriTable<T> = Omit<StripVirtual<T>, "__virtual__">;
+// virtual 컬럼 제거 후 __fulltext__ 유지
+export type PuriTable<T> = Omit<StripVirtual<T>, VirtualKey>;
 
-// 메타데이터 컬럼 제외 타입 정의
-export type OmitMetadataColumns<T> = Omit<T, MetadataColumns>;
+// 내부 타입 키 제외 (실제 컬럼만 남김)
+export type OmitInternalTypeKeys<T> = Omit<T, InternalTypeKeys>;
 
 // TTables의 모든 테이블에서 사용 가능한 컬럼 경로
 export type AvailableColumns<TTables extends Record<string, any>> =
@@ -32,27 +55,120 @@ export type AvailableColumns<TTables extends Record<string, any>> =
       ? ColumnKeys<TTables[keyof TTables]> // 단일 테이블이면 컬럼명만도 허용
       : never);
 
+// 숫자 타입 컬럼만 추출하는 유틸리티 타입
+type NumericColumnKeys<T> = {
+  [K in keyof T]: T[K] extends number | bigint | null | undefined ? K : never;
+}[keyof T] &
+  string;
+
+// TTables의 모든 테이블에서 숫자 타입 컬럼만 추출
+export type NumericColumns<TTables extends Record<string, any>> =
+  | {
+      [TAlias in keyof TTables]: `${TAlias & string}.${NumericColumnKeys<TTables[TAlias]>}`;
+    }[keyof TTables]
+  | (IsSingleKey<TTables> extends true
+      ? NumericColumnKeys<TTables[keyof TTables]> // 단일 테이블이면 컬럼명만도 허용
+      : never);
+
 // Group By, Order By, Having 등에서 선택 가능한 컬럼
 export type ResultAvailableColumns<TTables extends Record<string, any>, TResult = any> =
   | AvailableColumns<TTables>
   | `${keyof TResult & string}`;
 
-// Select 값 타입 확장
+// Select 값 타입 확장 (단일 컬럼 또는 SQL 표현식)
 export type SelectValue<TTables extends Record<string, any>> =
   | AvailableColumns<TTables>
   | SqlExpression<"string" | "number" | "boolean" | "date">;
 
-// Select 객체 타입 (현재는 컬럼 경로만 지원)
-export type SelectObject<TTables extends Record<string, any>> = Record<
-  string,
-  SelectValue<TTables> // AvailableColumns 대신
->;
+// 중첩 Select 객체 타입 (재귀적)
+// 예: { parent: { id: "parent.id", name: "parent.name" } }
+export type NestedSelectObject<TTables extends Record<string, any>> = {
+  [key: string]: SelectValue<TTables> | NestedSelectObject<TTables>;
+};
+
+// Select 객체 타입 (flat 또는 중첩 허용)
+export type SelectObject<TTables extends Record<string, any>> = NestedSelectObject<TTables>;
+
+// 값이 중첩 객체인지 판별하는 헬퍼 타입
+type IsNestedObject<T> = T extends string
+  ? false
+  : T extends SqlExpression<any>
+    ? false
+    : T extends Record<string, any>
+      ? true
+      : false;
+
+// 컬럼이 nullable인지 확인 (스키마에서 직접 추출)
+// 예: IsNullableColumn<TTables, "employees.department_id"> → department_id가 number | null이면 true
+export type IsNullableColumn<
+  TTables,
+  Path extends string,
+> = Path extends `${infer TAlias}.${infer TColumn}`
+  ? TAlias extends keyof TTables
+    ? TColumn extends keyof TTables[TAlias]
+      ? null extends TTables[TAlias][TColumn]
+        ? true
+        : false
+      : false
+    : false
+  : false;
+
+// FK nullable 여부에 따른 마커 타입 결정
+// nullable FK로 leftJoin → LeftJoinedMarker (객체 자체가 null일 수 있음)
+// non-null FK로 leftJoin → 마커 없음 (부모가 있으면 자식도 반드시 있음)
+export type LeftJoinMarkerFor<TTables, Path extends string> = IsNullableColumn<
+  TTables,
+  Path
+> extends true
+  ? LeftJoinedMarker
+  : {};
+
+// 주어진 테이블이 FK nullable로 leftJoin 된 테이블인지 확인합니다.
+// 사실 LeftJoinMarker가 붙었는지 확인하는게 다입니다.
+// 이 마커는 FK nullable + leftJoin 조합에서만 붙습니다.
+type IsNullableJoinedTable<TTables, TableKey> = TableKey extends keyof TTables
+  ? TTables[TableKey] extends LeftJoinedMarker
+    ? true // LeftJoinedMarker가 있으면 nullable
+    : false
+  : false;
 
-// Select 결과 타입 추론
+// 경로 조합 헬퍼 (prefix가 없으면 key만, 있으면 prefix__key)
+type JoinPath<Prefix extends string, Key extends string> = Prefix extends ""
+  ? Key
+  : `${Prefix}__${Key}`;
+
+// Select 결과 타입을 추론해주는 친구입니다.
+// 이 타입은 Puri의 select, appendSelect에서 TResult로 사용됩니다.
+//
+// Schema를 읽어서 FK의 nullability에 따라 join된 객체의 타입을 추론해주는 기능이 있습니다.
+// 이게 무슨 소리냐? FK가 nullable인데 leftJoin되었다면, 해당 객체는 nullable 해야 함을 타입 추론으로 반영해준다는 것입니다.
+// 반면 FK가 non-nullable이거나 그냥 join으로 이어졌다면 해당 객체는 non-nullable할 겁니다.
+// 물론 객체 내부의 nullability는 또 별개로 추론됩니다. 
+// 
+// 아래에도 ParseSelectObjectWithPath를 비롯해 ExtractColumnType, ExtractColumnTypeRaw 등의 타입이 있습니다.
+// 이들의 역할은 다음과 같습니다:
+// - Parse*: 객체 레벨에서 중첩 구조를 순회하며 객체에 | null을 붙일지 결정합니다.
+// - Extract*: 필드 레벨에서 "table.column" 경로로부터 실제 타입을 추출합니다.
+//
+// 예시:
+// .select({
+//   id: "users.id",           // ← ExtractColumnType의 결과는 number입니다.
+//   department: {             // ← ParseSelectObjectInner에 의해 nullable 객체로 추론됩니다.
+//     id: "department.id",    // ← ExtractColumnTypeRaw의 결과는 number입니다.
+//     name: "department.name" // ← ExtractColumnTypeRaw의 결과는 string입니다.
+//   }
+// })
 export type ParseSelectObject<
   TTables extends Record<string, any>,
   TSelect extends SelectObject<TTables>,
-> = {
+> = ParseSelectObjectWithPath<TTables, TSelect, "">;
+
+// 경로를 추적하면서 Select 결과 타입을 추론합니다.
+type ParseSelectObjectWithPath<
+  TTables extends Record<string, any>,
+  TSelect extends SelectObject<TTables>,
+  Prefix extends string,
+> = Expand<{
   [K in keyof TSelect]: TSelect[K] extends SqlExpression<infer R>
     ? R extends "string"
       ? string
@@ -63,24 +179,78 @@ export type ParseSelectObject<
           : R extends "date"
             ? Date
             : never
-    : ExtractColumnType<TTables, TSelect[K] & string>;
-};
+    : IsNestedObject<TSelect[K]> extends true
+      ? TSelect[K] extends NestedSelectObject<TTables>
+        ? IsNullableJoinedTable<TTables, JoinPath<Prefix, K & string>> extends true // 주어진 테이블이 FK nullable에 leftJoin되었는지 여부에 따라 select 결과 객체의 타입이 달라집니다.
+          ? Expand<ParseSelectObjectInner<TTables, TSelect[K], JoinPath<Prefix, K & string>>> | null // 만약 해당한다면 해당 객체 자체는 nullable 하며,
+          : Expand<ParseSelectObjectInner<TTables, TSelect[K], JoinPath<Prefix, K & string>>> // 그렇지 않다면 non-nullable 합니다.
+        : never
+      : ExtractColumnType<TTables, TSelect[K] & string>;
+}>;
+
+// 중첩 객체 내부용 - leftJoin nullable을 객체 레벨에서 이미 처리했으므로 필드는 원본 타입을 사용합니다.
+// ParseSelectObjectWithPath와 거의 동일하나, 마지막에 ExtractColumnType 대신 ExtractColumnTypeRaw를 사용하여
+// 필드 레벨에서 중복으로 | null이 추가되는 것을 방지합니다.
+type ParseSelectObjectInner<
+  TTables extends Record<string, any>,
+  TSelect extends SelectObject<TTables>,
+  Prefix extends string,
+> = Expand<{
+  [K in keyof TSelect]: TSelect[K] extends SqlExpression<infer R>
+    ? R extends "string"
+      ? string
+      : R extends "number"
+        ? number
+        : R extends "boolean"
+          ? boolean
+          : R extends "date"
+            ? Date
+            : never
+    : IsNestedObject<TSelect[K]> extends true
+      ? TSelect[K] extends NestedSelectObject<TTables>
+        ? IsNullableJoinedTable<TTables, JoinPath<Prefix, K & string>> extends true
+          ? Expand<ParseSelectObjectInner<TTables, TSelect[K], JoinPath<Prefix, K & string>>> | null
+          : Expand<ParseSelectObjectInner<TTables, TSelect[K], JoinPath<Prefix, K & string>>>
+        : never
+      : ExtractColumnTypeRaw<TTables, TSelect[K] & string>; // leftJoin nullable 무시
+}>;
 
-// 컬럼 경로에서 타입 추출
+// 컬럼 경로에서 타입을 추출합니다. LeftJoinedMarker가 있으면 | null을 추가합니다.
+// 최상위 select 필드에서 사용됩니다.
 export type ExtractColumnType<
   TTables extends Record<string, any>,
   Path extends string,
 > = Path extends `${infer TAlias}.${infer TColumn}`
   ? TAlias extends keyof TTables
     ? TColumn extends keyof TTables[TAlias]
-      ? TTables[TAlias][TColumn]
+      ? TTables[TAlias] extends LeftJoinedMarker
+        ? TTables[TAlias][TColumn] | null // LEFT JOIN (nullable FK) → nullable
+        : TTables[TAlias][TColumn] // INNER JOIN 또는 non-null FK leftJoin → non-nullable
+      : never
+    : never
+  : IsSingleKey<TTables> extends true
+    ? Path extends keyof TTables[keyof TTables]
+      ? TTables[keyof TTables][Path]
+      : never
+    : never;
+
+// 컬럼 경로에서 타입을 추출합니다. leftJoin 여부와 관계없이 원본 타입을 반환합니다.
+// 중첩 객체 내부 필드에서 사용됩니다. (객체 레벨에서 이미 | null 처리가 완료되었으므로)
+type ExtractColumnTypeRaw<
+  TTables extends Record<string, any>,
+  Path extends string,
+> = Path extends `${infer TAlias}.${infer TColumn}`
+  ? TAlias extends keyof TTables
+    ? TColumn extends keyof TTables[TAlias]
+      ? TTables[TAlias][TColumn] // leftJoin 여부와 관계없이 원본 타입
       : never
     : never
-  : IsSingleKey<TTables> extends true // 추가
+  : IsSingleKey<TTables> extends true
     ? Path extends keyof TTables[keyof TTables]
       ? TTables[keyof TTables][Path]
       : never
     : never;
+
 // Where 조건 객체 타입
 // 예: { "u.id": 1, "u.status": "active" }
 export type WhereCondition<TTables extends Record<string, any>> = {
@@ -90,7 +260,7 @@ export type WhereCondition<TTables extends Record<string, any>> = {
 // Fulltext index 컬럼 추출 타입
 export type FulltextColumns<TTables extends Record<string, any>> = {
   [TAlias in keyof TTables]: TTables[TAlias] extends {
-    __fulltext__: readonly (infer Col)[];
+    [K in FulltextKey]: readonly (infer Col)[];
   }
     ? Col extends string
       ? `${TAlias & string}.${Col}`
@@ -100,6 +270,8 @@ export type FulltextColumns<TTables extends Record<string, any>> = {
 
 // 비교 연산자
 export type ComparisonOperator = "=" | ">" | ">=" | "<" | "<=" | "<>" | "!=";
+// 조건 연산자: 비교 연산자 + 패턴 매칭 연산자
+export type WhereOperator = ComparisonOperator | "like" | "not like";
 
 // SQL Expression 타입 정의
 export type SqlExpression<T extends "string" | "number" | "boolean" | "date"> = {
@@ -126,17 +298,23 @@ type IsSingleKey<TTables extends Record<string, any>> = keyof TTables extends in
 export type SingleTableValue<TTables extends Record<string, any>> =
   IsSingleKey<TTables> extends true ? TTables[keyof TTables] : never;
 
-// Nullable을 Optional로 변환
-type NullableToOptional<T> = {
-  [K in keyof T as T[K] extends null | undefined ? K : never]?: Exclude<T[K], null | undefined>;
-} & Partial<{
-  [K in keyof T as T[K] extends null | undefined ? never : K]: T[K];
-}>;
+// __hasDefault__에 포함된 키들을 PuriTable<T>의 키로 제한
+type HasDefaultKeys<T> = T extends { __hasDefault__: readonly (infer K)[] }
+  ? Extract<K, keyof PuriTable<T>>
+  : never;
 
-// Insert 타입: id, created_at 제외
-export type InsertData<T> = NullableToOptional<
-  Omit<PuriTable<T>, "id" | "created_at" | MetadataColumns>
->;
+// __generated__에 포함된 키들 (INSERT 시 제외해야 함)
+type GeneratedKeys<T> = T extends { __generated__: readonly (infer K)[] }
+  ? Extract<K, keyof PuriTable<T>>
+  : never;
+
+// Insert 타입: 메타데이터 제거 후, __hasDefault__ 컬럼들만 optional로 처리, __generated__ 컬럼은 완전히 제외
+export type InsertData<T> = Omit<
+  PuriTable<T>,
+  InternalTypeKeys | HasDefaultKeys<T> | GeneratedKeys<T>
+> & {
+  [K in HasDefaultKeys<T>]?: PuriTable<T>[K];
+};
 
 // Insert Result 타입
 export type InsertResult = Pick<QueryResult<any>, "command" | "rowCount" | "rows" | "oid">;
@@ -170,3 +348,23 @@ export type OnConflictAction<TTables extends Record<string, unknown>> =
         | AvailableColumns<TTables>[] // 배열 형태 - ["name", "email"]
         | WhereCondition<TTables>; // 객체 형태 - { name: "John", count: Puri.rawNumber(...) }
     };
+
+// FK 컬럼명 추출 유틸리티 타입 - DatabaseForeignKeys 활용
+export type ForeignKeyColumns<TTable extends TableName<DatabaseSchemaExtend>> =
+  TTable extends keyof DatabaseForeignKeys ? DatabaseForeignKeys[TTable] : never;
+
+// Union을 Intersection으로 변환하는 유틸리티
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void
+  ? I
+  : never;
+
+// SelectAll 시 모든 조인된 테이블의 컬럼 포함
+export type SelectAllResult<TTables extends Record<string, any>> = UnionToIntersection<
+  {
+    [K in keyof TTables]: TTables[K] extends infer T
+      ? T extends LeftJoinedMarker
+        ? Partial<OmitInternalTypeKeys<T>> // LEFT JOIN은 nullable, 메타데이터 제거
+        : OmitInternalTypeKeys<T> // INNER JOIN은 non-nullable, 메타데이터 제거
+      : never;
+  }[keyof TTables]
+>;

package/src/database/upsert-builder.ts

@@ -3,24 +3,43 @@ import type { Knex } from "knex";
 import { isArray, unique } from "radashi";
 import { EntityManager } from "../entity/entity-manager";
 import { Naite } from "../naite/naite";
+import type { DatabaseForeignKeys, DatabaseSchemaExtend, EntityIndex } from "../types/types";
 import { assertDefined, chunk, nonNullable } from "../utils/utils";
 import { batchUpdate, type RowWithId } from "./_batch_update";
+import type { ForeignKeyColumns, TableName } from "./puri.types";
 
+/**
+ * FK 타입 추론을 위해 DatabaseForeignKeys export
+ * (module augmentation 자동 로드 보장)
+ */
+export type { DatabaseForeignKeys };
+
+// 테이블 데이터 타입
 type TableData = {
   references: Set<string>;
   rows: Record<string, unknown>[];
-  uniqueIndexes: { name?: string; columns: string[] }[];
+  uniqueIndexes: EntityIndex[];
   uniquesMap: Map<string, string>;
 };
+
+// 참조 필드 타입
 export type UBRef = {
   uuid: string;
   of: string;
   use?: string;
 };
-type UpsertOptions = {
+
+// upsert 옵션
+export type UpsertOptions<TTable extends TableName<DatabaseSchemaExtend>> = {
+  chunkSize?: number;
+  cleanOrphans?: ForeignKeyColumns<TTable> | ForeignKeyColumns<TTable>[];
+};
+
+// insertOnly 옵션
+export type InsertOnlyOptions = {
   chunkSize?: number;
-  cleanOrphans?: string | string[]; // FK 컬럼명(들)
 };
+
 export function isRefField(field: unknown): field is UBRef {
   return (
     field !== undefined &&
@@ -76,11 +95,11 @@ export class UpsertBuilder {
     const uniqueKeys = table.uniqueIndexes
       .map((unqIndex) => {
         const uniqueKeyArray = unqIndex.columns.map((unqCol) => {
-          const val = row[unqCol as keyof typeof row];
+          const val = row[unqCol.name as keyof typeof row];
           if (isRefField(val)) {
             return val.uuid;
           } else {
-            return row[unqCol as keyof typeof row] ?? randomUUID(); // nullable인 경우 uuid로 랜덤값 삽입
+            return row[unqCol.name as keyof typeof row] ?? randomUUID(); // nullable인 경우 uuid로 랜덤값 삽입
           }
         });
 
@@ -154,37 +173,27 @@ export class UpsertBuilder {
     return result;
   }
 
-  async upsert(
+  async upsert<TTable extends TableName<DatabaseSchemaExtend>>(
     wdb: Knex,
-    tableName: string,
-    optionsOrChunkSize?: UpsertOptions,
+    tableName: TTable,
+    options?: UpsertOptions<TTable>,
   ): Promise<number[]> {
-    // 숫자면 { chunkSize: n } 으로 변환
-    const options =
-      typeof optionsOrChunkSize === "number"
-        ? { chunkSize: optionsOrChunkSize }
-        : optionsOrChunkSize;
-
     return this.upsertOrInsert(wdb, tableName, "upsert", options);
   }
-  async insertOnly(
+
+  async insertOnly<TTable extends TableName<DatabaseSchemaExtend>>(
     wdb: Knex,
-    tableName: string,
-    optionsOrChunkSize?: UpsertOptions | number,
+    tableName: TTable,
+    options?: InsertOnlyOptions,
   ): Promise<number[]> {
-    const options =
-      typeof optionsOrChunkSize === "number"
-        ? { chunkSize: optionsOrChunkSize }
-        : optionsOrChunkSize;
-
     return this.upsertOrInsert(wdb, tableName, "insert", options);
   }
 
-  async upsertOrInsert(
+  async upsertOrInsert<TTable extends TableName<DatabaseSchemaExtend>>(
     wdb: Knex,
-    tableName: string,
+    tableName: TTable,
     mode: "upsert" | "insert",
-    options?: UpsertOptions,
+    options?: UpsertOptions<TTable>,
   ): Promise<number[]> {
     if (this.hasTable(tableName) === false) {
       return [];
@@ -234,11 +243,6 @@ export class UpsertBuilder {
       throw new Error(`${tableName}에 순환 자기 참조가 있습니다.`);
     }
 
-    // upsert 모드일 때 유니크 인덱스가 없으면 에러
-    if (mode === "upsert" && table.uniqueIndexes.length === 0) {
-      throw new Error(`${tableName}에 unique index가 정의되지 않아 upsert를 할 수 없습니다.`);
-    }
-
     const uuidMap = new Map<string, unknown>();
     const allIds: number[] = [];
 
@@ -284,8 +288,11 @@ export class UpsertBuilder {
           // INSERT 모드 - RETURNING 사용
           resultRows = await wdb.insert(dataForDb).into(tableName).returning(selectFields);
         } else {
-          // UPSERT 모드 - onConflict 사용
-          const conflictColumns = table.uniqueIndexes[0].columns;
+          // UPSERT 모드 - onConflict 사용 (unique index 없으면 PK fallback)
+          const conflictColumns =
+            table.uniqueIndexes.length > 0
+              ? table.uniqueIndexes[0].columns.map((c) => c.name)
+              : ["id"];
           const updateColumns = Object.keys(dataForDb[0]).filter(
             (col) => !conflictColumns.includes(col),
           );
@@ -340,7 +347,9 @@ export class UpsertBuilder {
 
     if (options?.cleanOrphans) {
       const cleanOrphans = options.cleanOrphans;
-      const fkColumns = isArray(cleanOrphans) ? cleanOrphans : [cleanOrphans];
+      const fkColumns = isArray(cleanOrphans)
+        ? (cleanOrphans as ForeignKeyColumns<TTable>[])
+        : [cleanOrphans as ForeignKeyColumns<TTable>];
 
       // 현재 register된 레코드들의 FK 값들 추출
       const fkConditions = fkColumns.map((fkCol) => {
@@ -430,7 +439,7 @@ export class UpsertBuilder {
   }
 
   // ============================================================================
-  // Private Helpers
+  // Private Helper Methods
   // ============================================================================
 
   /**

package/src/entity/entity-manager.ts

@@ -5,7 +5,7 @@ import inflection from "inflection";
 import path from "path";
 import { prettifyError } from "zod";
 import { Sonamu } from "../api/sonamu";
-import { type EntityJson, EntityJsonSchema } from "../types/types";
+import { type EntityIndex, type EntityJson, EntityJsonSchema } from "../types/types";
 import type { AbsolutePath } from "../utils/path-utils";
 import { Entity } from "./entity";
 
@@ -15,7 +15,7 @@ export type EntityNamesRecord = Record<
 >;
 type TableSpec = {
   name: string;
-  uniqueIndexes: { name?: string; columns: string[] }[];
+  uniqueIndexes: EntityIndex[];
 };
 class EntityManagerClass {
   private entities: Map<string, Entity> = new Map();