@simplysm/orm-common 14.0.49 → 14.0.51

package/docs/schema-builders/table.md

@@ -0,0 +1,94 @@
+# Table
+
+Fluent API로 Database Table 스키마를 정의하는 빌더 팩토리 함수. 반환된 `TableBuilder`에 컬럼, PK, 인덱스, 관계를 메서드 체이닝으로 정의한다. 각 메서드는 새 인스턴스를 반환하므로 불변(immutable)이다.
+
+```typescript
+export function Table(name: string): TableBuilder<never, never>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | 테이블 이름 |
+
+## Returns
+
+`TableBuilder<never, never>` — 빈 TableBuilder 인스턴스
+
+## Related Types
+
+### `TableBuilder<TColumns, TRelations>`
+
+```typescript
+export class TableBuilder<
+  TColumns extends ColumnBuilderRecord,
+  TRelations extends RelationBuilderRecord,
+> {
+  readonly $inferSelect!: InferColumns<TColumns> & InferDeepRelations<TRelations>;
+  readonly $inferColumns!: InferColumns<TColumns>;
+  readonly $inferInsert!: InferInsertColumns<TColumns>;
+  readonly $inferUpdate!: InferUpdateColumns<TColumns>;
+}
+```
+
+#### 타입 추론 프로퍼티
+
+| 프로퍼티 | 설명 |
+|----------|------|
+| `$inferSelect` | SELECT 결과 타입 (컬럼 + 관계 포함) |
+| `$inferColumns` | 컬럼만의 타입 |
+| `$inferInsert` | INSERT 입력 타입 (autoIncrement 제외, nullable/default는 optional) |
+| `$inferUpdate` | UPDATE 입력 타입 (모든 필드 optional) |
+
+#### 빌더 메서드
+
+| 메서드 | 설명 |
+|--------|------|
+| `description(desc)` | 테이블 설명 설정 (DDL Comment) |
+| `database(db)` | Database 이름 설정 |
+| `schema(schema)` | Schema 이름 설정 (MSSQL: dbo, PostgreSQL: public) |
+| `columns(fn)` | 컬럼 정의. `fn(c) => ({ name: c.varchar(100), ... })` |
+| `primaryKey(...columns)` | PK 설정. 복합 PK는 여러 인자 전달 |
+| `indexes(fn)` | 인덱스 정의. `fn(i) => [i.index("email").unique(), ...]` |
+| `relations(fn)` | 관계 정의. `fn(r) => ({ company: r.foreignKey(...), ... })` |
+
+## Usage
+
+```typescript
+const User = Table("User")
+  .database("mydb")
+  .columns((c) => ({
+    id: c.bigint().autoIncrement(),
+    name: c.varchar(100),
+    email: c.varchar(200).nullable(),
+    isActive: c.boolean().default(true),
+    companyId: c.bigint().nullable(),
+    createdAt: c.datetime(),
+  }))
+  .primaryKey("id")
+  .indexes((i) => [
+    i.index("email").unique(),
+    i.index("name", "createdAt").orderBy("ASC", "DESC"),
+  ])
+  .relations((r) => ({
+    company: r.foreignKey(["companyId"], () => Company, { description: "소속회사" }),
+    posts: r.foreignKeyTarget(() => Post, "user"),
+    profile: r.foreignKeyTarget(() => Profile, "user", { single: true }),
+  }));
+
+// 복합 PK
+const UserRole = Table("UserRole")
+  .columns((c) => ({
+    userId: c.bigint(),
+    roleId: c.bigint(),
+  }))
+  .primaryKey("userId", "roleId");
+```
+
+## 권장사항
+
+### `isDeleted` 컬럼
+
+- **기초정보(마스터 데이터) 테이블**: `isDeleted: c.boolean().default(false)` 컬럼을 포함한다. 삭제 시 `isDeleted: true`로 soft-delete하고, 복구 기능을 제공한다.
+- **일반 데이터(트랜잭션 데이터 등) 테이블**: `isDeleted` 컬럼을 두지 않는다. 삭제 시 물리 삭제(row DELETE)로 처리한다.

package/docs/schema-builders/view.md

@@ -0,0 +1,71 @@
+# View
+
+Fluent API로 Database View 스키마를 정의하는 빌더 팩토리 함수. 반환된 `ViewBuilder`에 쿼리와 관계를 메서드 체이닝으로 정의한다.
+
+```typescript
+export function View(name: string): ViewBuilder<never, never, never>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | View 이름 |
+
+## Returns
+
+`ViewBuilder<never, never, never>` — 빈 ViewBuilder 인스턴스
+
+## Related Types
+
+### `ViewBuilder<TDbContext, TData, TRelations>`
+
+```typescript
+export class ViewBuilder<
+  TDbContext extends DbContextBase,
+  TData extends DataRecord,
+  TRelations extends RelationBuilderRecord,
+> {
+  readonly $inferSelect!: TData;
+}
+```
+
+#### 빌더 메서드
+
+| 메서드 | 설명 |
+|--------|------|
+| `description(desc)` | View 설명 설정 (DDL Comment) |
+| `database(db)` | Database 이름 설정 |
+| `schema(schema)` | Schema 이름 설정 |
+| `query(viewFn)` | View 쿼리 정의. `(db: TDb) => Queryable<TViewData, any>` |
+| `relations(fn)` | 관계 정의 (`relationKey`/`relationKeyTarget`만 사용 가능) |
+
+## Usage
+
+```typescript
+// 단순 필터 View
+const ActiveUsers = View("ActiveUsers")
+  .database("mydb")
+  .query((db: MainDb) =>
+    db.user()
+      .where((u) => [expr.eq(u.isActive, true)])
+      .select((u) => ({ id: u.id, name: u.name }))
+  );
+
+// 집계 View
+const UserStats = View("UserStats")
+  .database("mydb")
+  .query((db: MainDb) =>
+    db.user()
+      .groupBy((u) => [u.companyId])
+      .select((u) => ({
+        companyId: u.companyId,
+        userCount: expr.count(u.id),
+      }))
+  );
+
+// DbContext에 등록
+class MainDb extends DbContext {
+  activeUsers = this.queryable(ActiveUsers);
+}
+```

package/docs/types/data-type.md

@@ -0,0 +1,146 @@
+# DataType
+
+SQL 데이터 타입 및 TypeScript 타입 매핑 관련 타입/상수 모음.
+
+## `DataType`
+
+SQL 데이터 타입 정의 discriminated union.
+
+```typescript
+export type DataType =
+  | { type: "int" }
+  | { type: "bigint" }
+  | { type: "float" }
+  | { type: "double" }
+  | { type: "decimal"; precision: number; scale?: number }
+  | { type: "varchar"; length: number }
+  | { type: "char"; length: number }
+  | { type: "text" }
+  | { type: "binary" }
+  | { type: "boolean" }
+  | { type: "datetime" }
+  | { type: "date" }
+  | { type: "time" }
+  | { type: "uuid" };
+```
+
+| `type` | MySQL | MSSQL | PostgreSQL | TypeScript |
+|--------|-------|-------|------------|------------|
+| `int` | INT | INT | INTEGER | `number` |
+| `bigint` | BIGINT | BIGINT | BIGINT | `number` |
+| `float` | FLOAT | REAL | REAL | `number` |
+| `double` | DOUBLE | FLOAT | DOUBLE PRECISION | `number` |
+| `decimal` | DECIMAL(p,s) | DECIMAL(p,s) | NUMERIC(p,s) | `number` |
+| `varchar` | VARCHAR(n) | NVARCHAR(n) | VARCHAR(n) | `string` |
+| `char` | CHAR(n) | NCHAR(n) | CHAR(n) | `string` |
+| `text` | LONGTEXT | NVARCHAR(MAX) | TEXT | `string` |
+| `binary` | LONGBLOB | VARBINARY(MAX) | BYTEA | `Bytes` |
+| `boolean` | TINYINT(1) | BIT | BOOLEAN | `boolean` |
+| `datetime` | DATETIME | DATETIME2 | TIMESTAMP | `DateTime` |
+| `date` | DATE | DATE | DATE | `DateOnly` |
+| `time` | TIME | TIME | TIME | `Time` |
+| `uuid` | BINARY(16) | UNIQUEIDENTIFIER | UUID | `Uuid` |
+
+## `ColumnPrimitiveMap`
+
+TypeScript 타입 이름(문자열) → 실제 TypeScript 타입 매핑.
+
+```typescript
+export type ColumnPrimitiveMap = {
+  string: string;
+  number: number;
+  boolean: boolean;
+  DateTime: DateTime;
+  DateOnly: DateOnly;
+  Time: Time;
+  Uuid: Uuid;
+  Bytes: Bytes;
+};
+```
+
+## `ColumnPrimitiveStr`
+
+Column 원시 타입 이름 문자열. `keyof ColumnPrimitiveMap`.
+
+```typescript
+export type ColumnPrimitiveStr = keyof ColumnPrimitiveMap;
+// "string" | "number" | "boolean" | "DateTime" | "DateOnly" | "Time" | "Uuid" | "Bytes"
+```
+
+## `ColumnPrimitive`
+
+Column에 저장 가능한 모든 원시 타입. `undefined`는 NULL을 나타낸다.
+
+```typescript
+export type ColumnPrimitive = ColumnPrimitiveMap[ColumnPrimitiveStr] | undefined;
+```
+
+## `dataTypeStrToColumnPrimitiveStr`
+
+SQL DataType의 `type` 문자열 → `ColumnPrimitiveStr` 매핑 상수.
+
+```typescript
+export const dataTypeStrToColumnPrimitiveStr: {
+  int: "number";
+  bigint: "number";
+  float: "number";
+  double: "number";
+  decimal: "number";
+  varchar: "string";
+  char: "string";
+  text: "string";
+  binary: "Bytes";
+  boolean: "boolean";
+  datetime: "DateTime";
+  date: "DateOnly";
+  time: "Time";
+  uuid: "Uuid";
+};
+```
+
+## `InferColumnPrimitiveFromDataType<T>`
+
+`DataType`으로부터 TypeScript 타입을 추론하는 제네릭 타입.
+
+```typescript
+export type InferColumnPrimitiveFromDataType<TDataType extends DataType> =
+  ColumnPrimitiveMap[(typeof dataTypeStrToColumnPrimitiveStr)[TDataType["type"]]];
+
+// 예시
+type IntType = InferColumnPrimitiveFromDataType<{ type: "int" }>;  // number
+type VarcharType = InferColumnPrimitiveFromDataType<{ type: "varchar"; length: 100 }>;  // string
+```
+
+## `inferColumnPrimitiveStr`
+
+런타임 값에서 `ColumnPrimitiveStr`을 추론하는 함수.
+
+```typescript
+export function inferColumnPrimitiveStr(value: ColumnPrimitive): ColumnPrimitiveStr;
+```
+
+- `undefined`/`null`이면 에러를 던진다.
+
+## `ColumnMeta`
+
+`ColumnBuilder`에서 생성되어 `TableBuilder`에 전달되는 Column 메타데이터.
+
+```typescript
+export interface ColumnMeta {
+  type: ColumnPrimitiveStr;
+  dataType: DataType;
+  autoIncrement?: boolean;
+  nullable?: boolean;
+  default?: ColumnPrimitive;
+  description?: string;
+}
+```
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `type` | `ColumnPrimitiveStr` | TypeScript 타입 이름 |
+| `dataType` | `DataType` | SQL 데이터 타입 |
+| `autoIncrement` | `boolean \| undefined` | AUTO_INCREMENT 여부 |
+| `nullable` | `boolean \| undefined` | NULL 허용 여부 |
+| `default` | `ColumnPrimitive \| undefined` | 기본값 |
+| `description` | `string \| undefined` | Column 설명 (DDL Comment) |

package/docs/types/dialect.md

@@ -0,0 +1,151 @@
+# Dialect
+
+지원하는 DB 방언 타입 및 관련 런타임 타입 모음.
+
+## `Dialect`
+
+```typescript
+export type Dialect = "mysql" | "mssql" | "postgresql";
+```
+
+| 값 | 지원 버전 |
+|----|-----------|
+| `"mysql"` | MySQL 8.0.14+ |
+| `"mssql"` | Microsoft SQL Server 2012+ |
+| `"postgresql"` | PostgreSQL 9.0+ |
+
+## `dialects`
+
+모든 dialect 목록 배열. 테스트에서 dialect별 검증에 사용한다.
+
+```typescript
+export const dialects: Dialect[] = ["mysql", "mssql", "postgresql"];
+```
+
+## `IsolationLevel`
+
+트랜잭션 격리 수준.
+
+```typescript
+export type IsolationLevel =
+  | "READ_UNCOMMITTED"
+  | "READ_COMMITTED"
+  | "REPEATABLE_READ"
+  | "SERIALIZABLE";
+```
+
+| 값 | 설명 |
+|----|------|
+| `READ_UNCOMMITTED` | 커밋되지 않은 데이터 읽기 가능 (Dirty Read) |
+| `READ_COMMITTED` | 커밋된 데이터만 읽기 (기본값) |
+| `REPEATABLE_READ` | 트랜잭션 내 동일 쿼리가 동일 결과 보장 |
+| `SERIALIZABLE` | 완전 직렬화 (가장 엄격) |
+
+## `DataRecord`
+
+쿼리 결과 데이터 레코드 타입. 재귀적 구조로 중첩 관계(`include`) 결과를 표현한다.
+
+```typescript
+export type DataRecord = {
+  [key: string]: ColumnPrimitive | DataRecord | DataRecord[];
+};
+```
+
+## `DbContextExecutor`
+
+실제 DB 연결과 쿼리 실행을 담당하는 인터페이스. `orm-node`의 `NodeDbContextExecutor` 또는 서비스 클라이언트 구현체가 이 인터페이스를 구현한다.
+
+```typescript
+export interface DbContextExecutor {
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
+  commitTransaction(): Promise<void>;
+  rollbackTransaction(): Promise<void>;
+  executeDefs<T = DataRecord>(
+    defs: QueryDef[],
+    resultMetas?: (ResultMeta | undefined)[],
+  ): Promise<T[][]>;
+}
+```
+
+| 메서드 | 설명 |
+|--------|------|
+| `connect()` | DB 연결 수립 |
+| `close()` | DB 연결 종료 |
+| `beginTransaction(isolationLevel?)` | 트랜잭션 시작 |
+| `commitTransaction()` | 트랜잭션 커밋 |
+| `rollbackTransaction()` | 트랜잭션 롤백 |
+| `executeDefs(defs, resultMetas?)` | QueryDef 배열 실행, 결과 배열 반환 |
+
+## `QueryBuildResult`
+
+`QueryBuilderBase.build()` 반환 타입.
+
+```typescript
+export interface QueryBuildResult {
+  sql: string;
+  resultSetIndex?: number;
+  resultSetStride?: number;
+}
+```
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `sql` | `string` | 빌드된 SQL 문자열 |
+| `resultSetIndex` | `number \| undefined` | 결과를 가져올 결과 셋 인덱스. 기본값 0 |
+| `resultSetStride` | `number \| undefined` | stride 간격으로 다중 결과 셋 수집. MySQL 배치 INSERT에 사용 |
+
+## `ResultMeta`
+
+SELECT 결과를 TypeScript 객체로 변환할 때 사용하는 메타데이터.
+
+```typescript
+export interface ResultMeta {
+  columns: Record<string, ColumnPrimitiveStr>;
+  joins: Record<string, { isSingle: boolean }>;
+}
+```
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `columns` | `Record<string, ColumnPrimitiveStr>` | 컬럼 이름 → 타입 이름 매핑 |
+| `joins` | `Record<string, { isSingle: boolean }>` | JOIN 별칭 → 단일/배열 구분 |
+
+## `Migration`
+
+DB 마이그레이션 정의.
+
+```typescript
+export interface Migration {
+  name: string;
+  up: (db: DbContextBase & DbContextDdlMethods) => Promise<void>;
+}
+```
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `name` | `string` | 고유 마이그레이션 이름. 타임스탬프 형식 권장 |
+| `up` | `(db) => Promise<void>` | 마이그레이션 실행 함수 |
+
+```typescript
+const migrations: Migration[] = [
+  {
+    name: "20260105_001_create_user_table",
+    up: async (db) => {
+      await db.createTable(User);
+    },
+  },
+];
+```
+
+## `pickResultSets`
+
+다중 결과 셋에서 `QueryBuildResult` 메타데이터에 따라 필요한 결과만 추출한다. MySQL 배치 INSERT 후 OUTPUT 추출에 사용된다.
+
+```typescript
+export function pickResultSets<T>(
+  rawResults: T[][],
+  buildResult: Pick<QueryBuildResult, "resultSetIndex" | "resultSetStride">,
+): T[];
+```

package/docs/types/expr.md

@@ -0,0 +1,175 @@
+# Expr
+
+SQL 표현식 AST 타입 모음. `expr.*` 함수들이 내부적으로 생성하며, `QueryBuilderBase`가 SQL 문자열로 변환한다.
+
+## `Expr`
+
+모든 SELECT 표현식 AST의 유니온 타입.
+
+```typescript
+export type Expr =
+  | ExprColumn
+  | ExprValue
+  | ExprRaw
+  | ExprConcat
+  | ExprLeft
+  | ExprRight
+  | ExprTrim
+  | ExprPadStart
+  | ExprReplace
+  | ExprUpper
+  | ExprLower
+  | ExprLength
+  | ExprByteLength
+  | ExprSubstring
+  | ExprIndexOf
+  | ExprAbs
+  | ExprRound
+  | ExprCeil
+  | ExprFloor
+  | ExprAdd
+  | ExprSub
+  | ExprMul
+  | ExprDiv
+  | ExprMod
+  | ExprYear
+  | ExprMonth
+  | ExprDay
+  | ExprHour
+  | ExprMinute
+  | ExprSecond
+  | ExprDateDiff
+  | ExprDateAdd
+  | ExprCount
+  | ExprSum
+  | ExprAvg
+  | ExprMax
+  | ExprMin
+  | ExprRowNumber
+  | ExprRank
+  | ExprDenseRank
+  | ExprLag
+  | ExprLead
+  | ExprSumOver
+  | ExprCountOver
+  | ExprAvgOver
+  | ExprMaxOver
+  | ExprMinOver
+  | ExprFirstValue
+  | ExprLastValue
+  | ExprNtile
+  | ExprSubquery
+  | ExprIf
+  | ExprSwitch
+  | ExprCoalesce
+  | ExprNullIf
+  | ExprCast
+  | ExprToDateOnly
+  | ExprToDateTime;
+```
+
+## `WhereExpr`
+
+WHERE 절 표현식 AST 유니온 타입.
+
+```typescript
+export type WhereExpr =
+  | ExprEq
+  | ExprGt
+  | ExprLt
+  | ExprGte
+  | ExprLte
+  | ExprBetween
+  | ExprIsNull
+  | ExprLike
+  | ExprRegexp
+  | ExprIn
+  | ExprInQuery
+  | ExprExists
+  | ExprNot
+  | ExprAnd
+  | ExprOr;
+```
+
+## `DateUnit`
+
+날짜 연산 단위. `expr.dateDiff()`, `expr.dateAdd()`에서 사용.
+
+```typescript
+export type DateUnit = "year" | "month" | "day" | "hour" | "minute" | "second";
+```
+
+## `WinSpec`
+
+윈도우 함수 스펙.
+
+```typescript
+export interface WinSpec {
+  partitionBy?: Expr[];
+  orderBy?: [Expr, ("ASC" | "DESC")?][];
+}
+```
+
+## 값 표현식 인터페이스
+
+| 인터페이스 | `type` 값 | 설명 |
+|------------|-----------|------|
+| `ExprColumn` | `"column"` | 컬럼 참조. `path: string[]` |
+| `ExprValue` | `"value"` | 리터럴 값. `value: ColumnPrimitive` |
+| `ExprRaw` | `"raw"` | Raw SQL. `sql: string`, `params: Expr[]` |
+
+## 비교 표현식 인터페이스 (WhereExpr)
+
+| 인터페이스 | `type` 값 | 설명 |
+|------------|-----------|------|
+| `ExprEq` | `"eq"` | `=` (NULL 안전). `source`, `target` |
+| `ExprGt` | `"gt"` | `>`. `source`, `target` |
+| `ExprLt` | `"lt"` | `<`. `source`, `target` |
+| `ExprGte` | `"gte"` | `>=`. `source`, `target` |
+| `ExprLte` | `"lte"` | `<=`. `source`, `target` |
+| `ExprBetween` | `"between"` | `BETWEEN`. `source`, `from?`, `to?` |
+| `ExprIsNull` | `"null"` | `IS NULL`. `arg` |
+| `ExprLike` | `"like"` | `LIKE`. `source`, `pattern` |
+| `ExprRegexp` | `"regexp"` | 정규식. `source`, `pattern` |
+| `ExprIn` | `"in"` | `IN (...)`. `source`, `values: Expr[]` |
+| `ExprInQuery` | `"inQuery"` | `IN (SELECT ...)`. `source`, `query: SelectQueryDef` |
+| `ExprExists` | `"exists"` | `EXISTS (SELECT ...)`. `query: SelectQueryDef` |
+| `ExprNot` | `"not"` | `NOT`. `arg: WhereExpr` |
+| `ExprAnd` | `"and"` | `AND`. `conditions: WhereExpr[]` |
+| `ExprOr` | `"or"` | `OR`. `conditions: WhereExpr[]` |
+
+## 집계/윈도우 함수 인터페이스
+
+| 인터페이스 | `type` 값 | 설명 |
+|------------|-----------|------|
+| `ExprCount` | `"count"` | `COUNT(*)` 또는 `COUNT(arg)`. `arg?: Expr` |
+| `ExprSum` | `"sum"` | `SUM(arg)`. `arg: Expr` |
+| `ExprAvg` | `"avg"` | `AVG(arg)`. `arg: Expr` |
+| `ExprMax` | `"max"` | `MAX(arg)`. `arg: Expr` |
+| `ExprMin` | `"min"` | `MIN(arg)`. `arg: Expr` |
+| `ExprRowNumber` | `"rowNumber"` | `ROW_NUMBER() OVER (...)`. `winSpec: WinSpec` |
+| `ExprRank` | `"rank"` | `RANK() OVER (...)`. `winSpec: WinSpec` |
+| `ExprDenseRank` | `"denseRank"` | `DENSE_RANK() OVER (...)`. `winSpec: WinSpec` |
+| `ExprLag` | `"lag"` | `LAG(...) OVER (...)`. `source`, `offset?`, `default?`, `winSpec?` |
+| `ExprLead` | `"lead"` | `LEAD(...) OVER (...)`. `source`, `offset?`, `default?`, `winSpec?` |
+| `ExprSumOver` | `"sumOver"` | `SUM(...) OVER (...)` |
+| `ExprCountOver` | `"countOver"` | `COUNT(...) OVER (...)` |
+| `ExprAvgOver` | `"avgOver"` | `AVG(...) OVER (...)` |
+| `ExprMaxOver` | `"maxOver"` | `MAX(...) OVER (...)` |
+| `ExprMinOver` | `"minOver"` | `MIN(...) OVER (...)` |
+| `ExprFirstValue` | `"firstValue"` | `FIRST_VALUE(...) OVER (...)` |
+| `ExprLastValue` | `"lastValue"` | `LAST_VALUE(...) OVER (...)` |
+| `ExprNtile` | `"ntile"` | `NTILE(n) OVER (...)` |
+
+## 조건부/변환 인터페이스
+
+| 인터페이스 | `type` 값 | 설명 |
+|------------|-----------|------|
+| `ExprIf` | `"if"` | `IF(cond, then, else)`. `condition: WhereExpr`, `then: Expr`, `else_: Expr` |
+| `ExprSwitch` | `"switch"` | `CASE WHEN`. `cases: { condition, then }[]`, `default?: Expr` |
+| `ExprCoalesce` | `"coalesce"` | `COALESCE(...)`. `args: Expr[]` |
+| `ExprNullIf` | `"nullIf"` | `NULLIF(source, target)` |
+| `ExprCast` | `"cast"` | `CAST(source AS type)`. `source: Expr`, `dataType: DataType` |
+| `ExprToDateOnly` | `"toDateOnly"` | DateTime → DateOnly 변환 |
+| `ExprToDateTime` | `"toDateTime"` | DateOnly → DateTime 변환 |
+| `ExprSubquery` | `"subquery"` | 단일 값 반환 서브쿼리. `dataType: ColumnPrimitiveStr`, `query: SelectQueryDef` |

package/docs/types/parse-query-result.md

@@ -0,0 +1,58 @@
+# parseQueryResult
+
+DB 쿼리 원시 결과(`Record<string, unknown>[]`)를 `ResultMeta`를 이용해 타입 변환하고, JOIN 결과를 중첩 TypeScript 객체로 재구성한다. `Queryable.execute()` 내부에서 자동 호출되며, 직접 호출은 커스텀 executor 구현 시에만 필요하다.
+
+```typescript
+export async function parseQueryResult<TRecord>(
+  rawResults: Record<string, unknown>[],
+  meta: ResultMeta,
+): Promise<TRecord[] | undefined>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `rawResults` | `Record<string, unknown>[]` | DB에서 반환된 플랫 원시 결과 배열 |
+| `meta` | `ResultMeta` | 컬럼 타입 정보 및 JOIN 구조 정보 |
+
+## Returns
+
+`Promise<TRecord[] | undefined>` — 타입 변환 및 중첩 구조로 재구성된 결과 배열. 입력이 비어 있거나 파싱 후 모든 레코드가 빈 객체이면 `undefined` 반환.
+
+## 동작
+
+1. **단순 타입 파싱** (JOIN 없는 경우): `meta.columns`에 따라 각 컬럼 값을 TypeScript 타입으로 변환한다. 예를 들어 `"1"` → `1`, `"2026-01-07T10:00:00.000Z"` → `DateTime`.
+2. **JOIN 결과 중첩** (JOIN 있는 경우): `meta.joins`에 따라 `"posts.id"` 등 점 구분 플랫 키를 중첩 객체/배열로 그룹핑한다. `isSingle: false`이면 배열, `isSingle: true`이면 단일 객체로 조합한다.
+3. **비동기 양보**: 100개 레코드마다 이벤트 루프에 양보하여 대규모 결과 처리 시 UI/다른 작업을 차단하지 않는다.
+
+## 주의사항
+
+- `meta` 없이는 이 함수를 호출할 필요가 없다 (입력 = 출력).
+- 브라우저/Node.js 양쪽에서 동작한다 (`setImmediate` 또는 `setTimeout` 폴백).
+- 타입 파싱 실패(숫자 변환 실패 등) 시 에러를 던진다.
+
+## Usage
+
+```typescript
+// 단순 타입 파싱
+const raw = [{ id: "1", createdAt: "2026-01-07T10:00:00.000Z" }];
+const meta: ResultMeta = {
+  columns: { id: "number", createdAt: "DateTime" },
+  joins: {},
+};
+const result = await parseQueryResult(raw, meta);
+// [{ id: 1, createdAt: DateTime(...) }]
+
+// JOIN 결과 중첩
+const raw = [
+  { id: 1, name: "User1", "posts.id": 10, "posts.title": "Post1" },
+  { id: 1, name: "User1", "posts.id": 11, "posts.title": "Post2" },
+];
+const meta: ResultMeta = {
+  columns: { id: "number", name: "string", "posts.id": "number", "posts.title": "string" },
+  joins: { posts: { isSingle: false } },
+};
+const result = await parseQueryResult(raw, meta);
+// [{ id: 1, name: "User1", posts: [{ id: 10, title: "Post1" }, { id: 11, title: "Post2" }] }]
+```