@simplysm/orm-common 13.0.93 → 13.0.96

package/docs/ddl.md

@@ -19,6 +19,15 @@ await db.connectWithoutTransaction(async () => {
 });
 ```
 
+### initialize API
+
+```
+db.initialize(options?: {
+  dbs?: string[];      // 초기화할 DB 목록 (생략 시 전체)
+  force?: boolean;     // true이면 기존 스키마 삭제 후 재생성
+}): Promise<void>
+```
+
 ## 테이블 DDL
 
 ```typescript
@@ -95,6 +104,49 @@ await db.switchFk({ name: "user" }, false); // FK 비활성화
 await db.switchFk({ name: "user" }, true);  // FK 활성화
 ```
 
+## DDL 메서드 API
+
+### 테이블/뷰/프로시저
+
+| 메서드 | 시그니처 | 설명 |
+|--------|---------|------|
+| `createTable` | `(table: TableBuilder) => Promise<void>` | 테이블 생성 |
+| `dropTable` | `(table: QueryDefObjectName) => Promise<void>` | 테이블 삭제 |
+| `renameTable` | `(table: QueryDefObjectName, newName: string) => Promise<void>` | 테이블 이름 변경 |
+| `createView` | `(view: ViewBuilder) => Promise<void>` | 뷰 생성 |
+| `dropView` | `(view: QueryDefObjectName) => Promise<void>` | 뷰 삭제 |
+| `createProc` | `(proc: ProcedureBuilder) => Promise<void>` | 프로시저 생성 |
+| `dropProc` | `(proc: QueryDefObjectName) => Promise<void>` | 프로시저 삭제 |
+
+### 컬럼
+
+| 메서드 | 시그니처 | 설명 |
+|--------|---------|------|
+| `addColumn` | `(table, columnName, column: ColumnBuilder) => Promise<void>` | 컬럼 추가 |
+| `dropColumn` | `(table, column: string) => Promise<void>` | 컬럼 삭제 |
+| `modifyColumn` | `(table, columnName, column: ColumnBuilder) => Promise<void>` | 컬럼 수정 |
+| `renameColumn` | `(table, column, newName) => Promise<void>` | 컬럼 이름 변경 |
+
+### 키/인덱스
+
+| 메서드 | 시그니처 | 설명 |
+|--------|---------|------|
+| `addPrimaryKey` | `(table, columns: string[]) => Promise<void>` | PK 추가 |
+| `dropPrimaryKey` | `(table) => Promise<void>` | PK 삭제 |
+| `addForeignKey` | `(table, relationName, relationDef) => Promise<void>` | FK 추가 |
+| `dropForeignKey` | `(table, relationName) => Promise<void>` | FK 삭제 |
+| `addIndex` | `(table, indexBuilder) => Promise<void>` | 인덱스 추가 |
+| `dropIndex` | `(table, columns: string[]) => Promise<void>` | 인덱스 삭제 |
+
+### 스키마
+
+| 메서드 | 시그니처 | 설명 |
+|--------|---------|------|
+| `schemaExists` | `(database, schema?) => Promise<boolean>` | 스키마 존재 여부 |
+| `clearSchema` | `(params: { database, schema? }) => Promise<void>` | 스키마 내 모든 테이블 삭제 |
+| `truncate` | `(table) => Promise<void>` | 테이블 TRUNCATE |
+| `switchFk` | `(table, enabled: boolean) => Promise<void>` | FK 제약조건 on/off |
+
 ## 연결 & 트랜잭션
 
 ```typescript
@@ -121,6 +173,14 @@ await db.connectWithoutTransaction(async () => {
 });
 ```
 
+### 연결 API
+
+| 메서드 | 시그니처 | 설명 |
+|--------|---------|------|
+| `connect` | `(fn, isolationLevel?) => Promise<T>` | 자동 트랜잭션 (connect -> begin -> fn -> commit/rollback -> close) |
+| `connectWithoutTransaction` | `(fn) => Promise<T>` | 트랜잭션 없이 연결 (DDL용) |
+| `transaction` | `(fn, isolationLevel?) => Promise<T>` | 수동 트랜잭션 (connectWithoutTransaction 내에서) |
+
 격리 수준: `"READ_UNCOMMITTED"`, `"READ_COMMITTED"`, `"REPEATABLE_READ"`, `"SERIALIZABLE"`
 
 ## DbContextExecutor 인터페이스
@@ -163,6 +223,15 @@ const MyDb = defineDbContext({
 });
 ```
 
+### Migration 인터페이스
+
+```typescript
+interface Migration {
+  name: string;
+  up: (db: DbContextBase & DbContextDdlMethods) => Promise<void>;
+}
+```
+
 실행된 마이그레이션은 `_migration` 테이블에 기록된다.
 
 ```typescript
@@ -184,6 +253,17 @@ import { DbTransactionError, DbErrorCode } from "@simplysm/orm-common";
 // - LOCK_TIMEOUT: 잠금 타임아웃
 ```
 
+### DbTransactionError API
+
+```typescript
+class DbTransactionError extends Error {
+  readonly name: "DbTransactionError";
+  readonly code: DbErrorCode;
+  readonly originalError?: unknown;
+  constructor(code: DbErrorCode, message: string, originalError?: unknown);
+}
+```
+
 ## QueryDef 생성기
 
 DDL 메서드 외에도 `get*QueryDef()` 메서드로 QueryDef만 생성할 수 있다 (직접 실행하지 않음).
@@ -193,3 +273,28 @@ const def = db.getCreateTableQueryDef(User);
 const def2 = db.getAddColumnQueryDef({ name: "user" }, "phone", c.varchar(20));
 // ... 등. 모든 DDL 메서드에 대응하는 get*QueryDef() 메서드가 있다.
 ```
+
+| 생성기 | 대응 DDL 메서드 |
+|--------|---------------|
+| `getCreateTableQueryDef` | `createTable` |
+| `getCreateViewQueryDef` | `createView` |
+| `getCreateProcQueryDef` | `createProc` |
+| `getCreateObjectQueryDef` | Table/View/Procedure 자동 판별 |
+| `getDropTableQueryDef` | `dropTable` |
+| `getRenameTableQueryDef` | `renameTable` |
+| `getDropViewQueryDef` | `dropView` |
+| `getDropProcQueryDef` | `dropProc` |
+| `getAddColumnQueryDef` | `addColumn` |
+| `getDropColumnQueryDef` | `dropColumn` |
+| `getModifyColumnQueryDef` | `modifyColumn` |
+| `getRenameColumnQueryDef` | `renameColumn` |
+| `getAddPrimaryKeyQueryDef` | `addPrimaryKey` |
+| `getDropPrimaryKeyQueryDef` | `dropPrimaryKey` |
+| `getAddForeignKeyQueryDef` | `addForeignKey` |
+| `getAddIndexQueryDef` | `addIndex` |
+| `getDropForeignKeyQueryDef` | `dropForeignKey` |
+| `getDropIndexQueryDef` | `dropIndex` |
+| `getClearSchemaQueryDef` | `clearSchema` |
+| `getSchemaExistsQueryDef` | `schemaExists` |
+| `getTruncateQueryDef` | `truncate` |
+| `getSwitchFkQueryDef` | `switchFk` |

package/docs/query.md

@@ -29,6 +29,61 @@ const hasAdmin = await db.user()
   .exists();
 ```
 
+### Queryable API
+
+#### 실행 메서드
+
+| 메서드 | 시그니처 | 설명 |
+|--------|---------|------|
+| `execute` | `() => Promise<TData[]>` | SELECT 실행, 결과 배열 반환 |
+| `single` | `() => Promise<TData \| undefined>` | 단건 반환 (2건 이상이면 throw) |
+| `first` | `() => Promise<TData \| undefined>` | 첫 번째 결과 반환 |
+| `count` | `(fn?) => Promise<number>` | 행 수 반환. distinct/groupBy 이후에는 wrap() 필요 |
+| `exists` | `() => Promise<boolean>` | 데이터 존재 여부 |
+
+#### 조건 메서드 (체이닝)
+
+| 메서드 | 시그니처 | 설명 |
+|--------|---------|------|
+| `where` | `(fn: (cols) => WhereExprUnit[]) => Queryable` | WHERE 조건 (여러 번 호출 시 AND 결합) |
+| `search` | `(fn: (cols) => ExprUnit[], text: string) => Queryable` | 텍스트 검색 |
+| `orderBy` | `(fn: (cols) => ExprUnit, dir?) => Queryable` | 정렬 (기본 ASC, 여러 번 호출 가능) |
+| `top` | `(count: number) => Queryable` | 상위 N건 (ORDER BY 없이 사용 가능) |
+| `limit` | `(skip: number, take: number) => Queryable` | 페이징 (ORDER BY 필수) |
+| `select` | `(fn: (cols) => Record) => Queryable` | 컬럼 선택/변환 |
+| `distinct` | `() => Queryable` | 중복 제거 |
+| `lock` | `() => Queryable` | FOR UPDATE 잠금 |
+| `groupBy` | `(fn: (cols) => ExprUnit[]) => Queryable` | 그룹화 |
+| `having` | `(fn: (cols) => WhereExprUnit[]) => Queryable` | 그룹 필터링 |
+
+#### JOIN 메서드
+
+| 메서드 | 시그니처 | 설명 |
+|--------|---------|------|
+| `join` | `(as, fn: (qr, cols) => Queryable) => Queryable` | LEFT JOIN (1:N, 배열) |
+| `joinSingle` | `(as, fn: (qr, cols) => Queryable) => Queryable` | LEFT JOIN (N:1, 단일 객체) |
+| `include` | `(fn: (item) => PathProxy) => Queryable` | 관계 기반 자동 JOIN |
+
+#### 서브쿼리/유틸리티
+
+| 메서드 | 시그니처 | 설명 |
+|--------|---------|------|
+| `wrap` | `() => Queryable` | 서브쿼리로 래핑 |
+| `Queryable.union` | `(...queries) => Queryable` | UNION (최소 2개) |
+| `recursive` | `(fn: (cte) => Queryable) => Queryable` | 재귀 CTE |
+
+#### CUD 메서드
+
+| 메서드 | 시그니처 | 설명 |
+|--------|---------|------|
+| `insert` | `(records, outputColumns?) => Promise` | INSERT (1000건 단위 자동 분할) |
+| `insertIfNotExists` | `(record, outputColumns?) => Promise` | 조건부 INSERT |
+| `insertInto` | `(targetTable, outputColumns?) => Promise` | INSERT INTO ... SELECT |
+| `update` | `(fn: (cols) => Record, outputColumns?) => Promise` | UPDATE |
+| `delete` | `(outputColumns?) => Promise` | DELETE |
+| `upsert` | `(updateFn, insertFn?, outputColumns?) => Promise` | UPSERT (UPDATE or INSERT) |
+| `switchFk` | `(enabled: boolean) => Promise<void>` | FK 제약조건 on/off |
+
 ### 필터링 (WHERE)
 
 ```typescript
@@ -60,7 +115,7 @@ db.user()
   .search((c) => [c.name, c.email], "John +admin -withdrawn")
 ```
 
-검색 문법: `term`(OR), `+term`(AND 필수), `-term`(NOT 제외), `"exact"`(정확히), `wild*`(접두사). 내부적으로 `parseSearchQuery()`를 사용하여 SQL LIKE 패턴으로 변환한다.
+검색 문법: `term`(OR), `+term`(AND 필수), `-term`(NOT 제외), `"exact"`(정확히 + 필수), `wild*`(접두사). 내부적으로 `parseSearchQuery()`를 사용하여 SQL LIKE 패턴으로 변환한다.
 
 ### 정렬 (ORDER BY)
 
@@ -252,6 +307,12 @@ await db.user()
   .where((c) => [expr.eq(c.id, 1)])
   .update((c) => ({ name: expr.val("string", "Alice2") }));
 
+// 기존 값 참조
+await db.product()
+  .update((p) => ({
+    price: expr.mul(p.price, expr.val("number", 1.1)),
+  }));
+
 // OUTPUT으로 변경된 데이터 반환
 const updated = await db.user()
   .where((c) => [expr.eq(c.id, 1)])
@@ -320,15 +381,25 @@ await db.connect(async () => {
 });
 ```
 
+### Executable API
+
+| 메서드 | 시그니처 | 설명 |
+|--------|---------|------|
+| `execute` | `(params) => Promise<TReturns[][]>` | 프로시저 실행 |
+| `getExecProcQueryDef` | `(params?) => QueryDef` | QueryDef만 생성 (실행 안 함) |
+
 ---
 
 ## expr -- 표현식 빌더
 
+방언 독립적인 SQL 표현식을 생성한다. JSON AST(Expr)를 생성하며, QueryBuilder가 각 DBMS(MySQL, MSSQL, PostgreSQL)에 맞게 변환한다.
+
 ### 값/조건
 
 | 함수 | 설명 |
 |------|------|
 | `expr.val(type, value)` | 리터럴 값 |
+| `expr.col(type, alias, key)` | 컬럼 참조 |
 | `expr.raw(type)\`sql\`` | Raw SQL (태그 템플릿) |
 | `expr.eq(a, b)` | `=` (NULL 안전) |
 | `expr.gt(a, b)` | `>` |
@@ -449,6 +520,29 @@ expr.maxOver(c.amount, { partitionBy: [c.dept] })
 
 ---
 
+## ExprUnit / WhereExprUnit
+
+Queryable 콜백에서 컬럼 참조 시 자동으로 `ExprUnit`으로 래핑된다.
+
+```typescript
+// ExprUnit<TPrimitive> -- 타입 안전한 표현식 래퍼
+class ExprUnit<TPrimitive extends ColumnPrimitive> {
+  readonly dataType: ColumnPrimitiveStr;
+  readonly expr: Expr;
+  get n(): ExprUnit<NonNullable<TPrimitive>>;  // nullable 제거
+}
+
+// WhereExprUnit -- WHERE 절용 표현식 래퍼
+class WhereExprUnit {
+  readonly expr: WhereExpr;
+}
+
+// ExprInput -- ExprUnit 또는 리터럴 값을 받는 입력 타입
+type ExprInput<TPrimitive> = ExprUnit<TPrimitive> | TPrimitive;
+```
+
+---
+
 ## 검색 파서
 
 사용자 검색 문법을 SQL LIKE 패턴으로 변환.
@@ -464,6 +558,87 @@ parseSearchQuery('apple +fruit -rotten "green apple" wild*');
 // }
 ```
 
+### parseSearchQuery API
+
+```
+parseSearchQuery(searchText: string): ParsedSearchQuery
+
+interface ParsedSearchQuery {
+  or: string[];    // OR 조건 (LIKE 패턴)
+  must: string[];  // AND 필수 조건 (LIKE 패턴)
+  not: string[];   // NOT 제외 조건 (LIKE 패턴)
+}
+```
+
 문법: `term`(OR), `+term`(AND 필수), `-term`(NOT 제외), `"exact"`(정확히 + 필수), `wild*`(접두사)
 
 이스케이프: `\\` (리터럴 `\`), `\*` (리터럴 `*`), `\%` (리터럴 `%`), `\"` (리터럴 `"`), `\+` (리터럴 `+`), `\-` (리터럴 `-`)
+
+---
+
+## QueryBuilder
+
+QueryDef(JSON AST)를 DBMS별 SQL 문자열로 변환한다.
+
+```typescript
+import { createQueryBuilder } from "@simplysm/orm-common";
+import type { Dialect } from "@simplysm/orm-common";
+
+const builder = createQueryBuilder("mysql");  // "mysql" | "mssql" | "postgresql"
+const result = builder.build(queryDef);
+// result.sql -> SQL 문자열
+```
+
+### createQueryBuilder API
+
+```
+createQueryBuilder(dialect: Dialect): QueryBuilderBase
+```
+
+| 방언 | 구현 클래스 |
+|------|-----------|
+| `"mysql"` | `MysqlQueryBuilder` |
+| `"mssql"` | `MssqlQueryBuilder` |
+| `"postgresql"` | `PostgresqlQueryBuilder` |
+
+---
+
+## parseQueryResult
+
+DB 쿼리 결과를 ResultMeta 기반으로 TypeScript 객체로 변환한다. 타입 파싱과 JOIN 결과 중첩을 처리한다.
+
+```typescript
+import { parseQueryResult } from "@simplysm/orm-common";
+
+// 단순 타입 파싱
+const raw = [{ id: "1", createdAt: "2026-01-07T10:00:00.000Z" }];
+const meta = { columns: { id: "number", createdAt: "DateTime" }, joins: {} };
+const result = await parseQueryResult(raw, meta);
+// [{ id: 1, createdAt: DateTime(...) }]
+
+// JOIN 결과 중첩
+const raw2 = [
+  { id: 1, name: "User1", "posts.id": 10, "posts.title": "Post1" },
+  { id: 1, name: "User1", "posts.id": 11, "posts.title": "Post2" },
+];
+const meta2 = {
+  columns: { id: "number", name: "string", "posts.id": "number", "posts.title": "string" },
+  joins: { posts: { isSingle: false } },
+};
+const result2 = await parseQueryResult(raw2, meta2);
+// [{ id: 1, name: "User1", posts: [{ id: 10, title: "Post1" }, { id: 11, title: "Post2" }] }]
+```
+
+### parseQueryResult API
+
+```
+parseQueryResult<TRecord>(
+  rawResults: Record<string, unknown>[],
+  meta: ResultMeta,
+): Promise<TRecord[] | undefined>
+
+interface ResultMeta {
+  columns: Record<string, ColumnPrimitiveStr>;
+  joins: Record<string, { isSingle: boolean }>;
+}
+```

package/docs/schema.md

@@ -37,6 +37,22 @@ const User = Table("user")
   }));
 ```
 
+### Table API
+
+```
+Table(name: string): TableBuilder
+```
+
+| 메서드 | 시그니처 | 설명 |
+|--------|---------|------|
+| `description` | `(desc: string) => TableBuilder` | 테이블 설명 (DDL 코멘트) |
+| `database` | `(db: string) => TableBuilder` | 데이터베이스 이름 |
+| `schema` | `(schema: string) => TableBuilder` | 스키마 이름 (MSSQL: dbo, PostgreSQL: public) |
+| `columns` | `(fn: (c) => Record) => TableBuilder` | 컬럼 정의 |
+| `primaryKey` | `(...columns: string[]) => TableBuilder` | PK 설정 (복합 PK 지원) |
+| `indexes` | `(fn: (i) => IndexBuilder[]) => TableBuilder` | 인덱스 정의 |
+| `relations` | `(fn: (r) => Record) => TableBuilder` | 관계 정의 |
+
 ### 컬럼 타입
 
 | 메서드 | SQL 타입 | TypeScript 타입 |
@@ -115,6 +131,22 @@ View에서도 사용 가능. DB에 FK 제약조건을 생성하지 않는다.
 }))
 ```
 
+### 관계 빌더 API
+
+| 빌더 | 용도 | DB FK 생성 |
+|------|------|----------|
+| `ForeignKeyBuilder` | N:1 관계 (FK 컬럼 소유) | O |
+| `ForeignKeyTargetBuilder` | 1:N / 1:1 역참조 | O (대상 테이블) |
+| `RelationKeyBuilder` | N:1 논리적 관계 | X |
+| `RelationKeyTargetBuilder` | 1:N / 1:1 논리적 역참조 | X |
+
+공통 메서드:
+
+| 메서드 | 설명 |
+|--------|------|
+| `.description(desc)` | 관계 설명 |
+| `.single()` | 1:1 관계 (ForeignKeyTargetBuilder, RelationKeyTargetBuilder만 해당) |
+
 ---
 
 ## View
@@ -139,6 +171,20 @@ const UserSummary = View("user_summary")
   }));
 ```
 
+### View API
+
+```
+View(name: string): ViewBuilder
+```
+
+| 메서드 | 시그니처 | 설명 |
+|--------|---------|------|
+| `description` | `(desc: string) => ViewBuilder` | 뷰 설명 |
+| `database` | `(db: string) => ViewBuilder` | 데이터베이스 이름 |
+| `schema` | `(schema: string) => ViewBuilder` | 스키마 이름 |
+| `query` | `(viewFn: (db) => Queryable) => ViewBuilder` | 뷰 쿼리 정의 |
+| `relations` | `(fn: (r) => Record) => ViewBuilder` | 관계 정의 (relationKey만 가능) |
+
 **DbContext 등록:**
 
 ```typescript
@@ -173,6 +219,21 @@ const GetUserOrders = Procedure("get_user_orders")
   `);
 ```
 
+### Procedure API
+
+```
+Procedure(name: string): ProcedureBuilder
+```
+
+| 메서드 | 시그니처 | 설명 |
+|--------|---------|------|
+| `description` | `(desc: string) => ProcedureBuilder` | 프로시저 설명 |
+| `database` | `(db: string) => ProcedureBuilder` | 데이터베이스 이름 |
+| `schema` | `(schema: string) => ProcedureBuilder` | 스키마 이름 |
+| `params` | `(fn: (c) => Record) => ProcedureBuilder` | 파라미터 정의 |
+| `returns` | `(fn: (c) => Record) => ProcedureBuilder` | 반환 타입 정의 |
+| `body` | `(sql: string) => ProcedureBuilder` | 프로시저 본문 SQL |
+
 **DbContext 등록:**
 
 ```typescript
@@ -197,6 +258,16 @@ MSSQL은 파라미터에 `@` 접두사 필요: `@userId`, `@fromDate`
 ])
 ```
 
+### IndexBuilder API
+
+| 메서드 | 시그니처 | 설명 |
+|--------|---------|------|
+| `index` | `(...columns: string[]) => IndexBuilder` | 인덱스 생성 (단일/복합) |
+| `unique` | `() => IndexBuilder` | 유니크 인덱스 설정 |
+| `orderBy` | `(...dirs: ("ASC"\|"DESC")[]) => IndexBuilder` | 컬럼별 정렬 방향 |
+| `name` | `(name: string) => IndexBuilder` | 커스텀 인덱스 이름 |
+| `description` | `(desc: string) => IndexBuilder` | 인덱스 설명 |
+
 ---
 
 ## defineDbContext / createDbContext
@@ -235,4 +306,20 @@ const db = createDbContext(MyDb, executor, {
 });
 ```
 
+```
+createDbContext(
+  def: DbContextDef,
+  executor: DbContextExecutor,
+  opt: { database: string; schema?: string },
+): DbContextInstance
+```
+
 `executor`는 `DbContextExecutor` 인터페이스를 구현해야 한다 (`@simplysm/orm-node`의 `NodeDbContextExecutor` 등).
+
+생성된 인스턴스는 다음을 포함한다:
+- 등록된 테이블/뷰에 대한 `Queryable` 접근자 (예: `db.user()`, `db.order()`)
+- 등록된 프로시저에 대한 `Executable` 접근자 (예: `db.getUserOrders()`)
+- 연결/트랜잭션 관리 메서드
+- DDL 실행 메서드
+- `initialize()` 메서드
+- `_migration()` 시스템 테이블 접근자

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/orm-common",
-  "version": "13.0.93",
+  "version": "13.0.96",
   "description": "Simplysm Package - ORM Module (common)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -20,6 +20,6 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@simplysm/core-common": "13.0.93"
+    "@simplysm/core-common": "13.0.96"
   }
 }