sonamu 0.5.7 → 0.7.0

package/src/database/puri.ts

@@ -1,38 +1,38 @@
+/** biome-ignore-all lint/suspicious/noThenProperty: Puri는 thenable 인터페이스를 구현하고 있습니다. */
+/** biome-ignore-all lint/suspicious/noExplicitAny: Puri는 다양한 타입을 사용하고 있습니다. */
+
+import assert from "assert";
+import chalk from "chalk";
 import type { Knex } from "knex";
+import { Naite } from "../naite/naite";
 import type {
   AvailableColumns,
-  SelectObject,
-  ParseSelectObject,
-  WhereCondition,
+  ColumnKeys,
   ComparisonOperator,
-  ExtractColumnType,
-  SqlExpression,
   Expand,
+  ExtractColumnType,
   FulltextColumns,
-  ResultAvailableColumns,
   InsertData,
+  InsertResult,
+  OnConflictAction,
+  ParseSelectObject,
+  ResultAvailableColumns,
+  SelectObject,
   SingleTableValue,
+  SqlExpression,
+  WhereCondition,
 } from "./puri.types";
-import chalk from "chalk";
-import assert from "assert";
+import type { ClearStatements } from "./puri-subset.types";
 
-export class Puri<
-  TSchema,
-  TTables extends Record<string, any>,
-  TResult,
-  TResolved = Expand<TResult>[],
-> {
+export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
   private knexQuery: Knex.QueryBuilder;
 
   // 생성자 시그니처들
   constructor(knex: Knex, tableName: string);
+  constructor(knex: Knex, tableSpec: Record<string, string | Puri<TSchema, any, any>>);
   constructor(
-    knex: Knex,
-    tableSpec: Record<string, string | Puri<TSchema, any, any>>
-  );
-  constructor(
-    private knex: Knex,
-    tableNameOrSpec: any
+    public knex: Knex,
+    tableNameOrSpec: any,
   ) {
     if (typeof tableNameOrSpec === "string") {
       // Case: new Puri(knex, "users")
@@ -62,7 +62,7 @@ export class Puri<
     return {
       _type: "sql_expression",
       _return: "number",
-      _sql: `COUNT(${column})`,
+      _sql: `COUNT(${column})::integer`,
     };
   }
   static sum(column: string): SqlExpression<"number"> {
@@ -129,21 +129,16 @@ export class Puri<
     return { _type: "sql_expression", _return: "date", _sql: sql };
   }
 
-  // SELECT
+  // SELECT (overwrite)
   select<TSelect extends SelectObject<TTables>>(
-    selectObj: TSelect
+    selectObj: TSelect,
   ): Puri<TSchema, TTables, ParseSelectObject<TTables, TSelect>> {
     const selectClauses: (string | Knex.Raw)[] = [];
 
     for (const [alias, columnOrFunction] of Object.entries(selectObj)) {
-      if (
-        typeof columnOrFunction === "object" &&
-        columnOrFunction._type === "sql_expression"
-      ) {
+      if (typeof columnOrFunction === "object" && columnOrFunction._type === "sql_expression") {
         // SQL 함수인 경우
-        selectClauses.push(
-          this.knex.raw(`${columnOrFunction._sql} as ${alias}`)
-        );
+        selectClauses.push(this.knex.raw(`${columnOrFunction._sql} as ${alias}`));
       } else {
         // 일반 컬럼인 경우
         const columnPath = columnOrFunction as string;
@@ -161,17 +156,43 @@ export class Puri<
     return this as any;
   }
 
+  // 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;
+  }
+
   // SELECT *
   selectAll(): this {
     this.knexQuery.select("*");
     return this as any;
   }
 
+  // CLEAR
+  clear(statement: ClearStatements): this {
+    this.knexQuery.clear(statement);
+    return this;
+  }
+
+  // knex에 없어서 직접 구현함
+  clearJoin(alias: string): this {
+    (this.knexQuery as any)._statements = (this.knexQuery as any)._statements.filter((s: any) => {
+      if ("joinType" in s) {
+        const [_alias, _table] = Object.entries(s.table)[0];
+        return _alias !== alias;
+      } else {
+        return true;
+      }
+    });
+    return this;
+  }
+
   // JOIN: 서브쿼리 + Alias
   join<TJoinAlias extends string, TSubResult>(
     tableSpec: { [K in TJoinAlias]: Puri<TSchema, any, TSubResult> },
     left: AvailableColumns<TTables>,
-    right: `${TJoinAlias}.${keyof TSubResult & string}`
+    right: `${TJoinAlias}.${ColumnKeys<TSubResult>}`,
   ): Puri<
     TSchema,
     TTables & Record<TJoinAlias, TSubResult>, // 서브쿼리의 TResult
@@ -181,7 +202,7 @@ export class Puri<
   join<TJoinTable extends keyof TSchema, TJoinAlias extends string>(
     tableSpec: { [K in TJoinAlias]: TJoinTable },
     left: AvailableColumns<TTables>,
-    right: `${TJoinAlias}.${keyof TSchema[TJoinTable] & string}`
+    right: `${TJoinAlias}.${ColumnKeys<TSchema[TJoinTable]>}`,
   ): Puri<
     TSchema,
     TTables & Record<TJoinAlias, TSchema[TJoinTable]>, // TTables 확장!
@@ -191,7 +212,7 @@ export class Puri<
   join<TJoinTable extends keyof TSchema>(
     tableName: TJoinTable,
     left: AvailableColumns<TTables>,
-    right: `${TJoinTable & string}.${keyof TSchema[TJoinTable] & string}`
+    right: `${TJoinTable & string}.${ColumnKeys<TSchema[TJoinTable]>}`,
   ): Puri<
     TSchema,
     TTables & Record<TJoinTable, TSchema[TJoinTable]>, // 테이블명이 키
@@ -200,23 +221,17 @@ export class Puri<
   // JOIN: 서브쿼리 + Alias + 콜백
   join<TJoinAlias extends string, TSubResult>(
     tableSpec: { [K in TJoinAlias]: Puri<TSchema, any, TSubResult> },
-    callback: (
-      j: JoinClauseGroup<TTables, Record<TJoinAlias, TSubResult>>
-    ) => void
+    callback: (j: JoinClauseGroup<TTables, Record<TJoinAlias, TSubResult>>) => void,
   ): Puri<TSchema, TTables & Record<TJoinAlias, TSubResult>, TResult>;
   // JOIN: 테이블 + Alias + 콜백
   join<TJoinTable extends keyof TSchema, TJoinAlias extends string>(
     tableSpec: { [K in TJoinAlias]: TJoinTable },
-    callback: (
-      j: JoinClauseGroup<TTables, Record<TJoinAlias, TSchema[TJoinTable]>>
-    ) => void
+    callback: (j: JoinClauseGroup<TTables, Record<TJoinAlias, TSchema[TJoinTable]>>) => void,
   ): Puri<TSchema, TTables & Record<TJoinAlias, TSchema[TJoinTable]>, TResult>;
   // JOIN: 테이블명 + 콜백
   join<TJoinTable extends keyof TSchema>(
     tableName: TJoinTable,
-    callback: (
-      j: JoinClauseGroup<TTables, Record<TJoinTable, TSchema[TJoinTable]>>
-    ) => void
+    callback: (j: JoinClauseGroup<TTables, Record<TJoinTable, TSchema[TJoinTable]>>) => void,
   ): Puri<TSchema, TTables & Record<TJoinTable, TSchema[TJoinTable]>, TResult>;
   // JOIN 실제 구현
   join(tableNameOrSpec: any, ...args: any[]): any {
@@ -227,7 +242,7 @@ export class Puri<
   leftJoin<TJoinAlias extends string, TSubResult>(
     tableSpec: { [K in TJoinAlias]: Puri<TSchema, any, TSubResult> },
     left: AvailableColumns<TTables>,
-    right: `${TJoinAlias}.${keyof TSubResult & string}`
+    right: `${TJoinAlias}.${ColumnKeys<TSubResult>}`,
   ): Puri<
     TSchema,
     TTables & Record<TJoinAlias, TSubResult>, // 서브쿼리의 TResult
@@ -237,7 +252,7 @@ export class Puri<
   leftJoin<TJoinTable extends keyof TSchema, TJoinAlias extends string>(
     tableSpec: { [K in TJoinAlias]: TJoinTable },
     left: AvailableColumns<TTables>,
-    right: `${TJoinAlias}.${keyof TSchema[TJoinTable] & string}`
+    right: `${TJoinAlias}.${ColumnKeys<TSchema[TJoinTable]>}`,
   ): Puri<
     TSchema,
     TTables & Record<TJoinAlias, TSchema[TJoinTable]>, // TTables 확장!
@@ -247,7 +262,7 @@ export class Puri<
   leftJoin<TJoinTable extends keyof TSchema>(
     tableName: TJoinTable,
     left: AvailableColumns<TTables>,
-    right: `${TJoinTable & string}.${keyof TSchema[TJoinTable] & string}`
+    right: `${TJoinTable & string}.${ColumnKeys<TSchema[TJoinTable]>}`,
   ): Puri<
     TSchema,
     TTables & Record<TJoinTable, TSchema[TJoinTable]>, // 테이블명이 키
@@ -256,34 +271,24 @@ export class Puri<
   // LEFT JOIN: 서브쿼리 + Alias + 콜백
   leftJoin<TJoinAlias extends string, TSubResult>(
     tableSpec: { [K in TJoinAlias]: Puri<TSchema, any, TSubResult> },
-    callback: (
-      j: JoinClauseGroup<TTables, Record<TJoinAlias, TSubResult>>
-    ) => void
+    callback: (j: JoinClauseGroup<TTables, Record<TJoinAlias, TSubResult>>) => void,
   ): Puri<TSchema, TTables & Record<TJoinAlias, TSubResult>, 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
+    callback: (j: JoinClauseGroup<TTables, Record<TJoinAlias, TSchema[TJoinTable]>>) => void,
   ): Puri<TSchema, TTables & Record<TJoinAlias, TSchema[TJoinTable]>, TResult>;
   // LEFT JOIN: 테이블명 + 콜백
   leftJoin<TJoinTable extends keyof TSchema>(
     tableName: TJoinTable,
-    callback: (
-      j: JoinClauseGroup<TTables, Record<TJoinTable, TSchema[TJoinTable]>>
-    ) => void
+    callback: (j: JoinClauseGroup<TTables, Record<TJoinTable, TSchema[TJoinTable]>>) => void,
   ): Puri<TSchema, TTables & Record<TJoinTable, TSchema[TJoinTable]>, TResult>;
   // LEFT JOIN 실제 구현
   leftJoin(tableNameOrSpec: any, ...args: any[]): any {
     return this.__commonJoin("leftJoin", tableNameOrSpec, ...args);
   }
 
-  __commonJoin(
-    joinType: "join" | "leftJoin",
-    tableNameOrSpec: any,
-    ...args: any[]
-  ): this {
+  __commonJoin(joinType: "join" | "leftJoin", tableNameOrSpec: any, ...args: any[]): this {
     if (typeof tableNameOrSpec === "string") {
       // Case 1: join("posts", ...)
       const tableName = tableNameOrSpec;
@@ -349,25 +354,26 @@ export class Puri<
   // WHERE: 컬럼 - 사용: .where("u.id", 1)
   where<TColumn extends AvailableColumns<TTables>>(
     column: TColumn,
-    value: ExtractColumnType<TTables, TColumn & string>
+    value: ExtractColumnType<TTables, TColumn & string>,
   ): this;
   // WHERE: 컬럼 - 사용: .where("u.id", ">", 10)
   where<TColumn extends AvailableColumns<TTables>>(
     column: TColumn,
-    operator: ComparisonOperator,
-    value: ExtractColumnType<TTables, TColumn & string>
+    operator: ComparisonOperator | "like" | "not like",
+    value: ExtractColumnType<TTables, TColumn & string>,
   ): this;
   // WHERE: 컬럼 - 사용: .where("u.id", "like", "%test%")
-  where(columnOrConditions: any, operatorOrValue?: any, value?: any): this {
+  where(...args: [columnOrConditions: any, operatorOrValue?: any, value?: any]): this {
+    const [columnOrConditions, operatorOrValue, value] = args;
     if (typeof columnOrConditions === "object") {
       this.knexQuery.where(columnOrConditions);
-    } else if (arguments.length === 2) {
+    } else if (typeof value === "undefined") {
       if (operatorOrValue === null) {
         this.knexQuery.whereNull(columnOrConditions);
         return this;
       }
       this.knexQuery.where(columnOrConditions, operatorOrValue);
-    } else if (arguments.length === 3) {
+    } else if (typeof value !== "undefined") {
       if (value === null) {
         if (operatorOrValue === "!=") {
           this.knexQuery.whereNotNull(columnOrConditions);
@@ -387,7 +393,7 @@ export class Puri<
   // WHERE IN
   whereIn<TColumn extends AvailableColumns<TTables>>(
     column: TColumn,
-    values: ExtractColumnType<TTables, TColumn & string>[]
+    values: ExtractColumnType<TTables, TColumn & string>[],
   ): Puri<TSchema, TTables, TResult> {
     this.knexQuery.whereIn(column, values);
     return this as any;
@@ -396,17 +402,14 @@ export class Puri<
   // WHERE NOT IN
   whereNotIn<TColumn extends AvailableColumns<TTables>>(
     column: TColumn,
-    values: ExtractColumnType<TTables, TColumn & string>[]
+    values: ExtractColumnType<TTables, TColumn & string>[],
   ): Puri<TSchema, TTables, TResult> {
-    this.knexQuery.whereIn(column, values);
+    this.knexQuery.whereNotIn(column, values);
     return this as any;
   }
 
   // WHERE MATCH
-  whereMatch<TColumn extends FulltextColumns<TTables>>(
-    column: TColumn,
-    value: string
-  ): this {
+  whereMatch<TColumn extends FulltextColumns<TTables>>(column: TColumn, value: string): this {
     this.knexQuery.whereRaw(`MATCH (${String(column)}) AGAINST (?)`, [value]);
     return this;
   }
@@ -430,7 +433,7 @@ export class Puri<
   // ORDER BY
   orderBy<TColumn extends ResultAvailableColumns<TTables, TResult>>(
     column: TColumn,
-    direction: "asc" | "desc"
+    direction: "asc" | "desc",
   ): this;
   orderBy(column: string, direction: "asc" | "desc" = "asc"): this {
     this.knexQuery.orderBy(column, direction);
@@ -449,9 +452,7 @@ export class Puri<
   }
 
   // GROUP BY
-  groupBy<TColumns extends ResultAvailableColumns<TTables, TResult>>(
-    ...columns: TColumns[]
-  ): this;
+  groupBy<TColumns extends ResultAvailableColumns<TTables, TResult>>(...columns: TColumns[]): this;
   groupBy(...columns: string[]): this {
     this.knexQuery.groupBy(...(columns as string[]));
     return this;
@@ -462,16 +463,20 @@ export class Puri<
   having<TColumn extends ResultAvailableColumns<TTables, TResult>>(
     column: TColumn,
     operator: ComparisonOperator,
-    value: any
+    value: any,
   ): this;
   // HAVING 구현
   having(...conditions: any[]): this {
     if (conditions.length === 1) {
       // having("COUNT(*) > 10")
-      this.knexQuery.having(conditions[0]);
+      this.knexQuery.having(this.knex.raw(conditions[0]));
     } else if (conditions.length === 3) {
       // having("count", ">", 10)
-      this.knexQuery.having(conditions[0], conditions[1], conditions[2]);
+      this.knexQuery.having(
+        this.knex.raw(conditions[0]),
+        conditions[1],
+        this.knex.raw(conditions[2]),
+      );
     } else {
       throw new Error("Invalid having arguments");
     }
@@ -479,101 +484,82 @@ export class Puri<
   }
 
   // 실행 메서드들 - thenable 구현
-  then<TResult1 = TResolved, TResult2 = never>(
-    onfulfilled?:
-      | ((value: TResolved) => TResult1 | PromiseLike<TResult1>)
-      | null,
-    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
+  then<TResult1 = Expand<TResult>[], TResult2 = never>(
+    onfulfilled?: ((value: Expand<TResult>[]) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
   ): Promise<TResult1 | TResult2> {
+    Naite.t("puri:executed-query", this.toQuery());
     return this.knexQuery.then(onfulfilled as any, onrejected);
   }
   catch<TResult2 = never>(
-    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
-  ): Promise<Expand<TResult> | TResult2> {
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
+  ): Promise<TResult | TResult2> {
     return this.knexQuery.catch(onrejected);
   }
-  finally(onfinally?: (() => void) | null): Promise<Expand<TResult>> {
+  finally(onfinally?: (() => void) | null): Promise<TResult> {
     return this.knexQuery.finally(onfinally);
   }
 
   // 하나만 쿼리
-  async first(): Promise<Expand<TResult> | undefined> {
-    return this.knexQuery.first();
-  }
-  // 하나만 쿼리 실패 시 에러
-  async firstOrFail(): Promise<TResult> {
-    const result = await this.knexQuery.first();
-    if (!result) {
-      throw new Error("No results found");
-    }
-    return result;
-  }
-
-  // 쿼리 후 인덱스 리턴
-  async at(index: number): Promise<Expand<TResult> | undefined> {
-    const results = (await this) as any[];
-    return results[index];
-  }
-  // 쿼리 후 인덱스 리턴 실패 시 에러
-  async assertAt(index: number): Promise<Expand<TResult>> {
-    const results = (await this) as any[];
-    const result = results[index];
-    if (result === undefined) {
-      throw new Error(`No result found at index ${index}`);
-    }
-    return result;
+  first(): ResolvedPuri<Expand<TResult>, never> {
+    this.knexQuery.first();
+    return new ResolvedPuri(this.knexQuery, this.knex);
   }
 
   // 쿼리한 레코드에서 특정 컬럼만 추출한 배열 리턴
-  async pluck<TColumn extends ResultAvailableColumns<TTables, TResult>>(
-    column: TColumn
-  ): Promise<ExtractColumnType<TTables, TColumn & string>[]> {
-    return this.knexQuery.pluck(column) as Promise<
-      ExtractColumnType<TTables, TColumn & string>[]
-    >;
+  pluck<TColumn extends keyof TResult | ResultAvailableColumns<TTables, TResult>>(
+    column: TColumn,
+  ): ResolvedPuri<
+    TColumn extends keyof TResult
+      ? TResult[TColumn][]
+      : ExtractColumnType<TTables, TColumn & string>[],
+    never
+  > {
+    this.knexQuery.pluck(column as string);
+    return new ResolvedPuri(this.knexQuery, this.knex);
   }
 
   // INSERT
   insert(
-    data: InsertData<SingleTableValue<TTables>>
-  ): Puri<TSchema, {}, number, number[]> {
+    data: InsertData<SingleTableValue<TTables>>,
+  ): ResolvedPuri<InsertResult, SingleTableValue<TTables>> {
     this.knexQuery.insert(data);
-    return this as any;
+    return new ResolvedPuri(this.knexQuery, this.knex);
   }
 
   // UPDATE
-  update(data: WhereCondition<TTables>): Puri<TSchema, {}, number, number> {
+  update(data: WhereCondition<TTables>): ResolvedPuri<number, SingleTableValue<TTables>> {
     this.knexQuery.update(data);
-    return this as any;
+    return new ResolvedPuri(this.knexQuery, this.knex);
   }
 
   // Increment
   increment<TColumn extends AvailableColumns<TTables>>(
     column: TColumn,
-    value: number
-  ): this {
+    value: number,
+  ): ResolvedPuri<number, SingleTableValue<TTables>> {
     if (value <= 0) {
       throw new Error("Increment value must be greater than 0");
     }
     this.knexQuery.increment(column, value);
-    return this;
+    return new ResolvedPuri(this.knexQuery, this.knex);
   }
   // Decrement
   decrement<TColumn extends AvailableColumns<TTables>>(
     column: TColumn,
-    value: number
-  ): this {
+    value: number,
+  ): ResolvedPuri<number, SingleTableValue<TTables>> {
     if (value <= 0) {
       throw new Error("Decrement value must be greater than 0");
     }
     this.knexQuery.decrement(column, value);
-    return this;
+    return new ResolvedPuri(this.knexQuery, this.knex);
   }
 
   // DELETE
-  delete(): Puri<TSchema, {}, number, number> {
+  delete(): ResolvedPuri<number, SingleTableValue<TTables>> {
     this.knexQuery.delete();
-    return this as any;
+    return new ResolvedPuri(this.knexQuery, this.knex);
   }
 
   // 확인 쿼리 리턴
@@ -583,12 +569,17 @@ export class Puri<
 
   // 쿼리 디버깅 로그 출력
   debug(): this {
-    console.log(
-      `${chalk.cyan("[Puri Debug]")} ${chalk.yellow(this.toQuery())}`
-    );
+    console.log(`${chalk.cyan("[Puri Debug]")} ${chalk.yellow(this.toQuery())}`);
     return this;
   }
 
+  clone(): Puri<TSchema, TTables, TResult> {
+    // 'dual'은 더미 테이블이며, 바로 아래 줄에서 knexQuery가 덮어씌워집니다.
+    const newPuri = new Puri<TSchema, TTables, TResult>(this.knex, "dual");
+    newPuri.knexQuery = this.knexQuery.clone();
+    return newPuri;
+  }
+
   formatSQL(unformatted: string): string {
     // SQL 예약어 목록
     const keywords = [
@@ -662,10 +653,7 @@ export class Puri<
     });
 
     // JOIN 절 처리
-    formatted = formatted.replace(
-      /\s+((?:INNER|LEFT|RIGHT|FULL OUTER)\s+)?JOIN\s+/gi,
-      "\n$1JOIN "
-    );
+    formatted = formatted.replace(/\s+((?:INNER|LEFT|RIGHT|FULL OUTER)\s+)?JOIN\s+/gi, "\n$1JOIN ");
 
     // AND, OR 조건 처리
     formatted = formatted.replace(/\s+(AND|OR)\s+/gi, "\n  $1 ");
@@ -675,7 +663,7 @@ export class Puri<
     const indentedLines = [];
     let indentLevel = 0;
 
-    for (let line of lines) {
+    for (const line of lines) {
       const trimmedLine = line.trim();
       if (!trimmedLine) continue;
 
@@ -713,12 +701,12 @@ export class WhereGroup<TTables extends Record<string, any>> {
   where(conditions: WhereCondition<TTables>): this;
   where<TColumn extends AvailableColumns<TTables>>(
     column: TColumn,
-    value: ExtractColumnType<TTables, TColumn & string>
+    value: ExtractColumnType<TTables, TColumn & string>,
   ): this;
   where<TColumn extends AvailableColumns<TTables>>(
     column: TColumn,
     operator: ComparisonOperator,
-    value: ExtractColumnType<TTables, TColumn & string>
+    value: ExtractColumnType<TTables, TColumn & string>,
   ): this;
   where(...args: any[]): WhereGroup<TTables> {
     this.builder.where(args[0], ...args.slice(1));
@@ -729,12 +717,12 @@ export class WhereGroup<TTables extends Record<string, any>> {
   orWhere(conditions: WhereCondition<TTables>): this;
   orWhere<TColumn extends AvailableColumns<TTables>>(
     column: TColumn,
-    value: ExtractColumnType<TTables, TColumn & string>
+    value: ExtractColumnType<TTables, TColumn & string>,
   ): this;
   orWhere<TColumn extends AvailableColumns<TTables>>(
     column: TColumn,
     operator: ComparisonOperator,
-    value: ExtractColumnType<TTables, TColumn & string>
+    value: ExtractColumnType<TTables, TColumn & string>,
   ): this;
   orWhere(...args: any[]): WhereGroup<TTables> {
     this.builder.orWhere(args[0], ...args.slice(1));
@@ -751,9 +739,7 @@ export class WhereGroup<TTables extends Record<string, any>> {
     return this;
   }
   orWhereGroup(callback: (g: WhereGroup<TTables>) => void): this;
-  orWhereGroup(
-    callback: (g: WhereGroup<TTables>) => void
-  ): WhereGroup<TTables> {
+  orWhereGroup(callback: (g: WhereGroup<TTables>) => void): WhereGroup<TTables> {
     this.builder.orWhere((subBuilder) => {
       const subGroup = new WhereGroup<TTables>(subBuilder);
       callback(subGroup);
@@ -774,7 +760,7 @@ export class JoinClauseGroup<
   on(
     left: AvailableColumns<TLeft>,
     operator: ComparisonOperator,
-    right: AvailableColumns<TRight>
+    right: AvailableColumns<TRight>,
   ): this;
   // ON(AND): 콜백
   on(callback: (nested: JoinClauseGroup<TLeft, TRight>) => void): this;
@@ -790,7 +776,7 @@ export class JoinClauseGroup<
   orOn(
     left: AvailableColumns<TLeft>,
     operator: ComparisonOperator,
-    right: AvailableColumns<TRight>
+    right: AvailableColumns<TRight>,
   ): this;
   // ON(OR): 콜백
   orOn(callback: (nested: JoinClauseGroup<TLeft, TRight>) => void): this;
@@ -800,3 +786,98 @@ export class JoinClauseGroup<
     return this;
   }
 }
+
+/*
+  TResolved: 쿼리 실행 후 반환될 결과 타입
+  TReturning: RETURNING 절에 사용될 타입
+*/
+export class ResolvedPuri<TResolved, TReturning> {
+  constructor(
+    public knexQuery: Knex.QueryBuilder,
+    private knex: Knex,
+  ) {}
+
+  toQuery(): string {
+    return this.knexQuery.toQuery();
+  }
+
+  debug(): this {
+    console.log(`${chalk.cyan("[Puri Debug]")} ${chalk.yellow(this.toQuery())}`);
+    return this;
+  }
+
+  then<TResult1 = TResolved, TResult2 = never>(
+    onfulfilled?: ((value: TResolved) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
+  ): Promise<TResult1 | TResult2> {
+    Naite.t("puri:executed-query", this.toQuery());
+    return this.knexQuery.then(onfulfilled as any, onrejected);
+  }
+  catch<TResult2 = never>(
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
+  ): Promise<TResolved | TResult2> {
+    return this.knexQuery.catch(onrejected);
+  }
+  finally(onfinally?: (() => void) | null): Promise<TResolved> {
+    return this.knexQuery.finally(onfinally);
+  }
+
+  // ON CONFLICT - 컬럼 기반
+  onConflict<TTables extends Record<string, TReturning>>(
+    columns: string | string[],
+    action?: OnConflictAction<TTables>,
+  ): this {
+    const target = Array.isArray(columns) ? columns : [columns];
+
+    if (!action || action === "nothing") {
+      // DO NOTHING
+      this.knexQuery.onConflict(target).ignore();
+    } else {
+      // DO UPDATE
+      const { update } = action;
+
+      // action.update 배열 형태 : ["name", "email"]
+      if (Array.isArray(update)) {
+        this.knexQuery.onConflict(target).merge(update);
+      } else {
+        // action.update 객체 형태: { name: "John", count: raw(...) }
+        const mergeObj: Record<string, any> = {};
+
+        for (const [key, value] of Object.entries(update)) {
+          if (
+            value &&
+            typeof value === "object" &&
+            "_type" in value &&
+            value._type === "sql_expression"
+          ) {
+            // SqlExpression → knex.raw()로 변환
+            mergeObj[key] = this.knex.raw((value as SqlExpression<any>)._sql);
+          } else {
+            // 일반 값
+            mergeObj[key] = value;
+          }
+        }
+
+        this.knexQuery.onConflict(target).merge(mergeObj);
+      }
+    }
+
+    return this;
+  }
+
+  // RETURNING: "*" - 전체 컬럼
+  returning(column: "*"): ResolvedPuri<TReturning[], never>;
+  // RETURNING: 단일 컬럼
+  returning<TColumn extends ColumnKeys<TReturning>>(
+    column: TColumn,
+  ): ResolvedPuri<Pick<TReturning, TColumn>[], never>;
+  // RETURNING: 복수 컬럼 (배열)
+  returning<TColumn extends ColumnKeys<TReturning>>(
+    columns: TColumn[],
+  ): ResolvedPuri<Pick<TReturning, TColumn>[], never>;
+  // RETURNING 구현
+  returning(columnOrColumns: string | string[]): ResolvedPuri<any[], never> {
+    this.knexQuery.returning(columnOrColumns);
+    return new ResolvedPuri(this.knexQuery, this.knex);
+  }
+}