@simplysm/orm-common 13.0.100 → 14.0.4

package/docs/expression.md

@@ -1,45 +1,166 @@
-# Expression
+# Expression DSL
 
-## `ExprUnit`
+Dialect-independent SQL expression builder. Generates JSON AST (`Expr`) instead of SQL strings. The QueryBuilder transforms the AST to target DBMS syntax.
 
-Type-safe expression wrapper. Tracks expression return type using TypeScript generics.
+## expr
 
-```typescript
-class ExprUnit<TPrimitive extends ColumnPrimitive> {
-  readonly $infer!: TPrimitive;
-  get n(): ExprUnit<NonNullable<TPrimitive>>;
-  constructor(readonly dataType: ColumnPrimitiveStr, readonly expr: Expr);
-}
-```
+Constant object with all expression builder methods. Used inside Queryable callbacks for `where()`, `select()`, `orderBy()`, etc.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `$infer` | `TPrimitive` | Type inference marker (not used at runtime) |
-| `n` | `ExprUnit<NonNullable<TPrimitive>>` | Non-nullable version of this expression |
-| `dataType` | `ColumnPrimitiveStr` | Column data type name |
-| `expr` | `Expr` | Internal expression AST |
+### Value Generation
 
-## `WhereExprUnit`
+| 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. |
 
-Expression wrapper for WHERE clause conditions.
+**Example:**
 
 ```typescript
-class WhereExprUnit {
-  constructor(readonly expr: WhereExpr);
-}
+expr.val("string", "active")
+expr.val("number", 100)
+expr.val("DateOnly", DateOnly.today())
+expr.raw("string")`JSON_EXTRACT(${u.metadata}, '$.email')`
 ```
 
-## `ExprInput`
+### 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 |
+
+### String Search
+
+| Method | Signature | Description |
+|---|---|---|
+| `like` | `(source, pattern) => WhereExprUnit` | LIKE pattern matching (`%`, `_` wildcards) |
+| `regexp` | `(source, pattern) => WhereExprUnit` | Regular expression matching |
+
+### IN / EXISTS
+
+| 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 |
+
+### Logical Operators
+
+| Method | Signature | Description |
+|---|---|---|
+| `not` | `(arg: WhereExprUnit) => WhereExprUnit` | NOT |
+| `and` | `(conditions: WhereExprUnit[]) => WhereExprUnit` | AND (all must match) |
+| `or` | `(conditions: WhereExprUnit[]) => WhereExprUnit` | OR (any must match) |
+
+### String Functions (SELECT)
+
+| 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)
+
+| Method | Signature | Description |
+|---|---|---|
+| `abs` | `(source) => ExprUnit` | Absolute value |
+| `round` | `(source, digits) => ExprUnit` | Round |
+| `ceil` | `(source) => ExprUnit` | Ceiling |
+| `floor` | `(source) => ExprUnit` | Floor |
+
+### Date/Time Functions (SELECT)
+
+| 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
+
+| 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 |
+
+### Aggregate Functions
 
-Input type that accepts `ExprUnit` or literal values.
+| 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 |
+
+### Utility
+
+| 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 |
 
-```typescript
-type ExprInput<TPrimitive extends ColumnPrimitive> = ExprUnit<TPrimitive> | TPrimitive;
-```
+### Window Functions
 
-## `SwitchExprBuilder`
+All window functions accept a `WinSpecInput: { partitionBy?: ExprInput[]; orderBy?: [ExprInput, ("ASC" | "DESC")?][] }`.
 
-CASE/WHEN expression builder interface.
+| 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 |
+
+## SwitchExprBuilder
+
+Builder interface for CASE WHEN expressions. Created by `expr.switch()`.
 
 ```typescript
 interface SwitchExprBuilder<TPrimitive extends ColumnPrimitive> {
@@ -48,187 +169,49 @@ interface SwitchExprBuilder<TPrimitive extends ColumnPrimitive> {
 }
 ```
 
-## `expr`
+**Example:**
+
+```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"),
+}))
+```
+
+## ExprUnit
 
-Dialect-independent SQL expression builder. Generates JSON AST (`Expr`) instead of SQL strings, which `QueryBuilder` converts to each DBMS (MySQL, MSSQL, PostgreSQL).
+Type-safe expression wrapper that tracks the return type through TypeScript generics.
 
 ```typescript
-const expr: {
-  // Value creation
-  val<TStr extends ColumnPrimitiveStr>(dataType: TStr, value): ExprUnit<...>;
-  col<TStr extends ColumnPrimitiveStr>(dataType: ColumnPrimitiveStr, ...path: string[]): ExprUnit<...>;
-  raw<T extends ColumnPrimitiveStr>(dataType: T): (strings: TemplateStringsArray, ...values: ExprInput<ColumnPrimitive>[]) => ExprUnit<...>;
-
-  // Comparison (WHERE)
-  eq<T extends ColumnPrimitive>(source: ExprUnit<T>, target: ExprInput<T>): WhereExprUnit;
-  gt<T extends ColumnPrimitive>(source: ExprUnit<T>, target: ExprInput<T>): WhereExprUnit;
-  lt<T extends ColumnPrimitive>(source: ExprUnit<T>, target: ExprInput<T>): WhereExprUnit;
-  gte<T extends ColumnPrimitive>(source: ExprUnit<T>, target: ExprInput<T>): WhereExprUnit;
-  lte<T extends ColumnPrimitive>(source: ExprUnit<T>, target: ExprInput<T>): WhereExprUnit;
-  between<T extends ColumnPrimitive>(source: ExprUnit<T>, from?: ExprInput<T>, to?: ExprInput<T>): WhereExprUnit;
-  isNull(arg: ExprUnit<ColumnPrimitive>): WhereExprUnit;
-  like(source: ExprUnit<string | undefined>, pattern: ExprInput<string>): WhereExprUnit;
-  regexp(source: ExprUnit<string | undefined>, pattern: ExprInput<string>): WhereExprUnit;
-  in<T extends ColumnPrimitive>(source: ExprUnit<T>, values: ExprInput<T>[]): WhereExprUnit;
-  inQuery<T extends ColumnPrimitive>(source: ExprUnit<T>, query: Queryable<any, any>): WhereExprUnit;
-  exists(query: Queryable<any, any>): WhereExprUnit;
-
-  // Logical
-  not(condition: WhereExprUnit): WhereExprUnit;
-  and(...conditions: WhereExprUnit[]): WhereExprUnit;
-  or(...conditions: WhereExprUnit[]): WhereExprUnit;
-
-  // String
-  concat(...args: ExprInput<string | undefined>[]): ExprUnit<string>;
-  left(source: ExprInput<string | undefined>, length: ExprInput<number>): ExprUnit<string>;
-  right(source: ExprInput<string | undefined>, length: ExprInput<number>): ExprUnit<string>;
-  trim(arg: ExprInput<string | undefined>): ExprUnit<string>;
-  padStart(source: ExprInput<string | undefined>, length: ExprInput<number>, fillString: ExprInput<string>): ExprUnit<string>;
-  replace(source: ExprInput<string | undefined>, from: ExprInput<string>, to: ExprInput<string>): ExprUnit<string>;
-  upper(arg: ExprInput<string | undefined>): ExprUnit<string>;
-  lower(arg: ExprInput<string | undefined>): ExprUnit<string>;
-  length(arg: ExprInput<string | undefined>): ExprUnit<number>;
-  byteLength(arg: ExprInput<string | undefined>): ExprUnit<number>;
-  substring(source: ExprInput<string | undefined>, start: ExprInput<number>, length?: ExprInput<number>): ExprUnit<string>;
-  indexOf(source: ExprInput<string | undefined>, search: ExprInput<string>): ExprUnit<number>;
-
-  // Numeric
-  abs(arg: ExprInput<number | undefined>): ExprUnit<number>;
-  round(arg: ExprInput<number | undefined>, digits: number): ExprUnit<number>;
-  ceil(arg: ExprInput<number | undefined>): ExprUnit<number>;
-  floor(arg: ExprInput<number | undefined>): ExprUnit<number>;
-
-  // Date
-  year(arg: ExprInput<DateTime | DateOnly | undefined>): ExprUnit<number>;
-  month(arg: ExprInput<DateTime | DateOnly | undefined>): ExprUnit<number>;
-  day(arg: ExprInput<DateTime | DateOnly | undefined>): ExprUnit<number>;
-  hour(arg: ExprInput<DateTime | undefined>): ExprUnit<number>;
-  minute(arg: ExprInput<DateTime | undefined>): ExprUnit<number>;
-  second(arg: ExprInput<DateTime | undefined>): ExprUnit<number>;
-  isoWeek(arg: ExprInput<DateTime | DateOnly | undefined>): ExprUnit<number>;
-  isoWeekStartDate(arg: ExprInput<DateTime | DateOnly | undefined>): ExprUnit<DateOnly>;
-  isoYearMonth(arg: ExprInput<DateTime | DateOnly | undefined>): ExprUnit<string>;
-  dateDiff(unit: DateUnit, from: ExprInput<ColumnPrimitive>, to: ExprInput<ColumnPrimitive>): ExprUnit<number>;
-  dateAdd(unit: DateUnit, source: ExprInput<ColumnPrimitive>, value: ExprInput<number>): ExprUnit<DateTime>;
-  formatDate(source: ExprInput<ColumnPrimitive>, format: string): ExprUnit<string>;
-
-  // Conditional
-  coalesce<T extends ColumnPrimitive>(...args: ExprInput<T | undefined>[]): ExprUnit<T>;
-  nullIf<T extends ColumnPrimitive>(source: ExprInput<T>, value: ExprInput<T>): ExprUnit<T | undefined>;
-  is(condition: WhereExprUnit): ExprUnit<number>;
-  switch<T extends ColumnPrimitive>(dataType: ColumnPrimitiveStr): SwitchExprBuilder<T>;
-  if<T extends ColumnPrimitive>(condition: WhereExprUnit, then: ExprInput<T>, elseVal?: ExprInput<T>): ExprUnit<T>;
-
-  // Aggregate
-  count(arg?: ExprUnit<ColumnPrimitive>, distinct?: boolean): ExprUnit<number>;
-  sum(arg: ExprUnit<number | undefined>): ExprUnit<number>;
-  avg(arg: ExprUnit<number | undefined>): ExprUnit<number>;
-  max<T extends ColumnPrimitive>(arg: ExprUnit<T>): ExprUnit<T>;
-  min<T extends ColumnPrimitive>(arg: ExprUnit<T>): ExprUnit<T>;
-
-  // Other
-  greatest<T extends ColumnPrimitive>(...args: ExprInput<T>[]): ExprUnit<T>;
-  least<T extends ColumnPrimitive>(...args: ExprInput<T>[]): ExprUnit<T>;
-  rowNum(): ExprUnit<number>;
-  random(): ExprUnit<number>;
-  cast<TDataType extends DataType>(source: ExprInput<ColumnPrimitive>, targetType: TDataType): ExprUnit<InferColumnPrimitiveFromDataType<TDataType>>;
-
-  // Window
-  window(fn: WinFn, spec?: WinSpecInput): ExprUnit<number>;
-
-  // Subquery
-  subquery<T extends ColumnPrimitive>(query: Queryable<any, any>, selectFn: (q: ...) => ExprUnit<T>): ExprUnit<T>;
-};
+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);
+}
 ```
 
-### Value Creation
-
-| Method | Description |
-|--------|-------------|
-| `val()` | Wrap literal value as ExprUnit |
-| `col()` | Generate column reference |
-| `raw()` | Raw SQL expression (escape hatch, tagged template literal) |
-
-### Comparison (WHERE)
-
-| Method | SQL | Description |
-|--------|-----|-------------|
-| `eq()` | `=` | Equality comparison (NULL-safe) |
-| `gt()` | `>` | Greater than |
-| `lt()` | `<` | Less than |
-| `gte()` | `>=` | Greater than or equal |
-| `lte()` | `<=` | Less than or equal |
-| `between()` | `BETWEEN` | Range comparison |
-| `isNull()` | `IS NULL` | NULL check |
-| `like()` | `LIKE` | Pattern matching |
-| `regexp()` | `REGEXP` | Regular expression matching |
-| `in()` | `IN` | Value list inclusion |
-| `inQuery()` | `IN (SELECT)` | Subquery inclusion |
-| `exists()` | `EXISTS` | Subquery existence |
-
-### Logical
-
-| Method | SQL | Description |
-|--------|-----|-------------|
-| `not()` | `NOT` | Logical negation |
-| `and()` | `AND` | Logical conjunction |
-| `or()` | `OR` | Logical disjunction |
-
-### String Functions
-
-| Method | SQL | Description |
-|--------|-----|-------------|
-| `concat()` | `CONCAT` | String concatenation |
-| `left()` | `LEFT` | Extract left N characters |
-| `right()` | `RIGHT` | Extract right N characters |
-| `trim()` | `TRIM` | Remove leading/trailing whitespace |
-| `padStart()` | `LPAD` | Left padding |
-| `replace()` | `REPLACE` | String replacement |
-| `upper()` | `UPPER` | Uppercase |
-| `lower()` | `LOWER` | Lowercase |
-| `length()` | `CHAR_LENGTH` | Character length |
-| `byteLength()` | `LENGTH/DATALENGTH` | Byte length |
-| `substring()` | `SUBSTRING` | Substring extraction |
-| `indexOf()` | `LOCATE/CHARINDEX` | Find string position |
-
-### Numeric Functions
-
-| Method | SQL | Description |
-|--------|-----|-------------|
-| `abs()` | `ABS` | Absolute value |
-| `round()` | `ROUND` | Rounding |
-| `ceil()` | `CEIL` | Ceiling |
-| `floor()` | `FLOOR` | Floor |
-
-### Date Functions
-
-| Method | SQL | Description |
-|--------|-----|-------------|
-| `year()` | `YEAR` | Extract year |
-| `month()` | `MONTH` | Extract month |
-| `day()` | `DAY` | Extract day |
-| `hour()` | `HOUR` | Extract hour |
-| `minute()` | `MINUTE` | Extract minute |
-| `second()` | `SECOND` | Extract second |
-| `isoWeek()` | `WEEK` | ISO week number |
-| `isoWeekStartDate()` | - | ISO week start date |
-| `isoYearMonth()` | - | ISO year-month (YYYYMM) |
-| `dateDiff()` | `DATEDIFF` | Date difference |
-| `dateAdd()` | `DATEADD` | Date arithmetic |
-| `formatDate()` | `FORMAT/DATE_FORMAT` | Date formatting |
+## WhereExprUnit
 
-### Aggregate Functions
+WHERE clause expression wrapper.
 
-| Method | SQL | Description |
-|--------|-----|-------------|
-| `count()` | `COUNT` | Record count |
-| `sum()` | `SUM` | Sum |
-| `avg()` | `AVG` | Average |
-| `max()` | `MAX` | Maximum |
-| `min()` | `MIN` | Minimum |
+```typescript
+class WhereExprUnit {
+  readonly expr: WhereExpr;
+  constructor(expr: WhereExpr);
+}
+```
 
-### Window Functions
+## ExprInput
 
-| Method | SQL | Description |
-|--------|-----|-------------|
-| `window()` | `OVER(...)` | Window function (rowNumber, rank, denseRank, ntile, lag, lead, firstValue, lastValue, sum, avg, count, min, max) |
+Union type accepting either an `ExprUnit` or a literal value.
+
+```typescript
+type ExprInput<TPrimitive extends ColumnPrimitive> = ExprUnit<TPrimitive> | TPrimitive;
+```

package/docs/query-builder.md

@@ -1,36 +1,62 @@
 # Query Builder
 
-## `createQueryBuilder`
+Transforms `QueryDef` AST into dialect-specific SQL strings.
 
-Generate a `QueryBuilderBase` instance matching the given dialect.
+## createQueryBuilder
+
+Factory function that creates the appropriate `QueryBuilderBase` for a given dialect.
 
 ```typescript
 function createQueryBuilder(dialect: Dialect): QueryBuilderBase;
 ```
 
+**Parameters:**
+
 | Parameter | Type | Description |
-|-----------|------|-------------|
-| `dialect` | `Dialect` | Database dialect (`"mysql"`, `"mssql"`, `"postgresql"`) |
+|---|---|---|
+| `dialect` | `"mysql" \| "mssql" \| "postgresql"` | Target database dialect |
+
+**Returns:** `QueryBuilderBase` instance (`MysqlQueryBuilder`, `MssqlQueryBuilder`, or `PostgresqlQueryBuilder`)
+
+**Example:**
+
+```typescript
+const builder = createQueryBuilder("mysql");
+const result = builder.build(selectQueryDef);
+console.log(result.sql);
+```
 
-## `QueryBuilderBase`
+## QueryBuilderBase
 
-Abstract base class that renders `QueryDef` JSON AST to dialect-specific SQL strings. Implements dispatch logic identical across all dialects; dialect-specific rendering is handled by subclasses.
+Abstract base class for QueryDef-to-SQL rendering. Implements dispatch logic shared across all dialects. Dialect-specific differences are delegated to abstract methods.
 
 ```typescript
 abstract class QueryBuilderBase {
-  protected abstract expr: ExprRendererBase;
+  abstract readonly exprRenderer: ExprRendererBase;
 
   build(def: QueryDef): QueryBuildResult;
 }
 ```
 
-| Method | Description |
-|--------|-------------|
-| `build()` | Render a `QueryDef` to SQL. Dispatches to the appropriate method by `def.type`. |
+### build
 
-## `ExprRendererBase`
+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.
 
-Abstract base class for rendering `Expr` and `WhereExpr` JSON AST nodes to dialect-specific SQL strings. Each dialect (MySQL, MSSQL, PostgreSQL) extends this class with its own implementations.
+```typescript
+build(def: QueryDef): QueryBuildResult;
+```
+
+**Returns:** `QueryBuildResult` with:
+
+| 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 |
+
+## ExprRendererBase
+
+Abstract base class for rendering `Expr` and `WhereExpr` AST nodes to SQL strings. Each dialect implements its own renderer for DBMS-specific syntax.
 
 ```typescript
 abstract class ExprRendererBase {
@@ -39,55 +65,62 @@ abstract class ExprRendererBase {
 }
 ```
 
-| Method | Description |
-|--------|-------------|
-| `render()` | Render a value expression to SQL |
-| `renderWhere()` | Render a WHERE expression to SQL |
-
-## `MysqlQueryBuilder`
+## MysqlQueryBuilder
 
 MySQL-specific query builder. Extends `QueryBuilderBase`.
 
 ```typescript
-class MysqlQueryBuilder extends QueryBuilderBase { ... }
+class MysqlQueryBuilder extends QueryBuilderBase {
+  readonly exprRenderer: MysqlExprRenderer;
+}
 ```
 
-## `MysqlExprRenderer`
-
-MySQL-specific expression renderer. 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`
 
-```typescript
-class MysqlExprRenderer extends ExprRendererBase { ... }
-```
-
-## `MssqlQueryBuilder`
+## MssqlQueryBuilder
 
 MSSQL-specific query builder. Extends `QueryBuilderBase`.
 
 ```typescript
-class MssqlQueryBuilder extends QueryBuilderBase { ... }
+class MssqlQueryBuilder extends QueryBuilderBase {
+  readonly exprRenderer: MssqlExprRenderer;
+}
 ```
 
-## `MssqlExprRenderer`
-
-MSSQL-specific expression renderer. 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
 
-```typescript
-class MssqlExprRenderer extends ExprRendererBase { ... }
-```
-
-## `PostgresqlQueryBuilder`
+## PostgresqlQueryBuilder
 
 PostgreSQL-specific query builder. Extends `QueryBuilderBase`.
 
 ```typescript
-class PostgresqlQueryBuilder extends QueryBuilderBase { ... }
+class PostgresqlQueryBuilder extends QueryBuilderBase {
+  readonly exprRenderer: PostgresqlExprRenderer;
+}
 ```
 
-## `PostgresqlExprRenderer`
+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
 
-PostgreSQL-specific expression renderer. Extends `ExprRendererBase`.
+## Dialect-Specific Expression Renderers
 
-```typescript
-class PostgresqlExprRenderer extends ExprRendererBase { ... }
-```
+| 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 |
+
+Each renderer extends `ExprRendererBase` and overrides methods for dialect-specific expression rendering (e.g., date functions, string functions, type casting).