@simplysm/orm-common 14.0.1 → 14.0.5

package/docs/core.md

@@ -0,0 +1,157 @@
+# Core
+
+DbContext definition, creation, and lifecycle management.
+
+## defineDbContext
+
+```typescript
+function defineDbContext<
+  TTables extends Record<string, TableBuilder<any, any>> = {},
+  TViews extends Record<string, ViewBuilder<any, any, any>> = {},
+  TProcedures extends Record<string, ProcedureBuilder<any, any>> = {},
+>(config: {
+  tables?: TTables;
+  views?: TViews;
+  procedures?: TProcedures;
+  migrations?: Migration[];
+}): DbContextDef<TTables & { _migration: typeof _Migration }, TViews, TProcedures>
+```
+
+Creates a DbContext definition (blueprint) containing schema metadata. Automatically adds the `_migration` system table. The definition itself has no runtime state.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `config.tables` | `Record<string, TableBuilder>` | Table definitions |
+| `config.views` | `Record<string, ViewBuilder>` | View definitions |
+| `config.procedures` | `Record<string, ProcedureBuilder>` | Procedure definitions |
+| `config.migrations` | `Migration[]` | Migration definitions |
+
+```typescript
+const MyDb = defineDbContext({
+  tables: { user: User, post: Post },
+  views: { activeUsers: ActiveUsersView },
+  procedures: { getUserById: GetUserById },
+  migrations: [
+    { name: "20260101_001_init", up: async (db) => { await db.createTable(User); } },
+  ],
+});
+```
+
+## createDbContext
+
+```typescript
+function createDbContext<TDef extends DbContextDef<any, any, any>>(
+  def: TDef,
+  executor: DbContextExecutor,
+  opt: { database: string; schema?: string },
+): DbContextInstance<TDef>
+```
+
+Creates a full DbContext instance from a definition and executor. The returned object provides:
+
+- **Queryable accessors** for each table/view (e.g., `db.user()` returns a `Queryable`)
+- **Executable accessors** for each procedure (e.g., `db.getUserById()` returns an `Executable`)
+- **Connection management**: `connect()`, `connectWithoutTransaction()`, `transaction()`
+- **DDL methods**: `createTable()`, `dropTable()`, `addColumn()`, etc. (see `DbContextDdlMethods`)
+- **DDL QueryDef generators**: `getCreateTableQueryDef()`, etc.
+- **Initialize**: `initialize()` runs migrations
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `def` | `DbContextDef` | Definition from `defineDbContext()` |
+| `executor` | `DbContextExecutor` | Query execution engine (e.g., `NodeDbContextExecutor`) |
+| `opt.database` | `string` | Database name |
+| `opt.schema` | `string?` | Schema name (MSSQL: dbo, PostgreSQL: public) |
+
+### Connection Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `connect` | `<R>(fn: () => Promise<R>, isolationLevel?: IsolationLevel) => Promise<R>` | Connect, begin transaction, execute callback, commit (auto-rollback on error) |
+| `connectWithoutTransaction` | `<R>(fn: () => Promise<R>) => Promise<R>` | Connect without transaction, execute callback, close |
+| `transaction` | `<R>(fn: () => Promise<R>, isolationLevel?: IsolationLevel) => Promise<R>` | Begin transaction within existing connection (for use inside `connectWithoutTransaction`) |
+
+### DDL Execution Methods
+
+| Method | Signature |
+|--------|-----------|
+| `createTable` | `(table: TableBuilder) => Promise<void>` |
+| `dropTable` | `(table: QueryDefObjectName) => Promise<void>` |
+| `renameTable` | `(table: QueryDefObjectName, newName: string) => Promise<void>` |
+| `createView` | `(view: ViewBuilder) => Promise<void>` |
+| `dropView` | `(view: QueryDefObjectName) => Promise<void>` |
+| `createProc` | `(procedure: ProcedureBuilder) => Promise<void>` |
+| `dropProc` | `(procedure: QueryDefObjectName) => Promise<void>` |
+| `addColumn` | `(table: QueryDefObjectName, columnName: string, column: ColumnBuilder) => Promise<void>` |
+| `dropColumn` | `(table: QueryDefObjectName, column: string) => Promise<void>` |
+| `modifyColumn` | `(table: QueryDefObjectName, columnName: string, column: ColumnBuilder) => Promise<void>` |
+| `renameColumn` | `(table: QueryDefObjectName, column: string, newName: string) => Promise<void>` |
+| `addPrimaryKey` | `(table: QueryDefObjectName, columns: string[]) => Promise<void>` |
+| `dropPrimaryKey` | `(table: QueryDefObjectName) => Promise<void>` |
+| `addForeignKey` | `(table: QueryDefObjectName, relationName: string, relationDef: ForeignKeyBuilder) => Promise<void>` |
+| `addIndex` | `(table: QueryDefObjectName, indexBuilder: IndexBuilder) => Promise<void>` |
+| `dropForeignKey` | `(table: QueryDefObjectName, relationName: string) => Promise<void>` |
+| `dropIndex` | `(table: QueryDefObjectName, columns: string[]) => Promise<void>` |
+| `clearSchema` | `(params: { database: string; schema?: string }) => Promise<void>` |
+| `schemaExists` | `(database: string, schema?: string) => Promise<boolean>` |
+| `truncate` | `(table: QueryDefObjectName) => Promise<void>` |
+| `switchFk` | `(table: QueryDefObjectName, enabled: boolean) => Promise<void>` |
+
+### DDL QueryDef Generators
+
+Each DDL method has a corresponding `get*QueryDef` method that returns a `QueryDef` without executing it. For example: `getCreateTableQueryDef(table)`, `getDropTableQueryDef(table)`, etc.
+
+### Initialize
+
+```typescript
+async initialize(options?: { dbs?: string[]; force?: boolean }): Promise<void>
+```
+
+Runs pending migrations. If `force` is true, drops and recreates the schema.
+
+## DbTransactionError
+
+```typescript
+class DbTransactionError extends Error {
+  readonly name = "DbTransactionError";
+  constructor(
+    public readonly code: DbErrorCode,
+    message: string,
+    public readonly originalError?: unknown,
+  )
+}
+```
+
+Wraps DBMS-native transaction errors into standardized error codes.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `code` | `DbErrorCode` | Standardized error code |
+| `message` | `string` | Error message |
+| `originalError` | `unknown?` | Original DBMS error (for debugging) |
+
+## DbErrorCode
+
+```typescript
+enum DbErrorCode {
+  NO_ACTIVE_TRANSACTION = "NO_ACTIVE_TRANSACTION",
+  TRANSACTION_ALREADY_STARTED = "TRANSACTION_ALREADY_STARTED",
+  DEADLOCK = "DEADLOCK",
+  LOCK_TIMEOUT = "LOCK_TIMEOUT",
+}
+```
+
+| Value | Description |
+|-------|-------------|
+| `NO_ACTIVE_TRANSACTION` | No active transaction (e.g., rollback when no transaction) |
+| `TRANSACTION_ALREADY_STARTED` | Transaction already started |
+| `DEADLOCK` | Deadlock detected |
+| `LOCK_TIMEOUT` | Lock timeout exceeded |
+
+## _Migration
+
+```typescript
+const _Migration: TableBuilder<{ code: ColumnBuilder<string, ...> }, {}>
+```
+
+System migration tracking table. Automatically added to every DbContext via `defineDbContext()`. Has a single `code` column (VARCHAR(255)) as primary key, storing executed migration names.

package/docs/expression.md

@@ -0,0 +1,220 @@
+# Expression DSL
+
+Dialect-independent SQL expression builder. Generates JSON AST (`Expr`) instead of SQL strings. The QueryBuilder transforms the AST to target DBMS syntax.
+
+## ExprUnit
+
+```typescript
+class ExprUnit<TPrimitive extends ColumnPrimitive> {
+  readonly $infer!: TPrimitive;
+  readonly dataType: ColumnPrimitiveStr;
+  readonly expr: Expr;
+  get n(): ExprUnit<NonNullable<TPrimitive>>;
+  constructor(dataType: ColumnPrimitiveStr, expr: Expr);
+}
+```
+
+Type-safe expression wrapper. Tracks the return type via the `TPrimitive` generic parameter.
+
+| 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 |
+
+## WhereExprUnit
+
+```typescript
+class WhereExprUnit {
+  readonly expr: WhereExpr;
+  constructor(expr: WhereExpr);
+}
+```
+
+WHERE clause expression wrapper. Returned by comparison and logical methods on `expr`.
+
+## ExprInput
+
+```typescript
+type ExprInput<TPrimitive extends ColumnPrimitive> = ExprUnit<TPrimitive> | TPrimitive;
+```
+
+Accepts either an `ExprUnit` or a literal value. Literal values are automatically wrapped.
+
+## SwitchExprBuilder
+
+```typescript
+interface SwitchExprBuilder<TPrimitive extends ColumnPrimitive> {
+  case(condition: WhereExprUnit, then: ExprInput<TPrimitive>): SwitchExprBuilder<TPrimitive>;
+  default(value: ExprInput<TPrimitive>): ExprUnit<TPrimitive>;
+}
+```
+
+Fluent CASE WHEN builder. Chain `.case()` calls and terminate with `.default()`.
+
+## expr Object
+
+The `expr` object provides all expression-building methods. Methods are grouped by category below.
+
+### Value Creation
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `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 |
+
+### Comparison (WHERE)
+
+| 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) |
+
+### NULL Check (WHERE)
+
+| Method | Signature | SQL | Description |
+|--------|-----------|-----|-------------|
+| `null` | `(source: ExprUnit<T>) => WhereExprUnit` | `IS NULL` | NULL check |
+
+### String Search (WHERE)
+
+| 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 |
+
+### IN / EXISTS (WHERE)
+
+| 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 |
+
+### Logical (WHERE)
+
+| 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 |
+
+### String Functions (SELECT)
+
+| 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
+interface WinSpecInput {
+  partitionBy?: ExprInput<ColumnPrimitive>[];
+  orderBy?: [ExprInput<ColumnPrimitive>, ("ASC" | "DESC")?][];
+}
+```
+
+**lag/lead options**:
+
+| 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 |
+
+### Helper
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `toExpr` | `(value: ExprInput<ColumnPrimitive>) => Expr` | Convert ExprInput to Expr JSON AST (internal use) |

package/docs/query-builder.md

@@ -0,0 +1,150 @@
+# Query Builder
+
+Transforms `QueryDef` AST into dialect-specific SQL strings.
+
+## createQueryBuilder
+
+```typescript
+function createQueryBuilder(dialect: Dialect): QueryBuilderBase
+```
+
+Factory function that creates a dialect-specific QueryBuilder instance.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `dialect` | `"mysql" \| "mssql" \| "postgresql"` | Target DBMS dialect |
+
+Returns `MysqlQueryBuilder`, `MssqlQueryBuilder`, or `PostgresqlQueryBuilder`.
+
+## QueryBuilderBase
+
+```typescript
+abstract class QueryBuilderBase {
+  build(def: QueryDef): QueryBuildResult;
+}
+```
+
+Abstract base class for rendering `QueryDef` AST to SQL. Implements common dispatch logic; dialect-specific differences are handled by abstract methods in subclasses.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `build` | `(def: QueryDef) => QueryBuildResult` | Convert any QueryDef to SQL |
+
+`QueryBuildResult` contains:
+
+| 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
+```
+
+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.
+
+### MssqlQueryBuilder
+
+```typescript
+class MssqlQueryBuilder extends QueryBuilderBase
+```
+
+MSSQL 2012+ query builder. Handles bracket quoting, `TOP`, `OFFSET ... FETCH NEXT`, `MERGE` for upsert, `SET IDENTITY_INSERT`, etc.
+
+### PostgresqlQueryBuilder
+
+```typescript
+class PostgresqlQueryBuilder extends QueryBuilderBase
+```
+
+PostgreSQL 9.0+ query builder. Handles double-quote quoting, `LIMIT ... OFFSET`, `ON CONFLICT` for upsert, `COPY FROM STDIN`, etc.
+
+## ExprRendererBase
+
+```typescript
+abstract class ExprRendererBase {
+  renderExpr(expr: Expr): string;
+  renderWhereExpr(expr: WhereExpr): string;
+}
+```
+
+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
+
+### MysqlExprRenderer
+
+```typescript
+class MysqlExprRenderer extends ExprRendererBase
+```
+
+MySQL expression renderer. Uses `<=>` for NULL-safe equality, `IFNULL`, `LOCATE`, MySQL `DATE_FORMAT` patterns, etc.
+
+### MssqlExprRenderer
+
+```typescript
+class MssqlExprRenderer extends ExprRendererBase
+```
+
+MSSQL expression renderer. Uses `IIF`, `CHARINDEX`, `FORMAT` for date formatting, `DATALENGTH` for byte length, etc.
+
+### PostgresqlExprRenderer
+
+```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.
+
+## parseQueryResult
+
+```typescript
+async function parseQueryResult<TRecord>(
+  rawResults: Record<string, unknown>[],
+  meta: ResultMeta,
+): Promise<TRecord[] | undefined>
+```
+
+Parses raw database query results into typed TypeScript objects. Handles:
+
+- **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
+
+| 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.
+
+```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" }] }]
+```