@simplysm/orm-common 14.1.2 → 14.1.7

package/src/schema/view-builder.ts

@@ -1,143 +1,148 @@
-import type { DbContextBase } from "../types/db-context-def";
-import type { Queryable } from "../exec/queryable";
-import type { DataRecord } from "../types/db";
-import {
-  createRelationFactory,
-  type InferDeepRelations,
-  type RelationBuilderRecord,
-} from "./factory/relation-builder";
-
-// ============================================
-// ViewBuilder
-// ============================================
-
-/**
- * Database View 정의 builder
- *
- * Fluent API로 View query와 관계를 정의
- * DbContext의 queryable()과 함께 사용하여 타입 안전한 query 구성
- *
- * @template TDbContext - DbContext 타입
- * @template TData - View 데이터 레코드 타입
- * @template TRelations - 관계 정의 레코드 타입
- *
- * @see {@link View} factory 함수
- * @see {@link queryable} Queryable 생성
- */
-export class ViewBuilder<
-  TDbContext extends DbContextBase,
-  TData extends DataRecord,
-  TRelations extends RelationBuilderRecord,
-> {
-  /** 관계 정의 (타입 추론용) */
-  readonly $relations!: TRelations;
-  /** 전체 타입 추론 */
-  readonly $inferSelect!: TData;
-
-  /**
-   * @param meta - View 메타데이터
-   * @param meta.name - View 이름
-   * @param meta.description - View 설명 (comment)
-   * @param meta.database - Database 이름
-   * @param meta.schema - Schema 이름 (MSSQL/PostgreSQL)
-   * @param meta.viewFn - View query 정의 함수
-   * @param meta.relations - 관계 정의
-   */
-  constructor(
-    readonly meta: {
-      name: string;
-      description?: string;
-      database?: string;
-      schema?: string;
-      viewFn?: (db: TDbContext) => Queryable<TData, any>;
-      relations?: TRelations;
-    },
-  ) {}
-
-  /**
-   * View 설명 설정
-   *
-   * @param desc - View 설명 (DDL Comment로 사용됨)
-   * @returns 새 ViewBuilder 인스턴스
-   */
-  description(desc: string): ViewBuilder<TDbContext, TData, TRelations> {
-    return new ViewBuilder({ ...this.meta, description: desc });
-  }
-
-  /**
-   * Database 이름 설정
-   *
-   * @param db - Database 이름
-   * @returns 새 ViewBuilder 인스턴스
-   */
-  database(db: string): ViewBuilder<TDbContext, TData, TRelations> {
-    return new ViewBuilder({ ...this.meta, database: db });
-  }
-
-  /**
-   * Schema 이름 설정
-   *
-   * MSSQL, PostgreSQL에서 사용
-   *
-   * @param schema - Schema 이름 (MSSQL: dbo, PostgreSQL: public)
-   * @returns 새 ViewBuilder 인스턴스
-   */
-  schema(schema: string): ViewBuilder<TDbContext, TData, TRelations> {
-    return new ViewBuilder({ ...this.meta, schema });
-  }
-
-  /**
-   * View query 정의
-   *
-   * SELECT query를 통해 View의 데이터 소스를 정의
-   *
-   * @template TViewData - View 데이터 타입
-   * @template TDb - DbContext 타입
-   * @param viewFn - DbContext를 받아 Queryable을 반환하는 함수
-   * @returns 새 ViewBuilder 인스턴스
-   */
-  query<TViewData extends DataRecord, TDb extends DbContextBase>(
-    viewFn: (db: TDb) => Queryable<TViewData, any>,
-  ): ViewBuilder<TDb, TViewData, TRelations> {
-    return new ViewBuilder({ ...this.meta, viewFn });
-  }
-
-  /**
-   * 관계 정의
-   *
-   * 다른 Table/View와의 관계를 설정
-   *
-   * @template T - 관계 정의 타입
-   * @param fn - 관계 factory를 받아 관계 정의를 반환하는 함수
-   * @returns 새 ViewBuilder 인스턴스
-   *
-   * @see {@link ForeignKeyBuilder} FK builder
-   * @see {@link ForeignKeyTargetBuilder} FK reverse-reference builder
-   */
-  relations<T extends RelationBuilderRecord>(
-    fn: (r: ReturnType<typeof createRelationFactory<this, keyof TData & string>>) => T,
-  ): ViewBuilder<TDbContext, TData & InferDeepRelations<T>, T> {
-    return new ViewBuilder({
-      ...this.meta,
-      relations: fn(createRelationFactory<this, keyof TData & string>(() => this)),
-    }) as any;
-  }
-}
-
-// ============================================
-// View 함수
-// ============================================
-
-/**
- * View builder factory 함수
- *
- * Fluent API로 View schema를 정의하기 위한 ViewBuilder를 생성
- *
- * @param name - View 이름
- * @returns ViewBuilder 인스턴스
- *
- * @see {@link ViewBuilder} builder 클래스
- */
-export function View(name: string) {
-  return new ViewBuilder({ name });
-}
+import type { DbContextBase } from "../types/db-context-def";
+import type { Queryable } from "../exec/queryable";
+import type { DataRecord } from "../types/db";
+import {
+  createRelationFactory,
+  type InferDeepRelations,
+  type ViewRelationFactory,
+} from "./factory/relation-builder";
+
+// ============================================
+// ViewBuilder
+// ============================================
+
+/**
+ * Database View 정의 builder
+ *
+ * Fluent API로 View query를 정의
+ * DbContext의 queryable()과 함께 사용하여 타입 안전한 query 구성
+ *
+ * 관계는 `.relations((r) => ({ ... }))` 메서드 체이닝으로 정의한다(RelationKey만 사용 가능).
+ * 관계를 잡는 4번째 제네릭 `TRelations` 는 **무제약**이라 TS6 순환을 회피한다.
+ *
+ * @template TDbContext - DbContext 타입
+ * @template TName - View 이름
+ * @template TData - View 데이터 레코드 타입
+ * @template TRelations - 관계 정의 레코드 타입 (무제약, 기본값 `{}`)
+ *
+ * @see {@link View} factory 함수
+ * @see {@link queryable} Queryable 생성
+ */
+export class ViewBuilder<
+  TDbContext extends DbContextBase,
+  TName extends string,
+  TData extends DataRecord,
+  TRelations = {},
+> {
+  /**
+   * 전체 타입 추론 (column + 관계).
+   *
+   * 관계는 `TRelations` 를 구조적으로 lazy walk 하여 다단계로 해소된다.
+   */
+  readonly $inferSelect!: TData & InferDeepRelations<TRelations>;
+
+  /**
+   * @param meta - View 메타데이터
+   * @param meta.name - View 이름
+   * @param meta.description - View 설명 (comment)
+   * @param meta.database - Database 이름
+   * @param meta.schema - Schema 이름 (MSSQL/PostgreSQL)
+   * @param meta.viewFn - View query 정의 함수
+   * @param meta.relations - 관계 정의 (런타임: `.relations(fn)` 호출 시 부착됨)
+   */
+  constructor(
+    readonly meta: {
+      name: TName;
+      description?: string;
+      database?: string;
+      schema?: string;
+      viewFn?: (db: TDbContext) => Queryable<TData, any>;
+      relations?: TRelations;
+    },
+  ) {}
+
+  /**
+   * View 설명 설정
+   *
+   * @param desc - View 설명 (DDL Comment로 사용됨)
+   * @returns 새 ViewBuilder 인스턴스
+   */
+  description(desc: string): ViewBuilder<TDbContext, TName, TData, TRelations> {
+    return new ViewBuilder({ ...this.meta, description: desc });
+  }
+
+  /**
+   * Database 이름 설정
+   *
+   * @param db - Database 이름
+   * @returns 새 ViewBuilder 인스턴스
+   */
+  database(db: string): ViewBuilder<TDbContext, TName, TData, TRelations> {
+    return new ViewBuilder({ ...this.meta, database: db });
+  }
+
+  /**
+   * Schema 이름 설정
+   *
+   * MSSQL, PostgreSQL에서 사용
+   *
+   * @param schema - Schema 이름 (MSSQL: dbo, PostgreSQL: public)
+   * @returns 새 ViewBuilder 인스턴스
+   */
+  schema(schema: string): ViewBuilder<TDbContext, TName, TData, TRelations> {
+    return new ViewBuilder({ ...this.meta, schema });
+  }
+
+  /**
+   * View query 정의
+   *
+   * SELECT query를 통해 View의 데이터 소스를 정의
+   *
+   * @template TViewData - View 데이터 타입
+   * @template TDb - DbContext 타입
+   * @param viewFn - DbContext를 받아 Queryable을 반환하는 함수
+   * @returns 새 ViewBuilder 인스턴스
+   */
+  query<TViewData extends DataRecord, TDb extends DbContextBase>(
+    viewFn: (db: TDb) => Queryable<TViewData, any>,
+  ): ViewBuilder<TDb, TName, TViewData, TRelations> {
+    return new ViewBuilder({ ...this.meta, viewFn });
+  }
+
+  /**
+   * 관계 정의 (RelationKey / RelationKeyTarget 만 사용 가능)
+   *
+   * 관계 타입 `T` 는 **무제약**으로 추론되며, 내부적으로 런타임 결과를
+   * `meta.relations` 에 저장한다(`as any`). TS6 순환 회피.
+   *
+   * @template T - 관계 정의 레코드 타입 (무제약)
+   * @param fn - 관계 factory를 받아 관계 정의를 반환하는 함수
+   * @returns 관계가 부착된 새 ViewBuilder 인스턴스
+   */
+  relations<T>(
+    fn: (r: ViewRelationFactory<keyof TData & string>) => T,
+  ): ViewBuilder<TDbContext, TName, TData, T> {
+    return new ViewBuilder<TDbContext, TName, TData, T>({
+      ...this.meta,
+      relations: fn(createRelationFactory<keyof TData & string>()),
+    });
+  }
+}
+
+// ============================================
+// View 함수
+// ============================================
+
+/**
+ * View builder factory 함수
+ *
+ * Fluent API로 View schema를 정의하기 위한 ViewBuilder를 생성
+ *
+ * @param name - View 이름
+ * @returns ViewBuilder 인스턴스
+ *
+ * @see {@link ViewBuilder} builder 클래스
+ */
+export function View<TName extends string>(name: TName) {
+  return new ViewBuilder<DbContextBase, TName, DataRecord, {}>({ name });
+}

package/src/types/column.ts

@@ -1,4 +1,4 @@
-import { DateOnly, DateTime, Time, Uuid, type Bytes } from "@simplysm/core-common";
+import { primitive, type PrimitiveType, type PrimitiveTypeMap, type PrimitiveTypeStr } from "@simplysm/core-common";
 
 // ============================================
 // DataType (SQL 타입 정의)
@@ -45,31 +45,20 @@ export type DataType =
 
 /**
  * Column 원시 타입 매핑
- *
- * TypeScript 타입 이름 (문자열) → 실제 TypeScript 타입 매핑
  */
-export type ColumnPrimitiveMap = {
-  string: string;
-  number: number;
-  boolean: boolean;
-  DateTime: DateTime;
-  DateOnly: DateOnly;
-  Time: Time;
-  Uuid: Uuid;
-  Bytes: Bytes;
-};
+export type ColumnPrimitiveMap = PrimitiveTypeMap;
 
 /**
  * Column 원시 타입 이름 (문자열)
  */
-export type ColumnPrimitiveStr = keyof ColumnPrimitiveMap;
+export type ColumnPrimitiveStr = PrimitiveTypeStr;
 
 /**
  * Column에 저장 가능한 모든 원시 타입
  *
  * undefined는 NULL을 나타냄
  */
-export type ColumnPrimitive = ColumnPrimitiveMap[ColumnPrimitiveStr] | undefined;
+export type ColumnPrimitive = PrimitiveType;
 
 // ============================================
 // DataType ↔ ColumnPrimitive Mapping
@@ -108,18 +97,10 @@ export type InferColumnPrimitiveFromDataType<TDataType extends DataType> =
  *
  * @param value - Column 값
  * @returns ColumnPrimitiveStr 타입 이름
- * @throws 값 타입이 알 수 없을 때 Error
+ * @throws 값 타입이 알 수 없을 때 ArgumentError
  */
-export function inferColumnPrimitiveStr(value: ColumnPrimitive): ColumnPrimitiveStr {
-  if (typeof value === "string") return "string";
-  if (typeof value === "number") return "number";
-  if (typeof value === "boolean") return "boolean";
-  if (value instanceof DateTime) return "DateTime";
-  if (value instanceof DateOnly) return "DateOnly";
-  if (value instanceof Time) return "Time";
-  if (value instanceof Uuid) return "Uuid";
-  if (value instanceof Uint8Array) return "Bytes";
-  throw new Error("NULL 값으로는 타입을 추론할 수 없습니다.");
+export function inferColumnPrimitiveStr(value: Exclude<ColumnPrimitive, undefined>): ColumnPrimitiveStr {
+  return primitive.typeStr(value);
 }
 
 // ============================================

package/src/types/db-context-def.ts

@@ -14,7 +14,7 @@ import type { QueryDef, QueryDefObjectName } from "./query-def";
  * DbContext class가 이 인터페이스를 구현한다.
  */
 export interface DbContextBase {
-  status: DbContextStatus;
+  readonly status: DbContextStatus;
   readonly database: string | undefined;
   readonly schema: string | undefined;
   getNextAlias(): string;
@@ -24,7 +24,7 @@ export interface DbContextBase {
     resultMetas?: (ResultMeta | undefined)[],
   ): Promise<T[][]>;
   getQueryDefObjectName(
-    tableOrView: TableBuilder<any, any, any> | ViewBuilder<any, any, any>,
+    tableOrView: TableBuilder<any, any> | ViewBuilder<any, any, any>,
   ): QueryDefObjectName;
   switchFk(table: QueryDefObjectName, enabled: boolean): Promise<void>;
 }
@@ -32,7 +32,7 @@ export interface DbContextBase {
 export type DbContextStatus = "ready" | "connect" | "transact";
 
 export interface DbContextDdlMethods {
-  createTable(table: TableBuilder<any, any, any>): Promise<void>;
+  createTable(table: TableBuilder<any, any>): Promise<void>;
   dropTable(table: QueryDefObjectName): Promise<void>;
   renameTable(table: QueryDefObjectName, newName: string): Promise<void>;
   createView(view: ViewBuilder<any, any, any>): Promise<void>;
@@ -56,7 +56,7 @@ export interface DbContextDdlMethods {
   addForeignKey(
     table: QueryDefObjectName,
     relationName: string,
-    relationDef: ForeignKeyBuilder<any, any>,
+    relationDef: ForeignKeyBuilder<any>,
   ): Promise<void>;
   addIndex(table: QueryDefObjectName, indexBuilder: IndexBuilder<string[]>): Promise<void>;
   dropForeignKey(table: QueryDefObjectName, relationName: string): Promise<void>;
@@ -66,11 +66,11 @@ export interface DbContextDdlMethods {
   truncate(table: QueryDefObjectName): Promise<void>;
   switchFk(table: QueryDefObjectName, enabled: boolean): Promise<void>;
   // QueryDef 생성기
-  getCreateTableQueryDef(table: TableBuilder<any, any, any>): QueryDef;
+  getCreateTableQueryDef(table: TableBuilder<any, any>): QueryDef;
   getCreateViewQueryDef(view: ViewBuilder<any, any, any>): QueryDef;
   getCreateProcQueryDef(procedure: ProcedureBuilder<any, any>): QueryDef;
   getCreateObjectQueryDef(
-    builder: TableBuilder<any, any, any> | ViewBuilder<any, any, any> | ProcedureBuilder<any, any>,
+    builder: TableBuilder<any, any> | ViewBuilder<any, any, any> | ProcedureBuilder<any, any>,
   ): QueryDef;
   getDropTableQueryDef(table: QueryDefObjectName): QueryDef;
   getRenameTableQueryDef(table: QueryDefObjectName, newName: string): QueryDef;
@@ -93,7 +93,7 @@ export interface DbContextDdlMethods {
   getAddForeignKeyQueryDef(
     table: QueryDefObjectName,
     relationName: string,
-    relationDef: ForeignKeyBuilder<any, any>,
+    relationDef: ForeignKeyBuilder<any>,
   ): QueryDef;
   getAddIndexQueryDef(table: QueryDefObjectName, indexBuilder: IndexBuilder<string[]>): QueryDef;
   getDropForeignKeyQueryDef(table: QueryDefObjectName, relationName: string): QueryDef;

package/src/types/query-def.ts

@@ -351,7 +351,7 @@ export interface CreateProcQueryDef {
     name: string;
     dataType: DataType;
     nullable?: boolean;
-    default?: unknown;
+    default?: ColumnPrimitive;
   }>;
   returns?: Array<{
     name: string;

package/src/utils/result-parser.ts

@@ -1,9 +1,7 @@
-import { bytes, obj, DateOnly, DateTime, Time, Uuid } from "@simplysm/core-common";
+import { bytes, obj, wait, DateOnly, DateTime, Time, Uuid } from "@simplysm/core-common";
 import type { ColumnPrimitiveStr } from "../types/column";
 import type { ResultMeta } from "../types/db";
 
-declare function setImmediate(callback: () => void): void;
-
 // ============================================
 // 타입 파서
 // ============================================
@@ -164,12 +162,6 @@ function isEmptyJoinObject(record: Record<string, unknown>): boolean {
 /** 양보 간격: N개 레코드마다 이벤트 루프에 양보 */
 const YIELD_INTERVAL = 100;
 
-/** 이벤트 루프 양보: Node.js는 setImmediate, 브라우저는 setTimeout 폴백 */
-const yieldToEventLoop: () => Promise<void> =
-  typeof setImmediate !== "undefined"
-    ? () => new Promise<void>((resolve) => setImmediate(resolve))
-    : () => new Promise<void>((resolve) => setTimeout(resolve, 0));
-
 /**
  * ResultMeta를 통해 DB 쿼리 결과를 TypeScript 객체로 변환
  *
@@ -197,27 +189,27 @@ export async function parseQueryResult<TRecord>(
 
   // JOIN 없음: 단순 타입 파싱만 수행
   if (joinKeys.length === 0) {
-    return parseSimpleRecords<TRecord>(rawResults, meta.columns);
+    return parseSimpleRecords(rawResults, meta.columns) as Promise<TRecord[] | undefined>;
   }
 
   // JOIN 있음: 그룹핑 + 중첩
-  return parseJoinedRecords<TRecord>(rawResults, meta);
+  return parseJoinedRecords(rawResults, meta) as Promise<TRecord[] | undefined>;
 }
 
 /**
  * JOIN이 없는 단순 레코드 파싱
  */
-async function parseSimpleRecords<TRecord>(
+async function parseSimpleRecords(
   rawResults: Record<string, unknown>[],
   columns: Record<string, ColumnPrimitiveStr>,
-): Promise<TRecord[] | undefined> {
+): Promise<Record<string, unknown>[] | undefined> {
   const columnInfos = buildColumnInfos(columns);
   const results: Record<string, unknown>[] = [];
 
   for (let i = 0; i < rawResults.length; i++) {
     // 이벤트 루프에 양보
     if (i > 0 && i % YIELD_INTERVAL === 0) {
-      await yieldToEventLoop();
+      await wait.immediate();
     }
 
     const parsed = flatToNested(rawResults[i], columnInfos);
@@ -229,7 +221,7 @@ async function parseSimpleRecords<TRecord>(
   }
 
   // 빈 배열은 undefined 반환
-  return results.length > 0 ? (results as TRecord[]) : undefined;
+  return results.length > 0 ? results : undefined;
 }
 
 /**
@@ -247,16 +239,16 @@ function sortJoinKeysByDepth(joinKeys: string[]): string[] {
 /**
  * JOIN이 있는 레코드 파싱 (재귀 그룹핑)
  */
-async function parseJoinedRecords<TRecord>(
+async function parseJoinedRecords(
   rawResults: Record<string, unknown>[],
   meta: ResultMeta,
-): Promise<TRecord[] | undefined> {
+): Promise<Record<string, unknown>[] | undefined> {
   // 1. 모든 레코드를 중첩 구조로 변환
   const columnInfos = buildColumnInfos(meta.columns);
   const nestedRecords: Record<string, unknown>[] = [];
   for (let i = 0; i < rawResults.length; i++) {
     if (i > 0 && i % YIELD_INTERVAL === 0) {
-      await yieldToEventLoop();
+      await wait.immediate();
     }
     nestedRecords.push(flatToNested(rawResults[i], columnInfos));
   }
@@ -270,7 +262,7 @@ async function parseJoinedRecords<TRecord>(
   // 4. 빈 결과 필터링
   const filteredResults = results.filter((r) => !isEmptyObject(r));
 
-  return filteredResults.length > 0 ? (filteredResults as TRecord[]) : undefined;
+  return filteredResults.length > 0 ? filteredResults : undefined;
 }
 
 /**