@simplysm/orm-common 13.0.100 → 14.0.4

package/docs/types.md

@@ -1,6 +1,8 @@
 # Types
 
-## `Dialect`
+Core type definitions for the ORM.
+
+## Dialect
 
 Supported database dialects.
 
@@ -8,17 +10,15 @@ Supported database dialects.
 type Dialect = "mysql" | "mssql" | "postgresql";
 ```
 
-## `dialects`
-
-List of all supported database dialects.
+**Constant:**
 
 ```typescript
 const dialects: Dialect[] = ["mysql", "mssql", "postgresql"];
 ```
 
-## `IsolationLevel`
+## IsolationLevel
 
-Transaction isolation level.
+Transaction isolation levels.
 
 ```typescript
 type IsolationLevel =
@@ -28,9 +28,9 @@ type IsolationLevel =
   | "SERIALIZABLE";
 ```
 
-## `DataRecord`
+## DataRecord
 
-Query result data record type. Supports nested relation (include) results with recursive structure.
+Recursive data record type for query results. Supports nested relations.
 
 ```typescript
 type DataRecord = {
@@ -38,9 +38,9 @@ type DataRecord = {
 };
 ```
 
-## `DbContextExecutor`
+## DbContextExecutor
 
-DbContext executor interface. Responsible for actual DB connection and query execution.
+Interface for DB connection and query execution. Implemented by `NodeDbContextExecutor` (server) or service-based executors (client).
 
 ```typescript
 interface DbContextExecutor {
@@ -56,68 +56,74 @@ interface DbContextExecutor {
 }
 ```
 
-| Method | Description |
-|--------|-------------|
-| `connect()` | Establish DB connection |
-| `close()` | Close DB connection |
-| `beginTransaction()` | Begin transaction with optional isolation level |
-| `commitTransaction()` | Commit transaction |
-| `rollbackTransaction()` | Rollback transaction |
-| `executeDefs()` | Execute QueryDef array and return results |
+## ResultMeta
 
-## `QueryBuildResult`
-
-`QueryBuilder.build()` return type.
+Metadata for transforming raw query results into typed TypeScript objects.
 
 ```typescript
-interface QueryBuildResult {
-  sql: string;
-  resultSetIndex?: number;
-  resultSetStride?: number;
+interface ResultMeta {
+  columns: Record<string, ColumnPrimitiveStr>;
+  joins: Record<string, { isSingle: boolean }>;
 }
 ```
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `sql` | `string` | Built SQL string |
-| `resultSetIndex` | `number` | Result set index to fetch results from |
-| `resultSetStride` | `number` | Extract every Nth result set from multiple results |
+| Field | Description |
+|---|---|
+| `columns` | Maps column name (dot-notation for nested) to TypeScript type name |
+| `joins` | Maps JOIN alias to single/array indicator |
 
-## `ResultMeta`
+## Migration
 
-Metadata for query result transformation.
+Database migration definition for schema versioning.
 
 ```typescript
-interface ResultMeta {
-  columns: Record<string, ColumnPrimitiveStr>;
-  joins: Record<string, { isSingle: boolean }>;
+interface Migration {
+  name: string;
+  up: (db: DbContextBase & DbContextDdlMethods) => Promise<void>;
 }
 ```
 
 | Field | Type | Description |
-|-------|------|-------------|
-| `columns` | `Record<string, ColumnPrimitiveStr>` | Column name to type mapping |
-| `joins` | `Record<string, { isSingle: boolean }>` | JOIN alias to single/array indicator |
+|---|---|---|
+| `name` | `string` | Unique migration name (timestamp recommended) |
+| `up` | `(db) => Promise<void>` | Migration function with DDL access |
 
-## `Migration`
+## QueryBuildResult
 
-Database migration definition.
+Return type of `QueryBuilderBase.build()`.
 
 ```typescript
-interface Migration {
-  name: string;
-  up: (db: DbContextBase & DbContextDdlMethods) => Promise<void>;
+interface QueryBuildResult {
+  sql: string;
+  resultSetIndex?: number;
+  resultSetStride?: number;
 }
 ```
 
 | Field | Type | Description |
-|-------|------|-------------|
-| `name` | `string` | Unique migration name (timestamp recommended) |
-| `up` | `(db) => Promise<void>` | Migration execution function |
+|---|---|---|
+| `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`
+## DataType
 
-SQL data type definition.
+SQL data type definition. Discriminated union on `type` field.
 
 ```typescript
 type DataType =
@@ -137,9 +143,30 @@ type DataType =
   | { type: "uuid" };
 ```
 
-## `ColumnPrimitiveMap`
+**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
 
-Column primitive type mapping. TypeScript type name (string) to actual type.
+Maps TypeScript type names to actual types.
 
 ```typescript
 type ColumnPrimitiveMap = {
@@ -154,15 +181,14 @@ type ColumnPrimitiveMap = {
 };
 ```
 
-## `ColumnPrimitiveStr`
-
-Column primitive type name.
+### ColumnPrimitiveStr
 
 ```typescript
 type ColumnPrimitiveStr = keyof ColumnPrimitiveMap;
+// "string" | "number" | "boolean" | "DateTime" | "DateOnly" | "Time" | "Uuid" | "Bytes"
 ```
 
-## `ColumnPrimitive`
+### ColumnPrimitive
 
 All primitive types that can be stored in columns. `undefined` represents NULL.
 
@@ -170,29 +196,24 @@ All primitive types that can be stored in columns. `undefined` represents NULL.
 type ColumnPrimitive = ColumnPrimitiveMap[ColumnPrimitiveStr] | undefined;
 ```
 
-## `dataTypeStrToColumnPrimitiveStr`
+### dataTypeStrToColumnPrimitiveStr
 
-SQL DataType to TypeScript type name mapping.
+Constant mapping SQL DataType string to ColumnPrimitiveStr.
 
 ```typescript
-const dataTypeStrToColumnPrimitiveStr: {
-  int: "number"; bigint: "number"; float: "number"; double: "number"; decimal: "number";
-  varchar: "string"; char: "string"; text: "string";
-  binary: "Bytes"; boolean: "boolean";
-  datetime: "DateTime"; date: "DateOnly"; time: "Time"; uuid: "Uuid";
-};
+const dataTypeStrToColumnPrimitiveStr: Record<DataType["type"], ColumnPrimitiveStr>;
+// { int: "number", bigint: "number", varchar: "string", datetime: "DateTime", ... }
 ```
 
-## `InferColumnPrimitiveFromDataType`
+### InferColumnPrimitiveFromDataType
 
-TypeScript type inference from DataType.
+Infer TypeScript type from a `DataType`.
 
 ```typescript
-type InferColumnPrimitiveFromDataType<TDataType extends DataType> =
-  ColumnPrimitiveMap[(typeof dataTypeStrToColumnPrimitiveStr)[TDataType["type"]]];
+type InferColumnPrimitiveFromDataType<T extends DataType> = ColumnPrimitiveMap[...];
 ```
 
-## `inferColumnPrimitiveStr`
+### inferColumnPrimitiveStr
 
 Infer `ColumnPrimitiveStr` from a runtime value.
 
@@ -200,41 +221,11 @@ Infer `ColumnPrimitiveStr` from a runtime value.
 function inferColumnPrimitiveStr(value: ColumnPrimitive): ColumnPrimitiveStr;
 ```
 
-## `ColumnMeta`
-
-Column metadata. Generated by `ColumnBuilder` and passed to `TableBuilder`.
-
-```typescript
-interface ColumnMeta {
-  type: ColumnPrimitiveStr;
-  dataType: DataType;
-  autoIncrement?: boolean;
-  nullable?: boolean;
-  default?: ColumnPrimitive;
-  description?: string;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `type` | `ColumnPrimitiveStr` | TypeScript type name |
-| `dataType` | `DataType` | SQL data type |
-| `autoIncrement` | `boolean` | Whether to auto-increment |
-| `nullable` | `boolean` | Whether to allow NULL |
-| `default` | `ColumnPrimitive` | Default value |
-| `description` | `string` | Column description (DDL comment) |
+## QueryDef Types
 
-## `DateUnit`
+All query definition types used by the QueryBuilder.
 
-Date operation unit.
-
-```typescript
-type DateUnit = "year" | "month" | "day" | "hour" | "minute" | "second";
-```
-
-## `QueryDefObjectName`
-
-DB object name (table, view, procedure, etc.).
+### QueryDefObjectName
 
 ```typescript
 interface QueryDefObjectName {
@@ -244,31 +235,17 @@ interface QueryDefObjectName {
 }
 ```
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `database` | `string` | Database name |
-| `schema` | `string` | Schema name |
-| `name` | `string` | Object name |
-
-## `QueryDef`
-
-All query definition union type. DML + DDL + Utils + Meta.
+### CudOutputDef
 
 ```typescript
-type QueryDef =
-  | SelectQueryDef | InsertQueryDef | InsertIfNotExistsQueryDef | InsertIntoQueryDef
-  | UpdateQueryDef | DeleteQueryDef | UpsertQueryDef
-  | ClearSchemaQueryDef | CreateTableQueryDef | DropTableQueryDef | RenameTableQueryDef
-  | TruncateQueryDef | AddColumnQueryDef | DropColumnQueryDef | ModifyColumnQueryDef
-  | RenameColumnQueryDef | DropPrimaryKeyQueryDef | AddPrimaryKeyQueryDef
-  | AddForeignKeyQueryDef | DropForeignKeyQueryDef | AddIndexQueryDef | DropIndexQueryDef
-  | CreateViewQueryDef | DropViewQueryDef | CreateProcQueryDef | DropProcQueryDef
-  | ExecProcQueryDef | SwitchFkQueryDef | SchemaExistsQueryDef;
+interface CudOutputDef {
+  columns: string[];
+  pkColNames: string[];
+  aiColName?: string;
+}
 ```
 
-## `SelectQueryDef`
-
-SELECT query definition.
+### SelectQueryDef
 
 ```typescript
 interface SelectQueryDef {
@@ -289,9 +266,7 @@ interface SelectQueryDef {
 }
 ```
 
-## `SelectQueryDefJoin`
-
-JOIN query definition. Extends `SelectQueryDef` with `isSingle` flag.
+### SelectQueryDefJoin
 
 ```typescript
 interface SelectQueryDefJoin extends SelectQueryDef {
@@ -299,9 +274,7 @@ interface SelectQueryDefJoin extends SelectQueryDef {
 }
 ```
 
-## `InsertQueryDef`
-
-INSERT query definition.
+### InsertQueryDef
 
 ```typescript
 interface InsertQueryDef {
@@ -313,38 +286,30 @@ interface InsertQueryDef {
 }
 ```
 
-## `InsertIfNotExistsQueryDef`
-
-Conditional INSERT query definition. Insert only if not exists.
+### InsertIfNotExistsQueryDef
 
 ```typescript
 interface InsertIfNotExistsQueryDef {
   type: "insertIfNotExists";
   table: QueryDefObjectName;
   record: Record<string, ColumnPrimitive>;
-  existsSelectQuery: SelectQueryDef;
-  overrideIdentity?: boolean;
+  existsSelectQuery: Omit<SelectQueryDef, "select">;
   output?: CudOutputDef;
 }
 ```
 
-## `InsertIntoQueryDef`
-
-INSERT INTO SELECT query definition. Insert subquery results.
+### InsertIntoQueryDef
 
 ```typescript
 interface InsertIntoQueryDef {
   type: "insertInto";
   table: QueryDefObjectName;
   recordsSelectQuery: SelectQueryDef;
-  overrideIdentity?: boolean;
   output?: CudOutputDef;
 }
 ```
 
-## `UpdateQueryDef`
-
-UPDATE query definition.
+### UpdateQueryDef
 
 ```typescript
 interface UpdateQueryDef {
@@ -360,9 +325,7 @@ interface UpdateQueryDef {
 }
 ```
 
-## `DeleteQueryDef`
-
-DELETE query definition.
+### DeleteQueryDef
 
 ```typescript
 interface DeleteQueryDef {
@@ -377,69 +340,162 @@ interface DeleteQueryDef {
 }
 ```
 
-## `UpsertQueryDef`
-
-UPSERT query definition. INSERT or UPDATE (MERGE pattern).
+### UpsertQueryDef
 
 ```typescript
 interface UpsertQueryDef {
   type: "upsert";
   table: QueryDefObjectName;
-  existsSelectQuery: SelectQueryDef;
-  insertRecord: Record<string, Expr>;
+  existsSelectQuery: Omit<SelectQueryDef, "select">;
   updateRecord: Record<string, Expr>;
-  overrideIdentity?: boolean;
+  insertRecord: Record<string, Expr>;
   output?: CudOutputDef;
 }
 ```
 
-## `CudOutputDef`
-
-CUD query OUTPUT clause definition.
+### 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
-interface CudOutputDef {
-  columns: string[];
-  pkColNames: string[];
-  aiColName?: string;
-}
+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;
 ```
 
-## `DDL_TYPES`
+## Expr Types
+
+All expression AST node types. See [expression.md](expression.md) for the `expr` builder API.
 
-DDL type constants. Used for blocking DDL within transactions.
+### DateUnit
 
 ```typescript
-const DDL_TYPES: readonly string[];
+type DateUnit = "year" | "month" | "day" | "hour" | "minute" | "second";
 ```
 
-## `DdlType`
+### WhereExpr
 
-DDL type union.
+Union of all WHERE-clause expression types.
 
 ```typescript
-type DdlType = (typeof DDL_TYPES)[number];
+type WhereExpr =
+  | ExprEq | ExprGt | ExprLt | ExprGte | ExprLte | ExprBetween
+  | ExprIsNull | ExprLike | ExprRegexp | ExprIn | ExprInQuery | ExprExists
+  | ExprNot | ExprAnd | ExprOr;
 ```
 
-## Expression Types (Expr)
-
-Union type `Expr` covers all expression types: value (`ExprColumn`, `ExprValue`, `ExprRaw`), string, numeric, date, conditional, aggregate, window, and subquery expressions.
+### Expr
 
-Union type `WhereExpr` covers comparison (`ExprEq`, `ExprGt`, `ExprLt`, `ExprGte`, `ExprLte`, `ExprBetween`, `ExprIsNull`, `ExprLike`, `ExprRegexp`, `ExprIn`, `ExprInQuery`, `ExprExists`) and logical (`ExprNot`, `ExprAnd`, `ExprOr`) expressions.
+Union of all expression types (values, functions, aggregates, window, etc.).
 
-## Window Types
+```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;
+```
 
-`WinFn` is a union of all window function types: `WinFnRowNumber`, `WinFnRank`, `WinFnDenseRank`, `WinFnNtile`, `WinFnLag`, `WinFnLead`, `WinFnFirstValue`, `WinFnLastValue`, `WinFnSum`, `WinFnAvg`, `WinFnCount`, `WinFnMin`, `WinFnMax`.
+### WinSpec
 
 ```typescript
 interface WinSpec {
   partitionBy?: Expr[];
   orderBy?: [Expr, ("ASC" | "DESC")?][];
 }
+```
 
-interface ExprWindow {
-  type: "window";
-  fn: WinFn;
-  spec: WinSpec;
-}
+### 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,8 +1,8 @@
 {
   "name": "@simplysm/orm-common",
-  "version": "13.0.100",
-  "description": "Simplysm Package - ORM Module (common)",
-  "author": "simplysm",
+  "version": "14.0.4",
+  "description": "심플리즘 패키지 - ORM (common)",
+  "author": "심플리즘",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -15,11 +15,13 @@
   "files": [
     "dist",
     "src",
-    "tests",
     "docs"
   ],
   "sideEffects": false,
+  "devDependencies": {
+    "@types/node": "^20.19.37"
+  },
   "dependencies": {
-    "@simplysm/core-common": "13.0.100"
+    "@simplysm/core-common": "14.0.4"
   }
 }