@mikro-orm/knex 7.0.0-dev.9 → 7.0.0-dev.91

package/query/ArrayCriteriaNode.d.ts

@@ -7,4 +7,5 @@ export declare class ArrayCriteriaNode<T extends object> extends CriteriaNode<T>
     process(qb: IQueryBuilder<T>, options?: ICriteriaNodeProcessOptions): any;
     unwrap(): any;
     willAutoJoin(qb: IQueryBuilder<T>, alias?: string, options?: ICriteriaNodeProcessOptions): any;
+    isStrict(): boolean;
 }

package/query/ArrayCriteriaNode.js

@@ -18,4 +18,7 @@ export class ArrayCriteriaNode extends CriteriaNode {
             return node.willAutoJoin(qb, alias, options);
         });
     }
+    isStrict() {
+        return this.strict || this.payload.some((node) => node.isStrict());
+    }
 }

package/query/CriteriaNode.d.ts

@@ -1,4 +1,3 @@
-import { inspect } from 'node:util';
 import { type EntityKey, type EntityProperty, type MetadataStorage } from '@mikro-orm/core';
 import type { ICriteriaNode, ICriteriaNodeProcessOptions, IQueryBuilder } from '../typings.js';
 /**
@@ -11,20 +10,20 @@ export declare class CriteriaNode<T extends object> implements ICriteriaNode<T>
     readonly entityName: string;
     readonly parent?: ICriteriaNode<T> | undefined;
     readonly key?: EntityKey<T> | undefined;
+    readonly strict: boolean;
     payload: any;
     prop?: EntityProperty<T>;
     index?: number;
-    constructor(metadata: MetadataStorage, entityName: string, parent?: ICriteriaNode<T> | undefined, key?: EntityKey<T> | undefined, validate?: boolean);
+    constructor(metadata: MetadataStorage, entityName: string, parent?: ICriteriaNode<T> | undefined, key?: EntityKey<T> | undefined, validate?: boolean, strict?: boolean);
     process(qb: IQueryBuilder<T>, options?: ICriteriaNodeProcessOptions): any;
     unwrap(): any;
     shouldInline(payload: any): boolean;
     willAutoJoin(qb: IQueryBuilder<T>, alias?: string, options?: ICriteriaNodeProcessOptions): boolean;
     shouldRename(payload: any): boolean;
-    renameFieldToPK<T>(qb: IQueryBuilder<T>): string;
+    renameFieldToPK<T>(qb: IQueryBuilder<T>, ownerAlias?: string): string;
     getPath(addIndex?: boolean): string;
     private isPivotJoin;
     getPivotPath(path: string): string;
     aliased(field: string, alias?: string): string;
-    /** @ignore */
-    [inspect.custom](): string;
+    isStrict(): boolean;
 }

package/query/CriteriaNode.js

@@ -1,5 +1,4 @@
-import { inspect } from 'node:util';
-import { RawQueryFragment, ReferenceKind, Utils, } from '@mikro-orm/core';
+import { RawQueryFragment, ReferenceKind, Utils, inspect, } from '@mikro-orm/core';
 /**
  * Helper for working with deeply nested where/orderBy/having criteria. Uses composite pattern to build tree from the payload.
  * Auto-joins relations and converts payload from { books: { publisher: { name: '...' } } } to { 'publisher_alias.name': '...' }
@@ -10,14 +9,16 @@ export class CriteriaNode {
     entityName;
     parent;
     key;
+    strict;
     payload;
     prop;
     index;
-    constructor(metadata, entityName, parent, key, validate = true) {
+    constructor(metadata, entityName, parent, key, validate = true, strict = false) {
         this.metadata = metadata;
         this.entityName = entityName;
         this.parent = parent;
         this.key = key;
+        this.strict = strict;
         const meta = parent && metadata.find(parent.entityName);
         if (meta && key) {
             const pks = Utils.splitPrimaryKeys(key);
@@ -65,13 +66,13 @@ export class CriteriaNode {
             default: return false;
         }
     }
-    renameFieldToPK(qb) {
-        let joinAlias = qb.getAliasForJoinPath(this.getPath());
+    renameFieldToPK(qb, ownerAlias) {
+        const joinAlias = qb.getAliasForJoinPath(this.getPath(), { matchPopulateJoins: true });
         if (!joinAlias && this.parent && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(this.prop.kind) && this.prop.owner) {
-            joinAlias = qb.getAliasForJoinPath(this.parent.getPath());
-            return Utils.getPrimaryKeyHash(this.prop.joinColumns.map(col => `${joinAlias ?? qb.alias}.${col}`));
+            const alias = qb.getAliasForJoinPath(this.parent.getPath()) ?? ownerAlias ?? qb.alias;
+            return Utils.getPrimaryKeyHash(this.prop.joinColumns.map(col => `${alias}.${col}`));
         }
-        const alias = joinAlias ?? qb.alias;
+        const alias = joinAlias ?? ownerAlias ?? qb.alias;
         if (this.prop.kind === ReferenceKind.MANY_TO_MANY) {
             return Utils.getPrimaryKeyHash(this.prop.inverseJoinColumns.map(col => `${alias}.${col}`));
         }
@@ -106,8 +107,11 @@ export class CriteriaNode {
     aliased(field, alias) {
         return alias ? `${alias}.${field}` : field;
     }
+    isStrict() {
+        return this.strict;
+    }
     /** @ignore */
-    [inspect.custom]() {
+    [Symbol.for('nodejs.util.inspect.custom')]() {
         const o = {};
         ['entityName', 'key', 'index', 'payload']
             .filter(k => this[k] !== undefined)

package/query/CriteriaNodeFactory.js

@@ -1,4 +1,4 @@
-import { isRaw, JsonType, RawQueryFragment, ReferenceKind, Utils, ValidationError, } from '@mikro-orm/core';
+import { GroupOperator, isRaw, JsonType, RawQueryFragment, ReferenceKind, Utils, ValidationError, } from '@mikro-orm/core';
 import { ObjectCriteriaNode } from './ObjectCriteriaNode.js';
 import { ArrayCriteriaNode } from './ArrayCriteriaNode.js';
 import { ScalarCriteriaNode } from './ScalarCriteriaNode.js';
@@ -36,7 +36,7 @@ export class CriteriaNodeFactory {
     }
     static createObjectNode(metadata, entityName, payload, parent, key) {
         const meta = metadata.find(entityName);
-        const node = new ObjectCriteriaNode(metadata, entityName, parent, key);
+        const node = new ObjectCriteriaNode(metadata, entityName, parent, key, true, payload.__strict);
         node.payload = {};
         for (const key of Object.keys(payload)) {
             node.payload[key] = this.createObjectItemNode(metadata, entityName, node, payload, key, meta);
@@ -46,10 +46,14 @@ export class CriteriaNodeFactory {
     static createObjectItemNode(metadata, entityName, node, payload, key, meta) {
         const prop = meta?.properties[key];
         const childEntity = prop && prop.kind !== ReferenceKind.SCALAR ? prop.type : entityName;
-        if (prop?.customType instanceof JsonType) {
+        const isNotEmbedded = prop?.kind !== ReferenceKind.EMBEDDED;
+        if (isNotEmbedded && prop?.customType instanceof JsonType) {
             return this.createScalarNode(metadata, childEntity, payload[key], node, key);
         }
-        if (prop?.kind !== ReferenceKind.EMBEDDED) {
+        if (prop?.kind === ReferenceKind.SCALAR && payload[key] != null && Object.keys(payload[key]).some(f => f in GroupOperator)) {
+            throw ValidationError.cannotUseGroupOperatorsInsideScalars(entityName, prop.name, payload);
+        }
+        if (isNotEmbedded) {
             return this.createNode(metadata, childEntity, payload[key], node, key);
         }
         if (payload[key] == null) {
@@ -66,11 +70,12 @@ export class CriteriaNodeFactory {
             throw ValidationError.cannotUseOperatorsInsideEmbeddables(entityName, prop.name, payload);
         }
         const map = Object.keys(payload[key]).reduce((oo, k) => {
-            if (!prop.embeddedProps[k] && !allowedOperators.includes(k)) {
+            const embeddedProp = prop.embeddedProps[k] ?? Object.values(prop.embeddedProps).find(p => p.name === k);
+            if (!embeddedProp && !allowedOperators.includes(k)) {
                 throw ValidationError.invalidEmbeddableQuery(entityName, k, prop.type);
             }
-            if (prop.embeddedProps[k]) {
-                oo[prop.embeddedProps[k].name] = payload[key][k];
+            if (embeddedProp) {
+                oo[embeddedProp.name] = payload[key][k];
             }
             else if (typeof payload[key][k] === 'object') {
                 oo[k] = JSON.stringify(payload[key][k]);

package/query/NativeQueryBuilder.js

@@ -261,7 +261,7 @@ export class NativeQueryBuilder {
         }
         if (this.options.where?.sql.trim()) {
             this.parts.push(`where ${this.options.where.sql}`);
-            this.params.push(...this.options.where.params);
+            this.options.where.params.forEach(p => this.params.push(p));
         }
         if (this.options.groupBy) {
             const fields = this.options.groupBy.map(field => this.quote(field));

package/query/ObjectCriteriaNode.d.ts

@@ -5,6 +5,7 @@ import type { ICriteriaNodeProcessOptions, IQueryBuilder } from '../typings.js';
  */
 export declare class ObjectCriteriaNode<T extends object> extends CriteriaNode<T> {
     process(qb: IQueryBuilder<T>, options?: ICriteriaNodeProcessOptions): any;
+    isStrict(): boolean;
     unwrap(): any;
     willAutoJoin(qb: IQueryBuilder<T>, alias?: string, options?: ICriteriaNodeProcessOptions): boolean;
     shouldInline(payload: any): boolean;

package/query/ObjectCriteriaNode.js

@@ -1,4 +1,4 @@
-import { ALIAS_REPLACEMENT, QueryFlag, raw, RawQueryFragment, ReferenceKind, Utils, } from '@mikro-orm/core';
+import { ALIAS_REPLACEMENT, GroupOperator, QueryFlag, raw, RawQueryFragment, ReferenceKind, Utils, } from '@mikro-orm/core';
 import { CriteriaNode } from './CriteriaNode.js';
 import { JoinType, QueryType } from './enums.js';
 /**
@@ -6,7 +6,8 @@ import { JoinType, QueryType } from './enums.js';
  */
 export class ObjectCriteriaNode extends CriteriaNode {
     process(qb, options) {
-        const nestedAlias = qb.getAliasForJoinPath(this.getPath(), options);
+        const matchPopulateJoins = options?.matchPopulateJoins || (this.prop && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(this.prop.kind));
+        const nestedAlias = qb.getAliasForJoinPath(this.getPath(), { ...options, matchPopulateJoins });
         const ownerAlias = options?.alias || qb.alias;
         const keys = Object.keys(this.payload);
         let alias = options?.alias;
@@ -57,6 +58,22 @@ export class ObjectCriteriaNode extends CriteriaNode {
             }
             alias = this.autoJoin(qb, ownerAlias, options);
         }
+        if (this.prop && nestedAlias) {
+            const toOneProperty = [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(this.prop.kind);
+            // if the property is nullable and the filter is strict, we need to use left join, so we mimic the inner join behaviour
+            // with an exclusive condition on the join columns:
+            // - if the owning column is null, the row is missing, we don't apply the filter
+            // - if the target column is not null, the row is matched, we apply the filter
+            if (toOneProperty && this.prop.nullable && this.isStrict()) {
+                const key = this.prop.owner ? this.prop.name : this.prop.referencedPKs;
+                qb.andWhere({
+                    $or: [
+                        { [ownerAlias + '.' + key]: null },
+                        { [nestedAlias + '.' + Utils.getPrimaryKeyHash(this.prop.referencedPKs)]: { $ne: null } },
+                    ],
+                });
+            }
+        }
         return keys.reduce((o, field) => {
             const childNode = this.payload[field];
             const payload = childNode.process(qb, { ...options, alias: this.prop ? alias : ownerAlias });
@@ -66,13 +83,14 @@ export class ObjectCriteriaNode extends CriteriaNode {
             const virtual = childNode.prop?.persist === false && !childNode.prop?.formula;
             // if key is missing, we are inside group operator and we need to prefix with alias
             const primaryKey = this.key && this.metadata.find(this.entityName)?.primaryKeys.includes(field);
+            const isToOne = childNode.prop && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(childNode.prop.kind);
             if (childNode.shouldInline(payload)) {
-                const childAlias = qb.getAliasForJoinPath(childNode.getPath(), options);
+                const childAlias = qb.getAliasForJoinPath(childNode.getPath(), { preferNoBranch: isToOne, ...options });
                 const a = qb.helper.isTableNameAliasRequired(qb.type) ? alias : undefined;
                 this.inlineChildPayload(o, payload, field, a, childAlias);
             }
             else if (childNode.shouldRename(payload)) {
-                this.inlineCondition(childNode.renameFieldToPK(qb), o, payload);
+                this.inlineCondition(childNode.renameFieldToPK(qb, alias), o, payload);
             }
             else if (isRawField) {
                 const rawField = RawQueryFragment.getKnownFragment(field);
@@ -87,6 +105,11 @@ export class ObjectCriteriaNode extends CriteriaNode {
             return o;
         }, {});
     }
+    isStrict() {
+        return this.strict || Object.keys(this.payload).some(key => {
+            return this.payload[key].isStrict();
+        });
+    }
     unwrap() {
         return Object.keys(this.payload).reduce((o, field) => {
             o[field] = this.payload[field].unwrap();
@@ -137,7 +160,7 @@ export class ObjectCriteriaNode extends CriteriaNode {
                 delete payload[k];
                 o[this.aliased(field, alias)] = { [k]: tmp, ...o[this.aliased(field, alias)] };
             }
-            else if (Utils.isGroupOperator(k) && Array.isArray(payload[k])) {
+            else if (k in GroupOperator && Array.isArray(payload[k])) {
                 this.inlineArrayChildPayload(o, payload[k], k, prop, childAlias, alias);
             }
             else if (this.isPrefixed(k) || Utils.isOperator(k) || !childAlias) {
@@ -157,7 +180,7 @@ export class ObjectCriteriaNode extends CriteriaNode {
             o[key] = value;
             return;
         }
-        /* v8 ignore next 4 */
+        /* v8 ignore next */
         if (key === '$and') {
             o.$and.push({ [key]: value });
             return;
@@ -206,12 +229,16 @@ export class ObjectCriteriaNode extends CriteriaNode {
         }
         else {
             const prev = qb._fields?.slice();
-            qb[method](field, nestedAlias, undefined, JoinType.leftJoin, path);
+            const toOneProperty = [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(this.prop.kind);
+            const joinType = toOneProperty && !this.prop.nullable
+                ? JoinType.innerJoin
+                : JoinType.leftJoin;
+            qb[method](field, nestedAlias, undefined, joinType, path);
             if (!qb.hasFlag(QueryFlag.INFER_POPULATE)) {
                 qb._fields = prev;
             }
         }
-        if (!options || options.type !== 'orderBy') {
+        if (options?.type !== 'orderBy') {
             qb.scheduleFilterCheck(path);
         }
         return nestedAlias;

package/query/QueryBuilder.d.ts

@@ -1,5 +1,4 @@
-import { inspect } from 'node:util';
-import { type AnyEntity, type ConnectionType, type Dictionary, type EntityData, type EntityKey, type EntityManager, type EntityMetadata, type EntityName, type EntityProperty, type ExpandProperty, type FlushMode, type GroupOperator, type Loaded, LockMode, type LoggingOptions, type MetadataStorage, type ObjectQuery, PopulateHint, type PopulateOptions, type QBFilterQuery, type QBQueryOrderMap, QueryFlag, type QueryOrderMap, type QueryResult, RawQueryFragment, type RequiredEntityData, type Transaction } from '@mikro-orm/core';
+import { type AnyEntity, type ConnectionType, type Dictionary, type EntityData, type EntityKey, type EntityManager, type EntityMetadata, type EntityName, type EntityProperty, type ExpandProperty, type FilterOptions, type FlushMode, type GroupOperator, type Loaded, LockMode, type LoggingOptions, type MetadataStorage, type ObjectQuery, PopulateHint, type PopulateOptions, type QBFilterQuery, type QBQueryOrderMap, QueryFlag, type QueryOrderMap, type QueryResult, RawQueryFragment, type RequiredEntityData, type Transaction } from '@mikro-orm/core';
 import { JoinType, QueryType } from './enums.js';
 import type { AbstractSqlDriver } from '../AbstractSqlDriver.js';
 import { type Alias, type OnConflictClause, QueryBuilderHelper } from './QueryBuilderHelper.js';
@@ -11,6 +10,30 @@ export interface ExecuteOptions {
     mapResults?: boolean;
     mergeResults?: boolean;
 }
+export interface QBStreamOptions {
+    /**
+     * Results are mapped to entities, if you set `mapResults: false` you will get POJOs instead.
+     *
+     * @default true
+     */
+    mapResults?: boolean;
+    /**
+     * When populating to-many relations, the ORM streams fully merged entities instead of yielding every row.
+     * You can opt out of this behavior by specifying `mergeResults: false`. This will yield every row from
+     * the SQL result, but still mapped to entities, meaning that to-many collections will contain at most
+     * one item, and you will get duplicate root entities when they have multiple items in the populated
+     * collection.
+     *
+     * @default true
+     */
+    mergeResults?: boolean;
+    /**
+     * When enabled, the driver will return the raw database results without renaming the fields to match the entity property names.
+     *
+     * @default false
+     */
+    rawResults?: boolean;
+}
 type AnyString = string & {};
 type Compute<T> = {
     [K in keyof T]: T[K];
@@ -140,7 +163,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     /**
      * Apply filters to the QB where condition.
      */
-    applyFilters(filterOptions?: Dictionary<boolean | Dictionary> | string[] | boolean): Promise<void>;
+    applyFilters(filterOptions?: FilterOptions): Promise<void>;
     private readonly autoJoinedPaths;
     /**
      * @internal
@@ -149,7 +172,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     /**
      * @internal
      */
-    applyJoinedFilters(em: EntityManager, filterOptions?: Dictionary<boolean | Dictionary> | string[] | boolean): Promise<void>;
+    applyJoinedFilters(em: EntityManager, filterOptions: FilterOptions | undefined): Promise<void>;
     withSubQuery(subQuery: RawQueryFragment | NativeQueryBuilder, alias: string): this;
     where(cond: QBFilterQuery<Entity>, operator?: keyof typeof GroupOperator): this;
     where(cond: string, params?: any[], operator?: keyof typeof GroupOperator): this;
@@ -158,6 +181,8 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     orWhere(cond: QBFilterQuery<Entity>): this;
     orWhere(cond: string, params?: any[]): this;
     orderBy(orderBy: QBQueryOrderMap<Entity> | QBQueryOrderMap<Entity>[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
+    andOrderBy(orderBy: QBQueryOrderMap<Entity> | QBQueryOrderMap<Entity>[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
+    private processOrderBy;
     groupBy(fields: EntityKeyOrString<Entity> | readonly EntityKeyOrString<Entity>[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
     having(cond?: QBFilterQuery | string, params?: any[], operator?: keyof typeof GroupOperator): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
     andHaving(cond?: QBFilterQuery | string, params?: any[]): SelectQueryBuilder<Entity, RootAlias, Hint, Context>;
@@ -182,17 +207,17 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     /**
      * Adds index hint to the FROM clause.
      */
-    indexHint(sql: string): this;
+    indexHint(sql: string | undefined): this;
     /**
      * Prepend comment to the sql query using the syntax `/* ... *&#8205;/`. Some characters are forbidden such as `/*, *&#8205;/` and `?`.
      */
-    comment(comment: string | string[]): this;
+    comment(comment: string | string[] | undefined): 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;
+    hintComment(comment: string | string[] | undefined): 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.
@@ -245,14 +270,35 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * Use `method` to specify what kind of result you want to get (array/single/meta).
      */
     execute<U = any>(method?: 'all' | 'get' | 'run', options?: ExecuteOptions | boolean): Promise<U>;
+    private getConnection;
+    /**
+     * Executes the query and returns an async iterable (async generator) that yields results one by one.
+     * By default, the results are merged and mapped to entity instances, without adding them to the identity map.
+     * You can disable merging and mapping by passing the options `{ mergeResults: false, mapResults: false }`.
+     * This is useful for processing large datasets without loading everything into memory at once.
+     *
+     * ```ts
+     * const qb = em.createQueryBuilder(Book, 'b');
+     * qb.select('*').where({ title: '1984' }).leftJoinAndSelect('b.author', 'a');
+     *
+     * for await (const book of qb.stream()) {
+     *   // book is an instance of Book entity
+     *   console.log(book.title, book.author.name);
+     * }
+     * ```
+     */
+    stream(options?: QBStreamOptions): AsyncIterableIterator<Loaded<Entity, Hint>>;
     /**
      * Alias for `qb.getResultList()`
      */
     getResult(): Promise<Loaded<Entity, Hint>[]>;
     /**
-     * Executes the query, returning array of results
+     * Executes the query, returning array of results mapped to entity instances.
      */
     getResultList(limit?: number): Promise<Loaded<Entity, Hint>[]>;
+    private propagatePopulateHint;
+    private mapResult;
+    private mapResults;
     /**
      * Executes the query, returning the first result or null
      */
@@ -290,6 +336,11 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     processPopulateHint(): void;
     private processPopulateWhere;
     private mergeOnConditions;
+    /**
+     * When adding an inner join on a left joined relation, we need to nest them,
+     * otherwise the inner join could discard rows of the root table.
+     */
+    private processNestedJoins;
     private hasToManyJoins;
     protected wrapPaginateSubQuery(meta: EntityMetadata): void;
     private pruneExtraJoins;
@@ -302,8 +353,6 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     private createQueryBuilderHelper;
     private ensureFromClause;
     private ensureNotFinalized;
-    /** @ignore */
-    [inspect.custom](depth?: number): string;
 }
 export interface RunQueryBuilder<Entity extends object> extends Omit<QueryBuilder<Entity, any, any>, 'getResult' | 'getSingleResult' | 'getResultList' | 'where'> {
     where(cond: QBFilterQuery<Entity> | string, params?: keyof typeof GroupOperator | any[], operator?: keyof typeof GroupOperator): this;