metal-orm 1.1.8 → 1.1.10

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

@@ -1,45 +1,50 @@
 // src/core/execution/db-executor.ts
 
 // low-level canonical shape
-export type QueryResult = {
-  columns: string[];
-  values: unknown[][];
-  meta?: {
-    insertId?: number | string;
-    rowsAffected?: number;
-  };
-};
-
-/**
- * Canonical execution payload.
- * It remains array-compatible for a gradual migration but always exposes
- * `resultSets` for explicit multi-result handling.
- */
-export type ExecutionPayload = QueryResult[] & {
-  resultSets?: QueryResult[];
-};
-
-export const toExecutionPayload = (resultSets: QueryResult[]): ExecutionPayload => {
-  const payload = resultSets as ExecutionPayload;
-  payload.resultSets = resultSets;
-  return payload;
-};
-
-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;
+export type QueryResult = {
+  columns: string[];
+  values: unknown[][];
+  meta?: {
+    insertId?: number | string;
+    rowsAffected?: number;
   };
+};
+
+/**
+ * Canonical execution payload.
+ * It remains array-compatible for a gradual migration but always exposes
+ * `resultSets` for explicit multi-result handling.
+ */
+export type ExecutionPayload = QueryResult[] & {
+  resultSets?: QueryResult[];
+};
 
-  executeSql(sql: string, params?: unknown[]): Promise<ExecutionPayload>;
+export const toExecutionPayload = (resultSets: QueryResult[]): ExecutionPayload => {
+  const payload = resultSets as ExecutionPayload;
+  payload.resultSets = resultSets;
+  return payload;
+};
 
-  beginTransaction(): Promise<void>;
-  commitTransaction(): Promise<void>;
-  rollbackTransaction(): Promise<void>;
+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;
+    /** True if savepoint/release/rollback-to-savepoint are implemented. */
+    savepoints?: boolean;
+  };
+
+  executeSql(sql: string, params?: unknown[]): Promise<ExecutionPayload>;
+
+  beginTransaction(): Promise<void>;
+  commitTransaction(): Promise<void>;
+  rollbackTransaction(): Promise<void>;
+  savepoint?(name: string): Promise<void>;
+  releaseSavepoint?(name: string): Promise<void>;
+  rollbackToSavepoint?(name: string): Promise<void>;
 
   /** Release any underlying resources (connections, pool leases, etc). Must be idempotent. */
   dispose(): Promise<void>;
@@ -71,10 +76,13 @@ export interface SimpleQueryRunner {
     params?: unknown[]
   ): Promise<Array<Record<string, unknown>>>;
 
-  /** Optional: used to support real transactions. */
-  beginTransaction?(): Promise<void>;
-  commitTransaction?(): Promise<void>;
-  rollbackTransaction?(): Promise<void>;
+  /** Optional: used to support real transactions. */
+  beginTransaction?(): Promise<void>;
+  commitTransaction?(): Promise<void>;
+  rollbackTransaction?(): Promise<void>;
+  savepoint?(name: string): Promise<void>;
+  releaseSavepoint?(name: string): Promise<void>;
+  rollbackToSavepoint?(name: string): Promise<void>;
 
   /** Optional: release resources (connection close, pool lease release, etc). */
   dispose?(): Promise<void>;
@@ -86,20 +94,26 @@ export interface SimpleQueryRunner {
 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 toExecutionPayload([result]);
+  const supportsTransactions =
+    typeof runner.beginTransaction === 'function' &&
+    typeof runner.commitTransaction === 'function' &&
+    typeof runner.rollbackTransaction === 'function';
+  const supportsSavepoints =
+    supportsTransactions &&
+    typeof runner.savepoint === 'function' &&
+    typeof runner.releaseSavepoint === 'function' &&
+    typeof runner.rollbackToSavepoint === 'function';
+
+  return {
+    capabilities: {
+      transactions: supportsTransactions,
+      ...(supportsSavepoints ? { savepoints: true } : {}),
     },
+    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');
@@ -112,14 +126,32 @@ export function createExecutorFromQueryRunner(
       }
       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 rollbackTransaction() {
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await runner.rollbackTransaction!.call(runner);
+    },
+    async savepoint(name: string) {
+      if (!supportsSavepoints) {
+        throw new Error('Savepoints are not supported by this executor');
+      }
+      await runner.savepoint!.call(runner, name);
+    },
+    async releaseSavepoint(name: string) {
+      if (!supportsSavepoints) {
+        throw new Error('Savepoints are not supported by this executor');
+      }
+      await runner.releaseSavepoint!.call(runner, name);
+    },
+    async rollbackToSavepoint(name: string) {
+      if (!supportsSavepoints) {
+        throw new Error('Savepoints are not supported by this executor');
+      }
+      await runner.rollbackToSavepoint!.call(runner, name);
+    },
+    async dispose() {
+      await runner.dispose?.call(runner);
+    },
+  };
+}

package/src/core/execution/executors/better-sqlite3-executor.ts

@@ -0,0 +1,94 @@
+// src/core/execution/executors/better-sqlite3-executor.ts
+import {
+  DbExecutor,
+  toExecutionPayload,
+  rowsToQueryResult,
+  QueryResult
+} from '../db-executor.js';
+
+export interface BetterSqlite3Statement {
+  reader: boolean;
+  all(...params: unknown[]): unknown[];
+  run(...params: unknown[]): { changes: number; lastInsertRowid: number | bigint };
+}
+
+export interface BetterSqlite3ClientLike {
+  prepare(sql: string): BetterSqlite3Statement;
+  transaction<T extends (...args: any[]) => any>(fn: T): T;
+}
+
+const SAVEPOINT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+const sanitizeSavepointName = (name: string): string => {
+  const trimmed = name.trim();
+  if (!SAVEPOINT_NAME_PATTERN.test(trimmed)) {
+    throw new Error(`Invalid savepoint name: "${name}"`);
+  }
+  return trimmed;
+};
+
+/**
+ * Creates a database executor for better-sqlite3.
+ * @param client A better-sqlite3 database instance.
+ * @returns A DbExecutor implementation for better-sqlite3.
+ */
+export function createBetterSqlite3Executor(
+  client: BetterSqlite3ClientLike
+): DbExecutor {
+  // better-sqlite3 handles nested transactions using savepoints automatically
+  // when using .transaction(), but DbExecutor needs explicit control.
+
+  return {
+    capabilities: {
+      transactions: true,
+      savepoints: true,
+    },
+    async executeSql(sql, params) {
+      const stmt = client.prepare(sql);
+      let result: QueryResult;
+
+      if (stmt.reader) {
+        const rows = stmt.all(...(params ?? [])) as Record<string, unknown>[];
+        result = rowsToQueryResult(rows);
+      } else {
+        const info = stmt.run(...(params ?? []));
+        result = {
+          columns: [],
+          values: [],
+          meta: {
+            rowsAffected: info.changes,
+            insertId: typeof info.lastInsertRowid === 'bigint'
+              ? info.lastInsertRowid.toString()
+              : info.lastInsertRowid
+          }
+        };
+      }
+
+      return toExecutionPayload([result]);
+    },
+    async beginTransaction() {
+      client.prepare('BEGIN').run();
+    },
+    async commitTransaction() {
+      client.prepare('COMMIT').run();
+    },
+    async rollbackTransaction() {
+      client.prepare('ROLLBACK').run();
+    },
+    async savepoint(name: string) {
+      const savepoint = sanitizeSavepointName(name);
+      client.prepare(`SAVEPOINT ${savepoint}`).run();
+    },
+    async releaseSavepoint(name: string) {
+      const savepoint = sanitizeSavepointName(name);
+      client.prepare(`RELEASE SAVEPOINT ${savepoint}`).run();
+    },
+    async rollbackToSavepoint(name: string) {
+      const savepoint = sanitizeSavepointName(name);
+      client.prepare(`ROLLBACK TO SAVEPOINT ${savepoint}`).run();
+    },
+    async dispose() {
+      // Connection lifecycle is owned by the caller.
+    },
+  };
+}

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

@@ -1,22 +1,32 @@
 // src/core/execution/executors/mssql-executor.ts
-import {
-  DbExecutor,
-  toExecutionPayload,
-  rowsToQueryResult
-} from '../db-executor.js';
+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>;
+  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>;
 }
+
+const SAVEPOINT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+const sanitizeSavepointName = (name: string): string => {
+  const trimmed = name.trim();
+  if (!SAVEPOINT_NAME_PATTERN.test(trimmed)) {
+    throw new Error(`Invalid savepoint name: "${name}"`);
+  }
+  return trimmed;
+};
 
 /**
  * Creates a database executor for Microsoft SQL Server.
@@ -26,20 +36,22 @@ export interface MssqlClientLike {
 export function createMssqlExecutor(
   client: MssqlClientLike
 ): DbExecutor {
-  const supportsTransactions =
-    typeof client.beginTransaction === 'function' &&
-    typeof client.commit === 'function' &&
-    typeof client.rollback === 'function';
+  const supportsTransactions =
+    typeof client.beginTransaction === 'function' &&
+    typeof client.commit === 'function' &&
+    typeof client.rollback === 'function';
+  const supportsSavepoints = supportsTransactions;
 
   return {
     capabilities: {
       transactions: supportsTransactions,
+      ...(supportsSavepoints ? { savepoints: true } : {}),
     },
-    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 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');
@@ -52,15 +64,35 @@ export function createMssqlExecutor(
       }
       await client.commit!();
     },
-    async rollbackTransaction() {
-      if (!supportsTransactions) {
-        throw new Error('Transactions are not supported by this executor');
-      }
-      await client.rollback!();
-    },
-    async dispose() {
-      // Connection lifecycle is owned by the caller/driver. Pool lease executors should implement dispose.
-    },
+    async rollbackTransaction() {
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.rollback!();
+    },
+    async savepoint(name: string) {
+      if (!supportsSavepoints) {
+        throw new Error('Savepoints are not supported by this executor');
+      }
+      const savepoint = sanitizeSavepointName(name);
+      await client.query(`SAVE TRANSACTION ${savepoint}`);
+    },
+    async releaseSavepoint(_name: string) {
+      if (!supportsSavepoints) {
+        throw new Error('Savepoints are not supported by this executor');
+      }
+      // SQL Server does not expose a RELEASE SAVEPOINT statement.
+    },
+    async rollbackToSavepoint(name: string) {
+      if (!supportsSavepoints) {
+        throw new Error('Savepoints are not supported by this executor');
+      }
+      const savepoint = sanitizeSavepointName(name);
+      await client.query(`ROLLBACK TRANSACTION ${savepoint}`);
+    },
+    async dispose() {
+      // Connection lifecycle is owned by the caller/driver. Pool lease executors should implement dispose.
+    },
   };
 }
 
@@ -161,8 +193,8 @@ export function createTediousMssqlClient(
         }
       );
 
-      return { recordset: rows, recordsets: [rows] };
-    },
+      return { recordset: rows, recordsets: [rows] };
+    },
 
     beginTransaction: connection.beginTransaction
       ? () =>

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

@@ -1,12 +1,12 @@
 // src/core/execution/executors/mysql-executor.ts
-import {
-  DbExecutor,
-  QueryResult,
-  toExecutionPayload,
-  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[]
@@ -14,57 +14,66 @@ export interface MysqlClientLike {
   beginTransaction?(): Promise<void>;
   commit?(): Promise<void>;
   rollback?(): Promise<void>;
-}
-
+}
+
 type RowObject = Record<string, unknown>;
+const SAVEPOINT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
 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 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,
+  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 sanitizeSavepointName = (name: string): string => {
+  const trimmed = name.trim();
+  if (!SAVEPOINT_NAME_PATTERN.test(trimmed)) {
+    throw new Error(`Invalid savepoint name: "${name}"`);
   }
-
-  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([])];
+  return trimmed;
 };
 
+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.
  * @param client A MySQL client instance.
@@ -73,19 +82,21 @@ const normalizeMysqlResults = (rows: unknown): QueryResult[] => {
 export function createMysqlExecutor(
   client: MysqlClientLike
 ): DbExecutor {
-  const supportsTransactions =
-    typeof client.beginTransaction === 'function' &&
-    typeof client.commit === 'function' &&
-    typeof client.rollback === 'function';
+  const supportsTransactions =
+    typeof client.beginTransaction === 'function' &&
+    typeof client.commit === 'function' &&
+    typeof client.rollback === 'function';
+  const supportsSavepoints = supportsTransactions;
 
   return {
-    capabilities: {
-      transactions: supportsTransactions,
-    },
-    async executeSql(sql, params) {
-      const [rows] = await client.query(sql, params);
-      return toExecutionPayload(normalizeMysqlResults(rows));
+    capabilities: {
+      transactions: supportsTransactions,
+      ...(supportsSavepoints ? { savepoints: true } : {}),
     },
+    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');
@@ -98,14 +109,35 @@ export function createMysqlExecutor(
       }
       await client.commit!();
     },
-    async rollbackTransaction() {
-      if (!supportsTransactions) {
-        throw new Error('Transactions are not supported by this executor');
-      }
-      await client.rollback!();
-    },
-    async dispose() {
-      // Connection lifecycle is owned by the caller/driver. Pool lease executors should implement dispose.
-    },
+    async rollbackTransaction() {
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.rollback!();
+    },
+    async savepoint(name: string) {
+      if (!supportsSavepoints) {
+        throw new Error('Savepoints are not supported by this executor');
+      }
+      const savepoint = sanitizeSavepointName(name);
+      await client.query(`SAVEPOINT ${savepoint}`);
+    },
+    async releaseSavepoint(name: string) {
+      if (!supportsSavepoints) {
+        throw new Error('Savepoints are not supported by this executor');
+      }
+      const savepoint = sanitizeSavepointName(name);
+      await client.query(`RELEASE SAVEPOINT ${savepoint}`);
+    },
+    async rollbackToSavepoint(name: string) {
+      if (!supportsSavepoints) {
+        throw new Error('Savepoints are not supported by this executor');
+      }
+      const savepoint = sanitizeSavepointName(name);
+      await client.query(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+    },
+    async dispose() {
+      // Connection lifecycle is owned by the caller/driver. Pool lease executors should implement dispose.
+    },
   };
 }

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

@@ -1,15 +1,25 @@
 // src/core/execution/executors/postgres-executor.ts
-import {
-  DbExecutor,
-  createExecutorFromQueryRunner
-} from '../db-executor.js';
+import {
+  DbExecutor,
+  createExecutorFromQueryRunner
+} from '../db-executor.js';
 
-export interface PostgresClientLike {
+export interface PostgresClientLike {
   query(
     text: string,
     params?: unknown[]
   ): Promise<{ rows: Array<Record<string, unknown>> }>;
-}
+}
+
+const SAVEPOINT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+const sanitizeSavepointName = (name: string): string => {
+  const trimmed = name.trim();
+  if (!SAVEPOINT_NAME_PATTERN.test(trimmed)) {
+    throw new Error(`Invalid savepoint name: "${name}"`);
+  }
+  return trimmed;
+};
 
 /**
  * Creates a database executor for PostgreSQL.
@@ -30,8 +40,20 @@ export function createPostgresExecutor(
     async commitTransaction() {
       await client.query('COMMIT');
     },
-    async rollbackTransaction() {
-      await client.query('ROLLBACK');
-    },
-  });
-}
+    async rollbackTransaction() {
+      await client.query('ROLLBACK');
+    },
+    async savepoint(name: string) {
+      const savepoint = sanitizeSavepointName(name);
+      await client.query(`SAVEPOINT ${savepoint}`);
+    },
+    async releaseSavepoint(name: string) {
+      const savepoint = sanitizeSavepointName(name);
+      await client.query(`RELEASE SAVEPOINT ${savepoint}`);
+    },
+    async rollbackToSavepoint(name: string) {
+      const savepoint = sanitizeSavepointName(name);
+      await client.query(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+    },
+  });
+}