@simplysm/orm-common 14.0.22 → 14.0.24

package/docs/query-builder.md

@@ -1,150 +0,0 @@
-# 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" }] }]
-```

package/docs/queryable.md

@@ -1,261 +0,0 @@
-# Queryable / Executable
-
-Type-safe query builder and stored procedure executor.
-
-## Queryable
-
-```typescript
-class Queryable<TData extends DataRecord, TFrom extends TableBuilder<any, any> | never> {
-  constructor(readonly meta: QueryableMeta<TData>);
-}
-```
-
-Fluent query builder for composing SELECT, INSERT, UPDATE, DELETE, and UPSERT queries. All methods return new Queryable instances (immutable chaining).
-
-- `TData` - Query result data type
-- `TFrom` - Source table (required for CUD operations, `never` for read-only)
-
-### Option Methods (SELECT / DISTINCT / LOCK)
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `select` | `<R>(fn: (cols: QueryableRecord<TData>) => R) => Queryable<UnwrapQueryableRecord<R>, never>` | Specify columns to SELECT |
-| `distinct` | `() => Queryable<TData, never>` | Apply DISTINCT |
-| `lock` | `() => Queryable<TData, TFrom>` | Apply FOR UPDATE row lock |
-
-### Restrict Methods (TOP / LIMIT)
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `top` | `(count: number) => Queryable<TData, TFrom>` | Select top N rows |
-| `limit` | `(skip: number, take: number) => Queryable<TData, TFrom>` | Pagination (requires orderBy) |
-
-### Sorting (ORDER BY)
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `orderBy` | `(fn: (cols) => ExprUnit, orderBy?: "ASC" \| "DESC") => Queryable<TData, TFrom>` | Add sort condition (stackable) |
-
-### Filtering (WHERE)
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `where` | `(predicate: (cols) => WhereExprUnit[]) => Queryable<TData, TFrom>` | Add WHERE conditions (stackable, AND) |
-| `search` | `(fn: (cols) => ExprUnit<string\|undefined>[], searchText: string) => Queryable<TData, TFrom>` | Full-text search across columns |
-
-### Grouping (GROUP BY / HAVING)
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `groupBy` | `(fn: (cols) => ExprUnit[]) => Queryable<TData, never>` | Group by columns |
-| `having` | `(predicate: (cols) => WhereExprUnit[]) => Queryable<TData, never>` | Filter groups |
-
-### JOIN
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `join` | `<A, R>(as: A, fn: (qr: JoinQueryable, cols) => Queryable<R, any>) => Queryable<TData & { [K in A]?: R[] }, TFrom>` | LEFT OUTER JOIN (1:N, result as array) |
-| `joinSingle` | `<A, R>(as: A, fn: (qr: JoinQueryable, cols) => Queryable<R, any>) => Queryable<TData & { [K in A]?: R }, TFrom>` | LEFT OUTER JOIN (N:1 or 1:1, result as single object) |
-| `include` | `(fn: (item: PathProxy<TData>) => PathProxy) => Queryable<TData, TFrom>` | Auto-JOIN based on TableBuilder FK/FKT relations |
-
-### Subquery / Union
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `wrap` | `() => Queryable<TData, never>` | Wrap as subquery (needed for count after distinct/groupBy) |
-| `Queryable.union` (static) | `(...queries: Queryable<TData, any>[]) => Queryable<TData, never>` | Combine queries with UNION (min 2) |
-
-### Recursive CTE
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `recursive` | `(fn: (cte: RecursiveQueryable<TData>) => Queryable<TData, any>) => Queryable<TData, never>` | Generate recursive CTE (WITH RECURSIVE) |
-
-### Execution (SELECT)
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `execute` | `() => Promise<TData[]>` | Execute SELECT and return results |
-| `single` | `() => Promise<TData \| undefined>` | Return single result (throws if > 1) |
-| `first` | `() => Promise<TData \| undefined>` | Return first result |
-| `count` | `(fn?: (cols) => ExprUnit) => Promise<number>` | Count rows (throws after distinct/groupBy without wrap) |
-| `exists` | `() => Promise<boolean>` | Check if any matching data exists |
-
-### QueryDef Getters (SELECT)
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `getSelectQueryDef` | `() => SelectQueryDef` | Get the SELECT QueryDef AST |
-| `getResultMeta` | `(outputColumns?: string[]) => ResultMeta` | Get result parsing metadata |
-
-### INSERT
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `insert` | `(records: TFrom["$inferInsert"][]) => Promise<void>` | Insert records (auto-chunks per 1000) |
-| `insert` | `(records, outputColumns: K[]) => Promise<Pick<...>[]>` | Insert with output columns |
-| `insertIfNotExists` | `(record: TFrom["$inferInsert"]) => Promise<void>` | Insert if WHERE condition has no match |
-| `insertIfNotExists` | `(record, outputColumns: K[]) => Promise<Pick<...>>` | Insert if not exists with output |
-| `insertInto` | `(targetTable: TableBuilder) => Promise<void>` | INSERT INTO ... SELECT |
-| `insertInto` | `(targetTable, outputColumns: K[]) => Promise<Pick<...>[]>` | INSERT INTO ... SELECT with output |
-
-### UPDATE / DELETE
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `update` | `(recordFwd: (cols) => QueryableWriteRecord) => Promise<void>` | Update matching rows |
-| `update` | `(recordFwd, outputColumns: K[]) => Promise<Pick<...>[]>` | Update with output |
-| `delete` | `() => Promise<void>` | Delete matching rows |
-| `delete` | `(outputColumns: K[]) => Promise<Pick<...>[]>` | Delete with output |
-
-### UPSERT
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `upsert` | `(updateFn: (cols) => WriteRecord) => Promise<void>` | Update or insert (same data) |
-| `upsert` | `(updateFn, insertFn) => Promise<void>` | Update or insert (different data) |
-| `upsert` | `(updateFn, insertFn?, outputColumns?) => Promise<Pick<...>[] \| void>` | With output columns |
-
-### DDL Helper
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `switchFk` | `(enabled: boolean) => Promise<void>` | Enable/disable FK constraints on this table |
-
-## queryable (factory)
-
-```typescript
-function queryable<TBuilder extends TableBuilder<any, any> | ViewBuilder<any, any, any>>(
-  db: DbContextBase,
-  tableOrView: TBuilder,
-  as?: string,
-): () => Queryable<TBuilder["$inferSelect"], TBuilder extends TableBuilder ? TBuilder : never>
-```
-
-Creates a factory function that returns a new Queryable instance each time it is called. Each call allocates a fresh alias via `db.getNextAlias()`.
-
-## Executable
-
-```typescript
-class Executable<TParams extends ColumnBuilderRecord, TReturns extends ColumnBuilderRecord> {
-  constructor(db: DbContextBase, builder: ProcedureBuilder<TParams, TReturns>);
-  getExecProcQueryDef(params?: InferColumnExprs<TParams>): { type: "execProc"; ... };
-  async execute(params: InferColumnExprs<TParams>): Promise<InferColumnExprs<TReturns>[][]>;
-}
-```
-
-Stored procedure execution wrapper.
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `getExecProcQueryDef` | `(params?) => ExecProcQueryDef` | Build procedure execution QueryDef |
-| `execute` | `(params) => Promise<T[][]>` | Execute the procedure |
-
-## executable (factory)
-
-```typescript
-function executable<TParams, TReturns>(
-  db: DbContextBase,
-  builder: ProcedureBuilder<TParams, TReturns>,
-): () => Executable<TParams, TReturns>
-```
-
-Creates a factory function that returns a new Executable instance.
-
-## parseSearchQuery
-
-```typescript
-function parseSearchQuery(searchText: string): ParsedSearchQuery
-```
-
-Parses a search query string into SQL LIKE patterns.
-
-| Syntax | Meaning | Example |
-|--------|---------|---------|
-| `term1 term2` | OR (match any) | `apple banana` |
-| `+term` | Required (AND) | `+apple +banana` |
-| `-term` | Exclude (NOT) | `apple -banana` |
-| `"exact phrase"` | Exact match (required) | `"delicious fruit"` |
-| `*` | Wildcard | `app*` becomes `app%` |
-
-Escape sequences: `\\` (literal `\`), `\*`, `\%`, `\"`, `\+`, `\-`.
-
-## ParsedSearchQuery
-
-```typescript
-interface ParsedSearchQuery {
-  or: string[];    // OR conditions - LIKE patterns
-  must: string[];  // AND conditions (+ prefix or quotes) - LIKE patterns
-  not: string[];   // NOT conditions (- prefix) - LIKE patterns
-}
-```
-
-## getMatchedPrimaryKeys
-
-```typescript
-function getMatchedPrimaryKeys(
-  fkCols: string[],
-  targetTable: TableBuilder<any, any>,
-): string[]
-```
-
-Match FK column array with the target table's PK. Returns PK column name array. Throws if column counts do not match.
-
-## QueryableRecord
-
-```typescript
-type QueryableRecord<TData extends DataRecord> = {
-  [K in keyof TData]: TData[K] extends ColumnPrimitive
-    ? ExprUnit<TData[K]>
-    : TData[K] extends (infer U)[]
-      ? U extends DataRecord ? QueryableRecord<U>[] : never
-      : TData[K] extends DataRecord ? QueryableRecord<TData[K]> : ...
-}
-```
-
-Maps each field of a DataRecord to its corresponding ExprUnit proxy. Used as the column accessor type in Queryable callbacks.
-
-## QueryableWriteRecord
-
-```typescript
-type QueryableWriteRecord<TData> = {
-  [K in keyof TData]: TData[K] extends ColumnPrimitive ? ExprInput<TData[K]> : never;
-}
-```
-
-Maps each field to ExprInput for write operations (UPDATE, UPSERT).
-
-## NullableQueryableRecord
-
-```typescript
-type NullableQueryableRecord<TData extends DataRecord> = { ... }
-```
-
-Like QueryableRecord but all primitive fields become `ExprUnit<T | undefined>`. Used for LEFT JOIN results where all columns may be NULL.
-
-## UnwrapQueryableRecord
-
-```typescript
-type UnwrapQueryableRecord<R> = {
-  [K in keyof R]: R[K] extends ExprUnit<infer T> ? T : ...
-}
-```
-
-Reverse-maps QueryableRecord back to a plain DataRecord. Used internally by `select()` to infer the resulting data type.
-
-## PathProxy
-
-```typescript
-type PathProxy<TObject> = {
-  [K in keyof TObject as TObject[K] extends ColumnPrimitive ? never : K]-?: PathProxy<UnwrapArray<TObject[K]>>;
-} & { readonly [PATH_SYMBOL]: string[] }
-```
-
-Type-safe proxy for `include()` that only exposes non-primitive (relation) fields. Property access builds a path array internally.
-
-```typescript
-// Only relation fields are accessible:
-db.post().include((p) => p.author)         // OK - author is a relation
-db.post().include((p) => p.author.company) // OK - nested relation
-// db.post().include((p) => p.title)       // Compile error - title is string
-```

package/docs/schema-builders.md

@@ -1,288 +0,0 @@
-# Schema Builders
-
-Fluent API builders for defining tables, views, procedures, columns, indexes, and relations.
-
-## Table (function)
-
-```typescript
-function Table(name: string): TableBuilder<{}, {}>
-```
-
-Creates a new TableBuilder with the given table name.
-
-## TableBuilder
-
-```typescript
-class TableBuilder<TColumns extends ColumnBuilderRecord, TRelations extends RelationBuilderRecord>
-```
-
-Fluent API for defining database table schema including columns, primary key, indexes, and relations.
-
-### Phantom Type Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `$columns` | `TColumns` | Column definitions (type inference) |
-| `$relations` | `TRelations` | Relation definitions (type inference) |
-| `$inferSelect` | `InferColumns<TColumns> & InferDeepRelations<TRelations>` | Full SELECT type |
-| `$inferColumns` | `InferColumns<TColumns>` | Column-only type |
-| `$inferInsert` | `InferInsertColumns<TColumns>` | INSERT type (AI/nullable/default optional) |
-| `$inferUpdate` | `InferUpdateColumns<TColumns>` | UPDATE type (all optional) |
-
-### Constructor
-
-```typescript
-constructor(readonly meta: {
-  name: string;
-  description?: string;
-  database?: string;
-  schema?: string;
-  columns?: TColumns;
-  primaryKey?: (keyof TColumns & string)[];
-  relations?: TRelations;
-  indexes?: IndexBuilder<(keyof TColumns & string)[]>[];
-})
-```
-
-### Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `description` | `(desc: string) => TableBuilder` | Set table description (DDL comment) |
-| `database` | `(db: string) => TableBuilder` | Set database name |
-| `schema` | `(schema: string) => TableBuilder` | Set schema name (MSSQL/PostgreSQL) |
-| `columns` | `<T>(fn: (c: ColumnFactory) => T) => TableBuilder<T, TRelations>` | Define columns via column factory |
-| `primaryKey` | `(...columns: (keyof TColumns & string)[]) => TableBuilder` | Set primary key (single or composite) |
-| `indexes` | `(fn: (i: IndexFactory) => IndexBuilder[]) => TableBuilder` | Define indexes |
-| `relations` | `<T>(fn: (r: RelationFactory) => T) => TableBuilder<TColumns, T>` | Define FK and relation mappings |
-
-## View (function)
-
-```typescript
-function View(name: string): ViewBuilder<any, any, {}>
-```
-
-Creates a new ViewBuilder with the given view name.
-
-## ViewBuilder
-
-```typescript
-class ViewBuilder<TDbContext extends DbContextBase, TData extends DataRecord, TRelations extends RelationBuilderRecord>
-```
-
-Fluent API for defining database view schema.
-
-### Phantom Type Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `$relations` | `TRelations` | Relation definitions |
-| `$inferSelect` | `TData` | Full SELECT type |
-
-### Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `description` | `(desc: string) => ViewBuilder` | Set view description |
-| `database` | `(db: string) => ViewBuilder` | Set database name |
-| `schema` | `(schema: string) => ViewBuilder` | Set schema name |
-| `query` | `<TViewData, TDb>(viewFn: (db: TDb) => Queryable<TViewData, any>) => ViewBuilder<TDb, TViewData, TRelations>` | Define the view's SELECT query |
-| `relations` | `<T>(fn: (r: RelationFactory) => T) => ViewBuilder` | Define relations (RelationKey only, no FK) |
-
-## Procedure (function)
-
-```typescript
-function Procedure(name: string): ProcedureBuilder<never, never>
-```
-
-Creates a new ProcedureBuilder with the given procedure name.
-
-## ProcedureBuilder
-
-```typescript
-class ProcedureBuilder<TParams extends ColumnBuilderRecord, TReturns extends ColumnBuilderRecord>
-```
-
-Fluent API for defining stored procedure schema.
-
-### Phantom Type Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `$params` | `TParams` | Parameter definitions |
-| `$returns` | `TReturns` | Return type definitions |
-
-### Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `description` | `(desc: string) => ProcedureBuilder` | Set procedure description |
-| `database` | `(db: string) => ProcedureBuilder` | Set database name |
-| `schema` | `(schema: string) => ProcedureBuilder` | Set schema name |
-| `params` | `<T>(fn: (c: ColumnFactory) => T) => ProcedureBuilder<T, TReturns>` | Define input parameters |
-| `returns` | `<T>(fn: (c: ColumnFactory) => T) => ProcedureBuilder<TParams, T>` | Define return columns |
-| `body` | `(sql: string) => ProcedureBuilder` | Set procedure body SQL |
-
-## ColumnBuilder
-
-```typescript
-class ColumnBuilder<TValue extends ColumnPrimitive, TMeta extends ColumnMeta> {
-  constructor(readonly meta: TMeta);
-}
-```
-
-Column definition builder with fluent API for type modifiers.
-
-### Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `autoIncrement` | `() => ColumnBuilder<TValue, TMeta & { autoIncrement: true }>` | Set auto-increment (INSERT optional) |
-| `nullable` | `() => ColumnBuilder<TValue \| undefined, TMeta & { nullable: true }>` | Allow NULL values |
-| `default` | `(value: TValue) => ColumnBuilder<TValue, TMeta & { default: TValue }>` | Set default value (INSERT optional) |
-| `description` | `(desc: string) => ColumnBuilder<TValue, TMeta & { description: string }>` | Set column description (DDL comment) |
-
-## createColumnFactory
-
-```typescript
-function createColumnFactory(): ColumnFactory
-```
-
-Returns a column type factory object. Used inside `TableBuilder.columns()` and `ProcedureBuilder.params()/returns()`.
-
-### Factory Methods
-
-| Method | Signature | SQL Type | TypeScript Type |
-|--------|-----------|----------|-----------------|
-| `int` | `() => ColumnBuilder<number, ...>` | `INT` | `number` |
-| `bigint` | `() => ColumnBuilder<number, ...>` | `BIGINT` | `number` |
-| `float` | `() => ColumnBuilder<number, ...>` | `FLOAT` | `number` |
-| `double` | `() => ColumnBuilder<number, ...>` | `DOUBLE` | `number` |
-| `decimal` | `(precision, scale?) => ColumnBuilder<number, ...>` | `DECIMAL(p,s)` | `number` |
-| `varchar` | `(length) => ColumnBuilder<string, ...>` | `VARCHAR(n)` | `string` |
-| `char` | `(length) => ColumnBuilder<string, ...>` | `CHAR(n)` | `string` |
-| `text` | `() => ColumnBuilder<string, ...>` | `TEXT` | `string` |
-| `binary` | `() => ColumnBuilder<Bytes, ...>` | `LONGBLOB`/`BYTEA` | `Bytes` |
-| `boolean` | `() => ColumnBuilder<boolean, ...>` | `TINYINT(1)`/`BIT`/`BOOLEAN` | `boolean` |
-| `datetime` | `() => ColumnBuilder<DateTime, ...>` | `DATETIME` | `DateTime` |
-| `date` | `() => ColumnBuilder<DateOnly, ...>` | `DATE` | `DateOnly` |
-| `time` | `() => ColumnBuilder<Time, ...>` | `TIME` | `Time` |
-| `uuid` | `() => ColumnBuilder<Uuid, ...>` | `BINARY(16)`/`UNIQUEIDENTIFIER`/`UUID` | `Uuid` |
-
-## IndexBuilder
-
-```typescript
-class IndexBuilder<TKeys extends string[]> {
-  constructor(readonly meta: {
-    columns: TKeys;
-    name?: string;
-    unique?: boolean;
-    orderBy?: { [K in keyof TKeys]: "ASC" | "DESC" };
-    description?: string;
-  });
-}
-```
-
-### Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `name` | `(name: string) => IndexBuilder<TKeys>` | Set custom index name |
-| `unique` | `() => IndexBuilder<TKeys>` | Mark as unique index |
-| `orderBy` | `(...orderBy: ("ASC" \| "DESC")[]) => IndexBuilder<TKeys>` | Set sort order per column |
-| `description` | `(desc: string) => IndexBuilder<TKeys>` | Set index description |
-
-## createIndexFactory
-
-```typescript
-function createIndexFactory<TColumnKey extends string>(): { index: (...columns: TColumnKey[]) => IndexBuilder }
-```
-
-Returns an index factory. Used inside `TableBuilder.indexes()`.
-
-## ForeignKeyBuilder
-
-```typescript
-class ForeignKeyBuilder<TOwner extends TableBuilder<any, any>, TTargetFn extends () => TableBuilder<any, any>> {
-  constructor(readonly meta: {
-    ownerFn: () => TOwner;
-    columns: string[];
-    targetFn: TTargetFn;
-    description?: string;
-  });
-}
-```
-
-N:1 FK relation builder. Creates an actual DB foreign key constraint.
-
-`description` is configured via the factory function's `opts` parameter (3rd argument to `foreignKey()`), not via method chaining. This class has no methods — it is a data holder for relation metadata.
-
-## ForeignKeyTargetBuilder
-
-```typescript
-class ForeignKeyTargetBuilder<TTargetTableFn extends () => TableBuilder<any, any>, TIsSingle extends boolean> {
-  constructor(readonly meta: {
-    targetTableFn: TTargetTableFn;
-    relationName: string;
-    description?: string;
-    isSingle?: TIsSingle;
-  });
-}
-```
-
-1:N FK reverse-reference builder. Loaded as array by default, single object with `{ single: true }` opts.
-
-`description` and `single` are configured via the factory function's `opts` parameter (3rd argument to `foreignKeyTarget()`), not via method chaining. Method chaining was removed to prevent TS7022 in complex circular references.
-
-This class has no methods — it is a data holder for relation metadata.
-
-## RelationKeyBuilder
-
-```typescript
-class RelationKeyBuilder<
-  TOwner extends TableBuilder<any, any> | ViewBuilder<any, any, any>,
-  TTargetFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>,
->
-```
-
-Logical N:1 relation builder (no DB FK constraint). Works with both Tables and Views.
-
-`description` is configured via the factory function's `opts` parameter (3rd argument to `relationKey()`), not via method chaining. This class has no methods — it is a data holder for relation metadata.
-
-## RelationKeyTargetBuilder
-
-```typescript
-class RelationKeyTargetBuilder<
-  TTargetTableFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>,
-  TIsSingle extends boolean,
->
-```
-
-Logical 1:N reverse-reference builder (no DB FK constraint). Works with both Tables and Views.
-
-`description` and `single` are configured via the factory function's `opts` parameter (3rd argument to `relationKeyTarget()`), not via method chaining.
-
-This class has no methods — it is a data holder for relation metadata.
-
-## createRelationFactory
-
-```typescript
-function createRelationFactory<TOwner, TColumnKey extends string>(
-  ownerFn: () => TOwner,
-): RelationFactory
-```
-
-Creates a relation factory. For `TableBuilder`: provides `foreignKey`, `foreignKeyTarget`, `relationKey`, `relationKeyTarget`. For `ViewBuilder`: provides only `relationKey`, `relationKeyTarget`.
-
-### Factory Methods (Table)
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `foreignKey` | `(columns, targetFn, opts?: { description?: string })` | N:1 FK (creates DB constraint) |
-| `foreignKeyTarget` | `(targetTableFn, relationName, opts?: { single?: boolean; description?: string })` | 1:N FK reverse-reference. `{ single: true }` → 1:1 |
-| `relationKey` | `(columns, targetFn, opts?: { description?: string })` | N:1 logical relation (no DB FK) |
-| `relationKeyTarget` | `(targetTableFn, relationName, opts?: { single?: boolean; description?: string })` | 1:N logical reverse-reference. `{ single: true }` → 1:1 |
-
-### Factory Methods (View)
-
-Only `relationKey` and `relationKeyTarget` are available for ViewBuilder.