metal-orm 1.0.11 → 1.0.13

package/dist/{select-654m4qy8.d.cts → select-CCp1oz9p.d.cts}

@@ -1,7 +1,26 @@
 /**
  * Supported column data types for database schema definitions
  */
-type ColumnType = 'INT' | 'INTEGER' | 'VARCHAR' | 'TEXT' | 'JSON' | 'ENUM' | 'BOOLEAN' | 'int' | 'integer' | 'varchar' | 'text' | 'json' | 'enum' | 'boolean';
+type ColumnType = 'INT' | 'INTEGER' | 'BIGINT' | 'VARCHAR' | 'TEXT' | 'JSON' | 'ENUM' | 'DECIMAL' | 'FLOAT' | 'DOUBLE' | 'UUID' | 'DATE' | 'DATETIME' | 'TIMESTAMP' | 'TIMESTAMPTZ' | 'BOOLEAN' | 'int' | 'integer' | 'bigint' | 'varchar' | 'text' | 'json' | 'enum' | 'decimal' | 'float' | 'double' | 'uuid' | 'date' | 'datetime' | 'timestamp' | 'timestamptz' | 'boolean';
+type ReferentialAction = 'NO ACTION' | 'RESTRICT' | 'CASCADE' | 'SET NULL' | 'SET DEFAULT';
+interface RawDefaultValue {
+    raw: string;
+}
+type DefaultValue = unknown | RawDefaultValue;
+interface ForeignKeyReference {
+    /** Target table name */
+    table: string;
+    /** Target column name */
+    column: string;
+    /** Optional constraint name */
+    name?: string;
+    /** ON DELETE action */
+    onDelete?: ReferentialAction;
+    /** ON UPDATE action */
+    onUpdate?: ReferentialAction;
+    /** Whether the constraint is deferrable (Postgres) */
+    deferrable?: boolean;
+}
 /**
  * Definition of a database column
  */
@@ -14,6 +33,20 @@ interface ColumnDef<T extends ColumnType = ColumnType> {
     primary?: boolean;
     /** Whether this column cannot be null */
     notNull?: boolean;
+    /** Whether this column must be unique (or name of the unique constraint) */
+    unique?: boolean | string;
+    /** Default value for the column */
+    default?: DefaultValue;
+    /** Whether the column auto-increments / identity */
+    autoIncrement?: boolean;
+    /** Identity strategy where supported */
+    generated?: 'always' | 'byDefault';
+    /** Inline check constraint expression */
+    check?: string;
+    /** Foreign key reference */
+    references?: ForeignKeyReference;
+    /** Column comment/description */
+    comment?: string;
     /** Additional arguments for the column type (e.g., VARCHAR length) */
     args?: any[];
     /** Table name this column belongs to (filled at runtime by defineTable) */
@@ -28,12 +61,44 @@ declare const col: {
      * @returns ColumnDef with INT type
      */
     int: () => ColumnDef<"INT">;
+    /**
+     * Creates a big integer column definition
+     */
+    bigint: () => ColumnDef<"BIGINT">;
     /**
      * Creates a variable character column definition
      * @param length - Maximum length of the string
      * @returns ColumnDef with VARCHAR type
      */
     varchar: (length: number) => ColumnDef<"VARCHAR">;
+    /**
+     * Creates a fixed precision decimal column definition
+     */
+    decimal: (precision: number, scale?: number) => ColumnDef<"DECIMAL">;
+    /**
+     * Creates a floating point column definition
+     */
+    float: (precision?: number) => ColumnDef<"FLOAT">;
+    /**
+     * Creates a UUID column definition
+     */
+    uuid: () => ColumnDef<"UUID">;
+    /**
+     * Creates a timestamp column definition
+     */
+    timestamp: () => ColumnDef<"TIMESTAMP">;
+    /**
+     * Creates a timestamptz column definition
+     */
+    timestamptz: () => ColumnDef<"TIMESTAMPTZ">;
+    /**
+     * Creates a date column definition
+     */
+    date: () => ColumnDef<"DATE">;
+    /**
+     * Creates a datetime column definition
+     */
+    datetime: () => ColumnDef<"DATETIME">;
     /**
      * Creates a JSON column definition
      * @returns ColumnDef with JSON type
@@ -44,12 +109,45 @@ declare const col: {
      * @returns ColumnDef with BOOLEAN type
      */
     boolean: () => ColumnDef<"BOOLEAN">;
+    /**
+     * Creates an enum column definition
+     * @param values - Enum values
+     */
+    enum: (values: string[]) => ColumnDef<"ENUM">;
     /**
      * Marks a column definition as a primary key
      * @param def - Column definition to modify
      * @returns Modified ColumnDef with primary: true
      */
     primaryKey: <T extends ColumnType>(def: ColumnDef<T>) => ColumnDef<T>;
+    /**
+     * Marks a column as NOT NULL
+     */
+    notNull: <T extends ColumnType>(def: ColumnDef<T>) => ColumnDef<T>;
+    /**
+     * Marks a column as UNIQUE
+     */
+    unique: <T extends ColumnType>(def: ColumnDef<T>, name?: string) => ColumnDef<T>;
+    /**
+     * Sets a default value for the column
+     */
+    default: <T extends ColumnType>(def: ColumnDef<T>, value: unknown) => ColumnDef<T>;
+    /**
+     * Sets a raw SQL default value for the column
+     */
+    defaultRaw: <T extends ColumnType>(def: ColumnDef<T>, expression: string) => ColumnDef<T>;
+    /**
+     * Marks a column as auto-increment / identity
+     */
+    autoIncrement: <T extends ColumnType>(def: ColumnDef<T>, strategy?: ColumnDef["generated"]) => ColumnDef<T>;
+    /**
+     * Adds a foreign key reference
+     */
+    references: <T extends ColumnType>(def: ColumnDef<T>, ref: ForeignKeyReference) => ColumnDef<T>;
+    /**
+     * Adds a check constraint to the column
+     */
+    check: <T extends ColumnType>(def: ColumnDef<T>, expression: string) => ColumnDef<T>;
 };
 
 /**
@@ -150,6 +248,31 @@ declare const belongsToMany: <TTarget extends TableDef>(target: TTarget, pivotTa
     cascade?: CascadeMode;
 }) => BelongsToManyRelation<TTarget>;
 
+interface IndexColumn {
+    column: string;
+    order?: 'ASC' | 'DESC';
+    nulls?: 'FIRST' | 'LAST';
+}
+interface IndexDef {
+    name?: string;
+    columns: (string | IndexColumn)[];
+    unique?: boolean;
+    where?: string;
+}
+interface CheckConstraint {
+    name?: string;
+    expression: string;
+}
+interface TableOptions {
+    schema?: string;
+    primaryKey?: string[];
+    indexes?: IndexDef[];
+    checks?: CheckConstraint[];
+    comment?: string;
+    engine?: string;
+    charset?: string;
+    collation?: string;
+}
 interface TableHooks {
     beforeInsert?(ctx: unknown, entity: any): Promise<void> | void;
     afterInsert?(ctx: unknown, entity: any): Promise<void> | void;
@@ -165,12 +288,26 @@ interface TableHooks {
 interface TableDef<T extends Record<string, ColumnDef> = Record<string, ColumnDef>> {
     /** Name of the table */
     name: string;
+    /** Optional schema/catalog name */
+    schema?: string;
     /** Record of column definitions keyed by column name */
     columns: T;
     /** Record of relationship definitions keyed by relation name */
     relations: Record<string, RelationDef>;
     /** Optional lifecycle hooks */
     hooks?: TableHooks;
+    /** Composite primary key definition (falls back to column.primary flags) */
+    primaryKey?: string[];
+    /** Secondary indexes */
+    indexes?: IndexDef[];
+    /** Table-level check constraints */
+    checks?: CheckConstraint[];
+    /** Table comment/description */
+    comment?: string;
+    /** Dialect-specific options */
+    engine?: string;
+    charset?: string;
+    collation?: string;
 }
 /**
  * Creates a table definition with columns and relationships
@@ -189,12 +326,12 @@ interface TableDef<T extends Record<string, ColumnDef> = Record<string, ColumnDe
  * });
  * ```
  */
-declare const defineTable: <T extends Record<string, ColumnDef>>(name: string, columns: T, relations?: Record<string, RelationDef>, hooks?: TableHooks) => TableDef<T>;
+declare const defineTable: <T extends Record<string, ColumnDef>>(name: string, columns: T, relations?: Record<string, RelationDef>, hooks?: TableHooks, options?: TableOptions) => TableDef<T>;
 
 /**
  * Maps a ColumnDef to its TypeScript type representation
  */
-type ColumnToTs<T extends ColumnDef> = T['type'] extends 'INT' | 'INTEGER' | 'int' | 'integer' ? number : T['type'] extends 'BOOLEAN' | 'boolean' ? boolean : T['type'] extends 'JSON' | 'json' ? unknown : string;
+type ColumnToTs<T extends ColumnDef> = T['type'] extends 'INT' | 'INTEGER' | 'int' | 'integer' ? number : T['type'] extends 'BIGINT' | 'bigint' ? number | bigint : T['type'] extends 'DECIMAL' | 'decimal' | 'FLOAT' | 'float' | 'DOUBLE' | 'double' ? number : T['type'] extends 'BOOLEAN' | 'boolean' ? boolean : T['type'] extends 'JSON' | 'json' ? unknown : T['type'] extends 'DATE' | 'date' | 'DATETIME' | 'datetime' | 'TIMESTAMP' | 'timestamp' | 'TIMESTAMPTZ' | 'timestamptz' ? string : string;
 /**
  * Infers a row shape from a table definition
  */
@@ -584,6 +721,20 @@ interface CommonTableExpressionNode {
     /** Whether the CTE is recursive */
     recursive: boolean;
 }
+/**
+ * Supported set operation kinds for compound SELECT queries
+ */
+type SetOperationKind = 'UNION' | 'UNION ALL' | 'INTERSECT' | 'EXCEPT';
+/**
+ * AST node representing a set operation (UNION, INTERSECT, etc.)
+ */
+interface SetOperationNode {
+    type: 'SetOperation';
+    /** Operator to combine queries */
+    operator: SetOperationKind;
+    /** Right-hand query in the compound expression */
+    query: SelectQueryNode;
+}
 /**
  * AST node representing a complete SELECT query
  */
@@ -613,6 +764,8 @@ interface SelectQueryNode {
     meta?: QueryMetadata;
     /** Optional DISTINCT clause */
     distinct?: ColumnNode[];
+    /** Optional set operations chaining this query with others */
+    setOps?: SetOperationNode[];
 }
 interface InsertQueryNode {
     type: 'InsertQuery';
@@ -695,6 +848,7 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
     compileInsert(ast: InsertQueryNode): CompiledQuery;
     compileUpdate(ast: UpdateQueryNode): CompiledQuery;
     compileDelete(ast: DeleteQueryNode): CompiledQuery;
+    supportsReturning(): boolean;
     /**
      * Compiles SELECT query AST to SQL (to be implemented by concrete dialects)
      * @param ast - Query AST
@@ -740,6 +894,31 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
      * @returns Formatted placeholder string
      */
     protected formatPlaceholder(index: number): string;
+    /**
+     * Whether the current dialect supports a given set operation.
+     * Override in concrete dialects to restrict support.
+     */
+    protected supportsSetOperation(kind: SetOperationKind): boolean;
+    /**
+     * Validates set-operation semantics:
+     * - Ensures the dialect supports requested operators.
+     * - Enforces that only the outermost compound query may have ORDER/LIMIT/OFFSET.
+     * @param ast - Query to validate
+     * @param isOutermost - Whether this node is the outermost compound query
+     */
+    protected validateSetOperations(ast: SelectQueryNode, isOutermost?: boolean): void;
+    /**
+     * Hoists CTEs from set-operation operands to the outermost query so WITH appears once.
+     * @param ast - Query AST
+     * @returns Normalized AST without inner CTEs and a list of hoisted CTEs
+     */
+    private hoistCtes;
+    /**
+     * Normalizes a SELECT AST before compilation (validation + CTE hoisting).
+     * @param ast - Query AST
+     * @returns Normalized query AST
+     */
+    protected normalizeSelectAst(ast: SelectQueryNode): SelectQueryNode;
     private readonly expressionCompilers;
     private readonly operandCompilers;
     protected constructor();
@@ -862,6 +1041,12 @@ declare class SelectQueryState {
      * @returns New SelectQueryState with CTE
      */
     withCte(cte: CommonTableExpressionNode): SelectQueryState;
+    /**
+     * Adds a set operation (UNION/INTERSECT/EXCEPT) to the query
+     * @param op - Set operation node to add
+     * @returns New SelectQueryState with set operation
+     */
+    withSetOperation(op: SetOperationNode): SelectQueryState;
 }
 
 /**
@@ -964,6 +1149,31 @@ declare class HydrationManager {
      * @returns Hydration plan or undefined if none exists
      */
     getPlan(): HydrationPlan | undefined;
+    /**
+     * Attaches hydration metadata to a query AST node.
+     */
+    private attachHydrationMeta;
+    /**
+     * Determines whether the query needs pagination rewriting to keep LIMIT/OFFSET
+     * applied to parent rows when eager-loading multiplicative relations.
+     */
+    private requiresParentPagination;
+    private hasMultiplyingRelations;
+    /**
+     * Rewrites the query using CTEs so LIMIT/OFFSET target distinct parent rows
+     * instead of the joined result set.
+     *
+     * The strategy:
+     * - Hoist the original query (minus limit/offset) into a base CTE.
+     * - Select distinct parent ids from that base CTE with the original ordering and pagination.
+     * - Join the base CTE against the paged ids to retrieve the joined rows for just that page.
+     */
+    private wrapForParentPagination;
+    private nextCteName;
+    private getProjectionNames;
+    private buildProjectionAliasMap;
+    private mapOrderBy;
+    private buildPagingColumns;
 }
 
 /**
@@ -1012,6 +1222,13 @@ declare class QueryAstService {
      * @returns Updated query state with CTE
      */
     withCte(name: string, query: SelectQueryNode, columns?: string[], recursive?: boolean): SelectQueryState;
+    /**
+     * Adds a set operation (UNION/UNION ALL/INTERSECT/EXCEPT) to the query
+     * @param operator - Set operator
+     * @param query - Right-hand side query
+     * @returns Updated query state with set operation
+     */
+    withSetOperation(operator: SetOperationKind, query: SelectQueryNode): SelectQueryState;
     /**
      * Selects a subquery as a column
      * @param alias - Alias for the subquery
@@ -1271,6 +1488,12 @@ interface HasDomainEvents {
 type DomainEventHandler$1<Context> = (event: any, ctx: Context) => Promise<void> | void;
 declare const addDomainEvent: (entity: HasDomainEvents, event: any) => void;
 
+interface QueryLogEntry {
+    sql: string;
+    params?: unknown[];
+}
+type QueryLogger = (entry: QueryLogEntry) => void;
+
 interface OrmInterceptor {
     beforeFlush?(ctx: OrmContext): Promise<void> | void;
     afterFlush?(ctx: OrmContext): Promise<void> | void;
@@ -1281,10 +1504,12 @@ interface OrmContextOptions {
     executor: DbExecutor;
     interceptors?: OrmInterceptor[];
     domainEventHandlers?: Record<string, DomainEventHandler[]>;
+    queryLogger?: QueryLogger;
 }
 declare class OrmContext {
     private readonly options;
     private readonly identityMap;
+    private readonly executorWithLogging;
     private readonly unitOfWork;
     private readonly relationChanges;
     private readonly interceptors;
@@ -1331,6 +1556,7 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
     private createChildBuilder;
     private applyAst;
     private applyJoin;
+    private applySetOperation;
     /**
      * Selects specific columns for the query
      * @param columns - Record of column definitions, function nodes, case expressions, or window functions
@@ -1456,6 +1682,30 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      * @returns New query builder instance with the OFFSET clause
      */
     offset(n: number): SelectQueryBuilder<T, TTable>;
+    /**
+     * Combines this query with another using UNION
+     * @param query - Query to union with
+     * @returns New query builder instance with the set operation
+     */
+    union(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
+    /**
+     * Combines this query with another using UNION ALL
+     * @param query - Query to union with
+     * @returns New query builder instance with the set operation
+     */
+    unionAll(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
+    /**
+     * Combines this query with another using INTERSECT
+     * @param query - Query to intersect with
+     * @returns New query builder instance with the set operation
+     */
+    intersect(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
+    /**
+     * Combines this query with another using EXCEPT
+     * @param query - Query to subtract
+     * @returns New query builder instance with the set operation
+     */
+    except(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
     /**
      * Adds a WHERE EXISTS condition to the query
      * @param subquery - Subquery to check for existence
@@ -1519,4 +1769,4 @@ declare const createColumn: (table: string, name: string) => ColumnNode;
  */
 declare const createLiteral: (val: string | number) => LiteralNode;
 
-export { createLiteral as $, RelationKinds as A, type BinaryExpressionNode as B, type ColumnDef as C, type DeleteQueryNode as D, type ExpressionNode as E, type FunctionNode as F, type RelationType as G, type HydrationPlan as H, type InExpressionNode as I, type JsonPathNode as J, type CascadeMode as K, type LogicalExpressionNode as L, type ManyToManyCollection as M, type NullExpressionNode as N, type OperandNode as O, type RelationDef as P, hasMany as Q, type RelationMap as R, type SelectQueryNode as S, type TableDef as T, type UpdateQueryNode as U, belongsTo as V, type WindowFunctionNode as W, belongsToMany as X, type ColumnToTs as Y, type InferRow as Z, createColumn as _, type ColumnNode as a, isOperandNode as a0, isFunctionNode as a1, isCaseExpressionNode as a2, isWindowFunctionNode as a3, isExpressionSelectionNode as a4, addDomainEvent as a5, EntityStatus as a6, type QueryResult as a7, type DbExecutor as a8, type RelationKey as a9, type RelationChange as aa, type HasDomainEvents as ab, type OrmInterceptor as ac, type DomainEventHandler as ad, type OrmContextOptions as ae, type LiteralNode as b, type BetweenExpressionNode as c, type CaseExpressionNode as d, type ExistsExpressionNode as e, type OrderDirection as f, type ScalarSubqueryNode as g, type InsertQueryNode as h, type InsertCompiler as i, type CompiledQuery as j, type UpdateCompiler as k, type DeleteCompiler as l, Dialect as m, type CompilerContext as n, OrmContext as o, type Entity as p, type HasManyRelation as q, type BelongsToRelation as r, type BelongsToManyRelation as s, type HasManyCollection as t, type BelongsToReference as u, SelectQueryBuilder as v, type TableHooks as w, defineTable as x, type ColumnType as y, col as z };
+export { type RelationType as $, type CheckConstraint as A, type BinaryExpressionNode as B, type ColumnDef as C, type DeleteQueryNode as D, type ExpressionNode as E, type FunctionNode as F, type TableOptions as G, type HydrationPlan as H, type InExpressionNode as I, type JsonPathNode as J, type TableHooks as K, type LogicalExpressionNode as L, type ManyToManyCollection as M, type NullExpressionNode as N, type OperandNode as O, defineTable as P, type ColumnType as Q, type RelationMap as R, type SelectQueryNode as S, type TableDef as T, type UpdateQueryNode as U, type ReferentialAction as V, type WindowFunctionNode as W, type RawDefaultValue as X, type DefaultValue as Y, col as Z, RelationKinds as _, type ColumnNode as a, type CascadeMode as a0, type RelationDef as a1, hasMany as a2, belongsTo as a3, belongsToMany as a4, type ColumnToTs as a5, type InferRow as a6, createColumn as a7, createLiteral as a8, isOperandNode as a9, isFunctionNode as aa, isCaseExpressionNode as ab, isWindowFunctionNode as ac, isExpressionSelectionNode as ad, addDomainEvent as ae, EntityStatus as af, type QueryResult as ag, type RelationKey as ah, type RelationChange as ai, type HasDomainEvents as aj, type OrmInterceptor as ak, type DomainEventHandler as al, type OrmContextOptions as am, type QueryLogEntry as an, type QueryLogger as ao, type LiteralNode as b, type BetweenExpressionNode as c, type CaseExpressionNode as d, type ExistsExpressionNode as e, type OrderDirection as f, type ScalarSubqueryNode as g, type InsertQueryNode as h, type InsertCompiler as i, type CompiledQuery as j, type UpdateCompiler as k, type DeleteCompiler as l, Dialect as m, type CompilerContext as n, type ForeignKeyReference as o, type IndexColumn as p, type IndexDef as q, type DbExecutor as r, OrmContext as s, type Entity as t, type HasManyRelation as u, type BelongsToRelation as v, type BelongsToManyRelation as w, type HasManyCollection as x, type BelongsToReference as y, SelectQueryBuilder as z };