metal-orm 1.0.14 → 1.0.15

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

@@ -154,6 +154,8 @@ declare const col: {
  * Types of relationships supported between tables
  */
 declare const RelationKinds: {
+    /** One-to-one relationship */
+    readonly HasOne: "HAS_ONE";
     /** One-to-many relationship */
     readonly HasMany: "HAS_MANY";
     /** Many-to-one relationship */
@@ -176,6 +178,16 @@ interface HasManyRelation<TTarget extends TableDef = TableDef> {
     localKey?: string;
     cascade?: CascadeMode;
 }
+/**
+ * One-to-one relationship definition
+ */
+interface HasOneRelation<TTarget extends TableDef = TableDef> {
+    type: typeof RelationKinds.HasOne;
+    target: TTarget;
+    foreignKey: string;
+    localKey?: string;
+    cascade?: CascadeMode;
+}
 /**
  * Many-to-one relationship definition
  */
@@ -204,7 +216,7 @@ interface BelongsToManyRelation<TTarget extends TableDef = TableDef> {
 /**
  * Union type representing any supported relationship definition
  */
-type RelationDef = HasManyRelation | BelongsToRelation | BelongsToManyRelation;
+type RelationDef = HasManyRelation | HasOneRelation | BelongsToRelation | BelongsToManyRelation;
 /**
  * Creates a one-to-many relationship definition
  * @param target - Target table of the relationship
@@ -218,6 +230,14 @@ type RelationDef = HasManyRelation | BelongsToRelation | BelongsToManyRelation;
  * ```
  */
 declare const hasMany: <TTarget extends TableDef>(target: TTarget, foreignKey: string, localKey?: string, cascade?: CascadeMode) => HasManyRelation<TTarget>;
+/**
+ * Creates a one-to-one relationship definition
+ * @param target - Target table of the relationship
+ * @param foreignKey - Foreign key column name on the child table
+ * @param localKey - Local key column name (optional)
+ * @returns HasOneRelation definition
+ */
+declare const hasOne: <TTarget extends TableDef>(target: TTarget, foreignKey: string, localKey?: string, cascade?: CascadeMode) => HasOneRelation<TTarget>;
 /**
  * Creates a many-to-one relationship definition
  * @param target - Target table of the relationship
@@ -338,7 +358,7 @@ type ColumnToTs<T extends ColumnDef> = T['type'] extends 'INT' | 'INTEGER' | 'in
 type InferRow<TTable extends TableDef> = {
     [K in keyof TTable['columns']]: ColumnToTs<TTable['columns'][K]>;
 };
-type RelationResult$1<T extends RelationDef> = T extends HasManyRelation<infer TTarget> ? InferRow<TTarget>[] : T extends BelongsToRelation<infer TTarget> ? InferRow<TTarget> | null : T extends BelongsToManyRelation<infer TTarget> ? (InferRow<TTarget> & {
+type RelationResult$1<T extends RelationDef> = T extends HasManyRelation<infer TTarget> ? InferRow<TTarget>[] : T extends HasOneRelation<infer TTarget> ? InferRow<TTarget> | null : T extends BelongsToRelation<infer TTarget> ? InferRow<TTarget> | null : T extends BelongsToManyRelation<infer TTarget> ? (InferRow<TTarget> & {
     _pivot?: any;
 })[] : never;
 /**
@@ -360,6 +380,11 @@ interface BelongsToReference<TParent> {
     get(): TParent | null;
     set(data: Partial<TParent> | TParent | null): TParent | null;
 }
+interface HasOneReference<TChild> {
+    load(): Promise<TChild | null>;
+    get(): TChild | null;
+    set(data: Partial<TChild> | TChild | null): TChild | null;
+}
 interface ManyToManyCollection<TTarget> {
     load(): Promise<TTarget[]>;
     getItems(): TTarget[];
@@ -368,7 +393,7 @@ interface ManyToManyCollection<TTarget> {
     syncByIds(ids: (number | string)[]): Promise<void>;
 }
 type Entity<TTable extends TableDef, TRow = InferRow<TTable>> = TRow & {
-    [K in keyof RelationMap<TTable>]: TTable['relations'][K] extends HasManyRelation<infer TTarget> ? HasManyCollection<Entity<TTarget>> : TTable['relations'][K] extends BelongsToManyRelation<infer TTarget> ? ManyToManyCollection<Entity<TTarget>> : TTable['relations'][K] extends BelongsToRelation<infer TTarget> ? BelongsToReference<Entity<TTarget>> : never;
+    [K in keyof RelationMap<TTable>]: TTable['relations'][K] extends HasManyRelation<infer TTarget> ? HasManyCollection<Entity<TTarget>> : TTable['relations'][K] extends HasOneRelation<infer TTarget> ? HasOneReference<Entity<TTarget>> : TTable['relations'][K] extends BelongsToManyRelation<infer TTarget> ? ManyToManyCollection<Entity<TTarget>> : TTable['relations'][K] extends BelongsToRelation<infer TTarget> ? BelongsToReference<Entity<TTarget>> : never;
 } & {
     $load<K extends keyof RelationMap<TTable>>(relation: K): Promise<RelationMap<TTable>[K]>;
 };
@@ -448,6 +473,43 @@ declare const ORDER_DIRECTIONS: {
  * Type representing any supported order direction
  */
 type OrderDirection = (typeof ORDER_DIRECTIONS)[keyof typeof ORDER_DIRECTIONS];
+/**
+ * Supported database dialects
+ */
+declare const SUPPORTED_DIALECTS: {
+    /** MySQL database dialect */
+    readonly MYSQL: "mysql";
+    /** SQLite database dialect */
+    readonly SQLITE: "sqlite";
+    /** Microsoft SQL Server dialect */
+    readonly MSSQL: "mssql";
+    /** PostgreSQL database dialect */
+    readonly POSTGRES: "postgres";
+};
+/**
+ * Type representing any supported database dialect
+ */
+type DialectName = (typeof SUPPORTED_DIALECTS)[keyof typeof SUPPORTED_DIALECTS];
+
+/**
+ * Minimal column reference used by AST builders.
+ * Accepts any object with a name and optional table/alias fields
+ * (schema ColumnDef/TableDef remain structurally compatible).
+ */
+interface ColumnRef {
+    name: string;
+    table?: string;
+    alias?: string;
+}
+/**
+ * Minimal table reference used by AST builders.
+ * Keeps AST decoupled from full schema TableDef shape.
+ */
+interface TableRef {
+    name: string;
+    schema?: string;
+    alias?: string;
+}
 
 /**
  * AST node representing a literal value
@@ -476,8 +538,10 @@ interface FunctionNode {
     type: 'Function';
     /** Function name (e.g., COUNT, SUM) */
     name: string;
+    /** Optional canonical function key for dialect-aware rendering */
+    fn?: string;
     /** Function arguments */
-    args: (ColumnNode | LiteralNode | JsonPathNode)[];
+    args: OperandNode[];
     /** Optional alias for the function result */
     alias?: string;
 }
@@ -542,7 +606,7 @@ declare const isOperandNode: (node: any) => node is OperandNode;
 declare const isFunctionNode: (node: any) => node is FunctionNode;
 declare const isCaseExpressionNode: (node: any) => node is CaseExpressionNode;
 declare const isWindowFunctionNode: (node: any) => node is WindowFunctionNode;
-declare const isExpressionSelectionNode: (node: ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode) => node is FunctionNode | CaseExpressionNode | WindowFunctionNode;
+declare const isExpressionSelectionNode: (node: ColumnRef | FunctionNode | CaseExpressionNode | WindowFunctionNode) => node is FunctionNode | CaseExpressionNode | WindowFunctionNode;
 /**
  * AST node representing a binary expression (e.g., column = value)
  */
@@ -626,11 +690,11 @@ interface JoinNode {
     /** Type of join (INNER, LEFT, RIGHT, etc.) */
     kind: JoinKind;
     /** Table to join */
-    table: TableNode;
+    table: TableNode | FunctionTableNode;
     /** Join condition expression */
     condition: ExpressionNode;
-    /** Optional relation name for code generation */
-    relationName?: string;
+    /** Optional metadata for non-SQL concerns (e.g., relation name) */
+    meta?: Record<string, unknown>;
 }
 
 /**
@@ -645,6 +709,26 @@ interface TableNode {
     /** Optional table alias */
     alias?: string;
 }
+/**
+ * AST node representing a function used as a table source (table-valued function)
+ */
+interface FunctionTableNode {
+    type: 'FunctionTable';
+    /** Function name */
+    name: string;
+    /** Optional schema for the function (some dialects) */
+    schema?: string;
+    /** Function arguments as operand nodes */
+    args?: any[];
+    /** Optional alias for the function table */
+    alias?: string;
+    /** LATERAL flag */
+    lateral?: boolean;
+    /** WITH ORDINALITY flag */
+    withOrdinality?: boolean;
+    /** Optional column aliases */
+    columnAliases?: string[];
+}
 /**
  * AST node representing an ORDER BY clause
  */
@@ -655,58 +739,6 @@ interface OrderByNode {
     /** Order direction (ASC or DESC) */
     direction: OrderDirection;
 }
-/**
- * Plan describing pivot columns needed for hydration
- */
-interface HydrationPivotPlan {
-    table: string;
-    primaryKey: string;
-    aliasPrefix: string;
-    columns: string[];
-}
-/**
- * Plan for hydrating relationship data
- */
-interface HydrationRelationPlan {
-    /** Name of the relationship */
-    name: string;
-    /** Alias prefix for the relationship */
-    aliasPrefix: string;
-    /** Type of relationship */
-    type: RelationType;
-    /** Target table name */
-    targetTable: string;
-    /** Target table primary key */
-    targetPrimaryKey: string;
-    /** Foreign key column */
-    foreignKey: string;
-    /** Local key column */
-    localKey: string;
-    /** Columns to include */
-    columns: string[];
-    /** Optional pivot plan for many-to-many relationships */
-    pivot?: HydrationPivotPlan;
-}
-/**
- * Complete hydration plan for a query
- */
-interface HydrationPlan {
-    /** Root table name */
-    rootTable: string;
-    /** Root table primary key */
-    rootPrimaryKey: string;
-    /** Root table columns */
-    rootColumns: string[];
-    /** Relationship hydration plans */
-    relations: HydrationRelationPlan[];
-}
-/**
- * Query metadata including hydration information
- */
-interface QueryMetadata {
-    /** Optional hydration plan */
-    hydration?: HydrationPlan;
-}
 /**
  * AST node representing a Common Table Expression (CTE)
  */
@@ -742,8 +774,8 @@ interface SelectQueryNode {
     type: 'SelectQuery';
     /** Optional CTEs (WITH clauses) */
     ctes?: CommonTableExpressionNode[];
-    /** FROM clause table */
-    from: TableNode;
+    /** FROM clause table (either a Table or a FunctionTable) */
+    from: TableNode | FunctionTableNode;
     /** SELECT clause columns */
     columns: (ColumnNode | FunctionNode | ScalarSubqueryNode | CaseExpressionNode | WindowFunctionNode)[];
     /** JOIN clauses */
@@ -761,7 +793,7 @@ interface SelectQueryNode {
     /** Optional OFFSET clause */
     offset?: number;
     /** Optional query metadata */
-    meta?: QueryMetadata;
+    meta?: Record<string, unknown>;
     /** Optional DISTINCT clause */
     distinct?: ColumnNode[];
     /** Optional set operations chaining this query with others */
@@ -805,6 +837,72 @@ interface DeleteQueryNode {
     returning?: ColumnNode[];
 }
 
+/**
+ * Plan describing pivot columns needed for hydration
+ */
+interface HydrationPivotPlan {
+    table: string;
+    primaryKey: string;
+    aliasPrefix: string;
+    columns: string[];
+}
+/**
+ * Plan for hydrating relationship data
+ */
+interface HydrationRelationPlan {
+    /** Name of the relationship */
+    name: string;
+    /** Alias prefix for the relationship */
+    aliasPrefix: string;
+    /** Type of relationship */
+    type: RelationType;
+    /** Target table name */
+    targetTable: string;
+    /** Target table primary key */
+    targetPrimaryKey: string;
+    /** Foreign key column */
+    foreignKey: string;
+    /** Local key column */
+    localKey: string;
+    /** Columns to include */
+    columns: string[];
+    /** Optional pivot plan for many-to-many relationships */
+    pivot?: HydrationPivotPlan;
+}
+/**
+ * Complete hydration plan for a query
+ */
+interface HydrationPlan {
+    /** Root table name */
+    rootTable: string;
+    /** Root table primary key */
+    rootPrimaryKey: string;
+    /** Root table columns */
+    rootColumns: string[];
+    /** Relationship hydration plans */
+    relations: HydrationRelationPlan[];
+}
+/**
+ * Metadata bag for attaching hydration to query ASTs without coupling AST types.
+ */
+interface HydrationMetadata {
+    hydration?: HydrationPlan;
+    [key: string]: unknown;
+}
+
+interface FunctionRenderContext {
+    node: FunctionNode;
+    compiledArgs: string[];
+}
+type FunctionRenderer = (ctx: FunctionRenderContext) => string;
+interface FunctionStrategy {
+    /**
+     * Returns a renderer for a specific function name (e.g. "DATE_ADD").
+     * Returns undefined if this dialect doesn't support the function.
+     */
+    getRenderer(functionName: string): FunctionRenderer | undefined;
+}
+
 /**
  * Context for SQL compilation with parameter management
  */
@@ -839,6 +937,8 @@ interface DeleteCompiler {
  * Abstract base class for SQL dialect implementations
  */
 declare abstract class Dialect implements SelectCompiler, InsertCompiler, UpdateCompiler, DeleteCompiler {
+    /** Dialect identifier used for function rendering and formatting */
+    protected abstract readonly dialect: DialectName;
     /**
      * Compiles a SELECT query AST to SQL
      * @param ast - Query AST to compile
@@ -921,7 +1021,8 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
     protected normalizeSelectAst(ast: SelectQueryNode): SelectQueryNode;
     private readonly expressionCompilers;
     private readonly operandCompilers;
-    protected constructor();
+    protected readonly functionStrategy: FunctionStrategy;
+    protected constructor(functionStrategy?: FunctionStrategy);
     /**
      * Registers an expression compiler for a specific node type
      * @param type - Expression node type
@@ -951,8 +1052,14 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
     private registerDefaultExpressionCompilers;
     private registerDefaultOperandCompilers;
     protected compileJsonPath(node: JsonPathNode): string;
+    /**
+     * Compiles a function operand, using the dialect's function strategy.
+     */
+    protected compileFunctionOperand(fnNode: FunctionNode, ctx: CompilerContext): string;
 }
 
+type DialectKey = 'postgres' | 'mysql' | 'sqlite' | 'mssql' | (string & {});
+
 /**
  * Node types that can be used in query projections
  */
@@ -1452,6 +1559,23 @@ interface DbExecutor {
     commitTransaction?(): Promise<void>;
     rollbackTransaction?(): Promise<void>;
 }
+/**
+ * Convert an array of row objects into a QueryResult.
+ */
+declare function rowsToQueryResult(rows: Array<Record<string, unknown>>): QueryResult;
+/**
+ * Minimal contract that most SQL clients can implement.
+ */
+interface SimpleQueryRunner {
+    query(sql: string, params?: unknown[]): Promise<Array<Record<string, unknown>>>;
+    beginTransaction?(): Promise<void>;
+    commitTransaction?(): Promise<void>;
+    rollbackTransaction?(): Promise<void>;
+}
+/**
+ * Generic factory: turn any SimpleQueryRunner into a DbExecutor.
+ */
+declare function createExecutorFromQueryRunner(runner: SimpleQueryRunner): DbExecutor;
 
 declare enum EntityStatus {
     New = "new",
@@ -1532,6 +1656,8 @@ declare class OrmContext {
     getEntitiesForTable(table: TableDef): TrackedEntity[];
 }
 
+type SelectDialectInput = Dialect | DialectKey;
+
 /**
  * Main query builder class for constructing SQL SELECT queries
  * @typeParam T - Result type for projections (unused)
@@ -1737,13 +1863,13 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      * @param dialect - Database dialect to compile for
      * @returns Compiled query with SQL and parameters
      */
-    compile(dialect: Dialect): CompiledQuery;
+    compile(dialect: SelectDialectInput): CompiledQuery;
     /**
      * Converts the query to SQL string for a specific dialect
      * @param dialect - Database dialect to generate SQL for
      * @returns SQL string representation of the query
      */
-    toSql(dialect: Dialect): string;
+    toSql(dialect: SelectDialectInput): string;
     /**
      * Gets the hydration plan for the query
      * @returns Hydration plan or undefined if none exists
@@ -1769,4 +1895,4 @@ declare const createColumn: (table: string, name: string) => ColumnNode;
  */
 declare const createLiteral: (val: string | number) => LiteralNode;
 
-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 };
+export { type RawDefaultValue as $, type BelongsToManyRelation as A, type BinaryExpressionNode as B, type ColumnRef as C, Dialect as D, type ExpressionNode as E, type FunctionNode as F, type HasManyCollection as G, type HydrationPlan as H, type InExpressionNode as I, type JsonPathNode as J, type BelongsToReference as K, type LogicalExpressionNode as L, type ManyToManyCollection as M, type NullExpressionNode as N, type OperandNode as O, SelectQueryBuilder as P, type CheckConstraint as Q, type RelationMap as R, type SelectQueryNode as S, type TableRef as T, type UpdateQueryNode as U, type TableOptions as V, type WindowFunctionNode as W, type TableHooks as X, defineTable as Y, type ColumnType as Z, type ReferentialAction as _, type ColumnNode as a, type DefaultValue as a0, col as a1, RelationKinds as a2, type RelationType as a3, type CascadeMode as a4, type RelationDef as a5, hasMany as a6, hasOne as a7, belongsTo as a8, belongsToMany as a9, createExecutorFromQueryRunner as aA, type ColumnToTs as aa, type InferRow as ab, type HasOneReference as ac, createColumn as ad, createLiteral as ae, isOperandNode as af, isFunctionNode as ag, isCaseExpressionNode as ah, isWindowFunctionNode as ai, isExpressionSelectionNode as aj, type HydrationPivotPlan as ak, type HydrationRelationPlan as al, type HydrationMetadata as am, addDomainEvent as an, EntityStatus as ao, type QueryResult as ap, type RelationKey as aq, type RelationChange as ar, type HasDomainEvents as as, type OrmInterceptor as at, type DomainEventHandler as au, type OrmContextOptions as av, type QueryLogEntry as aw, type QueryLogger as ax, rowsToQueryResult as ay, type SimpleQueryRunner as az, 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 ColumnDef as h, type TableDef as i, type InsertQueryNode as j, type InsertCompiler as k, type CompiledQuery as l, type DialectKey as m, type UpdateCompiler as n, type DeleteQueryNode as o, type DeleteCompiler as p, type CompilerContext as q, type ForeignKeyReference as r, type IndexColumn as s, type IndexDef as t, type DbExecutor as u, OrmContext as v, type Entity as w, type HasManyRelation as x, type HasOneRelation as y, type BelongsToRelation as z };