@simplysm/sd-claude 14.0.91 → 14.0.93

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

@@ -1,113 +1,85 @@
 # @simplysm/orm-common — DbContext / 연결·트랜잭션·DDL·마이그레이션
 
-`DbContext` 추상 클래스를 상속해 테이블·뷰·프로시저를 클래스 프로퍼티로 등록하고, 연결·트랜잭션·DDL·마이그레이션을 실행하는 묶음. `DbContextExecutor` 구현체와 `{ database, schema? }` 옵션을 생성자로 주입한다. 각 프로퍼티가 독립 직렬화되어 40+ 테이블에서도 TS7056 이 발생하지 않는다. 트랜잭션 롤백 에러는 `DbTransactionError` 로 표준화된다.
-
-> 앱(Angular) 환경에서는 화면이 `DbContext` 를 직접 생성하지 않고 `AppOrmProvider.connectAsync(cb)` 로 감싼다(client-orm.md). `db` 인자가 곧 아래 `DbContext` 인스턴스이므로, 콜백 안의 쿼리 작성법은 동일하다.
+`DbContext` 추상 클래스를 상속해 테이블·뷰·프로시저를 클래스 프로퍼티로 등록하고, 연결·트랜잭션·DDL·마이그레이션을 실행하는 묶음. 생성자에 `DbContextExecutor` 구현체와 `{ database, schema? }` 옵션을 주입한다. 각 프로퍼티가 독립적으로 직렬화되므로 40+ 테이블에서도 TS7056 이 발생하지 않는다. 롤백 중 발생하는 트랜잭션 에러는 `DbTransactionError` 로 표준화된다.
 
 ## DbContext (abstract class)
 
 ```typescript
 abstract class DbContext implements DbContextBase {
   constructor(executor: DbContextExecutor, opt: { database: string; schema?: string });
-
-  status: DbContextStatus;                  // "ready" | "connect" | "transact"
+  status: DbContextStatus;            // "ready" | "connect" | "transact"
   get database(): string | undefined;
   get schema(): string | undefined;
-  migrations: Migration[];                  // 서브클래스에서 오버라이드
-
-  // 등록 (protected — 서브클래스 프로퍼티 초기화에서 사용)
-  protected queryable<T>(builder: T): () => Queryable<...>;
-  protected executable<T>(builder: T): () => Executable<...>;
-
-  // 연결
-  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>;
-
-  // DDL 실행 / DDL QueryDef 생성기 / initialize ...
+  migrations: Migration[];            // 서브클래스에서 오버라이드
 }
 ```
 
-식별자 풀이:
+서브클래스에서 `protected queryable(builder)` / `protected executable(builder)` 로 멤버를 등록한다.
 
-- constructor `executor: DbContextExecutor` — 실제 DB 연결·쿼리 실행을 위임할 어댑터(서버 측 node executor, 클라이언트 측 service-client executor). 이 패키지는 SQL/QueryDef 까지만 만들고 실행은 전부 executor 가 한다.
-- constructor `opt.database: string` — 기본 데이터베이스명. 빌더가 database 를 지정하지 않으면 이 값이 객체 네임스페이스에 쓰인다.
-- constructor `opt.schema?: string` — 기본 스키마명(MSSQL `dbo`, PostgreSQL `public`). MySQL 은 무시.
-- `status: "ready"|"connect"|"transact"` — 현재 상태. "ready"=미연결, "connect"=연결됨(트랜잭션 없음), "transact"=트랜잭션 중. `connect()` 중복 호출 방지·트랜잭션 중 DDL 차단 판정에 쓰인다.
-- `database` / `schema` (getter) — 주입한 opt 값을 그대로 노출. 빌더의 `getQueryDefObjectName` 기본값으로 쓰임.
-- `migrations: Migration[]` — 마이그레이션 정의 배열. 기본 `[]`, 서브클래스에서 오버라이드해 채운다. `initialize()` 가 미실행 항목만 순서대로 실행.
-- `queryable(builder)` (protected) — `TableBuilder`/`ViewBuilder` 를 받아 호출할 때마다 새 alias 가 붙는 `() => Queryable` 팩토리를 반환. 서브클래스에서 `user = this.queryable(User)` 형태로 멤버를 만든다.
-- `executable(builder)` (protected) — `ProcedureBuilder` 를 받아 `() => Executable` 팩토리를 반환. 서브클래스에서 `getUserById = this.executable(GetUserById)` 형태로 만든다.
-- `connect(fn, isolationLevel?)` — 연결 + 트랜잭션으로 `fn` 을 감싼다. 정상 종료 시 commit, throw 시 rollback 후 재throw, 무조건 close. 첫 호출 시 관계 정합성을 1회 검증(`validateRelations`). 기본 진입점.
-- `connectWithoutTransaction(callback)` — 연결만 하고 트랜잭션은 열지 않음. 트랜잭션 안에서 동작하지 않는 작업(`initialize`/일부 DDL) 전용. 끝나면 close.
-- `transaction(fn, isolationLevel?)` — 이미 `connect` 상태일 때 그 안에서 트랜잭션 블록을 추가로 연다. "transact" 상태에서 재호출하면 throw.
-- `isolationLevel?` — 트랜잭션 격리 수준. 미지정 시 executor/DB 기본값. 값별 의미는 아래 `IsolationLevel` 참조.
+- `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()` 가 이미 적용된 것을 제외하고 순서대로 실행.
 
-사용 예 (직접 API):
+### 멤버 등록 (protected)
+
+- `queryable(builder)` — `TableBuilder`/`ViewBuilder` 를 받아 `() => Queryable<...>` 팩토리를 반환. 호출할 때마다 새 alias 가 부여된 Queryable 생성. CUD 는 `TableBuilder` 기반에서만 가능.
+- `executable(builder)` — `ProcedureBuilder` 를 받아 `() => Executable<...>` 팩토리를 반환.
 
 ```typescript
-class MainDb extends DbContext {
+class AppDb extends DbContext {
   user = this.queryable(User);
-  post = this.queryable(Post);
-  getUserById = this.executable(GetUserById);
-  override migrations = [{ name: "001", up: async (db) => { await db.createTable(User); } }];
+  activeUsers = this.queryable(ActiveUsers); // View
+  getUserById = this.executable(GetUserById); // Procedure
+  override migrations = [{ name: "001_init", up: async (db) => { await db.createTable(User); } }];
 }
-
-const db = new MainDb(executor, { database: "mydb" });
-const users = await db.connect(async () => {
-  return db.user().where((u) => [expr.eq(u.isActive, true)]).execute();
-});
+const db = new AppDb(executor, { database: "mydb" });
 ```
 
-주의:
-
-- 트랜잭션("transact") 상태에서 DDL(`createTable` 등)을 `executeDefs` 로 보내면 "TRANSACTION 상태에서는 DDL을 실행할 수 없습니다" throw. DDL 은 `connectWithoutTransaction` 안에서 실행.
-- 롤백 자체가 실패해도 원래 에러를 우선 throw 하고, 롤백 실패 원인은 `err.cause` 로 부착(단, `NO_ACTIVE_TRANSACTION` 은 무시).
-
-## DDL 실행 메서드
-
-`connectWithoutTransaction` 안에서 호출하며, 즉시 executor 로 실행한다. 모두 `Promise<void>`(예외: `schemaExists` → `Promise<boolean>`).
+### 연결·트랜잭션
 
-- `createTable(table: TableBuilder)` / `dropTable(table)` / `renameTable(table, newName)` — 테이블 생성/삭제/이름변경. drop·rename 의 `table` 인자는 `QueryDefObjectName`(`{ database?, schema?, name }`).
-- `createView(view: ViewBuilder)` / `dropView(view)` — 뷰 생성/삭제.
-- `createProc(procedure: ProcedureBuilder)` / `dropProc(procedure)` — 프로시저 생성/삭제.
-- `addColumn(table, columnName, column: ColumnBuilder)` / `dropColumn(table, column)` / `modifyColumn(table, columnName, column)` / `renameColumn(table, column, newName)` — column 추가/삭제/타입·속성변경/이름변경.
-- `addPrimaryKey(table, columns: string[])` / `dropPrimaryKey(table)` — PK 추가/삭제. 복합 PK 는 `columns` 에 여러 이름.
-- `addForeignKey(table, relationName, relationDef: ForeignKeyBuilder)` / `dropForeignKey(table, relationName)` — FK 제약 추가/삭제.
-- `addIndex(table, indexBuilder: IndexBuilder<string[]>)` / `dropIndex(table, columns: string[])` — index 추가/삭제. drop 은 column 이름 배열로 식별.
-- `clearSchema(params: { database; schema? })` — 스키마의 모든 객체 삭제(초기화).
-- `schemaExists(database, schema?): Promise<boolean>` — 스키마 존재 여부.
-- `truncate(table)` — 테이블 데이터 전체 비우기(구조 유지).
-- `switchFk(table, enabled: boolean)` — FK 제약 일시 활성/비활성. `enabled` false=비활성(대량 적재 전), true=재활성. DDL 이 아니라 트랜잭션 안에서도 호출 가능.
-
-각 `createX`/`dropX`/... 에는 동일 시그니처의 `getXQueryDef(...): QueryDef` 생성기 버전이 쌍으로 존재(실행하지 않고 QueryDef AST 만 반환). 추가로 `getCreateObjectQueryDef(builder)` 는 Table/View/Procedure 중 무엇이든 받아 알맞은 create QueryDef 를 반환한다. 마이그레이션에서 여러 DDL 을 모아 한 번에 보내거나 DDL 을 검사·로깅할 때 사용.
-
-## initialize
+- `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). 더티 리드 허용~완전 직렬화 순으로 엄격해짐.
 
 ```typescript
-initialize(options?: { dbs?: string[]; force?: boolean }): Promise<boolean>
+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
 ```
 
-- `dbs?: string[]` — 초기화 대상 데이터베이스명 목록. 미지정 시 컨텍스트의 기본 database.
-- `force?: boolean` — true 면 기존 스키마를 비우고(`clearSchema`) 전체 재생성. false/미지정이면 미적용 마이그레이션만 증분 실행하고, 변경이 있었는지를 boolean 으로 반환.
-- 반환값 — 실제로 스키마를 만들거나 마이그레이션을 적용했으면 true. 트랜잭션 안에서 돌지 않으므로 `connectWithoutTransaction` 으로 호출.
+### DDL 실행 메서드 (트랜잭션 밖에서만)
+
+각각 `executeDefs` 로 즉시 실행한다. `transact` 상태에서 호출하면 throw.
 
-## DbContextBase / DbContextStatus / DbContextDdlMethods
+- `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` 산출.
 
-- `DbContextBase` (interface) — `Queryable`/`Executable`/`ViewBuilder` 가 의존하는 컨텍스트 최소 면(`status`, `database`, `schema`, `getNextAlias()`, `resetAliasCounter()`, `executeDefs()`, `getQueryDefObjectName()`, `switchFk()`). 직접 구현할 일은 드물고, 커스텀 컨텍스트 타입의 상한으로 쓰인다.
-- `DbContextStatus` — `"ready" | "connect" | "transact"`. 위 `status` 와 동일 의미.
-- `DbContextDdlMethods` (interface) — 위 DDL 실행 메서드 + QueryDef 생성기 전체를 모은 인터페이스. `Migration.up(db)` 의 `db` 타입이 `DbContextBase & DbContextDdlMethods` 라 마이그레이션 콜백에서 DDL 을 호출할 수 있다.
+### DDL QueryDef 생성기 (실행 없이 def 만)
 
-## DbContextExecutor / ResultMeta
+위 실행 메서드와 1:1 대응하는 `get*QueryDef(...)` 가 모두 있다(`getCreateTableQueryDef`, `getDropTableQueryDef`, `getAddColumnQueryDef`, `getAddForeignKeyQueryDef`, `getTruncateQueryDef`, `getSwitchFkQueryDef`, `getClearSchemaQueryDef`, `getSchemaExistsQueryDef` 등). 실행하지 않고 `QueryDef` AST 만 얻어 배치 실행·검증·SQL 변환에 쓸 때 사용. 단일 `getCreateObjectQueryDef(builder)` 는 Table/View/Procedure 빌더 종류를 보고 알맞은 CREATE def 를 만든다.
 
-`DbContextExecutor` (interface) — DbContext 가 연결·실행을 위임할 어댑터. 직접 구현은 서버/클라이언트 어댑터 패키지에서만.
+### 마이그레이션 / 초기화
 
-- `connect(): Promise<void>` / `close(): Promise<void>` — 물리 연결 수립/종료.
-- `beginTransaction(isolationLevel?)` / `commitTransaction()` / `rollbackTransaction()` — 트랜잭션 제어. rollback 은 활성 트랜잭션이 없으면 `DbTransactionError(NO_ACTIVE_TRANSACTION)` 를 던질 수 있음.
-- `executeDefs<T>(defs: QueryDef[], resultMetas?: (ResultMeta|undefined)[]): Promise<T[][]>` — QueryDef 배열을 실행하고 def별 결과 배열을 반환. `resultMetas` 가 있으면 해당 def 결과를 그 메타로 타입 환원.
-- `ResultMeta` (interface) — `{ columns: Record<string, ColumnPrimitiveStr>; joins: Record<string, { isSingle: boolean }> }`. SELECT 결과를 TS 객체로 환원할 때의 column 타입·JOIN 중첩 구조 메타. `Queryable.getResultMeta()` 가 생성. (자세히는 [types.md](./types.md))
+- `initialize(options?)` — `migrations` 중 미적용분을 순서대로 실행하고, 적용 여부를 `_migration` 시스템 테이블에 기록. `boolean` 반환(변경 발생 여부 등).
+  - `options.dbs`: string[] — 대상 데이터베이스 목록 한정(선택).
+  - `options.force`: boolean — true 면 강제 재초기화. 스키마를 다시 깔아야 할 때만 사용.
+- `executeDefs(defs, resultMetas?)` — `QueryDef[]` 를 executor 로 실행해 `T[][]`(def 별 결과) 반환. `transact` 상태에서 DDL 타입이 섞이면 throw. 빌더가 만든 def 를 저수준으로 직접 실행할 때 사용.
 
-## Migration
+## Migration (interface)
 
 ```typescript
 interface Migration {
@@ -116,47 +88,41 @@ interface Migration {
 }
 ```
 
-- `name: string` — 마이그레이션 고유 이름(타임스탬프 권장, 예 `20260105_001_create_user`). 적용 여부 추적 키이므로 한 번 배포 후 변경 금지.
-- `up(db)` — 적용 시 실행할 함수. `db` 로 DDL 메서드를 호출. 미적용 항목만 `name` 순서대로 1회씩 실행된다.
-
-## IsolationLevel
-
-`connect`/`transaction`/`beginTransaction` 의 격리 수준.
-
-- `"READ_UNCOMMITTED"` — 커밋 전 데이터까지 읽음(Dirty Read 허용). 가장 느슨, 정합성 낮음.
-- `"READ_COMMITTED"` — 커밋된 데이터만 읽음. 일반적 기본값.
-- `"REPEATABLE_READ"` — 트랜잭션 내 동일 쿼리가 동일 결과 보장.
-- `"SERIALIZABLE"` — 완전 직렬화. 가장 엄격, 경합 시 잠금/충돌 비용 큼.
+- `name`: string — 고유 마이그레이션 식별자. 타임스탬프 접두 권장(`20260105_001_...`). 이 값으로 적용 여부를 추적하므로 한번 배포되면 변경 금지.
+- `up`: `(db) => Promise<void>` — 스키마 변경 함수. `db` 로 DDL 메서드를 호출. 실행은 `initialize()` 가 미적용분만 골라 호출.
 
 ## DbTransactionError / DbErrorCode
 
-DBMS별 네이티브 트랜잭션 에러를 표준 코드로 래핑한다. 롤백·재시도 분기에서 `instanceof DbTransactionError` + `err.code` 로 판별.
+DBMS 네이티브 에러를 dialect 독립 코드로 래핑한다. `connect`/`transaction` 의 롤백 단계에서 "이미 롤백되어 활성 트랜잭션이 없음" 같은 상황을 코드로 식별해 무시 여부를 판단할 때 쓴다.
 
 ```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 }
 ```
 
-- `code: DbErrorCode` — 표준화된 에러 코드(아래). 분기 기준.
-- `message: string` — 사람용 메시지.
-- `originalError?: unknown` — 원본 DBMS 에러(디버깅용 원형 보존).
-
-`DbErrorCode` (enum, 값은 동명 문자열):
-
-- `NO_ACTIVE_TRANSACTION` — 롤백 대상 활성 트랜잭션 없음. 이미 롤백/커밋된 경우. `connect` 내부에서 이 코드는 무시된다.
-- `TRANSACTION_ALREADY_STARTED` — 트랜잭션이 이미 시작됨(중복 begin).
-- `DEADLOCK` — 데드락 발생. 재시도 정책 트리거로 사용.
-- `LOCK_TIMEOUT` — 잠금 대기 타임아웃.
+- `code`: `DbErrorCode` — 표준화된 에러 종류. 아래 enum literal 로 분기.
+- `originalError`: unknown — 래핑 전 원본 DBMS 에러(디버깅용). dialect 별 원인 추적 시 참조.
+- `NO_ACTIVE_TRANSACTION` — 롤백/커밋할 활성 트랜잭션이 없음. 이미 롤백된 경우 무시 분기에 사용.
+- `TRANSACTION_ALREADY_STARTED` — 트랜잭션이 이미 시작됨(중첩 시작 시도).
+- `DEADLOCK` — 교착 상태로 트랜잭션이 강제 중단됨. 재시도 정책 분기에 사용.
+- `LOCK_TIMEOUT` — 잠금 대기 시간 초과. 재시도/백오프 분기에 사용.
 
 ```typescript
 try {
-  await executor.rollbackTransaction();
+  await db.rollbackTransaction();
 } catch (err) {
   if (err instanceof DbTransactionError && err.code === DbErrorCode.NO_ACTIVE_TRANSACTION) return;
   throw err;
 }
 ```
+
+## 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 자동화 등) 사용.

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

@@ -1,125 +1,111 @@
 # @simplysm/orm-common — expr (SQL 표현식 빌더)
 
-`expr` 객체로 dialect 독립 SQL 표현식을 JSON AST(`Expr`)로 조립한다. dialect별 QueryBuilder 가 MySQL/MSSQL/PostgreSQL 로 변환. where/having 콜백은 `WhereExprUnit[]`, select/orderBy/groupBy 콜백은 `ExprUnit<T>`, update/upsert/where 비교값은 `ExprInput<T>`(= `ExprUnit<T> | T`)를 다룬다.
+`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).
 
-**리터럴 래핑 규칙(orm.md)**: where 비교·update/upsert/insert 값은 `ExprInput` 자리라 **리터럴을 그대로** 넘긴다 — `expr.val` 로 감싸지 말 것. `expr.val` 은 `select` 콜백에서 상수 column 을 만들 때처럼 `ExprUnit` 이 요구되는 자리에서만.
+## 래퍼 타입
 
-```typescript
-// 좋음                                         // 나쁨 (불필요한 래핑)
-.where((u) => [expr.eq(u.status, "active")])   // expr.eq(u.status, expr.val("string","active"))
-.update((u) => ({ name: "새이름" }))            // ({ name: expr.val("string","새이름") })
-```
-
-연산 함수 인자는 대부분 `ExprInput<T>` — column 프록시(`ExprUnit`)·중첩 식·리터럴을 섞어 넘길 수 있다. `undefined` 컬럼 타입은 `.n` getter 로 non-null 단언 가능.
-
-## ExprUnit / WhereExprUnit / ExprInput
-
-- `ExprUnit<TPrimitive>` — 타입 안전 값 표현식 래퍼. `.dataType`(ColumnPrimitiveStr), `.expr`(AST), `.$infer`(타입 추론 마커). `.n` getter — 동일 식을 `NonNullable<T>` 로 좁힌 새 ExprUnit(`p.state!.sumQty` 처럼 nullable join 컬럼을 non-null 로 다룰 때 `.n` 대신 `!` 도 가능).
-- `WhereExprUnit` — WHERE/HAVING 절 boolean 표현식 래퍼(`.expr: WhereExpr`). 비교·논리 함수가 반환.
-- `ExprInput<T>` — `ExprUnit<T> | T`. 연산 인자·쓰기 값이 받는 타입(리터럴 직접 허용).
+- `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`).
 
 ## 값 생성
 
-- `val(dataType, value)` — 리터럴을 ExprUnit 으로 래핑. `dataType`="string"|"number"|"boolean"|"DateTime"|"DateOnly"|"Time"|"Uuid"|"Bytes". `value` undefined 허용(결과 타입에 undefined 포함). `select` 상수 컬럼 등 ExprUnit 강제 자리에서만.
-- `col(dataType, ...path)` — column 참조 생성(내부용). 보통 콜백 프록시로 충분.
-- `raw(dataType)\`SQL\`` — 이스케이프 해치. 태그드 템플릿, 보간값은 자동 파라미터화. ORM 미지원 DB 함수 직접 사용 시. 보간값은 `ExprInput`. union 의 NULL 자리채움(`` expr.raw("number")`NULL` ``)에도 사용(orm-union.md).
-- `toExpr(value)` — `ExprInput` → `Expr` AST 변환(내부 헬퍼).
+- `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 로 변환(내부 헬퍼).
 
-## WHERE — 비교 (반환 `WhereExprUnit`)
+## WHERE — 비교 (`WhereExprUnit` 반환)
 
-- `eq(source, target)` — 동등(NULL 안전: MySQL `<=>`, 그 외 `IS NULL OR =`).
+- `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`/`to` 중 하나가 undefined 면 그 방향 제한 없음(한쪽만 주면 `>=`/`<=` 로 동작).
-- `null(source)` — IS NULL.
-- `like(source, pattern)` — LIKE. `%`=0+ 문자, `_`=1 문자, 특수문자 `\` 이스케이프.
-- `regexp(source, pattern)` — 정규식 매칭(구문은 DBMS 의존).
-- `in(source, values)` — IN(값 목록).
-- `inQuery(source, query)` — IN (SELECT ...). `query` 는 단일 column SELECT Queryable — 아니면 throw.
-- `exists(query)` — EXISTS (서브쿼리 행 존재). SELECT 절은 제거되어 패킷 절약. (orm.md: SELECT 절 내부 `exists` 는 행당 N회 실행되므로 금지 — `joinSingle` 로 부착)
+- `between(source, from?, to?)` — 범위. `from` undefined 면 하한 없음, `to` undefined 면 상한 없음(한쪽만 주면 단방향 부등호).
+- `null(source)` — `IS NULL`. nullable 컬럼의 결측 판정.
 
-## WHERE — 논리 (반환 `WhereExprUnit`)
+## WHERE — 문자열/IN/논리
 
-- `not(arg)` — NOT.
-- `and(conditions)` — AND 결합. 빈 배열이면 throw. `where` 에 배열 넘기면 자동 AND 라 보통 불필요.
-- `or(conditions)` — OR 결합. 빈 배열이면 throw.
+- `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 안에서 묶을 때 등에 사용.)
 
-## SELECT — 문자열 (반환 `ExprUnit`)
+```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, "이%")]),
+])
+```
 
-- `concat(...args)` — CONCAT(NULL→빈문자열).
-- `left(source, length)` / `right(source, length)` — 왼쪽/오른쪽 N자.
+## SELECT — 문자열 (`ExprUnit` 반환)
+
+- `concat(...args)` — `CONCAT`(NULL 은 빈 문자열 처리).
+- `left(source, length)` / `right(source, length)` — 왼쪽/오른쪽 N자 추출.
 - `trim(source)` — 양쪽 공백 제거.
-- `padStart(source, length, fillString)` — LPAD(목표 길이까지 왼쪽 채움).
+- `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`)
+- `substring(source, start, length?)` — 부분 문자열(1부터 시작, `length` 생략 시 끝까지).
+- `indexOf(source, search)` — 위치 찾기(1부터, 없으면 0).
 
-- `abs(source)` — 절대값. `round(source, digits)` — 반올림(소수 자릿수). `ceil(source)` — 올림. `floor(source)` — 내림.
+## SELECT — 숫자 / 날짜
 
-## SELECT — 날짜 (반환 `ExprUnit`)
+- `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"`).
 
-- `year(source)` / `month(source)` / `day(source)` — 연/월/일(source: DateTime|DateOnly).
-- `hour(source)` / `minute(source)` / `second(source)` — 시/분/초(source: DateTime|Time).
-- `isoWeek(source)` — ISO 주 번호(1~53). `isoWeekStartDate(source)` — 그 주 월요일. `isoYearMonth(source)` — 해당 월 1일.
-- `dateDiff(unit, from, to)` — 날짜 차(to - from). `unit`="year"|"month"|"day"|"hour"|"minute"|"second".
-- `dateAdd(unit, source, value)` — 날짜 가감(value 음수 허용). 결과 타입은 source 와 동일.
-- `formatDate(source, format)` — 포맷 문자열로 변환(`"%Y-%m-%d"` 등, 규칙 DBMS 의존).
+## 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 리터럴에서 타입 추론.
 
-- `coalesce(...args)` — 첫 non-null. 마지막 인수가 non-nullable 이면 결과도 non-nullable. join 도출 컬럼 기본값(`coalesce(p.state!.sum, 0)`)에 자주.
-- `nullIf(source, value)` — source===value 이면 NULL(빈 문자열→NULL 변환 등).
-- `is(condition)` — `WhereExprUnit` → boolean column 으로 변환(SELECT 절에서 조건 결과를 컬럼화).
-- `switch<T>()` — CASE WHEN 빌더. `.case(condition, then).case(...).default(value)` 체이닝으로 `ExprUnit<T>` 마무리.
-- `if(condition, then, else_)` — 삼항(IF/IIF). then/else 중 최소 하나 non-null 아니면 throw(타입 추론용).
-
-## SELECT — 집계 (반환 `ExprUnit`)
-
-NULL 값 행은 무시, 전부 NULL/무행이면 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"),
+}))
+```
 
-- `count(arg?, distinct?)` — 행 수. `arg` 미지정=전체, `distinct: true`=중복 제거.
-- `sum(arg)` / `avg(arg)` — 합/평균(number, 결과 nullable).
-- `max(arg)` / `min(arg)` — 최대/최소(결과 nullable).
+## SELECT — 집계 / 기타
 
-## SELECT — 기타 (반환 `ExprUnit`)
+집계는 NULL 값 행을 무시하고, 모든 값이 NULL 이거나 행이 없을 때만 NULL 반환.
 
-- `greatest(...args)` / `least(...args)` — 여러 값 중 최대/최소(행 내 비교). 인자 중 ExprUnit 하나는 있어야 타입 추론(없으면 throw).
-- `rowNum()` — 전체 행 순번(1-기반, 단순 버전). `random()` — 0~1 난수(무작위 정렬에).
-- `cast(source, targetType)` — 타입 변환. `targetType`=`DataType`(`{ type:"varchar", length:20 }` 등).
-- `subquery(dataType, queryable)` — 스칼라 서브쿼리(1행 1열). `queryable`=`getSelectQueryDef()` 보유 객체. (orm.md: SELECT 절 내부 subquery 는 행당 N회 실행 → `joinSingle` 권장)
+- `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.)
 
-## SELECT — Window 함수 (반환 `ExprUnit`)
+## SELECT — 윈도우 함수
 
-모두 `spec: { partitionBy?: ExprInput[]; orderBy?: [ExprInput, ("ASC"|"DESC")?][] }`(OVER 절) 인자를 받음.
+모두 `spec: { partitionBy?: ExprInput[]; orderBy?: [ExprInput, ("ASC"|"DESC")?][] }` 를 받는다(`partitionBy`=구간 분할 컬럼, `orderBy`=구간 내 정렬).
 
-- `rowNumber(spec)` — 파티션 내 순번(1-기반).
-- `rank(spec)` — 순위(동순위 후 건너뜀: 1,1,3). `denseRank(spec)` — 순위(동순위 후 연속: 1,1,2).
-- `ntile(n, spec)` — 파티션을 n 그룹으로 분할(그룹 번호 1~n).
-- `lag(column, spec, options?)` / `lead(column, spec, options?)` — 이전/다음 행 값. `options.offset?`(기본 1), `options.default?`(없을 때 기본값).
+- `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(column, spec)` / `avgOver(column, spec)` / `minOver(column, spec)` / `maxOver(column, spec)` — window 합/평균/최소/최대(누적합·이동평균 등).
-- `countOver(spec, column?)` — window 행 수. `column` 미지정=전체.
+- `sumOver`/`avgOver`(column, spec) — 윈도우 합계/평균(누적합·이동평균).
+- `countOver(spec, column?)` — 윈도우 카운트(`column` 생략 시 전체 행).
+- `minOver`/`maxOver`(column, spec) — 윈도우 최소/최대.
 
 ```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
-
-`expr.switch<T>()` 반환 객체.
-
-- `case(condition: WhereExprUnit, then: ExprInput<T>)` — 분기 추가(체이닝).
-- `default(value: ExprInput<T>)` — ELSE 값 + 마무리, `ExprUnit<T>` 반환. case/default 중 최소 하나 non-null 아니면 throw.
-
-```typescript
-grade: expr.switch<string>()
-  .case(expr.gte(u.score, 90), "A")
-  .case(expr.gte(u.score, 80), "B")
-  .default("F"),
+}))
 ```