sonamu 0.13.2 → 0.13.4

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

package/src/dict/sonamu-dictionary.ts

@@ -2,13 +2,14 @@ import { execSync } from "child_process";
 import fs from "fs";
 import path from "path";
 
-import { Workbook } from "@sheetkit/node";
+import { type JsRowCell, Workbook } from "@sheetkit/node";
 import ts from "@typescript/typescript6";
 
 import { Sonamu } from "../api/sonamu";
 import { formatCode } from "../code-formatting";
 import { EntityManager } from "../entity/entity-manager";
 import { BadRequestException } from "../exceptions/so-exceptions";
+import { isStringValue } from "../utils/runtime-value";
 import { SD } from "./sd";
 import {
   type DictEntry,
@@ -33,6 +34,29 @@ function colLetter(index: number): string {
   return result;
 }
 
+/**
+ * Excel 행 셀을 사전 값 문자열로 읽습니다.
+ *
+ * SheetKit 0.5.1과 같은 결과를 유지합니다.
+ * - 문자열 셀은 그 값을 그대로 씁니다.
+ * - 수식 셀은 캐시된 결과가 아니라 수식 텍스트를 씁니다. SheetKit 1.0.1은 수식 텍스트를
+ *   `value`와 `formula` 객체에 함께 주며, `value`가 없을 때는 `formula` 객체의 텍스트를 씁니다.
+ * - 숫자·날짜·불리언 셀은 빈 문자열로 둡니다. 객체 값을 문자열로 바꾸면
+ *   "[object Object]" 같은 값이 사전에 들어가므로 변환하지 않습니다.
+ */
+function readCellText(cell: JsRowCell | undefined): string {
+  if (cell === undefined) {
+    return "";
+  }
+  if (isStringValue(cell.value)) {
+    return cell.value;
+  }
+  if (cell.valueType === "formula" && cell.formula !== undefined) {
+    return cell.formula.formula;
+  }
+  return "";
+}
+
 /**
  * Sonamu Dictionary 관리 클래스
  * i18n 딕셔너리의 CRUD 및 Excel import/export를 담당합니다.
@@ -757,9 +781,7 @@ export class SonamuDictionary {
     let headerRowNum = 0;
     for (const rowData of allRows) {
       const firstCell = rowData.cells.find((c) => c.column === "A");
-      const firstCellValue = String(firstCell?.value ?? "")
-        .trim()
-        .toLowerCase();
+      const firstCellValue = readCellText(firstCell).trim().toLowerCase();
       if (firstCellValue === "key") {
         headerRowNum = rowData.row;
         break;
@@ -775,7 +797,7 @@ export class SonamuDictionary {
     const colToHeader: Map<string, string> = new Map();
     if (headerRowData) {
       for (const cell of headerRowData.cells) {
-        colToHeader.set(cell.column, String(cell.value ?? ""));
+        colToHeader.set(cell.column, readCellText(cell));
       }
     }
 
@@ -787,7 +809,7 @@ export class SonamuDictionary {
       for (const cell of rowData.cells) {
         const headerName = colToHeader.get(cell.column);
         if (headerName) {
-          rowValues[headerName] = String(cell.value ?? "");
+          rowValues[headerName] = readCellText(cell);
         }
       }
 

package/src/storage/__tests__/storage-manager.test.ts

@@ -0,0 +1,64 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { type MultipartFile } from "@fastify/multipart";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { Sonamu } from "../../api/sonamu";
+import { BufferedFile, drivers, StorageManager, StreamedFile } from "../index";
+
+describe("이름 붙인 디스크", () => {
+  const originalStorage = Sonamu["storageValue"];
+  let directory: string;
+
+  beforeEach(async () => {
+    directory = await mkdtemp(path.join(tmpdir(), "sonamu-storage-"));
+  });
+
+  afterEach(async () => {
+    Reflect.set(Sonamu, "storageValue", originalStorage);
+    await rm(directory, { recursive: true, force: true });
+  });
+
+  it("버퍼 업로드와 스트림 파일 다운로드가 같은 이름의 디스크를 사용한다", async () => {
+    const factory = vi.fn(
+      drivers.fs({
+        location: directory,
+        visibility: "public",
+        urlBuilder: {
+          async generateURL(key) {
+            return `https://cdn.example.com/${key}`;
+          },
+          async generateSignedURL(key) {
+            return `https://cdn.example.com/${key}?signed`;
+          },
+        },
+      }),
+    );
+    const manager = new StorageManager({ drivers: { images: factory } });
+    Reflect.set(Sonamu, "storageValue", manager);
+    expect(factory).not.toHaveBeenCalled();
+
+    // SAFETY: BufferedFile 생성자가 읽는 필드는 filename과 mimetype뿐이며 raw는 이 테스트에서 사용하지 않는다.
+    const multipart = { filename: "hello.txt", mimetype: "text/plain" } as MultipartFile;
+    const buffer = new BufferedFile(multipart, Buffer.from("hello"));
+    expect(await buffer.saveToDisk("images", "hello.txt")).toBe(
+      "https://cdn.example.com/hello.txt",
+    );
+    expect(await readFile(path.join(directory, "hello.txt"), "utf8")).toBe("hello");
+    const streamed = new StreamedFile({
+      filename: "hello.txt",
+      mimetype: "text/plain",
+      size: 5,
+      key: "hello.txt",
+      diskName: "images",
+      url: "https://cdn.example.com/hello.txt",
+      signedUrl: "https://cdn.example.com/hello.txt?signed",
+    });
+    expect(streamed.diskName).toBe("images");
+    expect(await streamed.download()).toEqual(Buffer.from("hello"));
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(() => manager.use("missing")).toThrow('Unknown disk: "missing". Available: images');
+  });
+});

package/src/storage/buffered-file.ts

@@ -3,7 +3,7 @@ import { createHash } from "crypto";
 import { type MultipartFile } from "@fastify/multipart";
 
 import { BaseFile } from "./base-file";
-import { type DriverKey } from "./drivers";
+import { type DiskName } from "./types";
 
 /**
  * Buffer 모드로 업로드된 파일
@@ -35,11 +35,11 @@ export class BufferedFile extends BaseFile {
 
   /**
    * 파일을 디스크에 저장
-   * @param diskName 디스크 이름 ("fs" 또는 "s3")
+   * @param diskName 설정에 등록한 디스크 이름
    * @param key 저장 경로 (예: 'uploads/avatar.png')
    * @returns 저장된 파일의 URL
    */
-  async saveToDisk(diskName: DriverKey, key: string): Promise<string> {
+  async saveToDisk(diskName: DiskName, key: string): Promise<string> {
     // 순환 의존성 방지를 위해 동적 import
     const { Sonamu } = await import("../api/sonamu");
     const disk = Sonamu.storage.use(diskName);

package/src/storage/index.ts

@@ -3,5 +3,5 @@ export { BaseFile } from "./base-file";
 export { BufferedFile } from "./buffered-file";
 export { type DriverKey, drivers } from "./drivers";
 export { StorageManager } from "./storage-manager";
-export type { KeyGenerator, StorageConfig } from "./types";
+export type { DiskName, KeyGenerator, StorageConfig } from "./types";
 export { UploadedFile as StreamedFile } from "./uploaded-file";

package/src/storage/storage-manager.ts

@@ -1,22 +1,21 @@
 import { Disk } from "flydrive";
 
 import { assertDefined } from "../utils/utils";
-import { type DriverKey } from "./drivers";
-import { type StorageConfig } from "./types";
+import { type DiskName, type StorageConfig } from "./types";
 
 /**
  * 여러 디스크를 관리하는 매니저
  */
 export class StorageManager {
-  private disks: Map<DriverKey, Disk> = new Map();
+  private disks: Map<DiskName, Disk> = new Map();
 
   constructor(private config: StorageConfig) {}
 
   /**
    * 디스크 인스턴스 반환 (lazy initialization)
-   * @param diskName 디스크 이름 (없으면 default)
+   * @param diskName 설정에 등록한 디스크 이름
    */
-  use(diskName: DriverKey): Disk {
+  use(diskName: DiskName): Disk {
     if (!this.disks.has(diskName)) {
       const factory = this.config.drivers[diskName];
       if (!factory) {

package/src/storage/storage.test-d.ts

@@ -0,0 +1,47 @@
+import { describe, expectTypeOf, it } from "vitest";
+
+import { type SonamuConfig } from "../api/config";
+import { type UploadDecoratorOptions } from "../api/decorators";
+import { Sonamu } from "../api/sonamu";
+import {
+  type BufferedFile,
+  type DriverKey,
+  drivers,
+  StorageManager,
+  type StorageConfig,
+  StreamedFile,
+} from "./index";
+
+describe("스토리지 디스크 이름", () => {
+  it("드라이버 종류와 독립적인 디스크 이름을 모든 업로드 경로에서 허용한다", () => {
+    const factory = drivers.fs({ location: "/tmp", visibility: "public" });
+    const storage = { drivers: { images: factory, private: factory } } satisfies StorageConfig;
+    expectTypeOf(storage).toExtend<NonNullable<SonamuConfig["server"]["storage"]>>();
+    const manager = new StorageManager(storage);
+    expectTypeOf(manager.use).parameter(0).toEqualTypeOf<string>();
+    expectTypeOf(Sonamu.storage.use).parameter(0).toEqualTypeOf<string>();
+    expectTypeOf<BufferedFile["saveToDisk"]>().parameter(0).toEqualTypeOf<string>();
+    expectTypeOf<StreamedFile["diskName"]>().toEqualTypeOf<string>();
+    expectTypeOf<DriverKey>().toEqualTypeOf<"fs" | "s3">();
+    const options = { consume: "stream", destination: "images" } satisfies UploadDecoratorOptions;
+    expectTypeOf(options).toExtend<UploadDecoratorOptions>();
+    expectTypeOf(
+      new StreamedFile({
+        filename: "image.jpg",
+        mimetype: "image/jpeg",
+        size: 1,
+        url: "https://cdn.example.com/image.jpg",
+        signedUrl: "",
+        key: "image.jpg",
+        diskName: "images",
+      }),
+    ).toEqualTypeOf<StreamedFile>();
+  });
+
+  it("fs나 s3라는 이름의 디스크를 반드시 설정할 필요가 없다", () => {
+    const factory = drivers.fs({ location: "/tmp", visibility: "public" });
+    expectTypeOf({ drivers: { images: factory } }).toExtend<StorageConfig>();
+    expectTypeOf({ drivers: { fs: factory } }).toExtend<StorageConfig>();
+    expectTypeOf({ drivers: { s3: factory } }).toExtend<StorageConfig>();
+  });
+});