@mikro-orm/sql 7.0.0-rc.2 → 7.0.0

package/plugin/transformer.js

@@ -1,44 +1,52 @@
 import { ReferenceKind, isRaw, } from '@mikro-orm/core';
 import { AliasNode, ColumnNode, ColumnUpdateNode, OperationNodeTransformer, PrimitiveValueListNode, ReferenceNode, SchemableIdentifierNode, TableNode, ValueListNode, ValueNode, ValuesNode, } from 'kysely';
 export class MikroTransformer extends OperationNodeTransformer {
-    em;
-    options;
     /**
      * Context stack to support nested queries (subqueries, CTEs)
      * Each level of query scope has its own Map of table aliases/names to EntityMetadata
      * Top of stack (highest index) is the current scope
      */
-    contextStack = [];
+    #contextStack = [];
     /**
      * Subquery alias map: maps subquery/CTE alias to its source table metadata
      * Used to resolve columns from subqueries/CTEs to their original table definitions
      */
-    subqueryAliasMap = new Map();
-    metadata;
-    platform;
+    #subqueryAliasMap = new Map();
+    #metadata;
+    #platform;
     /**
      * Global map of all entities involved in the query.
      * Populated during AST transformation and used for result transformation.
      */
-    entityMap = new Map();
+    #entityMap = new Map();
+    #em;
+    #options;
     constructor(em, options = {}) {
         super();
-        this.em = em;
-        this.options = options;
-        this.metadata = em.getMetadata();
-        this.platform = em.getDriver().getPlatform();
+        this.#em = em;
+        this.#options = options;
+        this.#metadata = em.getMetadata();
+        this.#platform = em.getDriver().getPlatform();
     }
     reset() {
-        this.subqueryAliasMap.clear();
-        this.entityMap.clear();
+        this.#subqueryAliasMap.clear();
+        this.#entityMap.clear();
     }
     getOutputEntityMap() {
-        return this.entityMap;
+        return this.#entityMap;
+    }
+    /** @internal */
+    getContextStack() {
+        return this.#contextStack;
+    }
+    /** @internal */
+    getSubqueryAliasMap() {
+        return this.#subqueryAliasMap;
     }
     transformSelectQuery(node, queryId) {
         // Push a new context for this query scope (starts with inherited parent context)
         const currentContext = new Map();
-        this.contextStack.push(currentContext);
+        this.#contextStack.push(currentContext);
         try {
             // Process WITH clause (CTEs) first - they define names available in this scope
             if (node.with) {
@@ -60,12 +68,12 @@ export class MikroTransformer extends OperationNodeTransformer {
         }
         finally {
             // Pop the context when exiting this query scope
-            this.contextStack.pop();
+            this.#contextStack.pop();
         }
     }
     transformInsertQuery(node, queryId) {
         const currentContext = new Map();
-        this.contextStack.push(currentContext);
+        this.#contextStack.push(currentContext);
         try {
             let entityMeta;
             if (node.into) {
@@ -75,16 +83,12 @@ export class MikroTransformer extends OperationNodeTransformer {
                     if (meta) {
                         entityMeta = meta;
                         currentContext.set(meta.tableName, meta);
-                        this.entityMap.set(meta.tableName, meta);
+                        this.#entityMap.set(meta.tableName, meta);
                     }
                 }
             }
-            const nodeWithHooks = this.options.processOnCreateHooks && entityMeta
-                ? this.processOnCreateHooks(node, entityMeta)
-                : node;
-            const nodeWithConvertedValues = this.options.convertValues && entityMeta
-                ? this.processInsertValues(nodeWithHooks, entityMeta)
-                : nodeWithHooks;
+            const nodeWithHooks = this.#options.processOnCreateHooks && entityMeta ? this.processOnCreateHooks(node, entityMeta) : node;
+            const nodeWithConvertedValues = this.#options.convertValues && entityMeta ? this.processInsertValues(nodeWithHooks, entityMeta) : nodeWithHooks;
             // Handle ON CONFLICT clause
             let finalNode = nodeWithConvertedValues;
             if (node.onConflict?.updates && entityMeta) {
@@ -95,14 +99,14 @@ export class MikroTransformer extends OperationNodeTransformer {
                     table: node.into, // Dummy table
                     updates: node.onConflict.updates,
                 };
-                const updatesWithHooks = this.options.processOnUpdateHooks
+                const updatesWithHooks = this.#options.processOnUpdateHooks
                     ? this.processOnUpdateHooks(tempUpdateNode, entityMeta).updates
                     : node.onConflict.updates;
                 const tempUpdateNodeWithHooks = {
                     ...tempUpdateNode,
                     updates: updatesWithHooks,
                 };
-                const updatesWithConvertedValues = this.options.convertValues
+                const updatesWithConvertedValues = this.#options.convertValues
                     ? this.processUpdateValues(tempUpdateNodeWithHooks, entityMeta).updates
                     : updatesWithHooks;
                 if (updatesWithConvertedValues && updatesWithConvertedValues !== node.onConflict.updates) {
@@ -119,12 +123,12 @@ export class MikroTransformer extends OperationNodeTransformer {
             return super.transformInsertQuery(finalNode, queryId);
         }
         finally {
-            this.contextStack.pop();
+            this.#contextStack.pop();
         }
     }
     transformUpdateQuery(node, queryId) {
         const currentContext = new Map();
-        this.contextStack.push(currentContext);
+        this.#contextStack.push(currentContext);
         try {
             let entityMeta;
             if (node.table && TableNode.is(node.table)) {
@@ -134,7 +138,7 @@ export class MikroTransformer extends OperationNodeTransformer {
                     if (meta) {
                         entityMeta = meta;
                         currentContext.set(meta.tableName, meta);
-                        this.entityMap.set(meta.tableName, meta);
+                        this.#entityMap.set(meta.tableName, meta);
                     }
                 }
             }
@@ -150,21 +154,17 @@ export class MikroTransformer extends OperationNodeTransformer {
                     this.processJoinNode(join, currentContext);
                 }
             }
-            const nodeWithHooks = this.options.processOnUpdateHooks && entityMeta
-                ? this.processOnUpdateHooks(node, entityMeta)
-                : node;
-            const nodeWithConvertedValues = this.options.convertValues && entityMeta
-                ? this.processUpdateValues(nodeWithHooks, entityMeta)
-                : nodeWithHooks;
+            const nodeWithHooks = this.#options.processOnUpdateHooks && entityMeta ? this.processOnUpdateHooks(node, entityMeta) : node;
+            const nodeWithConvertedValues = this.#options.convertValues && entityMeta ? this.processUpdateValues(nodeWithHooks, entityMeta) : nodeWithHooks;
             return super.transformUpdateQuery(nodeWithConvertedValues, queryId);
         }
         finally {
-            this.contextStack.pop();
+            this.#contextStack.pop();
         }
     }
     transformDeleteQuery(node, queryId) {
         const currentContext = new Map();
-        this.contextStack.push(currentContext);
+        this.#contextStack.push(currentContext);
         try {
             const froms = node.from?.froms;
             if (froms && froms.length > 0) {
@@ -175,7 +175,7 @@ export class MikroTransformer extends OperationNodeTransformer {
                         const meta = this.findEntityMetadata(tableName);
                         if (meta) {
                             currentContext.set(meta.tableName, meta);
-                            this.entityMap.set(meta.tableName, meta);
+                            this.#entityMap.set(meta.tableName, meta);
                         }
                     }
                 }
@@ -189,24 +189,24 @@ export class MikroTransformer extends OperationNodeTransformer {
             return super.transformDeleteQuery(node, queryId);
         }
         finally {
-            this.contextStack.pop();
+            this.#contextStack.pop();
         }
     }
     transformMergeQuery(node, queryId) {
         const currentContext = new Map();
-        this.contextStack.push(currentContext);
+        this.#contextStack.push(currentContext);
         try {
             return super.transformMergeQuery(node, queryId);
         }
         finally {
-            this.contextStack.pop();
+            this.#contextStack.pop();
         }
     }
     transformIdentifier(node, queryId) {
         node = super.transformIdentifier(node, queryId);
         const parent = this.nodeStack[this.nodeStack.length - 2];
         // Transform table names when tableNamingStrategy is 'entity'
-        if (this.options.tableNamingStrategy === 'entity' && parent && SchemableIdentifierNode.is(parent)) {
+        if (this.#options.tableNamingStrategy === 'entity' && parent && SchemableIdentifierNode.is(parent)) {
             const meta = this.findEntityMetadata(node.name);
             if (meta) {
                 return {
@@ -217,7 +217,9 @@ export class MikroTransformer extends OperationNodeTransformer {
         }
         // Transform column names when columnNamingStrategy is 'property'
         // Support ColumnNode, ColumnUpdateNode, and ReferenceNode (for JOIN conditions)
-        if (this.options.columnNamingStrategy === 'property' && parent && (ColumnNode.is(parent) || ColumnUpdateNode.is(parent) || ReferenceNode.is(parent))) {
+        if (this.#options.columnNamingStrategy === 'property' &&
+            parent &&
+            (ColumnNode.is(parent) || ColumnUpdateNode.is(parent) || ReferenceNode.is(parent))) {
             const ownerMeta = this.findOwnerEntityInContext();
             if (ownerMeta) {
                 const prop = ownerMeta.properties[node.name];
@@ -245,8 +247,8 @@ export class MikroTransformer extends OperationNodeTransformer {
             const tableName = this.getTableName(reference.table);
             if (tableName) {
                 // First, check in subquery alias map (for CTE/subquery columns)
-                if (this.subqueryAliasMap.has(tableName)) {
-                    return this.subqueryAliasMap.get(tableName);
+                if (this.#subqueryAliasMap.has(tableName)) {
+                    return this.#subqueryAliasMap.get(tableName);
                 }
                 // Find entity metadata to get the actual table name
                 // Context uses table names (meta.tableName) as keys, not entity names
@@ -273,16 +275,16 @@ export class MikroTransformer extends OperationNodeTransformer {
             }
         }
         // If no explicit table reference, use the first entity in current context
-        if (this.contextStack.length > 0) {
-            const currentContext = this.contextStack[this.contextStack.length - 1];
+        if (this.#contextStack.length > 0) {
+            const currentContext = this.#contextStack[this.#contextStack.length - 1];
             for (const [alias, meta] of currentContext.entries()) {
                 if (meta) {
                     return meta;
                 }
                 // If the context value is undefined but the alias is in subqueryAliasMap,
                 // use the mapped metadata (for CTE/subquery cases)
-                if (!meta && this.subqueryAliasMap.has(alias)) {
-                    const mappedMeta = this.subqueryAliasMap.get(alias);
+                if (!meta && this.#subqueryAliasMap.has(alias)) {
+                    const mappedMeta = this.#subqueryAliasMap.get(alias);
                     if (mappedMeta) {
                         return mappedMeta;
                     }
@@ -312,7 +314,7 @@ export class MikroTransformer extends OperationNodeTransformer {
         }
         const newRows = node.values.values.map(row => {
             const valuesToAdd = missingProps.map(prop => {
-                const val = prop.onCreate(undefined, this.em);
+                const val = prop.onCreate(undefined, this.#em);
                 return val;
             });
             if (ValueListNode.is(row)) {
@@ -350,7 +352,7 @@ export class MikroTransformer extends OperationNodeTransformer {
         }
         const newUpdates = [...node.updates];
         for (const prop of missingProps) {
-            const val = prop.onUpdate(undefined, this.em);
+            const val = prop.onUpdate(undefined, this.#em);
             newUpdates.push(ColumnUpdateNode.create(ColumnNode.create(prop.name), ValueNode.create(val)));
         }
         return {
@@ -465,7 +467,7 @@ export class MikroTransformer extends OperationNodeTransformer {
         return meta.props.find(prop => prop.fieldNames?.includes(columnName));
     }
     shouldConvertValues() {
-        return !!this.options.convertValues;
+        return !!this.#options.convertValues;
     }
     prepareInputValue(prop, value, enabled) {
         if (!enabled || !prop || value == null) {
@@ -480,10 +482,14 @@ export class MikroTransformer extends OperationNodeTransformer {
             }
         }
         if (prop.customType && !isRaw(value)) {
-            return prop.customType.convertToDatabaseValue(value, this.platform, { fromQuery: true, key: prop.name, mode: 'query-data' });
+            return prop.customType.convertToDatabaseValue(value, this.#platform, {
+                fromQuery: true,
+                key: prop.name,
+                mode: 'query-data',
+            });
         }
         if (value instanceof Date) {
-            return this.platform.processDateProperty(value);
+            return this.#platform.processDateProperty(value);
         }
         return value;
     }
@@ -494,8 +500,8 @@ export class MikroTransformer extends OperationNodeTransformer {
      */
     lookupInContextStack(tableNameOrAlias) {
         // Search from top of stack (current scope) to bottom (parent scopes)
-        for (let i = this.contextStack.length - 1; i >= 0; i--) {
-            const context = this.contextStack[i];
+        for (let i = this.#contextStack.length - 1; i >= 0; i--) {
+            const context = this.#contextStack[i];
             if (context.has(tableNameOrAlias)) {
                 return context.get(tableNameOrAlias);
             }
@@ -517,10 +523,10 @@ export class MikroTransformer extends OperationNodeTransformer {
                 if (cte.expression?.kind === 'SelectQueryNode') {
                     const sourceMeta = this.extractSourceTableFromSelectQuery(cte.expression);
                     if (sourceMeta) {
-                        this.subqueryAliasMap.set(cteName, sourceMeta);
+                        this.#subqueryAliasMap.set(cteName, sourceMeta);
                         // Add CTE to entityMap so it can be used for result transformation if needed
                         // (though CTEs usually don't appear in result rows directly, but their columns might)
-                        this.entityMap.set(cteName, sourceMeta);
+                        this.#entityMap.set(cteName, sourceMeta);
                     }
                 }
             }
@@ -550,11 +556,11 @@ export class MikroTransformer extends OperationNodeTransformer {
                     if (aliasName) {
                         context.set(aliasName, meta);
                         if (meta) {
-                            this.entityMap.set(aliasName, meta);
+                            this.#entityMap.set(aliasName, meta);
                         }
                         // Also map the alias in subqueryAliasMap if the table name is a CTE
-                        if (this.subqueryAliasMap.has(tableName)) {
-                            this.subqueryAliasMap.set(aliasName, this.subqueryAliasMap.get(tableName));
+                        if (this.#subqueryAliasMap.has(tableName)) {
+                            this.#subqueryAliasMap.set(aliasName, this.#subqueryAliasMap.get(tableName));
                         }
                     }
                 }
@@ -567,7 +573,7 @@ export class MikroTransformer extends OperationNodeTransformer {
                     // Try to extract the source table from the subquery
                     const sourceMeta = this.extractSourceTableFromSelectQuery(from.node);
                     if (sourceMeta) {
-                        this.subqueryAliasMap.set(aliasName, sourceMeta);
+                        this.#subqueryAliasMap.set(aliasName, sourceMeta);
                     }
                 }
             }
@@ -586,7 +592,7 @@ export class MikroTransformer extends OperationNodeTransformer {
                 const meta = this.findEntityMetadata(tableName);
                 context.set(tableName, meta);
                 if (meta) {
-                    this.entityMap.set(tableName, meta);
+                    this.#entityMap.set(tableName, meta);
                 }
             }
         }
@@ -606,11 +612,11 @@ export class MikroTransformer extends OperationNodeTransformer {
                     if (aliasName) {
                         context.set(aliasName, meta);
                         if (meta) {
-                            this.entityMap.set(aliasName, meta);
+                            this.#entityMap.set(aliasName, meta);
                         }
                         // Also map the alias in subqueryAliasMap if the table name is a CTE
-                        if (this.subqueryAliasMap.has(tableName)) {
-                            this.subqueryAliasMap.set(aliasName, this.subqueryAliasMap.get(tableName));
+                        if (this.#subqueryAliasMap.has(tableName)) {
+                            this.#subqueryAliasMap.set(aliasName, this.#subqueryAliasMap.get(tableName));
                         }
                     }
                 }
@@ -623,7 +629,7 @@ export class MikroTransformer extends OperationNodeTransformer {
                     // Try to extract the source table from the subquery
                     const sourceMeta = this.extractSourceTableFromSelectQuery(joinTable.node);
                     if (sourceMeta) {
-                        this.subqueryAliasMap.set(aliasName, sourceMeta);
+                        this.#subqueryAliasMap.set(aliasName, sourceMeta);
                     }
                 }
             }
@@ -643,7 +649,7 @@ export class MikroTransformer extends OperationNodeTransformer {
                 // Use table name (meta.tableName) as key to match transformUpdateQuery behavior
                 if (meta) {
                     context.set(meta.tableName, meta);
-                    this.entityMap.set(meta.tableName, meta);
+                    this.#entityMap.set(meta.tableName, meta);
                     // Also set with entity name for backward compatibility
                     context.set(tableName, meta);
                 }
@@ -706,11 +712,11 @@ export class MikroTransformer extends OperationNodeTransformer {
      * Find entity metadata by table name or entity name
      */
     findEntityMetadata(name) {
-        const byEntity = this.metadata.getByClassName(name, false);
+        const byEntity = this.#metadata.getByClassName(name, false);
         if (byEntity) {
             return byEntity;
         }
-        const allMetadata = Array.from(this.metadata);
+        const allMetadata = Array.from(this.#metadata);
         const byTable = allMetadata.find(m => m.tableName === name);
         if (byTable) {
             return byTable;
@@ -723,7 +729,9 @@ export class MikroTransformer extends OperationNodeTransformer {
      */
     transformResult(rows, entityMap) {
         // Only transform if columnNamingStrategy is 'property' or convertValues is true, and we have data
-        if ((this.options.columnNamingStrategy !== 'property' && !this.options.convertValues) || !rows || rows.length === 0) {
+        if ((this.#options.columnNamingStrategy !== 'property' && !this.#options.convertValues) ||
+            !rows ||
+            rows.length === 0) {
             return rows;
         }
         // If no entities found (e.g. raw query without known tables), return rows as is
@@ -818,7 +826,7 @@ export class MikroTransformer extends OperationNodeTransformer {
                 continue;
             }
             const converted = this.prepareOutputValue(prop, transformed[fieldName]);
-            if (this.options.columnNamingStrategy === 'property' && prop.name !== fieldName) {
+            if (this.#options.columnNamingStrategy === 'property' && prop.name !== fieldName) {
                 if (!(prop.name in transformed)) {
                     transformed[prop.name] = converted;
                 }
@@ -828,13 +836,13 @@ export class MikroTransformer extends OperationNodeTransformer {
                 delete transformed[fieldName];
                 continue;
             }
-            if (this.options.convertValues) {
+            if (this.#options.convertValues) {
                 transformed[fieldName] = converted;
             }
         }
         // Second pass: handle relation fields
         // Only run if columnNamingStrategy is 'property', as we don't want to rename FKs otherwise
-        if (this.options.columnNamingStrategy === 'property') {
+        if (this.#options.columnNamingStrategy === 'property') {
             for (const [fieldName, relationPropertyName] of Object.entries(relationFieldMap)) {
                 if (fieldName in transformed && !(relationPropertyName in transformed)) {
                     // Move the foreign key value to the relation property name
@@ -846,35 +854,36 @@ export class MikroTransformer extends OperationNodeTransformer {
         return transformed;
     }
     prepareOutputValue(prop, value) {
-        if (!this.options.convertValues || !prop || value == null) {
+        if (!this.#options.convertValues || !prop || value == null) {
             return value;
         }
         if (prop.customType) {
-            return prop.customType.convertToJSValue(value, this.platform);
+            return prop.customType.convertToJSValue(value, this.#platform);
         }
         // Aligned with EntityComparator.getResultMapper logic
         if (prop.runtimeType === 'boolean') {
             // Use !! conversion like EntityComparator: value == null ? value : !!value
             return value == null ? value : !!value;
         }
-        if (prop.runtimeType === 'Date' && !this.platform.isNumericProperty(prop)) {
+        if (prop.runtimeType === 'Date' && !this.#platform.isNumericProperty(prop)) {
             // Aligned with EntityComparator: exclude numeric timestamp properties
             // If already Date instance or null, return as is
             if (value == null || value instanceof Date) {
                 return value;
             }
             // Handle timezone like EntityComparator.parseDate
-            const tz = this.platform.getTimezone();
+            const tz = this.#platform.getTimezone();
             if (!tz || tz === 'local') {
-                return this.platform.parseDate(value);
+                return this.#platform.parseDate(value);
             }
             // For non-local timezone, check if value already has timezone info
             // Number (timestamp) doesn't need timezone handling, string needs check
-            if (typeof value === 'number' || (typeof value === 'string' && (value.includes('+') || value.lastIndexOf('-') > 10 || value.endsWith('Z')))) {
-                return this.platform.parseDate(value);
+            if (typeof value === 'number' ||
+                (typeof value === 'string' && (value.includes('+') || value.lastIndexOf('-') > 10 || value.endsWith('Z')))) {
+                return this.#platform.parseDate(value);
             }
             // Append timezone if not present (only for string values)
-            return this.platform.parseDate(value + tz);
+            return this.#platform.parseDate(value + tz);
         }
         // For all other runtimeTypes (number, string, bigint, Buffer, object, any, etc.)
         // EntityComparator just assigns directly without conversion

package/query/ArrayCriteriaNode.d.ts

@@ -6,6 +6,6 @@ import type { IQueryBuilder, ICriteriaNodeProcessOptions } from '../typings.js';
 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;
+    willAutoJoin(qb: IQueryBuilder<T>, alias?: string, options?: ICriteriaNodeProcessOptions): boolean;
     isStrict(): boolean;
 }

package/query/CriteriaNode.js

@@ -53,22 +53,34 @@ export class CriteriaNode {
         const type = this.prop ? this.prop.kind : null;
         const composite = this.prop?.joinColumns ? this.prop.joinColumns.length > 1 : false;
         const rawField = RawQueryFragment.isKnownFragmentSymbol(this.key);
-        const scalar = payload === null || Utils.isPrimaryKey(payload) || payload instanceof RegExp || payload instanceof Date || rawField;
+        const scalar = payload === null ||
+            Utils.isPrimaryKey(payload) ||
+            payload instanceof RegExp ||
+            payload instanceof Date ||
+            rawField;
         const operator = Utils.isPlainObject(payload) && Utils.getObjectQueryKeys(payload).every(k => Utils.isOperator(k, false));
         if (composite) {
             return true;
         }
         switch (type) {
-            case ReferenceKind.MANY_TO_ONE: return false;
-            case ReferenceKind.ONE_TO_ONE: return !this.prop.owner;
-            case ReferenceKind.ONE_TO_MANY: return scalar || operator;
-            case ReferenceKind.MANY_TO_MANY: return scalar || operator;
-            default: return false;
+            case ReferenceKind.MANY_TO_ONE:
+                return false;
+            case ReferenceKind.ONE_TO_ONE:
+                return !this.prop.owner;
+            case ReferenceKind.ONE_TO_MANY:
+                return scalar || operator;
+            case ReferenceKind.MANY_TO_MANY:
+                return scalar || operator;
+            default:
+                return false;
         }
     }
     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) {
+        if (!joinAlias &&
+            this.parent &&
+            [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(this.prop.kind) &&
+            this.prop.owner) {
             const alias = qb.getAliasForJoinPath(this.parent.getPath()) ?? ownerAlias ?? qb.alias;
             return Utils.getPrimaryKeyHash(this.prop.joinColumns.map(col => `${alias}.${col}`));
         }
@@ -84,7 +96,9 @@ export class CriteriaNode {
         const parentPath = opts?.parentPath ?? this.parent?.getPath({ addIndex: addParentIndex }) ?? Utils.className(this.entityName);
         const index = opts?.addIndex && this.index != null ? `[${this.index}]` : '';
         // ignore group operators to allow easier mapping (e.g. for orderBy)
-        const key = this.key && !RawQueryFragment.isKnownFragmentSymbol(this.key) && !['$and', '$or', '$not'].includes(this.key) ? '.' + this.key : '';
+        const key = this.key && !RawQueryFragment.isKnownFragmentSymbol(this.key) && !['$and', '$or', '$not'].includes(this.key)
+            ? '.' + this.key
+            : '';
         const ret = parentPath + index + key;
         if (this.isPivotJoin()) {
             // distinguish pivot table join from target entity join
@@ -97,7 +111,11 @@ export class CriteriaNode {
             return false;
         }
         const rawField = RawQueryFragment.isKnownFragmentSymbol(this.key);
-        const scalar = this.payload === null || Utils.isPrimaryKey(this.payload) || this.payload instanceof RegExp || this.payload instanceof Date || rawField;
+        const scalar = this.payload === null ||
+            Utils.isPrimaryKey(this.payload) ||
+            this.payload instanceof RegExp ||
+            this.payload instanceof Date ||
+            rawField;
         const operator = Utils.isObject(this.payload) && Utils.getObjectQueryKeys(this.payload).every(k => Utils.isOperator(k, false));
         return this.prop.kind === ReferenceKind.MANY_TO_MANY && (scalar || operator);
     }
@@ -116,7 +134,7 @@ export class CriteriaNode {
         const o = {};
         ['entityName', 'key', 'index', 'payload']
             .filter(k => this[k] !== undefined)
-            .forEach(k => o[k] = this[k]);
+            .forEach(k => (o[k] = this[k]));
         return `${this.constructor.name} ${inspect(o)}`;
     }
 }

package/query/CriteriaNodeFactory.js

@@ -2,13 +2,18 @@ import { GroupOperator, isRaw, JsonType, RawQueryFragment, ReferenceKind, Utils,
 import { ObjectCriteriaNode } from './ObjectCriteriaNode.js';
 import { ArrayCriteriaNode } from './ArrayCriteriaNode.js';
 import { ScalarCriteriaNode } from './ScalarCriteriaNode.js';
+import { EMBEDDABLE_ARRAY_OPS } from './enums.js';
 /**
  * @internal
  */
 export class CriteriaNodeFactory {
     static createNode(metadata, entityName, payload, parent, key, validate = true) {
         const rawField = RawQueryFragment.isKnownFragmentSymbol(key);
-        const scalar = Utils.isPrimaryKey(payload) || isRaw(payload) || payload instanceof RegExp || payload instanceof Date || rawField;
+        const scalar = Utils.isPrimaryKey(payload) ||
+            isRaw(payload) ||
+            payload instanceof RegExp ||
+            payload instanceof Date ||
+            rawField;
         if (Array.isArray(payload) && !scalar) {
             return this.createArrayNode(metadata, entityName, payload, parent, key, validate);
         }
@@ -65,15 +70,26 @@ export class CriteriaNodeFactory {
             }, {});
             return this.createNode(metadata, entityName, map, node, key, validate);
         }
+        // For array embeddeds stored as real columns, route property-level queries
+        // as scalar nodes so QueryBuilderHelper generates EXISTS subqueries with
+        // JSON array iteration.  Keys containing `~` indicate the property lives
+        // inside a parent's object-mode JSON column (MetadataDiscovery uses `~` as
+        // the glue for object embeds), where JSON path access is used instead.
+        if (prop.array && !String(key).includes('~')) {
+            const keys = Object.keys(val);
+            const hasOnlyArrayOps = keys.every(k => EMBEDDABLE_ARRAY_OPS.includes(k));
+            if (!hasOnlyArrayOps) {
+                return this.createScalarNode(metadata, entityName, val, node, key, validate);
+            }
+        }
         // array operators can be used on embedded properties
-        const allowedOperators = ['$contains', '$contained', '$overlap'];
-        const operator = Object.keys(val).some(f => Utils.isOperator(f) && !allowedOperators.includes(f));
+        const operator = Object.keys(val).some(f => Utils.isOperator(f) && !EMBEDDABLE_ARRAY_OPS.includes(f));
         if (operator) {
             throw ValidationError.cannotUseOperatorsInsideEmbeddables(entityName, prop.name, payload);
         }
         const map = Object.keys(val).reduce((oo, k) => {
             const embeddedProp = prop.embeddedProps[k] ?? Object.values(prop.embeddedProps).find(p => p.name === k);
-            if (!embeddedProp && !allowedOperators.includes(k)) {
+            if (!embeddedProp && !EMBEDDABLE_ARRAY_OPS.includes(k)) {
                 throw ValidationError.invalidEmbeddableQuery(entityName, k, prop.type);
             }
             if (embeddedProp) {