@mikro-orm/sql 7.0.0-dev.335 → 7.0.0-dev.337

package/AbstractSqlPlatform.d.ts

@@ -4,6 +4,7 @@ import { type SchemaHelper } from './schema/SchemaHelper.js';
 import type { IndexDef } from './typings.js';
 import { NativeQueryBuilder } from './query/NativeQueryBuilder.js';
 export declare abstract class AbstractSqlPlatform extends Platform {
+    #private;
     protected readonly schemaHelper?: SchemaHelper;
     usesPivotTable(): boolean;
     indexForeignKeys(): boolean;
@@ -26,6 +27,12 @@ export declare abstract class AbstractSqlPlatform extends Platform {
     quoteValue(value: any): string;
     getSearchJsonPropertySQL(path: string, type: string, aliased: boolean): string | RawQueryFragment;
     getSearchJsonPropertyKey(path: string[], type: string, aliased: boolean, value?: unknown): string | RawQueryFragment;
+    /**
+     * Quotes a key for use inside a JSON path expression (e.g. `$.key`).
+     * Simple alphanumeric keys are left unquoted; others are wrapped in double quotes.
+     * @internal
+     */
+    quoteJsonKey(key: string): string;
     getJsonIndexDefinition(index: IndexDef): string[];
     supportsUnionWhere(): boolean;
     supportsSchemas(): boolean;
@@ -42,6 +49,27 @@ export declare abstract class AbstractSqlPlatform extends Platform {
     quoteCollation(collation: string): string;
     /** @internal */
     protected validateCollationName(collation: string): void;
+    /** @internal */
+    validateJsonPropertyName(name: string): void;
+    /**
+     * Returns FROM clause for JSON array iteration.
+     * @internal
+     */
+    getJsonArrayFromSQL(column: string, alias: string, _properties: {
+        name: string;
+        type: string;
+    }[]): string;
+    /**
+     * Returns SQL expression to access an element's property within a JSON array iteration.
+     * @internal
+     */
+    getJsonArrayElementPropertySQL(alias: string, property: string, _type: string): string;
+    /**
+     * Wraps JSON array FROM clause and WHERE condition into a full EXISTS condition.
+     * MySQL overrides this because `json_table` doesn't support correlated subqueries.
+     * @internal
+     */
+    getJsonArrayExistsSQL(from: string, where: string): string;
     /**
      * Maps a runtime type name (e.g. 'string', 'number') to a driver-specific bind type constant.
      * Used by NativeQueryBuilder for output bindings.

package/AbstractSqlPlatform.js

@@ -3,6 +3,7 @@ import { SqlEntityRepository } from './SqlEntityRepository.js';
 import { SqlSchemaGenerator } from './schema/SqlSchemaGenerator.js';
 import { NativeQueryBuilder } from './query/NativeQueryBuilder.js';
 export class AbstractSqlPlatform extends Platform {
+    static #JSON_PROPERTY_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
     schemaHelper;
     usesPivotTable() {
         return true;
@@ -64,11 +65,18 @@ export class AbstractSqlPlatform extends Platform {
     }
     getSearchJsonPropertyKey(path, type, aliased, value) {
         const [a, ...b] = path;
-        const quoteKey = (key) => (/^[a-z]\w*$/i.exec(key) ? key : `"${key}"`);
         if (aliased) {
-            return raw(alias => `json_extract(${this.quoteIdentifier(`${alias}.${a}`)}, '$.${b.map(quoteKey).join('.')}')`);
+            return raw(alias => `json_extract(${this.quoteIdentifier(`${alias}.${a}`)}, '$.${b.map(this.quoteJsonKey).join('.')}')`);
         }
-        return raw(`json_extract(${this.quoteIdentifier(a)}, '$.${b.map(quoteKey).join('.')}')`);
+        return raw(`json_extract(${this.quoteIdentifier(a)}, '$.${b.map(this.quoteJsonKey).join('.')}')`);
+    }
+    /**
+     * Quotes a key for use inside a JSON path expression (e.g. `$.key`).
+     * Simple alphanumeric keys are left unquoted; others are wrapped in double quotes.
+     * @internal
+     */
+    quoteJsonKey(key) {
+        return /^[a-z]\w*$/i.exec(key) ? key : `"${key}"`;
     }
     getJsonIndexDefinition(index) {
         return index.columnNames.map(column => {
@@ -116,6 +124,34 @@ export class AbstractSqlPlatform extends Platform {
             throw new Error(`Invalid collation name: '${collation}'. Collation names must contain only word characters.`);
         }
     }
+    /** @internal */
+    validateJsonPropertyName(name) {
+        if (!AbstractSqlPlatform.#JSON_PROPERTY_NAME_RE.test(name)) {
+            throw new Error(`Invalid JSON property name: '${name}'. JSON property names must contain only alphanumeric characters and underscores.`);
+        }
+    }
+    /**
+     * Returns FROM clause for JSON array iteration.
+     * @internal
+     */
+    getJsonArrayFromSQL(column, alias, _properties) {
+        return `json_each(${column}) as ${this.quoteIdentifier(alias)}`;
+    }
+    /**
+     * Returns SQL expression to access an element's property within a JSON array iteration.
+     * @internal
+     */
+    getJsonArrayElementPropertySQL(alias, property, _type) {
+        return `${this.quoteIdentifier(alias)}.${this.quoteIdentifier(property)}`;
+    }
+    /**
+     * Wraps JSON array FROM clause and WHERE condition into a full EXISTS condition.
+     * MySQL overrides this because `json_table` doesn't support correlated subqueries.
+     * @internal
+     */
+    getJsonArrayExistsSQL(from, where) {
+        return `exists (select 1 from ${from} where ${where})`;
+    }
     /**
      * Maps a runtime type name (e.g. 'string', 'number') to a driver-specific bind type constant.
      * Used by NativeQueryBuilder for output bindings.

package/dialects/mysql/BaseMySqlPlatform.d.ts

@@ -5,6 +5,7 @@ import { AbstractSqlPlatform } from '../../AbstractSqlPlatform.js';
 import type { IndexDef } from '../../typings.js';
 import { MySqlNativeQueryBuilder } from './MySqlNativeQueryBuilder.js';
 export declare class BaseMySqlPlatform extends AbstractSqlPlatform {
+    #private;
     protected readonly schemaHelper: MySqlSchemaHelper;
     protected readonly exceptionConverter: MySqlExceptionConverter;
     protected readonly ORDER_BY_NULLS_TRANSLATE: {
@@ -42,5 +43,10 @@ export declare class BaseMySqlPlatform extends AbstractSqlPlatform {
     getFullTextWhereClause(): string;
     getFullTextIndexExpression(indexName: string, schemaName: string | undefined, tableName: string, columns: SimpleColumnMeta[]): string;
     getOrderByExpression(column: string, direction: string, collation?: string): string[];
+    getJsonArrayFromSQL(column: string, alias: string, properties: {
+        name: string;
+        type: string;
+    }[]): string;
+    getJsonArrayExistsSQL(from: string, where: string): string;
     getDefaultClientUrl(): string;
 }

package/dialects/mysql/BaseMySqlPlatform.js

@@ -6,6 +6,12 @@ import { MySqlNativeQueryBuilder } from './MySqlNativeQueryBuilder.js';
 export class BaseMySqlPlatform extends AbstractSqlPlatform {
     schemaHelper = new MySqlSchemaHelper(this);
     exceptionConverter = new MySqlExceptionConverter();
+    #jsonTypeCasts = {
+        string: 'text',
+        number: 'double',
+        bigint: 'bigint',
+        boolean: 'unsigned',
+    };
     ORDER_BY_NULLS_TRANSLATE = {
         [QueryOrder.asc_nulls_first]: 'is not null',
         [QueryOrder.asc_nulls_last]: 'is null',
@@ -114,6 +120,17 @@ export class BaseMySqlPlatform extends AbstractSqlPlatform {
         ret.push(`${col} ${dir.replace(/(\s|nulls|first|last)*/gi, '')}`);
         return ret;
     }
+    getJsonArrayFromSQL(column, alias, properties) {
+        const columns = properties
+            .map(p => `${this.quoteIdentifier(p.name)} ${this.#jsonTypeCasts[p.type] ?? 'text'} path '$.${this.quoteJsonKey(p.name)}'`)
+            .join(', ');
+        return `json_table(${column}, '$[*]' columns (${columns})) as ${this.quoteIdentifier(alias)}`;
+    }
+    // MySQL does not support correlated json_table inside EXISTS subqueries,
+    // so we use a semi-join via the comma-join pattern instead.
+    getJsonArrayExistsSQL(from, where) {
+        return `(select 1 from ${from} where ${where} limit 1) is not null`;
+    }
     getDefaultClientUrl() {
         return 'mysql://root@127.0.0.1:3306';
     }

package/dialects/postgresql/BasePostgreSqlPlatform.d.ts

@@ -5,6 +5,7 @@ import { PostgreSqlNativeQueryBuilder } from './PostgreSqlNativeQueryBuilder.js'
 import { PostgreSqlSchemaHelper } from './PostgreSqlSchemaHelper.js';
 import { PostgreSqlExceptionConverter } from './PostgreSqlExceptionConverter.js';
 export declare class BasePostgreSqlPlatform extends AbstractSqlPlatform {
+    #private;
     protected readonly schemaHelper: PostgreSqlSchemaHelper;
     protected readonly exceptionConverter: PostgreSqlExceptionConverter;
     createNativeQueryBuilder(): PostgreSqlNativeQueryBuilder;
@@ -102,5 +103,10 @@ export declare class BasePostgreSqlPlatform extends AbstractSqlPlatform {
     castColumn(prop?: {
         columnTypes?: string[];
     }): string;
+    getJsonArrayFromSQL(column: string, alias: string, _properties: {
+        name: string;
+        type: string;
+    }[]): string;
+    getJsonArrayElementPropertySQL(alias: string, property: string, type: string): string;
     getDefaultClientUrl(): string;
 }

package/dialects/postgresql/BasePostgreSqlPlatform.js

@@ -7,6 +7,8 @@ import { FullTextType } from './FullTextType.js';
 export class BasePostgreSqlPlatform extends AbstractSqlPlatform {
     schemaHelper = new PostgreSqlSchemaHelper(this);
     exceptionConverter = new PostgreSqlExceptionConverter();
+    /** Maps JS runtime type names to PostgreSQL cast types for JSON property access. @internal */
+    #jsonTypeCasts = { number: 'float8', bigint: 'int8', boolean: 'bool' };
     createNativeQueryBuilder() {
         return new PostgreSqlNativeQueryBuilder(this);
     }
@@ -215,12 +217,7 @@ export class BasePostgreSqlPlatform extends AbstractSqlPlatform {
         const last = path.pop();
         const root = this.quoteIdentifier(aliased ? `${ALIAS_REPLACEMENT}.${first}` : first);
         type = typeof type === 'string' ? this.getMappedType(type).runtimeType : String(type);
-        const types = {
-            number: 'float8',
-            bigint: 'int8',
-            boolean: 'bool',
-        };
-        const cast = (key) => raw(type in types ? `(${key})::${types[type]}` : key);
+        const cast = (key) => raw(type in this.#jsonTypeCasts ? `(${key})::${this.#jsonTypeCasts[type]}` : key);
         let lastOperator = '->>';
         // force `->` for operator payloads with array values
         if (Utils.isPlainObject(value) &&
@@ -352,6 +349,13 @@ export class BasePostgreSqlPlatform extends AbstractSqlPlatform {
                 return '';
         }
     }
+    getJsonArrayFromSQL(column, alias, _properties) {
+        return `jsonb_array_elements(${column}) as ${this.quoteIdentifier(alias)}`;
+    }
+    getJsonArrayElementPropertySQL(alias, property, type) {
+        const expr = `${this.quoteIdentifier(alias)}->>${this.quoteValue(property)}`;
+        return type in this.#jsonTypeCasts ? `(${expr})::${this.#jsonTypeCasts[type]}` : expr;
+    }
     getDefaultClientUrl() {
         return 'postgresql://postgres@127.0.0.1:5432';
     }

package/dialects/sqlite/SqlitePlatform.d.ts

@@ -75,5 +75,6 @@ export declare class SqlitePlatform extends AbstractSqlPlatform {
     convertVersionValue(value: Date | number, prop: EntityProperty): number | {
         $in: (string | number)[];
     };
+    getJsonArrayElementPropertySQL(alias: string, property: string, _type: string): string;
     quoteValue(value: any): string;
 }

package/dialects/sqlite/SqlitePlatform.js

@@ -133,6 +133,9 @@ export class SqlitePlatform extends AbstractSqlPlatform {
         }
         return value;
     }
+    getJsonArrayElementPropertySQL(alias, property, _type) {
+        return `json_extract(${this.quoteIdentifier(alias)}.value, '$.${this.quoteJsonKey(property)}')`;
+    }
     quoteValue(value) {
         if (value instanceof Date) {
             return '' + +value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/sql",
-  "version": "7.0.0-dev.335",
+  "version": "7.0.0-dev.337",
   "description": "TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, PostgreSQL and SQLite databases as well as usage with vanilla JavaScript.",
   "keywords": [
     "data-mapper",
@@ -53,7 +53,7 @@
     "@mikro-orm/core": "^6.6.9"
   },
   "peerDependencies": {
-    "@mikro-orm/core": "7.0.0-dev.335"
+    "@mikro-orm/core": "7.0.0-dev.337"
   },
   "engines": {
     "node": ">= 22.17.0"

package/query/CriteriaNodeFactory.js

@@ -2,6 +2,7 @@ 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
  */
@@ -69,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) {

package/query/QueryBuilderHelper.d.ts

@@ -56,6 +56,17 @@ export declare class QueryBuilderHelper {
     private fieldName;
     getProperty(field: string, alias?: string): EntityProperty | undefined;
     isTableNameAliasRequired(type: QueryType): boolean;
+    private processEmbeddedArrayCondition;
+    private buildJsonArrayExists;
+    private resolveEmbeddedProp;
+    private buildEmbeddedArrayOperatorCondition;
+    private processJsonElemMatch;
+    /**
+     * Shared logic for building WHERE conditions inside JSON array EXISTS subqueries.
+     * Used by both embedded array queries (metadata-driven) and $elemMatch (type-inferred).
+     */
+    private buildArrayElementWhere;
+    private inferJsonValueType;
     processOnConflictCondition(cond: FilterQuery<any>, schema?: string): FilterQuery<any>;
     createFormulaTable(alias: string, meta: EntityMetadata, schema?: string): FormulaTable;
 }

package/query/QueryBuilderHelper.js

@@ -1,5 +1,5 @@
-import { ALIAS_REPLACEMENT, ALIAS_REPLACEMENT_RE, ArrayType, inspect, isRaw, LockMode, OptimisticLockError, QueryOperator, QueryOrderNumeric, raw, Raw, QueryHelper, ReferenceKind, Utils, ValidationError, } from '@mikro-orm/core';
-import { JoinType, QueryType } from './enums.js';
+import { ALIAS_REPLACEMENT, ALIAS_REPLACEMENT_RE, ArrayType, JsonType, inspect, isRaw, LockMode, OptimisticLockError, QueryOperator, QueryOrderNumeric, raw, Raw, QueryHelper, ReferenceKind, Utils, ValidationError, } from '@mikro-orm/core';
+import { EMBEDDABLE_ARRAY_OPS, JoinType, QueryType } from './enums.js';
 /**
  * @internal
  */
@@ -12,6 +12,8 @@ export class QueryBuilderHelper {
     #subQueries;
     #driver;
     #tptAliasMap;
+    /** Monotonically increasing counter for unique JSON array iteration aliases within a single query. */
+    #jsonAliasCounter = 0;
     constructor(entityName, alias, aliasMap, subQueries, driver, tptAliasMap = {}) {
         this.#entityName = entityName;
         this.#alias = alias;
@@ -436,6 +438,26 @@ export class QueryBuilderHelper {
             params.push(this.getRegExpParam(cond[key]));
             return { sql: parts.join(' and '), params };
         }
+        if (Utils.isPlainObject(cond[key]) && !Raw.isKnownFragmentSymbol(key)) {
+            const [a, f] = this.splitField(key);
+            const prop = this.getProperty(f, a);
+            if (prop?.kind === ReferenceKind.EMBEDDED && prop.array) {
+                const keys = Object.keys(cond[key]);
+                const hasOnlyArrayOps = keys.every((k) => EMBEDDABLE_ARRAY_OPS.includes(k));
+                if (!hasOnlyArrayOps) {
+                    return this.processEmbeddedArrayCondition(cond[key], prop, a);
+                }
+            }
+            // $elemMatch on JSON properties — iterate array elements via EXISTS subquery.
+            // When combined with other operators (e.g. $contains), processObjectSubCondition
+            // splits them first (size > 1), so $elemMatch arrives here alone.
+            if (prop && cond[key].$elemMatch != null && Utils.getObjectKeysSize(cond[key]) === 1) {
+                if (!(prop.customType instanceof JsonType)) {
+                    throw new ValidationError(`$elemMatch can only be used on JSON array properties, but '${this.#entityName}.${prop.name}' has type '${prop.type}'`);
+                }
+                return this.processJsonElemMatch(cond[key].$elemMatch, prop, a);
+            }
+        }
         if (Utils.isPlainObject(cond[key]) || cond[key] instanceof RegExp) {
             return this.processObjectSubCondition(cond, key, type);
         }
@@ -827,6 +849,196 @@ export class QueryBuilderHelper {
     isTableNameAliasRequired(type) {
         return [QueryType.SELECT, QueryType.COUNT].includes(type);
     }
+    processEmbeddedArrayCondition(cond, prop, alias) {
+        const column = this.#platform.quoteIdentifier(`${alias}.${prop.fieldNames[0]}`);
+        const resolveProperty = (key) => {
+            const { embProp, jsonPropName } = this.resolveEmbeddedProp(prop, key);
+            return { name: jsonPropName, type: embProp.runtimeType ?? 'string' };
+        };
+        const invalidObjectError = (key) => ValidationError.invalidEmbeddableQuery(this.#entityName, key, prop.type);
+        const parts = [];
+        const allParams = [];
+        // Top-level $not generates NOT EXISTS (no element matches the inner condition).
+        const { $not, ...rest } = cond;
+        if (Utils.hasObjectKeys(rest)) {
+            const result = this.buildJsonArrayExists(rest, column, false, resolveProperty, invalidObjectError);
+            if (result) {
+                parts.push(result.sql);
+                allParams.push(...result.params);
+            }
+        }
+        if ($not != null) {
+            if (!Utils.isPlainObject($not)) {
+                throw new ValidationError(`Invalid query: $not in embedded array queries expects an object value`);
+            }
+            const result = this.buildJsonArrayExists($not, column, true, resolveProperty, invalidObjectError);
+            if (result) {
+                parts.push(result.sql);
+                allParams.push(...result.params);
+            }
+        }
+        if (parts.length === 0) {
+            return { sql: '1 = 1', params: [] };
+        }
+        return { sql: parts.join(' and '), params: allParams };
+    }
+    buildJsonArrayExists(cond, column, negate, resolveProperty, invalidObjectError) {
+        const jeAlias = `__je${this.#jsonAliasCounter++}`;
+        const referencedProps = new Map();
+        const { sql: whereSql, params } = this.buildArrayElementWhere(cond, jeAlias, referencedProps, resolveProperty, invalidObjectError);
+        if (!whereSql) {
+            return null;
+        }
+        const from = this.#platform.getJsonArrayFromSQL(column, jeAlias, [...referencedProps.values()]);
+        const exists = this.#platform.getJsonArrayExistsSQL(from, whereSql);
+        return { sql: negate ? `not ${exists}` : exists, params };
+    }
+    resolveEmbeddedProp(prop, key) {
+        const embProp = prop.embeddedProps[key] ?? Object.values(prop.embeddedProps).find(p => p.name === key);
+        if (!embProp) {
+            throw ValidationError.invalidEmbeddableQuery(this.#entityName, key, prop.type);
+        }
+        const prefix = `${prop.fieldNames[0]}~`;
+        const raw = embProp.fieldNames[0];
+        const jsonPropName = raw.startsWith(prefix) ? raw.slice(prefix.length) : raw;
+        return { embProp, jsonPropName };
+    }
+    buildEmbeddedArrayOperatorCondition(lhs, value, params) {
+        const supported = new Set(['$eq', '$ne', '$gt', '$gte', '$lt', '$lte', '$in', '$nin', '$not', '$like', '$exists']);
+        const parts = [];
+        // Clone to avoid getOperatorReplacement mutating the original (it sets value[op] = null for $exists).
+        value = { ...value };
+        for (const op of Object.keys(value)) {
+            if (!supported.has(op)) {
+                throw new ValidationError(`Operator ${op} is not supported in embedded array queries`);
+            }
+            const replacement = this.getOperatorReplacement(op, value);
+            const val = value[op];
+            if (['$in', '$nin'].includes(op)) {
+                if (!Array.isArray(val)) {
+                    throw new ValidationError(`Invalid query: ${op} operator expects an array value`);
+                }
+                else if (val.length === 0) {
+                    parts.push(`1 = ${op === '$in' ? 0 : 1}`);
+                }
+                else {
+                    val.forEach((v) => params.push(v));
+                    parts.push(`${lhs} ${replacement} (${val.map(() => '?').join(', ')})`);
+                }
+            }
+            else if (op === '$exists') {
+                parts.push(`${lhs} ${replacement} null`);
+            }
+            else if (val === null) {
+                parts.push(`${lhs} ${replacement} null`);
+            }
+            else {
+                parts.push(`${lhs} ${replacement} ?`);
+                params.push(val);
+            }
+        }
+        return parts.join(' and ');
+    }
+    processJsonElemMatch(cond, prop, alias) {
+        const column = this.#platform.quoteIdentifier(`${alias}.${prop.fieldNames[0]}`);
+        const result = this.buildJsonArrayExists(cond, column, false, (key, value) => {
+            this.#platform.validateJsonPropertyName(key);
+            return { name: key, type: this.inferJsonValueType(value) };
+        }, () => ValidationError.invalidQueryCondition(cond));
+        return result ?? { sql: '1 = 1', params: [] };
+    }
+    /**
+     * Shared logic for building WHERE conditions inside JSON array EXISTS subqueries.
+     * Used by both embedded array queries (metadata-driven) and $elemMatch (type-inferred).
+     */
+    buildArrayElementWhere(cond, jeAlias, referencedProps, resolveProperty, invalidObjectError) {
+        const parts = [];
+        const params = [];
+        for (const k of Object.keys(cond)) {
+            if (k === '$and' || k === '$or') {
+                const items = cond[k];
+                if (items.length === 0) {
+                    continue;
+                }
+                const subParts = [];
+                for (const item of items) {
+                    const sub = this.buildArrayElementWhere(item, jeAlias, referencedProps, resolveProperty, invalidObjectError);
+                    if (sub.sql) {
+                        subParts.push(sub.sql);
+                        params.push(...sub.params);
+                    }
+                }
+                if (subParts.length > 0) {
+                    const joiner = k === '$or' ? ' or ' : ' and ';
+                    parts.push(`(${subParts.join(joiner)})`);
+                }
+                continue;
+            }
+            // Within $or/$and scope, $not provides element-level negation:
+            // "this element does not match the condition".
+            if (k === '$not') {
+                const sub = this.buildArrayElementWhere(cond[k], jeAlias, referencedProps, resolveProperty, invalidObjectError);
+                if (sub.sql) {
+                    parts.push(`not (${sub.sql})`);
+                    params.push(...sub.params);
+                }
+                continue;
+            }
+            const value = cond[k];
+            const { name, type } = resolveProperty(k, value);
+            referencedProps.set(k, { name, type });
+            const lhs = this.#platform.getJsonArrayElementPropertySQL(jeAlias, name, type);
+            if (Utils.isPlainObject(value)) {
+                const valueKeys = Object.keys(value);
+                if (valueKeys.some(vk => !Utils.isOperator(vk))) {
+                    throw invalidObjectError(k);
+                }
+                const sub = this.buildEmbeddedArrayOperatorCondition(lhs, value, params);
+                parts.push(sub);
+            }
+            else if (value === null) {
+                parts.push(`${lhs} is null`);
+            }
+            else {
+                parts.push(`${lhs} = ?`);
+                params.push(value);
+            }
+        }
+        return { sql: parts.join(' and '), params };
+    }
+    inferJsonValueType(value) {
+        if (typeof value === 'number') {
+            return 'number';
+        }
+        if (typeof value === 'boolean') {
+            return 'boolean';
+        }
+        if (typeof value === 'bigint') {
+            return 'bigint';
+        }
+        if (Utils.isPlainObject(value)) {
+            for (const v of Object.values(value)) {
+                if (typeof v === 'number') {
+                    return 'number';
+                }
+                if (typeof v === 'boolean') {
+                    return 'boolean';
+                }
+                if (typeof v === 'bigint') {
+                    return 'bigint';
+                }
+                if (Array.isArray(v) && v.length > 0) {
+                    if (typeof v[0] === 'number') {
+                        return 'number';
+                    }
+                    if (typeof v[0] === 'boolean') {
+                        return 'boolean';
+                    }
+                }
+            }
+        }
+        return 'string';
+    }
     processOnConflictCondition(cond, schema) {
         const meta = this.#metadata.get(this.#entityName);
         const tableName = meta.tableName;

package/query/enums.d.ts

@@ -7,6 +7,8 @@ export declare enum QueryType {
     DELETE = "DELETE",
     UPSERT = "UPSERT"
 }
+/** Operators that apply to the embedded array column itself, not to individual elements. */
+export declare const EMBEDDABLE_ARRAY_OPS: string[];
 export declare enum JoinType {
     leftJoin = "left join",
     innerJoin = "inner join",

package/query/enums.js

@@ -8,6 +8,8 @@ export var QueryType;
     QueryType["DELETE"] = "DELETE";
     QueryType["UPSERT"] = "UPSERT";
 })(QueryType || (QueryType = {}));
+/** Operators that apply to the embedded array column itself, not to individual elements. */
+export const EMBEDDABLE_ARRAY_OPS = ['$contains', '$contained', '$overlap'];
 export var JoinType;
 (function (JoinType) {
     JoinType["leftJoin"] = "left join";