@simplysm/orm-common 14.0.1 → 14.0.4

package/docs/core.md

@@ -0,0 +1,206 @@
+# Core
+
+DbContext definition, creation, and lifecycle management.
+
+## defineDbContext
+
+Factory function that creates a `DbContextDef` blueprint from tables, views, procedures, and migrations. Automatically adds a `_migration` system table.
+
+```typescript
+function defineDbContext<TTables, TViews, TProcedures>(config: {
+  tables?: TTables;
+  views?: TViews;
+  procedures?: TProcedures;
+  migrations?: Migration[];
+}): DbContextDef<TTables & { _migration: typeof _Migration }, TViews, TProcedures>;
+```
+
+**Parameters:**
+
+| 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 |
+
+**Example:**
+
+```typescript
+const MyDb = defineDbContext({
+  tables: { user: User, post: Post },
+  views: { userSummary: UserSummary },
+  procedures: { getUserById: GetUserById },
+  migrations: [
+    { name: "20260101_001_init", up: async (db) => { await db.createTable(User); } },
+  ],
+});
+```
+
+## createDbContext
+
+Factory that creates a complete `DbContextInstance` from a `DbContextDef` and a `DbContextExecutor`. The returned instance includes queryable accessors for all tables/views, executable accessors for procedures, connection/transaction management, and DDL methods.
+
+```typescript
+function createDbContext<TDef extends DbContextDef<any, any, any>>(
+  def: TDef,
+  executor: DbContextExecutor,
+  opt: { database: string; schema?: string },
+): DbContextInstance<TDef>;
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `def` | `DbContextDef` | Definition created by `defineDbContext()` |
+| `executor` | `DbContextExecutor` | Query executor (e.g., `NodeDbContextExecutor`) |
+| `opt.database` | `string` | Database name |
+| `opt.schema` | `string` | Schema name (MSSQL: dbo, PostgreSQL: public) |
+
+**Example:**
+
+```typescript
+const db = createDbContext(MyDb, executor, { database: "mydb" });
+
+await db.connect(async () => {
+  const users = await db.user().execute();
+});
+```
+
+## DbContextDef
+
+Blueprint interface created by `defineDbContext()`. Contains only schema metadata, no runtime state.
+
+```typescript
+interface DbContextDef<TTables, TViews, TProcedures> {
+  readonly meta: {
+    readonly tables: TTables;
+    readonly views: TViews;
+    readonly procedures: TProcedures;
+    readonly migrations: Migration[];
+  };
+}
+```
+
+## DbContextInstance
+
+Full DbContext instance type returned by `createDbContext()`. Extends `DbContextBase` with queryable accessors, DDL methods, and connection management.
+
+```typescript
+type DbContextInstance<TDef> = 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>;
+  };
+```
+
+## DbContextBase
+
+Core interface used internally 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 | ViewBuilder): QueryDefObjectName;
+  switchFk(table: QueryDefObjectName, enabled: boolean): Promise<void>;
+}
+```
+
+## DbContextStatus
+
+```typescript
+type DbContextStatus = "ready" | "connect" | "transact";
+```
+
+| Value | Description |
+|---|---|
+| `"ready"` | Not connected |
+| `"connect"` | Connected, no active transaction |
+| `"transact"` | Inside a transaction |
+
+## DbContextConnectionMethods
+
+```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(fn, isolationLevel?)` | Connect, begin transaction, execute `fn`, commit. Auto-rollback on error. |
+| `connectWithoutTransaction(fn)` | Connect and execute `fn` without a transaction. For DDL or read-only operations. |
+| `transaction(fn, isolationLevel?)` | Begin a nested transaction within an existing connection. Use inside `connectWithoutTransaction`. |
+
+## DbContextDdlMethods
+
+DDL execution methods and QueryDef generators on `DbContextInstance`.
+
+### Execution Methods
+
+| Method | Signature | Description |
+|---|---|---|
+| `createTable` | `(table: TableBuilder) => Promise<void>` | Create a table |
+| `dropTable` | `(table: QueryDefObjectName) => Promise<void>` | Drop a table |
+| `renameTable` | `(table: QueryDefObjectName, newName: string) => Promise<void>` | Rename a table |
+| `createView` | `(view: ViewBuilder) => Promise<void>` | Create a view |
+| `dropView` | `(view: QueryDefObjectName) => Promise<void>` | Drop a view |
+| `createProc` | `(procedure: ProcedureBuilder) => Promise<void>` | Create a stored procedure |
+| `dropProc` | `(procedure: QueryDefObjectName) => Promise<void>` | Drop a stored procedure |
+| `addColumn` | `(table, columnName, column: ColumnBuilder) => Promise<void>` | Add a column |
+| `dropColumn` | `(table, column: string) => Promise<void>` | Drop a column |
+| `modifyColumn` | `(table, columnName, column: ColumnBuilder) => Promise<void>` | Modify a column |
+| `renameColumn` | `(table, column, newName) => Promise<void>` | Rename a column |
+| `addPrimaryKey` | `(table, columns: string[]) => Promise<void>` | Add primary key |
+| `dropPrimaryKey` | `(table) => Promise<void>` | Drop primary key |
+| `addForeignKey` | `(table, relationName, relationDef: ForeignKeyBuilder) => Promise<void>` | Add foreign key |
+| `addIndex` | `(table, indexBuilder: IndexBuilder) => Promise<void>` | Add index |
+| `dropForeignKey` | `(table, relationName) => Promise<void>` | Drop foreign key |
+| `dropIndex` | `(table, columns: string[]) => Promise<void>` | Drop index |
+| `clearSchema` | `(params: { database; schema? }) => Promise<void>` | Clear all objects in schema |
+| `schemaExists` | `(database, schema?) => Promise<boolean>` | Check if schema exists |
+| `truncate` | `(table) => Promise<void>` | Truncate table |
+| `switchFk` | `(table, enabled: boolean) => Promise<void>` | Enable/disable FK constraints |
+
+### QueryDef Generator Methods
+
+Each DDL execution method has a corresponding `get*QueryDef` method (e.g., `getCreateTableQueryDef`, `getDropTableQueryDef`) that returns a `QueryDef` without executing it. These are useful for building migration scripts or batching DDL operations.
+
+## DbTransactionError
+
+Standardized transaction error that wraps DBMS-native errors with a `DbErrorCode`.
+
+```typescript
+class DbTransactionError extends Error {
+  readonly name = "DbTransactionError";
+  constructor(
+    readonly code: DbErrorCode,
+    message: string,
+    readonly originalError?: unknown,
+  );
+}
+```
+
+## DbErrorCode
+
+```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

@@ -0,0 +1,217 @@
+# Expression DSL
+
+Dialect-independent SQL expression builder. Generates JSON AST (`Expr`) instead of SQL strings. The QueryBuilder transforms the AST to target DBMS syntax.
+
+## expr
+
+Constant object with all expression builder methods. Used inside Queryable callbacks for `where()`, `select()`, `orderBy()`, etc.
+
+### Value Generation
+
+| Method | Signature | Description |
+|---|---|---|
+| `val` | `(dataType: ColumnPrimitiveStr, value) => ExprUnit` | Wrap literal value as ExprUnit |
+| `col` | `(dataType, ...path: string[]) => ExprUnit` | Generate column reference (internal use) |
+| `raw` | `(dataType) => tagged template => ExprUnit` | Raw SQL expression (escape hatch). Interpolated values are auto-parameterized. |
+
+**Example:**
+
+```typescript
+expr.val("string", "active")
+expr.val("number", 100)
+expr.val("DateOnly", DateOnly.today())
+expr.raw("string")`JSON_EXTRACT(${u.metadata}, '$.email')`
+```
+
+### Comparison Operators (WHERE)
+
+| Method | Signature | Description |
+|---|---|---|
+| `eq` | `(source, target) => WhereExprUnit` | Equality (NULL-safe: MySQL `<=>`) |
+| `gt` | `(source, target) => WhereExprUnit` | Greater than (`>`) |
+| `lt` | `(source, target) => WhereExprUnit` | Less than (`<`) |
+| `gte` | `(source, target) => WhereExprUnit` | Greater than or equal (`>=`) |
+| `lte` | `(source, target) => WhereExprUnit` | Less than or equal (`<=`) |
+| `between` | `(source, from?, to?) => WhereExprUnit` | Range (BETWEEN). Undefined bounds are unbounded. |
+
+### NULL Check
+
+| Method | Signature | Description |
+|---|---|---|
+| `null` | `(source) => WhereExprUnit` | IS NULL check |
+
+### String Search
+
+| Method | Signature | Description |
+|---|---|---|
+| `like` | `(source, pattern) => WhereExprUnit` | LIKE pattern matching (`%`, `_` wildcards) |
+| `regexp` | `(source, pattern) => WhereExprUnit` | Regular expression matching |
+
+### IN / EXISTS
+
+| Method | Signature | Description |
+|---|---|---|
+| `in` | `(source, values[]) => WhereExprUnit` | IN value list |
+| `inQuery` | `(source, query: Queryable) => WhereExprUnit` | IN subquery (single-column SELECT) |
+| `exists` | `(query: Queryable) => WhereExprUnit` | EXISTS subquery |
+
+### Logical Operators
+
+| Method | Signature | Description |
+|---|---|---|
+| `not` | `(arg: WhereExprUnit) => WhereExprUnit` | NOT |
+| `and` | `(conditions: WhereExprUnit[]) => WhereExprUnit` | AND (all must match) |
+| `or` | `(conditions: WhereExprUnit[]) => WhereExprUnit` | OR (any must match) |
+
+### String Functions (SELECT)
+
+| Method | Signature | Description |
+|---|---|---|
+| `concat` | `(...args) => ExprUnit<string>` | String concatenation (CONCAT) |
+| `left` | `(source, length) => ExprUnit` | Left N characters |
+| `right` | `(source, length) => ExprUnit` | Right N characters |
+| `trim` | `(source) => ExprUnit` | Trim whitespace |
+| `padStart` | `(source, length, fillString) => ExprUnit` | Left padding (LPAD) |
+| `replace` | `(source, from, to) => ExprUnit` | String replacement |
+| `upper` | `(source) => ExprUnit` | Uppercase |
+| `lower` | `(source) => ExprUnit` | Lowercase |
+| `length` | `(source) => ExprUnit<number>` | Character length |
+| `byteLength` | `(source) => ExprUnit<number>` | Byte length |
+| `substring` | `(source, start, length?) => ExprUnit` | Substring (1-based index) |
+| `indexOf` | `(source, search) => ExprUnit<number>` | Find position (1-based, 0 if not found) |
+
+### Number Functions (SELECT)
+
+| Method | Signature | Description |
+|---|---|---|
+| `abs` | `(source) => ExprUnit` | Absolute value |
+| `round` | `(source, digits) => ExprUnit` | Round |
+| `ceil` | `(source) => ExprUnit` | Ceiling |
+| `floor` | `(source) => ExprUnit` | Floor |
+
+### Date/Time Functions (SELECT)
+
+| Method | Signature | Description |
+|---|---|---|
+| `year` | `(source) => ExprUnit<number>` | Extract year |
+| `month` | `(source) => ExprUnit<number>` | Extract month |
+| `day` | `(source) => ExprUnit<number>` | Extract day |
+| `hour` | `(source) => ExprUnit<number>` | Extract hour |
+| `minute` | `(source) => ExprUnit<number>` | Extract minute |
+| `second` | `(source) => ExprUnit<number>` | Extract second |
+| `isoWeek` | `(source) => ExprUnit<number>` | ISO week number |
+| `isoWeekStartDate` | `(source) => ExprUnit<DateOnly>` | ISO week start date (Monday) |
+| `isoYearMonth` | `(source) => ExprUnit<DateOnly>` | ISO year-month (YYYYMM format) |
+| `dateDiff` | `(unit: DateUnit, from, to) => ExprUnit<number>` | Date difference |
+| `dateAdd` | `(unit: DateUnit, source, value) => ExprUnit` | Date arithmetic |
+| `formatDate` | `(source, format: string) => ExprUnit<string>` | Date formatting |
+
+### Conditional
+
+| Method | Signature | Description |
+|---|---|---|
+| `coalesce` | `(...args) => ExprUnit` | First non-null value (COALESCE) |
+| `nullIf` | `(source, value) => ExprUnit` | NULL if equal (NULLIF) |
+| `is` | `(condition: WhereExprUnit) => ExprUnit<boolean>` | Convert condition to boolean (0/1) |
+| `switch` | `() => SwitchExprBuilder` | CASE WHEN expression (chain `.case().default()`) |
+| `if` | `(condition, then, else?) => ExprUnit` | IIF conditional expression |
+
+### Aggregate Functions
+
+| Method | Signature | Description |
+|---|---|---|
+| `count` | `(arg?, distinct?) => ExprUnit<number>` | COUNT |
+| `sum` | `(arg) => ExprUnit<number \| undefined>` | SUM |
+| `avg` | `(arg) => ExprUnit<number \| undefined>` | AVG |
+| `max` | `(arg) => ExprUnit<T \| undefined>` | MAX |
+| `min` | `(arg) => ExprUnit<T \| undefined>` | MIN |
+
+### Utility
+
+| Method | Signature | Description |
+|---|---|---|
+| `greatest` | `(...args) => ExprUnit` | Greatest of values |
+| `least` | `(...args) => ExprUnit` | Least of values |
+| `rowNum` | `() => ExprUnit<number>` | Simple row number |
+| `random` | `() => ExprUnit<number>` | Random number (RAND/RANDOM) |
+| `cast` | `(source, targetType: DataType) => ExprUnit` | Type cast |
+| `subquery` | `(dataType, queryDef: SelectQueryDef) => ExprUnit` | Scalar subquery |
+| `toExpr` | `(value: ExprInput) => Expr` | Convert ExprInput to raw Expr AST |
+
+### Window Functions
+
+All window functions accept a `WinSpecInput: { partitionBy?: ExprInput[]; orderBy?: [ExprInput, ("ASC" | "DESC")?][] }`.
+
+| Method | Signature | Description |
+|---|---|---|
+| `rowNumber` | `(spec) => ExprUnit<number>` | ROW_NUMBER() OVER(...) |
+| `rank` | `(spec) => ExprUnit<number>` | RANK() OVER(...) |
+| `denseRank` | `(spec) => ExprUnit<number>` | DENSE_RANK() OVER(...) |
+| `ntile` | `(n, spec) => ExprUnit<number>` | NTILE(n) OVER(...) |
+| `lag` | `(column, spec, offset?, defaultValue?) => ExprUnit` | Previous row value |
+| `lead` | `(column, spec, offset?, defaultValue?) => ExprUnit` | Next row value |
+| `firstValue` | `(column, spec) => ExprUnit` | First value in partition |
+| `lastValue` | `(column, spec) => ExprUnit` | Last value in partition |
+| `sumOver` | `(column, spec) => ExprUnit<number \| undefined>` | Window SUM |
+| `avgOver` | `(column, spec) => ExprUnit<number \| undefined>` | Window AVG |
+| `countOver` | `(spec, column?) => ExprUnit<number>` | Window COUNT |
+| `minOver` | `(column, spec) => ExprUnit` | Window MIN |
+| `maxOver` | `(column, spec) => ExprUnit` | Window MAX |
+
+## SwitchExprBuilder
+
+Builder interface for CASE WHEN expressions. Created by `expr.switch()`.
+
+```typescript
+interface SwitchExprBuilder<TPrimitive extends ColumnPrimitive> {
+  case(condition: WhereExprUnit, then: ExprInput<TPrimitive>): SwitchExprBuilder<TPrimitive>;
+  default(value: ExprInput<TPrimitive>): ExprUnit<TPrimitive>;
+}
+```
+
+**Example:**
+
+```typescript
+db.user().select((u) => ({
+  tier: expr.switch<string>()
+    .case(expr.gte(u.score, 90), "gold")
+    .case(expr.gte(u.score, 70), "silver")
+    .default("bronze"),
+}))
+```
+
+## ExprUnit
+
+Type-safe expression wrapper that tracks the return type through TypeScript generics.
+
+```typescript
+class ExprUnit<TPrimitive extends ColumnPrimitive> {
+  readonly $infer!: TPrimitive;
+  readonly dataType: ColumnPrimitiveStr;
+  readonly expr: Expr;
+
+  /** Non-nullable assertion accessor */
+  get n(): ExprUnit<NonNullable<TPrimitive>>;
+
+  constructor(dataType: ColumnPrimitiveStr, expr: Expr);
+}
+```
+
+## WhereExprUnit
+
+WHERE clause expression wrapper.
+
+```typescript
+class WhereExprUnit {
+  readonly expr: WhereExpr;
+  constructor(expr: WhereExpr);
+}
+```
+
+## ExprInput
+
+Union type accepting either an `ExprUnit` or a literal value.
+
+```typescript
+type ExprInput<TPrimitive extends ColumnPrimitive> = ExprUnit<TPrimitive> | TPrimitive;
+```

package/docs/query-builder.md

@@ -0,0 +1,126 @@
+# Query Builder
+
+Transforms `QueryDef` AST into dialect-specific SQL strings.
+
+## createQueryBuilder
+
+Factory function that creates the appropriate `QueryBuilderBase` for a given dialect.
+
+```typescript
+function createQueryBuilder(dialect: Dialect): QueryBuilderBase;
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `dialect` | `"mysql" \| "mssql" \| "postgresql"` | Target database dialect |
+
+**Returns:** `QueryBuilderBase` instance (`MysqlQueryBuilder`, `MssqlQueryBuilder`, or `PostgresqlQueryBuilder`)
+
+**Example:**
+
+```typescript
+const builder = createQueryBuilder("mysql");
+const result = builder.build(selectQueryDef);
+console.log(result.sql);
+```
+
+## QueryBuilderBase
+
+Abstract base class for QueryDef-to-SQL rendering. Implements dispatch logic shared across all dialects. Dialect-specific differences are delegated to abstract methods.
+
+```typescript
+abstract class QueryBuilderBase {
+  abstract readonly exprRenderer: ExprRendererBase;
+
+  build(def: QueryDef): QueryBuildResult;
+}
+```
+
+### build
+
+The main entry point. Accepts any `QueryDef` (SELECT, INSERT, UPDATE, DELETE, UPSERT, DDL, etc.) and returns a `QueryBuildResult` containing the SQL string and optional result set metadata.
+
+```typescript
+build(def: QueryDef): QueryBuildResult;
+```
+
+**Returns:** `QueryBuildResult` with:
+
+| Field | Type | Description |
+|---|---|---|
+| `sql` | `string` | Generated SQL |
+| `resultSetIndex?` | `number` | Which result set to read (default: 0) |
+| `resultSetStride?` | `number` | For multi-result sets, read every Nth |
+
+## ExprRendererBase
+
+Abstract base class for rendering `Expr` and `WhereExpr` AST nodes to SQL strings. Each dialect implements its own renderer for DBMS-specific syntax.
+
+```typescript
+abstract class ExprRendererBase {
+  render(expr: Expr): string;
+  renderWhere(expr: WhereExpr): string;
+}
+```
+
+## MysqlQueryBuilder
+
+MySQL-specific query builder. Extends `QueryBuilderBase`.
+
+```typescript
+class MysqlQueryBuilder extends QueryBuilderBase {
+  readonly exprRenderer: MysqlExprRenderer;
+}
+```
+
+MySQL-specific behaviors:
+- Uses `<=>` for NULL-safe equality
+- Uses backtick quoting for identifiers
+- INSERT OUTPUT via separate SELECT with `LAST_INSERT_ID()`
+- UPSERT via `INSERT ... ON DUPLICATE KEY UPDATE`
+
+## MssqlQueryBuilder
+
+MSSQL-specific query builder. Extends `QueryBuilderBase`.
+
+```typescript
+class MssqlQueryBuilder extends QueryBuilderBase {
+  readonly exprRenderer: MssqlExprRenderer;
+}
+```
+
+MSSQL-specific behaviors:
+- Uses `[` `]` for identifier quoting
+- TOP instead of LIMIT
+- OUTPUT clause for INSERT/UPDATE/DELETE
+- `IDENTITY_INSERT` for auto-increment override
+- `OFFSET...FETCH` for pagination
+
+## PostgresqlQueryBuilder
+
+PostgreSQL-specific query builder. Extends `QueryBuilderBase`.
+
+```typescript
+class PostgresqlQueryBuilder extends QueryBuilderBase {
+  readonly exprRenderer: PostgresqlExprRenderer;
+}
+```
+
+PostgreSQL-specific behaviors:
+- Uses `"` for identifier quoting
+- `RETURNING` clause for INSERT/UPDATE/DELETE output
+- `LIMIT...OFFSET` for pagination
+- `LATERAL` subquery JOINs
+- `IS NOT DISTINCT FROM` for NULL-safe equality
+
+## Dialect-Specific Expression Renderers
+
+| Class | Dialect | Description |
+|---|---|---|
+| `MysqlExprRenderer` | MySQL | Renders Expr AST to MySQL SQL syntax |
+| `MssqlExprRenderer` | MSSQL | Renders Expr AST to MSSQL SQL syntax |
+| `PostgresqlExprRenderer` | PostgreSQL | Renders Expr AST to PostgreSQL SQL syntax |
+
+Each renderer extends `ExprRendererBase` and overrides methods for dialect-specific expression rendering (e.g., date functions, string functions, type casting).