@mikro-orm/core 7.0.2-dev.9 → 7.0.2

package/connections/Connection.d.ts

@@ -5,89 +5,113 @@ import type { ConnectionType, Dictionary, MaybePromise, Primary } from '../typin
 import type { Platform } from '../platforms/Platform.js';
 import type { TransactionEventBroadcaster } from '../events/TransactionEventBroadcaster.js';
 import type { IsolationLevel } from '../enums.js';
+/** Abstract base class for database connections, providing transaction and query execution support. */
 export declare abstract class Connection {
-    #private;
-    protected readonly config: Configuration;
-    protected readonly type: ConnectionType;
-    protected metadata: MetadataStorage;
-    protected platform: Platform;
-    protected readonly options: ConnectionOptions;
-    protected readonly logger: Logger;
-    protected connected: boolean;
-    constructor(config: Configuration, options?: ConnectionOptions, type?: ConnectionType);
-    /**
-     * Establishes connection to database
-     */
-    abstract connect(options?: {
-        skipOnConnect?: boolean;
-    }): void | Promise<void>;
-    /**
-     * Are we connected to the database
-     */
-    abstract isConnected(): Promise<boolean>;
-    /**
-     * Are we connected to the database
-     */
-    abstract checkConnection(): Promise<{
+  #private;
+  protected readonly config: Configuration;
+  protected readonly type: ConnectionType;
+  protected metadata: MetadataStorage;
+  protected platform: Platform;
+  protected readonly options: ConnectionOptions;
+  protected readonly logger: Logger;
+  protected connected: boolean;
+  constructor(config: Configuration, options?: ConnectionOptions, type?: ConnectionType);
+  /**
+   * Establishes connection to database
+   */
+  abstract connect(options?: { skipOnConnect?: boolean }): void | Promise<void>;
+  /**
+   * Are we connected to the database
+   */
+  abstract isConnected(): Promise<boolean>;
+  /**
+   * Are we connected to the database
+   */
+  abstract checkConnection(): Promise<
+    | {
         ok: true;
-    } | {
+      }
+    | {
         ok: false;
         reason: string;
         error?: Error;
-    }>;
-    /**
-     * Closes the database connection (aka disconnect)
-     */
-    close(force?: boolean): Promise<void>;
-    /**
-     * Ensure the connection exists, this is used to support lazy connect when using `new MikroORM()` instead of the async `init` method.
-     */
-    ensureConnection(): Promise<void>;
-    /**
-     * Execute raw SQL queries, handy from running schema dump loaded from a file.
-     * This method doesn't support transactions, as opposed to `orm.schema.execute()`, which is used internally.
-     */
-    executeDump(dump: string): Promise<void>;
-    protected onConnect(): Promise<void>;
-    transactional<T>(cb: (trx: Transaction) => Promise<T>, options?: {
-        isolationLevel?: IsolationLevel | `${IsolationLevel}`;
-        readOnly?: boolean;
-        ctx?: Transaction;
-        eventBroadcaster?: TransactionEventBroadcaster;
-        loggerContext?: LogContext;
-    }): Promise<T>;
-    begin(options?: {
-        isolationLevel?: IsolationLevel | `${IsolationLevel}`;
-        readOnly?: boolean;
-        ctx?: Transaction;
-        eventBroadcaster?: TransactionEventBroadcaster;
-        loggerContext?: LogContext;
-    }): Promise<Transaction>;
-    commit(ctx: Transaction, eventBroadcaster?: TransactionEventBroadcaster, loggerContext?: LogContext): Promise<void>;
-    rollback(ctx: Transaction, eventBroadcaster?: TransactionEventBroadcaster, loggerContext?: LogContext): Promise<void>;
-    abstract execute<T>(query: string, params?: any[], method?: 'all' | 'get' | 'run', ctx?: Transaction): Promise<QueryResult<T> | any | any[]>;
-    getConnectionOptions(): ConnectionConfig;
-    setMetadata(metadata: MetadataStorage): void;
-    setPlatform(platform: Platform): void;
-    getPlatform(): Platform;
-    protected executeQuery<T>(query: string, cb: () => Promise<T>, context?: LogContext): Promise<T>;
-    protected logQuery(query: string, context?: LogContext): void;
+      }
+  >;
+  /**
+   * Closes the database connection (aka disconnect)
+   */
+  close(force?: boolean): Promise<void>;
+  /**
+   * Ensure the connection exists, this is used to support lazy connect when using `new MikroORM()` instead of the async `init` method.
+   */
+  ensureConnection(): Promise<void>;
+  /**
+   * Execute raw SQL queries, handy from running schema dump loaded from a file.
+   * This method doesn't support transactions, as opposed to `orm.schema.execute()`, which is used internally.
+   */
+  executeDump(dump: string): Promise<void>;
+  protected onConnect(): Promise<void>;
+  /** Executes a callback inside a transaction, committing on success and rolling back on failure. */
+  transactional<T>(
+    cb: (trx: Transaction) => Promise<T>,
+    options?: {
+      isolationLevel?: IsolationLevel | `${IsolationLevel}`;
+      readOnly?: boolean;
+      ctx?: Transaction;
+      eventBroadcaster?: TransactionEventBroadcaster;
+      loggerContext?: LogContext;
+    },
+  ): Promise<T>;
+  /** Begins a new database transaction and returns the transaction context. */
+  begin(options?: {
+    isolationLevel?: IsolationLevel | `${IsolationLevel}`;
+    readOnly?: boolean;
+    ctx?: Transaction;
+    eventBroadcaster?: TransactionEventBroadcaster;
+    loggerContext?: LogContext;
+  }): Promise<Transaction>;
+  /** Commits the given transaction. */
+  commit(ctx: Transaction, eventBroadcaster?: TransactionEventBroadcaster, loggerContext?: LogContext): Promise<void>;
+  /** Rolls back the given transaction. */
+  rollback(ctx: Transaction, eventBroadcaster?: TransactionEventBroadcaster, loggerContext?: LogContext): Promise<void>;
+  /** Executes a raw query and returns the result. */
+  abstract execute<T>(
+    query: string,
+    params?: any[],
+    method?: 'all' | 'get' | 'run',
+    ctx?: Transaction,
+  ): Promise<QueryResult<T> | any | any[]>;
+  /** Parses and returns the resolved connection configuration (host, port, user, etc.). */
+  getConnectionOptions(): ConnectionConfig;
+  /** Sets the metadata storage on this connection. */
+  setMetadata(metadata: MetadataStorage): void;
+  /** Sets the platform abstraction on this connection. */
+  setPlatform(platform: Platform): void;
+  /** Returns the platform abstraction for this connection. */
+  getPlatform(): Platform;
+  protected executeQuery<T>(query: string, cb: () => Promise<T>, context?: LogContext): Promise<T>;
+  protected logQuery(query: string, context?: LogContext): void;
 }
-export interface QueryResult<T = {
+/** Result of a native database query (insert, update, delete). */
+export interface QueryResult<
+  T = {
     id: number;
-}> {
-    affectedRows: number;
-    insertId: Primary<T>;
-    row?: Dictionary;
-    rows?: Dictionary[];
-    insertedIds?: Primary<T>[];
+  },
+> {
+  affectedRows: number;
+  insertId: Primary<T>;
+  row?: Dictionary;
+  rows?: Dictionary[];
+  insertedIds?: Primary<T>[];
 }
+/** Resolved database connection parameters. */
 export interface ConnectionConfig {
-    host?: string;
-    port?: number;
-    user?: string;
-    password?: string | (() => MaybePromise<string>);
-    database?: string;
-    schema?: string;
+  host?: string;
+  port?: number;
+  user?: string;
+  password?: string | (() => MaybePromise<string>);
+  database?: string;
+  schema?: string;
 }
+/** Opaque transaction context type, wrapping the driver-specific transaction object. */
 export type Transaction<T = any> = T & {};

package/connections/Connection.js

@@ -1,163 +1,169 @@
 import { Utils } from '../utils/Utils.js';
+/** Abstract base class for database connections, providing transaction and query execution support. */
 export class Connection {
-    config;
-    type;
-    metadata;
-    platform;
-    options;
-    logger;
-    connected = false;
-    get #connectionLabel() {
-        return {
-            type: this.type,
-            name: this.options.name || this.config.get('name') || this.options.host || this.options.dbName,
-        };
-    }
-    constructor(config, options, type = 'write') {
-        this.config = config;
-        this.type = type;
-        this.logger = this.config.getLogger();
-        this.platform = this.config.getPlatform();
-        if (options) {
-            this.options = Utils.copy(options);
-        }
-        else {
-            const props = [
-                'dbName',
-                'clientUrl',
-                'host',
-                'port',
-                'user',
-                'password',
-                'multipleStatements',
-                'pool',
-                'schema',
-                'driverOptions',
-            ];
-            this.options = props.reduce((o, i) => {
-                o[i] = this.config.get(i);
-                return o;
-            }, {});
-        }
-    }
-    /**
-     * Closes the database connection (aka disconnect)
-     */
-    async close(force) {
-        Object.keys(this.options)
-            .filter(k => k !== 'name')
-            .forEach(k => delete this.options[k]);
-    }
-    /**
-     * Ensure the connection exists, this is used to support lazy connect when using `new MikroORM()` instead of the async `init` method.
-     */
-    async ensureConnection() {
-        if (!this.connected) {
-            await this.connect();
-        }
-    }
-    /**
-     * Execute raw SQL queries, handy from running schema dump loaded from a file.
-     * This method doesn't support transactions, as opposed to `orm.schema.execute()`, which is used internally.
-     */
-    async executeDump(dump) {
-        throw new Error(`Executing SQL dumps is not supported by current driver`);
-    }
-    async onConnect() {
-        const schemaGenerator = this.config.getExtension('@mikro-orm/schema-generator');
-        if (this.type === 'write' && schemaGenerator) {
-            if (this.config.get('ensureDatabase')) {
-                const options = this.config.get('ensureDatabase');
-                await schemaGenerator.ensureDatabase(typeof options === 'boolean' ? {} : { ...options, forceCheck: true });
-            }
-            if (this.config.get('ensureIndexes')) {
-                await schemaGenerator.ensureIndexes();
-            }
-        }
-    }
-    async transactional(cb, options) {
-        throw new Error(`Transactions are not supported by current driver`);
-    }
-    async begin(options) {
-        throw new Error(`Transactions are not supported by current driver`);
-    }
-    async commit(ctx, eventBroadcaster, loggerContext) {
-        throw new Error(`Transactions are not supported by current driver`);
-    }
-    async rollback(ctx, eventBroadcaster, loggerContext) {
-        throw new Error(`Transactions are not supported by current driver`);
-    }
-    getConnectionOptions() {
-        const ret = {};
-        if (this.options.clientUrl) {
-            const url = new URL(this.options.clientUrl);
-            this.options.host = ret.host = this.options.host ?? decodeURIComponent(url.hostname);
-            this.options.port = ret.port = this.options.port ?? +url.port;
-            this.options.user = ret.user = this.options.user ?? decodeURIComponent(url.username);
-            this.options.password = ret.password = this.options.password ?? decodeURIComponent(url.password);
-            this.options.dbName = ret.database = this.options.dbName ?? decodeURIComponent(url.pathname).replace(/^\//, '');
-            if (this.options.schema || url.searchParams.has('schema')) {
-                this.options.schema = ret.schema = this.options.schema ?? decodeURIComponent(url.searchParams.get('schema'));
-                this.config.set('schema', ret.schema);
-            }
-        }
-        else {
-            const url = new URL(this.config.get('clientUrl'));
-            this.options.host = ret.host = this.options.host ?? this.config.get('host', decodeURIComponent(url.hostname));
-            this.options.port = ret.port = this.options.port ?? this.config.get('port', +url.port);
-            this.options.user = ret.user = this.options.user ?? this.config.get('user', decodeURIComponent(url.username));
-            this.options.password = ret.password =
-                this.options.password ?? this.config.get('password', decodeURIComponent(url.password));
-            this.options.dbName = ret.database =
-                this.options.dbName ?? this.config.get('dbName', decodeURIComponent(url.pathname).replace(/^\//, ''));
-        }
-        return ret;
-    }
-    setMetadata(metadata) {
-        this.metadata = metadata;
-    }
-    setPlatform(platform) {
-        this.platform = platform;
-    }
-    getPlatform() {
-        return this.platform;
-    }
-    async executeQuery(query, cb, context) {
-        const now = Date.now();
-        try {
-            const res = await cb();
-            const took = Date.now() - now;
-            const results = Array.isArray(res) ? res.length : undefined;
-            const affected = Utils.isPlainObject(res) ? res.affectedRows : undefined;
-            this.logQuery(query, { ...context, took, results, affected });
-            return res;
-        }
-        catch (e) {
-            const took = Date.now() - now;
-            this.logQuery(query, { ...context, took, level: 'error' });
-            throw e;
-        }
-    }
-    logQuery(query, context = {}) {
-        const connection = this.#connectionLabel;
-        this.logger.logQuery({
-            level: 'info',
-            connection,
-            ...context,
-            query,
-        });
-        const threshold = this.config.get('slowQueryThreshold');
-        if (threshold != null && (context.took ?? 0) >= threshold) {
-            this.config.getSlowQueryLogger().logQuery({
-                ...context,
-                // `enabled: true` bypasses the debug-mode check in isEnabled(),
-                // ensuring slow query logs are always emitted regardless of the `debug` setting.
-                enabled: true,
-                level: context.level ?? 'warning',
-                namespace: 'slow-query',
-                connection,
-                query,
-            });
-        }
-    }
+  config;
+  type;
+  metadata;
+  platform;
+  options;
+  logger;
+  connected = false;
+  get #connectionLabel() {
+    return {
+      type: this.type,
+      name: this.options.name || this.config.get('name') || this.options.host || this.options.dbName,
+    };
+  }
+  constructor(config, options, type = 'write') {
+    this.config = config;
+    this.type = type;
+    this.logger = this.config.getLogger();
+    this.platform = this.config.getPlatform();
+    if (options) {
+      this.options = Utils.copy(options);
+    } else {
+      const props = [
+        'dbName',
+        'clientUrl',
+        'host',
+        'port',
+        'user',
+        'password',
+        'multipleStatements',
+        'pool',
+        'schema',
+        'driverOptions',
+      ];
+      this.options = props.reduce((o, i) => {
+        o[i] = this.config.get(i);
+        return o;
+      }, {});
+    }
+  }
+  /**
+   * Closes the database connection (aka disconnect)
+   */
+  async close(force) {
+    Object.keys(this.options)
+      .filter(k => k !== 'name')
+      .forEach(k => delete this.options[k]);
+  }
+  /**
+   * Ensure the connection exists, this is used to support lazy connect when using `new MikroORM()` instead of the async `init` method.
+   */
+  async ensureConnection() {
+    if (!this.connected) {
+      await this.connect();
+    }
+  }
+  /**
+   * Execute raw SQL queries, handy from running schema dump loaded from a file.
+   * This method doesn't support transactions, as opposed to `orm.schema.execute()`, which is used internally.
+   */
+  async executeDump(dump) {
+    throw new Error(`Executing SQL dumps is not supported by current driver`);
+  }
+  async onConnect() {
+    const schemaGenerator = this.config.getExtension('@mikro-orm/schema-generator');
+    if (this.type === 'write' && schemaGenerator) {
+      if (this.config.get('ensureDatabase')) {
+        const options = this.config.get('ensureDatabase');
+        await schemaGenerator.ensureDatabase(typeof options === 'boolean' ? {} : { ...options, forceCheck: true });
+      }
+      if (this.config.get('ensureIndexes')) {
+        await schemaGenerator.ensureIndexes();
+      }
+    }
+  }
+  /** Executes a callback inside a transaction, committing on success and rolling back on failure. */
+  async transactional(cb, options) {
+    throw new Error(`Transactions are not supported by current driver`);
+  }
+  /** Begins a new database transaction and returns the transaction context. */
+  async begin(options) {
+    throw new Error(`Transactions are not supported by current driver`);
+  }
+  /** Commits the given transaction. */
+  async commit(ctx, eventBroadcaster, loggerContext) {
+    throw new Error(`Transactions are not supported by current driver`);
+  }
+  /** Rolls back the given transaction. */
+  async rollback(ctx, eventBroadcaster, loggerContext) {
+    throw new Error(`Transactions are not supported by current driver`);
+  }
+  /** Parses and returns the resolved connection configuration (host, port, user, etc.). */
+  getConnectionOptions() {
+    const ret = {};
+    if (this.options.clientUrl) {
+      const url = new URL(this.options.clientUrl);
+      this.options.host = ret.host = this.options.host ?? decodeURIComponent(url.hostname);
+      this.options.port = ret.port = this.options.port ?? +url.port;
+      this.options.user = ret.user = this.options.user ?? decodeURIComponent(url.username);
+      this.options.password = ret.password = this.options.password ?? decodeURIComponent(url.password);
+      this.options.dbName = ret.database = this.options.dbName ?? decodeURIComponent(url.pathname).replace(/^\//, '');
+      if (this.options.schema || url.searchParams.has('schema')) {
+        this.options.schema = ret.schema = this.options.schema ?? decodeURIComponent(url.searchParams.get('schema'));
+        this.config.set('schema', ret.schema);
+      }
+    } else {
+      const url = new URL(this.config.get('clientUrl'));
+      this.options.host = ret.host = this.options.host ?? this.config.get('host', decodeURIComponent(url.hostname));
+      this.options.port = ret.port = this.options.port ?? this.config.get('port', +url.port);
+      this.options.user = ret.user = this.options.user ?? this.config.get('user', decodeURIComponent(url.username));
+      this.options.password = ret.password =
+        this.options.password ?? this.config.get('password', decodeURIComponent(url.password));
+      this.options.dbName = ret.database =
+        this.options.dbName ?? this.config.get('dbName', decodeURIComponent(url.pathname).replace(/^\//, ''));
+    }
+    return ret;
+  }
+  /** Sets the metadata storage on this connection. */
+  setMetadata(metadata) {
+    this.metadata = metadata;
+  }
+  /** Sets the platform abstraction on this connection. */
+  setPlatform(platform) {
+    this.platform = platform;
+  }
+  /** Returns the platform abstraction for this connection. */
+  getPlatform() {
+    return this.platform;
+  }
+  async executeQuery(query, cb, context) {
+    const now = Date.now();
+    try {
+      const res = await cb();
+      const took = Date.now() - now;
+      const results = Array.isArray(res) ? res.length : undefined;
+      const affected = Utils.isPlainObject(res) ? res.affectedRows : undefined;
+      this.logQuery(query, { ...context, took, results, affected });
+      return res;
+    } catch (e) {
+      const took = Date.now() - now;
+      this.logQuery(query, { ...context, took, level: 'error' });
+      throw e;
+    }
+  }
+  logQuery(query, context = {}) {
+    const connection = this.#connectionLabel;
+    this.logger.logQuery({
+      level: 'info',
+      connection,
+      ...context,
+      query,
+    });
+    const threshold = this.config.get('slowQueryThreshold');
+    if (threshold != null && (context.took ?? 0) >= threshold) {
+      this.config.getSlowQueryLogger().logQuery({
+        ...context,
+        // `enabled: true` bypasses the debug-mode check in isEnabled(),
+        // ensuring slow query logs are always emitted regardless of the `debug` setting.
+        enabled: true,
+        level: context.level ?? 'warning',
+        namespace: 'slow-query',
+        connection,
+        query,
+      });
+    }
+  }
 }