metal-orm 1.1.2 → 1.1.4

package/dist/index.cjs

@@ -55,6 +55,7 @@ __export(index_exports, {
   CPF: () => CPF,
   Capitalize: () => Capitalize,
   Column: () => Column,
+  ConflictBuilder: () => ConflictBuilder,
   ConstructorMaterializationStrategy: () => ConstructorMaterializationStrategy,
   DEFAULT_TREE_CONFIG: () => DEFAULT_TREE_CONFIG,
   DateTimeTypeStrategy: () => DateTimeTypeStrategy,
@@ -87,8 +88,10 @@ __export(index_exports, {
   Pool: () => Pool,
   PostgresDialect: () => PostgresDialect,
   PrimaryKey: () => PrimaryKey,
+  ProcedureCallBuilder: () => ProcedureCallBuilder,
   PrototypeMaterializationStrategy: () => PrototypeMaterializationStrategy,
   QueryCacheManager: () => QueryCacheManager,
+  RedisCacheAdapter: () => RedisCacheAdapter,
   RelationKinds: () => RelationKinds,
   STANDARD_COLUMN_TYPES: () => STANDARD_COLUMN_TYPES,
   SelectQueryBuilder: () => SelectQueryBuilder,
@@ -135,6 +138,7 @@ __export(index_exports, {
   buildScopeConditions: () => buildScopeConditions,
   calculateRowDepths: () => calculateRowDepths,
   calculateTotalPages: () => calculateTotalPages,
+  callProcedure: () => callProcedure,
   canonicalizeSchema: () => canonicalizeSchema,
   caseWhen: () => caseWhen,
   cast: () => cast,
@@ -207,6 +211,7 @@ __export(index_exports, {
   executeHydratedPlain: () => executeHydratedPlain,
   executeHydratedPlainWithContexts: () => executeHydratedPlainWithContexts,
   executeHydratedWithContexts: () => executeHydratedWithContexts,
+  executeProcedureAst: () => executeProcedureAst,
   executeSchemaSql: () => executeSchemaSql,
   executeSchemaSqlFor: () => executeSchemaSqlFor,
   exists: () => exists,
@@ -334,6 +339,7 @@ __export(index_exports, {
   paginationParamsSchema: () => paginationParamsSchema,
   parameterToRef: () => parameterToRef,
   parseDuration: () => parseDuration,
+  payloadResultSets: () => payloadResultSets,
   pi: () => pi,
   pick: () => pick,
   position: () => position,
@@ -393,6 +399,7 @@ __export(index_exports, {
   threadResults: () => threadResults,
   threadedNodeToOpenApiSchema: () => threadedNodeToOpenApiSchema,
   toColumnRef: () => toColumnRef,
+  toExecutionPayload: () => toExecutionPayload,
   toPagedResponse: () => toPagedResponse,
   toPagedResponseBuilder: () => toPagedResponseBuilder,
   toPaginationParams: () => toPaginationParams,
@@ -1834,6 +1841,9 @@ var Dialect = class _Dialect {
       compileDeleteAst() {
         throw new Error("Not implemented");
       }
+      compileProcedureCall() {
+        throw new Error("Not implemented");
+      }
     }
     return new TestDialect(functionStrategy, tableFunctionStrategy);
   }
@@ -2296,8 +2306,14 @@ var SqlDialectBase = class extends Dialect {
     const table = this.compileTableName(ast.into);
     const columnList = this.compileInsertColumnList(ast.columns);
     const source = this.compileInsertSource(ast.source, ctx);
+    const upsert = this.compileUpsertClause(ast, ctx);
     const returning = this.compileReturning(ast.returning, ctx);
-    return `INSERT INTO ${table} (${columnList}) ${source}${returning}`;
+    return `INSERT INTO ${table} (${columnList}) ${source}${upsert}${returning}`;
+  }
+  compileUpsertClause(ast, _ctx) {
+    void _ctx;
+    if (!ast.onConflict) return "";
+    throw new Error(`UPSERT/ON CONFLICT is not supported by dialect "${this.dialect}".`);
   }
   compileReturning(returning, ctx) {
     return this.returningStrategy.compileReturning(returning, ctx);
@@ -2316,6 +2332,11 @@ var SqlDialectBase = class extends Dialect {
   compileInsertColumnList(columns) {
     return columns.map((column) => this.quoteIdentifier(column.name)).join(", ");
   }
+  ensureConflictColumns(clause, message) {
+    if (!clause.target.columns.length) {
+      throw new Error(message);
+    }
+  }
   compileSelectCore(ast, ctx) {
     const columns = this.compileSelectColumns(ast, ctx);
     const from = this.compileFrom(ast.from, ctx);
@@ -2698,9 +2719,52 @@ var PostgresDialect = class extends SqlDialectBase {
     const columns = this.formatReturningColumns(returning);
     return ` RETURNING ${columns}`;
   }
+  compileUpsertClause(ast, ctx) {
+    if (!ast.onConflict) return "";
+    const clause = ast.onConflict;
+    const target = clause.target.constraint ? ` ON CONFLICT ON CONSTRAINT ${this.quoteIdentifier(clause.target.constraint)}` : (() => {
+      this.ensureConflictColumns(
+        clause,
+        "PostgreSQL ON CONFLICT requires conflict columns or a constraint name."
+      );
+      const cols = clause.target.columns.map((col2) => this.quoteIdentifier(col2.name)).join(", ");
+      return ` ON CONFLICT (${cols})`;
+    })();
+    if (clause.action.type === "DoNothing") {
+      return `${target} DO NOTHING`;
+    }
+    if (!clause.action.set.length) {
+      throw new Error("PostgreSQL ON CONFLICT DO UPDATE requires at least one assignment.");
+    }
+    const assignments = this.compileUpdateAssignments(clause.action.set, ast.into, ctx);
+    const where = clause.action.where ? ` WHERE ${this.compileExpression(clause.action.where, ctx)}` : "";
+    return `${target} DO UPDATE SET ${assignments}${where}`;
+  }
   supportsDmlReturningClause() {
     return true;
   }
+  compileProcedureCall(ast) {
+    const ctx = this.createCompilerContext();
+    const qualifiedName = ast.ref.schema ? `${this.quoteIdentifier(ast.ref.schema)}.${this.quoteIdentifier(ast.ref.name)}` : this.quoteIdentifier(ast.ref.name);
+    const args = [];
+    for (const param of ast.params) {
+      if (param.direction === "out") continue;
+      if (!param.value) {
+        throw new Error(`Procedure parameter "${param.name}" requires a value for direction "${param.direction}".`);
+      }
+      args.push(this.compileOperand(param.value, ctx));
+    }
+    const outNames = ast.params.filter((param) => param.direction === "out" || param.direction === "inout").map((param) => param.name);
+    const rawSql = `CALL ${qualifiedName}(${args.join(", ")})`;
+    return {
+      sql: `${rawSql};`,
+      params: [...ctx.params],
+      outParams: {
+        source: outNames.length ? "firstResultSet" : "none",
+        names: outNames
+      }
+    };
+  }
   /**
    * PostgreSQL requires unqualified column names in SET clause
    */
@@ -2800,6 +2864,7 @@ var MysqlFunctionStrategy = class extends StandardFunctionStrategy {
 };
 
 // src/core/dialect/mysql/index.ts
+var sanitizeVariableSuffix = (value) => value.replace(/[^a-zA-Z0-9_]/g, "_");
 var MySqlDialect = class extends SqlDialectBase {
   dialect = "mysql";
   /**
@@ -2825,6 +2890,73 @@ var MySqlDialect = class extends SqlDialectBase {
     const col2 = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
     return `${col2}->'${node.path}'`;
   }
+  compileUpsertClause(ast, ctx) {
+    if (!ast.onConflict) return "";
+    const clause = ast.onConflict;
+    if (clause.action.type === "DoNothing") {
+      const noOpColumn = clause.target.columns[0] ?? ast.columns[0];
+      if (!noOpColumn) {
+        throw new Error("MySQL ON DUPLICATE KEY UPDATE requires at least one target column.");
+      }
+      const col2 = this.quoteIdentifier(noOpColumn.name);
+      return ` ON DUPLICATE KEY UPDATE ${col2} = ${col2}`;
+    }
+    if (clause.action.where) {
+      throw new Error("MySQL ON DUPLICATE KEY UPDATE does not support a WHERE clause.");
+    }
+    if (!clause.action.set.length) {
+      throw new Error("MySQL ON DUPLICATE KEY UPDATE requires at least one assignment.");
+    }
+    const assignments = clause.action.set.map((assignment) => {
+      const target = this.quoteIdentifier(assignment.column.name);
+      const value = this.compileOperand(assignment.value, ctx);
+      return `${target} = ${value}`;
+    }).join(", ");
+    return ` ON DUPLICATE KEY UPDATE ${assignments}`;
+  }
+  compileProcedureCall(ast) {
+    const ctx = this.createCompilerContext();
+    const qualifiedName = ast.ref.schema ? `${this.quoteIdentifier(ast.ref.schema)}.${this.quoteIdentifier(ast.ref.name)}` : this.quoteIdentifier(ast.ref.name);
+    const prelude = [];
+    const callArgs = [];
+    const outVars = [];
+    ast.params.forEach((param, index) => {
+      const suffix = sanitizeVariableSuffix(param.name || `p${index + 1}`);
+      const variable = `@__metal_${suffix}_${index + 1}`;
+      if (param.direction === "in") {
+        if (!param.value) {
+          throw new Error(`Procedure parameter "${param.name}" requires a value for direction "in".`);
+        }
+        callArgs.push(this.compileOperand(param.value, ctx));
+        return;
+      }
+      if (param.direction === "inout") {
+        if (!param.value) {
+          throw new Error(`Procedure parameter "${param.name}" requires a value for direction "inout".`);
+        }
+        prelude.push(`SET ${variable} = ${this.compileOperand(param.value, ctx)};`);
+      }
+      callArgs.push(variable);
+      outVars.push({ variable, name: param.name });
+    });
+    const statements = [];
+    if (prelude.length) {
+      statements.push(...prelude);
+    }
+    statements.push(`CALL ${qualifiedName}(${callArgs.join(", ")});`);
+    if (outVars.length) {
+      const selectOut = outVars.map(({ variable, name }) => `${variable} AS ${this.quoteIdentifier(name)}`).join(", ");
+      statements.push(`SELECT ${selectOut};`);
+    }
+    return {
+      sql: statements.join(" "),
+      params: [...ctx.params],
+      outParams: {
+        source: outVars.length ? "lastResultSet" : "none",
+        names: outVars.map((item) => item.name)
+      }
+    };
+  }
 };
 
 // src/core/dialect/sqlite/functions.ts
@@ -3013,9 +3145,32 @@ var SqliteDialect = class extends SqlDialectBase {
       return `${this.quoteIdentifier(column.name)}${alias}`;
     }).join(", ");
   }
+  compileUpsertClause(ast, ctx) {
+    if (!ast.onConflict) return "";
+    const clause = ast.onConflict;
+    if (clause.target.constraint) {
+      throw new Error("SQLite ON CONFLICT does not support named constraints.");
+    }
+    this.ensureConflictColumns(clause, "SQLite ON CONFLICT requires conflict columns.");
+    const cols = clause.target.columns.map((col2) => this.quoteIdentifier(col2.name)).join(", ");
+    const target = ` ON CONFLICT (${cols})`;
+    if (clause.action.type === "DoNothing") {
+      return `${target} DO NOTHING`;
+    }
+    if (!clause.action.set.length) {
+      throw new Error("SQLite ON CONFLICT DO UPDATE requires at least one assignment.");
+    }
+    const assignments = this.compileUpdateAssignments(clause.action.set, ast.into, ctx);
+    const where = clause.action.where ? ` WHERE ${this.compileExpression(clause.action.where, ctx)}` : "";
+    return `${target} DO UPDATE SET ${assignments}${where}`;
+  }
   supportsDmlReturningClause() {
     return true;
   }
+  compileProcedureCall(_ast) {
+    void _ast;
+    throw new Error("Stored procedures are not supported by the SQLite dialect.");
+  }
 };
 
 // src/core/dialect/mssql/functions.ts
@@ -3134,6 +3289,8 @@ var MssqlFunctionStrategy = class extends StandardFunctionStrategy {
 };
 
 // src/core/dialect/mssql/index.ts
+var sanitizeVariableSuffix2 = (value) => value.replace(/[^a-zA-Z0-9_]/g, "_");
+var toProcedureParamReference = (value) => value.startsWith("@") ? value : `@${value}`;
 var SqlServerDialect = class extends SqlDialectBase {
   dialect = "mssql";
   /**
@@ -3289,12 +3446,58 @@ var SqlServerDialect = class extends SqlDialectBase {
     if (!ast.columns.length) {
       throw new Error("INSERT queries must specify columns.");
     }
+    if (ast.onConflict) {
+      return this.compileMergeInsert(ast, ctx);
+    }
     const table = this.compileTableName(ast.into);
     const columnList = ast.columns.map((column) => this.quoteIdentifier(column.name)).join(", ");
     const output = this.compileReturning(ast.returning, ctx);
     const source = this.compileInsertValues(ast, ctx);
     return `INSERT INTO ${table} (${columnList})${output} ${source}`;
   }
+  compileMergeInsert(ast, ctx) {
+    const clause = ast.onConflict;
+    if (clause.target.constraint) {
+      throw new Error("MSSQL MERGE does not support conflict target by constraint name.");
+    }
+    this.ensureConflictColumns(clause, "MSSQL MERGE requires conflict columns for the ON clause.");
+    const table = this.compileTableName(ast.into);
+    const targetRef = this.quoteIdentifier(ast.into.alias ?? ast.into.name);
+    const sourceAlias = this.quoteIdentifier("src");
+    const sourceColumns = ast.columns.map((column) => this.quoteIdentifier(column.name)).join(", ");
+    const usingSource = this.compileMergeUsingSource(ast, ctx);
+    const onClause = clause.target.columns.map((column) => `${targetRef}.${this.quoteIdentifier(column.name)} = ${sourceAlias}.${this.quoteIdentifier(column.name)}`).join(" AND ");
+    const branches = [];
+    if (clause.action.type === "DoUpdate") {
+      if (!clause.action.set.length) {
+        throw new Error("MSSQL MERGE WHEN MATCHED UPDATE requires at least one assignment.");
+      }
+      const assignments = clause.action.set.map((assignment) => {
+        const target = `${targetRef}.${this.quoteIdentifier(assignment.column.name)}`;
+        const value = this.compileOperand(assignment.value, ctx);
+        return `${target} = ${value}`;
+      }).join(", ");
+      const guard = clause.action.where ? ` AND ${this.compileExpression(clause.action.where, ctx)}` : "";
+      branches.push(`WHEN MATCHED${guard} THEN UPDATE SET ${assignments}`);
+    }
+    const insertColumns = ast.columns.map((column) => this.quoteIdentifier(column.name)).join(", ");
+    const insertValues = ast.columns.map((column) => `${sourceAlias}.${this.quoteIdentifier(column.name)}`).join(", ");
+    branches.push(`WHEN NOT MATCHED THEN INSERT (${insertColumns}) VALUES (${insertValues})`);
+    const output = this.compileReturning(ast.returning, ctx);
+    return `MERGE INTO ${table} USING ${usingSource} AS ${sourceAlias} (${sourceColumns}) ON ${onClause} ${branches.join(" ")}${output}`;
+  }
+  compileMergeUsingSource(ast, ctx) {
+    if (ast.source.type === "InsertValues") {
+      if (!ast.source.rows.length) {
+        throw new Error("INSERT ... VALUES requires at least one row.");
+      }
+      const rows = ast.source.rows.map((row) => `(${row.map((value) => this.compileOperand(value, ctx)).join(", ")})`).join(", ");
+      return `(VALUES ${rows})`;
+    }
+    const normalized = this.normalizeSelectAst(ast.source.query);
+    const selectSql = this.compileSelectAst(normalized, ctx).trim().replace(/;$/, "");
+    return `(${selectSql})`;
+  }
   compileInsertValues(ast, ctx) {
     const source = ast.source;
     if (source.type === "InsertValues") {
@@ -3317,6 +3520,57 @@ var SqlServerDialect = class extends SqlDialectBase {
     }).join(", ");
     return `WITH ${defs} `;
   }
+  compileProcedureCall(ast) {
+    const ctx = this.createCompilerContext();
+    const qualifiedName = ast.ref.schema ? `${this.quoteIdentifier(ast.ref.schema)}.${this.quoteIdentifier(ast.ref.name)}` : this.quoteIdentifier(ast.ref.name);
+    const declarations = [];
+    const assignments = [];
+    const execArgs = [];
+    const outVars = [];
+    ast.params.forEach((param, index) => {
+      const targetParam = toProcedureParamReference(param.name);
+      if (param.direction === "in") {
+        if (!param.value) {
+          throw new Error(`Procedure parameter "${param.name}" requires a value for direction "in".`);
+        }
+        execArgs.push(`${targetParam} = ${this.compileOperand(param.value, ctx)}`);
+        return;
+      }
+      if (!param.dbType) {
+        throw new Error(
+          `MSSQL procedure parameter "${param.name}" requires "dbType" for direction "${param.direction}".`
+        );
+      }
+      const suffix = sanitizeVariableSuffix2(param.name || `p${index + 1}`);
+      const variable = `@__metal_${suffix}_${index + 1}`;
+      declarations.push(`DECLARE ${variable} ${param.dbType};`);
+      if (param.direction === "inout") {
+        if (!param.value) {
+          throw new Error(`Procedure parameter "${param.name}" requires a value for direction "inout".`);
+        }
+        assignments.push(`SET ${variable} = ${this.compileOperand(param.value, ctx)};`);
+      }
+      execArgs.push(`${targetParam} = ${variable} OUTPUT`);
+      outVars.push({ variable, name: param.name });
+    });
+    const statements = [];
+    if (declarations.length) statements.push(...declarations);
+    if (assignments.length) statements.push(...assignments);
+    const argsSql = execArgs.length ? ` ${execArgs.join(", ")}` : "";
+    statements.push(`EXEC ${qualifiedName}${argsSql};`);
+    if (outVars.length) {
+      const selectOut = outVars.map(({ variable, name }) => `${variable} AS ${this.quoteIdentifier(name)}`).join(", ");
+      statements.push(`SELECT ${selectOut};`);
+    }
+    return {
+      sql: statements.join(" "),
+      params: [...ctx.params],
+      outParams: {
+        source: outVars.length ? "lastResultSet" : "none",
+        names: outVars.map((item) => item.name)
+      }
+    };
+  }
 };
 
 // src/core/dialect/dialect-factory.ts
@@ -7022,6 +7276,56 @@ var preloadRelationIncludes = async (entities, includeTree, depth = 0) => {
   }
 };
 
+// src/core/execution/db-executor.ts
+var toExecutionPayload = (resultSets) => {
+  const payload = resultSets;
+  payload.resultSets = resultSets;
+  return payload;
+};
+var payloadResultSets = (payload) => payload.resultSets ?? payload;
+function rowsToQueryResult(rows) {
+  if (rows.length === 0) {
+    return { columns: [], values: [] };
+  }
+  const columns = Object.keys(rows[0]);
+  const values = rows.map((row) => columns.map((c) => row[c]));
+  return { columns, values };
+}
+function createExecutorFromQueryRunner(runner) {
+  const supportsTransactions = typeof runner.beginTransaction === "function" && typeof runner.commitTransaction === "function" && typeof runner.rollbackTransaction === "function";
+  return {
+    capabilities: {
+      transactions: supportsTransactions
+    },
+    async executeSql(sql, params) {
+      const rows = await runner.query(sql, params);
+      const result = rowsToQueryResult(rows);
+      return toExecutionPayload([result]);
+    },
+    async beginTransaction() {
+      if (!supportsTransactions) {
+        throw new Error("Transactions are not supported by this executor");
+      }
+      await runner.beginTransaction.call(runner);
+    },
+    async commitTransaction() {
+      if (!supportsTransactions) {
+        throw new Error("Transactions are not supported by this executor");
+      }
+      await runner.commitTransaction.call(runner);
+    },
+    async rollbackTransaction() {
+      if (!supportsTransactions) {
+        throw new Error("Transactions are not supported by this executor");
+      }
+      await runner.rollbackTransaction.call(runner);
+    },
+    async dispose() {
+      await runner.dispose?.call(runner);
+    }
+  };
+}
+
 // src/orm/execute.ts
 var flattenResults = (results) => {
   const rows = [];
@@ -7041,7 +7345,7 @@ var executeWithContexts = async (execCtx, entityCtx, qb) => {
   const ast = qb.getAST();
   const compiled = execCtx.dialect.compileSelect(ast);
   const executed = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
-  const rows = flattenResults(executed);
+  const rows = flattenResults(payloadResultSets(executed));
   const lazyRelations = qb.getLazyRelations();
   const lazyRelationOptions = qb.getLazyRelationOptions();
   const includeTree = qb.getIncludeTree();
@@ -7061,7 +7365,7 @@ var executePlainWithContexts = async (execCtx, qb) => {
   const ast = qb.getAST();
   const compiled = execCtx.dialect.compileSelect(ast);
   const executed = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
-  const rows = flattenResults(executed);
+  const rows = flattenResults(payloadResultSets(executed));
   if (ast.setOps && ast.setOps.length > 0) {
     return rows;
   }
@@ -7329,7 +7633,8 @@ async function executeCount(context, env, session) {
   };
   const execCtx = session.getExecutionContext();
   const compiled = execCtx.dialect.compileSelect(countQuery);
-  const results = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+  const payload = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+  const results = payloadResultSets(payload);
   const value = results[0]?.values?.[0]?.[0];
   if (typeof value === "number") return value;
   if (typeof value === "bigint") return Number(value);
@@ -7361,7 +7666,8 @@ async function executeCountRows(context, env, session) {
   };
   const execCtx = session.getExecutionContext();
   const compiled = execCtx.dialect.compileSelect(countQuery);
-  const results = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+  const payload = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+  const results = payloadResultSets(payload);
   const value = results[0]?.values?.[0]?.[0];
   if (typeof value === "number") return value;
   if (typeof value === "bigint") return Number(value);
@@ -8335,6 +8641,45 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * // rows is EntityInstance<UserTable>[] (plain objects)
    * rows[0] instanceof User; // false
    */
+  /**
+   * Executes the query with LIMIT 1 and returns the first result.
+   * Throws if no record is found.
+   *
+   * @param ctx - ORM session context
+   * @returns Promise of a single entity instance
+   * @throws Error if no results are found
+   * @example
+   * const user = await selectFromEntity(User)
+   *   .where(eq(users.email, 'alice@example.com'))
+   *   .firstOrFail(session);
+   */
+  async firstOrFail(ctx) {
+    const rows = await this.limit(1).execute(ctx);
+    if (rows.length === 0) {
+      throw new Error("No results found");
+    }
+    return rows[0];
+  }
+  /**
+   * Executes the query with LIMIT 1 and returns the first result as a plain object (POJO).
+   * Throws if no record is found.
+   *
+   * @param ctx - ORM session context
+   * @returns Promise of a single plain object
+   * @throws Error if no results are found
+   * @example
+   * const user = await selectFromEntity(User)
+   *   .where(eq(users.email, 'alice@example.com'))
+   *   .firstOrFailPlain(session);
+   * // user is a plain object, not an instance of User
+   */
+  async firstOrFailPlain(ctx) {
+    const rows = await this.limit(1).executePlain(ctx);
+    if (rows.length === 0) {
+      throw new Error("No results found");
+    }
+    return rows[0];
+  }
   async executePlain(ctx) {
     const builder = this.ensureDefaultSelection();
     const rows = await executeHydratedPlain(ctx, builder);
@@ -9034,9 +9379,95 @@ var InsertQueryState = class _InsertQueryState {
       returning: [...columns]
     });
   }
+  /**
+   * Adds an UPSERT conflict clause to the INSERT query
+   * @param clause - Conflict clause and action
+   * @returns A new InsertQueryState with conflict handling configured
+   */
+  withOnConflict(clause) {
+    return this.clone({
+      ...this.ast,
+      onConflict: {
+        target: {
+          columns: [...clause.target.columns],
+          constraint: clause.target.constraint
+        },
+        action: clause.action.type === "DoUpdate" ? {
+          type: "DoUpdate",
+          set: clause.action.set.map((assignment) => ({
+            column: { ...assignment.column },
+            value: assignment.value
+          })),
+          where: clause.action.where
+        } : { type: "DoNothing" }
+      }
+    });
+  }
 };
 
 // src/query-builder/insert.ts
+var ConflictBuilder = class {
+  table;
+  columns;
+  constraint;
+  applyClause;
+  constructor(table, columns, constraint, applyClause) {
+    this.table = table;
+    this.columns = columns;
+    this.constraint = constraint;
+    this.applyClause = applyClause;
+  }
+  /**
+   * Adds ON CONFLICT ... DO UPDATE
+   * @param set - Column assignments for update branch
+   * @param where - Optional filter for update branch
+   * @returns InsertQueryBuilder with the upsert clause configured
+   */
+  doUpdate(set, where) {
+    const assignments = this.buildAssignments(set);
+    return this.applyClause({
+      target: this.buildTarget(),
+      action: {
+        type: "DoUpdate",
+        set: assignments,
+        where
+      }
+    });
+  }
+  /**
+   * Adds ON CONFLICT ... DO NOTHING
+   * @returns InsertQueryBuilder with the upsert clause configured
+   */
+  doNothing() {
+    return this.applyClause({
+      target: this.buildTarget(),
+      action: { type: "DoNothing" }
+    });
+  }
+  buildTarget() {
+    return {
+      columns: [...this.columns],
+      constraint: this.constraint
+    };
+  }
+  buildAssignments(set) {
+    const entries = Object.entries(set);
+    if (!entries.length) {
+      throw new Error("ON CONFLICT DO UPDATE requires at least one assignment.");
+    }
+    return entries.map(([columnName, rawValue]) => {
+      if (!isValueOperandInput(rawValue)) {
+        throw new Error(
+          `Invalid upsert value for column "${columnName}": only string, number, boolean, Date, Buffer, null, or OperandNodes are allowed`
+        );
+      }
+      return {
+        column: buildColumnNode(this.table, { name: columnName, table: this.table.name }),
+        value: valueToOperand(rawValue)
+      };
+    });
+  }
+};
 var InsertQueryBuilder = class _InsertQueryBuilder {
   table;
   state;
@@ -9052,6 +9483,9 @@ var InsertQueryBuilder = class _InsertQueryBuilder {
   clone(state) {
     return new _InsertQueryBuilder(this.table, state);
   }
+  withOnConflict(clause) {
+    return this.clone(this.state.withOnConflict(clause));
+  }
   /**
    * Adds VALUES to the INSERT query
    * @param rowOrRows - Single row object or array of row objects to insert
@@ -9083,6 +9517,21 @@ var InsertQueryBuilder = class _InsertQueryBuilder {
     const nodes = columns.length ? this.resolveColumnNodes(columns) : [];
     return this.clone(this.state.withSelect(ast, nodes));
   }
+  /**
+   * Configures UPSERT conflict handling for INSERT.
+   * @param columns - Conflict target columns (ignored by MySQL)
+   * @param constraint - Named unique/primary constraint (PostgreSQL only)
+   * @returns ConflictBuilder for selecting action (DO UPDATE / DO NOTHING)
+   */
+  onConflict(columns = [], constraint) {
+    const resolvedColumns = columns.length ? this.resolveColumnNodes(columns) : [];
+    return new ConflictBuilder(
+      this.table,
+      resolvedColumns,
+      constraint,
+      (clause) => this.withOnConflict(clause)
+    );
+  }
   /**
    * Adds a RETURNING clause to the INSERT query
    * @param columns - Columns to return after insertion
@@ -9360,7 +9809,8 @@ var UpdateQueryBuilder = class _UpdateQueryBuilder {
   async execute(session) {
     const execCtx = session.getExecutionContext();
     const compiled = this.compile(execCtx.dialect);
-    return execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+    const payload = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+    return payloadResultSets(payload);
   }
   /**
    * Returns the Abstract Syntax Tree (AST) representation of the query
@@ -9550,7 +10000,8 @@ var DeleteQueryBuilder = class _DeleteQueryBuilder {
   async execute(session) {
     const execCtx = session.getExecutionContext();
     const compiled = this.compile(execCtx.dialect);
-    return execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+    const payload = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+    return payloadResultSets(payload);
   }
   /**
    * Returns the Abstract Syntax Tree (AST) representation of the query
@@ -9562,6 +10013,149 @@ var DeleteQueryBuilder = class _DeleteQueryBuilder {
 };
 var isTableSourceNode2 = (source) => typeof source.type === "string";
 
+// src/orm/execute-procedure.ts
+var resolveColumnIndex = (columns, expectedName) => {
+  const exact = columns.findIndex((column) => column === expectedName);
+  if (exact >= 0) return exact;
+  const lowerExpected = expectedName.toLowerCase();
+  return columns.findIndex((column) => column.toLowerCase() === lowerExpected);
+};
+var extractOutValues = (compiled, resultSets) => {
+  if (!compiled.outParams.names.length || compiled.outParams.source === "none") {
+    return {};
+  }
+  const sourceSet = compiled.outParams.source === "firstResultSet" ? resultSets[0] : resultSets[resultSets.length - 1];
+  if (!sourceSet) {
+    throw new Error(
+      `Procedure expected OUT parameters in ${compiled.outParams.source}, but no result set was returned.`
+    );
+  }
+  if (!sourceSet.values.length) {
+    throw new Error(
+      `Procedure expected OUT parameters in ${compiled.outParams.source}, but the result set has no rows.`
+    );
+  }
+  const firstRow = sourceSet.values[0];
+  const out = {};
+  for (const expectedName of compiled.outParams.names) {
+    const columnIndex = resolveColumnIndex(sourceSet.columns, expectedName);
+    if (columnIndex < 0) {
+      const available = sourceSet.columns.length ? sourceSet.columns.join(", ") : "(none)";
+      throw new Error(
+        `Procedure OUT parameter "${expectedName}" was not found in ${compiled.outParams.source}. Available columns: ${available}.`
+      );
+    }
+    out[expectedName] = firstRow[columnIndex];
+  }
+  return out;
+};
+var executeProcedureAst = async (session, ast) => {
+  const execCtx = session.getExecutionContext();
+  const compiled = execCtx.dialect.compileProcedureCall(ast);
+  const payload = await execCtx.interceptors.run(
+    { sql: compiled.sql, params: compiled.params },
+    execCtx.executor
+  );
+  const resultSets = payloadResultSets(payload);
+  return {
+    resultSets,
+    out: extractOutValues(compiled, resultSets)
+  };
+};
+
+// src/query-builder/procedure-call.ts
+var cloneParam = (param) => ({
+  ...param,
+  value: param.value ? { ...param.value } : void 0
+});
+var ProcedureCallBuilder = class _ProcedureCallBuilder {
+  ast;
+  constructor(name, options, ast) {
+    this.ast = ast ?? {
+      type: "ProcedureCall",
+      ref: {
+        name,
+        schema: options?.schema
+      },
+      params: []
+    };
+  }
+  clone(nextParams) {
+    return new _ProcedureCallBuilder(
+      this.ast.ref.name,
+      { schema: this.ast.ref.schema },
+      {
+        ...this.ast,
+        ref: { ...this.ast.ref },
+        params: nextParams
+      }
+    );
+  }
+  in(name, value) {
+    return this.clone([
+      ...this.ast.params.map(cloneParam),
+      {
+        name,
+        direction: "in",
+        value: valueToOperand(value)
+      }
+    ]);
+  }
+  out(name, options) {
+    return this.clone([
+      ...this.ast.params.map(cloneParam),
+      {
+        name,
+        direction: "out",
+        dbType: options?.dbType
+      }
+    ]);
+  }
+  inOut(name, value, options) {
+    return this.clone([
+      ...this.ast.params.map(cloneParam),
+      {
+        name,
+        direction: "inout",
+        value: valueToOperand(value),
+        dbType: options?.dbType
+      }
+    ]);
+  }
+  compile(dialect) {
+    const resolved = resolveDialectInput(dialect);
+    this.validateMssqlOutDbType(resolved);
+    return resolved.compileProcedureCall(this.getAST());
+  }
+  toSql(dialect) {
+    return this.compile(dialect).sql;
+  }
+  getAST() {
+    return {
+      ...this.ast,
+      ref: { ...this.ast.ref },
+      params: this.ast.params.map(cloneParam)
+    };
+  }
+  async execute(session) {
+    this.validateMssqlOutDbType(session.getExecutionContext().dialect);
+    return executeProcedureAst(session, this.getAST());
+  }
+  validateMssqlOutDbType(dialect) {
+    const isMssqlDialect = dialect.constructor.name === "SqlServerDialect";
+    if (!isMssqlDialect) return;
+    for (const param of this.ast.params) {
+      const needsDbType = param.direction === "out" || param.direction === "inout";
+      if (needsDbType && !param.dbType) {
+        throw new Error(
+          `MSSQL requires "dbType" for procedure parameter "${param.name}" with direction "${param.direction}".`
+        );
+      }
+    }
+  }
+};
+var callProcedure = (name, options) => new ProcedureCallBuilder(name, options);
+
 // src/query/target.ts
 var resolveEntityTarget = (ctor) => {
   const table = getTableDefFromEntity(ctor);
@@ -12740,7 +13334,8 @@ var UnitOfWork = class {
    * @returns Query results
    */
   async executeCompiled(compiled) {
-    return this.executor.executeSql(compiled.sql, compiled.params);
+    const payload = await this.executor.executeSql(compiled.sql, compiled.params);
+    return payloadResultSets(payload);
   }
   /**
    * Gets columns for RETURNING clause.
@@ -13884,9 +14479,9 @@ var InterceptorPipeline = class {
     const dispatch = async () => {
       const interceptor = this.interceptors[i++];
       if (!interceptor) {
-        return executor.executeSql(ctx.sql, ctx.params);
+        return toExecutionPayload(await executor.executeSql(ctx.sql, ctx.params));
       }
-      return interceptor(ctx, dispatch);
+      return toExecutionPayload(await interceptor(ctx, dispatch));
     };
     return dispatch();
   }
@@ -14009,6 +14604,11 @@ function isValidDuration(value) {
 // src/cache/adapters/memory-cache-adapter.ts
 var MemoryCacheAdapter = class {
   name = "memory";
+  capabilities = {
+    tags: true,
+    prefix: true,
+    ttl: true
+  };
   storage = /* @__PURE__ */ new Map();
   tagIndex = /* @__PURE__ */ new Map();
   async get(key) {
@@ -15135,50 +15735,6 @@ function CEP(options) {
   };
 }
 
-// src/core/execution/db-executor.ts
-function rowsToQueryResult(rows) {
-  if (rows.length === 0) {
-    return { columns: [], values: [] };
-  }
-  const columns = Object.keys(rows[0]);
-  const values = rows.map((row) => columns.map((c) => row[c]));
-  return { columns, values };
-}
-function createExecutorFromQueryRunner(runner) {
-  const supportsTransactions = typeof runner.beginTransaction === "function" && typeof runner.commitTransaction === "function" && typeof runner.rollbackTransaction === "function";
-  return {
-    capabilities: {
-      transactions: supportsTransactions
-    },
-    async executeSql(sql, params) {
-      const rows = await runner.query(sql, params);
-      const result = rowsToQueryResult(rows);
-      return [result];
-    },
-    async beginTransaction() {
-      if (!supportsTransactions) {
-        throw new Error("Transactions are not supported by this executor");
-      }
-      await runner.beginTransaction.call(runner);
-    },
-    async commitTransaction() {
-      if (!supportsTransactions) {
-        throw new Error("Transactions are not supported by this executor");
-      }
-      await runner.commitTransaction.call(runner);
-    },
-    async rollbackTransaction() {
-      if (!supportsTransactions) {
-        throw new Error("Transactions are not supported by this executor");
-      }
-      await runner.rollbackTransaction.call(runner);
-    },
-    async dispose() {
-      await runner.dispose?.call(runner);
-    }
-  };
-}
-
 // src/core/execution/pooling/pool.ts
 var deferred = () => {
   let resolve;
@@ -15406,6 +15962,36 @@ function createPostgresExecutor(client) {
 }
 
 // src/core/execution/executors/mysql-executor.ts
+var isRowObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isRowObjectArray = (value) => Array.isArray(value) && value.every(isRowObject);
+var isMysqlResultHeader = (value) => isRowObject(value) && ("affectedRows" in value || "insertId" in value || "warningStatus" in value || "serverStatus" in value);
+var headerToQueryResult = (header) => ({
+  columns: [],
+  values: [],
+  meta: {
+    insertId: header.insertId,
+    rowsAffected: header.affectedRows
+  }
+});
+var normalizeMysqlResults = (rows) => {
+  if (!Array.isArray(rows)) {
+    return isMysqlResultHeader(rows) ? [headerToQueryResult(rows)] : [rowsToQueryResult([])];
+  }
+  if (isRowObjectArray(rows)) {
+    return [rowsToQueryResult(rows)];
+  }
+  const normalized = [];
+  for (const chunk of rows) {
+    if (isRowObjectArray(chunk)) {
+      normalized.push(rowsToQueryResult(chunk));
+      continue;
+    }
+    if (isMysqlResultHeader(chunk)) {
+      normalized.push(headerToQueryResult(chunk));
+    }
+  }
+  return normalized.length ? normalized : [rowsToQueryResult([])];
+};
 function createMysqlExecutor(client) {
   const supportsTransactions = typeof client.beginTransaction === "function" && typeof client.commit === "function" && typeof client.rollback === "function";
   return {
@@ -15414,21 +16000,7 @@ function createMysqlExecutor(client) {
     },
     async executeSql(sql, params) {
       const [rows] = await client.query(sql, params);
-      if (!Array.isArray(rows)) {
-        const header = rows;
-        return [{
-          columns: [],
-          values: [],
-          meta: {
-            insertId: header.insertId,
-            rowsAffected: header.affectedRows
-          }
-        }];
-      }
-      const result = rowsToQueryResult(
-        rows
-      );
-      return [result];
+      return toExecutionPayload(normalizeMysqlResults(rows));
     },
     async beginTransaction() {
       if (!supportsTransactions) {
@@ -15463,7 +16035,7 @@ function createSqliteExecutor(client) {
     async executeSql(sql, params) {
       const rows = await client.all(sql, params);
       const result = rowsToQueryResult(rows);
-      return [result];
+      return toExecutionPayload([result]);
     },
     async beginTransaction() {
       if (!supportsTransactions) {
@@ -15496,9 +16068,9 @@ function createMssqlExecutor(client) {
       transactions: supportsTransactions
     },
     async executeSql(sql, params) {
-      const { recordset } = await client.query(sql, params);
-      const result = rowsToQueryResult(recordset ?? []);
-      return [result];
+      const { recordset, recordsets } = await client.query(sql, params);
+      const sets = Array.isArray(recordsets) ? recordsets : [recordset ?? []];
+      return toExecutionPayload(sets.map((set) => rowsToQueryResult(set ?? [])));
     },
     async beginTransaction() {
       if (!supportsTransactions) {
@@ -15564,7 +16136,7 @@ function createTediousMssqlClient(connection, { Request, TYPES }, options) {
           connection.execSql(request);
         }
       );
-      return { recordset: rows };
+      return { recordset: rows, recordsets: [rows] };
     },
     beginTransaction: connection.beginTransaction ? () => new Promise((resolve, reject) => {
       connection.beginTransaction(
@@ -15589,6 +16161,8 @@ function createTediousExecutor(connection, module2, options) {
 }
 
 // src/orm/pooled-executor-factory.ts
+var isQueryResult = (value) => typeof value === "object" && value !== null && Array.isArray(value.columns) && Array.isArray(value.values);
+var isRowArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "object" && item !== null && !Array.isArray(item));
 function createPooledExecutorFactory(opts) {
   const { pool, adapter } = opts;
   const makeExecutor = (mode) => {
@@ -15600,7 +16174,13 @@ function createPooledExecutorFactory(opts) {
     };
     const executeWithConn = async (conn, sql, params) => {
       const rows = await adapter.query(conn, sql, params);
-      return [rowsToQueryResult(rows)];
+      if (Array.isArray(rows) && rows.length > 0 && rows.every(isQueryResult)) {
+        return toExecutionPayload(rows);
+      }
+      if (Array.isArray(rows) && rows.length > 0 && rows.every(isRowArray)) {
+        return toExecutionPayload(rows.map((set) => rowsToQueryResult(set)));
+      }
+      return toExecutionPayload([rowsToQueryResult(rows)]);
     };
     return {
       capabilities: { transactions: true },
@@ -18862,6 +19442,11 @@ var KeyvCacheAdapter = class {
     this.keyv = keyv;
   }
   name = "keyv";
+  capabilities = {
+    tags: false,
+    prefix: true,
+    ttl: true
+  };
   async get(key) {
     return this.keyv.get(key);
   }
@@ -18905,6 +19490,152 @@ var KeyvCacheAdapter = class {
   }
 };
 
+// src/cache/adapters/redis-cache-adapter.ts
+var RedisCacheAdapter = class {
+  name = "redis";
+  capabilities = {
+    tags: true,
+    prefix: true,
+    ttl: true
+  };
+  redis;
+  ownsConnection;
+  tagPrefix;
+  /**
+   * Cria um adapter Redis
+   * 
+   * @param redis - Instância do ioredis OU opções de conexão
+   * @param options - Opções adicionais
+   * @param options.tagPrefix - Prefixo para chaves de tag (default: 'tag:')
+   * 
+   * Exemplos:
+   * 
+   * // Com instância existente (recomendado para connection pooling):
+   * const redis = new Redis({ host: 'localhost', port: 6379 });
+   * const adapter = new RedisCacheAdapter(redis);
+   * 
+   * // Com opções (adapter gerencia conexão):
+   * const adapter = new RedisCacheAdapter({ host: 'localhost', port: 6379 });
+   * 
+   * // Para testes com ioredis-mock:
+   * import Redis from 'ioredis-mock';
+   * const adapter = new RedisCacheAdapter(new Redis());
+   */
+  constructor(redis, options) {
+    this.tagPrefix = options?.tagPrefix ?? "tag:";
+    if (this.isRedisInstance(redis)) {
+      this.redis = redis;
+      this.ownsConnection = false;
+    } else {
+      this.redis = this.createRedis(redis);
+      this.ownsConnection = true;
+    }
+  }
+  isRedisInstance(obj) {
+    return typeof obj === "object" && obj !== null && "get" in obj && "set" in obj && "del" in obj && typeof obj.get === "function";
+  }
+  createRedis(options) {
+    try {
+      const Redis = require("ioredis");
+      return new Redis(options);
+    } catch {
+      throw new Error(
+        "ioredis is required for RedisCacheAdapter. Install it with: npm install ioredis"
+      );
+    }
+  }
+  async get(key) {
+    const value = await this.redis.get(key);
+    if (value === null) {
+      return void 0;
+    }
+    try {
+      return JSON.parse(value);
+    } catch {
+      return void 0;
+    }
+  }
+  async has(key) {
+    const value = await this.redis.get(key);
+    return value !== null;
+  }
+  async set(key, value, ttlMs, tags) {
+    const serialized = JSON.stringify(value);
+    if (ttlMs) {
+      await this.redis.set(key, serialized, "PX", ttlMs);
+    } else {
+      await this.redis.set(key, serialized);
+    }
+    if (tags && tags.length > 0) {
+      await this.registerTags(key, tags);
+    }
+  }
+  async delete(key) {
+    await this.redis.del(key);
+  }
+  async invalidate(key) {
+    await this.delete(key);
+  }
+  async invalidateTags(tags) {
+    const keysToDelete = /* @__PURE__ */ new Set();
+    for (const tag of tags) {
+      const tagKey = `${this.tagPrefix}${tag}`;
+      const keys = await this.redis.smembers(tagKey);
+      for (const key of keys) {
+        keysToDelete.add(key);
+      }
+      await this.redis.del(tagKey);
+    }
+    if (keysToDelete.size > 0) {
+      await this.redis.del(...Array.from(keysToDelete));
+    }
+  }
+  async invalidatePrefix(prefix) {
+    const keysToDelete = [];
+    let cursor = "0";
+    do {
+      const [nextCursor, keys] = await this.redis.scan(
+        cursor,
+        "MATCH",
+        `${prefix}*`,
+        "COUNT",
+        100
+      );
+      cursor = nextCursor;
+      keysToDelete.push(...keys);
+    } while (cursor !== "0");
+    if (keysToDelete.length > 0) {
+      const batchSize = 1e3;
+      for (let i = 0; i < keysToDelete.length; i += batchSize) {
+        const batch = keysToDelete.slice(i, i + batchSize);
+        await this.redis.del(...batch);
+      }
+    }
+  }
+  async registerTags(key, tags) {
+    for (const tag of tags) {
+      const tagKey = `${this.tagPrefix}${tag}`;
+      await this.redis.sadd(tagKey, key);
+    }
+  }
+  async dispose() {
+    if (this.ownsConnection) {
+      try {
+        await this.redis.quit();
+      } catch {
+        this.redis.disconnect?.();
+      }
+    }
+  }
+  /**
+   * Retorna a instância Redis subjacente
+   * Útil para operações avançadas ou health checks
+   */
+  getRedis() {
+    return this.redis;
+  }
+};
+
 // src/cache/tag-index.ts
 var TagIndex = class {
   tagToKeys = /* @__PURE__ */ new Map();
@@ -19025,6 +19756,7 @@ var TagIndex = class {
   CPF,
   Capitalize,
   Column,
+  ConflictBuilder,
   ConstructorMaterializationStrategy,
   DEFAULT_TREE_CONFIG,
   DateTimeTypeStrategy,
@@ -19057,8 +19789,10 @@ var TagIndex = class {
   Pool,
   PostgresDialect,
   PrimaryKey,
+  ProcedureCallBuilder,
   PrototypeMaterializationStrategy,
   QueryCacheManager,
+  RedisCacheAdapter,
   RelationKinds,
   STANDARD_COLUMN_TYPES,
   SelectQueryBuilder,
@@ -19105,6 +19839,7 @@ var TagIndex = class {
   buildScopeConditions,
   calculateRowDepths,
   calculateTotalPages,
+  callProcedure,
   canonicalizeSchema,
   caseWhen,
   cast,
@@ -19177,6 +19912,7 @@ var TagIndex = class {
   executeHydratedPlain,
   executeHydratedPlainWithContexts,
   executeHydratedWithContexts,
+  executeProcedureAst,
   executeSchemaSql,
   executeSchemaSqlFor,
   exists,
@@ -19304,6 +20040,7 @@ var TagIndex = class {
   paginationParamsSchema,
   parameterToRef,
   parseDuration,
+  payloadResultSets,
   pi,
   pick,
   position,
@@ -19363,6 +20100,7 @@ var TagIndex = class {
   threadResults,
   threadedNodeToOpenApiSchema,
   toColumnRef,
+  toExecutionPayload,
   toPagedResponse,
   toPagedResponseBuilder,
   toPaginationParams,