@simplysm/orm-common 14.0.23 → 14.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/orm-common",
-  "version": "14.0.23",
+  "version": "14.0.24",
   "description": "심플리즘 패키지 - ORM (common)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -14,14 +14,13 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src",
-    "docs"
+    "src"
   ],
   "sideEffects": false,
   "devDependencies": {
     "@types/node": "^20.19.39"
   },
   "dependencies": {
-    "@simplysm/core-common": "14.0.23"
+    "@simplysm/core-common": "14.0.24"
   }
 }

package/README.md

@@ -1,170 +0,0 @@
-# @simplysm/orm-common
-
-Platform-neutral ORM module for the Simplysm framework. Provides type-safe query building, schema definition, expression building, and DDL generation for MySQL, MSSQL, and PostgreSQL.
-
-## Installation
-
-```bash
-npm install @simplysm/orm-common
-# or
-pnpm add @simplysm/orm-common
-```
-
-## API Overview
-
-### Core
-
-| Export | Type | Description |
-|--------|------|-------------|
-| [`DbContext`](./docs/core.md#dbcontext) | Abstract Class | Base class for database contexts with connection, transaction, DDL, and initialization |
-| [`SD_BUILDER`](./docs/core.md#sd_builder) | Symbol | Internal marker for queryable/executable builder identification |
-| [`DbTransactionError`](./docs/core.md#dbtransactionerror) | Class | Standardized database transaction error with DBMS-independent error codes |
-| [`DbErrorCode`](./docs/core.md#dberrorcode) | Enum | Transaction error codes |
-| [`DbContextBase`](./docs/core.md#dbcontextbase) | Interface | Core interface for Queryable/Executable internal use |
-| [`DbContextDdlMethods`](./docs/core.md#dbcontextddlmethods) | Interface | DDL execution and QueryDef generator methods |
-| [`DbContextStatus`](./docs/core.md#dbcontextstatus) | Type | Connection status: "ready", "connect", "transact" |
-| [`_Migration`](./docs/core.md#_migration) | Constant | System migration table definition (TableBuilder) |
-
-### Queryable / Executable
-
-| Export | Type | Description |
-|--------|------|-------------|
-| [`Queryable`](./docs/queryable.md#queryable) | Class | Fluent query builder for SELECT, INSERT, UPDATE, DELETE, UPSERT |
-| [`queryable`](./docs/queryable.md#queryable-factory) | Function | Factory to create Queryable accessors for tables/views |
-| [`Executable`](./docs/queryable.md#executable) | Class | Stored procedure execution wrapper |
-| [`executable`](./docs/queryable.md#executable-factory) | Function | Factory to create Executable accessors for procedures |
-| [`parseSearchQuery`](./docs/queryable.md#parsesearchquery) | Function | Parse search query string into SQL LIKE patterns |
-| [`ParsedSearchQuery`](./docs/queryable.md#parsedsearchquery) | Interface | Parsed search query result |
-| [`getMatchedPrimaryKeys`](./docs/queryable.md#getmatchedprimarykeys) | Function | Match FK columns with target table PK columns |
-| [`QueryableRecord`](./docs/queryable.md#queryablerecord) | Type | Maps DataRecord fields to ExprUnit proxies |
-| [`QueryableWriteRecord`](./docs/queryable.md#queryablewriterecord) | Type | Maps DataRecord fields to ExprInput for writes |
-| [`NullableQueryableRecord`](./docs/queryable.md#nullablequeryablerecord) | Type | QueryableRecord with nullable primitives (for LEFT JOIN) |
-| [`UnwrapQueryableRecord`](./docs/queryable.md#unwrapqueryablerecord) | Type | Reverse-map QueryableRecord to DataRecord |
-| [`PathProxy`](./docs/queryable.md#pathproxy) | Type | Type-safe path proxy for `include()` |
-
-### Expression Builder
-
-| Export | Type | Description |
-|--------|------|-------------|
-| [`expr`](./docs/expression.md#expr-object) | Object | Dialect-independent SQL expression builder (100+ methods) |
-| [`ExprUnit`](./docs/expression.md#exprunit) | Class | Type-safe expression wrapper |
-| [`WhereExprUnit`](./docs/expression.md#whereexprunit) | Class | WHERE clause expression wrapper |
-| [`ExprInput`](./docs/expression.md#exprinput) | Type | Union of ExprUnit or literal values |
-| [`SwitchExprBuilder`](./docs/expression.md#switchexprbuilder) | Interface | CASE WHEN builder (fluent API) |
-| [`toExpr`](./docs/expression.md#toexpr) | Function | Convert ExprInput to Expr JSON AST |
-
-### Schema Builders
-
-| Export | Type | Description |
-|--------|------|-------------|
-| [`Table`](./docs/schema-builders.md#table-function) | Function | Create a TableBuilder |
-| [`TableBuilder`](./docs/schema-builders.md#tablebuilder) | Class | Fluent API for table definitions |
-| [`View`](./docs/schema-builders.md#view-function) | Function | Create a ViewBuilder |
-| [`ViewBuilder`](./docs/schema-builders.md#viewbuilder) | Class | Fluent API for view definitions |
-| [`Procedure`](./docs/schema-builders.md#procedure-function) | Function | Create a ProcedureBuilder |
-| [`ProcedureBuilder`](./docs/schema-builders.md#procedurebuilder) | Class | Fluent API for stored procedure definitions |
-| [`ColumnBuilder`](./docs/schema-builders.md#columnbuilder) | Class | Column definition builder |
-| [`createColumnFactory`](./docs/schema-builders.md#createcolumnfactory) | Function | Column type factory |
-| [`IndexBuilder`](./docs/schema-builders.md#indexbuilder) | Class | Index definition builder |
-| [`createIndexFactory`](./docs/schema-builders.md#createindexfactory) | Function | Index factory |
-| [`ForeignKeyBuilder`](./docs/schema-builders.md#foreignkeybuilder) | Class | FK relation builder (N:1, configured via factory opts) |
-| [`ForeignKeyTargetBuilder`](./docs/schema-builders.md#foreignkeytargetbuilder) | Class | FK reverse-reference builder (1:N/1:1, configured via factory opts) |
-| [`RelationKeyBuilder`](./docs/schema-builders.md#relationkeybuilder) | Class | Logical relation builder (no DB FK, configured via factory opts) |
-| [`RelationKeyTargetBuilder`](./docs/schema-builders.md#relationkeytargetbuilder) | Class | Logical reverse-reference builder (configured via factory opts) |
-| [`createRelationFactory`](./docs/schema-builders.md#createrelationfactory) | Function | Relation factory |
-
-### Query Builder & Result Parsing
-
-| Export | Type | Description |
-|--------|------|-------------|
-| [`createQueryBuilder`](./docs/query-builder.md#createquerybuilder) | Function | Create a dialect-specific QueryBuilder |
-| [`QueryBuilderBase`](./docs/query-builder.md#querybuilderbase) | Abstract Class | Base for QueryDef to SQL rendering |
-| [`MysqlQueryBuilder`](./docs/query-builder.md#dialect-specific-query-builders) | Class | MySQL query builder |
-| [`MssqlQueryBuilder`](./docs/query-builder.md#dialect-specific-query-builders) | Class | MSSQL query builder |
-| [`PostgresqlQueryBuilder`](./docs/query-builder.md#dialect-specific-query-builders) | Class | PostgreSQL query builder |
-| [`ExprRendererBase`](./docs/query-builder.md#exprrendererbase) | Abstract Class | Base for Expr to SQL rendering |
-| [`MysqlExprRenderer`](./docs/query-builder.md#dialect-specific-expression-renderers) | Class | MySQL expression renderer |
-| [`MssqlExprRenderer`](./docs/query-builder.md#dialect-specific-expression-renderers) | Class | MSSQL expression renderer |
-| [`PostgresqlExprRenderer`](./docs/query-builder.md#dialect-specific-expression-renderers) | Class | PostgreSQL expression renderer |
-| [`parseQueryResult`](./docs/query-builder.md#parsequeryresult) | Function | Parse raw DB results into typed objects |
-
-### Types
-
-See [Types documentation](./docs/types.md) for all type exports including:
-- Database: `Dialect`, `dialects`, `IsolationLevel`, `DataRecord`, `DbContextExecutor`, `ResultMeta`, `Migration`, `QueryBuildResult`
-- Column: `DataType`, `ColumnPrimitive`, `ColumnPrimitiveStr`, `ColumnPrimitiveMap`, `ColumnMeta`, `dataTypeStrToColumnPrimitiveStr`, `inferColumnPrimitiveStr`, `InferColumnPrimitiveFromDataType`
-- Column Builder: `ColumnBuilderRecord`, `InferColumns`, `InferColumnExprs`, `InferInsertColumns`, `InferUpdateColumns`, `RequiredInsertKeys`, `OptionalInsertKeys`, `DataToColumnBuilderRecord`
-- Relation: `RelationBuilderRecord`, `InferDeepRelations`, `ExtractRelationTarget`, `ExtractRelationTargetResult`
-- Expression: `Expr` (50+ variants), `WhereExpr`, `DateUnit`, `WinFn`, `WinSpec`, all `Expr*` interfaces
-- QueryDef: `QueryDef` (30+ variants), `QueryDefObjectName`, `DDL_TYPES`, `DdlType`, all `*QueryDef` interfaces
-
-## Usage Examples
-
-### Define Schema and DbContext
-
-```typescript
-import { Table, DbContext, expr } from "@simplysm/orm-common";
-
-const User = Table("User")
-  .columns((c) => ({
-    id: c.bigint().autoIncrement(),
-    name: c.varchar(100),
-    email: c.varchar(200).nullable(),
-    companyId: c.bigint(),
-  }))
-  .primaryKey("id")
-  .indexes((i) => [i.index("email").unique()])
-  .relations((r) => ({
-    company: r.foreignKey(["companyId"], () => Company, { description: "Company" }),
-    posts: r.foreignKeyTarget(() => Post, "author"),
-    topPost: r.foreignKeyTarget(() => Post, "author", { single: true, description: "Top post" }),
-  }));
-
-class MyDb extends DbContext {
-  user = this.queryable(User);
-  post = this.queryable(Post);
-  company = this.queryable(Company);
-}
-
-const db = new MyDb(executor, { database: "mydb" });
-```
-
-### Query Data
-
-```typescript
-await db.connect(async () => {
-  const users = await db.user()
-    .where((u) => [expr.eq(u.name, "Alice")])
-    .orderBy((u) => u.name)
-    .execute();
-
-  const posts = await db.post().include((p) => p.author).execute();
-
-  await db.user().insert([{ name: "New User", companyId: 1 }]);
-
-  await db.user()
-    .where((u) => [expr.eq(u.id, 1)])
-    .update(() => ({ name: expr.val("string", "Updated") }));
-});
-```
-
-### Expression Builder
-
-```typescript
-// Window functions
-db.order().select((o) => ({
-  ...o,
-  rowNum: expr.rowNumber({ partitionBy: [o.userId], orderBy: [[o.createdAt, "DESC"]] }),
-}));
-
-// CASE WHEN
-db.user().select((u) => ({
-  grade: expr.switch<string>()
-    .case(expr.gte(u.score, 90), "A")
-    .default("C"),
-}));
-
-// Search parser
-const parsed = parseSearchQuery('+apple -banana "exact phrase"');
-// { must: ["%apple%", "%exact phrase%"], not: ["%banana%"], or: [] }
-```

package/docs/core.md

@@ -1,217 +0,0 @@
-# Core
-
-DbContext abstract class, connection/transaction lifecycle, DDL execution, and initialization.
-
-## DbContext
-
-```typescript
-abstract class DbContext implements DbContextBase {
-  status: DbContextStatus;
-
-  constructor(
-    executor: DbContextExecutor,
-    opt: { database: string; schema?: string },
-  )
-
-  // Registration
-  protected queryable<T extends TableBuilder | ViewBuilder>(builder: T): () => Queryable<...>
-  protected executable<T extends ProcedureBuilder>(builder: T): () => Executable<...>
-
-  // Connection
-  connect<R>(fn: () => Promise<R>, isolationLevel?: IsolationLevel): Promise<R>
-  connectWithoutTransaction<R>(fn: () => Promise<R>): Promise<R>
-  transaction<R>(fn: () => Promise<R>, isolationLevel?: IsolationLevel): Promise<R>
-
-  // DDL execution (see DDL Execution Methods below)
-  // DDL QueryDef generators (get*QueryDef methods)
-
-  // Initialization
-  initialize(options?: { dbs?: string[]; force?: boolean }): Promise<void>
-
-  // Override in subclass
-  migrations: Migration[];
-}
-```
-
-Base class for database contexts. Subclass to define tables, views, and procedures as class properties.
-
-Each property registered via `queryable()` or `executable()` is independently serialized, avoiding TS7056 even with 40+ tables.
-
-| Constructor Parameter | Type | Description |
-|---|---|---|
-| `executor` | `DbContextExecutor` | Query execution engine (e.g., `NodeDbContextExecutor`) |
-| `opt.database` | `string` | Database name |
-| `opt.schema` | `string?` | Schema name (MSSQL: dbo, PostgreSQL: public) |
-
-```typescript
-class MainDb extends DbContext {
-  user = this.queryable(User);
-  post = this.queryable(Post);
-  getUserById = this.executable(GetUserById);
-
-  migrations = [
-    { name: "20260101_001_init", up: async (db) => { await db.createTable(User); } },
-  ];
-}
-
-const db = new MainDb(executor, { database: "mydb", schema: "dbo" });
-```
-
-### 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)`, `getCreateObjectQueryDef(builder)`, etc.
-
-### Initialize
-
-```typescript
-async initialize(options?: { dbs?: string[]; force?: boolean }): Promise<void>
-```
-
-Code First database initialization. Creates all registered Table/View/Procedure objects and runs pending migrations.
-
-- **force=true**: Clear schema, recreate all objects, register all migrations as applied
-- **force=false** (default):
-  - No `_Migration` table: Full creation + register all migrations
-  - `_Migration` table exists: Run only pending migrations
-
-## SD_BUILDER
-
-```typescript
-const SD_BUILDER: unique symbol
-```
-
-Internal symbol used to tag queryable/executable factory functions with their underlying builder. Used by `initialize()` to discover registered builders from DbContext instances.
-
-## 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 |
-
-## DbContextBase
-
-```typescript
-interface DbContextBase {
-  status: DbContextStatus;
-  readonly database: string | undefined;
-  readonly schema: string | undefined;
-  getNextAlias(): string;
-  resetAliasCounter(): void;
-  executeDefs<T = DataRecord>(defs: QueryDef[], resultMetas?: (ResultMeta | undefined)[]): Promise<T[][]>;
-  getQueryDefObjectName(tableOrView: TableBuilder | ViewBuilder): QueryDefObjectName;
-  switchFk(table: QueryDefObjectName, enabled: boolean): Promise<void>;
-}
-```
-
-Core interface implemented by DbContext. Used internally by Queryable, Executable, and ViewBuilder.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `status` | `DbContextStatus` | Current connection status |
-| `database` | `string \| undefined` | Database name |
-| `schema` | `string \| undefined` | Schema name |
-| `getNextAlias()` | `string` | Generate next table alias (T1, T2, ...) |
-| `resetAliasCounter()` | `void` | Reset alias counter |
-| `executeDefs()` | `Promise<T[][]>` | Execute QueryDef array, returns result per def |
-| `getQueryDefObjectName()` | `QueryDefObjectName` | Resolve table/view to qualified name |
-| `switchFk()` | `Promise<void>` | Enable/disable FK constraints |
-
-## DbContextDdlMethods
-
-```typescript
-interface DbContextDdlMethods {
-  createTable(table: TableBuilder): Promise<void>;
-  dropTable(table: QueryDefObjectName): Promise<void>;
-  // ... all DDL methods listed in DbContext DDL Execution Methods above
-  // ... plus all get*QueryDef generator methods
-}
-```
-
-Interface for DDL execution and QueryDef generation methods. DbContext implements this interface. Used by the `initialize()` function and `Migration.up()` callback parameter type.
-
-## DbContextStatus
-
-```typescript
-type DbContextStatus = "ready" | "connect" | "transact";
-```
-
-| Value | Description |
-|-------|-------------|
-| `"ready"` | Not connected |
-| `"connect"` | Connected, no active transaction |
-| `"transact"` | Connected with active transaction |
-
-## _Migration
-
-```typescript
-const _Migration: TableBuilder<{ code: ColumnBuilder<string, ...> }, {}>
-```
-
-System migration tracking table. Automatically registered in every DbContext as `_migration`. Has a single `code` column (VARCHAR(255)) as primary key, storing executed migration names.

package/docs/expression.md

@@ -1,220 +0,0 @@
-# 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) |