metal-orm 1.0.14 → 1.0.16

package/dist/decorators/index.cjs

@@ -24,6 +24,7 @@ __export(decorators_exports, {
   Column: () => Column,
   Entity: () => Entity,
   HasMany: () => HasMany,
+  HasOne: () => HasOne,
   PrimaryKey: () => PrimaryKey,
   bootstrapEntities: () => bootstrapEntities,
   getTableDefFromEntity: () => getTableDefFromEntity,
@@ -133,11 +134,20 @@ function Entity(options = {}) {
 
 // src/decorators/column.ts
 var normalizeColumnInput = (input) => {
+  const asOptions = input;
+  const asDefinition = input;
   const column = {
-    type: input.type ?? input.type,
-    args: input.args ?? input.args,
-    notNull: input.notNull ?? input.notNull,
-    primary: input.primary ?? input.primary
+    type: asOptions.type ?? asDefinition.type,
+    args: asOptions.args ?? asDefinition.args,
+    notNull: asOptions.notNull ?? asDefinition.notNull,
+    primary: asOptions.primary ?? asDefinition.primary,
+    unique: asDefinition.unique,
+    default: asDefinition.default,
+    autoIncrement: asDefinition.autoIncrement,
+    generated: asDefinition.generated,
+    check: asDefinition.check,
+    references: asDefinition.references,
+    comment: asDefinition.comment
   };
   if (!column.type) {
     throw new Error("Column decorator requires a column type");
@@ -186,6 +196,8 @@ function PrimaryKey(definition) {
 
 // src/schema/relation.ts
 var RelationKinds = {
+  /** One-to-one relationship */
+  HasOne: "HAS_ONE",
   /** One-to-many relationship */
   HasMany: "HAS_MANY",
   /** Many-to-one relationship */
@@ -200,6 +212,13 @@ var hasMany = (target, foreignKey, localKey, cascade) => ({
   localKey,
   cascade
 });
+var hasOne = (target, foreignKey, localKey, cascade) => ({
+  type: RelationKinds.HasOne,
+  target,
+  foreignKey,
+  localKey,
+  cascade
+});
 var belongsTo = (target, foreignKey, localKey, cascade) => ({
   type: RelationKinds.BelongsTo,
   target,
@@ -260,6 +279,16 @@ function HasMany(options) {
     cascade: options.cascade
   }));
 }
+function HasOne(options) {
+  return createFieldDecorator((propertyName) => ({
+    kind: RelationKinds.HasOne,
+    propertyKey: propertyName,
+    target: options.target,
+    foreignKey: options.foreignKey,
+    localKey: options.localKey,
+    cascade: options.cascade
+  }));
+}
 function BelongsTo(options) {
   return createFieldDecorator((propertyName) => ({
     kind: RelationKinds.BelongsTo,
@@ -317,54 +346,1436 @@ var toOperand = (val) => {
   if (typeof val === "string" || typeof val === "number" || typeof val === "boolean") {
     return { type: "Literal", value: val };
   }
-  return toNode(val);
+  return toNode(val);
+};
+var columnOperand = (col) => toNode(col);
+var createBinaryExpression = (operator, left, right, escape) => {
+  const node = {
+    type: "BinaryExpression",
+    left: toNode(left),
+    operator,
+    right: toOperand(right)
+  };
+  if (escape !== void 0) {
+    node.escape = toLiteralNode(escape);
+  }
+  return node;
+};
+var eq = (left, right) => createBinaryExpression("=", left, right);
+var and = (...operands) => ({
+  type: "LogicalExpression",
+  operator: "AND",
+  operands
+});
+var createInExpression = (operator, left, values) => ({
+  type: "InExpression",
+  left: toNode(left),
+  operator,
+  right: values.map((v) => toOperand(v))
+});
+var inList = (left, values) => createInExpression("IN", left, values);
+var exists = (subquery) => ({
+  type: "ExistsExpression",
+  operator: "EXISTS",
+  subquery
+});
+var notExists = (subquery) => ({
+  type: "ExistsExpression",
+  operator: "NOT EXISTS",
+  subquery
+});
+
+// src/core/ast/aggregate-functions.ts
+var buildAggregate = (name) => (col) => ({
+  type: "Function",
+  name,
+  args: [columnOperand(col)]
+});
+var count = buildAggregate("COUNT");
+var sum = buildAggregate("SUM");
+var avg = buildAggregate("AVG");
+
+// src/core/functions/standard-strategy.ts
+var StandardFunctionStrategy = class {
+  constructor() {
+    this.renderers = /* @__PURE__ */ new Map();
+    this.registerStandard();
+  }
+  registerStandard() {
+    this.add("ABS", ({ compiledArgs }) => `ABS(${compiledArgs[0]})`);
+    this.add("UPPER", ({ compiledArgs }) => `UPPER(${compiledArgs[0]})`);
+    this.add("LOWER", ({ compiledArgs }) => `LOWER(${compiledArgs[0]})`);
+    this.add("LENGTH", ({ compiledArgs }) => `LENGTH(${compiledArgs[0]})`);
+    this.add("TRIM", ({ compiledArgs }) => `TRIM(${compiledArgs[0]})`);
+    this.add("LTRIM", ({ compiledArgs }) => `LTRIM(${compiledArgs[0]})`);
+    this.add("RTRIM", ({ compiledArgs }) => `RTRIM(${compiledArgs[0]})`);
+    this.add("SUBSTRING", ({ compiledArgs }) => `SUBSTRING(${compiledArgs.join(", ")})`);
+    this.add("CONCAT", ({ compiledArgs }) => `CONCAT(${compiledArgs.join(", ")})`);
+    this.add("NOW", () => `NOW()`);
+    this.add("CURRENT_DATE", () => `CURRENT_DATE`);
+    this.add("CURRENT_TIME", () => `CURRENT_TIME`);
+    this.add("EXTRACT", ({ compiledArgs }) => `EXTRACT(${compiledArgs[0]} FROM ${compiledArgs[1]})`);
+    this.add("YEAR", ({ compiledArgs }) => `EXTRACT(YEAR FROM ${compiledArgs[0]})`);
+    this.add("MONTH", ({ compiledArgs }) => `EXTRACT(MONTH FROM ${compiledArgs[0]})`);
+    this.add("DAY", ({ compiledArgs }) => `EXTRACT(DAY FROM ${compiledArgs[0]})`);
+    this.add("DATE_ADD", ({ compiledArgs }) => `(${compiledArgs[0]} + INTERVAL ${compiledArgs[1]} ${compiledArgs[2]})`);
+    this.add("DATE_SUB", ({ compiledArgs }) => `(${compiledArgs[0]} - INTERVAL ${compiledArgs[1]} ${compiledArgs[2]})`);
+    this.add("DATE_DIFF", ({ compiledArgs }) => `DATEDIFF(${compiledArgs[0]}, ${compiledArgs[1]})`);
+    this.add("DATE_FORMAT", ({ compiledArgs }) => `DATE_FORMAT(${compiledArgs[0]}, ${compiledArgs[1]})`);
+    this.add("UNIX_TIMESTAMP", () => `UNIX_TIMESTAMP()`);
+    this.add("FROM_UNIXTIME", ({ compiledArgs }) => `FROM_UNIXTIME(${compiledArgs[0]})`);
+    this.add("END_OF_MONTH", ({ compiledArgs }) => `LAST_DAY(${compiledArgs[0]})`);
+    this.add("DAY_OF_WEEK", ({ compiledArgs }) => `DAYOFWEEK(${compiledArgs[0]})`);
+    this.add("WEEK_OF_YEAR", ({ compiledArgs }) => `WEEKOFYEAR(${compiledArgs[0]})`);
+    this.add("DATE_TRUNC", ({ compiledArgs }) => `DATE_TRUNC(${compiledArgs[0]}, ${compiledArgs[1]})`);
+  }
+  add(name, renderer) {
+    this.renderers.set(name, renderer);
+  }
+  getRenderer(name) {
+    return this.renderers.get(name);
+  }
+};
+
+// src/core/dialect/abstract.ts
+var Dialect = class _Dialect {
+  /**
+   * Compiles a SELECT query AST to SQL
+   * @param ast - Query AST to compile
+   * @returns Compiled query with SQL and parameters
+   */
+  compileSelect(ast) {
+    const ctx = this.createCompilerContext();
+    const normalized = this.normalizeSelectAst(ast);
+    const rawSql = this.compileSelectAst(normalized, ctx).trim();
+    const sql = rawSql.endsWith(";") ? rawSql : `${rawSql};`;
+    return {
+      sql,
+      params: [...ctx.params]
+    };
+  }
+  compileInsert(ast) {
+    const ctx = this.createCompilerContext();
+    const rawSql = this.compileInsertAst(ast, ctx).trim();
+    const sql = rawSql.endsWith(";") ? rawSql : `${rawSql};`;
+    return {
+      sql,
+      params: [...ctx.params]
+    };
+  }
+  compileUpdate(ast) {
+    const ctx = this.createCompilerContext();
+    const rawSql = this.compileUpdateAst(ast, ctx).trim();
+    const sql = rawSql.endsWith(";") ? rawSql : `${rawSql};`;
+    return {
+      sql,
+      params: [...ctx.params]
+    };
+  }
+  compileDelete(ast) {
+    const ctx = this.createCompilerContext();
+    const rawSql = this.compileDeleteAst(ast, ctx).trim();
+    const sql = rawSql.endsWith(";") ? rawSql : `${rawSql};`;
+    return {
+      sql,
+      params: [...ctx.params]
+    };
+  }
+  supportsReturning() {
+    return false;
+  }
+  /**
+   * Compiles a WHERE clause
+   * @param where - WHERE expression
+   * @param ctx - Compiler context
+   * @returns SQL WHERE clause or empty string
+   */
+  compileWhere(where, ctx) {
+    if (!where) return "";
+    return ` WHERE ${this.compileExpression(where, ctx)}`;
+  }
+  compileReturning(returning, ctx) {
+    if (!returning || returning.length === 0) return "";
+    throw new Error("RETURNING is not supported by this dialect.");
+  }
+  /**
+   * Generates subquery for EXISTS expressions
+   * Rule: Always forces SELECT 1, ignoring column list
+   * Maintains FROM, JOINs, WHERE, GROUP BY, ORDER BY, LIMIT/OFFSET
+   * Does not add ';' at the end
+   * @param ast - Query AST
+   * @param ctx - Compiler context
+   * @returns SQL for EXISTS subquery
+   */
+  compileSelectForExists(ast, ctx) {
+    const normalized = this.normalizeSelectAst(ast);
+    const full = this.compileSelectAst(normalized, ctx).trim().replace(/;$/, "");
+    if (normalized.setOps && normalized.setOps.length > 0) {
+      return `SELECT 1 FROM (${full}) AS _exists`;
+    }
+    const upper = full.toUpperCase();
+    const fromIndex = upper.indexOf(" FROM ");
+    if (fromIndex === -1) {
+      return full;
+    }
+    const tail = full.slice(fromIndex);
+    return `SELECT 1${tail}`;
+  }
+  /**
+   * Creates a new compiler context
+   * @returns Compiler context with parameter management
+   */
+  createCompilerContext() {
+    const params = [];
+    let counter = 0;
+    return {
+      params,
+      addParameter: (value) => {
+        counter += 1;
+        params.push(value);
+        return this.formatPlaceholder(counter);
+      }
+    };
+  }
+  /**
+   * Formats a parameter placeholder
+   * @param index - Parameter index
+   * @returns Formatted placeholder string
+   */
+  formatPlaceholder(index) {
+    return "?";
+  }
+  /**
+   * Whether the current dialect supports a given set operation.
+   * Override in concrete dialects to restrict support.
+   */
+  supportsSetOperation(kind) {
+    return true;
+  }
+  /**
+   * 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
+   */
+  validateSetOperations(ast, isOutermost = true) {
+    const hasSetOps = !!(ast.setOps && ast.setOps.length);
+    if (!isOutermost && (ast.orderBy || ast.limit !== void 0 || ast.offset !== void 0)) {
+      throw new Error("ORDER BY / LIMIT / OFFSET are only allowed on the outermost compound query.");
+    }
+    if (hasSetOps) {
+      for (const op of ast.setOps) {
+        if (!this.supportsSetOperation(op.operator)) {
+          throw new Error(`Set operation ${op.operator} is not supported by this dialect.`);
+        }
+        this.validateSetOperations(op.query, false);
+      }
+    }
+  }
+  /**
+   * 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
+   */
+  hoistCtes(ast) {
+    let hoisted = [];
+    const normalizedSetOps = ast.setOps?.map((op) => {
+      const { normalized: child, hoistedCtes: childHoisted } = this.hoistCtes(op.query);
+      const childCtes = child.ctes ?? [];
+      if (childCtes.length) {
+        hoisted = hoisted.concat(childCtes);
+      }
+      hoisted = hoisted.concat(childHoisted);
+      const queryWithoutCtes = childCtes.length ? { ...child, ctes: void 0 } : child;
+      return { ...op, query: queryWithoutCtes };
+    });
+    const normalized = normalizedSetOps ? { ...ast, setOps: normalizedSetOps } : ast;
+    return { normalized, hoistedCtes: hoisted };
+  }
+  /**
+   * Normalizes a SELECT AST before compilation (validation + CTE hoisting).
+   * @param ast - Query AST
+   * @returns Normalized query AST
+   */
+  normalizeSelectAst(ast) {
+    this.validateSetOperations(ast, true);
+    const { normalized, hoistedCtes } = this.hoistCtes(ast);
+    const combinedCtes = [...normalized.ctes ?? [], ...hoistedCtes];
+    return combinedCtes.length ? { ...normalized, ctes: combinedCtes } : normalized;
+  }
+  constructor(functionStrategy) {
+    this.expressionCompilers = /* @__PURE__ */ new Map();
+    this.operandCompilers = /* @__PURE__ */ new Map();
+    this.functionStrategy = functionStrategy || new StandardFunctionStrategy();
+    this.registerDefaultOperandCompilers();
+    this.registerDefaultExpressionCompilers();
+  }
+  /**
+   * Creates a new Dialect instance (for testing purposes)
+   * @param functionStrategy - Optional function strategy
+   * @returns New Dialect instance
+   */
+  static create(functionStrategy) {
+    class TestDialect extends _Dialect {
+      constructor() {
+        super(...arguments);
+        this.dialect = "sqlite";
+      }
+      quoteIdentifier(id) {
+        return `"${id}"`;
+      }
+      compileSelectAst() {
+        throw new Error("Not implemented");
+      }
+      compileInsertAst() {
+        throw new Error("Not implemented");
+      }
+      compileUpdateAst() {
+        throw new Error("Not implemented");
+      }
+      compileDeleteAst() {
+        throw new Error("Not implemented");
+      }
+    }
+    return new TestDialect(functionStrategy);
+  }
+  /**
+   * Registers an expression compiler for a specific node type
+   * @param type - Expression node type
+   * @param compiler - Compiler function
+   */
+  registerExpressionCompiler(type, compiler) {
+    this.expressionCompilers.set(type, compiler);
+  }
+  /**
+   * Registers an operand compiler for a specific node type
+   * @param type - Operand node type
+   * @param compiler - Compiler function
+   */
+  registerOperandCompiler(type, compiler) {
+    this.operandCompilers.set(type, compiler);
+  }
+  /**
+   * Compiles an expression node
+   * @param node - Expression node to compile
+   * @param ctx - Compiler context
+   * @returns Compiled SQL expression
+   */
+  compileExpression(node, ctx) {
+    const compiler = this.expressionCompilers.get(node.type);
+    if (!compiler) {
+      throw new Error(`Unsupported expression node type "${node.type}" for ${this.constructor.name}`);
+    }
+    return compiler(node, ctx);
+  }
+  /**
+   * Compiles an operand node
+   * @param node - Operand node to compile
+   * @param ctx - Compiler context
+   * @returns Compiled SQL operand
+   */
+  compileOperand(node, ctx) {
+    const compiler = this.operandCompilers.get(node.type);
+    if (!compiler) {
+      throw new Error(`Unsupported operand node type "${node.type}" for ${this.constructor.name}`);
+    }
+    return compiler(node, ctx);
+  }
+  registerDefaultExpressionCompilers() {
+    this.registerExpressionCompiler("BinaryExpression", (binary, ctx) => {
+      const left = this.compileOperand(binary.left, ctx);
+      const right = this.compileOperand(binary.right, ctx);
+      const base = `${left} ${binary.operator} ${right}`;
+      if (binary.escape) {
+        const escapeOperand = this.compileOperand(binary.escape, ctx);
+        return `${base} ESCAPE ${escapeOperand}`;
+      }
+      return base;
+    });
+    this.registerExpressionCompiler("LogicalExpression", (logical, ctx) => {
+      if (logical.operands.length === 0) return "";
+      const parts = logical.operands.map((op) => {
+        const compiled = this.compileExpression(op, ctx);
+        return op.type === "LogicalExpression" ? `(${compiled})` : compiled;
+      });
+      return parts.join(` ${logical.operator} `);
+    });
+    this.registerExpressionCompiler("NullExpression", (nullExpr, ctx) => {
+      const left = this.compileOperand(nullExpr.left, ctx);
+      return `${left} ${nullExpr.operator}`;
+    });
+    this.registerExpressionCompiler("InExpression", (inExpr, ctx) => {
+      const left = this.compileOperand(inExpr.left, ctx);
+      const values = inExpr.right.map((v) => this.compileOperand(v, ctx)).join(", ");
+      return `${left} ${inExpr.operator} (${values})`;
+    });
+    this.registerExpressionCompiler("ExistsExpression", (existsExpr, ctx) => {
+      const subquerySql = this.compileSelectForExists(existsExpr.subquery, ctx);
+      return `${existsExpr.operator} (${subquerySql})`;
+    });
+    this.registerExpressionCompiler("BetweenExpression", (betweenExpr, ctx) => {
+      const left = this.compileOperand(betweenExpr.left, ctx);
+      const lower = this.compileOperand(betweenExpr.lower, ctx);
+      const upper = this.compileOperand(betweenExpr.upper, ctx);
+      return `${left} ${betweenExpr.operator} ${lower} AND ${upper}`;
+    });
+  }
+  registerDefaultOperandCompilers() {
+    this.registerOperandCompiler("Literal", (literal, ctx) => ctx.addParameter(literal.value));
+    this.registerOperandCompiler("Column", (column, _ctx) => {
+      return `${this.quoteIdentifier(column.table)}.${this.quoteIdentifier(column.name)}`;
+    });
+    this.registerOperandCompiler(
+      "Function",
+      (fnNode, ctx) => this.compileFunctionOperand(fnNode, ctx)
+    );
+    this.registerOperandCompiler("JsonPath", (path, _ctx) => this.compileJsonPath(path));
+    this.registerOperandCompiler("ScalarSubquery", (node, ctx) => {
+      const sql = this.compileSelectAst(node.query, ctx).trim().replace(/;$/, "");
+      return `(${sql})`;
+    });
+    this.registerOperandCompiler("CaseExpression", (node, ctx) => {
+      const parts = ["CASE"];
+      for (const { when, then } of node.conditions) {
+        parts.push(`WHEN ${this.compileExpression(when, ctx)} THEN ${this.compileOperand(then, ctx)}`);
+      }
+      if (node.else) {
+        parts.push(`ELSE ${this.compileOperand(node.else, ctx)}`);
+      }
+      parts.push("END");
+      return parts.join(" ");
+    });
+    this.registerOperandCompiler("WindowFunction", (node, ctx) => {
+      let result = `${node.name}(`;
+      if (node.args.length > 0) {
+        result += node.args.map((arg) => this.compileOperand(arg, ctx)).join(", ");
+      }
+      result += ") OVER (";
+      const parts = [];
+      if (node.partitionBy && node.partitionBy.length > 0) {
+        const partitionClause = "PARTITION BY " + node.partitionBy.map(
+          (col) => `${this.quoteIdentifier(col.table)}.${this.quoteIdentifier(col.name)}`
+        ).join(", ");
+        parts.push(partitionClause);
+      }
+      if (node.orderBy && node.orderBy.length > 0) {
+        const orderClause = "ORDER BY " + node.orderBy.map(
+          (o) => `${this.quoteIdentifier(o.column.table)}.${this.quoteIdentifier(o.column.name)} ${o.direction}`
+        ).join(", ");
+        parts.push(orderClause);
+      }
+      result += parts.join(" ");
+      result += ")";
+      return result;
+    });
+  }
+  // Default fallback, should be overridden by dialects if supported
+  compileJsonPath(node) {
+    throw new Error("JSON Path not supported by this dialect");
+  }
+  /**
+   * Compiles a function operand, using the dialect's function strategy.
+   */
+  compileFunctionOperand(fnNode, ctx) {
+    const compiledArgs = fnNode.args.map((arg) => this.compileOperand(arg, ctx));
+    const renderer = this.functionStrategy.getRenderer(fnNode.name);
+    if (renderer) {
+      return renderer({ node: fnNode, compiledArgs });
+    }
+    return `${fnNode.name}(${compiledArgs.join(", ")})`;
+  }
+};
+
+// src/core/dialect/base/function-table-formatter.ts
+var FunctionTableFormatter = class {
+  /**
+   * Formats a function table node into SQL syntax.
+   * @param fn - The function table node containing schema, name, args, and aliases.
+   * @param ctx - Optional compiler context for operand compilation.
+   * @param dialect - The dialect instance for compiling operands.
+   * @returns SQL function table expression (e.g., "LATERAL schema.func(args) WITH ORDINALITY AS alias(col1, col2)").
+   */
+  static format(fn, ctx, dialect) {
+    const schemaPart = this.formatSchema(fn, dialect);
+    const args = this.formatArgs(fn, ctx, dialect);
+    const base = this.formatBase(fn, schemaPart, args, dialect);
+    const lateral = this.formatLateral(fn);
+    const alias = this.formatAlias(fn, dialect);
+    const colAliases = this.formatColumnAliases(fn, dialect);
+    return `${lateral}${base}${alias}${colAliases}`;
+  }
+  /**
+   * Formats the schema prefix for the function name.
+   * @param fn - The function table node.
+   * @param dialect - The dialect instance for quoting identifiers.
+   * @returns Schema prefix (e.g., "schema.") or empty string.
+   * @internal
+   */
+  static formatSchema(fn, dialect) {
+    if (!fn.schema) return "";
+    const quoted = dialect ? dialect.quoteIdentifier(fn.schema) : fn.schema;
+    return `${quoted}.`;
+  }
+  /**
+   * Formats function arguments into SQL syntax.
+   * @param fn - The function table node containing arguments.
+   * @param ctx - Optional compiler context for operand compilation.
+   * @param dialect - The dialect instance for compiling operands.
+   * @returns Comma-separated function arguments.
+   * @internal
+   */
+  static formatArgs(fn, ctx, dialect) {
+    return (fn.args || []).map((a) => {
+      if (ctx && dialect) {
+        return dialect.compileOperand(a, ctx);
+      }
+      return String(a);
+    }).join(", ");
+  }
+  /**
+   * Formats the base function call with WITH ORDINALITY if present.
+   * @param fn - The function table node.
+   * @param schemaPart - Formatted schema prefix.
+   * @param args - Formatted function arguments.
+   * @param dialect - The dialect instance for quoting identifiers.
+   * @returns Base function call expression (e.g., "schema.func(args) WITH ORDINALITY").
+   * @internal
+   */
+  static formatBase(fn, schemaPart, args, dialect) {
+    const ordinality = fn.withOrdinality ? " WITH ORDINALITY" : "";
+    const quoted = dialect ? dialect.quoteIdentifier(fn.name) : fn.name;
+    return `${schemaPart}${quoted}(${args})${ordinality}`;
+  }
+  /**
+   * Formats the LATERAL keyword if present.
+   * @param fn - The function table node.
+   * @returns "LATERAL " or empty string.
+   * @internal
+   */
+  static formatLateral(fn) {
+    return fn.lateral ? "LATERAL " : "";
+  }
+  /**
+   * Formats the table alias for the function table.
+   * @param fn - The function table node.
+   * @param dialect - The dialect instance for quoting identifiers.
+   * @returns " AS alias" or empty string.
+   * @internal
+   */
+  static formatAlias(fn, dialect) {
+    if (!fn.alias) return "";
+    const quoted = dialect ? dialect.quoteIdentifier(fn.alias) : fn.alias;
+    return ` AS ${quoted}`;
+  }
+  /**
+   * Formats column aliases for the function table result columns.
+   * @param fn - The function table node containing column aliases.
+   * @param dialect - The dialect instance for quoting identifiers.
+   * @returns "(col1, col2, ...)" or empty string.
+   * @internal
+   */
+  static formatColumnAliases(fn, dialect) {
+    if (!fn.columnAliases || !fn.columnAliases.length) return "";
+    const aliases = fn.columnAliases.map((col) => dialect ? dialect.quoteIdentifier(col) : col).join(", ");
+    return `(${aliases})`;
+  }
+};
+
+// src/core/dialect/base/pagination-strategy.ts
+var StandardLimitOffsetPagination = class {
+  /**
+   * Compiles LIMIT/OFFSET pagination clause.
+   * @param limit - The maximum number of rows to return.
+   * @param offset - The number of rows to skip.
+   * @returns SQL pagination clause with LIMIT and/or OFFSET.
+   */
+  compilePagination(limit, offset) {
+    const parts = [];
+    if (limit !== void 0) parts.push(`LIMIT ${limit}`);
+    if (offset !== void 0) parts.push(`OFFSET ${offset}`);
+    return parts.length ? ` ${parts.join(" ")}` : "";
+  }
+};
+
+// src/core/dialect/base/cte-compiler.ts
+var CteCompiler = class {
+  /**
+   * Compiles CTEs (WITH clauses) including recursive CTEs.
+   * @param ast - The SELECT query AST containing CTE definitions.
+   * @param ctx - The compiler context for expression compilation.
+   * @param quoteIdentifier - Function to quote identifiers according to dialect rules.
+   * @param compileSelectAst - Function to recursively compile SELECT query ASTs.
+   * @param normalizeSelectAst - Function to normalize SELECT query ASTs before compilation.
+   * @param stripTrailingSemicolon - Function to remove trailing semicolons from SQL.
+   * @returns SQL WITH clause string (e.g., "WITH cte_name AS (...) ") or empty string if no CTEs.
+   */
+  static compileCtes(ast, ctx, quoteIdentifier, compileSelectAst, normalizeSelectAst, stripTrailingSemicolon) {
+    if (!ast.ctes || ast.ctes.length === 0) return "";
+    const hasRecursive = ast.ctes.some((cte) => cte.recursive);
+    const prefix = hasRecursive ? "WITH RECURSIVE " : "WITH ";
+    const cteDefs = ast.ctes.map((cte) => {
+      const name = quoteIdentifier(cte.name);
+      const cols = cte.columns && cte.columns.length ? `(${cte.columns.map((c) => quoteIdentifier(c)).join(", ")})` : "";
+      const query = stripTrailingSemicolon(compileSelectAst(normalizeSelectAst(cte.query), ctx));
+      return `${name}${cols} AS (${query})`;
+    }).join(", ");
+    return `${prefix}${cteDefs} `;
+  }
+};
+
+// src/core/dialect/base/returning-strategy.ts
+var NoReturningStrategy = class {
+  /**
+   * Throws an error as RETURNING is not supported.
+   * @param returning - Columns to return (causes error if non-empty).
+   * @param _ctx - Compiler context (unused).
+   * @throws Error indicating RETURNING is not supported.
+   */
+  compileReturning(returning, _ctx) {
+    if (!returning || returning.length === 0) return "";
+    throw new Error("RETURNING is not supported by this dialect.");
+  }
+  /**
+   * Formats column names for RETURNING clause.
+   * @param returning - Columns to format.
+   * @param quoteIdentifier - Function to quote identifiers according to dialect rules.
+   * @returns Simple comma-separated column names.
+   */
+  formatReturningColumns(returning, quoteIdentifier) {
+    return returning.map((column) => {
+      const tablePart = column.table ? `${quoteIdentifier(column.table)}.` : "";
+      const aliasPart = column.alias ? ` AS ${quoteIdentifier(column.alias)}` : "";
+      return `${tablePart}${quoteIdentifier(column.name)}${aliasPart}`;
+    }).join(", ");
+  }
+};
+
+// src/core/dialect/base/join-compiler.ts
+var JoinCompiler = class {
+  /**
+   * Compiles all JOIN clauses from a SELECT query AST.
+   * @param ast - The SELECT query AST containing join definitions.
+   * @param ctx - The compiler context for expression compilation.
+   * @param compileFrom - Function to compile table sources (tables or subqueries).
+   * @param compileExpression - Function to compile join condition expressions.
+   * @returns SQL JOIN clauses (e.g., " LEFT JOIN table ON condition") or empty string if no joins.
+   */
+  static compileJoins(ast, ctx, compileFrom, compileExpression) {
+    if (!ast.joins || ast.joins.length === 0) return "";
+    const parts = ast.joins.map((j) => {
+      const table = compileFrom(j.table, ctx);
+      const cond = compileExpression(j.condition, ctx);
+      return `${j.kind} JOIN ${table} ON ${cond}`;
+    });
+    return ` ${parts.join(" ")}`;
+  }
+};
+
+// src/core/dialect/base/groupby-compiler.ts
+var GroupByCompiler = class {
+  /**
+   * Compiles GROUP BY clause from a SELECT query AST.
+   * @param ast - The SELECT query AST containing grouping columns.
+   * @param quoteIdentifier - Function to quote identifiers according to dialect rules.
+   * @returns SQL GROUP BY clause (e.g., " GROUP BY table.col1, table.col2") or empty string if no grouping.
+   */
+  static compileGroupBy(ast, quoteIdentifier) {
+    if (!ast.groupBy || ast.groupBy.length === 0) return "";
+    const cols = ast.groupBy.map((c) => `${quoteIdentifier(c.table)}.${quoteIdentifier(c.name)}`).join(", ");
+    return ` GROUP BY ${cols}`;
+  }
+};
+
+// src/core/dialect/base/orderby-compiler.ts
+var OrderByCompiler = class {
+  /**
+   * Compiles ORDER BY clause from a SELECT query AST.
+   * @param ast - The SELECT query AST containing sort specifications.
+   * @param quoteIdentifier - Function to quote identifiers according to dialect rules.
+   * @returns SQL ORDER BY clause (e.g., " ORDER BY table.col1 ASC, table.col2 DESC") or empty string if no ordering.
+   */
+  static compileOrderBy(ast, quoteIdentifier) {
+    if (!ast.orderBy || ast.orderBy.length === 0) return "";
+    const parts = ast.orderBy.map((o) => `${quoteIdentifier(o.column.table)}.${quoteIdentifier(o.column.name)} ${o.direction}`).join(", ");
+    return ` ORDER BY ${parts}`;
+  }
+};
+
+// src/core/dialect/base/sql-dialect.ts
+var SqlDialectBase = class extends Dialect {
+  constructor() {
+    super(...arguments);
+    this.paginationStrategy = new StandardLimitOffsetPagination();
+    this.returningStrategy = new NoReturningStrategy();
+  }
+  compileSelectAst(ast, ctx) {
+    const hasSetOps = !!(ast.setOps && ast.setOps.length);
+    const ctes = CteCompiler.compileCtes(
+      ast,
+      ctx,
+      this.quoteIdentifier.bind(this),
+      this.compileSelectAst.bind(this),
+      this.normalizeSelectAst?.bind(this) ?? ((a) => a),
+      this.stripTrailingSemicolon.bind(this)
+    );
+    const baseAst = hasSetOps ? { ...ast, setOps: void 0, orderBy: void 0, limit: void 0, offset: void 0 } : ast;
+    const baseSelect = this.compileSelectCore(baseAst, ctx);
+    if (!hasSetOps) {
+      return `${ctes}${baseSelect}`;
+    }
+    return this.compileSelectWithSetOps(ast, baseSelect, ctes, ctx);
+  }
+  compileSelectWithSetOps(ast, baseSelect, ctes, ctx) {
+    const compound = ast.setOps.map((op) => `${op.operator} ${this.wrapSetOperand(this.compileSelectAst(op.query, ctx))}`).join(" ");
+    const orderBy = OrderByCompiler.compileOrderBy(ast, this.quoteIdentifier.bind(this));
+    const pagination = this.paginationStrategy.compilePagination(ast.limit, ast.offset);
+    const combined = `${this.wrapSetOperand(baseSelect)} ${compound}`;
+    return `${ctes}${combined}${orderBy}${pagination}`;
+  }
+  compileInsertAst(ast, ctx) {
+    const table = this.compileTableName(ast.into);
+    const columnList = this.compileInsertColumnList(ast.columns);
+    const values = this.compileInsertValues(ast.values, ctx);
+    const returning = this.compileReturning(ast.returning, ctx);
+    return `INSERT INTO ${table} (${columnList}) VALUES ${values}${returning}`;
+  }
+  compileReturning(returning, ctx) {
+    return this.returningStrategy.compileReturning(returning, ctx);
+  }
+  compileInsertColumnList(columns) {
+    return columns.map((column) => `${this.quoteIdentifier(column.table)}.${this.quoteIdentifier(column.name)}`).join(", ");
+  }
+  compileInsertValues(values, ctx) {
+    return values.map((row) => `(${row.map((value) => this.compileOperand(value, ctx)).join(", ")})`).join(", ");
+  }
+  compileSelectCore(ast, ctx) {
+    const columns = this.compileSelectColumns(ast, ctx);
+    const from = this.compileFrom(ast.from, ctx);
+    const joins = JoinCompiler.compileJoins(ast, ctx, this.compileFrom.bind(this), this.compileExpression.bind(this));
+    const whereClause = this.compileWhere(ast.where, ctx);
+    const groupBy = GroupByCompiler.compileGroupBy(ast, this.quoteIdentifier.bind(this));
+    const having = this.compileHaving(ast, ctx);
+    const orderBy = OrderByCompiler.compileOrderBy(ast, this.quoteIdentifier.bind(this));
+    const pagination = this.paginationStrategy.compilePagination(ast.limit, ast.offset);
+    return `SELECT ${this.compileDistinct(ast)}${columns} FROM ${from}${joins}${whereClause}${groupBy}${having}${orderBy}${pagination}`;
+  }
+  compileUpdateAst(ast, ctx) {
+    const table = this.compileTableName(ast.table);
+    const assignments = this.compileUpdateAssignments(ast.set, ctx);
+    const whereClause = this.compileWhere(ast.where, ctx);
+    const returning = this.compileReturning(ast.returning, ctx);
+    return `UPDATE ${table} SET ${assignments}${whereClause}${returning}`;
+  }
+  compileUpdateAssignments(assignments, ctx) {
+    return assignments.map((assignment) => {
+      const col = assignment.column;
+      const target = `${this.quoteIdentifier(col.table)}.${this.quoteIdentifier(col.name)}`;
+      const value = this.compileOperand(assignment.value, ctx);
+      return `${target} = ${value}`;
+    }).join(", ");
+  }
+  compileDeleteAst(ast, ctx) {
+    const table = this.compileTableName(ast.from);
+    const whereClause = this.compileWhere(ast.where, ctx);
+    const returning = this.compileReturning(ast.returning, ctx);
+    return `DELETE FROM ${table}${whereClause}${returning}`;
+  }
+  formatReturningColumns(returning) {
+    return this.returningStrategy.formatReturningColumns(returning, this.quoteIdentifier.bind(this));
+  }
+  compileDistinct(ast) {
+    return ast.distinct ? "DISTINCT " : "";
+  }
+  compileSelectColumns(ast, ctx) {
+    return ast.columns.map((c) => {
+      const expr = this.compileOperand(c, ctx);
+      if (c.alias) {
+        if (c.alias.includes("(")) return c.alias;
+        return `${expr} AS ${this.quoteIdentifier(c.alias)}`;
+      }
+      return expr;
+    }).join(", ");
+  }
+  compileFrom(ast, ctx) {
+    const tableSource = ast;
+    if (tableSource.type === "FunctionTable") {
+      return this.compileFunctionTable(tableSource, ctx);
+    }
+    return this.compileTableSource(tableSource);
+  }
+  compileFunctionTable(fn, ctx) {
+    return FunctionTableFormatter.format(fn, ctx, this);
+  }
+  compileTableSource(table) {
+    const base = this.compileTableName(table);
+    return table.alias ? `${base} AS ${this.quoteIdentifier(table.alias)}` : base;
+  }
+  compileTableName(table) {
+    if (table.schema) {
+      return `${this.quoteIdentifier(table.schema)}.${this.quoteIdentifier(table.name)}`;
+    }
+    return this.quoteIdentifier(table.name);
+  }
+  compileHaving(ast, ctx) {
+    if (!ast.having) return "";
+    return ` HAVING ${this.compileExpression(ast.having, ctx)}`;
+  }
+  stripTrailingSemicolon(sql) {
+    return sql.trim().replace(/;$/, "");
+  }
+  wrapSetOperand(sql) {
+    const trimmed = this.stripTrailingSemicolon(sql);
+    return `(${trimmed})`;
+  }
+};
+
+// src/core/dialect/postgres/functions.ts
+var PostgresFunctionStrategy = class extends StandardFunctionStrategy {
+  constructor() {
+    super();
+    this.registerOverrides();
+  }
+  registerOverrides() {
+    this.add("UTC_NOW", () => `(NOW() AT TIME ZONE 'UTC')`);
+    this.add("UNIX_TIMESTAMP", () => `EXTRACT(EPOCH FROM NOW())::INTEGER`);
+    this.add("FROM_UNIXTIME", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("FROM_UNIXTIME expects 1 argument");
+      return `to_timestamp(${compiledArgs[0]})`;
+    });
+    this.add("EXTRACT", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("EXTRACT expects 2 arguments (part, date)");
+      const [part, date] = compiledArgs;
+      const partClean = part.replace(/['"]/g, "");
+      return `EXTRACT(${partClean} FROM ${date})`;
+    });
+    this.add("YEAR", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("YEAR expects 1 argument");
+      return `EXTRACT(YEAR FROM ${compiledArgs[0]})`;
+    });
+    this.add("MONTH", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("MONTH expects 1 argument");
+      return `EXTRACT(MONTH FROM ${compiledArgs[0]})`;
+    });
+    this.add("DAY", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("DAY expects 1 argument");
+      return `EXTRACT(DAY FROM ${compiledArgs[0]})`;
+    });
+    this.add("DATE_ADD", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 3) throw new Error("DATE_ADD expects 3 arguments (date, interval, unit)");
+      const [date, interval] = compiledArgs;
+      const unitArg = node.args[2];
+      const unitClean = String(unitArg.value).replace(/['"]/g, "").toLowerCase();
+      return `(${date} + (${interval} || ' ${unitClean}')::INTERVAL)`;
+    });
+    this.add("DATE_SUB", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 3) throw new Error("DATE_SUB expects 3 arguments (date, interval, unit)");
+      const [date, interval] = compiledArgs;
+      const unitArg = node.args[2];
+      const unitClean = String(unitArg.value).replace(/['"]/g, "").toLowerCase();
+      return `(${date} - (${interval} || ' ${unitClean}')::INTERVAL)`;
+    });
+    this.add("DATE_DIFF", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("DATE_DIFF expects 2 arguments");
+      const [date1, date2] = compiledArgs;
+      return `(${date1}::DATE - ${date2}::DATE)`;
+    });
+    this.add("DATE_FORMAT", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("DATE_FORMAT expects 2 arguments");
+      const [date, format] = compiledArgs;
+      return `TO_CHAR(${date}, ${format})`;
+    });
+    this.add("END_OF_MONTH", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("END_OF_MONTH expects 1 argument");
+      return `(date_trunc('month', ${compiledArgs[0]}) + interval '1 month' - interval '1 day')::DATE`;
+    });
+    this.add("DAY_OF_WEEK", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("DAY_OF_WEEK expects 1 argument");
+      return `EXTRACT(DOW FROM ${compiledArgs[0]})`;
+    });
+    this.add("WEEK_OF_YEAR", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("WEEK_OF_YEAR expects 1 argument");
+      return `EXTRACT(WEEK FROM ${compiledArgs[0]})`;
+    });
+    this.add("DATE_TRUNC", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("DATE_TRUNC expects 2 arguments (part, date)");
+      const [, date] = compiledArgs;
+      const partArg = node.args[0];
+      const partClean = String(partArg.value).replace(/['"]/g, "").toLowerCase();
+      return `DATE_TRUNC('${partClean}', ${date})`;
+    });
+  }
+};
+
+// src/core/dialect/postgres/index.ts
+var PostgresDialect = class extends SqlDialectBase {
+  /**
+   * Creates a new PostgresDialect instance
+   */
+  constructor() {
+    super(new PostgresFunctionStrategy());
+    this.dialect = "postgres";
+  }
+  /**
+   * Quotes an identifier using PostgreSQL double-quote syntax
+   * @param id - Identifier to quote
+   * @returns Quoted identifier
+   */
+  quoteIdentifier(id) {
+    return `"${id}"`;
+  }
+  /**
+   * Compiles JSON path expression using PostgreSQL syntax
+   * @param node - JSON path node
+   * @returns PostgreSQL JSON path expression
+   */
+  compileJsonPath(node) {
+    const col = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
+    return `${col}->>'${node.path}'`;
+  }
+  compileReturning(returning, ctx) {
+    if (!returning || returning.length === 0) return "";
+    const columns = this.formatReturningColumns(returning);
+    return ` RETURNING ${columns}`;
+  }
+  supportsReturning() {
+    return true;
+  }
+};
+
+// src/core/dialect/mysql/functions.ts
+var MysqlFunctionStrategy = class extends StandardFunctionStrategy {
+  constructor() {
+    super();
+    this.registerOverrides();
+  }
+  registerOverrides() {
+    this.add("NOW", () => `NOW()`);
+    this.add("CURRENT_DATE", () => `CURDATE()`);
+    this.add("CURRENT_TIME", () => `CURTIME()`);
+    this.add("UTC_NOW", () => `UTC_TIMESTAMP()`);
+    this.add("EXTRACT", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("EXTRACT expects 2 arguments (part, date)");
+      const [part, date] = compiledArgs;
+      const partClean = part.replace(/['"]/g, "");
+      return `EXTRACT(${partClean} FROM ${date})`;
+    });
+    this.add("YEAR", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("YEAR expects 1 argument");
+      return `YEAR(${compiledArgs[0]})`;
+    });
+    this.add("MONTH", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("MONTH expects 1 argument");
+      return `MONTH(${compiledArgs[0]})`;
+    });
+    this.add("DAY", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("DAY expects 1 argument");
+      return `DAY(${compiledArgs[0]})`;
+    });
+    this.add("DATE_ADD", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 3) throw new Error("DATE_ADD expects 3 arguments (date, interval, unit)");
+      const [date, interval] = compiledArgs;
+      const unitArg = node.args[2];
+      const unitClean = String(unitArg.value).replace(/['"]/g, "").toUpperCase();
+      return `DATE_ADD(${date}, INTERVAL ${interval} ${unitClean})`;
+    });
+    this.add("DATE_SUB", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 3) throw new Error("DATE_SUB expects 3 arguments (date, interval, unit)");
+      const [date, interval] = compiledArgs;
+      const unitArg = node.args[2];
+      const unitClean = String(unitArg.value).replace(/['"]/g, "").toUpperCase();
+      return `DATE_SUB(${date}, INTERVAL ${interval} ${unitClean})`;
+    });
+    this.add("DATE_DIFF", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("DATE_DIFF expects 2 arguments");
+      const [date1, date2] = compiledArgs;
+      return `DATEDIFF(${date1}, ${date2})`;
+    });
+    this.add("DATE_FORMAT", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("DATE_FORMAT expects 2 arguments");
+      const [date, format] = compiledArgs;
+      return `DATE_FORMAT(${date}, ${format})`;
+    });
+    this.add("END_OF_MONTH", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("END_OF_MONTH expects 1 argument");
+      return `LAST_DAY(${compiledArgs[0]})`;
+    });
+    this.add("DAY_OF_WEEK", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("DAY_OF_WEEK expects 1 argument");
+      return `DAYOFWEEK(${compiledArgs[0]})`;
+    });
+    this.add("WEEK_OF_YEAR", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("WEEK_OF_YEAR expects 1 argument");
+      return `WEEKOFYEAR(${compiledArgs[0]})`;
+    });
+    this.add("DATE_TRUNC", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("DATE_TRUNC expects 2 arguments (part, date)");
+      const [, date] = compiledArgs;
+      const partArg = node.args[0];
+      const partClean = String(partArg.value).replace(/['"]/g, "").toLowerCase();
+      if (partClean === "year") {
+        return `DATE_FORMAT(${date}, '%Y-01-01')`;
+      } else if (partClean === "month") {
+        return `DATE_FORMAT(${date}, '%Y-%m-01')`;
+      } else if (partClean === "day") {
+        return `DATE(${date})`;
+      }
+      return `DATE(${date})`;
+    });
+  }
+};
+
+// src/core/dialect/mysql/index.ts
+var MySqlDialect = class extends SqlDialectBase {
+  /**
+   * Creates a new MySqlDialect instance
+   */
+  constructor() {
+    super(new MysqlFunctionStrategy());
+    this.dialect = "mysql";
+  }
+  /**
+   * Quotes an identifier using MySQL backtick syntax
+   * @param id - Identifier to quote
+   * @returns Quoted identifier
+   */
+  quoteIdentifier(id) {
+    return `\`${id}\``;
+  }
+  /**
+   * Compiles JSON path expression using MySQL syntax
+   * @param node - JSON path node
+   * @returns MySQL JSON path expression
+   */
+  compileJsonPath(node) {
+    const col = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
+    return `${col}->'${node.path}'`;
+  }
+};
+
+// src/core/dialect/sqlite/functions.ts
+var SqliteFunctionStrategy = class extends StandardFunctionStrategy {
+  constructor() {
+    super();
+    this.registerOverrides();
+  }
+  registerOverrides() {
+    this.add("NOW", () => `datetime('now', 'localtime')`);
+    this.add("CURRENT_DATE", () => `date('now', 'localtime')`);
+    this.add("CURRENT_TIME", () => `time('now', 'localtime')`);
+    this.add("UTC_NOW", () => `datetime('now')`);
+    this.add("EXTRACT", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("EXTRACT expects 2 arguments (part, date)");
+      const [part, date] = compiledArgs;
+      const partUpper = part.replace(/['"]/g, "").toUpperCase();
+      const formatMap = {
+        "YEAR": "%Y",
+        "MONTH": "%m",
+        "DAY": "%d",
+        "HOUR": "%H",
+        "MINUTE": "%M",
+        "SECOND": "%S",
+        "DOW": "%w",
+        "WEEK": "%W"
+      };
+      const format = formatMap[partUpper] || "%Y";
+      return `CAST(strftime('${format}', ${date}) AS INTEGER)`;
+    });
+    this.add("YEAR", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("YEAR expects 1 argument");
+      return `CAST(strftime('%Y', ${compiledArgs[0]}) AS INTEGER)`;
+    });
+    this.add("MONTH", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("MONTH expects 1 argument");
+      return `CAST(strftime('%m', ${compiledArgs[0]}) AS INTEGER)`;
+    });
+    this.add("DAY", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("DAY expects 1 argument");
+      return `CAST(strftime('%d', ${compiledArgs[0]}) AS INTEGER)`;
+    });
+    this.add("DATE_ADD", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 3) throw new Error("DATE_ADD expects 3 arguments (date, interval, unit)");
+      const [date, interval] = compiledArgs;
+      const unitArg = node.args[2];
+      const unitClean = String(unitArg.value).replace(/['"]/g, "").toLowerCase();
+      return `datetime(${date}, '+' || ${interval} || ' ${unitClean}')`;
+    });
+    this.add("DATE_SUB", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 3) throw new Error("DATE_SUB expects 3 arguments (date, interval, unit)");
+      const [date, interval] = compiledArgs;
+      const unitArg = node.args[2];
+      const unitClean = String(unitArg.value).replace(/['"]/g, "").toLowerCase();
+      return `datetime(${date}, '-' || ${interval} || ' ${unitClean}')`;
+    });
+    this.add("DATE_DIFF", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("DATE_DIFF expects 2 arguments");
+      const [date1, date2] = compiledArgs;
+      return `CAST(julianday(${date1}) - julianday(${date2}) AS INTEGER)`;
+    });
+    this.add("DATE_FORMAT", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("DATE_FORMAT expects 2 arguments");
+      const [date, format] = compiledArgs;
+      return `strftime(${format}, ${date})`;
+    });
+    this.add("UNIX_TIMESTAMP", () => `CAST(strftime('%s', 'now') AS INTEGER)`);
+    this.add("FROM_UNIXTIME", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("FROM_UNIXTIME expects 1 argument");
+      return `datetime(${compiledArgs[0]}, 'unixepoch')`;
+    });
+    this.add("END_OF_MONTH", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("END_OF_MONTH expects 1 argument");
+      return `date(${compiledArgs[0]}, 'start of month', '+1 month', '-1 day')`;
+    });
+    this.add("DAY_OF_WEEK", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("DAY_OF_WEEK expects 1 argument");
+      return `CAST(strftime('%w', ${compiledArgs[0]}) AS INTEGER)`;
+    });
+    this.add("WEEK_OF_YEAR", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("WEEK_OF_YEAR expects 1 argument");
+      return `CAST(strftime('%W', ${compiledArgs[0]}) AS INTEGER)`;
+    });
+    this.add("DATE_TRUNC", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("DATE_TRUNC expects 2 arguments (part, date)");
+      const [, date] = compiledArgs;
+      const partArg = node.args[0];
+      const partClean = String(partArg.value).replace(/['"]/g, "").toLowerCase();
+      if (partClean === "year") {
+        return `date(${date}, 'start of year')`;
+      } else if (partClean === "month") {
+        return `date(${date}, 'start of month')`;
+      } else if (partClean === "day") {
+        return `date(${date})`;
+      }
+      return `date(${date}, 'start of ${partClean}')`;
+    });
+  }
+};
+
+// src/core/dialect/sqlite/index.ts
+var SqliteDialect = class extends SqlDialectBase {
+  /**
+   * Creates a new SqliteDialect instance
+   */
+  constructor() {
+    super(new SqliteFunctionStrategy());
+    this.dialect = "sqlite";
+  }
+  /**
+   * Quotes an identifier using SQLite double-quote syntax
+   * @param id - Identifier to quote
+   * @returns Quoted identifier
+   */
+  quoteIdentifier(id) {
+    return `"${id}"`;
+  }
+  /**
+   * Compiles JSON path expression using SQLite syntax
+   * @param node - JSON path node
+   * @returns SQLite JSON path expression
+   */
+  compileJsonPath(node) {
+    const col = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
+    return `json_extract(${col}, '${node.path}')`;
+  }
+  compileReturning(returning, ctx) {
+    if (!returning || returning.length === 0) return "";
+    const columns = this.formatReturningColumns(returning);
+    return ` RETURNING ${columns}`;
+  }
+  supportsReturning() {
+    return true;
+  }
+};
+
+// src/core/dialect/mssql/functions.ts
+var MssqlFunctionStrategy = class extends StandardFunctionStrategy {
+  constructor() {
+    super();
+    this.registerOverrides();
+  }
+  registerOverrides() {
+    this.add("NOW", () => `GETDATE()`);
+    this.add("CURRENT_DATE", () => `CAST(GETDATE() AS DATE)`);
+    this.add("CURRENT_TIME", () => `CAST(GETDATE() AS TIME)`);
+    this.add("UTC_NOW", () => `GETUTCDATE()`);
+    this.add("EXTRACT", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("EXTRACT expects 2 arguments (part, date)");
+      const [part, date] = compiledArgs;
+      const partClean = part.replace(/['"]/g, "").toLowerCase();
+      return `DATEPART(${partClean}, ${date})`;
+    });
+    this.add("YEAR", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("YEAR expects 1 argument");
+      return `YEAR(${compiledArgs[0]})`;
+    });
+    this.add("MONTH", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("MONTH expects 1 argument");
+      return `MONTH(${compiledArgs[0]})`;
+    });
+    this.add("DAY", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("DAY expects 1 argument");
+      return `DAY(${compiledArgs[0]})`;
+    });
+    this.add("DATE_ADD", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 3) throw new Error("DATE_ADD expects 3 arguments (date, interval, unit)");
+      const [date, interval] = compiledArgs;
+      const unitArg = node.args[2];
+      const unitClean = String(unitArg.value).replace(/['"]/g, "").toLowerCase();
+      return `DATEADD(${unitClean}, ${interval}, ${date})`;
+    });
+    this.add("DATE_SUB", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 3) throw new Error("DATE_SUB expects 3 arguments (date, interval, unit)");
+      const [date, interval] = compiledArgs;
+      const unitArg = node.args[2];
+      const unitClean = String(unitArg.value).replace(/['"]/g, "").toLowerCase();
+      return `DATEADD(${unitClean}, -${interval}, ${date})`;
+    });
+    this.add("DATE_DIFF", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("DATE_DIFF expects 2 arguments");
+      const [date1, date2] = compiledArgs;
+      return `DATEDIFF(day, ${date2}, ${date1})`;
+    });
+    this.add("DATE_FORMAT", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("DATE_FORMAT expects 2 arguments");
+      const [date, format] = compiledArgs;
+      return `FORMAT(${date}, ${format})`;
+    });
+    this.add("UNIX_TIMESTAMP", () => `DATEDIFF(SECOND, '1970-01-01', GETUTCDATE())`);
+    this.add("FROM_UNIXTIME", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("FROM_UNIXTIME expects 1 argument");
+      return `DATEADD(SECOND, ${compiledArgs[0]}, '1970-01-01')`;
+    });
+    this.add("END_OF_MONTH", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("END_OF_MONTH expects 1 argument");
+      return `EOMONTH(${compiledArgs[0]})`;
+    });
+    this.add("DAY_OF_WEEK", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("DAY_OF_WEEK expects 1 argument");
+      return `DATEPART(dw, ${compiledArgs[0]})`;
+    });
+    this.add("WEEK_OF_YEAR", ({ compiledArgs }) => {
+      if (compiledArgs.length !== 1) throw new Error("WEEK_OF_YEAR expects 1 argument");
+      return `DATEPART(wk, ${compiledArgs[0]})`;
+    });
+    this.add("DATE_TRUNC", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 2) throw new Error("DATE_TRUNC expects 2 arguments (part, date)");
+      const [, date] = compiledArgs;
+      const partArg = node.args[0];
+      const partClean = String(partArg.value).replace(/['"]/g, "").toLowerCase();
+      return `DATETRUNC(${partClean}, ${date})`;
+    });
+  }
+};
+
+// src/core/dialect/mssql/index.ts
+var SqlServerDialect = class extends Dialect {
+  /**
+   * Creates a new SqlServerDialect instance
+   */
+  constructor() {
+    super(new MssqlFunctionStrategy());
+    this.dialect = "mssql";
+  }
+  /**
+   * Quotes an identifier using SQL Server bracket syntax
+   * @param id - Identifier to quote
+   * @returns Quoted identifier
+   */
+  quoteIdentifier(id) {
+    return `[${id}]`;
+  }
+  /**
+   * Compiles JSON path expression using SQL Server syntax
+   * @param node - JSON path node
+   * @returns SQL Server JSON path expression
+   */
+  compileJsonPath(node) {
+    const col = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
+    return `JSON_VALUE(${col}, '${node.path}')`;
+  }
+  /**
+   * Formats parameter placeholders using SQL Server named parameter syntax
+   * @param index - Parameter index
+   * @returns Named parameter placeholder
+   */
+  formatPlaceholder(index) {
+    return `@p${index}`;
+  }
+  /**
+   * Compiles SELECT query AST to SQL Server SQL
+   * @param ast - Query AST
+   * @param ctx - Compiler context
+   * @returns SQL Server SQL string
+   */
+  compileSelectAst(ast, ctx) {
+    const hasSetOps = !!(ast.setOps && ast.setOps.length);
+    const ctes = this.compileCtes(ast, ctx);
+    const baseAst = hasSetOps ? { ...ast, setOps: void 0, orderBy: void 0, limit: void 0, offset: void 0 } : ast;
+    const baseSelect = this.compileSelectCore(baseAst, ctx);
+    if (!hasSetOps) {
+      return `${ctes}${baseSelect}`;
+    }
+    const compound = ast.setOps.map((op) => `${op.operator} ${this.wrapSetOperand(this.compileSelectAst(op.query, ctx))}`).join(" ");
+    const orderBy = this.compileOrderBy(ast);
+    const pagination = this.compilePagination(ast, orderBy);
+    const combined = `${this.wrapSetOperand(baseSelect)} ${compound}`;
+    const tail = pagination || orderBy;
+    return `${ctes}${combined}${tail}`;
+  }
+  compileInsertAst(ast, ctx) {
+    const table = this.quoteIdentifier(ast.into.name);
+    const columnList = ast.columns.map((column) => `${this.quoteIdentifier(column.table)}.${this.quoteIdentifier(column.name)}`).join(", ");
+    const values = ast.values.map((row) => `(${row.map((value) => this.compileOperand(value, ctx)).join(", ")})`).join(", ");
+    return `INSERT INTO ${table} (${columnList}) VALUES ${values};`;
+  }
+  compileUpdateAst(ast, ctx) {
+    const table = this.quoteIdentifier(ast.table.name);
+    const assignments = ast.set.map((assignment) => {
+      const col = assignment.column;
+      const target = `${this.quoteIdentifier(col.table)}.${this.quoteIdentifier(col.name)}`;
+      const value = this.compileOperand(assignment.value, ctx);
+      return `${target} = ${value}`;
+    }).join(", ");
+    const whereClause = this.compileWhere(ast.where, ctx);
+    return `UPDATE ${table} SET ${assignments}${whereClause};`;
+  }
+  compileDeleteAst(ast, ctx) {
+    const table = this.quoteIdentifier(ast.from.name);
+    const whereClause = this.compileWhere(ast.where, ctx);
+    return `DELETE FROM ${table}${whereClause};`;
+  }
+  compileSelectCore(ast, ctx) {
+    const columns = ast.columns.map((c) => {
+      let expr = "";
+      if (c.type === "Function") {
+        expr = this.compileOperand(c, ctx);
+      } else if (c.type === "Column") {
+        expr = `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`;
+      } else if (c.type === "ScalarSubquery") {
+        expr = this.compileOperand(c, ctx);
+      } else if (c.type === "WindowFunction") {
+        expr = this.compileOperand(c, ctx);
+      }
+      if (c.alias) {
+        if (c.alias.includes("(")) return c.alias;
+        return `${expr} AS ${this.quoteIdentifier(c.alias)}`;
+      }
+      return expr;
+    }).join(", ");
+    const distinct = ast.distinct ? "DISTINCT " : "";
+    const from = `${this.quoteIdentifier(ast.from.name)}`;
+    const joins = ast.joins.map((j) => {
+      const table = this.quoteIdentifier(j.table.name);
+      const cond = this.compileExpression(j.condition, ctx);
+      return `${j.kind} JOIN ${table} ON ${cond}`;
+    }).join(" ");
+    const whereClause = this.compileWhere(ast.where, ctx);
+    const groupBy = ast.groupBy && ast.groupBy.length > 0 ? " GROUP BY " + ast.groupBy.map((c) => `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`).join(", ") : "";
+    const having = ast.having ? ` HAVING ${this.compileExpression(ast.having, ctx)}` : "";
+    const orderBy = this.compileOrderBy(ast);
+    const pagination = this.compilePagination(ast, orderBy);
+    if (pagination) {
+      return `SELECT ${distinct}${columns} FROM ${from}${joins ? " " + joins : ""}${whereClause}${groupBy}${having}${pagination}`;
+    }
+    return `SELECT ${distinct}${columns} FROM ${from}${joins ? " " + joins : ""}${whereClause}${groupBy}${having}${orderBy}`;
+  }
+  compileOrderBy(ast) {
+    if (!ast.orderBy || ast.orderBy.length === 0) return "";
+    return " ORDER BY " + ast.orderBy.map((o) => `${this.quoteIdentifier(o.column.table)}.${this.quoteIdentifier(o.column.name)} ${o.direction}`).join(", ");
+  }
+  compilePagination(ast, orderBy) {
+    const hasLimit = ast.limit !== void 0;
+    const hasOffset = ast.offset !== void 0;
+    if (!hasLimit && !hasOffset) return "";
+    const off = ast.offset ?? 0;
+    const orderClause = orderBy || " ORDER BY (SELECT NULL)";
+    let pagination = `${orderClause} OFFSET ${off} ROWS`;
+    if (hasLimit) {
+      pagination += ` FETCH NEXT ${ast.limit} ROWS ONLY`;
+    }
+    return pagination;
+  }
+  compileCtes(ast, ctx) {
+    if (!ast.ctes || ast.ctes.length === 0) return "";
+    const defs = ast.ctes.map((cte) => {
+      const name = this.quoteIdentifier(cte.name);
+      const cols = cte.columns ? `(${cte.columns.map((c) => this.quoteIdentifier(c)).join(", ")})` : "";
+      const query = this.compileSelectAst(this.normalizeSelectAst(cte.query), ctx).trim().replace(/;$/, "");
+      return `${name}${cols} AS (${query})`;
+    }).join(", ");
+    return `WITH ${defs} `;
+  }
+  wrapSetOperand(sql) {
+    const trimmed = sql.trim().replace(/;$/, "");
+    return `(${trimmed})`;
+  }
+};
+
+// src/core/dialect/dialect-factory.ts
+var DialectFactory = class {
+  static {
+    this.registry = /* @__PURE__ */ new Map();
+  }
+  static {
+    this.defaultsInitialized = false;
+  }
+  static ensureDefaults() {
+    if (this.defaultsInitialized) return;
+    this.defaultsInitialized = true;
+    if (!this.registry.has("postgres")) {
+      this.registry.set("postgres", () => new PostgresDialect());
+    }
+    if (!this.registry.has("mysql")) {
+      this.registry.set("mysql", () => new MySqlDialect());
+    }
+    if (!this.registry.has("sqlite")) {
+      this.registry.set("sqlite", () => new SqliteDialect());
+    }
+    if (!this.registry.has("mssql")) {
+      this.registry.set("mssql", () => new SqlServerDialect());
+    }
+  }
+  /**
+   * Register (or override) a dialect factory for a key.
+   *
+   * Examples:
+   *   DialectFactory.register('sqlite', () => new SqliteDialect());
+   *   DialectFactory.register('my-tenant-dialect', () => new CustomDialect());
+   */
+  static register(key, factory) {
+    this.registry.set(key, factory);
+  }
+  /**
+   * Resolve a key into a Dialect instance.
+   * Throws if the key is not registered.
+   */
+  static create(key) {
+    this.ensureDefaults();
+    const factory = this.registry.get(key);
+    if (!factory) {
+      throw new Error(
+        `Dialect "${String(
+          key
+        )}" is not registered. Use DialectFactory.register(...) to register it.`
+      );
+    }
+    return factory();
+  }
+  /**
+   * Clear all registrations (mainly for tests).
+   * Built-ins will be re-registered lazily on the next create().
+   */
+  static clear() {
+    this.registry.clear();
+    this.defaultsInitialized = false;
+  }
 };
-var columnOperand = (col) => toNode(col);
-var createBinaryExpression = (operator, left, right, escape) => {
-  const node = {
-    type: "BinaryExpression",
-    left: toNode(left),
-    operator,
-    right: toOperand(right)
-  };
-  if (escape !== void 0) {
-    node.escape = toLiteralNode(escape);
+var resolveDialectInput = (dialect) => {
+  if (typeof dialect === "string") {
+    return DialectFactory.create(dialect);
   }
-  return node;
+  return dialect;
 };
-var eq = (left, right) => createBinaryExpression("=", left, right);
-var and = (...operands) => ({
-  type: "LogicalExpression",
-  operator: "AND",
-  operands
-});
-var createInExpression = (operator, left, values) => ({
-  type: "InExpression",
-  left: toNode(left),
-  operator,
-  right: values.map((v) => toOperand(v))
-});
-var inList = (left, values) => createInExpression("IN", left, values);
-var exists = (subquery) => ({
-  type: "ExistsExpression",
-  operator: "EXISTS",
-  subquery
-});
-var notExists = (subquery) => ({
-  type: "ExistsExpression",
-  operator: "NOT EXISTS",
-  subquery
-});
-
-// src/core/ast/aggregate-functions.ts
-var buildAggregate = (name) => (col) => ({
-  type: "Function",
-  name,
-  args: [columnOperand(col)]
-});
-var count = buildAggregate("COUNT");
-var sum = buildAggregate("SUM");
-var avg = buildAggregate("AVG");
 
 // src/query-builder/select-query-state.ts
 var SelectQueryState = class _SelectQueryState {
@@ -517,9 +1928,9 @@ var SelectQueryState = class _SelectQueryState {
 var createJoinNode = (kind, tableName, condition, relationName) => ({
   type: "Join",
   kind,
-  table: { type: "Table", name: tableName },
+  table: typeof tableName === "string" ? { type: "Table", name: tableName } : tableName,
   condition,
-  relationName
+  meta: relationName ? { relationName } : void 0
 });
 
 // src/core/sql/sql.ts
@@ -861,7 +2272,8 @@ var HydrationPlanner = class _HydrationPlanner {
    */
   buildRelationPlan(rel, relationName, aliasPrefix, columns, pivot) {
     switch (rel.type) {
-      case RelationKinds.HasMany: {
+      case RelationKinds.HasMany:
+      case RelationKinds.HasOne: {
         const localKey = rel.localKey || findPrimaryKey(this.table);
         return {
           name: relationName,
@@ -1190,10 +2602,11 @@ var assertNever = (value) => {
   throw new Error(`Unhandled relation type: ${JSON.stringify(value)}`);
 };
 var baseRelationCondition = (root, relation) => {
-  const defaultLocalKey = relation.type === RelationKinds.HasMany ? findPrimaryKey(root) : findPrimaryKey(relation.target);
+  const defaultLocalKey = relation.type === RelationKinds.HasMany || relation.type === RelationKinds.HasOne ? findPrimaryKey(root) : findPrimaryKey(relation.target);
   const localKey = relation.localKey || defaultLocalKey;
   switch (relation.type) {
     case RelationKinds.HasMany:
+    case RelationKinds.HasOne:
       return eq(
         { type: "Column", table: relation.target.name, name: relation.foreignKey },
         { type: "Column", table: root.name, name: localKey }
@@ -1240,6 +2653,9 @@ var buildRelationCorrelation = (root, relation) => {
   return baseRelationCondition(root, relation);
 };
 
+// src/core/ast/join-metadata.ts
+var getJoinRelationName = (join) => join.meta?.relationName;
+
 // src/query-builder/relation-service.ts
 var RelationService = class {
   /**
@@ -1294,7 +2710,7 @@ var RelationService = class {
     let hydration = this.hydration;
     const relation = this.getRelation(relationName);
     const aliasPrefix = options?.aliasPrefix ?? relationName;
-    const alreadyJoined = state.ast.joins.some((j) => j.relationName === relationName);
+    const alreadyJoined = state.ast.joins.some((j) => getJoinRelationName(j) === relationName);
     if (!alreadyJoined) {
       const joined = this.joinRelation(relationName, options?.joinKind ?? JOIN_KINDS.LEFT, options?.filter);
       state = joined.state;
@@ -1615,6 +3031,12 @@ var hydrateRows = (rows, plan) => {
       const seen = getRelationSeenSet(rootId, rel.name);
       if (seen.has(childPk)) continue;
       seen.add(childPk);
+      if (rel.type === RelationKinds.HasOne) {
+        if (!parent[rel.name]) {
+          parent[rel.name] = buildChild(row, rel);
+        }
+        continue;
+      }
       const bucket = parent[rel.name];
       bucket.push(buildChild(row, rel));
     }
@@ -1628,7 +3050,7 @@ var createBaseRow = (row, plan) => {
     base[key] = row[key];
   }
   for (const rel of plan.relations) {
-    base[rel.name] = [];
+    base[rel.name] = rel.type === RelationKinds.HasOne ? null : [];
   }
   return base;
 };
@@ -1791,7 +3213,7 @@ var DefaultHasManyCollection = class {
   }
 };
 
-// src/orm/relations/belongs-to.ts
+// src/orm/relations/has-one.ts
 var toKey3 = (value) => value === null || value === void 0 ? "" : String(value);
 var hideInternal2 = (obj, keys) => {
   for (const key of keys) {
@@ -1803,6 +3225,123 @@ var hideInternal2 = (obj, keys) => {
     });
   }
 };
+var DefaultHasOneReference = class {
+  constructor(ctx, meta, root, relationName, relation, rootTable, loader, createEntity, localKey) {
+    this.ctx = ctx;
+    this.meta = meta;
+    this.root = root;
+    this.relationName = relationName;
+    this.relation = relation;
+    this.rootTable = rootTable;
+    this.loader = loader;
+    this.createEntity = createEntity;
+    this.localKey = localKey;
+    this.loaded = false;
+    this.current = null;
+    hideInternal2(this, [
+      "ctx",
+      "meta",
+      "root",
+      "relationName",
+      "relation",
+      "rootTable",
+      "loader",
+      "createEntity",
+      "localKey"
+    ]);
+    this.populateFromHydrationCache();
+  }
+  async load() {
+    if (this.loaded) return this.current;
+    const map = await this.loader();
+    const keyValue = this.root[this.localKey];
+    if (keyValue === void 0 || keyValue === null) {
+      this.loaded = true;
+      return this.current;
+    }
+    const row = map.get(toKey3(keyValue));
+    this.current = row ? this.createEntity(row) : null;
+    this.loaded = true;
+    return this.current;
+  }
+  get() {
+    return this.current;
+  }
+  set(data) {
+    if (data === null) {
+      return this.detachCurrent();
+    }
+    const entity = hasEntityMeta(data) ? data : this.createEntity(data);
+    if (this.current && this.current !== entity) {
+      this.ctx.registerRelationChange(
+        this.root,
+        this.relationKey,
+        this.rootTable,
+        this.relationName,
+        this.relation,
+        { kind: "remove", entity: this.current }
+      );
+    }
+    this.assignForeignKey(entity);
+    this.current = entity;
+    this.loaded = true;
+    this.ctx.registerRelationChange(
+      this.root,
+      this.relationKey,
+      this.rootTable,
+      this.relationName,
+      this.relation,
+      { kind: "attach", entity }
+    );
+    return entity;
+  }
+  toJSON() {
+    return this.current;
+  }
+  detachCurrent() {
+    const previous = this.current;
+    if (!previous) return null;
+    this.current = null;
+    this.loaded = true;
+    this.ctx.registerRelationChange(
+      this.root,
+      this.relationKey,
+      this.rootTable,
+      this.relationName,
+      this.relation,
+      { kind: "remove", entity: previous }
+    );
+    return null;
+  }
+  assignForeignKey(entity) {
+    const keyValue = this.root[this.localKey];
+    entity[this.relation.foreignKey] = keyValue;
+  }
+  get relationKey() {
+    return `${this.rootTable.name}.${this.relationName}`;
+  }
+  populateFromHydrationCache() {
+    const keyValue = this.root[this.localKey];
+    if (keyValue === void 0 || keyValue === null) return;
+    const row = getHydrationRecord(this.meta, this.relationName, keyValue);
+    if (!row) return;
+    this.current = this.createEntity(row);
+    this.loaded = true;
+  }
+};
+
+// src/orm/relations/belongs-to.ts
+var toKey4 = (value) => value === null || value === void 0 ? "" : String(value);
+var hideInternal3 = (obj, keys) => {
+  for (const key of keys) {
+    Object.defineProperty(obj, key, {
+      value: obj[key],
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+};
 var DefaultBelongsToReference = class {
   constructor(ctx, meta, root, relationName, relation, rootTable, loader, createEntity, targetKey) {
     this.ctx = ctx;
@@ -1816,7 +3355,7 @@ var DefaultBelongsToReference = class {
     this.targetKey = targetKey;
     this.loaded = false;
     this.current = null;
-    hideInternal2(this, ["ctx", "meta", "root", "relationName", "relation", "rootTable", "loader", "createEntity", "targetKey"]);
+    hideInternal3(this, ["ctx", "meta", "root", "relationName", "relation", "rootTable", "loader", "createEntity", "targetKey"]);
     this.populateFromHydrationCache();
   }
   async load() {
@@ -1826,7 +3365,7 @@ var DefaultBelongsToReference = class {
     if (fkValue === null || fkValue === void 0) {
       this.current = null;
     } else {
-      const row = map.get(toKey3(fkValue));
+      const row = map.get(toKey4(fkValue));
       this.current = row ? this.createEntity(row) : null;
     }
     this.loaded = true;
@@ -1883,8 +3422,8 @@ var DefaultBelongsToReference = class {
 };
 
 // src/orm/relations/many-to-many.ts
-var toKey4 = (value) => value === null || value === void 0 ? "" : String(value);
-var hideInternal3 = (obj, keys) => {
+var toKey5 = (value) => value === null || value === void 0 ? "" : String(value);
+var hideInternal4 = (obj, keys) => {
   for (const key of keys) {
     Object.defineProperty(obj, key, {
       value: obj[key],
@@ -1907,13 +3446,13 @@ var DefaultManyToManyCollection = class {
     this.localKey = localKey;
     this.loaded = false;
     this.items = [];
-    hideInternal3(this, ["ctx", "meta", "root", "relationName", "relation", "rootTable", "loader", "createEntity", "localKey"]);
+    hideInternal4(this, ["ctx", "meta", "root", "relationName", "relation", "rootTable", "loader", "createEntity", "localKey"]);
     this.hydrateFromCache();
   }
   async load() {
     if (this.loaded) return this.items;
     const map = await this.loader();
-    const key = toKey4(this.root[this.localKey]);
+    const key = toKey5(this.root[this.localKey]);
     const rows = map.get(key) ?? [];
     this.items = rows.map((row) => {
       const entity = this.createEntity(row);
@@ -1963,15 +3502,15 @@ var DefaultManyToManyCollection = class {
   async syncByIds(ids) {
     await this.load();
     const targetKey = this.relation.targetKey || findPrimaryKey(this.relation.target);
-    const normalized = new Set(ids.map((id) => toKey4(id)));
-    const currentIds = new Set(this.items.map((item) => toKey4(this.extractId(item))));
+    const normalized = new Set(ids.map((id) => toKey5(id)));
+    const currentIds = new Set(this.items.map((item) => toKey5(this.extractId(item))));
     for (const id of normalized) {
       if (!currentIds.has(id)) {
         this.attach(id);
       }
     }
     for (const item of [...this.items]) {
-      const itemId = toKey4(this.extractId(item));
+      const itemId = toKey5(this.extractId(item));
       if (!normalized.has(itemId)) {
         this.detach(item);
       }
@@ -2042,7 +3581,7 @@ var executeQuery = async (ctx, qb) => {
   const results = await ctx.executor.executeSql(compiled.sql, compiled.params);
   return rowsFromResults(results);
 };
-var toKey5 = (value) => value === null || value === void 0 ? "" : String(value);
+var toKey6 = (value) => value === null || value === void 0 ? "" : String(value);
 var loadHasManyRelation = async (ctx, rootTable, _relationName, relation) => {
   const localKey = relation.localKey || findPrimaryKey(rootTable);
   const roots = ctx.getEntitiesForTable(rootTable);
@@ -2066,13 +3605,43 @@ var loadHasManyRelation = async (ctx, rootTable, _relationName, relation) => {
   for (const row of rows) {
     const fkValue = row[relation.foreignKey];
     if (fkValue === null || fkValue === void 0) continue;
-    const key = toKey5(fkValue);
+    const key = toKey6(fkValue);
     const bucket = grouped.get(key) ?? [];
     bucket.push(row);
     grouped.set(key, bucket);
   }
   return grouped;
 };
+var loadHasOneRelation = async (ctx, rootTable, _relationName, relation) => {
+  const localKey = relation.localKey || findPrimaryKey(rootTable);
+  const roots = ctx.getEntitiesForTable(rootTable);
+  const keys = /* @__PURE__ */ new Set();
+  for (const tracked of roots) {
+    const value = tracked.entity[localKey];
+    if (value !== null && value !== void 0) {
+      keys.add(value);
+    }
+  }
+  if (!keys.size) {
+    return /* @__PURE__ */ new Map();
+  }
+  const selectMap = selectAllColumns(relation.target);
+  const qb = new SelectQueryBuilder(relation.target).select(selectMap);
+  const fkColumn = relation.target.columns[relation.foreignKey];
+  if (!fkColumn) return /* @__PURE__ */ new Map();
+  qb.where(inList(fkColumn, Array.from(keys)));
+  const rows = await executeQuery(ctx, qb);
+  const lookup = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const fkValue = row[relation.foreignKey];
+    if (fkValue === null || fkValue === void 0) continue;
+    const key = toKey6(fkValue);
+    if (!lookup.has(key)) {
+      lookup.set(key, row);
+    }
+  }
+  return lookup;
+};
 var loadBelongsToRelation = async (ctx, rootTable, _relationName, relation) => {
   const roots = ctx.getEntitiesForTable(rootTable);
   const foreignKeys = /* @__PURE__ */ new Set();
@@ -2096,7 +3665,7 @@ var loadBelongsToRelation = async (ctx, rootTable, _relationName, relation) => {
   for (const row of rows) {
     const keyValue = row[targetKey];
     if (keyValue === null || keyValue === void 0) continue;
-    map.set(toKey5(keyValue), row);
+    map.set(toKey6(keyValue), row);
   }
   return map;
 };
@@ -2127,12 +3696,12 @@ var loadBelongsToManyRelation = async (ctx, rootTable, _relationName, relation)
     if (rootValue === null || rootValue === void 0 || targetValue === null || targetValue === void 0) {
       continue;
     }
-    const bucket = rootLookup.get(toKey5(rootValue)) ?? [];
+    const bucket = rootLookup.get(toKey6(rootValue)) ?? [];
     bucket.push({
       targetId: targetValue,
       pivot: { ...pivot }
     });
-    rootLookup.set(toKey5(rootValue), bucket);
+    rootLookup.set(toKey6(rootValue), bucket);
     targetIds.add(targetValue);
   }
   if (!targetIds.size) {
@@ -2149,13 +3718,13 @@ var loadBelongsToManyRelation = async (ctx, rootTable, _relationName, relation)
   for (const row of targetRows) {
     const pkValue = row[targetKey];
     if (pkValue === null || pkValue === void 0) continue;
-    targetMap.set(toKey5(pkValue), row);
+    targetMap.set(toKey6(pkValue), row);
   }
   const result = /* @__PURE__ */ new Map();
   for (const [rootId, entries] of rootLookup.entries()) {
     const bucket = [];
     for (const entry of entries) {
-      const targetRow = targetMap.get(toKey5(entry.targetId));
+      const targetRow = targetMap.get(toKey6(entry.targetId));
       if (!targetRow) continue;
       bucket.push({
         ...targetRow,
@@ -2250,18 +3819,29 @@ var createEntityFromRow = (ctx, table, row, lazyRelations = []) => {
   }
   return entity;
 };
-var toKey6 = (value) => value === null || value === void 0 ? "" : String(value);
+var toKey7 = (value) => value === null || value === void 0 ? "" : String(value);
 var populateHydrationCache = (entity, row, meta) => {
   for (const relationName of Object.keys(meta.table.relations)) {
     const relation = meta.table.relations[relationName];
     const data = row[relationName];
+    if (relation.type === RelationKinds.HasOne) {
+      const localKey = relation.localKey || findPrimaryKey(meta.table);
+      const rootValue = entity[localKey];
+      if (rootValue === void 0 || rootValue === null) continue;
+      if (!data || typeof data !== "object") continue;
+      const cache = /* @__PURE__ */ new Map();
+      cache.set(toKey7(rootValue), data);
+      meta.relationHydration.set(relationName, cache);
+      meta.relationCache.set(relationName, Promise.resolve(cache));
+      continue;
+    }
     if (!Array.isArray(data)) continue;
     if (relation.type === RelationKinds.HasMany || relation.type === RelationKinds.BelongsToMany) {
       const localKey = relation.localKey || findPrimaryKey(meta.table);
       const rootValue = entity[localKey];
       if (rootValue === void 0 || rootValue === null) continue;
       const cache = /* @__PURE__ */ new Map();
-      cache.set(toKey6(rootValue), data);
+      cache.set(toKey7(rootValue), data);
       meta.relationHydration.set(relationName, cache);
       meta.relationCache.set(relationName, Promise.resolve(cache));
       continue;
@@ -2272,7 +3852,7 @@ var populateHydrationCache = (entity, row, meta) => {
       for (const item of data) {
         const pkValue = item[targetKey];
         if (pkValue === void 0 || pkValue === null) continue;
-        cache.set(toKey6(pkValue), item);
+        cache.set(toKey7(pkValue), item);
       }
       if (cache.size) {
         meta.relationHydration.set(relationName, cache);
@@ -2295,6 +3875,26 @@ var getRelationWrapper = (meta, relationName, owner) => {
 };
 var instantiateWrapper = (meta, relationName, relation, owner) => {
   switch (relation.type) {
+    case RelationKinds.HasOne: {
+      const hasOne2 = relation;
+      const localKey = hasOne2.localKey || findPrimaryKey(meta.table);
+      const loader = () => relationLoaderCache(
+        meta,
+        relationName,
+        () => loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne2)
+      );
+      return new DefaultHasOneReference(
+        meta.ctx,
+        meta,
+        owner,
+        relationName,
+        hasOne2,
+        meta.table,
+        loader,
+        (row) => createEntityFromRow(meta.ctx, hasOne2.target, row),
+        localKey
+      );
+    }
     case RelationKinds.HasMany: {
       const hasMany2 = relation;
       const localKey = hasMany2.localKey || findPrimaryKey(meta.table);
@@ -2375,31 +3975,43 @@ var flattenResults = (results) => {
   }
   return rows;
 };
-async function executeHydrated(ctx, qb) {
+var executeWithEntityContext = async (entityCtx, qb) => {
   const ast = qb.getAST();
-  const compiled = ctx.dialect.compileSelect(ast);
-  const executed = await ctx.executor.executeSql(compiled.sql, compiled.params);
+  const compiled = entityCtx.dialect.compileSelect(ast);
+  const executed = await entityCtx.executor.executeSql(compiled.sql, compiled.params);
   const rows = flattenResults(executed);
   if (ast.setOps && ast.setOps.length > 0) {
-    return rows.map(
-      (row) => createEntityProxy(ctx, qb.getTable(), row, qb.getLazyRelations())
-    );
+    return rows.map((row) => createEntityProxy(entityCtx, qb.getTable(), row, qb.getLazyRelations()));
   }
   const hydrated = hydrateRows(rows, qb.getHydrationPlan());
-  return hydrated.map(
-    (row) => createEntityFromRow(ctx, qb.getTable(), row, qb.getLazyRelations())
-  );
+  return hydrated.map((row) => createEntityFromRow(entityCtx, qb.getTable(), row, qb.getLazyRelations()));
+};
+async function executeHydrated(session, qb) {
+  return executeWithEntityContext(session, qb);
+}
+async function executeHydratedWithContexts(_execCtx, hydCtx, qb) {
+  const entityCtx = hydCtx.entityContext;
+  if (!entityCtx) {
+    throw new Error("Hydration context is missing an EntityContext");
+  }
+  return executeWithEntityContext(entityCtx, qb);
 }
 
 // src/query-builder/select.ts
 var SelectQueryBuilder = class _SelectQueryBuilder {
   /**
-   * Creates a new SelectQueryBuilder instance
-   * @param table - Table definition to query
-   * @param state - Optional initial query state
-   * @param hydration - Optional hydration manager
-   * @param dependencies - Optional query builder dependencies
-   */
+  
+     * Creates a new SelectQueryBuilder instance
+  
+     * @param table - Table definition to query
+  
+     * @param state - Optional initial query state
+  
+     * @param hydration - Optional hydration manager
+  
+     * @param dependencies - Optional query builder dependencies
+  
+     */
   constructor(table, state, hydration, dependencies, lazyRelations) {
     const deps = resolveSelectQueryBuilderDependencies(dependencies);
     this.env = { table, deps };
@@ -2436,112 +4048,168 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     return this.applyAst(this.context, (service) => service.withSetOperation(operator, subAst));
   }
   /**
-   * Selects specific columns for the query
-   * @param columns - Record of column definitions, function nodes, case expressions, or window functions
-   * @returns New query builder instance with selected columns
-   */
+  
+     * Selects specific columns for the query
+  
+     * @param columns - Record of column definitions, function nodes, case expressions, or window functions
+  
+     * @returns New query builder instance with selected columns
+  
+     */
   select(columns) {
     return this.clone(this.columnSelector.select(this.context, columns));
   }
   /**
-   * Selects raw column expressions
-   * @param cols - Column expressions as strings
-   * @returns New query builder instance with raw column selections
-   */
+  
+     * Selects raw column expressions
+  
+     * @param cols - Column expressions as strings
+  
+     * @returns New query builder instance with raw column selections
+  
+     */
   selectRaw(...cols) {
     return this.clone(this.columnSelector.selectRaw(this.context, cols));
   }
   /**
-   * Adds a Common Table Expression (CTE) to the query
-   * @param name - Name of the CTE
-   * @param query - Query builder or query node for the CTE
-   * @param columns - Optional column names for the CTE
-   * @returns New query builder instance with the CTE
-   */
+  
+     * Adds a Common Table Expression (CTE) to the query
+  
+     * @param name - Name of the CTE
+  
+     * @param query - Query builder or query node for the CTE
+  
+     * @param columns - Optional column names for the CTE
+  
+     * @returns New query builder instance with the CTE
+  
+     */
   with(name, query, columns) {
     const subAst = this.resolveQueryNode(query);
     const nextContext = this.applyAst(this.context, (service) => service.withCte(name, subAst, columns, false));
     return this.clone(nextContext);
   }
   /**
-   * Adds a recursive Common Table Expression (CTE) to the query
-   * @param name - Name of the CTE
-   * @param query - Query builder or query node for the CTE
-   * @param columns - Optional column names for the CTE
-   * @returns New query builder instance with the recursive CTE
-   */
+  
+     * Adds a recursive Common Table Expression (CTE) to the query
+  
+     * @param name - Name of the CTE
+  
+     * @param query - Query builder or query node for the CTE
+  
+     * @param columns - Optional column names for the CTE
+  
+     * @returns New query builder instance with the recursive CTE
+  
+     */
   withRecursive(name, query, columns) {
     const subAst = this.resolveQueryNode(query);
     const nextContext = this.applyAst(this.context, (service) => service.withCte(name, subAst, columns, true));
     return this.clone(nextContext);
   }
   /**
-   * Selects a subquery as a column
-   * @param alias - Alias for the subquery column
-   * @param sub - Query builder or query node for the subquery
-   * @returns New query builder instance with the subquery selection
-   */
+  
+     * Selects a subquery as a column
+  
+     * @param alias - Alias for the subquery column
+  
+     * @param sub - Query builder or query node for the subquery
+  
+     * @returns New query builder instance with the subquery selection
+  
+     */
   selectSubquery(alias, sub) {
     const query = this.resolveQueryNode(sub);
     return this.clone(this.columnSelector.selectSubquery(this.context, alias, query));
   }
   /**
-   * Adds an INNER JOIN to the query
-   * @param table - Table to join
-   * @param condition - Join condition expression
-   * @returns New query builder instance with the INNER JOIN
-   */
+  
+     * Adds an INNER JOIN to the query
+  
+     * @param table - Table to join
+  
+     * @param condition - Join condition expression
+  
+     * @returns New query builder instance with the INNER JOIN
+  
+     */
   innerJoin(table, condition) {
     const nextContext = this.applyJoin(this.context, table, condition, JOIN_KINDS.INNER);
     return this.clone(nextContext);
   }
   /**
-   * Adds a LEFT JOIN to the query
-   * @param table - Table to join
-   * @param condition - Join condition expression
-   * @returns New query builder instance with the LEFT JOIN
-   */
+  
+     * Adds a LEFT JOIN to the query
+  
+     * @param table - Table to join
+  
+     * @param condition - Join condition expression
+  
+     * @returns New query builder instance with the LEFT JOIN
+  
+     */
   leftJoin(table, condition) {
     const nextContext = this.applyJoin(this.context, table, condition, JOIN_KINDS.LEFT);
     return this.clone(nextContext);
   }
   /**
-   * Adds a RIGHT JOIN to the query
-   * @param table - Table to join
-   * @param condition - Join condition expression
-   * @returns New query builder instance with the RIGHT JOIN
-   */
+  
+     * Adds a RIGHT JOIN to the query
+  
+     * @param table - Table to join
+  
+     * @param condition - Join condition expression
+  
+     * @returns New query builder instance with the RIGHT JOIN
+  
+     */
   rightJoin(table, condition) {
     const nextContext = this.applyJoin(this.context, table, condition, JOIN_KINDS.RIGHT);
     return this.clone(nextContext);
   }
   /**
-   * Matches records based on a relationship
-   * @param relationName - Name of the relationship to match
-   * @param predicate - Optional predicate expression
-   * @returns New query builder instance with the relationship match
-   */
+  
+     * Matches records based on a relationship
+  
+     * @param relationName - Name of the relationship to match
+  
+     * @param predicate - Optional predicate expression
+  
+     * @returns New query builder instance with the relationship match
+  
+     */
   match(relationName, predicate) {
     const nextContext = this.relationManager.match(this.context, relationName, predicate);
     return this.clone(nextContext);
   }
   /**
-   * Joins a related table
-   * @param relationName - Name of the relationship to join
-   * @param joinKind - Type of join (defaults to INNER)
-   * @param extraCondition - Optional additional join condition
-   * @returns New query builder instance with the relationship join
-   */
+  
+     * Joins a related table
+  
+     * @param relationName - Name of the relationship to join
+  
+     * @param joinKind - Type of join (defaults to INNER)
+  
+     * @param extraCondition - Optional additional join condition
+  
+     * @returns New query builder instance with the relationship join
+  
+     */
   joinRelation(relationName, joinKind = JOIN_KINDS.INNER, extraCondition) {
     const nextContext = this.relationManager.joinRelation(this.context, relationName, joinKind, extraCondition);
     return this.clone(nextContext);
   }
   /**
-   * Includes related data in the query results
-   * @param relationName - Name of the relationship to include
-   * @param options - Optional include options
-   * @returns New query builder instance with the relationship inclusion
-   */
+  
+     * Includes related data in the query results
+  
+     * @param relationName - Name of the relationship to include
+  
+     * @param options - Optional include options
+  
+     * @returns New query builder instance with the relationship inclusion
+  
+     */
   include(relationName, options) {
     const nextContext = this.relationManager.include(this.context, relationName, options);
     return this.clone(nextContext);
@@ -2560,125 +4228,186 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   async execute(ctx) {
     return executeHydrated(ctx, this);
   }
+  async executeWithContexts(execCtx, hydCtx) {
+    return executeHydratedWithContexts(execCtx, hydCtx, this);
+  }
   /**
-   * Adds a WHERE condition to the query
-   * @param expr - Expression for the WHERE clause
-   * @returns New query builder instance with the WHERE condition
-   */
+  
+     * Adds a WHERE condition to the query
+  
+     * @param expr - Expression for the WHERE clause
+  
+     * @returns New query builder instance with the WHERE condition
+  
+     */
   where(expr) {
     const nextContext = this.applyAst(this.context, (service) => service.withWhere(expr));
     return this.clone(nextContext);
   }
   /**
-   * Adds a GROUP BY clause to the query
-   * @param col - Column definition or column node to group by
-   * @returns New query builder instance with the GROUP BY clause
-   */
+  
+     * Adds a GROUP BY clause to the query
+  
+     * @param col - Column definition or column node to group by
+  
+     * @returns New query builder instance with the GROUP BY clause
+  
+     */
   groupBy(col) {
     const nextContext = this.applyAst(this.context, (service) => service.withGroupBy(col));
     return this.clone(nextContext);
   }
   /**
-   * Adds a HAVING condition to the query
-   * @param expr - Expression for the HAVING clause
-   * @returns New query builder instance with the HAVING condition
-   */
+  
+     * Adds a HAVING condition to the query
+  
+     * @param expr - Expression for the HAVING clause
+  
+     * @returns New query builder instance with the HAVING condition
+  
+     */
   having(expr) {
     const nextContext = this.applyAst(this.context, (service) => service.withHaving(expr));
     return this.clone(nextContext);
   }
   /**
-   * Adds an ORDER BY clause to the query
-   * @param col - Column definition or column node to order by
-   * @param direction - Order direction (defaults to ASC)
-   * @returns New query builder instance with the ORDER BY clause
-   */
+  
+     * Adds an ORDER BY clause to the query
+  
+     * @param col - Column definition or column node to order by
+  
+     * @param direction - Order direction (defaults to ASC)
+  
+     * @returns New query builder instance with the ORDER BY clause
+  
+     */
   orderBy(col, direction = ORDER_DIRECTIONS.ASC) {
     const nextContext = this.applyAst(this.context, (service) => service.withOrderBy(col, direction));
     return this.clone(nextContext);
   }
   /**
-   * Adds a DISTINCT clause to the query
-   * @param cols - Columns to make distinct
-   * @returns New query builder instance with the DISTINCT clause
-   */
+  
+     * Adds a DISTINCT clause to the query
+  
+     * @param cols - Columns to make distinct
+  
+     * @returns New query builder instance with the DISTINCT clause
+  
+     */
   distinct(...cols) {
     return this.clone(this.columnSelector.distinct(this.context, cols));
   }
   /**
-   * Adds a LIMIT clause to the query
-   * @param n - Maximum number of rows to return
-   * @returns New query builder instance with the LIMIT clause
-   */
+  
+     * Adds a LIMIT clause to the query
+  
+     * @param n - Maximum number of rows to return
+  
+     * @returns New query builder instance with the LIMIT clause
+  
+     */
   limit(n) {
     const nextContext = this.applyAst(this.context, (service) => service.withLimit(n));
     return this.clone(nextContext);
   }
   /**
-   * Adds an OFFSET clause to the query
-   * @param n - Number of rows to skip
-   * @returns New query builder instance with the OFFSET clause
-   */
+  
+     * Adds an OFFSET clause to the query
+  
+     * @param n - Number of rows to skip
+  
+     * @returns New query builder instance with the OFFSET clause
+  
+     */
   offset(n) {
     const nextContext = this.applyAst(this.context, (service) => service.withOffset(n));
     return this.clone(nextContext);
   }
   /**
-   * Combines this query with another using UNION
-   * @param query - Query to union with
-   * @returns New query builder instance with the set operation
-   */
+  
+     * Combines this query with another using UNION
+  
+     * @param query - Query to union with
+  
+     * @returns New query builder instance with the set operation
+  
+     */
   union(query) {
     return this.clone(this.applySetOperation("UNION", query));
   }
   /**
-   * Combines this query with another using UNION ALL
-   * @param query - Query to union with
-   * @returns New query builder instance with the set operation
-   */
+  
+     * 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) {
     return this.clone(this.applySetOperation("UNION ALL", query));
   }
   /**
-   * Combines this query with another using INTERSECT
-   * @param query - Query to intersect with
-   * @returns New query builder instance with the set operation
-   */
+  
+     * Combines this query with another using INTERSECT
+  
+     * @param query - Query to intersect with
+  
+     * @returns New query builder instance with the set operation
+  
+     */
   intersect(query) {
     return this.clone(this.applySetOperation("INTERSECT", query));
   }
   /**
-   * Combines this query with another using EXCEPT
-   * @param query - Query to subtract
-   * @returns New query builder instance with the set operation
-   */
+  
+     * Combines this query with another using EXCEPT
+  
+     * @param query - Query to subtract
+  
+     * @returns New query builder instance with the set operation
+  
+     */
   except(query) {
     return this.clone(this.applySetOperation("EXCEPT", query));
   }
   /**
-   * Adds a WHERE EXISTS condition to the query
-   * @param subquery - Subquery to check for existence
-   * @returns New query builder instance with the WHERE EXISTS condition
-   */
+  
+     * Adds a WHERE EXISTS condition to the query
+  
+     * @param subquery - Subquery to check for existence
+  
+     * @returns New query builder instance with the WHERE EXISTS condition
+  
+     */
   whereExists(subquery) {
     const subAst = this.resolveQueryNode(subquery);
     return this.where(exists(subAst));
   }
   /**
-   * Adds a WHERE NOT EXISTS condition to the query
-   * @param subquery - Subquery to check for non-existence
-   * @returns New query builder instance with the WHERE NOT EXISTS condition
-   */
+  
+     * Adds a WHERE NOT EXISTS condition to the query
+  
+     * @param subquery - Subquery to check for non-existence
+  
+     * @returns New query builder instance with the WHERE NOT EXISTS condition
+  
+     */
   whereNotExists(subquery) {
     const subAst = this.resolveQueryNode(subquery);
     return this.where(notExists(subAst));
   }
   /**
-   * Adds a WHERE EXISTS condition based on a relationship
-   * @param relationName - Name of the relationship to check
-   * @param callback - Optional callback to modify the relationship query
-   * @returns New query builder instance with the relationship existence check
-   */
+  
+     * Adds a WHERE EXISTS condition based on a relationship
+  
+     * @param relationName - Name of the relationship to check
+  
+     * @param callback - Optional callback to modify the relationship query
+  
+     * @returns New query builder instance with the relationship existence check
+  
+     */
   whereHas(relationName, callback) {
     const relation = this.env.table.relations[relationName];
     if (!relation) {
@@ -2693,11 +4422,16 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     return this.where(exists(finalSubAst));
   }
   /**
-   * Adds a WHERE NOT EXISTS condition based on a relationship
-   * @param relationName - Name of the relationship to check
-   * @param callback - Optional callback to modify the relationship query
-   * @returns New query builder instance with the relationship non-existence check
-   */
+  
+     * Adds a WHERE NOT EXISTS condition based on a relationship
+  
+     * @param relationName - Name of the relationship to check
+  
+     * @param callback - Optional callback to modify the relationship query
+  
+     * @returns New query builder instance with the relationship non-existence check
+  
+     */
   whereHasNot(relationName, callback) {
     const relation = this.env.table.relations[relationName];
     if (!relation) {
@@ -2712,32 +4446,47 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     return this.where(notExists(finalSubAst));
   }
   /**
-   * Compiles the query to SQL for a specific dialect
-   * @param dialect - Database dialect to compile for
-   * @returns Compiled query with SQL and parameters
-   */
+  
+     * Compiles the query to SQL for a specific dialect
+  
+     * @param dialect - Database dialect to compile for
+  
+     * @returns Compiled query with SQL and parameters
+  
+     */
   compile(dialect) {
-    return dialect.compileSelect(this.context.state.ast);
+    const resolved = resolveDialectInput(dialect);
+    return resolved.compileSelect(this.context.state.ast);
   }
   /**
-   * 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
-   */
+  
+     * 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) {
     return this.compile(dialect).sql;
   }
   /**
-   * Gets the hydration plan for the query
-   * @returns Hydration plan or undefined if none exists
-   */
+  
+     * Gets the hydration plan for the query
+  
+     * @returns Hydration plan or undefined if none exists
+  
+     */
   getHydrationPlan() {
     return this.context.hydration.getPlan();
   }
   /**
-   * Gets the Abstract Syntax Tree (AST) representation of the query
-   * @returns Query AST with hydration applied
-   */
+  
+     * Gets the Abstract Syntax Tree (AST) representation of the query
+  
+     * @returns Query AST with hydration applied
+  
+     */
   getAST() {
     return this.context.hydration.applyToAst(this.context.state.ast);
   }
@@ -2768,6 +4517,15 @@ var buildRelationDefinitions = (meta, tableMap) => {
   const relations = {};
   for (const [name, relation] of Object.entries(meta.relations)) {
     switch (relation.kind) {
+      case RelationKinds.HasOne: {
+        relations[name] = hasOne(
+          resolveTableTarget(relation.target, tableMap),
+          relation.foreignKey,
+          relation.localKey,
+          relation.cascade
+        );
+        break;
+      }
       case RelationKinds.HasMany: {
         relations[name] = hasMany(
           resolveTableTarget(relation.target, tableMap),
@@ -2839,6 +4597,7 @@ var selectFromEntity = (ctor) => {
   Column,
   Entity,
   HasMany,
+  HasOne,
   PrimaryKey,
   bootstrapEntities,
   getTableDefFromEntity,