@simplysm/orm-common 14.0.1 → 14.0.4

package/docs/types.md

@@ -0,0 +1,501 @@
+# Types
+
+Core type definitions for the ORM.
+
+## Dialect
+
+Supported database dialects.
+
+```typescript
+type Dialect = "mysql" | "mssql" | "postgresql";
+```
+
+**Constant:**
+
+```typescript
+const dialects: Dialect[] = ["mysql", "mssql", "postgresql"];
+```
+
+## IsolationLevel
+
+Transaction isolation levels.
+
+```typescript
+type IsolationLevel =
+  | "READ_UNCOMMITTED"
+  | "READ_COMMITTED"
+  | "REPEATABLE_READ"
+  | "SERIALIZABLE";
+```
+
+## DataRecord
+
+Recursive data record type for query results. Supports nested relations.
+
+```typescript
+type DataRecord = {
+  [key: string]: ColumnPrimitive | DataRecord | DataRecord[];
+};
+```
+
+## DbContextExecutor
+
+Interface for DB connection and query execution. Implemented by `NodeDbContextExecutor` (server) or service-based executors (client).
+
+```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[][]>;
+}
+```
+
+## ResultMeta
+
+Metadata for transforming raw query results into typed TypeScript objects.
+
+```typescript
+interface ResultMeta {
+  columns: Record<string, ColumnPrimitiveStr>;
+  joins: Record<string, { isSingle: boolean }>;
+}
+```
+
+| Field | Description |
+|---|---|
+| `columns` | Maps column name (dot-notation for nested) to TypeScript type name |
+| `joins` | Maps JOIN alias to single/array indicator |
+
+## Migration
+
+Database migration definition for schema versioning.
+
+```typescript
+interface Migration {
+  name: string;
+  up: (db: DbContextBase & DbContextDdlMethods) => Promise<void>;
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | Unique migration name (timestamp recommended) |
+| `up` | `(db) => Promise<void>` | Migration function with DDL access |
+
+## QueryBuildResult
+
+Return type of `QueryBuilderBase.build()`.
+
+```typescript
+interface QueryBuildResult {
+  sql: string;
+  resultSetIndex?: number;
+  resultSetStride?: number;
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `sql` | `string` | Generated SQL string |
+| `resultSetIndex` | `number` | Result set index to read (default: 0) |
+| `resultSetStride` | `number` | Read every Nth result set (for multi-INSERT) |
+
+## ColumnMeta
+
+Column metadata generated by `ColumnBuilder`.
+
+```typescript
+interface ColumnMeta {
+  type: ColumnPrimitiveStr;
+  dataType: DataType;
+  autoIncrement?: boolean;
+  nullable?: boolean;
+  default?: ColumnPrimitive;
+  description?: string;
+}
+```
+
+## DataType
+
+SQL data type definition. Discriminated union on `type` field.
+
+```typescript
+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" };
+```
+
+**DBMS Mapping:**
+
+| DataType | MySQL | MSSQL | PostgreSQL |
+|---|---|---|---|
+| `int` | INT | INT | INT |
+| `bigint` | BIGINT | BIGINT | BIGINT |
+| `float` | FLOAT | REAL | REAL |
+| `double` | DOUBLE | FLOAT | DOUBLE PRECISION |
+| `decimal` | DECIMAL(p,s) | DECIMAL(p,s) | DECIMAL(p,s) |
+| `varchar` | VARCHAR(n) | NVARCHAR(n) | VARCHAR(n) |
+| `char` | CHAR(n) | NCHAR(n) | CHAR(n) |
+| `text` | LONGTEXT | NVARCHAR(MAX) | TEXT |
+| `binary` | LONGBLOB | VARBINARY(MAX) | BYTEA |
+| `boolean` | TINYINT(1) | BIT | BOOLEAN |
+| `datetime` | DATETIME | DATETIME2 | TIMESTAMP |
+| `date` | DATE | DATE | DATE |
+| `time` | TIME | TIME | TIME |
+| `uuid` | BINARY(16) | UNIQUEIDENTIFIER | UUID |
+
+## Column Primitive Types
+
+### ColumnPrimitiveMap
+
+Maps TypeScript type names to actual types.
+
+```typescript
+type ColumnPrimitiveMap = {
+  string: string;
+  number: number;
+  boolean: boolean;
+  DateTime: DateTime;
+  DateOnly: DateOnly;
+  Time: Time;
+  Uuid: Uuid;
+  Bytes: Bytes;
+};
+```
+
+### ColumnPrimitiveStr
+
+```typescript
+type ColumnPrimitiveStr = keyof ColumnPrimitiveMap;
+// "string" | "number" | "boolean" | "DateTime" | "DateOnly" | "Time" | "Uuid" | "Bytes"
+```
+
+### ColumnPrimitive
+
+All primitive types that can be stored in columns. `undefined` represents NULL.
+
+```typescript
+type ColumnPrimitive = ColumnPrimitiveMap[ColumnPrimitiveStr] | undefined;
+```
+
+### dataTypeStrToColumnPrimitiveStr
+
+Constant mapping SQL DataType string to ColumnPrimitiveStr.
+
+```typescript
+const dataTypeStrToColumnPrimitiveStr: Record<DataType["type"], ColumnPrimitiveStr>;
+// { int: "number", bigint: "number", varchar: "string", datetime: "DateTime", ... }
+```
+
+### InferColumnPrimitiveFromDataType
+
+Infer TypeScript type from a `DataType`.
+
+```typescript
+type InferColumnPrimitiveFromDataType<T extends DataType> = ColumnPrimitiveMap[...];
+```
+
+### inferColumnPrimitiveStr
+
+Infer `ColumnPrimitiveStr` from a runtime value.
+
+```typescript
+function inferColumnPrimitiveStr(value: ColumnPrimitive): ColumnPrimitiveStr;
+```
+
+## QueryDef Types
+
+All query definition types used by the QueryBuilder.
+
+### QueryDefObjectName
+
+```typescript
+interface QueryDefObjectName {
+  database?: string;
+  schema?: string;
+  name: string;
+}
+```
+
+### CudOutputDef
+
+```typescript
+interface CudOutputDef {
+  columns: string[];
+  pkColNames: string[];
+  aiColName?: string;
+}
+```
+
+### SelectQueryDef
+
+```typescript
+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
+interface SelectQueryDefJoin extends SelectQueryDef {
+  isSingle?: boolean;
+}
+```
+
+### InsertQueryDef
+
+```typescript
+interface InsertQueryDef {
+  type: "insert";
+  table: QueryDefObjectName;
+  records: Record<string, ColumnPrimitive>[];
+  overrideIdentity?: boolean;
+  output?: CudOutputDef;
+}
+```
+
+### InsertIfNotExistsQueryDef
+
+```typescript
+interface InsertIfNotExistsQueryDef {
+  type: "insertIfNotExists";
+  table: QueryDefObjectName;
+  record: Record<string, ColumnPrimitive>;
+  existsSelectQuery: Omit<SelectQueryDef, "select">;
+  output?: CudOutputDef;
+}
+```
+
+### InsertIntoQueryDef
+
+```typescript
+interface InsertIntoQueryDef {
+  type: "insertInto";
+  table: QueryDefObjectName;
+  recordsSelectQuery: SelectQueryDef;
+  output?: CudOutputDef;
+}
+```
+
+### UpdateQueryDef
+
+```typescript
+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
+interface DeleteQueryDef {
+  type: "delete";
+  table: QueryDefObjectName;
+  as: string;
+  top?: number;
+  where?: WhereExpr[];
+  joins?: SelectQueryDefJoin[];
+  limit?: [number, number];
+  output?: CudOutputDef;
+}
+```
+
+### UpsertQueryDef
+
+```typescript
+interface UpsertQueryDef {
+  type: "upsert";
+  table: QueryDefObjectName;
+  existsSelectQuery: Omit<SelectQueryDef, "select">;
+  updateRecord: Record<string, Expr>;
+  insertRecord: Record<string, Expr>;
+  output?: CudOutputDef;
+}
+```
+
+### DDL QueryDef Types
+
+| Type | Description |
+|---|---|
+| `CreateTableQueryDef` | CREATE TABLE |
+| `DropTableQueryDef` | DROP TABLE |
+| `RenameTableQueryDef` | RENAME TABLE |
+| `TruncateQueryDef` | TRUNCATE TABLE |
+| `AddColumnQueryDef` | ADD COLUMN |
+| `DropColumnQueryDef` | DROP COLUMN |
+| `ModifyColumnQueryDef` | ALTER COLUMN |
+| `RenameColumnQueryDef` | RENAME COLUMN |
+| `AddPrimaryKeyQueryDef` | ADD PRIMARY KEY |
+| `DropPrimaryKeyQueryDef` | DROP PRIMARY KEY |
+| `AddForeignKeyQueryDef` | ADD FOREIGN KEY |
+| `DropForeignKeyQueryDef` | DROP FOREIGN KEY |
+| `AddIndexQueryDef` | CREATE INDEX |
+| `DropIndexQueryDef` | DROP INDEX |
+| `CreateViewQueryDef` | CREATE VIEW |
+| `DropViewQueryDef` | DROP VIEW |
+| `CreateProcQueryDef` | CREATE PROCEDURE |
+| `DropProcQueryDef` | DROP PROCEDURE |
+| `ExecProcQueryDef` | EXECUTE PROCEDURE |
+| `ClearSchemaQueryDef` | Clear all objects in schema |
+| `SchemaExistsQueryDef` | Check schema existence |
+| `SwitchFkQueryDef` | Enable/disable FK constraints |
+
+### QueryDef (union)
+
+```typescript
+type QueryDef = SelectQueryDef | InsertQueryDef | InsertIfNotExistsQueryDef
+  | InsertIntoQueryDef | UpdateQueryDef | DeleteQueryDef | UpsertQueryDef
+  | CreateTableQueryDef | DropTableQueryDef | RenameTableQueryDef
+  | TruncateQueryDef | AddColumnQueryDef | DropColumnQueryDef
+  | ModifyColumnQueryDef | RenameColumnQueryDef
+  | AddPrimaryKeyQueryDef | DropPrimaryKeyQueryDef
+  | AddForeignKeyQueryDef | DropForeignKeyQueryDef
+  | AddIndexQueryDef | DropIndexQueryDef
+  | CreateViewQueryDef | DropViewQueryDef
+  | CreateProcQueryDef | DropProcQueryDef | ExecProcQueryDef
+  | ClearSchemaQueryDef | SchemaExistsQueryDef | SwitchFkQueryDef;
+```
+
+## Expr Types
+
+All expression AST node types. See [expression.md](expression.md) for the `expr` builder API.
+
+### DateUnit
+
+```typescript
+type DateUnit = "year" | "month" | "day" | "hour" | "minute" | "second";
+```
+
+### WhereExpr
+
+Union of all WHERE-clause expression types.
+
+```typescript
+type WhereExpr =
+  | ExprEq | ExprGt | ExprLt | ExprGte | ExprLte | ExprBetween
+  | ExprIsNull | ExprLike | ExprRegexp | ExprIn | ExprInQuery | ExprExists
+  | ExprNot | ExprAnd | ExprOr;
+```
+
+### Expr
+
+Union of all expression types (values, functions, aggregates, window, etc.).
+
+```typescript
+type Expr =
+  | ExprColumn | ExprValue | ExprRaw
+  | ExprConcat | ExprLeft | ExprRight | ExprTrim | ExprPadStart | ExprReplace
+  | ExprUpper | ExprLower | ExprLength | ExprByteLength | ExprSubstring | ExprIndexOf
+  | ExprAbs | ExprRound | ExprCeil | ExprFloor
+  | ExprYear | ExprMonth | ExprDay | ExprHour | ExprMinute | ExprSecond
+  | ExprIsoWeek | ExprIsoWeekStartDate | ExprIsoYearMonth
+  | ExprDateDiff | ExprDateAdd | ExprFormatDate
+  | ExprCoalesce | ExprNullIf | ExprIs | ExprSwitch | ExprIf
+  | ExprCount | ExprSum | ExprAvg | ExprMax | ExprMin
+  | ExprGreatest | ExprLeast | ExprRowNum | ExprRandom | ExprCast
+  | ExprWindow | ExprSubquery;
+```
+
+### WinSpec
+
+```typescript
+interface WinSpec {
+  partitionBy?: Expr[];
+  orderBy?: [Expr, ("ASC" | "DESC")?][];
+}
+```
+
+### WinFn
+
+Union of all window function types.
+
+```typescript
+type WinFn =
+  | WinFnRowNumber | WinFnRank | WinFnDenseRank | WinFnNtile
+  | WinFnLag | WinFnLead | WinFnFirstValue | WinFnLastValue
+  | WinFnSum | WinFnAvg | WinFnCount | WinFnMin | WinFnMax;
+```
+
+## parseQueryResult
+
+Transforms raw DB query results into typed TypeScript objects using `ResultMeta`. Handles type parsing, flat-to-nested conversion, and JOIN grouping.
+
+```typescript
+async function parseQueryResult<TRecord>(
+  rawResults: Record<string, unknown>[],
+  meta: ResultMeta,
+): Promise<TRecord[] | undefined>;
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `rawResults` | `Record<string, unknown>[]` | Raw result rows from database |
+| `meta` | `ResultMeta` | Type and JOIN structure metadata |
+
+**Returns:** Typed and nested result array, or `undefined` if empty.
+
+**Example:**
+
+```typescript
+const raw = [
+  { id: "1", name: "User1", "posts.id": "10", "posts.title": "Post1" },
+  { id: "1", name: "User1", "posts.id": "11", "posts.title": "Post2" },
+];
+const meta = {
+  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" }] }]
+```
+
+## _Migration
+
+System migration table definition. Automatically added to every `DbContextDef` by `defineDbContext()`.
+
+```typescript
+const _Migration: TableBuilder<{ code: ColumnBuilder<string, ...> }, {}>;
+// Table: "_migration", columns: { code: varchar(255) }, primaryKey: "code"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/orm-common",
-  "version": "14.0.1",
+  "version": "14.0.4",
   "description": "심플리즘 패키지 - ORM (common)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -14,10 +14,14 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "docs"
   ],
   "sideEffects": false,
+  "devDependencies": {
+    "@types/node": "^20.19.37"
+  },
   "dependencies": {
-    "@simplysm/core-common": "14.0.1"
+    "@simplysm/core-common": "14.0.4"
   }
 }

package/src/exec/queryable.ts

@@ -647,16 +647,16 @@ export class Queryable<
       });
     }
 
-    // 1. join alias Generate
+    // 1. JOIN 별칭 생성
     const joinAlias = `${this.meta.as}.${as}`;
 
-    // 2. Transform target → Queryable (pass alias)
+    // 2. 대상을 Queryable로 변환 (별칭 전달)
     const joinQr = new JoinQueryable(this.meta.db, joinAlias);
 
-    // 3. Execute fn (returns Queryable with conditions like where added)
+    // 3. fn 실행 (where 등 조건이 추가된 Queryable 반환)
     const resultQr = fn(joinQr, this.meta.columns);
 
-    // 4. Add join result to new columns
+    // 4. JOIN 결과를 새 column에 추가
     const joinColumns = transformColumnsAlias(resultQr.meta.columns, joinAlias);
 
     return new Queryable({
@@ -703,16 +703,16 @@ export class Queryable<
       });
     }
 
-    // 1. join alias Generate
+    // 1. JOIN 별칭 생성
     const joinAlias = `${this.meta.as}.${as}`;
 
-    // 2. Transform target → Queryable (pass alias)
+    // 2. 대상을 Queryable로 변환 (별칭 전달)
     const joinQr = new JoinQueryable(this.meta.db, joinAlias);
 
-    // 3. Execute fn (returns Queryable with conditions like where added)
+    // 3. fn 실행 (where 등 조건이 추가된 Queryable 반환)
     const resultQr = fn(joinQr, this.meta.columns);
 
-    // 4. Add join result to new columns
+    // 4. JOIN 결과를 새 column에 추가
     const joinColumns = transformColumnsAlias(resultQr.meta.columns, joinAlias);
 
     return new Queryable({
@@ -803,7 +803,7 @@ export class Queryable<
 
       if (relationDef instanceof ForeignKeyBuilder || relationDef instanceof RelationKeyBuilder) {
         // FK/RelationKey (N:1): Post.user → User
-        // condition: Post.userId = User.id
+        // 조건: Post.userId = User.id
         const targetTable = relationDef.meta.targetFn();
         const fkColKeys = relationDef.meta.columns;
         const targetPkColKeys = getMatchedPrimaryKeys(fkColKeys, targetTable);
@@ -811,7 +811,7 @@ export class Queryable<
         result = result.joinSingle(chainParts.join("."), (joinQr, parentCols) => {
           const qr = joinQr.from(targetTable);
 
-          // FKT join is stored as array, so use first element if array
+          // FKT JOIN은 배열로 저장되므로, 배열이면 첫 번째 요소 사용
           const srcColsRaw = parentChain ? parentCols[parentChain] : parentCols;
           const srcCols = (
             Array.isArray(srcColsRaw) ? srcColsRaw[0] : srcColsRaw
@@ -833,8 +833,8 @@ export class Queryable<
         relationDef instanceof ForeignKeyTargetBuilder ||
         relationDef instanceof RelationKeyTargetBuilder
       ) {
-        // FKT/RelationKeyTarget (1:N or 1:1): User.posts → Post[]
-        // condition: Post.userId = User.id
+        // FKT/RelationKeyTarget (1:N 또는 1:1): User.posts → Post[]
+        // 조건: Post.userId = User.id
         const targetTable = relationDef.meta.targetTableFn();
         const fkRelName = relationDef.meta.relationName;
         const sourceFk = targetTable.meta.relations?.[fkRelName];
@@ -853,7 +853,7 @@ export class Queryable<
         const buildJoin = (joinQr: JoinQueryable, parentCols: QueryableRecord<DataRecord>) => {
           const qr = joinQr.from(sourceTable);
 
-          // FKT join is stored as array, so use first element if array
+          // FKT JOIN은 배열로 저장되므로, 배열이면 첫 번째 요소 사용
           const srcColsRaw = parentChain ? parentCols[parentChain] : parentCols;
           const srcCols = (
             Array.isArray(srcColsRaw) ? srcColsRaw[0] : srcColsRaw
@@ -903,7 +903,7 @@ export class Queryable<
    * ```
    */
   wrap(): Queryable<TData, never> {
-    // Wrap the current Queryable as a Subquery
+    // 현재 Queryable을 서브쿼리로 래핑
     const wrapAlias = this.meta.db.getNextAlias();
     return new Queryable({
       db: this.meta.db,
@@ -982,13 +982,13 @@ export class Queryable<
         columns: transformColumnsAlias(newFroms[0].meta.columns, this.meta.as, ""),
       });
     }
-    // Generate dynamic CTE name
+    // 동적 CTE 이름 생성
     const cteName = this.meta.db.getNextAlias();
 
-    // 2. Transform target to Queryable (pass CTE name)
+    // 2. 대상을 Queryable로 변환 (CTE 이름 전달)
     const cteQr = new RecursiveQueryable(this, cteName);
 
-    // 3. Execute fn (returns Queryable with conditions like where added)
+    // 3. fn 실행 (where 등 조건이 추가된 Queryable 반환)
     const resultQr = fn(cteQr);
 
     return new Queryable({
@@ -998,7 +998,7 @@ export class Queryable<
       columns: transformColumnsAlias(this.meta.columns, this.meta.as, ""),
       with: {
         name: cteName,
-        base: this as any, // Block circular reference type inference
+        base: this as any, // 순환 참조 타입 추론 차단
         recursive: resultQr,
       },
     });