@mikro-orm/knex 6.0.0-dev.15 → 6.0.0-dev.151

package/query/QueryBuilder.d.ts

@@ -1,14 +1,17 @@
 /// <reference types="node" />
 import { inspect } from 'util';
 import type { Knex } from 'knex';
-import type { AnyEntity, ConnectionType, Dictionary, EntityData, EntityName, EntityProperty, FlushMode, GroupOperator, MetadataStorage, ObjectQuery, PopulateOptions, QBFilterQuery, QBQueryOrderMap, QueryResult, RequiredEntityData } from '@mikro-orm/core';
-import { LockMode, PopulateHint, QueryFlag } from '@mikro-orm/core';
-import { QueryType } from './enums';
+import { type AnyEntity, type ConnectionType, type Dictionary, type EntityData, type EntityName, type EntityProperty, type FlushMode, type GroupOperator, LockMode, type LoggingOptions, type MetadataStorage, type ObjectQuery, PopulateHint, type PopulateOptions, type QBFilterQuery, type QBQueryOrderMap, QueryFlag, type QueryResult, type RequiredEntityData } from '@mikro-orm/core';
+import { QueryType, JoinType } from './enums';
 import type { AbstractSqlDriver } from '../AbstractSqlDriver';
-import { QueryBuilderHelper } from './QueryBuilderHelper';
-import type { Alias } from './QueryBuilderHelper';
+import { type Alias, QueryBuilderHelper } from './QueryBuilderHelper';
 import type { SqlEntityManager } from '../SqlEntityManager';
 import type { Field } from '../typings';
+import type { AbstractSqlPlatform } from '../AbstractSqlPlatform';
+export interface ExecuteOptions {
+    mapResults?: boolean;
+    mergeResults?: boolean;
+}
 /**
  * SQL query builder with fluent interface.
  *
@@ -29,12 +32,14 @@ import type { Field } from '../typings';
  * ```
  */
 export declare class QueryBuilder<T extends object = AnyEntity> {
+    #private;
     private readonly metadata;
     private readonly driver;
     private readonly context?;
     private connectionType?;
     private readonly em?;
-    get mainAlias(): Alias;
+    private readonly logging?;
+    get mainAlias(): Alias<T>;
     get alias(): string;
     get helper(): QueryBuilderHelper;
     /** @internal */
@@ -44,7 +49,7 @@ export declare class QueryBuilder<T extends object = AnyEntity> {
     /** @internal */
     _populate: PopulateOptions<T>[];
     /** @internal */
-    _populateWhere?: ObjectQuery<T> | PopulateHint;
+    _populateWhere?: ObjectQuery<T> | PopulateHint | `${PopulateHint}`;
     /** @internal */
     _populateMap: Dictionary<string>;
     private aliasCounter;
@@ -58,6 +63,7 @@ export declare class QueryBuilder<T extends object = AnyEntity> {
     private _orderBy;
     private _groupBy;
     private _having;
+    private _returning?;
     private _onConflict?;
     private _limit?;
     private _offset?;
@@ -65,6 +71,8 @@ export declare class QueryBuilder<T extends object = AnyEntity> {
     private _joinedProps;
     private _cache?;
     private _indexHint?;
+    private _comments;
+    private _hintComments;
     private flushMode?;
     private lockMode?;
     private lockTables?;
@@ -77,7 +85,7 @@ export declare class QueryBuilder<T extends object = AnyEntity> {
     /**
      * @internal
      */
-    constructor(entityName: EntityName<T> | QueryBuilder<T>, metadata: MetadataStorage, driver: AbstractSqlDriver, context?: Knex.Transaction<any, any[]> | undefined, alias?: string, connectionType?: ConnectionType | undefined, em?: SqlEntityManager<AbstractSqlDriver<import("../AbstractSqlConnection").AbstractSqlConnection, import("../AbstractSqlPlatform").AbstractSqlPlatform>> | undefined);
+    constructor(entityName: EntityName<T> | QueryBuilder<T>, metadata: MetadataStorage, driver: AbstractSqlDriver, context?: Knex.Transaction<any, any[]> | undefined, alias?: string, connectionType?: ConnectionType | undefined, em?: SqlEntityManager<AbstractSqlDriver<import("..").AbstractSqlConnection, AbstractSqlPlatform>> | undefined, logging?: LoggingOptions | undefined);
     select(fields: Field<T> | Field<T>[], distinct?: boolean): SelectQueryBuilder<T>;
     addSelect(fields: Field<T> | Field<T>[]): SelectQueryBuilder<T>;
     distinct(): SelectQueryBuilder<T>;
@@ -88,11 +96,17 @@ export declare class QueryBuilder<T extends object = AnyEntity> {
     delete(cond?: QBFilterQuery): DeleteQueryBuilder<T>;
     truncate(): TruncateQueryBuilder<T>;
     count(field?: string | string[], distinct?: boolean): CountQueryBuilder<T>;
-    join(field: string, alias: string, cond?: QBFilterQuery, type?: 'leftJoin' | 'innerJoin' | 'pivotJoin', path?: string): this;
-    leftJoin(field: string, alias: string, cond?: QBFilterQuery): this;
-    joinAndSelect(field: string, alias: string, cond?: QBFilterQuery, type?: 'leftJoin' | 'innerJoin' | 'pivotJoin', path?: string): SelectQueryBuilder<T>;
-    leftJoinAndSelect(field: string, alias: string, cond?: QBFilterQuery): SelectQueryBuilder<T>;
-    protected getFieldsForJoinedLoad<U extends object>(prop: EntityProperty<U>, alias: string): Field<U>[];
+    join(field: string | Knex.QueryBuilder | QueryBuilder<any>, alias: string, cond?: QBFilterQuery, type?: JoinType, path?: string, schema?: string): this;
+    innerJoin(field: string | Knex.QueryBuilder | QueryBuilder<any>, alias: string, cond?: QBFilterQuery, schema?: string): this;
+    innerJoinLateral(field: string | Knex.QueryBuilder | QueryBuilder<any>, alias: string, cond?: QBFilterQuery, schema?: string): this;
+    leftJoin(field: string | Knex.QueryBuilder | QueryBuilder<any>, alias: string, cond?: QBFilterQuery, schema?: string): this;
+    leftJoinLateral(field: string | Knex.QueryBuilder | QueryBuilder<any>, alias: string, cond?: QBFilterQuery, schema?: string): this;
+    joinAndSelect(field: string | [field: string, qb: Knex.QueryBuilder | QueryBuilder<any>], alias: string, cond?: QBFilterQuery, type?: JoinType, path?: string, fields?: string[], schema?: string): SelectQueryBuilder<T>;
+    leftJoinAndSelect(field: string | [field: string, qb: Knex.QueryBuilder | QueryBuilder<any>], alias: string, cond?: QBFilterQuery, fields?: string[], schema?: string): SelectQueryBuilder<T>;
+    leftJoinLateralAndSelect(field: string | [field: string, qb: Knex.QueryBuilder | QueryBuilder<any>], alias: string, cond?: QBFilterQuery, fields?: string[], schema?: string): SelectQueryBuilder<T>;
+    innerJoinAndSelect(field: string | [field: string, qb: Knex.QueryBuilder | QueryBuilder<any>], alias: string, cond?: QBFilterQuery, fields?: string[], schema?: string): SelectQueryBuilder<T>;
+    innerJoinLateralAndSelect(field: string | [field: string, qb: Knex.QueryBuilder | QueryBuilder<any>], alias: string, cond?: QBFilterQuery, fields?: string[], schema?: string): SelectQueryBuilder<T>;
+    protected getFieldsForJoinedLoad(prop: EntityProperty<T>, alias: string, explicitFields?: string[]): Field<T>[];
     withSubQuery(subQuery: Knex.QueryBuilder, alias: string): this;
     where(cond: QBFilterQuery<T>, operator?: keyof typeof GroupOperator): this;
     where(cond: string, params?: any[], operator?: keyof typeof GroupOperator): this;
@@ -106,17 +120,11 @@ export declare class QueryBuilder<T extends object = AnyEntity> {
     onConflict(fields?: Field<T> | Field<T>[]): this;
     ignore(): this;
     merge(data?: EntityData<T> | Field<T>[]): this;
+    returning(fields?: Field<T> | Field<T>[]): this;
     /**
      * @internal
      */
-    populate(populate: PopulateOptions<T>[], populateWhere?: ObjectQuery<T> | PopulateHint): this;
-    /**
-     * @internal
-     */
-    ref(field: string): Knex.Ref<string, {
-        [x: string]: string;
-    }>;
-    raw<R = Knex.Raw>(sql: string, bindings?: Knex.RawBinding[] | Knex.ValueDict): R;
+    populate(populate: PopulateOptions<T>[], populateWhere?: ObjectQuery<T> | PopulateHint | `${PopulateHint}`): this;
     limit(limit?: number, offset?: number): this;
     offset(offset?: number): this;
     withSchema(schema?: string): this;
@@ -129,6 +137,16 @@ export declare class QueryBuilder<T extends object = AnyEntity> {
      * Adds index hint to the FROM clause.
      */
     indexHint(sql: string): this;
+    /**
+     * Prepend comment to the sql query using the syntax `/* ... *&#8205;/`. Some characters are forbidden such as `/*, *&#8205;/` and `?`.
+     */
+    comment(comment: string | string[]): this;
+    /**
+     * Add hints to the query using comment-like syntax `/*+ ... *&#8205;/`. MySQL and Oracle use this syntax for optimizer hints.
+     * Also various DB proxies and routers use this syntax to pass hints to alter their behavior. In other dialects the hints
+     * are ignored as simple comments.
+     */
+    hintComment(comment: string | string[]): this;
     /**
      * Specifies FROM which entity's table select/update/delete will be executed, removing all previously set FROM-s.
      * Allows setting a main string alias of the selection data.
@@ -140,6 +158,11 @@ export declare class QueryBuilder<T extends object = AnyEntity> {
      * Returns the query with parameters as wildcards.
      */
     getQuery(): string;
+    toQuery(): {
+        sql: string;
+        _sql: Knex.Sql;
+        params: readonly unknown[];
+    };
     /**
      * Returns the list of all parameters for this query.
      */
@@ -164,7 +187,7 @@ export declare class QueryBuilder<T extends object = AnyEntity> {
      * Executes this QB and returns the raw results, mapped to the property names (unless disabled via last parameter).
      * Use `method` to specify what kind of result you want to get (array/single/meta).
      */
-    execute<U = any>(method?: 'all' | 'get' | 'run', mapResults?: boolean): Promise<U>;
+    execute<U = any>(method?: 'all' | 'get' | 'run', options?: ExecuteOptions | boolean): Promise<U>;
     /**
      * Alias for `qb.getResultList()`
      */
@@ -181,6 +204,10 @@ export declare class QueryBuilder<T extends object = AnyEntity> {
      * Executes count query (without offset and limit), returning total count of results
      */
     getCount(field?: string | string[], distinct?: boolean): Promise<number>;
+    /**
+     * Executes the query, returning both array of results and total count query (without offset and limit).
+     */
+    getResultAndCount(): Promise<[T[], number]>;
     /**
      * Provides promise-like interface so we can await the QB instance.
      */
@@ -196,11 +223,12 @@ export declare class QueryBuilder<T extends object = AnyEntity> {
     private prepareFields;
     private init;
     private getQueryBase;
+    private applyDiscriminatorCondition;
     private finalize;
+    private processPopulateWhere;
     private hasToManyJoins;
     private wrapPaginateSubQuery;
     private wrapModifySubQuery;
-    private autoJoinPivotTable;
     private getSchema;
     private createAlias;
     private createMainAlias;
@@ -209,6 +237,7 @@ export declare class QueryBuilder<T extends object = AnyEntity> {
     private createQueryBuilderHelper;
     private ensureFromClause;
     private ensureNotFinalized;
+    /** @ignore */
     [inspect.custom](depth: number): string;
 }
 export interface RunQueryBuilder<T extends object> extends Omit<QueryBuilder<T>, 'getResult' | 'getSingleResult' | 'getResultList' | 'where'> {