@simplysm/orm-common 13.0.99 → 14.0.1

package/README.md

@@ -1,192 +0,0 @@
-# @simplysm/orm-common
-
-Simplysm Package - ORM Module (common)
-
-Dialect-independent ORM for MySQL, MSSQL, and PostgreSQL. Provides schema definition, type-safe query building, expression construction, and query rendering without any direct database dependency. Actual database execution is handled by `@simplysm/orm-node`.
-
-## Installation
-
-```bash
-npm install @simplysm/orm-common
-```
-
-## API Overview
-
-### Core
-| API | Type | Description |
-|-----|------|-------------|
-| `defineDbContext` | function | Create a DbContext definition (blueprint) |
-| `createDbContext` | function | Create a DbContext instance from definition + executor |
-| `DbContextDef` | interface | DbContext definition (schema metadata, no runtime state) |
-| `DbContextBase` | interface | Internal interface used by Queryable/Executable |
-| `DbContextStatus` | type | Connection status: `"ready" \| "connect" \| "transact"` |
-| `DbContextInstance` | type | Full DbContext instance with accessors and methods |
-| `DbContextConnectionMethods` | interface | connect/connectWithoutTransaction/transaction methods |
-| `DbContextDdlMethods` | interface | DDL execution and QueryDef generation methods |
-| `DbTransactionError` | class | Standardized transaction error with error codes |
-| `DbErrorCode` | enum | Transaction error codes (NO_ACTIVE_TRANSACTION, DEADLOCK, etc.) |
-
--> See [docs/core.md](./docs/core.md) for details.
-
-### Queryable / Executable
-| API | Type | Description |
-|-----|------|-------------|
-| `Queryable` | class | Type-safe query builder (SELECT/INSERT/UPDATE/DELETE) |
-| `queryable` | function | Factory to create Queryable accessor for DbContext |
-| `Executable` | class | Stored procedure execution wrapper |
-| `executable` | function | Factory to create Executable accessor for DbContext |
-| `parseSearchQuery` | function | Parse search query string to SQL LIKE patterns |
-| `ParsedSearchQuery` | interface | Search query parsing result (or/must/not arrays) |
-
--> See [docs/queryable.md](./docs/queryable.md) for details.
-
-### Expression
-| API | Type | Description |
-|-----|------|-------------|
-| `expr` | object | Dialect-independent SQL expression builder |
-| `ExprUnit` | class | Type-safe expression wrapper |
-| `WhereExprUnit` | class | WHERE clause expression wrapper |
-| `ExprInput` | type | Input type accepting ExprUnit or literal |
-| `SwitchExprBuilder` | interface | CASE/WHEN expression builder |
-
--> See [docs/expression.md](./docs/expression.md) for details.
-
-### Schema Builders
-| API | Type | Description |
-|-----|------|-------------|
-| `Table` | function | Table builder factory |
-| `TableBuilder` | class | Table definition builder (columns, PK, indexes, relations) |
-| `View` | function | View builder factory |
-| `ViewBuilder` | class | View definition builder (query, relations) |
-| `Procedure` | function | Procedure builder factory |
-| `ProcedureBuilder` | class | Stored procedure definition builder |
-| `ColumnBuilder` | class | Column definition builder (type, nullable, default) |
-| `createColumnFactory` | function | Column type factory (int, varchar, datetime, etc.) |
-| `IndexBuilder` | class | Index definition builder |
-| `createIndexFactory` | function | Index factory |
-| `ForeignKeyBuilder` | class | FK relation builder (N:1, creates DB constraint) |
-| `ForeignKeyTargetBuilder` | class | FK reverse-reference builder (1:N) |
-| `RelationKeyBuilder` | class | Logical relation builder (N:1, no DB FK) |
-| `RelationKeyTargetBuilder` | class | Logical reverse-reference builder (1:N, no DB FK) |
-| `createRelationFactory` | function | Relation builder factory |
-| `_Migration` | const | Built-in system migration table |
-| `ColumnBuilderRecord` | type | Column builder record type |
-| `RelationBuilderRecord` | type | Relation builder record type |
-| `InferColumns` | type | Infer value types from column builders |
-| `InferColumnExprs` | type | Infer expression input types |
-| `InferInsertColumns` | type | INSERT type inference |
-| `InferUpdateColumns` | type | UPDATE type inference |
-| `RequiredInsertKeys` | type | Required column keys for INSERT |
-| `OptionalInsertKeys` | type | Optional column keys for INSERT |
-| `DataToColumnBuilderRecord` | type | Data record to column builder record |
-| `InferDeepRelations` | type | Deep relation type inference |
-| `ExtractRelationTarget` | type | Extract N:1 relation target type |
-| `ExtractRelationTargetResult` | type | Extract 1:N relation target type |
-
--> See [docs/schema-builders.md](./docs/schema-builders.md) for details.
-
-### Query Builder
-| API | Type | Description |
-|-----|------|-------------|
-| `createQueryBuilder` | function | Create dialect-specific QueryBuilder |
-| `QueryBuilderBase` | class | Abstract QueryDef-to-SQL renderer |
-| `ExprRendererBase` | class | Abstract expression-to-SQL renderer |
-| `MysqlQueryBuilder` | class | MySQL query builder |
-| `MysqlExprRenderer` | class | MySQL expression renderer |
-| `MssqlQueryBuilder` | class | MSSQL query builder |
-| `MssqlExprRenderer` | class | MSSQL expression renderer |
-| `PostgresqlQueryBuilder` | class | PostgreSQL query builder |
-| `PostgresqlExprRenderer` | class | PostgreSQL expression renderer |
-
--> See [docs/query-builder.md](./docs/query-builder.md) for details.
-
-### Types
-| API | Type | Description |
-|-----|------|-------------|
-| `Dialect` | type | Database dialect (`"mysql" \| "mssql" \| "postgresql"`) |
-| `dialects` | const | List of all supported dialects |
-| `IsolationLevel` | type | Transaction isolation level |
-| `DataRecord` | type | Query result data record (supports nesting) |
-| `DbContextExecutor` | interface | DB connection and query executor interface |
-| `QueryBuildResult` | interface | Built SQL string + metadata |
-| `ResultMeta` | interface | Result transformation metadata |
-| `Migration` | interface | Database migration definition |
-| `DataType` | type | SQL data type definition (14 variants) |
-| `ColumnPrimitiveMap` | type | TypeScript type name to actual type mapping |
-| `ColumnPrimitiveStr` | type | Column primitive type name |
-| `ColumnPrimitive` | type | All column-storable primitive types |
-| `ColumnMeta` | interface | Column metadata |
-| `DateUnit` | type | Date operation unit |
-| `QueryDefObjectName` | interface | DB object name (database.schema.name) |
-| `QueryDef` | type | All query definition union type |
-| `SelectQueryDef` | interface | SELECT query definition |
-| `InsertQueryDef` | interface | INSERT query definition |
-| `UpdateQueryDef` | interface | UPDATE query definition |
-| `DeleteQueryDef` | interface | DELETE query definition |
-| `UpsertQueryDef` | interface | UPSERT query definition |
-| `DDL_TYPES` | const | DDL type constants |
-| `Expr` | type | All expression union type |
-| `WhereExpr` | type | WHERE clause expression union type |
-| `WinFn` | type | Window function union type |
-| `WinSpec` | interface | Window specification (OVER clause) |
-| `parseQueryResult` | function | Transform raw DB results to typed objects |
-| `inferColumnPrimitiveStr` | function | Infer ColumnPrimitiveStr from runtime value |
-| `dataTypeStrToColumnPrimitiveStr` | const | SQL type to TypeScript type mapping |
-
--> See [docs/types.md](./docs/types.md) and [docs/utilities.md](./docs/utilities.md) for details.
-
-## Usage Examples
-
-### Define Schema and Query
-
-```typescript
-import { Table, defineDbContext, createDbContext, expr } from "@simplysm/orm-common";
-
-// Define tables
-const User = Table("User")
-  .database("mydb")
-  .columns((c) => ({
-    id: c.bigint().autoIncrement(),
-    name: c.varchar(100),
-    email: c.varchar(200).nullable(),
-    status: c.varchar(20).default("active"),
-  }))
-  .primaryKey("id")
-  .indexes((i) => [i.index("email").unique()]);
-
-const Post = Table("Post")
-  .database("mydb")
-  .columns((c) => ({
-    id: c.bigint().autoIncrement(),
-    authorId: c.bigint(),
-    title: c.varchar(200),
-  }))
-  .primaryKey("id")
-  .relations((r) => ({
-    author: r.foreignKey(["authorId"], () => User),
-  }));
-
-// Define DbContext
-const MyDb = defineDbContext({
-  tables: { user: User, post: Post },
-});
-
-// Create instance and query
-const db = createDbContext(MyDb, executor, { database: "mydb" });
-
-await db.connect(async () => {
-  // SELECT with WHERE
-  const activeUsers = await db.user()
-    .where((u) => [expr.eq(u.status, "active")])
-    .orderBy((u) => u.name)
-    .execute();
-
-  // INSERT
-  await db.user().insert([{ name: "John", email: "john@test.com" }]);
-
-  // JOIN with include
-  const posts = await db.post()
-    .include((p) => p.author)
-    .execute();
-});
-```

package/docs/core.md

@@ -1,234 +0,0 @@
-# Core
-
-## `defineDbContext`
-
-Factory function that creates a DbContext definition (blueprint). Takes table, view, procedure builders and migration definitions. Automatically includes the `_migration` system table.
-
-```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>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `config.tables` | `TTables` | Table builder definitions |
-| `config.views` | `TViews` | View builder definitions |
-| `config.procedures` | `TProcedures` | Procedure builder definitions |
-| `config.migrations` | `Migration[]` | Migration definitions |
-
-## `createDbContext`
-
-DbContext instance factory. Takes a `DbContextDef` and `DbContextExecutor` and creates a complete DbContext instance with queryable accessors, DDL methods, and connection/transaction management.
-
-```typescript
-function createDbContext<TDef extends DbContextDef<any, any, any>>(
-  def: TDef,
-  executor: DbContextExecutor,
-  opt: { database: string; schema?: string },
-): DbContextInstance<TDef>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `def` | `TDef` | Definition object created by `defineDbContext()` |
-| `executor` | `DbContextExecutor` | Query executor implementation |
-| `opt.database` | `string` | Database name |
-| `opt.schema` | `string` | Schema name (MSSQL: dbo, PostgreSQL: public) |
-
-## `DbContextDef`
-
-DbContext definition (blueprint). Created by `defineDbContext()`. Contains schema metadata but no runtime state.
-
-```typescript
-interface DbContextDef<
-  TTables extends Record<string, TableBuilder<any, any>>,
-  TViews extends Record<string, ViewBuilder<any, any, any>>,
-  TProcedures extends Record<string, ProcedureBuilder<any, any>> = {},
-> {
-  readonly meta: {
-    readonly tables: TTables;
-    readonly views: TViews;
-    readonly procedures: TProcedures;
-    readonly migrations: Migration[];
-  };
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `meta.tables` | `TTables` | Table builder definitions |
-| `meta.views` | `TViews` | View builder definitions |
-| `meta.procedures` | `TProcedures` | Procedure builder definitions |
-| `meta.migrations` | `Migration[]` | Migration definitions |
-
-## `DbContextBase`
-
-Internal interface used by Queryable, Executable, and ViewBuilder.
-
-```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<any, any> | ViewBuilder<any, any, any>,
-  ): QueryDefObjectName;
-  switchFk(table: QueryDefObjectName, enabled: boolean): Promise<void>;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `status` | `DbContextStatus` | Current connection status |
-| `database` | `string \| undefined` | Database name |
-| `schema` | `string \| undefined` | Schema name |
-| `getNextAlias()` | `() => string` | Generate next table alias |
-| `resetAliasCounter()` | `() => void` | Reset alias counter |
-| `executeDefs()` | `(defs, resultMetas?) => Promise<T[][]>` | Execute query definitions |
-| `getQueryDefObjectName()` | `(tableOrView) => QueryDefObjectName` | Get qualified object name |
-| `switchFk()` | `(table, enabled) => Promise<void>` | Enable/disable FK constraints |
-
-## `DbContextStatus`
-
-Connection status type.
-
-```typescript
-type DbContextStatus = "ready" | "connect" | "transact";
-```
-
-## `DbContextInstance`
-
-Full DbContext instance type created by `createDbContext`. Extends `DbContextBase` with queryable accessors for tables/views, executable accessors for procedures, DDL methods, and connection/transaction management.
-
-```typescript
-type DbContextInstance<TDef extends DbContextDef<any, any, any>> = DbContextBase &
-  DbContextConnectionMethods &
-  DbContextDdlMethods & {
-    [K in keyof TDef["meta"]["tables"]]: () => Queryable<...>;
-  } & {
-    [K in keyof TDef["meta"]["views"]]: () => Queryable<...>;
-  } & {
-    [K in keyof TDef["meta"]["procedures"]]: () => Executable<...>;
-  } & {
-    _migration: () => Queryable<{ code: string }, any>;
-    initialize(options?: { dbs?: string[]; force?: boolean }): Promise<void>;
-  };
-```
-
-## `DbContextConnectionMethods`
-
-Connection and transaction management methods.
-
-```typescript
-interface DbContextConnectionMethods {
-  connect<TResult>(fn: () => Promise<TResult>, isolationLevel?: IsolationLevel): Promise<TResult>;
-  connectWithoutTransaction<TResult>(callback: () => Promise<TResult>): Promise<TResult>;
-  transaction<TResult>(fn: () => Promise<TResult>, isolationLevel?: IsolationLevel): Promise<TResult>;
-}
-```
-
-| Method | Description |
-|--------|-------------|
-| `connect()` | Execute callback within a transaction (auto commit/rollback) |
-| `connectWithoutTransaction()` | Connect without transaction, execute callback, auto-close |
-| `transaction()` | Start transaction in already-connected state (auto commit/rollback) |
-
-## `DbContextDdlMethods`
-
-DDL execution methods and QueryDef generators for tables, views, procedures, columns, indexes, foreign keys, and schema operations.
-
-```typescript
-interface DbContextDdlMethods {
-  createTable(table: TableBuilder<any, any>): Promise<void>;
-  dropTable(table: QueryDefObjectName): Promise<void>;
-  renameTable(table: QueryDefObjectName, newName: string): Promise<void>;
-  createView(view: ViewBuilder<any, any, any>): Promise<void>;
-  dropView(view: QueryDefObjectName): Promise<void>;
-  createProc(procedure: ProcedureBuilder<any, any>): Promise<void>;
-  dropProc(procedure: QueryDefObjectName): Promise<void>;
-  addColumn(table: QueryDefObjectName, columnName: string, column: ColumnBuilder<any, any>): Promise<void>;
-  dropColumn(table: QueryDefObjectName, column: string): Promise<void>;
-  modifyColumn(table: QueryDefObjectName, columnName: string, column: ColumnBuilder<any, any>): 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<any, any>): Promise<void>;
-  addIndex(table: QueryDefObjectName, indexBuilder: IndexBuilder<string[]>): 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>;
-  // QueryDef generators (get*QueryDef methods for each DDL operation)
-  getCreateTableQueryDef(table: TableBuilder<any, any>): QueryDef;
-  getCreateViewQueryDef(view: ViewBuilder<any, any, any>): QueryDef;
-  getCreateProcQueryDef(procedure: ProcedureBuilder<any, any>): QueryDef;
-  getCreateObjectQueryDef(builder: TableBuilder | ViewBuilder | ProcedureBuilder): QueryDef;
-  getDropTableQueryDef(table: QueryDefObjectName): QueryDef;
-  getRenameTableQueryDef(table: QueryDefObjectName, newName: string): QueryDef;
-  getDropViewQueryDef(view: QueryDefObjectName): QueryDef;
-  getDropProcQueryDef(procedure: QueryDefObjectName): QueryDef;
-  getAddColumnQueryDef(table: QueryDefObjectName, columnName: string, column: ColumnBuilder<any, any>): QueryDef;
-  getDropColumnQueryDef(table: QueryDefObjectName, column: string): QueryDef;
-  getModifyColumnQueryDef(table: QueryDefObjectName, columnName: string, column: ColumnBuilder<any, any>): QueryDef;
-  getRenameColumnQueryDef(table: QueryDefObjectName, column: string, newName: string): QueryDef;
-  getAddPrimaryKeyQueryDef(table: QueryDefObjectName, columns: string[]): QueryDef;
-  getDropPrimaryKeyQueryDef(table: QueryDefObjectName): QueryDef;
-  getAddForeignKeyQueryDef(table: QueryDefObjectName, relationName: string, relationDef: ForeignKeyBuilder<any, any>): QueryDef;
-  getAddIndexQueryDef(table: QueryDefObjectName, indexBuilder: IndexBuilder<string[]>): QueryDef;
-  getDropForeignKeyQueryDef(table: QueryDefObjectName, relationName: string): QueryDef;
-  getDropIndexQueryDef(table: QueryDefObjectName, columns: string[]): QueryDef;
-  getClearSchemaQueryDef(params: { database: string; schema?: string }): QueryDef;
-  getSchemaExistsQueryDef(database: string, schema?: string): QueryDef;
-  getTruncateQueryDef(table: QueryDefObjectName): QueryDef;
-  getSwitchFkQueryDef(table: QueryDefObjectName, enabled: boolean): QueryDef;
-}
-```
-
-## `DbTransactionError`
-
-Database transaction error with standardized error codes for DBMS-independent error handling.
-
-```typescript
-class DbTransactionError extends Error {
-  override readonly name = "DbTransactionError";
-  constructor(
-    public readonly code: DbErrorCode,
-    message: string,
-    public readonly originalError?: unknown,
-  );
-}
-```
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `code` | `DbErrorCode` | Standardized error code |
-| `originalError` | `unknown` | Original DBMS error (for debugging) |
-
-## `DbErrorCode`
-
-Transaction-related error codes.
-
-```typescript
-enum DbErrorCode {
-  NO_ACTIVE_TRANSACTION = "NO_ACTIVE_TRANSACTION",
-  TRANSACTION_ALREADY_STARTED = "TRANSACTION_ALREADY_STARTED",
-  DEADLOCK = "DEADLOCK",
-  LOCK_TIMEOUT = "LOCK_TIMEOUT",
-}
-```

package/docs/expression.md

@@ -1,234 +0,0 @@
-# Expression
-
-## `ExprUnit`
-
-Type-safe expression wrapper. Tracks expression return type using TypeScript generics.
-
-```typescript
-class ExprUnit<TPrimitive extends ColumnPrimitive> {
-  readonly $infer!: TPrimitive;
-  get n(): ExprUnit<NonNullable<TPrimitive>>;
-  constructor(readonly dataType: ColumnPrimitiveStr, readonly expr: Expr);
-}
-```
-
-| 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 |
-
-## `WhereExprUnit`
-
-Expression wrapper for WHERE clause conditions.
-
-```typescript
-class WhereExprUnit {
-  constructor(readonly expr: WhereExpr);
-}
-```
-
-## `ExprInput`
-
-Input type that accepts `ExprUnit` or literal values.
-
-```typescript
-type ExprInput<TPrimitive extends ColumnPrimitive> = ExprUnit<TPrimitive> | TPrimitive;
-```
-
-## `SwitchExprBuilder`
-
-CASE/WHEN expression builder interface.
-
-```typescript
-interface SwitchExprBuilder<TPrimitive extends ColumnPrimitive> {
-  case(condition: WhereExprUnit, then: ExprInput<TPrimitive>): SwitchExprBuilder<TPrimitive>;
-  default(value: ExprInput<TPrimitive>): ExprUnit<TPrimitive>;
-}
-```
-
-## `expr`
-
-Dialect-independent SQL expression builder. Generates JSON AST (`Expr`) instead of SQL strings, which `QueryBuilder` converts to each DBMS (MySQL, MSSQL, PostgreSQL).
-
-```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>;
-};
-```
-
-### 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 |
-
-### Aggregate Functions
-
-| Method | SQL | Description |
-|--------|-----|-------------|
-| `count()` | `COUNT` | Record count |
-| `sum()` | `SUM` | Sum |
-| `avg()` | `AVG` | Average |
-| `max()` | `MAX` | Maximum |
-| `min()` | `MIN` | Minimum |
-
-### Window Functions
-
-| Method | SQL | Description |
-|--------|-----|-------------|
-| `window()` | `OVER(...)` | Window function (rowNumber, rank, denseRank, ntile, lag, lead, firstValue, lastValue, sum, avg, count, min, max) |