metal-orm 1.1.3 → 1.1.4

package/src/core/execution/db-executor.ts

@@ -1,6 +1,6 @@
-// src/core/execution/db-executor.ts
-
-// low-level canonical shape
+// src/core/execution/db-executor.ts
+
+// low-level canonical shape
 export type QueryResult = {
   columns: string[];
   values: unknown[][];
@@ -10,98 +10,116 @@ export type QueryResult = {
   };
 };
 
-export interface DbExecutor {
-  /** Capability flags so the runtime can make correct decisions without relying on optional methods. */
-  readonly capabilities: {
-    /** True if begin/commit/rollback are real and should be used to provide atomicity. */
-    transactions: boolean;
-  };
-
-  executeSql(sql: string, params?: unknown[]): Promise<QueryResult[]>;
-
-  beginTransaction(): Promise<void>;
-  commitTransaction(): Promise<void>;
-  rollbackTransaction(): Promise<void>;
-
-  /** Release any underlying resources (connections, pool leases, etc). Must be idempotent. */
-  dispose(): Promise<void>;
-}
-
-// --- helpers ---
-
-/**
- * Convert an array of row objects into a QueryResult.
- */
-export function rowsToQueryResult(
-  rows: Array<Record<string, unknown>>
-): QueryResult {
-  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 };
-}
-
 /**
- * Minimal contract that most SQL clients can implement.
+ * Canonical execution payload.
+ * It remains array-compatible for a gradual migration but always exposes
+ * `resultSets` for explicit multi-result handling.
  */
-export interface SimpleQueryRunner {
-  query(
-    sql: string,
-    params?: unknown[]
-  ): Promise<Array<Record<string, unknown>>>;
-
-  /** Optional: used to support real transactions. */
-  beginTransaction?(): Promise<void>;
-  commitTransaction?(): Promise<void>;
-  rollbackTransaction?(): Promise<void>;
-
-  /** Optional: release resources (connection close, pool lease release, etc). */
-  dispose?(): Promise<void>;
-}
+export type ExecutionPayload = QueryResult[] & {
+  resultSets?: QueryResult[];
+};
 
-/**
- * Generic factory: turn any SimpleQueryRunner into a DbExecutor.
- */
-export function createExecutorFromQueryRunner(
-  runner: SimpleQueryRunner
-): DbExecutor {
-  const supportsTransactions =
-    typeof runner.beginTransaction === 'function' &&
-    typeof runner.commitTransaction === 'function' &&
-    typeof runner.rollbackTransaction === 'function';
+export const toExecutionPayload = (resultSets: QueryResult[]): ExecutionPayload => {
+  const payload = resultSets as ExecutionPayload;
+  payload.resultSets = resultSets;
+  return payload;
+};
 
-  return {
-    capabilities: {
-      transactions: supportsTransactions,
-    },
+export const payloadResultSets = (payload: ExecutionPayload): QueryResult[] =>
+  payload.resultSets ?? payload;
+
+export interface DbExecutor {
+  /** Capability flags so the runtime can make correct decisions without relying on optional methods. */
+  readonly capabilities: {
+    /** True if begin/commit/rollback are real and should be used to provide atomicity. */
+    transactions: boolean;
+  };
+
+  executeSql(sql: string, params?: unknown[]): Promise<ExecutionPayload>;
+
+  beginTransaction(): Promise<void>;
+  commitTransaction(): Promise<void>;
+  rollbackTransaction(): Promise<void>;
+
+  /** Release any underlying resources (connections, pool leases, etc). Must be idempotent. */
+  dispose(): Promise<void>;
+}
+
+// --- helpers ---
+
+/**
+ * Convert an array of row objects into a QueryResult.
+ */
+export function rowsToQueryResult(
+  rows: Array<Record<string, unknown>>
+): QueryResult {
+  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 };
+}
+
+/**
+ * Minimal contract that most SQL clients can implement.
+ */
+export interface SimpleQueryRunner {
+  query(
+    sql: string,
+    params?: unknown[]
+  ): Promise<Array<Record<string, unknown>>>;
+
+  /** Optional: used to support real transactions. */
+  beginTransaction?(): Promise<void>;
+  commitTransaction?(): Promise<void>;
+  rollbackTransaction?(): Promise<void>;
+
+  /** Optional: release resources (connection close, pool lease release, etc). */
+  dispose?(): Promise<void>;
+}
+
+/**
+ * Generic factory: turn any SimpleQueryRunner into a DbExecutor.
+ */
+export function createExecutorFromQueryRunner(
+  runner: SimpleQueryRunner
+): DbExecutor {
+  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];
+      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);
-    },
-  };
-}
+    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);
+    },
+  };
+}

package/src/core/execution/executors/mssql-executor.ts

@@ -1,18 +1,22 @@
 // src/core/execution/executors/mssql-executor.ts
-import {
-  DbExecutor,
-  rowsToQueryResult
-} from '../db-executor.js';
-
-export interface MssqlClientLike {
-  query(
-    sql: string,
-    params?: unknown[]
-  ): Promise<{ recordset: Array<Record<string, unknown>> }>;
-  beginTransaction?(): Promise<void>;
-  commit?(): Promise<void>;
-  rollback?(): Promise<void>;
-}
+import {
+  DbExecutor,
+  toExecutionPayload,
+  rowsToQueryResult
+} from '../db-executor.js';
+
+export interface MssqlClientLike {
+  query(
+    sql: string,
+    params?: unknown[]
+  ): Promise<{
+    recordset?: Array<Record<string, unknown>>;
+    recordsets?: Array<Array<Record<string, unknown>>>;
+  }>;
+  beginTransaction?(): Promise<void>;
+  commit?(): Promise<void>;
+  rollback?(): Promise<void>;
+}
 
 /**
  * Creates a database executor for Microsoft SQL Server.
@@ -28,14 +32,14 @@ export function createMssqlExecutor(
     typeof client.rollback === 'function';
 
   return {
-    capabilities: {
-      transactions: supportsTransactions,
-    },
-    async executeSql(sql, params) {
-      const { recordset } = await client.query(sql, params);
-      const result = rowsToQueryResult(recordset ?? []);
-      return [result];
-    },
+    capabilities: {
+      transactions: supportsTransactions,
+    },
+    async executeSql(sql, params) {
+      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) {
         throw new Error('Transactions are not supported by this executor');
@@ -157,8 +161,8 @@ export function createTediousMssqlClient(
         }
       );
 
-      return { recordset: rows };
-    },
+      return { recordset: rows, recordsets: [rows] };
+    },
 
     beginTransaction: connection.beginTransaction
       ? () =>

package/src/core/execution/executors/mysql-executor.ts

@@ -1,10 +1,12 @@
 // src/core/execution/executors/mysql-executor.ts
-import {
-  DbExecutor,
-  rowsToQueryResult
-} from '../db-executor.js';
+import {
+  DbExecutor,
+  QueryResult,
+  toExecutionPayload,
+  rowsToQueryResult
+} from '../db-executor.js';
 
-export interface MysqlClientLike {
+export interface MysqlClientLike {
   query(
     sql: string,
     params?: unknown[]
@@ -12,7 +14,56 @@ export interface MysqlClientLike {
   beginTransaction?(): Promise<void>;
   commit?(): Promise<void>;
   rollback?(): Promise<void>;
-}
+}
+
+type RowObject = Record<string, unknown>;
+
+const isRowObject = (value: unknown): value is RowObject =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isRowObjectArray = (value: unknown): value is RowObject[] =>
+  Array.isArray(value) && value.every(isRowObject);
+
+const isMysqlResultHeader = (value: unknown): value is Record<string, unknown> =>
+  isRowObject(value) &&
+  ('affectedRows' in value ||
+    'insertId' in value ||
+    'warningStatus' in value ||
+    'serverStatus' in value);
+
+const headerToQueryResult = (header: Record<string, unknown>): QueryResult => ({
+  columns: [],
+  values: [],
+  meta: {
+    insertId: header.insertId as number | string | undefined,
+    rowsAffected: header.affectedRows as number | undefined,
+  }
+});
+
+const normalizeMysqlResults = (rows: unknown): QueryResult[] => {
+  if (!Array.isArray(rows)) {
+    return isMysqlResultHeader(rows)
+      ? [headerToQueryResult(rows)]
+      : [rowsToQueryResult([])];
+  }
+
+  if (isRowObjectArray(rows)) {
+    return [rowsToQueryResult(rows)];
+  }
+
+  const normalized: QueryResult[] = [];
+  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([])];
+};
 
 /**
  * Creates a database executor for MySQL.
@@ -30,27 +81,11 @@ export function createMysqlExecutor(
   return {
     capabilities: {
       transactions: supportsTransactions,
-    },
-    async executeSql(sql, params) {
-      const [rows] = await client.query(sql, params);
-
-      if (!Array.isArray(rows)) {
-        const header = rows as Record<string, unknown>;
-        return [{
-          columns: [],
-          values: [],
-          meta: {
-            insertId: header.insertId as number | undefined,
-            rowsAffected: header.affectedRows as number | undefined,
-          }
-        }];
-      }
-
-      const result = rowsToQueryResult(
-        rows as Array<Record<string, unknown>>
-      );
-      return [result];
-    },
+    },
+    async executeSql(sql, params) {
+      const [rows] = await client.query(sql, params);
+      return toExecutionPayload(normalizeMysqlResults(rows));
+    },
     async beginTransaction() {
       if (!supportsTransactions) {
         throw new Error('Transactions are not supported by this executor');

package/src/core/execution/executors/sqlite-executor.ts

@@ -1,8 +1,9 @@
 // src/core/execution/executors/sqlite-executor.ts
-import {
-  DbExecutor,
-  rowsToQueryResult
-} from '../db-executor.js';
+import {
+  DbExecutor,
+  toExecutionPayload,
+  rowsToQueryResult
+} from '../db-executor.js';
 
 export interface SqliteClientLike {
   all(
@@ -32,11 +33,11 @@ export function createSqliteExecutor(
     capabilities: {
       transactions: supportsTransactions,
     },
-    async executeSql(sql, params) {
-      const rows = await client.all(sql, params);
-      const result = rowsToQueryResult(rows);
-      return [result];
-    },
+    async executeSql(sql, params) {
+      const rows = await client.all(sql, params);
+      const result = rowsToQueryResult(rows);
+      return toExecutionPayload([result]);
+    },
     async beginTransaction() {
       if (!supportsTransactions) {
         throw new Error('Transactions are not supported by this executor');

package/src/index.ts

@@ -9,11 +9,13 @@ export * from './schema/types.js';
 export * from './query-builder/select.js';
 export * from './query-builder/select-helpers.js';
 export * from './query-builder/insert.js';
-export * from './query-builder/update.js';
-export * from './query-builder/delete.js';
-export * from './query/index.js';
-export * from './core/ast/expression.js';
-export * from './core/ast/window-functions.js';
+export * from './query-builder/update.js';
+export * from './query-builder/delete.js';
+export * from './query-builder/procedure-call.js';
+export * from './query/index.js';
+export * from './core/ast/expression.js';
+export * from './core/ast/procedure.js';
+export * from './core/ast/window-functions.js';
 export * from './core/hydration/types.js';
 export * from './core/dialect/mysql/index.js';
 export * from './core/dialect/mssql/index.js';
@@ -41,7 +43,8 @@ export * from './orm/lazy-batch.js';
 export * from './orm/relations/has-many.js';
 export * from './orm/relations/belongs-to.js';
 export * from './orm/relations/many-to-many.js';
-export * from './orm/execute.js';
+export * from './orm/execute.js';
+export * from './orm/execute-procedure.js';
 export type { EntityContext } from './orm/entity-context.js';
 export type { PrimaryKey as EntityPrimaryKey } from './orm/entity-context.js';
 export * from './orm/execution-context.js';

package/src/orm/execute-procedure.ts

@@ -0,0 +1,77 @@
+import type { ProcedureCallNode } from '../core/ast/procedure.js';
+import type { QueryResult } from '../core/execution/db-executor.js';
+import { payloadResultSets } from '../core/execution/db-executor.js';
+import type { CompiledProcedureCall } from '../core/dialect/abstract.js';
+import type { OrmSession } from './orm-session.js';
+
+export interface ProcedureExecutionResult {
+  resultSets: QueryResult[];
+  out: Record<string, unknown>;
+}
+
+const resolveColumnIndex = (columns: string[], expectedName: string): number => {
+  const exact = columns.findIndex(column => column === expectedName);
+  if (exact >= 0) return exact;
+
+  const lowerExpected = expectedName.toLowerCase();
+  return columns.findIndex(column => column.toLowerCase() === lowerExpected);
+};
+
+const extractOutValues = (
+  compiled: CompiledProcedureCall,
+  resultSets: QueryResult[]
+): Record<string, unknown> => {
+  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: Record<string, unknown> = {};
+  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;
+};
+
+export const executeProcedureAst = async (
+  session: OrmSession,
+  ast: ProcedureCallNode
+): Promise<ProcedureExecutionResult> => {
+  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)
+  };
+};