sonamu 0.13.2 → 0.13.3

package/src/api/sonamu.ts

@@ -411,6 +411,12 @@ class SonamuClass {
     const { EntityManager } = await import("../entity/entity-manager");
     await EntityManager.autoload(doSilent);
 
+    // 테스트와 CLI에서도 URL 생성에 쓰며, 드라이버는 use() 시점까지 생성하지 않는다.
+    if (this.config.server.storage) {
+      const { StorageManager } = await import("../storage/storage-manager");
+      this.storageValue = new StorageManager(this.config.server.storage);
+    }
+
     // Cache 초기화
     await this.initializeCache(this.config.server.cache, forTesting);
 
@@ -490,12 +496,6 @@ class SonamuClass {
     this.server = server;
     this.websocketRuntime = new WebSocketRuntime(options.websocket);
 
-    // Storage 설정 → StorageManager 생성
-    if (options.storage) {
-      const { StorageManager } = await import("../storage/storage-manager");
-      this.storageValue = new StorageManager(options.storage);
-    }
-
     // 플러그인 등록
     if (options.plugins) {
       await this.registerPlugins(server, options.plugins);

package/src/database/__tests__/puri-hydration.test.ts

@@ -0,0 +1,226 @@
+import { knex, type Knex } from "knex";
+import { afterAll, describe, expect, it, vi } from "vitest";
+
+import { Puri } from "../puri";
+
+type Schema = { users: { id: number; name: string; nickname: string | null; payload: object } };
+const db = knex({ client: "pg" });
+const query = () => new Puri<Schema, Schema, Schema["users"]>(db, "users");
+
+type RawRow = { [column: string]: string | number | boolean | null | RawRow[] };
+
+function result(
+  builder: Knex.QueryBuilder,
+  rows: RawRow | RawRow[] | undefined,
+  presence: Record<string, readonly boolean[]> = {},
+) {
+  if (vi.isMockFunction(builder.clone)) builder.clone.mockRestore();
+  const clone = builder.clone.bind(builder);
+  vi.spyOn(builder, "clone").mockImplementation(() => {
+    const cloned = clone();
+    result(cloned, rows, presence);
+    return cloned;
+  });
+  vi.spyOn(builder, "then").mockImplementation((fulfilled, rejected) => {
+    const markers = [
+      ...builder.toQuery().matchAll(/"([^"]+)"\.\* IS DISTINCT FROM NULL AS "([^"]+)"/g),
+    ];
+    const withPresence = (row: RawRow, index: number) => ({
+      ...row,
+      ...Object.fromEntries(
+        markers.map(([, alias, column]) => [column, presence[alias]?.[index] ?? true]),
+      ),
+    });
+    const output = Array.isArray(rows)
+      ? rows.map(withPresence)
+      : rows
+        ? withPresence(rows, 0)
+        : rows;
+    return Promise.resolve(output).then(fulfilled, rejected);
+  });
+}
+
+afterAll(() => db.destroy());
+
+describe("Puri 중첩 select 결과", () => {
+  it("중첩 select 별칭만 복원하고 평평한 별칭과 JSON 값은 보존한다", async () => {
+    const selected = query().select({
+      user: { id: "users.id", data: "users.payload" },
+      literal__name: "users.name",
+      payload: "users.payload",
+    });
+    const payload = [{ arbitrary__key: "원본" }];
+    result(selected.rawQuery(), [
+      { user__id: 1, user__data: payload, literal__name: "이름", payload },
+    ]);
+    const rows = await selected;
+    expect(rows).toEqual([{ user: { id: 1, data: payload }, literal__name: "이름", payload }]);
+    expect(rows[0]?.user.data).toBe(payload);
+  });
+
+  it("중첩 select의 빈 JSON 배열을 관계 없음으로 바꾸지 않는다", async () => {
+    const selected = query().select({ user: { data: "users.payload" } });
+    result(selected.rawQuery(), [{ user__data: [] }]);
+    expect(await selected).toEqual([{ user: { data: [] } }]);
+  });
+
+  it("중첩 단계마다 null 관계를 복원하고 id가 없는 그룹도 처리한다", async () => {
+    const selected = query()
+      .leftJoin({ user: "users" }, (join) => join.on("users.id", "user.id"))
+      .leftJoin({ user__detail: "users" }, (join) => join.on("users.id", "user__detail.id"))
+      .select({ user: { id: "user.id", detail: { name: "user__detail.name" } } });
+    result(
+      selected.rawQuery(),
+      [
+        { user__id: 1, user__detail__name: null },
+        { user__id: null, user__detail__name: "무시할 값" },
+      ],
+      { user: [true, false], user__detail: [false, true] },
+    );
+    expect(await selected).toEqual([{ user: { id: 1, detail: null } }, { user: null }]);
+  });
+
+  it("nullable 필드만 선택한 일반 그룹은 null로 축약하지 않는다", async () => {
+    const selected = query().select({ profile: { nickname: "users.nickname" } });
+    result(selected.rawQuery(), [{ profile__nickname: null }]);
+    expect(await selected).toEqual([{ profile: { nickname: null } }]);
+  });
+
+  it("LEFT JOIN 별칭과 다른 이름으로 묶은 그룹은 객체로 유지한다", async () => {
+    const selected = query()
+      .leftJoin({ colleague: "users" }, (join) => join.on("users.id", "colleague.id"))
+      .select({
+        profile: { nickname: "colleague.nickname" },
+        colleague: { nickname: "colleague.nickname" },
+      });
+    result(selected.rawQuery(), [{ profile__nickname: null, colleague__nickname: null }], {
+      colleague: [false],
+    });
+    expect(await selected).toEqual([{ profile: { nickname: null }, colleague: null }]);
+  });
+
+  it("INNER JOIN 별칭과 같은 그룹도 nullable 필드를 보존한다", async () => {
+    const selected = query()
+      .join({ colleague: "users" }, "users.id", "colleague.id")
+      .select({ colleague: { nickname: "colleague.nickname" } });
+    result(selected.rawQuery(), [{ colleague__nickname: null }]);
+    expect(await selected).toEqual([{ colleague: { nickname: null } }]);
+  });
+
+  it("선택한 값이 모두 null이어도 실제 LEFT JOIN 행이 있으면 객체를 유지한다", async () => {
+    const selected = query()
+      .leftJoin({ colleague: "users" }, (join) => join.on("users.id", "colleague.id"))
+      .select({ colleague: { nickname: "colleague.nickname" } });
+    result(selected.rawQuery(), [{ colleague__nickname: null }, { colleague__nickname: null }], {
+      colleague: [true, false],
+    });
+    expect(await selected).toEqual([{ colleague: { nickname: null } }, { colleague: null }]);
+    expect(selected.toQuery()).not.toContain("__sonamu_presence_");
+    expect(await selected.rawQuery()).toEqual([
+      { colleague__nickname: null },
+      { colleague__nickname: null },
+    ]);
+  });
+
+  it("그룹화한 no-id projection은 SQL 열을 추가하지 않고 객체를 유지한다", async () => {
+    const selected = query()
+      .leftJoin({ colleague: "users" }, (join) => join.on("users.id", "colleague.id"))
+      .select({ colleague: { nickname: "colleague.nickname" } })
+      .groupBy("colleague.nickname");
+    result(selected.rawQuery(), [{ colleague__nickname: null }], { colleague: [false] });
+    expect(await selected).toEqual([{ colleague: { nickname: null } }]);
+  });
+
+  it.each([false, true])(
+    "다른 이름의 관계 그룹도 id 원본 LEFT JOIN을 따른다 (원시 표현식: %s)",
+    async (raw) => {
+      const selected = query()
+        .leftJoin({ staffs: "users" }, (join) => join.on("users.id", "staffs.id"))
+        .select({ manager: { id: "staffs.id", name: "staffs.name" } });
+      if (raw) selected.appendSelect({ total: Puri.rawNumber("(SELECT COUNT(*) FROM users)") });
+      result(
+        selected.rawQuery(),
+        [
+          { manager__id: 1, manager__name: "담당자" },
+          { manager__id: null, manager__name: null },
+        ],
+        { staffs: [true, false] },
+      );
+      expect(await selected.clone()).toEqual([
+        { manager: { id: 1, name: "담당자" } },
+        { manager: null },
+      ]);
+    },
+  );
+
+  it("관계 id 선택을 clear한 뒤 일반 nullable id 그룹을 선택하면 관계 의미도 지운다", async () => {
+    const selected = query()
+      .leftJoin({ staffs: "users" }, (join) => join.on("users.id", "staffs.id"))
+      .select({ manager: { id: "staffs.id" } })
+      .clear("select")
+      .select({ manager: { id: "users.nickname" } });
+    result(selected.rawQuery(), [{ manager__id: null }]);
+    expect(await selected).toEqual([{ manager: { id: null } }]);
+  });
+
+  it("객체 키 안의 구분자는 중첩 경로로 다시 해석하지 않는다", async () => {
+    const selected = query().select({ user__profile: { display__name: "users.name" } });
+    result(selected.rawQuery(), [{ user__profile__display__name: "이름" }]);
+    expect(await selected).toEqual([{ user__profile: { display__name: "이름" } }]);
+  });
+
+  it.each(["then", "catch", "finally"] as const)(
+    "%s 실행에서도 중첩 결과를 반환한다",
+    async (method) => {
+      const selected = query().select({ user: { id: "users.id" } });
+      result(selected.rawQuery(), [{ user__id: 1 }]);
+      const rows =
+        method === "then"
+          ? await selected.then()
+          : method === "catch"
+            ? await selected.catch()
+            : await selected.finally();
+      expect(rows).toEqual([{ user: { id: 1 } }]);
+    },
+  );
+
+  it.each(["then", "catch", "finally"] as const)(
+    "first의 %s 실행과 조회 결과 없음도 처리한다",
+    async (method) => {
+      const selected = query()
+        .select({ user: { id: "users.id" } })
+        .first();
+      result(selected.knexQuery, { user__id: 1 });
+      const row =
+        method === "then"
+          ? await selected.then()
+          : method === "catch"
+            ? await selected.catch()
+            : await selected.finally();
+      expect(row).toEqual({ user: { id: 1 } });
+      result(selected.knexQuery, undefined);
+      expect(await selected).toBeUndefined();
+    },
+  );
+
+  it.each(["select", "columns"] as const)(
+    "clone과 appendSelect는 중첩 경로를 보존하고 clear(%s)는 복제본에만 적용된다",
+    async (statement) => {
+      const original = query().select({ user: { id: "users.id" } });
+      const cloned = original.clone().appendSelect({ detail: { name: "users.name" } });
+      result(cloned.rawQuery(), [{ user__id: 1, detail__name: "이름" }]);
+      expect(await cloned).toEqual([{ user: { id: 1 }, detail: { name: "이름" } }]);
+      cloned.clear(statement).select({ user__id: "users.id" });
+      result(cloned.rawQuery(), [{ user__id: 2 }]);
+      expect(await cloned).toEqual([{ user__id: 2 }]);
+      result(original.rawQuery(), [{ user__id: 1 }]);
+      expect(await original).toEqual([{ user: { id: 1 } }]);
+    },
+  );
+
+  it("rawQuery는 기존의 평평한 SQL 결과를 그대로 반환한다", async () => {
+    const selected = query().select({ user: { id: "users.id" } });
+    result(selected.rawQuery(), [{ user__id: 1 }]);
+    expect(await selected.rawQuery()).toEqual([{ user__id: 1 }]);
+  });
+});

package/src/database/base-model.ts

@@ -9,6 +9,7 @@ import { EntityManager } from "../entity/entity-manager";
 import { type FilterOperator, type FilterQuery } from "../filter/types";
 import { normalizeFilterQuery, validateSonamuFilters } from "../filter/utils";
 import { convertDomainToCategory } from "../logger/category";
+import { Naite } from "../naite/naite";
 import { type DatabaseSchemaExtend, type SonamuQueryMode } from "../types/types";
 import { type ListResult } from "../utils/model";
 import { isObjectValue } from "../utils/runtime-value";
@@ -517,7 +518,9 @@ export class BaseModelClass<
         return qb.limit(num).offset(num * (page - 1));
       }
     })();
-    let unloadedRows = await limitedQb;
+    // 로더는 평평한 refId 별칭을 사용하므로 로딩을 마친 뒤 hydrate합니다.
+    Naite.t("puri:executed-query", limitedQb.toQuery());
+    let unloadedRows = await limitedQb.rawQuery();
 
     if (debug) {
       qb.debug();
@@ -554,8 +557,9 @@ export class BaseModelClass<
         resolveLoaderQb.debug();
       }
 
-      // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
-      let loadedRows = (await resolveLoaderQb) as any[];
+      Naite.t("puri:executed-query", resolveLoaderQb.toQuery());
+      // SAFETY: 로더의 select 쿼리는 평평한 레코드 배열을 반환합니다.
+      let loadedRows = (await resolveLoaderQb.rawQuery()) as any[];
 
       // 중첩 loaders가 있으면 재귀 처리
       if (nestedLoaders && nestedLoaders.length > 0) {

package/src/database/puri.ts

@@ -1,6 +1,8 @@
 /* oxlint-disable @typescript-eslint/no-explicit-any */ // Puri는 다양한 타입을 사용하고 있습니다.
 
 import assert from "assert";
+import { randomUUID } from "node:crypto";
+import { type EventEmitter } from "node:events";
 
 import chalk from "chalk";
 import inflection from "inflection";
@@ -182,9 +184,108 @@ function isNestedSelectObject<TTables extends object>(
   return isObjectValue(value) && !("_type" in value);
 }
 
+type SelectProjection = Map<string, string | SelectProjection>;
+type SelectResultValue =
+  | string
+  | number
+  | boolean
+  | bigint
+  | Date
+  | Buffer
+  | null
+  | undefined
+  | SelectRow
+  | SelectResultValue[];
+type SelectRow = { [column: string]: SelectResultValue };
+type SelectResult = SelectRow | SelectRow[] | undefined;
+
+function getSelectRelationAlias(
+  path: string,
+  correlations: ReadonlyMap<string, CorrelationRegistration>,
+  identitySources: ReadonlyMap<string, string>,
+): string | undefined {
+  const identityAlias = identitySources.get(`${path}__id`);
+  const identityRelation =
+    identityAlias === undefined ? undefined : correlations.get(identityAlias);
+  if (identityRelation?.kind === "join" && identityRelation.joinType === "leftJoin")
+    return identityAlias;
+  const relation = correlations.get(path);
+  return relation?.kind === "join" && relation.joinType === "leftJoin" ? path : undefined;
+}
+
+function hydrateSelectResult(
+  result: SelectResult,
+  paths: ReadonlyMap<string, readonly string[]>,
+  correlations: ReadonlyMap<string, CorrelationRegistration>,
+  presenceColumns: ReadonlyMap<string, string>,
+  identitySources: ReadonlyMap<string, string>,
+): SelectResult {
+  if (paths.size === 0 || result === undefined) return result;
+
+  const hiddenColumns = new Set(presenceColumns.values());
+  const projection: SelectProjection = new Map();
+  for (const [alias, path] of paths) {
+    let parent = projection;
+    for (const key of path.slice(0, -1)) {
+      let child = parent.get(key);
+      if (!(child instanceof Map)) {
+        child = new Map();
+        parent.set(key, child);
+      }
+      parent = child;
+    }
+    const leaf = path[path.length - 1];
+    assert(leaf !== undefined);
+    parent.set(leaf, alias);
+  }
+
+  const hydrateRow = (row: SelectRow) => {
+    const project = (fields: SelectProjection, path: readonly string[]): SelectRow | null => {
+      const entries: [string, SelectResultValue][] = [];
+      for (const [key, field] of fields) {
+        if (field instanceof Map) {
+          entries.push([key, project(field, [...path, key])]);
+        } else if (Object.hasOwn(row, field)) {
+          entries.push([key, row[field]]);
+        }
+      }
+      const value = Object.fromEntries(entries);
+      // 그룹 이름이 달라도 명시한 id의 LEFT JOIN 원본으로 관계 존재 여부를 판단합니다.
+      const relationAlias = getSelectRelationAlias(path.join("__"), correlations, identitySources);
+      const presenceColumn =
+        relationAlias === undefined ? undefined : presenceColumns.get(relationAlias);
+      if (
+        relationAlias !== undefined &&
+        (presenceColumn !== undefined
+          ? row[presenceColumn] === false
+          : Object.hasOwn(value, "id") && value.id === null)
+      ) {
+        return null;
+      }
+      return value;
+    };
+    return {
+      ...Object.fromEntries(
+        Object.entries(row).filter(([key]) => !paths.has(key) && !hiddenColumns.has(key)),
+      ),
+      ...Object.fromEntries(
+        [...projection].map(([key, fields]) => {
+          assert(fields instanceof Map);
+          return [key, project(fields, [key])];
+        }),
+      ),
+    };
+  };
+
+  // JSON 내부와 직접 지정한 __ 별칭은 중첩 select의 경로가 아니므로 탐색하지 않습니다.
+  return Array.isArray(result) ? result.map(hydrateRow) : hydrateRow(result);
+}
+
 export class Puri<TSchema, TTables extends object, TResult> {
   private knexQuery: Knex.QueryBuilder;
   private tableSpec: TableSpec | null = null;
+  private nestedSelectPaths = new Map<string, readonly string[]>();
+  private nestedSelectIdentitySources = new Map<string, string>();
   private correlationRegistry = new Map<string, CorrelationRegistration>();
 
   // 생성자 시그니처들
@@ -617,21 +718,28 @@ export class Puri<TSchema, TTables extends object, TResult> {
    */
   private *flattenSelectEntries(
     selectObj: SelectObject<TTables>,
-    prefix = "",
+    path: readonly string[] = [],
   ): Generator<[string, SelectValue<TTables>], void> {
     for (const [key, value] of Object.entries(selectObj)) {
-      const fullKey = prefix ? `${prefix}__${key}` : key;
+      const fieldPath = [...path, key];
+      const fullKey = fieldPath.join("__");
 
       if (isNestedSelectObject(value)) {
-        yield* this.flattenSelectEntries(value, fullKey);
+        yield* this.flattenSelectEntries(value, fieldPath);
       } else {
+        if (fieldPath.length > 1) this.nestedSelectPaths.set(fullKey, fieldPath);
+        else this.nestedSelectPaths.delete(fullKey);
+        this.nestedSelectIdentitySources.delete(fullKey);
+        if (fieldPath.length > 1 && key === "id" && isStringValue(value) && value.includes(".")) {
+          this.nestedSelectIdentitySources.set(fullKey, value.slice(0, value.lastIndexOf(".")));
+        }
         yield [fullKey, value];
       }
     }
   }
 
-  private flattenSelect(selectObj: SelectObject<TTables>, prefix = "") {
-    return Object.fromEntries(this.flattenSelectEntries(selectObj, prefix));
+  private flattenSelect(selectObj: SelectObject<TTables>) {
+    return Object.fromEntries(this.flattenSelectEntries(selectObj));
   }
 
   // SELECT (select는 overwrite, appendSelect는 append)
@@ -681,6 +789,10 @@ export class Puri<TSchema, TTables extends object, TResult> {
   // CLEAR
   clear(statement: ClearStatements): this {
     this.knexQuery.clear(statement);
+    if (statement === "select" || statement === "columns") {
+      this.nestedSelectPaths.clear();
+      this.nestedSelectIdentitySources.clear();
+    }
     if (statement === "join") {
       this.clearJoinRegistrations();
     }
@@ -1484,28 +1596,101 @@ export class Puri<TSchema, TTables extends object, TResult> {
     return this;
   }
 
+  private executeSelect(): Promise<SelectResult> {
+    if (this.nestedSelectPaths.size === 0) return this.knexQuery.then();
+    const presenceColumns = new Map<string, string>();
+    // 원본 쿼리는 rawQuery와 서브셋 로더가 공유하므로 실행 복제본에만 판별식을 추가합니다.
+    let executable = this.knexQuery;
+    if (this.canSelectRelationPresence()) {
+      const sql = this.toQuery();
+      for (const path of this.nestedSelectPaths.values()) {
+        for (let length = 1; length < path.length; length++) {
+          const alias = getSelectRelationAlias(
+            path.slice(0, length).join("__"),
+            this.correlationRegistry,
+            this.nestedSelectIdentitySources,
+          );
+          if (alias === undefined || presenceColumns.has(alias)) continue;
+          let column: string;
+          do {
+            column = `__sonamu_presence_${randomUUID().replaceAll("-", "")}`;
+          } while (sql.includes(column));
+          if (presenceColumns.size === 0) {
+            executable = this.knexQuery.clone();
+            // Knex.clone이 복제하지 않는 실행 제한과 이벤트는 원본의 계약을 유지합니다.
+            // SAFETY: timeout은 Knex QueryBuilder가 보관하는 실행 옵션입니다.
+            const timeout = (this.knexQuery as any)._timeout;
+            if (isNumberValue(timeout)) {
+              // SAFETY: cancelOnTimeout은 timeout 옵션과 함께 Knex가 기록하는 불리언입니다.
+              executable.timeout(timeout, {
+                cancel: (this.knexQuery as any)._cancelOnTimeout === true,
+              });
+            }
+            // SAFETY: Knex QueryBuilder는 EventEmitter를 상속하지만 공개 타입에는 일부 메서드만 있습니다.
+            const emitter = this.knexQuery as Knex.QueryBuilder & EventEmitter;
+            // SAFETY: 실행 복제본도 동일한 Knex EventEmitter 구현입니다.
+            const executionEmitter: EventEmitter = executable as Knex.QueryBuilder & EventEmitter;
+            for (const event of emitter.eventNames()) {
+              executionEmitter.on(event, (...args: any[]) => emitter.emit(event, ...args));
+            }
+          }
+          presenceColumns.set(alias, column);
+          executable.select(this.knex.raw("??.* IS DISTINCT FROM NULL AS ??", [alias, column]));
+        }
+      }
+    }
+    return executable.then((result) =>
+      hydrateSelectResult(
+        result,
+        this.nestedSelectPaths,
+        this.correlationRegistry,
+        presenceColumns,
+        this.nestedSelectIdentitySources,
+      ),
+    );
+  }
+
+  private canSelectRelationPresence(): boolean {
+    // 그룹·집계·DISTINCT·원시 표현식에는 열을 추가하면 SQL 의미가 바뀔 수 있습니다.
+    // SAFETY: Knex의 statement 구조는 다른 JOIN/벡터 처리와 동일한 내부 계약으로 읽습니다.
+    const statements = (this.knexQuery as any)._statements;
+    return statements.every((statement: any) => {
+      if (["group", "having", "union"].includes(statement.grouping)) return false;
+      if (statement.grouping !== "columns") return true;
+      if (statement.distinct || statement.distinctOn || statement.type) return false;
+      return statement.value.every((column: string | { ref?: string }) =>
+        isStringValue(column)
+          ? !column.includes("*")
+          : isObjectValue(column) && isStringValue(column.ref),
+      );
+    });
+  }
+
   // 실행 메서드들 - thenable 구현
   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());
-    // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
-    return this.knexQuery.then(onfulfilled as any, onrejected);
+    // SAFETY: SQL 결과에 선택 경로만 복원하므로 선언된 결과 배열 타입을 유지합니다.
+    return this.executeSelect().then(onfulfilled as any, onrejected);
   }
   catch<TResult2 = never>(
     onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
-  ): Promise<TResult | TResult2> {
-    return this.knexQuery.catch(onrejected);
+  ): Promise<Expand<TResult>[] | TResult2> {
+    return this.then().catch(onrejected);
   }
-  finally(onfinally?: (() => void) | null): Promise<TResult> {
-    return this.knexQuery.finally(onfinally);
+  finally(onfinally?: (() => void) | null): Promise<Expand<TResult>[]> {
+    return this.then().finally(onfinally);
   }
 
   // 하나만 쿼리
   first(): ResolvedPuri<Expand<TResult>, never> {
     this.knexQuery.first();
-    return new ResolvedPuri(this.knexQuery, this.knex, this.tableSpec);
+    return new ResolvedPuri(this.knexQuery, this.knex, this.tableSpec, () => {
+      // SAFETY: first의 SQL 결과에 선택 경로만 복원하므로 선언된 단일 레코드 타입을 유지합니다.
+      return this.executeSelect() as Promise<Expand<TResult>>;
+    });
   }
 
   // 쿼리한 레코드에서 특정 컬럼만 추출한 배열 리턴
@@ -1630,6 +1815,8 @@ export class Puri<TSchema, TTables extends object, TResult> {
     const newPuri = new Puri<TSchema, TTables, TResult>(this.knex, "dual");
     newPuri.knexQuery = this.knexQuery.clone();
     newPuri.tableSpec = this.tableSpec;
+    newPuri.nestedSelectPaths = new Map(this.nestedSelectPaths);
+    newPuri.nestedSelectIdentitySources = new Map(this.nestedSelectIdentitySources);
     newPuri.correlationRegistry = new Map(this.correlationRegistry);
     return newPuri;
   }
@@ -2156,6 +2343,7 @@ export class ResolvedPuri<TResolved, TReturning> implements Promise<TResolved> {
     public knexQuery: Knex.QueryBuilder,
     private knex: Knex,
     private tableSpec: TableSpec | null = null,
+    private resolveResult?: () => Promise<TResolved>,
   ) {}
 
   [Symbol.toStringTag]: string = "Promise";
@@ -2174,18 +2362,19 @@ export class ResolvedPuri<TResolved, TReturning> implements Promise<TResolved> {
     onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
   ): Promise<TResult1 | TResult2> {
     Naite.t("puri:executed-query", this.toQuery());
+    const result = this.resolveResult ? this.resolveResult() : this.knexQuery;
     // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
-    return this.knexQuery.then(onfulfilled as any, onrejected);
+    return result.then(onfulfilled as any, onrejected);
   }
 
   catch<TResult2 = never>(
     onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
   ): Promise<TResolved | TResult2> {
-    return this.knexQuery.catch(onrejected);
+    return this.then().catch(onrejected);
   }
 
   finally(onfinally?: (() => void) | null): Promise<TResolved> {
-    return this.knexQuery.finally(onfinally);
+    return this.then().finally(onfinally);
   }
 
   // ON CONFLICT - 컬럼 기반

package/src/database/puri.types.test-d.ts

@@ -922,3 +922,32 @@ describe("Puri ensureJoin methods", () => {
     });
   });
 });
+
+describe("Puri 중첩 결과 실행 타입", () => {
+  it("then, catch, finally가 동일한 중첩 레코드 배열을 반환한다", () => {
+    type Query = Puri<MockSchema, { users: MockSchema["users"] }, MockSchema["users"]>;
+    // SAFETY: 실행 없이 공개 쿼리 메서드의 반환 타입만 검사합니다.
+    const query = {} as Query;
+    const selected = query.select({ user: { id: "users.id", name: "users.name" } });
+    type Rows = { user: { id: number; name: string } }[];
+    expectTypeOf(selected.then()).resolves.toEqualTypeOf<Rows>();
+    expectTypeOf(selected.catch()).resolves.toEqualTypeOf<Rows>();
+    expectTypeOf(selected.finally()).resolves.toEqualTypeOf<Rows>();
+    expectTypeOf(selected.first().finally()).resolves.toEqualTypeOf<Rows[number]>();
+  });
+});
+
+describe("이름이 다른 관계 그룹의 null 추론", () => {
+  it("명시한 id의 nullable LEFT JOIN 원본을 그룹 nullability에 반영한다", () => {
+    type Tables = {
+      users: MockSchema["users"];
+      staffs: MockSchema["employees"] & LeftJoinedMarker;
+    };
+    type Selected = ParseSelectObject<Tables, { manager: { id: "staffs.id"; name: "users.name" } }>;
+    expectTypeOf<Selected>().toEqualTypeOf<{ manager: { id: number; name: string } | null }>();
+    type Nested = ParseSelectObject<Tables, { location: { manager: { id: "staffs.id" } } }>;
+    expectTypeOf<Nested>().toEqualTypeOf<{ location: { manager: { id: number } | null } }>();
+    type Plain = ParseSelectObject<Tables, { profile: { id: "users.department_id" } }>;
+    expectTypeOf<Plain>().toEqualTypeOf<{ profile: { id: number | null } }>();
+  });
+});

package/src/database/puri.types.ts

@@ -208,6 +208,14 @@ export type ParseSelectObject<
   TSelect extends SelectObject<TTables>,
 > = ParseSelectObjectWithPath<TTables, TSelect, "">;
 
+// 별칭이 다른 관계 그룹도 명시한 id의 nullable JOIN 원본을 따릅니다.
+type IsNullableSelectGroup<TTables, TSelect, Path extends string> =
+  IsNullableJoinedTable<TTables, Path> extends true
+    ? true
+    : TSelect extends { id: `${infer Alias}.${string}` }
+      ? IsNullableJoinedTable<TTables, Alias>
+      : false;
+
 // 경로를 추적하면서 Select 결과 타입을 추론합니다.
 type ParseSelectObjectWithPath<
   TTables extends object,
@@ -218,7 +226,7 @@ type ParseSelectObjectWithPath<
     ? ParseSqlExpression<TSelect[K]>
     : IsNestedObject<TSelect[K]> extends true
       ? TSelect[K] extends NestedSelectObject<TTables>
-        ? IsNullableJoinedTable<TTables, JoinPath<Prefix, K & string>> extends true // 주어진 테이블이 FK nullable에 leftJoin되었는지 여부에 따라 select 결과 객체의 타입이 달라집니다.
+        ? IsNullableSelectGroup<TTables, TSelect[K], 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
@@ -237,7 +245,7 @@ type ParseSelectObjectInner<
     ? ParseSqlExpression<TSelect[K]>
     : IsNestedObject<TSelect[K]> extends true
       ? TSelect[K] extends NestedSelectObject<TTables>
-        ? IsNullableJoinedTable<TTables, JoinPath<Prefix, K & string>> extends true
+        ? IsNullableSelectGroup<TTables, TSelect[K], 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