sonamu 0.5.7 → 0.7.0

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

@@ -0,0 +1,471 @@
+import { describe, expectTypeOf, it } from "vitest";
+import type { DatabaseSchemaExtend } from "../types/types";
+import type { Puri } from "./puri";
+import type { Hydrate, InferAllSubsets, LoadersResult } from "./puri-subset.types";
+import type { PuriWrapper } from "./puri-wrapper";
+
+type MockPuri<T> = Puri<DatabaseSchemaExtend, any, T>;
+
+describe("Hydrate", () => {
+  it("flat 객체를 그대로 유지한다 (__ 없는 경우)", () => {
+    type Input = { id: number; name: string };
+    type Result = Hydrate<Input>;
+
+    const result = {} as Result;
+    expectTypeOf(result).toEqualTypeOf<Hydrate<Input>>();
+  });
+
+  it("단일 depth의 __ 키를 중첩 객체로 변환한다", () => {
+    type Input = { id: number; user__name: string; user__email: string };
+    type Result = Hydrate<Input>;
+
+    const result = {} as Result;
+    expectTypeOf(result).toEqualTypeOf<{
+      id: number;
+      user: { name: string; email: string };
+    }>();
+  });
+
+  it("다중 depth의 __ 키를 재귀적으로 중첩 객체로 변환한다", () => {
+    type Input = {
+      id: number;
+      user__profile__bio: string;
+      user__profile__avatar: string;
+      user__name: string;
+    };
+    type Result = Hydrate<Input>;
+
+    const result = {} as Result;
+    expectTypeOf(result).toEqualTypeOf<{
+      id: number;
+      user: {
+        name: string;
+        profile: { bio: string; avatar: string };
+      };
+    }>();
+  });
+
+  it("여러 관계를 동시에 처리한다", () => {
+    type Input = {
+      id: number;
+      user__id: number;
+      user__name: string;
+      post__id: number;
+      post__title: string;
+    };
+    type Result = Hydrate<Input>;
+
+    const result = {} as Result;
+    expectTypeOf(result).toEqualTypeOf<{
+      id: number;
+      user: { id: number; name: string };
+      post: { id: number; title: string };
+    }>();
+  });
+
+  it("빈 객체를 처리한다", () => {
+    type Input = {};
+    type Result = Hydrate<Input>;
+
+    const result = {} as Result;
+    expectTypeOf(result).toEqualTypeOf<{}>();
+  });
+
+  it("nullable 필드가 있는 중첩 객체를 처리한다", () => {
+    type Input = {
+      id: number;
+      user__id: number | null;
+      user__name: string | null;
+    };
+    type Result = Hydrate<Input>;
+
+    const result = {} as Result;
+    expectTypeOf(result).toEqualTypeOf<{
+      id: number;
+      user: { id: number | null; name: string | null };
+    }>();
+  });
+
+  it("동일한 prefix를 가진 여러 필드를 올바르게 그룹화한다", () => {
+    type Input = {
+      id: number;
+      user__id: number;
+      user__name: string;
+      user_count: number;
+    };
+    type Result = Hydrate<Input>;
+
+    const result = {} as Result;
+    expectTypeOf(result).toEqualTypeOf<{
+      id: number;
+      user: { id: number; name: string };
+      user_count: number;
+    }>();
+  });
+});
+
+describe("LoadersResult", () => {
+  it("단일 로더의 결과 타입을 생성한다", () => {
+    type MockLoaderQb = (
+      qbWrapper: PuriWrapper<DatabaseSchemaExtend>,
+      fromIds: number[],
+    ) => MockPuri<{ id: number; title: string; refId: number }>;
+
+    type Loaders = [
+      {
+        as: "posts";
+        refId: "id";
+        qb: MockLoaderQb;
+      },
+    ];
+    type Result = LoadersResult<Loaders>;
+
+    const result = {} as Result;
+    expectTypeOf(result).toHaveProperty("posts");
+    expectTypeOf(result).toEqualTypeOf<{ posts: { id: number; title: string }[] }>();
+  });
+
+  it("중첩 로더를 처리한다", () => {
+    type CommentLoaderQb = (
+      qbWrapper: PuriWrapper<DatabaseSchemaExtend>,
+      fromIds: number[],
+    ) => MockPuri<{ id: number; content: string; refId: number }>;
+
+    type PostLoaderQb = (
+      qbWrapper: PuriWrapper<DatabaseSchemaExtend>,
+      fromIds: number[],
+    ) => MockPuri<{ id: number; title: string; refId: number }>;
+
+    type Loaders = [
+      {
+        as: "posts";
+        refId: "id";
+        qb: PostLoaderQb;
+        loaders: [
+          {
+            as: "comments";
+            refId: "id";
+            qb: CommentLoaderQb;
+          },
+        ];
+      },
+    ];
+    type Result = LoadersResult<Loaders>;
+
+    const result = {} as Result;
+    expectTypeOf(result).toHaveProperty("posts");
+    expectTypeOf(result).toEqualTypeOf<{
+      posts: { id: number; title: string; comments: { id: number; content: string }[] }[];
+    }>();
+  });
+
+  it("여러 로더를 처리한다", () => {
+    type ProjectLoader = {
+      as: "projects";
+      refId: "id";
+      qb: (
+        qbWrapper: PuriWrapper<DatabaseSchemaExtend>,
+        fromIds: number[],
+      ) => MockPuri<{ id: number; name: string; refId: number }>;
+    };
+    type DepartmentLoader = {
+      as: "department";
+      refId: "id";
+      qb: (
+        qbWrapper: PuriWrapper<DatabaseSchemaExtend>,
+        fromIds: number[],
+      ) => MockPuri<{ id: number; name: string; company_name: string; refId: number }>;
+    };
+    type EmployeeLoader = {
+      as: "employees";
+      refId: "id";
+      qb: (
+        qbWrapper: PuriWrapper<DatabaseSchemaExtend>,
+        fromIds: number[],
+      ) => MockPuri<{ id: number; employee_number: string; refId: number }>;
+      loaders: [
+        {
+          as: "user";
+          refId: "id";
+          qb: (
+            qbWrapper: PuriWrapper<DatabaseSchemaExtend>,
+            fromIds: number[],
+          ) => MockPuri<{ id: number; name: string; email: string; refId: number }>;
+        },
+      ];
+    };
+
+    type Loaders = [ProjectLoader, DepartmentLoader, EmployeeLoader];
+    type Result = LoadersResult<Loaders>;
+
+    const result = {} as Result;
+    expectTypeOf(result).toHaveProperty("projects");
+    expectTypeOf(result).toHaveProperty("employees");
+    expectTypeOf(result).toHaveProperty("department");
+    expectTypeOf(result).toEqualTypeOf<{
+      projects: { id: number; name: string }[];
+      department: { id: number; name: string; company_name: string }[];
+      employees: {
+        id: number;
+        employee_number: string;
+        user: { id: number; name: string; email: string }[];
+      }[];
+    }>();
+  });
+});
+
+describe("InferAllSubsets", () => {
+  describe("서브셋이 하나인 경우", () => {
+    it("로더 없이 기본 Subset 결과를 추론한다", () => {
+      // SubsetQuery
+      type SubsetFnA = (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => MockPuri<{
+        id: number;
+        user__name: string;
+        user__email: string;
+        department__name: string;
+        department__company__name: string;
+      }>;
+      type SubsetQueries = {
+        A: SubsetFnA;
+      };
+
+      // LoaderQuery
+      type LoaderQueries = {
+        A: [];
+      };
+
+      // Result
+      type Result = InferAllSubsets<SubsetQueries, LoaderQueries>;
+
+      const result = {} as Result;
+      expectTypeOf(result).toHaveProperty("A");
+      expectTypeOf(result.A).toEqualTypeOf<{
+        id: number;
+        user: { name: string; email: string };
+        department: { name: string; company: { name: string } };
+      }>();
+      expectTypeOf(result.A.department.company).toEqualTypeOf<{ name: string }>();
+    });
+
+    it("로더를 포함한 Subset 결과를 추론한다", () => {
+      // SubsetQuery
+      type SubsetFnA = (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => MockPuri<{
+        id: number;
+        company__id: number;
+        company__name: string;
+        department__id: number;
+        department__name: string;
+      }>;
+      type SubsetQueries = {
+        A: SubsetFnA;
+      };
+
+      // LoaderQuery
+      type CompanyDepartmentsLoader = {
+        as: "company__departments";
+        refId: "company__id";
+        qb: (
+          qbWrapper: PuriWrapper<DatabaseSchemaExtend>,
+          fromIds: number[],
+        ) => MockPuri<{ id: number; name: string; refId: number }>;
+      };
+      type DepartmentProjectsLoader = {
+        as: "department__projects";
+        refId: "department__id";
+        qb: (
+          qbWrapper: PuriWrapper<DatabaseSchemaExtend>,
+          fromIds: number[],
+        ) => MockPuri<{ id: number; name: string; status: string; refId: number }>;
+      };
+      type LoaderQueries = {
+        A: [CompanyDepartmentsLoader, DepartmentProjectsLoader];
+      };
+
+      // Result
+      type Result = InferAllSubsets<SubsetQueries, LoaderQueries>;
+
+      const result = {} as Result;
+      expectTypeOf(result).toHaveProperty("A");
+      expectTypeOf(result).toEqualTypeOf<{
+        A: {
+          id: number;
+          company: { id: number; name: string; departments: { id: number; name: string }[] };
+          department: {
+            id: number;
+            name: string;
+            projects: { id: number; name: string; status: string }[];
+          };
+        };
+      }>();
+    });
+
+    it("중첩 로더를 포함한 Subset 결과를 추론한다", () => {
+      // SubsetQuery
+      type SubsetFnA = (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => MockPuri<{
+        id: number;
+        company__name: string;
+      }>;
+      type SubsetQueries = {
+        A: SubsetFnA;
+      };
+
+      // LoaderQuery
+      type CompanyDepartmentsLoader = {
+        as: "company__departments";
+        refId: "company__id";
+        qb: (
+          qbWrapper: PuriWrapper<DatabaseSchemaExtend>,
+          fromIds: number[],
+        ) => MockPuri<{ id: number; name: string; refId: number }>;
+        loaders: [
+          {
+            as: "projects";
+            refId: "id";
+            qb: (
+              qbWrapper: PuriWrapper<DatabaseSchemaExtend>,
+              fromIds: number[],
+            ) => MockPuri<{ id: number; name: string; status: string; refId: number }>;
+          },
+        ];
+      };
+      type LoaderQueries = {
+        A: [CompanyDepartmentsLoader];
+      };
+
+      // Result
+      type Result = InferAllSubsets<SubsetQueries, LoaderQueries>;
+
+      const result = {} as Result;
+      expectTypeOf(result).toEqualTypeOf<{
+        A: {
+          id: number;
+          company: {
+            name: string;
+            departments: {
+              id: number;
+              name: string;
+              projects: { id: number; name: string; status: string }[];
+            }[];
+          };
+        };
+      }>();
+    });
+  });
+
+  describe("서브셋이 여러 개인 경우", () => {
+    it("로더 없이 기본 Subset 결과를 추론한다", () => {
+      // SubsetQuery
+      type SubsetFnA = (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => MockPuri<{
+        id: number;
+        name: string;
+        email: string;
+        department__name: string;
+      }>;
+      type SubsetFnP = (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => MockPuri<{
+        id: number;
+        name: string;
+        department__name: string;
+      }>;
+      type SubsetFnSS = (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => MockPuri<{
+        id: number;
+        name: string;
+        email: string;
+        password: string;
+      }>;
+      type SubsetQueries = {
+        A: SubsetFnA;
+        P: SubsetFnP;
+        SS: SubsetFnSS;
+      };
+
+      // LoaderQuery
+      type LoaderQueries = {
+        A: [];
+        P: [];
+        SS: [];
+      };
+
+      // Result
+      type Result = InferAllSubsets<SubsetQueries, LoaderQueries>;
+
+      const result = {} as Result;
+      expectTypeOf(result).toEqualTypeOf<{
+        A: { id: number; name: string; email: string; department: { name: string } };
+        P: { id: number; name: string; department: { name: string } };
+        SS: { id: number; name: string; email: string; password: string };
+      }>();
+    });
+
+    it("로더를 포함한 Subset 결과를 추론한다", () => {
+      // SubsetQuery
+      type SubsetFnA = (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => MockPuri<{
+        id: number;
+        name: string;
+        email: string;
+        department__name: string;
+      }>;
+      type SubsetFnP = (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => MockPuri<{
+        id: number;
+        name: string;
+        department__name: string;
+      }>;
+      type SubsetFnSS = (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => MockPuri<{
+        id: number;
+        name: string;
+        email: string;
+        password: string;
+      }>;
+      type SubsetQueries = {
+        A: SubsetFnA;
+        P: SubsetFnP;
+        SS: SubsetFnSS;
+      };
+
+      // LoaderQuery
+      type ProjectLoader = {
+        as: "projects";
+        refId: "id";
+        qb: (
+          qbWrapper: PuriWrapper<DatabaseSchemaExtend>,
+          fromIds: number[],
+        ) => MockPuri<{ id: number; name: string; status: string; refId: number }>;
+        loaders: [
+          {
+            as: "tags";
+            refId: "id";
+            qb: (
+              qbWrapper: PuriWrapper<DatabaseSchemaExtend>,
+              fromIds: number[],
+            ) => MockPuri<{ id: number; name: string; refId: number }>;
+          },
+        ];
+      };
+      type LoaderQueries = {
+        A: [ProjectLoader];
+        P: [];
+        SS: [];
+      };
+
+      // Result
+      type Result = InferAllSubsets<SubsetQueries, LoaderQueries>;
+
+      const result = {} as Result;
+      expectTypeOf(result).toEqualTypeOf<{
+        A: {
+          id: number;
+          name: string;
+          email: string;
+          department: { name: string };
+          projects: {
+            id: number;
+            name: string;
+            status: string;
+            tags: { id: number; name: string }[];
+          }[];
+        };
+        P: { id: number; name: string; department: { name: string } };
+        SS: { id: number; name: string; email: string; password: string };
+      }>();
+    });
+  });
+});

package/src/database/puri-subset.types.ts

@@ -0,0 +1,195 @@
+/**
+ * Puri Subset 타입 시스템
+ *
+ * SubsetQuery와 LoaderQuery를 기반으로 최종 결과 타입을 추론하는 타입 유틸리티들.
+ * 핵심 개념:
+ * - SubsetQuery: 기본 쿼리 (join, select)
+ * - LoaderQuery: 1:N, N:M 관계 데이터 로딩
+ * - Hydrate: flat한 결과를 중첩 객체로 변환 (예: user__name → { user: { name } })
+ */
+
+import type { DatabaseSchemaExtend } from "../types/types";
+import type { Puri } from "./puri";
+import type { Expand } from "./puri.types";
+import type { PuriWrapper } from "./puri-wrapper";
+
+// ============================================================================
+// 기본 타입 정의
+// ============================================================================
+
+/**
+ * SubsetQuery 함수 시그니처
+ * PuriWrapper를 받아 Puri 쿼리 빌더를 반환
+ */
+export type PuriSubsetFn = (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => Puri<any, any, any>;
+
+/**
+ * Puri 인스턴스에서 TResult 타입 추출
+ */
+export type ExtractPuriResult<T> = T extends Puri<any, any, infer R> ? R : never;
+
+// ============================================================================
+// Loader 관련 타입
+// ============================================================================
+
+/**
+ * Loader 쿼리 빌더 함수 시그니처
+ * @param qbWrapper - Puri 래퍼
+ * @param fromIds - 부모 레코드 ID 배열
+ */
+export type PuriLoaderQbFn = (
+  qbWrapper: PuriWrapper<DatabaseSchemaExtend>,
+  fromIds: number[],
+) => Puri<any, any, any>;
+
+/**
+ * 단일 Loader 정의
+ * 1:N 또는 N:M 관계 데이터를 로드하는 설정
+ */
+export type GenericPuriLoader = {
+  /** 결과 객체에서 사용할 필드명 */
+  as: string;
+  /** 부모 레코드와 연결할 참조 필드명 */
+  refId: string;
+  /** 데이터 로딩 쿼리 빌더 */
+  qb: PuriLoaderQbFn;
+  /** 중첩 로더 (재귀적 로딩 지원) */
+  loaders?: GenericPuriLoader[];
+};
+
+/**
+ * 모델별 Loader 쿼리 컬렉션
+ * 각 SubsetKey에 대해 Loader 배열을 정의
+ */
+export type PuriLoaderQueries<TSubsetKey extends string> = Record<TSubsetKey, GenericPuriLoader[]>;
+
+// ============================================================================
+// Hydrate 타입 시스템
+// ============================================================================
+
+/**
+ * 구분자(__) 앞부분 추출
+ * @example ExtractHead<"user__name"> = "user"
+ */
+type ExtractHead<K extends string> = K extends `${infer Head}__${string}` ? Head : never;
+
+/**
+ * 구분자(__) 뒷부분 추출
+ * @example ExtractTail<"user__profile__name", "user"> = "profile__name"
+ */
+type ExtractTail<K extends string, Head extends string> = K extends `${Head}__${infer Tail}`
+  ? Tail
+  : never;
+
+/**
+ * Flat 객체를 중첩 객체로 변환
+ *
+ * 런타임 hydrate 함수와 동일한 동작을 타입 레벨에서 구현.
+ * `__`로 구분된 키를 중첩 객체 구조로 변환.
+ *
+ * @example
+ * type Input = { id: number; user__name: string; user__profile__bio: string }
+ * type Output = Hydrate<Input>
+ * // { id: number; user: { name: string; profile: { bio: string } } }
+ */
+export type Hydrate<T> = Expand<HydrateInner<T>>;
+type HydrateInner<T> = {
+  [K in keyof T as K extends `${string}__${string}` ? never : K]: T[K];
+} & {
+  [K in ExtractHead<keyof T & string>]: Expand<
+    HydrateInner<{
+      [P in keyof T as P extends `${K}__${string}` ? ExtractTail<P & string, K> : never]: T[P];
+    }>
+  >;
+};
+
+// ============================================================================
+// Loader 결과 타입 추론
+// ============================================================================
+
+/**
+ * Loader 쿼리 함수에서 결과 타입 추출 (refId 제외, Hydrate 적용)
+ */
+type ExtractLoaderResult<TLoaderQb> = TLoaderQb extends PuriLoaderQbFn
+  ? Expand<Hydrate<Omit<ExtractPuriResult<ReturnType<TLoaderQb>>, "refId">>>
+  : never;
+
+/**
+ * Loader 배열에서 결과 객체 타입 빌드 (재귀적으로 중첩 loader 처리)
+ *
+ * @example
+ * type Loaders = [
+ *   { as: "employees"; refId: "id"; qb: ...; loaders: [{ as: "projects"; ... }] }
+ * ]
+ * type Result = LoadersResult<Loaders>
+ * // { employees: Array<{ ...employee fields; projects: Array<...> }> }
+ */
+export type LoadersResult<TLoaders extends GenericPuriLoader[]> = Expand<{
+  [L in TLoaders[number] as L["as"]]: WithLoaders<ExtractLoaderResult<L["qb"]>, L["loaders"]>[];
+}>;
+
+/**
+ * 기본 결과와 Loader 결과 병합
+ */
+type WithLoaders<TBase, TLoaders> = TLoaders extends GenericPuriLoader[]
+  ? Expand<TBase & LoadersResult<TLoaders>>
+  : TBase;
+
+// ============================================================================
+// Subset 결과 타입 추론
+// ============================================================================
+
+/**
+ * 단일 Subset 함수 + Loader에서 최종 결과 타입 추론
+ */
+type InferSubsetWithLoaders<
+  TSubsetFn extends (...args: any) => Puri<any, any, any>,
+  TLoaders extends GenericPuriLoader[] | undefined = undefined,
+> = Expand<Hydrate<WithLoaders<ExtractPuriResult<ReturnType<TSubsetFn>>, TLoaders>>>;
+
+/**
+ * 전체 SubsetQueries + LoaderQueries 객체에서 전체 결과 맵 생성
+ *
+ * @template TSubsetMap - Subset 함수들의 모음 객체
+ * @template TLoaderMap - Loader 배열들의 모음 객체
+ *
+ * @example
+ * type Result = InferAllSubsets<
+ *   { A: () => Puri<...>, P: () => Puri<...> },
+ *   { A: [...loaders], P: [] }
+ * >
+ * // { A: InferredTypeA; P: InferredTypeP }
+ */
+export type InferAllSubsets<
+  TSubsetMap extends Record<string, (...args: any) => any>,
+  TLoaderMap extends Partial<Record<string, GenericPuriLoader[]>>,
+> = {
+  [K in keyof TSubsetMap]: InferSubsetWithLoaders<
+    TSubsetMap[K],
+    K extends keyof TLoaderMap ? TLoaderMap[K] : undefined
+  >;
+};
+
+// ============================================================================
+// Clear 문
+// ============================================================================
+
+/**
+ * Knex QueryBuilder에서 clear 가능한 statement 목록
+ */
+export type ClearStatements =
+  | "with"
+  | "select"
+  | "columns"
+  | "hintComments"
+  | "where"
+  | "union"
+  | "using"
+  | "join"
+  | "group"
+  | "order"
+  | "having"
+  | "limit"
+  | "offset"
+  | "counter"
+  | "counters";