@simplysm/orm-common 14.0.4 → 14.0.5

package/docs/expression.md

@@ -2,216 +2,219 @@
 
 Dialect-independent SQL expression builder. Generates JSON AST (`Expr`) instead of SQL strings. The QueryBuilder transforms the AST to target DBMS syntax.
 
-## expr
-
-Constant object with all expression builder methods. Used inside Queryable callbacks for `where()`, `select()`, `orderBy()`, etc.
-
-### Value Generation
-
-| Method | Signature | Description |
-|---|---|---|
-| `val` | `(dataType: ColumnPrimitiveStr, value) => ExprUnit` | Wrap literal value as ExprUnit |
-| `col` | `(dataType, ...path: string[]) => ExprUnit` | Generate column reference (internal use) |
-| `raw` | `(dataType) => tagged template => ExprUnit` | Raw SQL expression (escape hatch). Interpolated values are auto-parameterized. |
-
-**Example:**
+## ExprUnit
 
 ```typescript
-expr.val("string", "active")
-expr.val("number", 100)
-expr.val("DateOnly", DateOnly.today())
-expr.raw("string")`JSON_EXTRACT(${u.metadata}, '$.email')`
+class ExprUnit<TPrimitive extends ColumnPrimitive> {
+  readonly $infer!: TPrimitive;
+  readonly dataType: ColumnPrimitiveStr;
+  readonly expr: Expr;
+  get n(): ExprUnit<NonNullable<TPrimitive>>;
+  constructor(dataType: ColumnPrimitiveStr, expr: Expr);
+}
 ```
 
-### Comparison Operators (WHERE)
-
-| Method | Signature | Description |
-|---|---|---|
-| `eq` | `(source, target) => WhereExprUnit` | Equality (NULL-safe: MySQL `<=>`) |
-| `gt` | `(source, target) => WhereExprUnit` | Greater than (`>`) |
-| `lt` | `(source, target) => WhereExprUnit` | Less than (`<`) |
-| `gte` | `(source, target) => WhereExprUnit` | Greater than or equal (`>=`) |
-| `lte` | `(source, target) => WhereExprUnit` | Less than or equal (`<=`) |
-| `between` | `(source, from?, to?) => WhereExprUnit` | Range (BETWEEN). Undefined bounds are unbounded. |
-
-### NULL Check
-
-| Method | Signature | Description |
-|---|---|---|
-| `null` | `(source) => WhereExprUnit` | IS NULL check |
+Type-safe expression wrapper. Tracks the return type via the `TPrimitive` generic parameter.
 
-### String Search
+| Member | Type | Description |
+|--------|------|-------------|
+| `$infer` | `TPrimitive` | Type inference helper (phantom type) |
+| `dataType` | `ColumnPrimitiveStr` | Runtime type name (`"string"`, `"number"`, etc.) |
+| `expr` | `Expr` | Underlying JSON AST expression |
+| `n` | `ExprUnit<NonNullable<TPrimitive>>` | Getter that narrows nullable to non-nullable |
 
-| Method | Signature | Description |
-|---|---|---|
-| `like` | `(source, pattern) => WhereExprUnit` | LIKE pattern matching (`%`, `_` wildcards) |
-| `regexp` | `(source, pattern) => WhereExprUnit` | Regular expression matching |
+## WhereExprUnit
 
-### IN / EXISTS
+```typescript
+class WhereExprUnit {
+  readonly expr: WhereExpr;
+  constructor(expr: WhereExpr);
+}
+```
 
-| Method | Signature | Description |
-|---|---|---|
-| `in` | `(source, values[]) => WhereExprUnit` | IN value list |
-| `inQuery` | `(source, query: Queryable) => WhereExprUnit` | IN subquery (single-column SELECT) |
-| `exists` | `(query: Queryable) => WhereExprUnit` | EXISTS subquery |
+WHERE clause expression wrapper. Returned by comparison and logical methods on `expr`.
 
-### Logical Operators
+## ExprInput
 
-| Method | Signature | Description |
-|---|---|---|
-| `not` | `(arg: WhereExprUnit) => WhereExprUnit` | NOT |
-| `and` | `(conditions: WhereExprUnit[]) => WhereExprUnit` | AND (all must match) |
-| `or` | `(conditions: WhereExprUnit[]) => WhereExprUnit` | OR (any must match) |
+```typescript
+type ExprInput<TPrimitive extends ColumnPrimitive> = ExprUnit<TPrimitive> | TPrimitive;
+```
 
-### String Functions (SELECT)
+Accepts either an `ExprUnit` or a literal value. Literal values are automatically wrapped.
 
-| Method | Signature | Description |
-|---|---|---|
-| `concat` | `(...args) => ExprUnit<string>` | String concatenation (CONCAT) |
-| `left` | `(source, length) => ExprUnit` | Left N characters |
-| `right` | `(source, length) => ExprUnit` | Right N characters |
-| `trim` | `(source) => ExprUnit` | Trim whitespace |
-| `padStart` | `(source, length, fillString) => ExprUnit` | Left padding (LPAD) |
-| `replace` | `(source, from, to) => ExprUnit` | String replacement |
-| `upper` | `(source) => ExprUnit` | Uppercase |
-| `lower` | `(source) => ExprUnit` | Lowercase |
-| `length` | `(source) => ExprUnit<number>` | Character length |
-| `byteLength` | `(source) => ExprUnit<number>` | Byte length |
-| `substring` | `(source, start, length?) => ExprUnit` | Substring (1-based index) |
-| `indexOf` | `(source, search) => ExprUnit<number>` | Find position (1-based, 0 if not found) |
-
-### Number Functions (SELECT)
+## SwitchExprBuilder
 
-| Method | Signature | Description |
-|---|---|---|
-| `abs` | `(source) => ExprUnit` | Absolute value |
-| `round` | `(source, digits) => ExprUnit` | Round |
-| `ceil` | `(source) => ExprUnit` | Ceiling |
-| `floor` | `(source) => ExprUnit` | Floor |
+```typescript
+interface SwitchExprBuilder<TPrimitive extends ColumnPrimitive> {
+  case(condition: WhereExprUnit, then: ExprInput<TPrimitive>): SwitchExprBuilder<TPrimitive>;
+  default(value: ExprInput<TPrimitive>): ExprUnit<TPrimitive>;
+}
+```
 
-### Date/Time Functions (SELECT)
+Fluent CASE WHEN builder. Chain `.case()` calls and terminate with `.default()`.
 
-| Method | Signature | Description |
-|---|---|---|
-| `year` | `(source) => ExprUnit<number>` | Extract year |
-| `month` | `(source) => ExprUnit<number>` | Extract month |
-| `day` | `(source) => ExprUnit<number>` | Extract day |
-| `hour` | `(source) => ExprUnit<number>` | Extract hour |
-| `minute` | `(source) => ExprUnit<number>` | Extract minute |
-| `second` | `(source) => ExprUnit<number>` | Extract second |
-| `isoWeek` | `(source) => ExprUnit<number>` | ISO week number |
-| `isoWeekStartDate` | `(source) => ExprUnit<DateOnly>` | ISO week start date (Monday) |
-| `isoYearMonth` | `(source) => ExprUnit<DateOnly>` | ISO year-month (YYYYMM format) |
-| `dateDiff` | `(unit: DateUnit, from, to) => ExprUnit<number>` | Date difference |
-| `dateAdd` | `(unit: DateUnit, source, value) => ExprUnit` | Date arithmetic |
-| `formatDate` | `(source, format: string) => ExprUnit<string>` | Date formatting |
-
-### Conditional
+## expr Object
 
-| Method | Signature | Description |
-|---|---|---|
-| `coalesce` | `(...args) => ExprUnit` | First non-null value (COALESCE) |
-| `nullIf` | `(source, value) => ExprUnit` | NULL if equal (NULLIF) |
-| `is` | `(condition: WhereExprUnit) => ExprUnit<boolean>` | Convert condition to boolean (0/1) |
-| `switch` | `() => SwitchExprBuilder` | CASE WHEN expression (chain `.case().default()`) |
-| `if` | `(condition, then, else?) => ExprUnit` | IIF conditional expression |
+The `expr` object provides all expression-building methods. Methods are grouped by category below.
 
-### Aggregate Functions
+### Value Creation
 
 | Method | Signature | Description |
-|---|---|---|
-| `count` | `(arg?, distinct?) => ExprUnit<number>` | COUNT |
-| `sum` | `(arg) => ExprUnit<number \| undefined>` | SUM |
-| `avg` | `(arg) => ExprUnit<number \| undefined>` | AVG |
-| `max` | `(arg) => ExprUnit<T \| undefined>` | MAX |
-| `min` | `(arg) => ExprUnit<T \| undefined>` | MIN |
+|--------|-----------|-------------|
+| `val` | `<TStr extends ColumnPrimitiveStr>(dataType: TStr, value: T) => ExprUnit` | Wrap a literal value into an ExprUnit |
+| `col` | `<TStr extends ColumnPrimitiveStr>(dataType: ColumnPrimitiveStr, ...path: string[]) => ExprUnit` | Create a column reference |
+| `raw` | `<T extends ColumnPrimitiveStr>(dataType: T) => (strings: TemplateStringsArray, ...values: ExprInput[]) => ExprUnit` | Raw SQL via tagged template literal; interpolated values become parameters |
 
-### Utility
+### Comparison (WHERE)
 
-| Method | Signature | Description |
-|---|---|---|
-| `greatest` | `(...args) => ExprUnit` | Greatest of values |
-| `least` | `(...args) => ExprUnit` | Least of values |
-| `rowNum` | `() => ExprUnit<number>` | Simple row number |
-| `random` | `() => ExprUnit<number>` | Random number (RAND/RANDOM) |
-| `cast` | `(source, targetType: DataType) => ExprUnit` | Type cast |
-| `subquery` | `(dataType, queryDef: SelectQueryDef) => ExprUnit` | Scalar subquery |
-| `toExpr` | `(value: ExprInput) => Expr` | Convert ExprInput to raw Expr AST |
+| Method | Signature | SQL | Description |
+|--------|-----------|-----|-------------|
+| `eq` | `(source: ExprUnit<T>, target: ExprInput<T>) => WhereExprUnit` | `<=>` / `IS NULL OR =` | NULL-safe equality |
+| `gt` | `(source: ExprUnit<T>, target: ExprInput<T>) => WhereExprUnit` | `>` | Greater than |
+| `lt` | `(source: ExprUnit<T>, target: ExprInput<T>) => WhereExprUnit` | `<` | Less than |
+| `gte` | `(source: ExprUnit<T>, target: ExprInput<T>) => WhereExprUnit` | `>=` | Greater than or equal |
+| `lte` | `(source: ExprUnit<T>, target: ExprInput<T>) => WhereExprUnit` | `<=` | Less than or equal |
+| `between` | `(source: ExprUnit<T>, from?: ExprInput<T>, to?: ExprInput<T>) => WhereExprUnit` | `BETWEEN` | Range comparison (undefined bounds omitted) |
 
-### Window Functions
+### NULL Check (WHERE)
 
-All window functions accept a `WinSpecInput: { partitionBy?: ExprInput[]; orderBy?: [ExprInput, ("ASC" | "DESC")?][] }`.
+| Method | Signature | SQL | Description |
+|--------|-----------|-----|-------------|
+| `null` | `(source: ExprUnit<T>) => WhereExprUnit` | `IS NULL` | NULL check |
 
-| Method | Signature | Description |
-|---|---|---|
-| `rowNumber` | `(spec) => ExprUnit<number>` | ROW_NUMBER() OVER(...) |
-| `rank` | `(spec) => ExprUnit<number>` | RANK() OVER(...) |
-| `denseRank` | `(spec) => ExprUnit<number>` | DENSE_RANK() OVER(...) |
-| `ntile` | `(n, spec) => ExprUnit<number>` | NTILE(n) OVER(...) |
-| `lag` | `(column, spec, offset?, defaultValue?) => ExprUnit` | Previous row value |
-| `lead` | `(column, spec, offset?, defaultValue?) => ExprUnit` | Next row value |
-| `firstValue` | `(column, spec) => ExprUnit` | First value in partition |
-| `lastValue` | `(column, spec) => ExprUnit` | Last value in partition |
-| `sumOver` | `(column, spec) => ExprUnit<number \| undefined>` | Window SUM |
-| `avgOver` | `(column, spec) => ExprUnit<number \| undefined>` | Window AVG |
-| `countOver` | `(spec, column?) => ExprUnit<number>` | Window COUNT |
-| `minOver` | `(column, spec) => ExprUnit` | Window MIN |
-| `maxOver` | `(column, spec) => ExprUnit` | Window MAX |
+### String Search (WHERE)
 
-## SwitchExprBuilder
+| Method | Signature | SQL | Description |
+|--------|-----------|-----|-------------|
+| `like` | `(source: ExprUnit<string\|undefined>, pattern: ExprInput<string\|undefined>) => WhereExprUnit` | `LIKE ... ESCAPE '\'` | Pattern matching |
+| `regexp` | `(source: ExprUnit<string\|undefined>, pattern: ExprInput<string\|undefined>) => WhereExprUnit` | `REGEXP` | Regex matching |
 
-Builder interface for CASE WHEN expressions. Created by `expr.switch()`.
+### IN / EXISTS (WHERE)
 
-```typescript
-interface SwitchExprBuilder<TPrimitive extends ColumnPrimitive> {
-  case(condition: WhereExprUnit, then: ExprInput<TPrimitive>): SwitchExprBuilder<TPrimitive>;
-  default(value: ExprInput<TPrimitive>): ExprUnit<TPrimitive>;
-}
-```
+| Method | Signature | SQL | Description |
+|--------|-----------|-----|-------------|
+| `in` | `(source: ExprUnit<T>, values: ExprInput<T>[]) => WhereExprUnit` | `IN (...)` | List membership |
+| `inQuery` | `(source: ExprUnit<T>, query: Queryable<...>) => WhereExprUnit` | `IN (SELECT ...)` | Subquery membership (single column) |
+| `exists` | `(query: Queryable<any, any>) => WhereExprUnit` | `EXISTS (SELECT ...)` | Subquery existence check |
 
-**Example:**
+### Logical (WHERE)
 
-```typescript
-db.user().select((u) => ({
-  tier: expr.switch<string>()
-    .case(expr.gte(u.score, 90), "gold")
-    .case(expr.gte(u.score, 70), "silver")
-    .default("bronze"),
-}))
-```
+| Method | Signature | SQL | Description |
+|--------|-----------|-----|-------------|
+| `not` | `(arg: WhereExprUnit) => WhereExprUnit` | `NOT (...)` | Negate condition |
+| `and` | `(conditions: WhereExprUnit[]) => WhereExprUnit` | `... AND ...` | All conditions must match |
+| `or` | `(conditions: WhereExprUnit[]) => WhereExprUnit` | `... OR ...` | At least one condition must match |
 
-## ExprUnit
+### String Functions (SELECT)
 
-Type-safe expression wrapper that tracks the return type through TypeScript generics.
+| Method | Signature | SQL | Description |
+|--------|-----------|-----|-------------|
+| `concat` | `(...args: ExprInput<string\|undefined>[]) => ExprUnit<string>` | `CONCAT(...)` | String concatenation (NULL becomes empty) |
+| `left` | `(source, length) => ExprUnit<T>` | `LEFT(source, n)` | Left substring |
+| `right` | `(source, length) => ExprUnit<T>` | `RIGHT(source, n)` | Right substring |
+| `trim` | `(source) => ExprUnit<T>` | `TRIM(source)` | Remove leading/trailing whitespace |
+| `padStart` | `(source, length, fillString) => ExprUnit<T>` | `LPAD(...)` | Left-pad to target length |
+| `replace` | `(source, from, to) => ExprUnit<T>` | `REPLACE(...)` | String replacement |
+| `upper` | `(source) => ExprUnit<T>` | `UPPER(source)` | Uppercase |
+| `lower` | `(source) => ExprUnit<T>` | `LOWER(source)` | Lowercase |
+| `length` | `(source) => ExprUnit<number>` | `CHAR_LENGTH(source)` | Character count |
+| `byteLength` | `(source) => ExprUnit<number>` | `OCTET_LENGTH(source)` | Byte count |
+| `substring` | `(source, start, length?) => ExprUnit<T>` | `SUBSTRING(source, start, length)` | Extract substring (1-based index) |
+| `indexOf` | `(source, search) => ExprUnit<number>` | `LOCATE(search, source)` | Find position (1-based, 0 if not found) |
+
+### Math Functions (SELECT)
+
+| Method | Signature | SQL | Description |
+|--------|-----------|-----|-------------|
+| `abs` | `(source) => ExprUnit<T>` | `ABS(source)` | Absolute value |
+| `round` | `(source, digits) => ExprUnit<T>` | `ROUND(source, digits)` | Round to N decimal places |
+| `ceil` | `(source) => ExprUnit<T>` | `CEILING(source)` | Round up |
+| `floor` | `(source) => ExprUnit<T>` | `FLOOR(source)` | Round down |
+
+### Date Functions (SELECT)
+
+| Method | Signature | SQL | Description |
+|--------|-----------|-----|-------------|
+| `year` | `(source) => ExprUnit<number>` | `YEAR(source)` | Extract year (4-digit) |
+| `month` | `(source) => ExprUnit<number>` | `MONTH(source)` | Extract month (1-12) |
+| `day` | `(source) => ExprUnit<number>` | `DAY(source)` | Extract day (1-31) |
+| `hour` | `(source) => ExprUnit<number>` | `HOUR(source)` | Extract hour (0-23) |
+| `minute` | `(source) => ExprUnit<number>` | `MINUTE(source)` | Extract minute (0-59) |
+| `second` | `(source) => ExprUnit<number>` | `SECOND(source)` | Extract second (0-59) |
+| `isoWeek` | `(source) => ExprUnit<number>` | `WEEK(source, 3)` | ISO week number (1-53) |
+| `isoWeekStartDate` | `(source) => ExprUnit<T>` | Computed | Monday of the source date's week |
+| `isoYearMonth` | `(source) => ExprUnit<T>` | Computed | First day of the source date's month |
+| `dateDiff` | `(unit: DateUnit, from, to) => ExprUnit<number>` | `DATEDIFF(unit, from, to)` | Date difference (to - from) |
+| `dateAdd` | `(unit: DateUnit, source, value) => ExprUnit<T>` | `DATEADD(unit, value, source)` | Add time to date |
+| `formatDate` | `(source, format: string) => ExprUnit<string>` | `DATE_FORMAT(...)` | Format date as string |
+
+### Conditional (SELECT)
+
+| Method | Signature | SQL | Description |
+|--------|-----------|-----|-------------|
+| `coalesce` | `(...args) => ExprUnit<T>` | `COALESCE(...)` | First non-null value |
+| `nullIf` | `(source, value) => ExprUnit<T\|undefined>` | `NULLIF(source, value)` | Return NULL if source equals value |
+| `is` | `(condition: WhereExprUnit) => ExprUnit<boolean>` | Condition as boolean | Convert WHERE expression to boolean column |
+| `switch` | `<T>() => SwitchExprBuilder<T>` | `CASE WHEN ... END` | Fluent CASE WHEN builder |
+| `if` | `(condition, then, else_) => ExprUnit<T>` | `IF(...)` / `IIF(...)` | Ternary conditional |
+
+### Aggregate (SELECT)
+
+| Method | Signature | SQL | Description |
+|--------|-----------|-----|-------------|
+| `count` | `(arg?, distinct?) => ExprUnit<number>` | `COUNT(...)` | Row count (all rows if arg omitted) |
+| `sum` | `(arg) => ExprUnit<number\|undefined>` | `SUM(arg)` | Sum (NULL if all values NULL) |
+| `avg` | `(arg) => ExprUnit<number\|undefined>` | `AVG(arg)` | Average (NULL if all values NULL) |
+| `max` | `(arg) => ExprUnit<T\|undefined>` | `MAX(arg)` | Maximum value |
+| `min` | `(arg) => ExprUnit<T\|undefined>` | `MIN(arg)` | Minimum value |
+
+### Other (SELECT)
+
+| Method | Signature | SQL | Description |
+|--------|-----------|-----|-------------|
+| `greatest` | `(...args) => ExprUnit<T>` | `GREATEST(...)` | Greatest of multiple values |
+| `least` | `(...args) => ExprUnit<T>` | `LEAST(...)` | Least of multiple values |
+| `rowNum` | `() => ExprUnit<number>` | `ROW_NUMBER` variant | Simple row numbering |
+| `random` | `() => ExprUnit<number>` | `RAND()` / `RANDOM()` | Random number (0 to 1) |
+| `cast` | `(source, targetType: DataType) => ExprUnit` | `CAST(source AS type)` | Type conversion |
+| `subquery` | `(dataType, queryable) => ExprUnit` | `(SELECT ...)` | Scalar subquery in SELECT |
+
+### Window Functions (SELECT)
+
+| Method | Signature | SQL | Description |
+|--------|-----------|-----|-------------|
+| `rowNumber` | `(spec: WinSpecInput) => ExprUnit<number>` | `ROW_NUMBER() OVER (...)` | Row number within partition |
+| `rank` | `(spec: WinSpecInput) => ExprUnit<number>` | `RANK() OVER (...)` | Rank (gaps after ties: 1,1,3) |
+| `denseRank` | `(spec: WinSpecInput) => ExprUnit<number>` | `DENSE_RANK() OVER (...)` | Dense rank (no gaps: 1,1,2) |
+| `ntile` | `(n: number, spec: WinSpecInput) => ExprUnit<number>` | `NTILE(n) OVER (...)` | Split into n groups |
+| `lag` | `(column, spec, options?) => ExprUnit<T\|undefined>` | `LAG(...) OVER (...)` | Previous row value |
+| `lead` | `(column, spec, options?) => ExprUnit<T\|undefined>` | `LEAD(...) OVER (...)` | Next row value |
+| `firstValue` | `(column, spec) => ExprUnit<T\|undefined>` | `FIRST_VALUE(...) OVER (...)` | First value in partition |
+| `lastValue` | `(column, spec) => ExprUnit<T\|undefined>` | `LAST_VALUE(...) OVER (...)` | Last value in partition |
+| `sumOver` | `(column, spec) => ExprUnit<number\|undefined>` | `SUM(...) OVER (...)` | Window sum |
+| `avgOver` | `(column, spec) => ExprUnit<number\|undefined>` | `AVG(...) OVER (...)` | Window average |
+| `countOver` | `(spec, column?) => ExprUnit<number>` | `COUNT(...) OVER (...)` | Window count |
+| `minOver` | `(column, spec) => ExprUnit<T\|undefined>` | `MIN(...) OVER (...)` | Window minimum |
+| `maxOver` | `(column, spec) => ExprUnit<T\|undefined>` | `MAX(...) OVER (...)` | Window maximum |
+
+**WinSpecInput** (window specification input):
 
 ```typescript
-class ExprUnit<TPrimitive extends ColumnPrimitive> {
-  readonly $infer!: TPrimitive;
-  readonly dataType: ColumnPrimitiveStr;
-  readonly expr: Expr;
-
-  /** Non-nullable assertion accessor */
-  get n(): ExprUnit<NonNullable<TPrimitive>>;
-
-  constructor(dataType: ColumnPrimitiveStr, expr: Expr);
+interface WinSpecInput {
+  partitionBy?: ExprInput<ColumnPrimitive>[];
+  orderBy?: [ExprInput<ColumnPrimitive>, ("ASC" | "DESC")?][];
 }
 ```
 
-## WhereExprUnit
+**lag/lead options**:
 
-WHERE clause expression wrapper.
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `offset` | `number` | `1` | Number of rows to look back/forward |
+| `default` | `ExprInput<T>` | `undefined` (NULL) | Default value when no row exists |
 
-```typescript
-class WhereExprUnit {
-  readonly expr: WhereExpr;
-  constructor(expr: WhereExpr);
-}
-```
-
-## ExprInput
-
-Union type accepting either an `ExprUnit` or a literal value.
+### Helper
 
-```typescript
-type ExprInput<TPrimitive extends ColumnPrimitive> = ExprUnit<TPrimitive> | TPrimitive;
-```
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `toExpr` | `(value: ExprInput<ColumnPrimitive>) => Expr` | Convert ExprInput to Expr JSON AST (internal use) |

package/docs/query-builder.md

@@ -4,123 +4,147 @@ Transforms `QueryDef` AST into dialect-specific SQL strings.
 
 ## createQueryBuilder
 
-Factory function that creates the appropriate `QueryBuilderBase` for a given dialect.
-
 ```typescript
-function createQueryBuilder(dialect: Dialect): QueryBuilderBase;
+function createQueryBuilder(dialect: Dialect): QueryBuilderBase
 ```
 
-**Parameters:**
+Factory function that creates a dialect-specific QueryBuilder instance.
 
 | Parameter | Type | Description |
-|---|---|---|
-| `dialect` | `"mysql" \| "mssql" \| "postgresql"` | Target database dialect |
+|-----------|------|-------------|
+| `dialect` | `"mysql" \| "mssql" \| "postgresql"` | Target DBMS dialect |
 
-**Returns:** `QueryBuilderBase` instance (`MysqlQueryBuilder`, `MssqlQueryBuilder`, or `PostgresqlQueryBuilder`)
+Returns `MysqlQueryBuilder`, `MssqlQueryBuilder`, or `PostgresqlQueryBuilder`.
 
-**Example:**
+## QueryBuilderBase
 
 ```typescript
-const builder = createQueryBuilder("mysql");
-const result = builder.build(selectQueryDef);
-console.log(result.sql);
+abstract class QueryBuilderBase {
+  build(def: QueryDef): QueryBuildResult;
+}
 ```
 
-## QueryBuilderBase
+Abstract base class for rendering `QueryDef` AST to SQL. Implements common dispatch logic; dialect-specific differences are handled by abstract methods in subclasses.
 
-Abstract base class for QueryDef-to-SQL rendering. Implements dispatch logic shared across all dialects. Dialect-specific differences are delegated to abstract methods.
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `build` | `(def: QueryDef) => QueryBuildResult` | Convert any QueryDef to SQL |
 
-```typescript
-abstract class QueryBuilderBase {
-  abstract readonly exprRenderer: ExprRendererBase;
+`QueryBuildResult` contains:
 
-  build(def: QueryDef): QueryBuildResult;
-}
+| Field | Type | Description |
+|-------|------|-------------|
+| `sql` | `string` | Generated SQL string |
+| `resultSetIndex` | `number?` | Result set index for multi-statement queries |
+| `resultSetStride` | `number?` | Stride for extracting results from multi-statement queries |
+
+## Dialect-Specific Query Builders
+
+### MysqlQueryBuilder
+
+```typescript
+class MysqlQueryBuilder extends QueryBuilderBase
 ```
 
-### build
+MySQL 8.0.14+ query builder. Handles MySQL-specific syntax such as backtick quoting, `<=>` for NULL-safe equality, `LIMIT ... OFFSET`, `LOAD DATA LOCAL INFILE`, etc.
 
-The main entry point. Accepts any `QueryDef` (SELECT, INSERT, UPDATE, DELETE, UPSERT, DDL, etc.) and returns a `QueryBuildResult` containing the SQL string and optional result set metadata.
+### MssqlQueryBuilder
 
 ```typescript
-build(def: QueryDef): QueryBuildResult;
+class MssqlQueryBuilder extends QueryBuilderBase
 ```
 
-**Returns:** `QueryBuildResult` with:
+MSSQL 2012+ query builder. Handles bracket quoting, `TOP`, `OFFSET ... FETCH NEXT`, `MERGE` for upsert, `SET IDENTITY_INSERT`, etc.
 
-| Field | Type | Description |
-|---|---|---|
-| `sql` | `string` | Generated SQL |
-| `resultSetIndex?` | `number` | Which result set to read (default: 0) |
-| `resultSetStride?` | `number` | For multi-result sets, read every Nth |
+### PostgresqlQueryBuilder
 
-## ExprRendererBase
+```typescript
+class PostgresqlQueryBuilder extends QueryBuilderBase
+```
 
-Abstract base class for rendering `Expr` and `WhereExpr` AST nodes to SQL strings. Each dialect implements its own renderer for DBMS-specific syntax.
+PostgreSQL 9.0+ query builder. Handles double-quote quoting, `LIMIT ... OFFSET`, `ON CONFLICT` for upsert, `COPY FROM STDIN`, etc.
+
+## ExprRendererBase
 
 ```typescript
 abstract class ExprRendererBase {
-  render(expr: Expr): string;
-  renderWhere(expr: WhereExpr): string;
+  renderExpr(expr: Expr): string;
+  renderWhereExpr(expr: WhereExpr): string;
 }
 ```
 
-## MysqlQueryBuilder
+Abstract base class for rendering `Expr` and `WhereExpr` AST nodes to SQL fragments. Each QueryBuilder uses a corresponding ExprRenderer.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `renderExpr` | `(expr: Expr) => string` | Render a value/function expression to SQL |
+| `renderWhereExpr` | `(expr: WhereExpr) => string` | Render a WHERE condition expression to SQL |
+
+## Dialect-Specific Expression Renderers
 
-MySQL-specific query builder. Extends `QueryBuilderBase`.
+### MysqlExprRenderer
 
 ```typescript
-class MysqlQueryBuilder extends QueryBuilderBase {
-  readonly exprRenderer: MysqlExprRenderer;
-}
+class MysqlExprRenderer extends ExprRendererBase
 ```
 
-MySQL-specific behaviors:
-- Uses `<=>` for NULL-safe equality
-- Uses backtick quoting for identifiers
-- INSERT OUTPUT via separate SELECT with `LAST_INSERT_ID()`
-- UPSERT via `INSERT ... ON DUPLICATE KEY UPDATE`
-
-## MssqlQueryBuilder
+MySQL expression renderer. Uses `<=>` for NULL-safe equality, `IFNULL`, `LOCATE`, MySQL `DATE_FORMAT` patterns, etc.
 
-MSSQL-specific query builder. Extends `QueryBuilderBase`.
+### MssqlExprRenderer
 
 ```typescript
-class MssqlQueryBuilder extends QueryBuilderBase {
-  readonly exprRenderer: MssqlExprRenderer;
-}
+class MssqlExprRenderer extends ExprRendererBase
 ```
 
-MSSQL-specific behaviors:
-- Uses `[` `]` for identifier quoting
-- TOP instead of LIMIT
-- OUTPUT clause for INSERT/UPDATE/DELETE
-- `IDENTITY_INSERT` for auto-increment override
-- `OFFSET...FETCH` for pagination
+MSSQL expression renderer. Uses `IIF`, `CHARINDEX`, `FORMAT` for date formatting, `DATALENGTH` for byte length, etc.
+
+### PostgresqlExprRenderer
 
-## PostgresqlQueryBuilder
+```typescript
+class PostgresqlExprRenderer extends ExprRendererBase
+```
+
+PostgreSQL expression renderer. Uses `IS NOT DISTINCT FROM` for NULL-safe equality, `POSITION`, `TO_CHAR` for date formatting, `OCTET_LENGTH`, etc.
 
-PostgreSQL-specific query builder. Extends `QueryBuilderBase`.
+## parseQueryResult
 
 ```typescript
-class PostgresqlQueryBuilder extends QueryBuilderBase {
-  readonly exprRenderer: PostgresqlExprRenderer;
-}
+async function parseQueryResult<TRecord>(
+  rawResults: Record<string, unknown>[],
+  meta: ResultMeta,
+): Promise<TRecord[] | undefined>
 ```
 
-PostgreSQL-specific behaviors:
-- Uses `"` for identifier quoting
-- `RETURNING` clause for INSERT/UPDATE/DELETE output
-- `LIMIT...OFFSET` for pagination
-- `LATERAL` subquery JOINs
-- `IS NOT DISTINCT FROM` for NULL-safe equality
+Parses raw database query results into typed TypeScript objects. Handles:
 
-## Dialect-Specific Expression Renderers
+- **Type conversion**: Converts raw values (strings, numbers) to proper TypeScript types (`DateTime`, `DateOnly`, `Uuid`, etc.) based on `ResultMeta.columns`
+- **JOIN nesting**: Flattens `"posts.id"` keys into nested `{ posts: { id: ... } }` objects
+- **Grouping**: Groups rows by non-JOIN columns, collecting JOIN data into arrays (1:N) or single objects (1:1)
+- **Event loop yielding**: Yields to the event loop every 100 records for large result sets
 
-| Class | Dialect | Description |
-|---|---|---|
-| `MysqlExprRenderer` | MySQL | Renders Expr AST to MySQL SQL syntax |
-| `MssqlExprRenderer` | MSSQL | Renders Expr AST to MSSQL SQL syntax |
-| `PostgresqlExprRenderer` | PostgreSQL | Renders Expr AST to PostgreSQL SQL syntax |
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `rawResults` | `Record<string, unknown>[]` | Raw DB result rows |
+| `meta` | `ResultMeta` | Column types and JOIN structure info |
+
+Returns `undefined` if the input is empty or all records parse to empty objects.
 
-Each renderer extends `ExprRendererBase` and overrides methods for dialect-specific expression rendering (e.g., date functions, string functions, type casting).
+```typescript
+// Simple type parsing
+const raw = [{ id: "1", createdAt: "2026-01-07T10:00:00.000Z" }];
+const meta = { columns: { id: "number", createdAt: "DateTime" }, joins: {} };
+const result = await parseQueryResult(raw, meta);
+// [{ id: 1, createdAt: DateTime(...) }]
+
+// JOIN nesting
+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" }] }]
+```