metal-orm 1.0.11 → 1.0.13

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { O as OperandNode, C as ColumnDef, a as ColumnNode, B as BinaryExpressionNode, E as ExpressionNode, L as LogicalExpressionNode, N as NullExpressionNode, b as LiteralNode, I as InExpressionNode, c as BetweenExpressionNode, J as JsonPathNode, d as CaseExpressionNode, S as SelectQueryNode, e as ExistsExpressionNode, W as WindowFunctionNode, f as OrderDirection, F as FunctionNode, g as ScalarSubqueryNode, T as TableDef, h as InsertQueryNode, i as InsertCompiler, j as CompiledQuery, U as UpdateQueryNode, k as UpdateCompiler, D as DeleteQueryNode, l as DeleteCompiler, m as Dialect, n as CompilerContext, H as HydrationPlan, R as RelationMap, o as OrmContext, p as Entity, q as HasManyRelation, r as BelongsToRelation, s as BelongsToManyRelation, t as HasManyCollection, u as BelongsToReference, M as ManyToManyCollection, v as SelectQueryBuilder } from './select-654m4qy8.js';
-export { K as CascadeMode, Y as ColumnToTs, y as ColumnType, a8 as DbExecutor, ad as DomainEventHandler, a6 as EntityStatus, ab as HasDomainEvents, Z as InferRow, ae as OrmContextOptions, ac as OrmInterceptor, a7 as QueryResult, aa as RelationChange, P as RelationDef, a9 as RelationKey, A as RelationKinds, G as RelationType, w as TableHooks, a5 as addDomainEvent, V as belongsTo, X as belongsToMany, z as col, _ as createColumn, $ as createLiteral, x as defineTable, Q as hasMany, a2 as isCaseExpressionNode, a4 as isExpressionSelectionNode, a1 as isFunctionNode, a0 as isOperandNode, a3 as isWindowFunctionNode } from './select-654m4qy8.js';
+import { O as OperandNode, C as ColumnDef, a as ColumnNode, B as BinaryExpressionNode, E as ExpressionNode, L as LogicalExpressionNode, N as NullExpressionNode, b as LiteralNode, I as InExpressionNode, c as BetweenExpressionNode, J as JsonPathNode, d as CaseExpressionNode, S as SelectQueryNode, e as ExistsExpressionNode, W as WindowFunctionNode, f as OrderDirection, F as FunctionNode, g as ScalarSubqueryNode, T as TableDef, h as InsertQueryNode, i as InsertCompiler, j as CompiledQuery, U as UpdateQueryNode, k as UpdateCompiler, D as DeleteQueryNode, l as DeleteCompiler, m as Dialect, n as CompilerContext, o as ForeignKeyReference, p as IndexColumn, q as IndexDef, r as DbExecutor, H as HydrationPlan, R as RelationMap, s as OrmContext, t as Entity, u as HasManyRelation, v as BelongsToRelation, w as BelongsToManyRelation, x as HasManyCollection, y as BelongsToReference, M as ManyToManyCollection, z as SelectQueryBuilder } from './select-CCp1oz9p.js';
+export { a0 as CascadeMode, A as CheckConstraint, a5 as ColumnToTs, Q as ColumnType, Y as DefaultValue, al as DomainEventHandler, af as EntityStatus, aj as HasDomainEvents, a6 as InferRow, am as OrmContextOptions, ak as OrmInterceptor, an as QueryLogEntry, ao as QueryLogger, ag as QueryResult, X as RawDefaultValue, V as ReferentialAction, ai as RelationChange, a1 as RelationDef, ah as RelationKey, _ as RelationKinds, $ as RelationType, K as TableHooks, G as TableOptions, ae as addDomainEvent, a3 as belongsTo, a4 as belongsToMany, Z as col, a7 as createColumn, a8 as createLiteral, P as defineTable, a2 as hasMany, ab as isCaseExpressionNode, ad as isExpressionSelectionNode, aa as isFunctionNode, a9 as isOperandNode, ac as isWindowFunctionNode } from './select-CCp1oz9p.js';
 
 /**
  * Converts a primitive or existing operand into an operand node
@@ -341,10 +341,60 @@ declare class DeleteQueryBuilder<T> {
     getAST(): DeleteQueryNode;
 }
 
+/**
+ * Shared SQL compiler for dialects with standard LIMIT/OFFSET pagination.
+ * Concrete dialects override only the minimal hooks (identifier quoting,
+ * JSON path, placeholders, RETURNING support) instead of re-implementing
+ * the entire compile pipeline.
+ */
+declare abstract class SqlDialectBase extends Dialect {
+    /**
+     * Quotes an identifier (dialect-specific).
+     */
+    abstract quoteIdentifier(id: string): string;
+    /**
+     * Compiles SELECT query AST to SQL using common rules.
+     */
+    protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string;
+    protected compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string;
+    /**
+     * Compiles a single SELECT (no set operations, no CTE prefix).
+     */
+    private compileSelectCore;
+    protected compileUpdateAst(ast: UpdateQueryNode, ctx: CompilerContext): string;
+    protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string;
+    /**
+     * Default RETURNING compilation: no support.
+     */
+    protected compileReturning(returning: ColumnNode[] | undefined, _ctx: CompilerContext): string;
+    protected formatReturningColumns(returning: ColumnNode[]): string;
+    /**
+     * DISTINCT clause. Override for DISTINCT ON support.
+     */
+    protected compileDistinct(ast: SelectQueryNode): string;
+    protected compileSelectColumns(ast: SelectQueryNode, ctx: CompilerContext): string;
+    protected compileFrom(ast: SelectQueryNode['from']): string;
+    protected compileTableName(table: {
+        name: string;
+        schema?: string;
+    }): string;
+    protected compileJoins(ast: SelectQueryNode, ctx: CompilerContext): string;
+    protected compileGroupBy(ast: SelectQueryNode): string;
+    protected compileHaving(ast: SelectQueryNode, ctx: CompilerContext): string;
+    protected compileOrderBy(ast: SelectQueryNode): string;
+    /**
+     * Default LIMIT/OFFSET pagination clause.
+     */
+    protected compilePagination(ast: SelectQueryNode, _orderByClause: string): string;
+    protected compileCtes(ast: SelectQueryNode, ctx: CompilerContext): string;
+    protected stripTrailingSemicolon(sql: string): string;
+    protected wrapSetOperand(sql: string): string;
+}
+
 /**
  * MySQL dialect implementation
  */
-declare class MySqlDialect extends Dialect {
+declare class MySqlDialect extends SqlDialectBase {
     /**
      * Creates a new MySqlDialect instance
      */
@@ -361,16 +411,6 @@ declare class MySqlDialect extends Dialect {
      * @returns MySQL JSON path expression
      */
     protected compileJsonPath(node: JsonPathNode): string;
-    /**
-     * Compiles SELECT query AST to MySQL SQL
-     * @param ast - Query AST
-     * @param ctx - Compiler context
-     * @returns MySQL SQL string
-     */
-    protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string;
-    protected compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string;
-    protected compileUpdateAst(ast: UpdateQueryNode, ctx: CompilerContext): string;
-    protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string;
 }
 
 /**
@@ -409,12 +449,17 @@ declare class SqlServerDialect extends Dialect {
     protected compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string;
     protected compileUpdateAst(ast: UpdateQueryNode, ctx: CompilerContext): string;
     protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string;
+    private compileSelectCore;
+    private compileOrderBy;
+    private compilePagination;
+    private compileCtes;
+    private wrapSetOperand;
 }
 
 /**
  * SQLite dialect implementation
  */
-declare class SqliteDialect extends Dialect {
+declare class SqliteDialect extends SqlDialectBase {
     /**
      * Creates a new SqliteDialect instance
      */
@@ -431,18 +476,220 @@ declare class SqliteDialect extends Dialect {
      * @returns SQLite JSON path expression
      */
     protected compileJsonPath(node: JsonPathNode): string;
+    protected compileReturning(returning: ColumnNode[] | undefined, ctx: CompilerContext): string;
+    supportsReturning(): boolean;
+}
+
+/**
+ * PostgreSQL dialect implementation
+ */
+declare class PostgresDialect extends SqlDialectBase {
     /**
-     * Compiles SELECT query AST to SQLite SQL
-     * @param ast - Query AST
-     * @param ctx - Compiler context
-     * @returns SQLite SQL string
+     * Creates a new PostgresDialect instance
      */
-    protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string;
-    protected compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string;
-    protected compileUpdateAst(ast: UpdateQueryNode, ctx: CompilerContext): string;
-    protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string;
+    constructor();
+    /**
+     * Quotes an identifier using PostgreSQL double-quote syntax
+     * @param id - Identifier to quote
+     * @returns Quoted identifier
+     */
+    quoteIdentifier(id: string): string;
+    /**
+     * Compiles JSON path expression using PostgreSQL syntax
+     * @param node - JSON path node
+     * @returns PostgreSQL JSON path expression
+     */
+    protected compileJsonPath(node: JsonPathNode): string;
     protected compileReturning(returning: ColumnNode[] | undefined, ctx: CompilerContext): string;
+    supportsReturning(): boolean;
+}
+
+interface DatabaseColumn {
+    name: string;
+    type: string;
+    notNull?: boolean;
+    default?: unknown;
+    autoIncrement?: boolean;
+    generated?: 'always' | 'byDefault';
+    unique?: boolean | string;
+    references?: ForeignKeyReference;
+    check?: string;
+}
+interface DatabaseIndex {
+    name: string;
+    columns: IndexColumn[];
+    unique?: boolean;
+    where?: string;
+}
+interface DatabaseCheck {
+    name?: string;
+    expression: string;
+}
+interface DatabaseTable {
+    name: string;
+    schema?: string;
+    columns: DatabaseColumn[];
+    primaryKey?: string[];
+    indexes?: DatabaseIndex[];
+    checks?: DatabaseCheck[];
+}
+interface DatabaseSchema {
+    tables: DatabaseTable[];
+}
+
+type TableLike = {
+    name: string;
+    schema?: string;
+};
+/**
+ * Common behavior for schema dialects (DDL).
+ * Concrete dialects only override the small surface area instead of reimplementing everything.
+ */
+declare abstract class BaseSchemaDialect implements SchemaDialect {
+    abstract name: DialectName;
+    abstract quoteIdentifier(id: string): string;
+    abstract renderColumnType(column: ColumnDef): string;
+    abstract renderAutoIncrement(column: ColumnDef, table: TableDef): string | undefined;
+    abstract renderIndex(table: TableDef, index: IndexDef): string;
+    supportsPartialIndexes(): boolean;
+    formatTableName(table: TableLike): string;
+    renderDefault(value: unknown, _column: ColumnDef): string;
+    renderReference(ref: ForeignKeyReference, _table: TableDef): string;
+    renderTableOptions(_table: TableDef): string | undefined;
+    dropTableSql(table: DatabaseTable): string[];
+    abstract dropColumnSql(table: DatabaseTable, column: string): string[];
+    abstract dropIndexSql(table: DatabaseTable, index: string): string[];
+    warnDropColumn(_table: DatabaseTable, _column: string): string | undefined;
+}
+
+declare class PostgresSchemaDialect extends BaseSchemaDialect {
+    name: DialectName;
+    quoteIdentifier(id: string): string;
+    renderColumnType(column: ColumnDef): string;
+    renderAutoIncrement(column: ColumnDef): string | undefined;
+    renderIndex(table: TableDef, index: IndexDef): string;
+    supportsPartialIndexes(): boolean;
+    dropColumnSql(table: DatabaseTable, column: string): string[];
+    dropIndexSql(table: DatabaseTable, index: string): string[];
+}
+
+declare class MySqlSchemaDialect extends BaseSchemaDialect {
+    name: DialectName;
+    quoteIdentifier(id: string): string;
+    renderColumnType(column: ColumnDef): string;
+    renderDefault(value: unknown): string;
+    renderAutoIncrement(column: ColumnDef): string | undefined;
+    renderIndex(table: TableDef, index: IndexDef): string;
+    renderTableOptions(table: TableDef): string | undefined;
+    dropColumnSql(table: DatabaseTable, column: string): string[];
+    dropIndexSql(table: DatabaseTable, index: string): string[];
+}
+
+declare class SQLiteSchemaDialect extends BaseSchemaDialect {
+    name: DialectName;
+    quoteIdentifier(id: string): string;
+    renderColumnType(column: ColumnDef): string;
+    renderAutoIncrement(column: ColumnDef, table: TableDef): string | undefined;
+    preferInlinePkAutoincrement(column: ColumnDef, table: TableDef, pk: string[]): boolean;
+    renderDefault(value: unknown): string;
+    renderIndex(table: TableDef, index: IndexDef): string;
+    dropColumnSql(_table: DatabaseTable, _column: string): string[];
+    dropIndexSql(_table: DatabaseTable, index: string): string[];
+    warnDropColumn(table: DatabaseTable, column: string): string | undefined;
+}
+
+declare class MSSqlSchemaDialect extends BaseSchemaDialect {
+    name: DialectName;
+    quoteIdentifier(id: string): string;
+    renderColumnType(column: ColumnDef): string;
+    renderDefault(value: unknown): string;
+    renderAutoIncrement(column: ColumnDef): string | undefined;
+    renderIndex(table: TableDef, index: IndexDef): string;
+    supportsPartialIndexes(): boolean;
+    dropColumnSql(table: DatabaseTable, column: string): string[];
+    dropIndexSql(table: DatabaseTable, index: string): string[];
+}
+
+type DialectName = 'postgres' | 'mysql' | 'sqlite' | 'mssql';
+interface SchemaDialect {
+    name: DialectName;
+    quoteIdentifier(id: string): string;
+    formatTableName(table: TableDef | DatabaseTable): string;
+    renderColumnType(column: ColumnDef): string;
+    renderDefault(value: unknown, column: ColumnDef): string;
+    renderAutoIncrement(column: ColumnDef, table: TableDef): string | undefined;
+    renderReference(ref: ForeignKeyReference, table: TableDef): string;
+    renderIndex(table: TableDef, index: IndexDef): string;
+    renderTableOptions(table: TableDef): string | undefined;
+    supportsPartialIndexes(): boolean;
+    preferInlinePkAutoincrement?(column: ColumnDef, table: TableDef, pk: string[]): boolean;
+    dropColumnSql(table: DatabaseTable, column: string): string[];
+    dropIndexSql(table: DatabaseTable, index: string): string[];
+    dropTableSql(table: DatabaseTable): string[];
+    warnDropColumn?(table: DatabaseTable, column: string): string | undefined;
+}
+interface SchemaGenerateResult {
+    tableSql: string;
+    indexSql: string[];
+}
+declare const escapeLiteral: (value: string) => string;
+declare const formatLiteral: (value: unknown, dialect: DialectName) => string;
+declare const resolvePrimaryKey: (table: TableDef) => string[];
+declare const quoteQualified: (dialect: SchemaDialect, identifier: string) => string;
+declare const renderIndexColumns: (dialect: SchemaDialect, columns: (string | IndexColumn)[]) => string;
+declare const deriveIndexName: (table: TableDef, index: IndexDef) => string;
+interface RenderColumnOptions {
+    includePrimary?: boolean;
+}
+declare const renderColumnDefinition: (table: TableDef, col: ColumnDef, dialect: SchemaDialect, options?: RenderColumnOptions) => {
+    sql: string;
+    inlinePrimary: boolean;
+};
+declare const generateCreateTableSql: (table: TableDef, dialect: SchemaDialect) => SchemaGenerateResult;
+declare const generateSchemaSql: (tables: TableDef[], dialect: SchemaDialect) => string[];
+
+type SchemaChangeKind = 'createTable' | 'dropTable' | 'addColumn' | 'dropColumn' | 'alterColumn' | 'addIndex' | 'dropIndex';
+interface SchemaChange {
+    kind: SchemaChangeKind;
+    table: string;
+    description: string;
+    statements: string[];
+    safe: boolean;
+}
+interface SchemaPlan {
+    changes: SchemaChange[];
+    warnings: string[];
+}
+interface SchemaDiffOptions {
+    /** Allow destructive operations (drops) */
+    allowDestructive?: boolean;
 }
+declare const diffSchema: (expectedTables: TableDef[], actualSchema: DatabaseSchema, dialect: SchemaDialect, options?: SchemaDiffOptions) => SchemaPlan;
+interface SynchronizeOptions extends SchemaDiffOptions {
+    dryRun?: boolean;
+}
+declare const synchronizeSchema: (expectedTables: TableDef[], actualSchema: DatabaseSchema, dialect: SchemaDialect, executor: DbExecutor, options?: SynchronizeOptions) => Promise<SchemaPlan>;
+
+/**
+ * Dialect-agnostic options for schema introspection.
+ */
+interface IntrospectOptions {
+    /** Dialect-specific schema/catalog. Postgres: schema; MySQL: database; MSSQL: schema. */
+    schema?: string;
+    includeTables?: string[];
+    excludeTables?: string[];
+}
+/**
+ * Strategy interface implemented per dialect to introspect an existing database schema.
+ */
+interface SchemaIntrospector {
+    introspect(executor: DbExecutor, options: IntrospectOptions): Promise<DatabaseSchema>;
+}
+
+/**
+ * Introspects an existing database schema using the dialect-specific strategy.
+ */
+declare const introspectSchema: (executor: DbExecutor, dialect: DialectName, options?: IntrospectOptions) => Promise<DatabaseSchema>;
 
 /**
  * Browser-compatible implementation of AsyncLocalStorage
@@ -647,6 +894,7 @@ declare class DefaultHasManyCollection<TChild> implements HasManyCollection<TChi
     clear(): void;
     private get relationKey();
     private hydrateFromCache;
+    toJSON(): TChild[];
 }
 
 type Rows$1 = Record<string, any>;
@@ -668,6 +916,7 @@ declare class DefaultBelongsToReference<TParent> implements BelongsToReference<T
     set(data: Partial<TParent> | TParent | null): TParent | null;
     private get relationKey();
     private populateFromHydrationCache;
+    toJSON(): TParent | null;
 }
 
 type Rows = Record<string, any>[];
@@ -694,8 +943,9 @@ declare class DefaultManyToManyCollection<TTarget> implements ManyToManyCollecti
     private get relationKey();
     private get targetKey();
     private hydrateFromCache;
+    toJSON(): TTarget[];
 }
 
 declare function executeHydrated<TTable extends TableDef>(ctx: OrmContext, qb: SelectQueryBuilder<any, TTable>): Promise<Entity<TTable>[]>;
 
-export { AsyncLocalStorage, BelongsToManyRelation, BelongsToReference, BelongsToRelation, BetweenExpressionNode, BinaryExpressionNode, CaseExpressionNode, ColumnDef, ColumnNode, DefaultBelongsToReference, DefaultHasManyCollection, DefaultManyToManyCollection, DeleteQueryBuilder, Entity, ExistsExpressionNode, ExpressionNode, type ExpressionVisitor, FunctionNode, HasManyCollection, HasManyRelation, InExpressionNode, InsertQueryBuilder, JsonPathNode, LiteralNode, LogicalExpressionNode, ManyToManyCollection, MySqlDialect, NullExpressionNode, OperandNode, type OperandVisitor, OrmContext, RelationMap, ScalarSubqueryNode, SelectQueryBuilder, SqlServerDialect, SqliteDialect, TableDef, TypeScriptGenerator, UpdateQueryBuilder, WindowFunctionNode, and, avg, between, caseWhen, columnOperand, count, createEntityFromRow, createEntityProxy, denseRank, eq, executeHydrated, exists, firstValue, gt, gte, hydrateRows, inList, isNotNull, isNull, jsonPath, lag, lastValue, lead, like, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, lt, lte, neq, notBetween, notExists, notInList, notLike, ntile, or, rank, rowNumber, sum, valueToOperand, visitExpression, visitOperand, windowFunction };
+export { AsyncLocalStorage, BaseSchemaDialect, BelongsToManyRelation, BelongsToReference, BelongsToRelation, BetweenExpressionNode, BinaryExpressionNode, CaseExpressionNode, ColumnDef, ColumnNode, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, DbExecutor, DefaultBelongsToReference, DefaultHasManyCollection, DefaultManyToManyCollection, DeleteQueryBuilder, type DialectName, Entity, ExistsExpressionNode, ExpressionNode, type ExpressionVisitor, ForeignKeyReference, FunctionNode, HasManyCollection, HasManyRelation, InExpressionNode, IndexColumn, IndexDef, InsertQueryBuilder, type IntrospectOptions, JsonPathNode, LiteralNode, LogicalExpressionNode, MSSqlSchemaDialect, ManyToManyCollection, MySqlDialect, MySqlSchemaDialect, NullExpressionNode, OperandNode, type OperandVisitor, OrmContext, PostgresDialect, PostgresSchemaDialect, RelationMap, type RenderColumnOptions, SQLiteSchemaDialect, ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDialect, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, SqlServerDialect, SqliteDialect, type SynchronizeOptions, TableDef, TypeScriptGenerator, UpdateQueryBuilder, WindowFunctionNode, and, avg, between, caseWhen, columnOperand, count, createEntityFromRow, createEntityProxy, denseRank, deriveIndexName, diffSchema, eq, escapeLiteral, executeHydrated, exists, firstValue, formatLiteral, generateCreateTableSql, generateSchemaSql, gt, gte, hydrateRows, inList, introspectSchema, isNotNull, isNull, jsonPath, lag, lastValue, lead, like, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, lt, lte, neq, notBetween, notExists, notInList, notLike, ntile, or, quoteQualified, rank, renderColumnDefinition, renderIndexColumns, resolvePrimaryKey, rowNumber, sum, synchronizeSchema, valueToOperand, visitExpression, visitOperand, windowFunction };