@simplysm/orm-common 14.0.48 → 14.0.50

package/docs/types/query-def.md

@@ -0,0 +1,224 @@
+# QueryDef
+
+SQL AST 정의 타입 모음. `Queryable`이 내부적으로 생성하며, `QueryBuilderBase.build(def)`에 전달되어 SQL 문자열로 변환된다.
+
+## `QueryDef`
+
+모든 쿼리 정의의 유니온 타입.
+
+```typescript
+export type QueryDef =
+  | SelectQueryDef
+  | InsertQueryDef
+  | InsertIfNotExistsQueryDef
+  | InsertIntoQueryDef
+  | UpdateQueryDef
+  | DeleteQueryDef
+  | UpsertQueryDef
+  | SwitchFkQueryDef
+  | CreateTableQueryDef
+  | DropTableQueryDef
+  | RenameTableQueryDef
+  | TruncateQueryDef
+  | AddColumnQueryDef
+  | DropColumnQueryDef
+  | ModifyColumnQueryDef
+  | RenameColumnQueryDef
+  | AddPrimaryKeyQueryDef
+  | DropPrimaryKeyQueryDef
+  | AddForeignKeyQueryDef
+  | DropForeignKeyQueryDef
+  | AddIndexQueryDef
+  | DropIndexQueryDef
+  | CreateViewQueryDef
+  | DropViewQueryDef
+  | CreateProcQueryDef
+  | DropProcQueryDef
+  | ExecProcQueryDef
+  | ClearSchemaQueryDef
+  | SchemaExistsQueryDef;
+```
+
+## `QueryDefObjectName`
+
+DB 객체 이름 (테이블, 뷰, 프로시저 등).
+
+```typescript
+export interface QueryDefObjectName {
+  database?: string;
+  schema?: string;
+  name: string;
+}
+```
+
+DBMS별 네임스페이스 처리:
+- MySQL: `database.name` (schema 무시)
+- MSSQL: `database.schema.name` (schema 기본값 dbo)
+- PostgreSQL: `schema.name` (database는 연결용)
+
+## DML 쿼리 정의
+
+### `SelectQueryDef`
+
+```typescript
+export interface SelectQueryDef {
+  type: "select";
+  from?: QueryDefObjectName | SelectQueryDef | SelectQueryDef[] | string;
+  as: string;
+  select?: Record<string, Expr>;
+  distinct?: boolean;
+  top?: number;
+  lock?: boolean;
+  where?: WhereExpr[];
+  joins?: SelectQueryDefJoin[];
+  orderBy?: [Expr, ("ASC" | "DESC")?][];
+  limit?: [number, number];
+  groupBy?: Expr[];
+  having?: WhereExpr[];
+  with?: { name: string; base: SelectQueryDef; recursive: SelectQueryDef };
+}
+```
+
+### `SelectQueryDefJoin`
+
+```typescript
+export interface SelectQueryDefJoin extends SelectQueryDef {
+  isSingle?: boolean;
+}
+```
+
+### `InsertQueryDef`
+
+```typescript
+export interface InsertQueryDef {
+  type: "insert";
+  table: QueryDefObjectName;
+  records: Record<string, ColumnPrimitive>[];
+  overrideIdentity?: boolean;
+  output?: CudOutputDef;
+}
+```
+
+### `InsertIfNotExistsQueryDef`
+
+```typescript
+export interface InsertIfNotExistsQueryDef {
+  type: "insertIfNotExists";
+  table: QueryDefObjectName;
+  record: Record<string, ColumnPrimitive>;
+  existsSelectQuery: SelectQueryDef;
+  overrideIdentity?: boolean;
+  output?: CudOutputDef;
+}
+```
+
+### `InsertIntoQueryDef`
+
+```typescript
+export interface InsertIntoQueryDef {
+  type: "insertInto";
+  table: QueryDefObjectName;
+  recordsSelectQuery: SelectQueryDef;
+  overrideIdentity?: boolean;
+  output?: CudOutputDef;
+}
+```
+
+### `UpdateQueryDef`
+
+```typescript
+export interface UpdateQueryDef {
+  type: "update";
+  table: QueryDefObjectName;
+  as: string;
+  record: Record<string, Expr>;
+  top?: number;
+  where?: WhereExpr[];
+  joins?: SelectQueryDefJoin[];
+  limit?: [number, number];
+  output?: CudOutputDef;
+}
+```
+
+### `DeleteQueryDef`
+
+```typescript
+export interface DeleteQueryDef {
+  type: "delete";
+  table: QueryDefObjectName;
+  as: string;
+  top?: number;
+  where?: WhereExpr[];
+  joins?: SelectQueryDefJoin[];
+  limit?: [number, number];
+  output?: CudOutputDef;
+}
+```
+
+### `UpsertQueryDef`
+
+```typescript
+export interface UpsertQueryDef {
+  type: "upsert";
+  table: QueryDefObjectName;
+  existsSelectQuery: SelectQueryDef;
+  insertRecord: Record<string, Expr>;
+  updateRecord: Record<string, Expr>;
+  overrideIdentity?: boolean;
+  output?: CudOutputDef;
+}
+```
+
+## `CudOutputDef`
+
+INSERT/UPDATE/DELETE 후 반환값 정의 (OUTPUT 절).
+
+```typescript
+export interface CudOutputDef {
+  columns: string[];
+  pkColNames: string[];
+  aiColName?: string;
+}
+```
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `columns` | `string[]` | 반환할 컬럼 이름 배열 |
+| `pkColNames` | `string[]` | PK 컬럼 이름 배열 |
+| `aiColName` | `string \| undefined` | AUTO_INCREMENT 컬럼 이름 |
+
+## DDL 쿼리 정의
+
+| 인터페이스 | `type` 값 | 설명 |
+|------------|-----------|------|
+| `CreateTableQueryDef` | `"createTable"` | CREATE TABLE |
+| `DropTableQueryDef` | `"dropTable"` | DROP TABLE |
+| `RenameTableQueryDef` | `"renameTable"` | RENAME TABLE |
+| `TruncateQueryDef` | `"truncate"` | TRUNCATE TABLE |
+| `AddColumnQueryDef` | `"addColumn"` | ADD COLUMN |
+| `DropColumnQueryDef` | `"dropColumn"` | DROP COLUMN |
+| `ModifyColumnQueryDef` | `"modifyColumn"` | MODIFY/ALTER COLUMN |
+| `RenameColumnQueryDef` | `"renameColumn"` | RENAME COLUMN |
+| `AddPrimaryKeyQueryDef` | `"addPrimaryKey"` | ADD PRIMARY KEY |
+| `DropPrimaryKeyQueryDef` | `"dropPrimaryKey"` | DROP PRIMARY KEY |
+| `AddForeignKeyQueryDef` | `"addForeignKey"` | ADD FOREIGN KEY |
+| `DropForeignKeyQueryDef` | `"dropForeignKey"` | DROP FOREIGN KEY |
+| `AddIndexQueryDef` | `"addIndex"` | ADD INDEX |
+| `DropIndexQueryDef` | `"dropIndex"` | DROP INDEX |
+| `CreateViewQueryDef` | `"createView"` | CREATE VIEW |
+| `DropViewQueryDef` | `"dropView"` | DROP VIEW |
+| `CreateProcQueryDef` | `"createProc"` | CREATE PROCEDURE |
+| `DropProcQueryDef` | `"dropProc"` | DROP PROCEDURE |
+| `ExecProcQueryDef` | `"execProc"` | EXEC PROCEDURE |
+| `ClearSchemaQueryDef` | `"clearSchema"` | 스키마 내 모든 객체 제거 |
+| `SchemaExistsQueryDef` | `"schemaExists"` | 스키마 존재 여부 확인 |
+| `SwitchFkQueryDef` | `"switchFk"` | FK 제약조건 활성화/비활성화 |
+
+## `DDL_TYPES` / `DdlType`
+
+DDL 타입 문자열 목록 및 유니온 타입. `DbContext.executeDefs()` 내부에서 트랜잭션 중 DDL 실행 차단에 사용된다.
+
+```typescript
+export const DDL_TYPES: readonly string[];
+export type DdlType = typeof DDL_TYPES[number];
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/orm-common",
-  "version": "14.0.48",
+  "version": "14.0.50",
   "description": "심플리즘 패키지 - ORM (common)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -22,6 +22,6 @@
     "@types/node": "^20.19.39"
   },
   "dependencies": {
-    "@simplysm/core-common": "14.0.48"
+    "@simplysm/core-common": "14.0.50"
   }
 }

package/src/db-context.ts

@@ -100,7 +100,7 @@ export abstract class DbContext implements DbContextBase {
   }
 
   getQueryDefObjectName(
-    tableOrView: TableBuilder<any, any> | ViewBuilder<any, any, any>,
+    tableOrView: TableBuilder<any, any, any> | ViewBuilder<any, any, any>,
   ): QueryDefObjectName {
     return getQueryDefObjectNameImpl(this, tableOrView);
   }
@@ -111,9 +111,9 @@ export abstract class DbContext implements DbContextBase {
 
   // ── 등록 메서드 ──
 
-  protected queryable<T extends TableBuilder<any, any> | ViewBuilder<any, any, any>>(
+  protected queryable<T extends TableBuilder<any, any, any> | ViewBuilder<any, any, any>>(
     builder: T,
-  ): () => Queryable<T["$inferSelect"], T extends TableBuilder<any, any> ? T : never> {
+  ): () => Queryable<T["$inferSelect"], T extends TableBuilder<any, any, any> ? T : never> {
     const fn = createQueryable(this, builder);
     Object.defineProperty(fn, SD_BUILDER, { value: builder });
     return fn;
@@ -245,7 +245,7 @@ export abstract class DbContext implements DbContextBase {
 
   // ── DDL 실행 메서드 ──
 
-  async createTable(table: TableBuilder<any, any>): Promise<void> {
+  async createTable(table: TableBuilder<any, any, any>): Promise<void> {
     await this.executeDefs([tableDdl.getCreateTableQueryDef(this, table)]);
   }
 
@@ -342,12 +342,12 @@ export abstract class DbContext implements DbContextBase {
 
   // ── DDL QueryDef 생성기 ──
 
-  getCreateTableQueryDef(table: TableBuilder<any, any>): QueryDef {
+  getCreateTableQueryDef(table: TableBuilder<any, any, any>): QueryDef {
     return tableDdl.getCreateTableQueryDef(this, table);
   }
 
   getCreateViewQueryDef(view: ViewBuilder<any, any, any>): QueryDef {
-    return tableDdl.getCreateViewQueryDef(this as any, view);
+    return tableDdl.getCreateViewQueryDef(this, view);
   }
 
   getCreateProcQueryDef(procedure: ProcedureBuilder<any, any>): QueryDef {
@@ -355,9 +355,9 @@ export abstract class DbContext implements DbContextBase {
   }
 
   getCreateObjectQueryDef(
-    builder: TableBuilder<any, any> | ViewBuilder<any, any, any> | ProcedureBuilder<any, any>,
+    builder: TableBuilder<any, any, any> | ViewBuilder<any, any, any> | ProcedureBuilder<any, any>,
   ): QueryDef {
-    return tableDdl.getCreateObjectQueryDef(this as any, builder);
+    return tableDdl.getCreateObjectQueryDef(this, builder);
   }
 
   getDropTableQueryDef(table: QueryDefObjectName): QueryDef {

package/src/ddl/initialize.ts

@@ -131,7 +131,7 @@ export async function initialize(
  */
 async function createAllObjects(
   db: DbContextBase,
-  builders: (TableBuilder<any, any> | ViewBuilder<any, any, any> | ProcedureBuilder<any, any>)[],
+  builders: (TableBuilder<any, any, any> | ViewBuilder<any, any, any> | ProcedureBuilder<any, any>)[],
   targetDatabase: string,
 ): Promise<void> {
   // targetDatabase에 해당하는 builder만 필터링
@@ -188,16 +188,16 @@ async function createAllObjects(
  */
 function collectBuilders(
   dbContext: object,
-): (TableBuilder<any, any> | ViewBuilder<any, any, any> | ProcedureBuilder<any, any>)[] {
+): (TableBuilder<any, any, any> | ViewBuilder<any, any, any> | ProcedureBuilder<any, any>)[] {
   const builders: (
-    | TableBuilder<any, any>
+    | TableBuilder<any, any, any>
     | ViewBuilder<any, any, any>
     | ProcedureBuilder<any, any>
   )[] = [];
 
   for (const value of Object.values(dbContext)) {
     if (typeof value === "function" && SD_BUILDER in value) {
-      builders.push(value[SD_BUILDER as keyof typeof value] as TableBuilder<any, any>);
+      builders.push(value[SD_BUILDER as keyof typeof value] as TableBuilder<any, any, any>);
     }
   }
 

package/src/ddl/table-ddl.ts

@@ -23,7 +23,7 @@ import { obj } from "@simplysm/core-common";
  */
 export function getCreateObjectQueryDef(
   db: DbContextBase,
-  builder: TableBuilder<any, any> | ViewBuilder<any, any, any> | ProcedureBuilder<any, any>,
+  builder: TableBuilder<any, any, any> | ViewBuilder<any, any, any> | ProcedureBuilder<any, any>,
 ): QueryDef {
   if (builder instanceof TableBuilder) {
     return getCreateTableQueryDef(db, builder);
@@ -44,7 +44,7 @@ export function getCreateObjectQueryDef(
  * @returns CREATE TABLE QueryDef
  * @throws {Error} 테이블에 column이 없을 때
  */
-export function getCreateTableQueryDef(db: DbContextBase, table: TableBuilder<any, any>): QueryDef {
+export function getCreateTableQueryDef(db: DbContextBase, table: TableBuilder<any, any, any>): QueryDef {
   const columns = table.meta.columns as ColumnBuilderRecord | undefined;
   if (columns == null) {
     throw new Error(`테이블 '${table.meta.name}'에 column이 없습니다.`);
@@ -179,7 +179,7 @@ export function getDropProcQueryDef(procedure: QueryDefObjectName): DropProcQuer
  */
 export function getQueryDefObjectName(
   db: DbContextBase,
-  tableOrView: TableBuilder<any, any> | ViewBuilder<any, any, any>,
+  tableOrView: TableBuilder<any, any, any> | ViewBuilder<any, any, any>,
 ): QueryDefObjectName {
   return obj.clearUndefined({
     database: tableOrView.meta.database ?? db.database,

package/src/exec/queryable.ts

@@ -49,7 +49,7 @@ class JoinQueryable {
    * @param table - 조인할 table
    * @returns 조인된 Queryable
    */
-  from<T extends TableBuilder<any, any>>(table: T): Queryable<T["$inferSelect"], T> {
+  from<T extends TableBuilder<any, any, any>>(table: T): Queryable<T["$inferSelect"], T> {
     return queryable(this._db, table, this._joinAlias)();
   }
 
@@ -113,7 +113,7 @@ class RecursiveQueryable<TBaseData extends DataRecord> {
    * @param table - 재귀할 대상 table
    * @returns self 속성이 추가된 Queryable (자기 참조용)
    */
-  from<T extends TableBuilder<any, any>>(
+  from<T extends TableBuilder<any, any, any>>(
     table: T,
   ): Queryable<T["$inferSelect"] & { self?: TBaseData[] }, T> {
     const selfAlias = `${this._cteName}.self`;
@@ -128,7 +128,7 @@ class RecursiveQueryable<TBaseData extends DataRecord> {
           columns: transformColumnsAlias(this._baseQr.meta.columns, selfAlias, ""),
           isCustomColumns: false,
         }),
-    ) as any;
+    );
   }
 
   /**
@@ -227,7 +227,7 @@ class RecursiveQueryable<TBaseData extends DataRecord> {
  */
 export class Queryable<
   TData extends DataRecord,
-  TFrom extends TableBuilder<any, any> | never, // CUD 연산은 TableBuilder만 지원
+  TFrom extends TableBuilder<any, any, any> | never, // CUD 연산은 TableBuilder만 지원
 > {
   constructor(readonly meta: QueryableMeta<TData>) {}
 
@@ -675,7 +675,7 @@ export class Queryable<
       columns: {
         ...this.meta.columns,
         [as]: [joinColumns],
-      } as QueryableRecord<any>,
+      },
       isCustomColumns: true,
       joins: [...(this.meta.joins ?? []), { queryable: resultQr, isSingle: false }],
     }) as any;
@@ -731,7 +731,7 @@ export class Queryable<
       columns: {
         ...this.meta.columns,
         [as]: joinColumns,
-      } as QueryableRecord<any>,
+      },
       isCustomColumns: true,
       joins: [...(this.meta.joins ?? []), { queryable: resultQr, isSingle: true }],
     }) as any;
@@ -1396,15 +1396,15 @@ export class Queryable<
    *   .insertInto(ArchivedUser);
    * ```
    */
-  async insertInto<TTable extends TableBuilder<DataToColumnBuilderRecord<TData>, any>>(
+  async insertInto<TTable extends TableBuilder<any, DataToColumnBuilderRecord<TData>, any>>(
     targetTable: TTable,
   ): Promise<void>;
   async insertInto<
-    TTable extends TableBuilder<DataToColumnBuilderRecord<TData>, any>,
+    TTable extends TableBuilder<any, DataToColumnBuilderRecord<TData>, any>,
     TOut extends keyof TTable["$inferColumns"] & string,
   >(targetTable: TTable, outputColumns: TOut[]): Promise<Pick<TData, TOut>[]>;
   async insertInto<
-    TTable extends TableBuilder<DataToColumnBuilderRecord<TData>, any>,
+    TTable extends TableBuilder<any, DataToColumnBuilderRecord<TData>, any>,
     TOut extends keyof TTable["$inferColumns"] & string,
   >(targetTable: TTable, outputColumns?: TOut[]): Promise<Pick<TData, TOut>[] | void> {
     const results = await this.meta.db.executeDefs<Pick<TData, TOut>>(
@@ -1421,7 +1421,7 @@ export class Queryable<
     records: TFrom["$inferInsert"][],
     outputColumns?: (keyof TFrom["$inferColumns"] & string)[],
   ): InsertQueryDef {
-    const from = this.meta.from as TableBuilder<any, any> | ViewBuilder<any, any, any>;
+    const from = this.meta.from as TableBuilder<any, any, any> | ViewBuilder<any, any, any>;
     const outputDef = this._getCudOutputDef();
 
     // AI column에 명시적 값이 있으면 overrideIdentity 설정
@@ -1448,7 +1448,7 @@ export class Queryable<
     record: TFrom["$inferInsert"],
     outputColumns?: (keyof TFrom["$inferColumns"] & string)[],
   ): InsertIfNotExistsQueryDef {
-    const from = this.meta.from as TableBuilder<any, any> | ViewBuilder<any, any, any>;
+    const from = this.meta.from as TableBuilder<any, any, any> | ViewBuilder<any, any, any>;
     const outputDef = this._getCudOutputDef();
 
     const { select: _, ...existsSelectQuery } = this.getSelectQueryDef();
@@ -1468,7 +1468,7 @@ export class Queryable<
     });
   }
 
-  getInsertIntoQueryDef<TTable extends TableBuilder<DataToColumnBuilderRecord<TData>, any>>(
+  getInsertIntoQueryDef<TTable extends TableBuilder<any, DataToColumnBuilderRecord<TData>, any>>(
     targetTable: TTable,
     outputColumns?: (keyof TTable["$inferColumns"] & string)[],
   ): InsertIntoQueryDef {
@@ -1577,7 +1577,7 @@ export class Queryable<
     recordFwd: (cols: QueryableRecord<TData>) => QueryableWriteRecord<TFrom["$inferUpdate"]>,
     outputColumns?: (keyof TFrom["$inferColumns"] & string)[],
   ): UpdateQueryDef {
-    const from = this.meta.from as TableBuilder<any, any> | ViewBuilder<any, any, any>;
+    const from = this.meta.from as TableBuilder<any, any, any> | ViewBuilder<any, any, any>;
     const outputDef = this._getCudOutputDef();
 
     return obj.clearUndefined({
@@ -1600,7 +1600,7 @@ export class Queryable<
   }
 
   getDeleteQueryDef(outputColumns?: (keyof TFrom["$inferColumns"] & string)[]): DeleteQueryDef {
-    const from = this.meta.from as TableBuilder<any, any> | ViewBuilder<any, any, any>;
+    const from = this.meta.from as TableBuilder<any, any, any> | ViewBuilder<any, any, any>;
     const outputDef = this._getCudOutputDef();
 
     return obj.clearUndefined({
@@ -1709,7 +1709,7 @@ export class Queryable<
     insertRecordFn: (updateRecord: U) => QueryableWriteRecord<TFrom["$inferInsert"]>,
     outputColumns?: (keyof TFrom["$inferColumns"] & string)[],
   ): UpsertQueryDef {
-    const from = this.meta.from as TableBuilder<any, any> | ViewBuilder<any, any, any>;
+    const from = this.meta.from as TableBuilder<any, any, any> | ViewBuilder<any, any, any>;
     const outputDef = this._getCudOutputDef();
 
     const { select: _sel, ...existsSelectQuery } = this.getSelectQueryDef();
@@ -1806,7 +1806,7 @@ export class Queryable<
  */
 export function getMatchedPrimaryKeys(
   fkCols: string[],
-  targetTable: TableBuilder<any, any>,
+  targetTable: TableBuilder<any, any, any>,
 ): string[] {
   const pk = targetTable.meta.primaryKey;
   if (pk == null || fkCols.length !== pk.length) {
@@ -1866,7 +1866,7 @@ function transformColumnsAlias<TRecord extends DataRecord>(
 interface QueryableMeta<TData extends DataRecord> {
   db: DbContextBase;
   from?:
-    | TableBuilder<any, any>
+    | TableBuilder<any, any, any>
     | ViewBuilder<any, any, any>
     | Queryable<any, any>
     | Queryable<TData, any>[]
@@ -1919,8 +1919,8 @@ export type QueryableWriteRecord<TData> = {
  * ExprUnit<T>를 T로 언래핑, 중첩 객체/배열을 재귀적으로 언래핑
  */
 export type UnwrapQueryableRecord<R> = {
-  [K in keyof R as K extends symbol ? never : K]: R[K] extends ExprUnit<infer T>
-    ? T
+  [K in keyof R as K extends symbol ? never : K]: NonNullable<R[K]> extends ExprUnit<infer T>
+    ? T | Extract<R[K], undefined>
     : NonNullable<R[K]> extends (infer U)[]
       ? U extends Record<string, any>
         ? UnwrapQueryableRecord<U>[] | Extract<R[K], undefined>
@@ -2019,11 +2019,11 @@ function createPathProxy<TObject>(path: string[] = []): PathProxy<TObject> {
  * }
  * ```
  */
-export function queryable<TBuilder extends TableBuilder<any, any> | ViewBuilder<any, any, any>>(
+export function queryable<TBuilder extends TableBuilder<any, any, any> | ViewBuilder<any, any, any>>(
   db: DbContextBase,
   tableOrView: TBuilder,
   as?: string,
-): () => Queryable<TBuilder["$inferSelect"], TBuilder extends TableBuilder<any, any> ? TBuilder : never> {
+): () => Queryable<TBuilder["$inferSelect"], TBuilder extends TableBuilder<any, any, any> ? TBuilder : never> {
   return () => {
     // as가 미지정이면 db.getNextAlias() 사용 (카운터 증가)
     // as가 지정되면 그대로 사용 (카운터 증가 없음)