@simplysm/orm-common 13.0.96 → 13.0.98

package/docs/types.md

@@ -0,0 +1,445 @@
+# Types
+
+TypeScript types for dialects, queries, expressions, columns, and results.
+
+Source: `src/types/db.ts`, `src/types/column.ts`, `src/types/expr.ts`, `src/types/query-def.ts`
+
+## Database Types
+
+Source: `src/types/db.ts`
+
+### Dialect
+
+```typescript
+type Dialect = "mysql" | "mssql" | "postgresql";
+```
+
+- `mysql`: MySQL 8.0.14+
+- `mssql`: Microsoft SQL Server 2012+
+- `postgresql`: PostgreSQL 9.0+
+
+### dialects
+
+```typescript
+const dialects: Dialect[] = ["mysql", "mssql", "postgresql"];
+```
+
+### QueryBuildResult
+
+Return type of `QueryBuilderBase.build()`.
+
+```typescript
+interface QueryBuildResult {
+  /** Built SQL string */
+  sql: string;
+  /** Result set index to fetch results from (default: 0) */
+  resultSetIndex?: number;
+  /** Extract every Nth result set from multiple results */
+  resultSetStride?: number;
+}
+```
+
+### IsolationLevel
+
+```typescript
+type IsolationLevel =
+  | "READ_UNCOMMITTED"
+  | "READ_COMMITTED"
+  | "REPEATABLE_READ"
+  | "SERIALIZABLE";
+```
+
+### DataRecord
+
+Recursive record type for query results, supporting nested relations.
+
+```typescript
+type DataRecord = {
+  [key: string]: ColumnPrimitive | DataRecord | DataRecord[];
+};
+```
+
+### DbContextExecutor
+
+Interface for actual DB connection and query execution. Implemented by `NodeDbContextExecutor` (server) or service client executors.
+
+```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 query result transformation (type parsing and JOIN nesting).
+
+```typescript
+interface ResultMeta {
+  /** Column name -> ColumnPrimitiveStr mapping */
+  columns: Record<string, ColumnPrimitiveStr>;
+  /** JOIN alias -> single/array indicator */
+  joins: Record<string, { isSingle: boolean }>;
+}
+```
+
+### Migration
+
+Database migration definition.
+
+```typescript
+interface Migration {
+  name: string;
+  up: (db: DbContextBase & DbContextDdlMethods) => Promise<void>;
+}
+```
+
+**Example:**
+
+```typescript
+const migrations: Migration[] = [
+  {
+    name: "20260105_001_create_user_table",
+    up: async (db) => {
+      await db.createTable(User);
+    },
+  },
+];
+```
+
+---
+
+## Column Types
+
+Source: `src/types/column.ts`
+
+### DataType
+
+SQL data type definition (discriminated union).
+
+```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" };
+```
+
+### ColumnPrimitiveMap
+
+TypeScript type name to actual type mapping.
+
+```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;
+```
+
+### ColumnMeta
+
+Column metadata generated by `ColumnBuilder`.
+
+```typescript
+interface ColumnMeta {
+  type: ColumnPrimitiveStr;
+  dataType: DataType;
+  autoIncrement?: boolean;
+  nullable?: boolean;
+  default?: ColumnPrimitive;
+  description?: string;
+}
+```
+
+### dataTypeStrToColumnPrimitiveStr
+
+SQL DataType type string to TypeScript type name mapping.
+
+```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";
+};
+```
+
+### InferColumnPrimitiveFromDataType
+
+Infer TypeScript type from `DataType`.
+
+```typescript
+type InferColumnPrimitiveFromDataType<TDataType extends DataType> =
+  ColumnPrimitiveMap[(typeof dataTypeStrToColumnPrimitiveStr)[TDataType["type"]]];
+```
+
+### inferColumnPrimitiveStr (function)
+
+Infer `ColumnPrimitiveStr` from a runtime value.
+
+```typescript
+function inferColumnPrimitiveStr(value: ColumnPrimitive): ColumnPrimitiveStr;
+```
+
+---
+
+## Expression Types
+
+Source: `src/types/expr.ts`
+
+### DateUnit
+
+```typescript
+type DateUnit = "year" | "month" | "day" | "hour" | "minute" | "second";
+```
+
+### Expr (union type)
+
+Discriminated union of all expression AST node types. Used in `select()`, `orderBy()`, etc.
+
+| Category | Types |
+|----------|-------|
+| Value | `ExprColumn`, `ExprValue`, `ExprRaw` |
+| String | `ExprConcat`, `ExprLeft`, `ExprRight`, `ExprTrim`, `ExprPadStart`, `ExprReplace`, `ExprUpper`, `ExprLower`, `ExprLength`, `ExprByteLength`, `ExprSubstring`, `ExprIndexOf` |
+| Numeric | `ExprAbs`, `ExprRound`, `ExprCeil`, `ExprFloor` |
+| Date | `ExprYear`, `ExprMonth`, `ExprDay`, `ExprHour`, `ExprMinute`, `ExprSecond`, `ExprIsoWeek`, `ExprIsoWeekStartDate`, `ExprIsoYearMonth`, `ExprDateDiff`, `ExprDateAdd`, `ExprFormatDate` |
+| Condition | `ExprCoalesce`, `ExprNullIf`, `ExprIs`, `ExprSwitch`, `ExprIf` |
+| Aggregate | `ExprCount`, `ExprSum`, `ExprAvg`, `ExprMax`, `ExprMin` |
+| Other | `ExprGreatest`, `ExprLeast`, `ExprRowNum`, `ExprRandom`, `ExprCast` |
+| Window | `ExprWindow` |
+| System | `ExprSubquery` |
+
+### WhereExpr (union type)
+
+Subset of `Expr` for WHERE clauses (comparison + logical operators).
+
+| Category | Types |
+|----------|-------|
+| Comparison | `ExprEq`, `ExprGt`, `ExprLt`, `ExprGte`, `ExprLte`, `ExprBetween`, `ExprIsNull`, `ExprLike`, `ExprRegexp`, `ExprIn`, `ExprInQuery`, `ExprExists` |
+| Logical | `ExprNot`, `ExprAnd`, `ExprOr` |
+
+### Individual Expr Interfaces
+
+Each expression type is a simple interface with a `type` discriminant:
+
+```typescript
+interface ExprColumn { type: "column"; path: string[]; }
+interface ExprValue { type: "value"; value: ColumnPrimitive; }
+interface ExprRaw { type: "raw"; sql: string; params: Expr[]; }
+interface ExprEq { type: "eq"; source: Expr; target: Expr; }
+interface ExprGt { type: "gt"; source: Expr; target: Expr; }
+// ... etc.
+```
+
+### Window Function Types
+
+```typescript
+type WinFn =
+  | WinFnRowNumber | WinFnRank | WinFnDenseRank | WinFnNtile
+  | WinFnLag | WinFnLead | WinFnFirstValue | WinFnLastValue
+  | WinFnSum | WinFnAvg | WinFnCount | WinFnMin | WinFnMax;
+
+interface WinSpec {
+  partitionBy?: Expr[];
+  orderBy?: [Expr, ("ASC" | "DESC")?][];
+}
+
+interface ExprWindow {
+  type: "window";
+  fn: WinFn;
+  spec: WinSpec;
+}
+```
+
+---
+
+## Query Definition Types
+
+Source: `src/types/query-def.ts`
+
+### QueryDefObjectName
+
+```typescript
+interface QueryDefObjectName {
+  database?: string;
+  schema?: string;
+  name: string;
+}
+```
+
+DBMS-specific namespaces:
+- MySQL: `database.name` (schema ignored)
+- MSSQL: `database.schema.name` (schema defaults to dbo)
+- PostgreSQL: `schema.name` (database is for connection only)
+
+### QueryDef (union type)
+
+Union of all query definition types:
+
+**DML:** `SelectQueryDef`, `InsertQueryDef`, `InsertIfNotExistsQueryDef`, `InsertIntoQueryDef`, `UpdateQueryDef`, `DeleteQueryDef`, `UpsertQueryDef`
+
+**DDL - Schema:** `ClearSchemaQueryDef`
+
+**DDL - Table:** `CreateTableQueryDef`, `DropTableQueryDef`, `RenameTableQueryDef`, `TruncateQueryDef`
+
+**DDL - Column:** `AddColumnQueryDef`, `DropColumnQueryDef`, `ModifyColumnQueryDef`, `RenameColumnQueryDef`
+
+**DDL - Constraint:** `DropPrimaryKeyQueryDef`, `AddPrimaryKeyQueryDef`, `AddForeignKeyQueryDef`, `DropForeignKeyQueryDef`, `AddIndexQueryDef`, `DropIndexQueryDef`
+
+**DDL - View/Procedure:** `CreateViewQueryDef`, `DropViewQueryDef`, `CreateProcQueryDef`, `DropProcQueryDef`, `ExecProcQueryDef`
+
+**Utils:** `SwitchFkQueryDef`
+
+**Meta:** `SchemaExistsQueryDef`
+
+### 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;
+}
+```
+
+### 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: SelectQueryDef;
+  insertRecord: Record<string, Expr>;
+  updateRecord: Record<string, Expr>;
+  overrideIdentity?: boolean;
+  output?: CudOutputDef;
+}
+```
+
+### CudOutputDef
+
+```typescript
+interface CudOutputDef {
+  columns: string[];
+  pkColNames: string[];
+  aiColName?: string;
+}
+```
+
+### DDL_TYPES
+
+Constant array of all DDL type strings (for blocking DDL within transactions).
+
+```typescript
+const DDL_TYPES: readonly DdlType[];
+```

package/docs/utilities.md

@@ -0,0 +1,122 @@
+# Utilities
+
+Result parsing helpers for transforming raw database output to typed TypeScript objects.
+
+Source: `src/utils/result-parser.ts`
+
+## parseQueryResult
+
+Transform raw DB query results to TypeScript objects via `ResultMeta`. Handles type parsing, flat-to-nested transformation, and JOIN grouping.
+
+```typescript
+async function parseQueryResult<TRecord>(
+  rawResults: Record<string, unknown>[],
+  meta: ResultMeta,
+): Promise<TRecord[] | undefined>;
+```
+
+**Parameters:**
+
+- `rawResults` -- Raw result array from the database driver (flat key-value records)
+- `meta` -- Type transformation and JOIN structure information (`ResultMeta`)
+
+**Returns:**
+
+- Type-transformed and nested result array, or `undefined` if input is empty or all records are empty after parsing
+
+**Behavior:**
+
+- **Type parsing** -- Converts raw values (strings from DB) to proper TypeScript types based on `meta.columns` mapping (e.g., `"1"` to `1` for number, `"2026-01-15T10:00:00Z"` to `DateTime`)
+- **Flat-to-nested** -- Transforms dot-notation keys to nested objects (e.g., `"posts.id"` becomes `{ posts: { id: ... } }`)
+- **JOIN grouping** -- Groups rows by non-JOIN columns, collecting JOIN data into arrays (1:N) or single objects (1:1)
+- **Async** -- Yields to the event loop every 100 records to prevent blocking
+- **Empty handling** -- Returns `undefined` for empty input or when all parsed records are empty objects
+
+### Example: Simple Type Parsing
+
+```typescript
+const raw = [
+  { id: "1", name: "Alice", createdAt: "2026-01-07T10:00:00.000Z" },
+];
+
+const meta: ResultMeta = {
+  columns: { id: "number", name: "string", createdAt: "DateTime" },
+  joins: {},
+};
+
+const result = await parseQueryResult(raw, meta);
+// [{ id: 1, name: "Alice", createdAt: DateTime("2026-01-07T10:00:00.000Z") }]
+```
+
+### Example: JOIN Result Nesting
+
+```typescript
+const raw = [
+  { id: 1, name: "User1", "posts.id": 10, "posts.title": "Post1" },
+  { id: 1, name: "User1", "posts.id": 11, "posts.title": "Post2" },
+  { id: 2, name: "User2", "posts.id": 20, "posts.title": "Post3" },
+];
+
+const meta: ResultMeta = {
+  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" }] },
+//   { id: 2, name: "User2", posts: [{ id: 20, title: "Post3" }] },
+// ]
+```
+
+### Example: Single JOIN (1:1)
+
+```typescript
+const raw = [
+  { id: 1, title: "Post1", "author.id": 10, "author.name": "Alice" },
+  { id: 2, title: "Post2", "author.id": 10, "author.name": "Alice" },
+];
+
+const meta: ResultMeta = {
+  columns: {
+    id: "number",
+    title: "string",
+    "author.id": "number",
+    "author.name": "string",
+  },
+  joins: {
+    author: { isSingle: true },
+  },
+};
+
+const result = await parseQueryResult(raw, meta);
+// [
+//   { id: 1, title: "Post1", author: { id: 10, name: "Alice" } },
+//   { id: 2, title: "Post2", author: { id: 10, name: "Alice" } },
+// ]
+```
+
+---
+
+## Type Parsing Rules
+
+| ColumnPrimitiveStr | Input | Output |
+|--------------------|-------|--------|
+| `"number"` | `"123"` / `123` | `123` (throws if NaN) |
+| `"string"` | any | `String(value)` |
+| `"boolean"` | `0` / `"0"` / `false` | `false` |
+| `"boolean"` | `1` / `"1"` / `true` | `true` |
+| `"DateTime"` | ISO string | `DateTime.parse(value)` |
+| `"DateOnly"` | date string | `DateOnly.parse(value)` |
+| `"Time"` | time string | `Time.parse(value)` |
+| `"Uuid"` | `Uint8Array` / string | `Uuid.fromBytes(value)` / `new Uuid(value)` |
+| `"Bytes"` | `Uint8Array` / hex string | as-is / `bytes.fromHex(value)` |
+
+`null` and `undefined` values are returned as `undefined` (keys are omitted from the result).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/orm-common",
-  "version": "13.0.96",
+  "version": "13.0.98",
   "description": "Simplysm Package - ORM Module (common)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -20,6 +20,6 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@simplysm/core-common": "13.0.96"
+    "@simplysm/core-common": "13.0.98"
   }
 }