sonamu 0.13.1 → 0.13.3

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/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>();
+  });
+});

package/src/storage/types.ts

@@ -1,6 +1,7 @@
 import { type DriverContract } from "flydrive/types";
 
-import { type DriverKey } from "./drivers";
+/** storage.drivers에 등록한 디스크 이름. 드라이버 종류(fs·s3)와는 독립적이다. */
+export type DiskName = string;
 
 /**
  * Stream 모드에서 파일 키 생성 함수 타입
@@ -15,7 +16,7 @@ export type KeyGenerator = (file: {
  */
 export type StorageConfig = {
   /** 디스크별 드라이버 팩토리 */
-  drivers: Record<DriverKey, () => DriverContract>;
+  drivers: Record<DiskName, () => DriverContract>;
   /** stream 모드의 전역 키 생성 함수 (생략 시 timestamp-random 기본값) */
   keyGenerator?: KeyGenerator;
 };

package/src/storage/uploaded-file.ts

@@ -1,5 +1,5 @@
 import { BaseFile } from "./base-file";
-import { type DriverKey } from "./drivers";
+import { type DiskName } from "./types";
 
 /**
  * Stream 모드로 업로드된 파일
@@ -7,7 +7,7 @@ import { type DriverKey } from "./drivers";
  */
 export class UploadedFile extends BaseFile {
   private keyValue: string;
-  private diskNameValue: DriverKey;
+  private diskNameValue: DiskName;
 
   constructor(params: {
     filename: string;
@@ -16,7 +16,7 @@ export class UploadedFile extends BaseFile {
     url: string;
     signedUrl: string;
     key: string;
-    diskName: DriverKey;
+    diskName: DiskName;
   }) {
     super({
       filename: params.filename,
@@ -35,7 +35,7 @@ export class UploadedFile extends BaseFile {
   }
 
   /** 저장된 디스크 이름 */
-  get diskName(): DriverKey {
+  get diskName(): DiskName {
     return this.diskNameValue;
   }