@simplysm/sd-claude 14.0.98 → 14.0.99

package/claude/references/sd-simplysm14/apis/orm-common/db-context.md

@@ -1,128 +1,162 @@
-# @simplysm/orm-common — DbContext / 연결·트랜잭션·DDL·마이그레이션
+# @simplysm/orm-common — db-context
 
-`DbContext` 추상 클래스를 상속해 테이블·뷰·프로시저를 클래스 프로퍼티로 등록하고, 연결·트랜잭션·DDL·마이그레이션을 실행하는 묶음. 생성자에 `DbContextExecutor` 구현체와 `{ database, schema? }` 옵션을 주입한다. 각 프로퍼티가 독립적으로 직렬화되므로 40+ 테이블에서도 TS7056 이 발생하지 않는다. 롤백 중 발생하는 트랜잭션 에러는 `DbTransactionError` 로 표준화된다.
+`DbContext` 를 상속해 테이블·뷰·프로시저를 프로퍼티로 등록하고, 연결·트랜잭션 경계·DDL·마이그레이션을 다루는 군. 실제 DB I/O 는 생성자에 주입하는 `DbContextExecutor` 가 담당하고, `DbContext` 는 QueryDef 생성·트랜잭션 상태 관리·DDL 실행 오케스트레이션만 한다.
 
-## DbContext (abstract class)
+## DbContext
 
 ```typescript
 abstract class DbContext implements DbContextBase {
+  status: DbContextStatus;             // "ready" | "connect" | "transact"
+  migrations: Migration[];             // 서브클래스에서 오버라이드
   constructor(executor: DbContextExecutor, opt: { database: string; schema?: string });
-  status: DbContextStatus;            // "ready" | "connect" | "transact"
-  get database(): string | undefined;
-  get schema(): string | undefined;
-  migrations: Migration[];            // 서브클래스에서 오버라이드
-}
-```
 
-서브클래스에서 `protected queryable(builder)` / `protected executable(builder)` 로 멤버를 등록한다.
+  protected queryable<T extends TableBuilder | ViewBuilder>(builder: T): () => Queryable<...>;
+  protected executable<T extends ProcedureBuilder>(builder: T): () => Executable<...>;
 
-- `executor`: `DbContextExecutor` — 실제 connect/close/begin/commit/rollback/executeDefs 를 수행하는 어댑터. 서버는 node 구현, 클라이언트는 service-client 구현을 넣는다.
-- `opt.database`: string — 대상 데이터베이스 이름. `database` getter 로 노출.
-- `opt.schema`: string — MSSQL/PostgreSQL 스키마(선택). 미지정 시 dialect 기본값.
-- `status`: `"ready" | "connect" | "transact"` — 현재 연결 단계. "ready"=미연결, "connect"=연결됨(트랜잭션 밖), "transact"=트랜잭션 중. `transact` 상태에서 DDL 실행 시 throw.
-- `migrations`: `Migration[]` — 서브클래스에서 오버라이드하는 마이그레이션 정의 배열. `initialize()` 가 이미 적용된 것을 제외하고 순서대로 실행.
+  connect<R>(fn: () => Promise<R>, isolationLevel?: IsolationLevel): Promise<R>;
+  connectWithoutTransaction<R>(callback: () => Promise<R>): Promise<R>;
+  transaction<R>(fn: () => Promise<R>, isolationLevel?: IsolationLevel): Promise<R>;
+  initialize(options?: { dbs?: string[]; force?: boolean }): Promise<boolean>;
+  // + DDL 실행 메서드 / DDL QueryDef 생성기 (아래)
+}
+```
 
-### 멤버 등록 (protected)
+### 등록 메서드 (protected — 서브클래스에서 프로퍼티 정의용)
 
-- `queryable(builder)` — `TableBuilder`/`ViewBuilder` 를 받아 `() => Queryable<...>` 팩토리를 반환. 호출할 때마다 새 alias 가 부여된 Queryable 생성. CUD 는 `TableBuilder` 기반에서만 가능.
-- `executable(builder)` — `ProcedureBuilder` 를 받아 `() => Executable<...>` 팩토리를 반환.
+- `this.queryable(builder)` — Table/View 빌더를 등록해 `() => Queryable` 팩토리를 반환. 호출할 때마다 새 alias 가 부여됨. 각 테이블을 별도 프로퍼티로 두면 40+ 테이블에서도 TS7056 직렬화 한계를 피함.
+- `this.executable(builder)` — Procedure 빌더를 등록해 `() => Executable` 팩토리를 반환.
 
 ```typescript
-class AppDb extends DbContext {
+class MainDb extends DbContext {
   user = this.queryable(User);
-  activeUsers = this.queryable(ActiveUsers); // View
-  getUserById = this.executable(GetUserById); // Procedure
-  override migrations = [{ name: "001_init", up: async (db) => { await db.createTable(User); } }];
+  post = this.queryable(Post);
+  activeUsers = this.queryable(ActiveUsers);
+  getUserById = this.executable(GetUserById);
+
+  migrations = [{ name: "001", up: async (db) => { await db.createTable(User); } }];
 }
-const db = new AppDb(executor, { database: "mydb" });
+const db = new MainDb(executor, { database: "mydb" });
 ```
 
-### 연결·트랜잭션
+### 연결·트랜잭션 경계
 
-- `connect(fn, isolationLevel?)` — 연결 → 트랜잭션 시작 → `fn` 실행 → 성공 시 commit, 예외 시 rollback 후 재throw → 최종 close. `ready` 가 아니면 throw. 최초 호출 시 관계 정의를 1회 검증. 업무 단위의 표준 진입점.
-- `connectWithoutTransaction(callback)` — 트랜잭션 없이 연결만 잡고 `callback` 실행 후 close. DDL·초기화처럼 트랜잭션 밖에서 실행해야 하는 작업용.
-- `transaction(fn, isolationLevel?)` — 이미 `connect` 상태에서 추가 트랜잭션 경계를 잡을 때. `transact` 상태면 throw. 성공 시 commit, 예외 시 rollback.
-- `isolationLevel`: `"READ_UNCOMMITTED" | "READ_COMMITTED" | "REPEATABLE_READ" | "SERIALIZABLE"` — 격리 수준(선택). 미지정 시 DB 기본값(보통 READ_COMMITTED). 더티 리드 허용~완전 직렬화 순으로 엄격해짐.
+- `connect(fn, isolationLevel?)` — 연결 → `BEGIN TRANSACTION` → `fn()` → 성공 시 COMMIT, 예외 시 ROLLBACK → 항상 close. 콜백 반환값이 그대로 반환됨. `status` 가 `"ready"` 가 아니면 throw. 첫 호출 시 관계 정의 검증(`validateRelations`)을 1회 수행. **앱에서 권장하는 기본 진입점**.
+- `connectWithoutTransaction(callback)` — 트랜잭션 없이 연결만(자동 BEGIN/COMMIT 없음). 트랜잭션이 불가하거나 불필요한 작업용.
+- `transaction(fn, isolationLevel?)` — 이미 연결된(`connect`/`connectWithoutTransaction` 내부) 상태에서 트랜잭션만 따로 시작. 이미 `"transact"` 면 throw. ROLLBACK 시 활성 트랜잭션이 없으면(`NO_ACTIVE_TRANSACTION`) 그 에러는 무시하고 원본 에러를 던짐.
+- `isolationLevel` — `READ_UNCOMMITTED`/`READ_COMMITTED`/`REPEATABLE_READ`/`SERIALIZABLE`. 미지정 시 executor 기본값.
 
 ```typescript
-await db.connect(async () => {
-  const users = await db.user().where((u) => [expr.eq(u.isActive, true)]).execute();
-  await db.user().where((u) => [expr.eq(u.id, 1)]).update((u) => ({ name: "수정" }));
-}); // 콜백 정상 종료 시 commit, throw 시 rollback
+const users = await db.connect(async () => {
+  return db.user().where((u) => [expr.eq(u.isActive, true)]).execute();
+});
 ```
 
-### DDL 실행 메서드 (트랜잭션 밖에서만)
+### DbContextBase 핵심 메서드 (executor·내부에서 사용)
+
+- `database` / `schema` — 생성자 옵션 게터.
+- `getNextAlias()` — `T1`, `T2`, ... 순차 alias 발급. `resetAliasCounter()` 로 초기화(연결 시작 시 자동).
+- `executeDefs<T>(defs, resultMetas?)` — QueryDef 배열을 executor 로 실행. `"transact"` 상태에서 DDL 타입(`DDL_TYPES`)이 섞이면 throw.
+- `getQueryDefObjectName(tableOrView)` — 빌더 → `{ database?, schema?, name }` 변환.
+- `switchFk(table, enabled)` — FK 제약 활성/비활성(트랜잭션 내 사용 가능, DDL 아님).
+
+### DDL 실행 메서드 (Promise<void>)
 
-각각 `executeDefs` 로 즉시 실행한다. `transact` 상태에서 호출하면 throw.
+`executeDefs` 로 즉시 실행. `"transact"` 상태에서는 DDL 차단됨.
 
-- `createTable(table)` / `dropTable(name)` / `renameTable(name, newName)` — 테이블 생성/삭제/이름변경.
-- `truncate(name)` — 테이블 비우기(전 행 삭제, identity 리셋).
-- `createView(view)` / `dropView(name)` — 뷰 생성/삭제.
-- `createProc(procedure)` / `dropProc(name)` — 프로시저 생성/삭제.
-- `addColumn(table, columnName, column)` / `dropColumn(table, column)` / `modifyColumn(table, columnName, column)` / `renameColumn(table, column, newName)` — 컬럼 변경. `column` 은 `ColumnBuilder`.
-- `addPrimaryKey(table, columns)` / `dropPrimaryKey(table)` — PK 추가/삭제. `columns` 는 컬럼명 배열(복합 PK).
-- `addForeignKey(table, relationName, relationDef)` / `dropForeignKey(table, relationName)` — FK 추가/삭제. `relationDef` 는 `ForeignKeyBuilder`.
-- `addIndex(table, indexBuilder)` / `dropIndex(table, columns)` — 인덱스 추가/삭제.
-- `clearSchema({ database, schema? })` — 스키마 내 모든 객체 삭제.
-- `schemaExists(database, schema?)` — 스키마 존재 여부 `boolean` 반환.
-- `switchFk(table, enabled)` — FK 제약 활성/비활성 토글. `enabled` true=활성, false=비활성. DDL 이 아니라 `transact` 상태에서도 호출 가능(대량 적재 시 FK 일시 해제 용도).
-- `getQueryDefObjectName(tableOrView)` — 빌더에서 dialect 네임스페이스가 반영된 `QueryDefObjectName` 산출.
+- 테이블: `createTable(table)` / `dropTable(name)` / `renameTable(name, newName)` / `truncate(name)`
+- 뷰: `createView(view)` / `dropView(name)`
+- 프로시저: `createProc(proc)` / `dropProc(name)`
+- 컬럼: `addColumn(name, columnName, column)` / `dropColumn(name, column)` / `modifyColumn(name, columnName, column)` / `renameColumn(name, column, newName)`
+- 키·인덱스: `addPrimaryKey(name, columns)` / `dropPrimaryKey(name)` / `addForeignKey(name, relationName, relationDef)` / `dropForeignKey(name, relationName)` / `addIndex(name, indexBuilder)` / `dropIndex(name, columns)`
+- 스키마: `clearSchema({ database, schema? })` / `schemaExists(database, schema?): Promise<boolean>`
+- `switchFk(name, enabled)` — DDL 아님(트랜잭션 내 가능).
 
-### DDL QueryDef 생성기 (실행 없이 def 만)
+### DDL QueryDef 생성기 (`get*QueryDef`)
 
-위 실행 메서드와 1:1 대응하는 `get*QueryDef(...)` 가 모두 있다(`getCreateTableQueryDef`, `getDropTableQueryDef`, `getAddColumnQueryDef`, `getAddForeignKeyQueryDef`, `getTruncateQueryDef`, `getSwitchFkQueryDef`, `getClearSchemaQueryDef`, `getSchemaExistsQueryDef` 등). 실행하지 않고 `QueryDef` AST 만 얻어 배치 실행·검증·SQL 변환에 쓸 때 사용. 단일 `getCreateObjectQueryDef(builder)` 는 Table/View/Procedure 빌더 종류를 보고 알맞은 CREATE def 를 만든다.
+위 실행 메서드와 1:1 대응하되 실행하지 않고 `QueryDef` 만 반환. 마이그레이션·배치에서 여러 DDL 을 모아 한 번에 `executeDefs` 하거나 SQL 을 검사할 때. 예: `getCreateTableQueryDef`, `getAddColumnQueryDef`, `getAddForeignKeyQueryDef`, `getDropIndexQueryDef`, `getTruncateQueryDef`, `getSwitchFkQueryDef` 등. `getCreateObjectQueryDef(builder)` 는 Table/View/Procedure 중 무엇이든 받아 적절한 CREATE QueryDef 를 반환.
 
-### 마이그레이션 / 초기화
+### initialize
 
-- `initialize(options?)` — `migrations` 중 미적용분을 순서대로 실행하고, 적용 여부를 `_migration` 시스템 테이블에 기록. `boolean` 반환(변경 발생 여부 등).
-  - `options.dbs`: string[] — 대상 데이터베이스 목록 한정(선택).
-  - `options.force`: boolean — true 면 강제 재초기화. 스키마를 다시 깔아야 할 때만 사용.
-- `executeDefs(defs, resultMetas?)` — `QueryDef[]` 를 executor 로 실행해 `T[][]`(def 별 결과) 반환. `transact` 상태에서 DDL 타입이 섞이면 throw. 빌더가 만든 def 를 저수준으로 직접 실행할 때 사용.
+- `initialize(options?)` — DbContext 에 등록된 스키마·`migrations` 를 기준으로 DB 를 초기화/마이그레이션. `options.dbs` 로 대상 DB 제한, `options.force` 로 강제 재생성. 변경이 있었으면 `true` 반환.
 
-## Migration (interface)
+## DbContextStatus
+
+```typescript
+type DbContextStatus = "ready" | "connect" | "transact";
+```
+
+- `"ready"` — 미연결. `connect`/`connectWithoutTransaction` 호출 가능.
+- `"connect"` — 연결됨, 트랜잭션 없음. `transaction` 호출 가능.
+- `"transact"` — 트랜잭션 활성. DDL 실행 차단.
+
+## DbContextExecutor
+
+`DbContext` 가 위임하는 실제 DB I/O 인터페이스. `@simplysm/orm-node`(서버)·orm-service 클라이언트 등이 구현.
+
+```typescript
+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[][]>;
+}
+```
+
+- `executeDefs(defs, resultMetas?)` — QueryDef 배열을 SQL 로 빌드·실행. `resultMetas[i]` 가 주어진 def 의 결과는 `parseQueryResult` 로 타입 변환/중첩되고, 없으면 원시 결과 그대로. 반환은 def 별 결과 배열의 배열.
+
+## Migration
 
 ```typescript
 interface Migration {
-  name: string;
+  name: string;                                              // 고유 이름 (타임스탬프 권장)
   up: (db: DbContextBase & DbContextDdlMethods) => Promise<void>;
 }
 ```
 
-- `name`: string — 고유 마이그레이션 식별자. 타임스탬프 접두 권장(`20260105_001_...`). 이 값으로 적용 여부를 추적하므로 한번 배포되면 변경 금지.
-- `up`: `(db) => Promise<void>` — 스키마 변경 함수. `db` 로 DDL 메서드를 호출. 실행은 `initialize()` 가 미적용분만 골라 호출.
+- `name` — 적용 여부를 추적하는 고유 키. 적용된 이름은 `_migration` 시스템 테이블에 적재됨.
+- `up(db)` — 스키마 변경을 수행하는 함수. `db` 로 DDL 실행 메서드 사용.
+
+```typescript
+migrations = [
+  { name: "20260105_001_create_user", up: async (db) => { await db.createTable(User); } },
+  { name: "20260105_002_add_email", up: async (db) => {
+    await db.addColumn(User, "email", { type: "varchar", length: 200 });
+  } },
+];
+```
 
 ## DbTransactionError / DbErrorCode
 
-DBMS 네이티브 에러를 dialect 독립 코드로 래핑한다. `connect`/`transaction` 의 롤백 단계에서 "이미 롤백되어 활성 트랜잭션이 없음" 같은 상황을 코드로 식별해 무시 여부를 판단할 때 쓴다.
+DBMS 별 네이티브 에러를 표준 코드로 래핑. ROLLBACK 시 활성 트랜잭션 없음 등을 코드로 분기.
 
 ```typescript
 class DbTransactionError extends Error {
+  readonly name = "DbTransactionError";
   constructor(code: DbErrorCode, message: string, originalError?: unknown);
   readonly code: DbErrorCode;
   readonly originalError?: unknown;
 }
-enum DbErrorCode { NO_ACTIVE_TRANSACTION, TRANSACTION_ALREADY_STARTED, DEADLOCK, LOCK_TIMEOUT }
+enum DbErrorCode {
+  NO_ACTIVE_TRANSACTION = "NO_ACTIVE_TRANSACTION",       // ROLLBACK 시 활성 트랜잭션 없음
+  TRANSACTION_ALREADY_STARTED = "TRANSACTION_ALREADY_STARTED",
+  DEADLOCK = "DEADLOCK",                                  // 데드락
+  LOCK_TIMEOUT = "LOCK_TIMEOUT",                          // 잠금 타임아웃
+}
 ```
 
-- `code`: `DbErrorCode` — 표준화된 에러 종류. 아래 enum literal 로 분기.
-- `originalError`: unknown — 래핑 전 원본 DBMS 에러(디버깅용). dialect 별 원인 추적 시 참조.
-- `NO_ACTIVE_TRANSACTION` — 롤백/커밋할 활성 트랜잭션이 없음. 이미 롤백된 경우 무시 분기에 사용.
-- `TRANSACTION_ALREADY_STARTED` — 트랜잭션이 이미 시작됨(중첩 시작 시도).
-- `DEADLOCK` — 교착 상태로 트랜잭션이 강제 중단됨. 재시도 정책 분기에 사용.
-- `LOCK_TIMEOUT` — 잠금 대기 시간 초과. 재시도/백오프 분기에 사용.
+- `code` — DBMS 독립 분류. `connect`/`transaction` 의 롤백 로직이 `NO_ACTIVE_TRANSACTION` 을 무시하는 데 사용.
+- `originalError` — 원본 DBMS 에러(디버깅용).
 
-```typescript
-try {
-  await db.rollbackTransaction();
-} catch (err) {
-  if (err instanceof DbTransactionError && err.code === DbErrorCode.NO_ACTIVE_TRANSACTION) return;
-  throw err;
-}
-```
+## 관련 export
+
+- `DbContextBase` / `DbContextDdlMethods` — `DbContext` 가 구현하는 핵심·DDL 인터페이스. executor·`Queryable`·`ViewBuilder` 가 의존.
+- `SD_BUILDER` — `queryable()`/`executable()` 이 반환 팩토리에 빌더를 부착하는 심볼 키(내부용).
+- `_Migration` — 적용된 마이그레이션을 기록하는 시스템 테이블 빌더(`_migration`, PK `code`).
 
-## DbContextBase / DbContextStatus / DbContextDdlMethods / SD_BUILDER
+## 주의사항
 
-- `DbContextBase` (interface) — `Queryable`/`Executable`/`ViewBuilder` 가 의존하는 컨텍스트 최소 인터페이스(`status`, `database`, `schema`, `getNextAlias`, `resetAliasCounter`, `executeDefs`, `getQueryDefObjectName`, `switchFk`). `DbContext` 가 구현한다. executor·뷰 정의처럼 컨텍스트 전체가 아니라 일부 능력만 요구하는 시그니처에 쓴다.
-- `DbContextStatus` (type) — `"ready" | "connect" | "transact"`. 위 `status` 와 동일.
-- `DbContextDdlMethods` (interface) — DDL 실행 메서드 + `get*QueryDef` 생성기를 모은 인터페이스. `Migration.up` 의 `db` 파라미터 타입(`DbContextBase & DbContextDdlMethods`)에 쓰여, 마이그레이션 함수에서 DDL 만 노출되게 한다.
-- `SD_BUILDER` (symbol) — `queryable()`/`executable()` 가 반환하는 팩토리 함수에 원본 빌더를 매다는 심볼 키. 등록된 멤버에서 원본 `TableBuilder`/`ViewBuilder`/`ProcedureBuilder` 를 역참조해야 할 때(스키마 수집·DDL 자동화 등) 사용.
+- 테이블은 반드시 **개별 프로퍼티**로(`user = this.queryable(User)`) — 한 객체에 묶으면 TS7056.
+- 앱 코드는 옵션을 흩뿌리지 말고 `connect` 경계 안에서만 쿼리 (client-orm.md 의 `AppOrmProvider` 패턴).
+- DDL 은 트랜잭션 밖에서. `transaction()` 안에서 DDL 메서드 호출 시 `executeDefs` 가 throw.

package/claude/references/sd-simplysm14/apis/orm-common/expr.md

@@ -1,111 +1,167 @@
-# @simplysm/orm-common — expr (SQL 표현식 빌더)
+# @simplysm/orm-common — expr
 
-`expr` 객체로 dialect 독립 SQL 표현식을 JSON AST(`Expr`)로 조립한다. dialect 별 QueryBuilder 가 MySQL/MSSQL/PostgreSQL 로 변환. where/having 콜백은 `WhereExprUnit[]`, select/orderBy/groupBy 콜백은 `ExprUnit<T>`, update/upsert/insert/where 비교값은 `ExprInput<T>`(= `ExprUnit<T> | T`)를 다룬다. 비교·쓰기 값은 리터럴을 그대로 넘긴다 — `expr.val` 로 감싸지 말 것(orm.md). `expr.subquery`/`expr.exists` 를 SELECT 절에 넣지 말고 `joinSingle` 로 집계를 부착한다(orm.md).
+dialect 독립 SQL 표현식 빌더 군. `expr.*` 함수가 SQL 문자열 대신 JSON AST(`Expr`)를 만들고, QueryBuilder 가 DBMS 별로 렌더링한다. `where`/`select`/`groupBy`/`orderBy`/`having`/`update` 콜백 안에서 컬럼 프록시(`ExprUnit`)를 받아 조합한다. 비교/논리 함수는 `WhereExprUnit`(WHERE 절용), 그 외는 `ExprUnit<T>`(값 표현식)를 반환한다.
 
-## 래퍼 타입
+`ExprInput<T> = ExprUnit<T> | T` — 비교 대상·값 인자는 리터럴을 그대로 받는다(`expr.val` 래핑 불필요, orm.md).
 
-- `ExprUnit<T>` — 타입 안전 표현식 래퍼. `dataType`(`ColumnPrimitiveStr`)·`expr`(`Expr` AST) 보유. getter `n` 은 동일 표현식을 non-nullable 타입(`NonNullable<T>`)으로 다시 래핑(coalesce 후 null 아님이 보장될 때 타입만 좁힐 용도).
-- `WhereExprUnit` — WHERE 절용 래퍼(`WhereExpr` AST 보유). `where`/`having` 콜백 반환 원소.
-- `ExprInput<T>` = `ExprUnit<T> | T` — 표현식 또는 리터럴 둘 다 받는 입력 타입. 비교 target·쓰기 값 자리.
-- `SwitchExprBuilder<T>` — `expr.switch()` 가 반환하는 CASE 빌더(`case`/`default`).
+## ExprUnit / WhereExprUnit / ExprInput
+
+```typescript
+class ExprUnit<TPrimitive> {
+  readonly dataType: ColumnPrimitiveStr;
+  readonly expr: Expr;
+  get n(): ExprUnit<NonNullable<TPrimitive>>;   // nullable 제거(타입만)
+}
+class WhereExprUnit { readonly expr: WhereExpr; }
+type ExprInput<TPrimitive> = ExprUnit<TPrimitive> | TPrimitive;
+```
+
+- `ExprUnit<T>` — 타입 안전 표현식 래퍼. `dataType` 은 결과 원시 타입 이름, `expr` 은 AST. 컬럼 프록시의 각 필드가 이 타입.
+- `.n` — 타입 수준에서 `undefined` 를 제거한 새 `ExprUnit`(런타임 AST 동일). nullable 컬럼을 non-null 로 단언할 때.
+- `WhereExprUnit` — `where`/`having` 가 받는 boolean 조건 래퍼.
+- `ExprInput<T>` — 표현식 또는 리터럴.
 
 ## 값 생성
 
-- `val(dataType, value)` — 리터럴을 `ExprUnit` 으로 래핑. `dataType`=`"string"|"number"|"boolean"|"DateTime"|"DateOnly"|"Time"|"Uuid"|"Buffer"` 등 원시 타입 문자열. `value`=값(undefined 허용 → NULL). `ExprUnit` 이 요구되는 자리(select 의 리터럴 상수 컬럼 등)에서만 사용.
-- `col(dataType, ...path)` — 컬럼 참조 `ExprUnit` 생성. `path`=별칭·컬럼 경로. 보통 콜백의 컬럼 프록시가 대신하므로 내부용.
-- `raw(dataType)\`...\`` — Raw SQL 이스케이프 해치. 태그드 템플릿. 보간 값은 자동 파라미터화. ORM 미지원 DB 함수·UNION 의 타입 명시 NULL(`` expr.raw("number")`NULL` ``)에 사용.
-- `toExpr(value)` — `ExprInput` 을 `Expr` AST 로 변환(내부 헬퍼).
+- `expr.val(dataType, value)` — 리터럴을 `ExprUnit` 으로 래핑. `dataType` 은 `"string"|"number"|"boolean"|"DateTime"|"DateOnly"|"Time"|"Uuid"|"Bytes"`. `value` 가 `undefined` 면 결과 타입이 nullable. **`select` 등 `ExprUnit` 이 요구되는 자리에서만** 사용(비교·CUD 값은 리터럴 직접 전달).
+- `expr.col(dataType, ...path)` — 컬럼 참조(`{ type:"column", path }`). 보통 프록시가 자동 생성하므로 직접 호출은 드묾.
+- `expr.raw(dataType)\`...\`` — Raw SQL 이스케이프 해치. 태그드 템플릿이며 보간값(`${u.x}`)은 자동 파라미터화. ORM 미지원 DB 함수·UNION NULL 자리채움(`expr.raw("number")\`NULL\``, orm-union.md)에 사용.
+- `expr.toExpr(value)` — `ExprInput` → `Expr` 변환(내부 헬퍼).
+
+```typescript
+db.user().select((u) => ({ name: u.name, label: expr.val("string", "fixed") }));
+expr.raw("string")`JSON_EXTRACT(${u.metadata}, '$.email')`;
+```
+
+## WHERE — 비교 (→ WhereExprUnit)
 
-## WHERE — 비교 (`WhereExprUnit` 반환)
+- `expr.eq(source, target)` — 동등 비교. **NULL 안전**(MySQL `<=>`, 그 외 `IS NULL OR =`).
+- `expr.gt` / `expr.lt` / `expr.gte` / `expr.lte` — `>` / `<` / `>=` / `<=`.
+- `expr.between(source, from?, to?)` — 범위(BETWEEN). `from`/`to` 가 undefined 면 그 방향 제한 없음(한쪽만 주면 `>=`/`<=`).
+- `expr.null(source)` — IS NULL.
+- `expr.like(source, pattern)` — LIKE(`%`/`_` 와일드카드, `\` 이스케이프).
+- `expr.regexp(source, pattern)` — 정규식 매칭(구문은 DBMS 의존).
+- `expr.in(source, values)` — IN 값 목록.
+- `expr.inQuery(source, query)` — IN (SELECT). 서브쿼리는 **단일 컬럼만** SELECT 해야 함(아니면 throw).
+- `expr.exists(query)` — EXISTS(서브쿼리가 1행 이상이면 true). SELECT 절을 제거해 패킷 절약.
 
-- `eq(source, target)` — `=` 비교(NULL 안전: MySQL `<=>`, 그 외 `IS NULL OR =`). NULL 끼리도 일치 판정해야 할 때.
-- `gt(source, target)` / `lt(source, target)` / `gte(source, target)` / `lte(source, target)` — `>` / `<` / `>=` / `<=`.
-- `between(source, from?, to?)` — 범위. `from` undefined 면 하한 없음, `to` undefined 면 상한 없음(한쪽만 주면 단방향 부등호).
-- `null(source)` — `IS NULL`. nullable 컬럼의 결측 판정.
+```typescript
+db.user().where((u) => [expr.eq(u.status, "active"), expr.between(u.age, 18, 65)]);
+db.user().where((u) => [expr.inQuery(u.id, db.order().select((o) => ({ userId: o.userId })))]);
+```
 
-## WHERE — 문자열/IN/논리
+## WHERE — 논리 (→ WhereExprUnit)
 
-- `like(source, pattern)` — `LIKE`(% 다수, _ 단일, `\` 이스케이프). 부분/접두/접미 검색.
-- `regexp(source, pattern)` — 정규식 매칭(구문은 DBMS 의존).
-- `in(source, values)` — `IN (값목록)`. `values`=`ExprInput[]`.
-- `inQuery(source, query)` — `IN (SELECT 단일컬럼)`. 서브쿼리가 단일 컬럼 select 가 아니면 throw.
-- `exists(query)` — `EXISTS (...)`. 서브쿼리 SELECT 절은 패킷 절약 위해 제거됨. WHERE 절 존재 검사용(SELECT 절에는 쓰지 말 것).
-- `not(arg)` — 조건 부정.
-- `and(conditions)` / `or(conditions)` — 조건 배열 AND/OR 결합. 빈 배열이면 `ArgumentError`. (`where` 에 배열을 넘기면 자동 AND 이므로 `and` 는 OR 안에서 묶을 때 등에 사용.)
+- `expr.not(arg)` — 조건 부정(NOT).
+- `expr.and(conditions)` — AND 결합. **빈 배열이면 `ArgumentError`**.
+- `expr.or(conditions)` — OR 결합. **빈 배열이면 `ArgumentError`**.
 
 ```typescript
-db.user().where((u) => [
-  expr.eq(u.status, "active"),
-  expr.between(u.age, 18, undefined),
-  expr.or([expr.like(u.name, "김%"), expr.like(u.name, "이%")]),
-])
+db.user().where((u) => [expr.or([expr.eq(u.status, "active"), expr.eq(u.status, "pending")])]);
 ```
 
-## SELECT — 문자열 (`ExprUnit` 반환)
+## SELECT — 문자열 (→ ExprUnit)
+
+- `expr.concat(...args)` — CONCAT(NULL 은 빈 문자열).
+- `expr.left(source, length)` / `expr.right(source, length)` — 왼/오른쪽 N자.
+- `expr.trim(source)` — 양쪽 공백 제거.
+- `expr.padStart(source, length, fillString)` — LPAD(목표 길이까지 왼쪽 채움).
+- `expr.replace(source, from, to)` — 치환.
+- `expr.upper(source)` / `expr.lower(source)` — 대/소문자.
+- `expr.length(source)` — 문자 수. `expr.byteLength(source)` — 바이트 수(UTF-8 CJK 3바이트).
+- `expr.substring(source, start, length?)` — 부분 문자열(**1부터 시작**).
+- `expr.indexOf(source, search)` — 위치(1부터, 없으면 0).
 
-- `concat(...args)` — `CONCAT`(NULL 은 빈 문자열 처리).
-- `left(source, length)` / `right(source, length)` — 왼쪽/오른쪽 N자 추출.
-- `trim(source)` — 양쪽 공백 제거.
-- `padStart(source, length, fillString)` — `LPAD`. `length` 도달까지 `fillString` 으로 왼쪽 패딩(주문번호 zero-pad 등).
-- `replace(source, from, to)` — 문자열 치환.
-- `upper(source)` / `lower(source)` — 대/소문자 변환.
-- `length(source)` — 문자 수. `byteLength(source)` — 바이트 수(UTF-8 CJK 3바이트).
-- `substring(source, start, length?)` — 부분 문자열(1부터 시작, `length` 생략 시 끝까지).
-- `indexOf(source, search)` — 위치 찾기(1부터, 없으면 0).
+## SELECT — 숫자 (→ ExprUnit)
 
-## SELECT — 숫자 / 날짜
+- `expr.abs(source)` — 절대값.
+- `expr.round(source, digits)` — 반올림(소수 자릿수).
+- `expr.ceil(source)` / `expr.floor(source)` — 올림/내림.
 
-- `abs(source)` / `round(source, digits)` / `ceil(source)` / `floor(source)` — 절대값/반올림(`digits`=소수자릿수)/올림/내림.
-- `year`/`month`/`day`/`hour`/`minute`/`second`(source) — 날짜·시간 구성요소 추출(number).
-- `isoWeek(source)` — ISO 8601 주 번호(월요일 시작, 1~53). `isoWeekStartDate(source)` — 해당 주 월요일(DateOnly). `isoYearMonth(source)` — 해당 월 1일(DateOnly).
-- `dateDiff(unit, from, to)` — 날짜 차이(`to - from`). `unit`=`"year"|"month"|"day"|"hour"|"minute"|"second"`.
-- `dateAdd(unit, source, value)` — 날짜 가감(`value` 음수 허용). 결과 타입은 `source` 와 동일.
-- `formatDate(source, format)` — 날짜 포맷 문자열(포맷 구문 DBMS 의존, 예 `"%Y-%m-%d"`).
+## SELECT — 날짜 (→ ExprUnit)
+
+- `expr.year` / `expr.month` / `expr.day` (DateTime|DateOnly), `expr.hour` / `expr.minute` / `expr.second` (DateTime|Time) — 각 단위 추출(number).
+- `expr.isoWeek(source)` — ISO 8601 주 번호(1~53). `expr.isoWeekStartDate(source)` — 그 주의 월요일(DateOnly). `expr.isoYearMonth(source)` — `"YYYYMM"` 문자열.
+- `expr.dateDiff(unit, from, to)` — 날짜 차(`to - from`). `unit` 은 `"year"|"month"|"day"|"hour"|"minute"|"second"`.
+- `expr.dateAdd(unit, source, value)` — 날짜 가감(음수 가능).
+- `expr.formatDate(source, format)` — 포맷 문자열(예 `"%Y-%m-%d"`, DBMS 의존).
+
+```typescript
+db.user().select((u) => ({
+  age: expr.dateDiff("year", u.birthDate, expr.val("DateOnly", DateOnly.today())),
+}));
+```
 
-## SELECT — 조건
+## SELECT — 조건 (→ ExprUnit)
 
-- `coalesce(...args)` — 첫 non-null 값(`COALESCE`). 마지막 인자가 non-nullable 이면 결과도 non-nullable 로 추론.
-- `nullIf(source, value)` — `source === value` 면 NULL, 아니면 source(빈 문자열 → NULL 변환 등).
-- `is(condition)` — `WhereExprUnit` 을 boolean `ExprUnit` 으로 변환(조건 결과를 컬럼으로). select 절에서 도메인 boolean 컬럼 만들 때.
-- `switch<T>()` — CASE WHEN 빌더(`SwitchExprBuilder`). `case(condition, then)` 체이닝 후 `default(value)` 로 종료. then/default 의 타입에서 결과 타입 추론(모두 리터럴이면 non-null 하나에서 추론, 전부 null 이면 throw).
-- `if(condition, then, else_)` — 삼항(IIF/IF). then/else 중 ExprUnit 또는 non-null 리터럴에서 타입 추론.
+- `expr.coalesce(...args)` — 첫 non-null(COALESCE). 마지막 인자가 non-nullable 이면 결과도 non-nullable(오버로드).
+- `expr.nullIf(source, value)` — `source === value` 면 NULL, 아니면 source.
+- `expr.is(condition)` — `WhereExprUnit` 을 boolean 컬럼으로(SELECT 절에서 조건 결과 노출).
+- `expr.switch<T>()` — CASE WHEN 빌더. `.case(condition, then)` 체이닝 후 `.default(value)` 로 종료해 `ExprUnit` 반환. then/default 중 하나 이상 non-null 이어야 dataType 추론 가능.
+- `expr.if(condition, then, else_)` — 삼항(IF/IIF). then/else 중 하나 이상 non-null 필요.
 
 ```typescript
 db.user().select((u) => ({
-  isActive: expr.is(expr.eq(u.status, "active")),
-  grade: expr.switch<string>().case(expr.gte(u.score, 90), "A").case(expr.gte(u.score, 80), "B").default("F"),
-}))
+  grade: expr.switch<string>()
+    .case(expr.gte(u.score, 90), "A")
+    .case(expr.gte(u.score, 80), "B")
+    .default("F"),
+  isAdult: expr.is(expr.gte(u.age, 18)),
+}));
 ```
 
-## SELECT — 집계 / 기타
+## SELECT — 집계 (→ ExprUnit)
+
+NULL 값 행은 무시되고, 행이 없거나 전부 NULL 일 때만 NULL 반환.
+
+- `expr.count(arg?, distinct?)` — COUNT. `arg` 없으면 `COUNT(*)`, `distinct: true` 면 중복 제거.
+- `expr.sum(arg)` / `expr.avg(arg)` — SUM/AVG(nullable number).
+- `expr.max(arg)` / `expr.min(arg)` — MAX/MIN(인자 타입 유지, nullable).
 
-집계는 NULL 값 행을 무시하고, 모든 값이 NULL 이거나 행이 없을 때만 NULL 반환.
+## SELECT — 기타 (→ ExprUnit)
 
-- `count(arg?, distinct?)` — `COUNT`. `arg` 생략 시 전체 행, 지정 시 그 컬럼의 non-null 행. `distinct` true 면 중복 제거 카운트.
-- `sum(arg)` / `avg(arg)` — 합계/평균(number, NULL 가능).
-- `max(arg)` / `min(arg)` — 최대/최소(타입 유지, NULL 가능).
-- `greatest(...args)` / `least(...args)` — 인자들 중 최대/최소값(행 단위, 집계 아님).
-- `rowNum()` — 단순 행 순번(1부터). `random()` — 0~1 난수(무작위 정렬 `orderBy(() => expr.random())`).
-- `cast(source, targetType)` — 타입 변환. `targetType`=`DataType`(예 `{ type: "varchar", length: 20 }`).
-- `subquery(dataType, queryable)` — 스칼라 서브쿼리(단일 행·단일 컬럼). SELECT 절에서 단일 값 반환. (행마다 N회 실행되므로 집계는 `joinSingle` 권장, orm.md.)
+- `expr.greatest(...args)` / `expr.least(...args)` — 여러 값 중 최대/최소(GREATEST/LEAST). 인자 중 하나 이상 `ExprUnit` 이어야 dataType 추론(아니면 throw).
+- `expr.rowNum()` — 모든 행에 1부터 순번(단순).
+- `expr.random()` — 0~1 난수(주로 `orderBy` 무작위 정렬).
+- `expr.cast(source, targetType)` — 타입 변환(CAST). `targetType` 은 `DataType`(예 `{ type:"varchar", length:20 }`).
+- `expr.subquery(dataType, queryable)` — 스칼라 서브쿼리(정확히 1행 1컬럼). SELECT 절에서 단일 값. (행당 N회 실행 주의 — 집계는 `joinSingle` 권장, orm.md.)
+
+```typescript
+db.order().select((o) => ({ idStr: expr.cast(o.id, { type: "varchar", length: 20 }) }));
+```
 
-## SELECT — 윈도우 함수
+## SELECT — 윈도우 함수 (→ ExprUnit, OVER)
 
-모두 `spec: { partitionBy?: ExprInput[]; orderBy?: [ExprInput, ("ASC"|"DESC")?][] }` 를 받는다(`partitionBy`=구간 분할 컬럼, `orderBy`=구간 내 정렬).
+모두 `spec: { partitionBy?: ExprInput[]; orderBy?: [ExprInput, ("ASC"|"DESC")?][] }` 를 받는다.
 
-- `rowNumber(spec)` — `ROW_NUMBER()`(파티션 내 1부터 순번).
-- `rank(spec)` — `RANK()`(동순위 후 건너뜀: 1,1,3). `denseRank(spec)` — `DENSE_RANK()`(연속: 1,1,2).
-- `ntile(n, spec)` — `NTILE(n)`(파티션을 `n` 그룹으로 분할, 1~n).
-- `lag(column, spec, options?)` / `lead(column, spec, options?)` — 이전/다음 행 값. `options.offset`(기본 1)·`options.default`(이전/다음 행 없을 때 기본값).
-- `firstValue(column, spec)` / `lastValue(column, spec)` — 프레임 내 첫/마지막 값.
-- `sumOver`/`avgOver`(column, spec) — 윈도우 합계/평균(누적합·이동평균).
-- `countOver(spec, column?)` — 윈도우 카운트(`column` 생략 시 전체 행).
-- `minOver`/`maxOver`(column, spec) — 윈도우 최소/최대.
+- `expr.rowNumber(spec)` — ROW_NUMBER(파티션 내 1부터).
+- `expr.rank(spec)` — RANK(동순위 후 건너뜀: 1,1,3). `expr.denseRank(spec)` — DENSE_RANK(연속: 1,1,2).
+- `expr.ntile(n, spec)` — 파티션을 n 그룹으로(1~n).
+- `expr.lag(column, spec, options?)` / `expr.lead(column, spec, options?)` — 이전/다음 행 값. `options.offset`(기본 1)·`options.default`(없을 때 값).
+- `expr.firstValue(column, spec)` / `expr.lastValue(column, spec)` — 프레임 첫/끝 값.
+- `expr.sumOver` / `expr.avgOver` / `expr.minOver` / `expr.maxOver` (column, spec) — 윈도우 집계. `expr.countOver(spec, column?)` — 윈도우 COUNT(`column` 생략 시 전체).
 
 ```typescript
 db.order().select((o) => ({
   ...o,
   rowNum: expr.rowNumber({ partitionBy: [o.userId], orderBy: [[o.createdAt, "DESC"]] }),
   runningTotal: expr.sumOver(o.amount, { partitionBy: [o.userId], orderBy: [[o.createdAt, "ASC"]] }),
-}))
+}));
 ```
+
+## SwitchExprBuilder
+
+```typescript
+interface SwitchExprBuilder<TPrimitive> {
+  case(condition: WhereExprUnit, then: ExprInput<TPrimitive>): SwitchExprBuilder<TPrimitive>;
+  default(value: ExprInput<TPrimitive>): ExprUnit<TPrimitive>;
+}
+```
+
+`expr.switch<T>()` 의 반환 인터페이스. `case` 누적 후 `default` 로 종료해야 `ExprUnit` 이 나온다.
+
+## 주의사항
+
+- 비교(`eq` 등)·CUD 값은 리터럴 직접 — `expr.val` 금지(orm.md). `expr.val`/`expr.raw` 는 `ExprUnit` 이 요구되는 select 컬럼·UNION 자리채움에서만.
+- `and`/`or` 에 빈 배열, `inQuery` 에 다중 컬럼 서브쿼리, `greatest`/`least`/`coalesce` 에 ExprUnit 없는 인자 전부 throw.
+- 집계·도출은 SELECT 절 subquery/exists 대신 `joinSingle` 로 outer 행에 부착(orm.md 안티패턴).