sonamu 0.7.3 → 0.7.5

package/src/database/puri.ts

@@ -14,13 +14,18 @@ import type {
   FulltextColumns,
   InsertData,
   InsertResult,
+  LeftJoinedMarker,
+  LeftJoinMarkerFor,
+  NumericColumns,
   OnConflictAction,
   ParseSelectObject,
   ResultAvailableColumns,
+  SelectAllResult,
   SelectObject,
   SingleTableValue,
   SqlExpression,
   WhereCondition,
+  WhereOperator,
 } from "./puri.types";
 import type { ClearStatements } from "./puri-subset.types";
 
@@ -47,7 +52,7 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
       if (typeof spec === "string") {
         this.knexQuery = this.knex(spec).from({ [alias]: spec });
       } else if (spec instanceof Puri) {
-        const subqueryBuilder = spec.raw();
+        const subqueryBuilder = spec.rawQuery();
         this.knexQuery = this.knex.from(subqueryBuilder.as(alias));
       } else {
         throw new Error("Invalid table specification");
@@ -133,9 +138,12 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
   select<TSelect extends SelectObject<TTables>>(
     selectObj: TSelect,
   ): Puri<TSchema, TTables, ParseSelectObject<TTables, TSelect>> {
+    // 중첩 객체를 flat하게 변환
+    const flatSelect = this.flattenSelect(selectObj);
+
     const selectClauses: (string | Knex.Raw)[] = [];
 
-    for (const [alias, columnOrFunction] of Object.entries(selectObj)) {
+    for (const [alias, columnOrFunction] of Object.entries(flatSelect)) {
       if (typeof columnOrFunction === "object" && columnOrFunction._type === "sql_expression") {
         // SQL 함수인 경우
         selectClauses.push(this.knex.raw(`${columnOrFunction._sql} as ${alias}`));
@@ -156,15 +164,58 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
     return this as any;
   }
 
+  /**
+   * 중첩 객체를 flat 객체로 변환
+   * 예: { parent: { id: "parent.id", name: "parent.name" } }
+   *   → { parent__id: "parent.id", parent__name: "parent.name" }
+   */
+  private flattenSelect(selectObj: Record<string, any>, prefix = ""): Record<string, any> {
+    const flatSelect: Record<string, any> = {};
+
+    for (const [key, value] of Object.entries(selectObj)) {
+      const fullKey = prefix ? `${prefix}__${key}` : key;
+
+      if (typeof value === "object" && value !== null && !("_type" in value)) {
+        // 중첩 객체인 경우 - 재귀 처리
+        const nested = this.flattenSelect(value, fullKey);
+        Object.assign(flatSelect, nested);
+      } else {
+        // 일반 값인 경우 (컬럼 경로 또는 SqlExpression)
+        flatSelect[fullKey] = value;
+      }
+    }
+
+    return flatSelect;
+  }
+
   // SELECT (select는 overwrite, appendSelect는 append)
   appendSelect<TSelect extends SelectObject<TTables>>(
     selectObj: TSelect,
   ): Puri<TSchema, TTables, TResult & ParseSelectObject<TTables, TSelect>> {
-    return this.select(selectObj) as any;
+    // 중첩 객체를 flat하게 변환
+    const flatSelect = this.flattenSelect(selectObj);
+
+    const selectClauses: (string | Knex.Raw)[] = [];
+
+    for (const [alias, columnOrFunction] of Object.entries(flatSelect)) {
+      if (typeof columnOrFunction === "object" && columnOrFunction._type === "sql_expression") {
+        selectClauses.push(this.knex.raw(`${columnOrFunction._sql} as ${alias}`));
+      } else {
+        const columnPath = columnOrFunction as string;
+        if (alias === columnPath) {
+          selectClauses.push(columnPath);
+        } else {
+          selectClauses.push(`${columnPath} as ${alias}`);
+        }
+      }
+    }
+
+    this.knexQuery.select(selectClauses);
+    return this as any;
   }
 
   // SELECT *
-  selectAll(): this {
+  selectAll(): Puri<TSchema, TTables, SelectAllResult<TTables>> {
     this.knexQuery.select("*");
     return this as any;
   }
@@ -243,46 +294,47 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
     tableSpec: { [K in TJoinAlias]: Puri<TSchema, any, TSubResult> },
     left: AvailableColumns<TTables>,
     right: `${TJoinAlias}.${ColumnKeys<TSubResult>}`,
-  ): Puri<
-    TSchema,
-    TTables & Record<TJoinAlias, TSubResult>, // 서브쿼리의 TResult
-    TResult
-  >;
+  ): Puri<TSchema, TTables & Record<TJoinAlias, TSubResult & LeftJoinedMarker>, TResult>; // 서브쿼리의 TResult
   // LEFT JOIN: 테이블 + Alias
-  leftJoin<TJoinTable extends keyof TSchema, TJoinAlias extends string>(
+  // FK nullable 여부에 따라 자동으로 LeftJoinedMarker 결정
+  leftJoin<
+    TJoinTable extends keyof TSchema,
+    TJoinAlias extends string,
+    TLeft extends AvailableColumns<TTables>,
+  >(
     tableSpec: { [K in TJoinAlias]: TJoinTable },
-    left: AvailableColumns<TTables>,
+    left: TLeft,
     right: `${TJoinAlias}.${ColumnKeys<TSchema[TJoinTable]>}`,
   ): Puri<
     TSchema,
-    TTables & Record<TJoinAlias, TSchema[TJoinTable]>, // TTables 확장!
+    TTables & Record<TJoinAlias, TSchema[TJoinTable] & LeftJoinMarkerFor<TTables, TLeft>>,
     TResult
   >;
   // LEFT JOIN: 테이블명
-  leftJoin<TJoinTable extends keyof TSchema>(
+  leftJoin<TJoinTable extends keyof TSchema, TLeft extends AvailableColumns<TTables>>(
     tableName: TJoinTable,
-    left: AvailableColumns<TTables>,
+    left: TLeft,
     right: `${TJoinTable & string}.${ColumnKeys<TSchema[TJoinTable]>}`,
   ): Puri<
     TSchema,
-    TTables & Record<TJoinTable, TSchema[TJoinTable]>, // 테이블명이 키
+    TTables & Record<TJoinTable, TSchema[TJoinTable] & LeftJoinMarkerFor<TTables, TLeft>>,
     TResult
   >;
   // LEFT JOIN: 서브쿼리 + Alias + 콜백
   leftJoin<TJoinAlias extends string, TSubResult>(
     tableSpec: { [K in TJoinAlias]: Puri<TSchema, any, TSubResult> },
     callback: (j: JoinClauseGroup<TTables, Record<TJoinAlias, TSubResult>>) => void,
-  ): Puri<TSchema, TTables & Record<TJoinAlias, TSubResult>, TResult>;
+  ): Puri<TSchema, TTables & Record<TJoinAlias, TSubResult & LeftJoinedMarker>, TResult>;
   // LEFT JOIN: 테이블 + Alias + 콜백
   leftJoin<TJoinTable extends keyof TSchema, TJoinAlias extends string>(
     tableSpec: { [K in TJoinAlias]: TJoinTable },
     callback: (j: JoinClauseGroup<TTables, Record<TJoinAlias, TSchema[TJoinTable]>>) => void,
-  ): Puri<TSchema, TTables & Record<TJoinAlias, TSchema[TJoinTable]>, TResult>;
+  ): Puri<TSchema, TTables & Record<TJoinAlias, TSchema[TJoinTable] & LeftJoinedMarker>, TResult>;
   // LEFT JOIN: 테이블명 + 콜백
   leftJoin<TJoinTable extends keyof TSchema>(
     tableName: TJoinTable,
     callback: (j: JoinClauseGroup<TTables, Record<TJoinTable, TSchema[TJoinTable]>>) => void,
-  ): Puri<TSchema, TTables & Record<TJoinTable, TSchema[TJoinTable]>, TResult>;
+  ): Puri<TSchema, TTables & Record<TJoinTable, TSchema[TJoinTable] & LeftJoinedMarker>, TResult>;
   // LEFT JOIN 실제 구현
   leftJoin(tableNameOrSpec: any, ...args: any[]): any {
     return this.__commonJoin("leftJoin", tableNameOrSpec, ...args);
@@ -331,13 +383,13 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
         if (args.length === 1 && typeof args[0] === "function") {
           // Callback
           const callback = args[0];
-          this.knexQuery[joinType](spec.raw().as(alias), (joinClause) => {
+          this.knexQuery[joinType](spec.rawQuery().as(alias), (joinClause) => {
             callback(new JoinClauseGroup(joinClause));
           });
         } else {
           // Simple
           const [left, right] = args;
-          this.knexQuery[joinType](spec.raw().as(alias), left, right);
+          this.knexQuery[joinType](spec.rawQuery().as(alias), left, right);
         }
       } else {
         throw new Error("Invalid table specification");
@@ -351,17 +403,23 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
 
   // WHERE: 객체 - 사용: .where({ "u.id": 1, "u.status": "active" })
   where(conditions: WhereCondition<TTables>): this;
-  // WHERE: 컬럼 - 사용: .where("u.id", 1)
+  // WHERE: 컬럼 - 사용: .where("u.id", 1), .where("u.id", null)
   where<TColumn extends AvailableColumns<TTables>>(
     column: TColumn,
     value: ExtractColumnType<TTables, TColumn & string>,
   ): this;
-  // WHERE: 컬럼 - 사용: .where("u.id", ">", 10)
+  // WHERE: 컬럼 - 사용: .where("u.id", ">", 10), .where("u.id", "!=", null)
   where<TColumn extends AvailableColumns<TTables>>(
     column: TColumn,
     operator: ComparisonOperator | "like" | "not like",
     value: ExtractColumnType<TTables, TColumn & string>,
   ): this;
+  // WHERE: SQL 표현식 - 사용: .where(puri.raw("CONCAT(u.name, u.email)"), "like", "%test%")
+  where<TColumn extends Knex.Raw>(
+    column: TColumn,
+    operator: ComparisonOperator | "like" | "not like",
+    value: any,
+  ): this;
   // WHERE: 컬럼 - 사용: .where("u.id", "like", "%test%")
   where(...args: [columnOrConditions: any, operatorOrValue?: any, value?: any]): this {
     const [columnOrConditions, operatorOrValue, value] = args;
@@ -442,11 +500,17 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
 
   // 기본 쿼리 메서드들
   limit(count: number): this {
+    if (count < 0) {
+      throw new Error("Invalid limit: must be >= 0");
+    }
     this.knexQuery.limit(count);
     return this;
   }
 
   offset(count: number): this {
+    if (count < 0) {
+      throw new Error("Invalid offset: must be >= 0");
+    }
     this.knexQuery.offset(count);
     return this;
   }
@@ -534,7 +598,7 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
   }
 
   // Increment
-  increment<TColumn extends AvailableColumns<TTables>>(
+  increment<TColumn extends NumericColumns<TTables>>(
     column: TColumn,
     value: number,
   ): ResolvedPuri<number, SingleTableValue<TTables>> {
@@ -545,7 +609,7 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
     return new ResolvedPuri(this.knexQuery, this.knex);
   }
   // Decrement
-  decrement<TColumn extends AvailableColumns<TTables>>(
+  decrement<TColumn extends NumericColumns<TTables>>(
     column: TColumn,
     value: number,
   ): ResolvedPuri<number, SingleTableValue<TTables>> {
@@ -688,8 +752,12 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
     return indentedLines.join("\n").trim();
   }
 
+  raw(sql: string): Knex.Raw {
+    return this.knex.raw(sql);
+  }
+
   // Knex 쿼리 빌더 직접 접근
-  raw(): Knex.QueryBuilder {
+  rawQuery(): Knex.QueryBuilder {
     return this.knexQuery;
   }
 }
@@ -705,7 +773,7 @@ export class WhereGroup<TTables extends Record<string, any>> {
   ): this;
   where<TColumn extends AvailableColumns<TTables>>(
     column: TColumn,
-    operator: ComparisonOperator,
+    operator: WhereOperator,
     value: ExtractColumnType<TTables, TColumn & string>,
   ): this;
   where(...args: any[]): WhereGroup<TTables> {
@@ -721,7 +789,7 @@ export class WhereGroup<TTables extends Record<string, any>> {
   ): this;
   orWhere<TColumn extends AvailableColumns<TTables>>(
     column: TColumn,
-    operator: ComparisonOperator,
+    operator: WhereOperator,
     value: ExtractColumnType<TTables, TColumn & string>,
   ): this;
   orWhere(...args: any[]): WhereGroup<TTables> {
@@ -748,6 +816,7 @@ export class WhereGroup<TTables extends Record<string, any>> {
   }
 }
 
+// JOIN 절 그룹에는 Left와 Right에 대한 순서가 필요하지 않으므로, 모든 경우의 수를 계산해야함.
 export class JoinClauseGroup<
   TLeft extends Record<string, any>,
   TRight extends Record<string, any>,
@@ -756,14 +825,41 @@ export class JoinClauseGroup<
 
   // ON(AND): 컬럼 = 컬럼
   on(left: AvailableColumns<TLeft>, right: AvailableColumns<TRight>): this;
+  on(left: AvailableColumns<TRight>, right: AvailableColumns<TLeft>): this;
+  // ON(AND): 컬럼 = 값
+  on(
+    left: AvailableColumns<TLeft>,
+    right: ExtractColumnType<TLeft, AvailableColumns<TLeft> & string>,
+  ): this;
+  on(
+    left: AvailableColumns<TRight>,
+    right: ExtractColumnType<TRight, AvailableColumns<TRight> & string>,
+  ): this;
   // ON(AND): 컬럼 (연산자) 컬럼
   on(
     left: AvailableColumns<TLeft>,
     operator: ComparisonOperator,
     right: AvailableColumns<TRight>,
   ): this;
+  on(
+    left: AvailableColumns<TRight>,
+    operator: ComparisonOperator,
+    right: AvailableColumns<TLeft>,
+  ): this;
+  // ON(AND): 컬럼 (연산자) 값
+  on(
+    left: AvailableColumns<TLeft>,
+    operator: ComparisonOperator,
+    right: ExtractColumnType<TLeft, AvailableColumns<TLeft> & string>,
+  ): this;
+  on(
+    left: AvailableColumns<TRight>,
+    operator: ComparisonOperator,
+    right: ExtractColumnType<TRight, AvailableColumns<TRight> & string>,
+  ): this;
   // ON(AND): 콜백
   on(callback: (nested: JoinClauseGroup<TLeft, TRight>) => void): this;
+  on(callback: (nested: JoinClauseGroup<TRight, TLeft>) => void): this;
   // ON(AND) 구현
   on(...args: any[]): this {
     this.callback.on(...(args as [string, string]));
@@ -772,14 +868,41 @@ export class JoinClauseGroup<
 
   // ON(OR): 컬럼 = 컬럼
   orOn(left: AvailableColumns<TLeft>, right: AvailableColumns<TRight>): this;
+  orOn(left: AvailableColumns<TRight>, right: AvailableColumns<TLeft>): this;
+  // ON(OR): 컬럼 = 값
+  orOn(
+    left: AvailableColumns<TLeft>,
+    right: ExtractColumnType<TLeft, AvailableColumns<TLeft> & string>,
+  ): this;
+  orOn(
+    left: AvailableColumns<TRight>,
+    right: ExtractColumnType<TRight, AvailableColumns<TRight> & string>,
+  ): this;
   // ON(OR): 컬럼 (연산자) 컬럼
   orOn(
     left: AvailableColumns<TLeft>,
     operator: ComparisonOperator,
     right: AvailableColumns<TRight>,
   ): this;
+  orOn(
+    left: AvailableColumns<TRight>,
+    operator: ComparisonOperator,
+    right: AvailableColumns<TLeft>,
+  ): this;
+  // ON(OR): 컬럼 (연산자) 값
+  orOn(
+    left: AvailableColumns<TLeft>,
+    operator: ComparisonOperator,
+    right: ExtractColumnType<TLeft, AvailableColumns<TLeft> & string>,
+  ): this;
+  orOn(
+    left: AvailableColumns<TRight>,
+    operator: ComparisonOperator,
+    right: ExtractColumnType<TRight, AvailableColumns<TRight> & string>,
+  ): this;
   // ON(OR): 콜백
   orOn(callback: (nested: JoinClauseGroup<TLeft, TRight>) => void): this;
+  orOn(callback: (nested: JoinClauseGroup<TRight, TLeft>) => void): this;
   // ON(OR) 구현
   orOn(...args: any[]): this {
     this.callback.orOn(...(args as [string, string]));