uql-orm 0.19.0 → 0.20.1

package/dist/dialect/abstractSqlDialect.js

@@ -1,10 +1,12 @@
 import { getMeta } from '../entity/index.js';
-import { resolveVectorCast } from '../schema/canonicalType.js';
 import { QueryRaw, RAW_ALIAS, RAW_VALUE, } from '../type/index.js';
-import { applyFilters, asSelectMap, buildQueryWhereAsMap, buildSortMap, escapeSqlId, fillOnFields, filterFieldKeys, flatObject, getFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, hasMultipleKeys, isJsonType, isPopulatingRelations, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationAtKey, raw, withoutSoftDeleteFilter, } from '../util/index.js';
-import { AbstractDialect } from './abstractDialect.js';
+import { escapeAnsiSqlLiteral, escapeSingleQuotes } from '../util/ansiSqlLiteral.js';
+import { applyFilters, asSelectMap, buildQueryWhereAsMap, buildSortMap, escapeSqlId, fillOnFields, filterFieldKeys, flatObject, getFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, hasMultipleKeys, isJsonType, isJsonUpdateOp, isOperatorObject, isOperatorOnlyObject, isPopulatingRelations, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationAtKey, raw, someValue, withoutSoftDeleteFilter, } from '../util/index.js';
+import { buildElemMatchConditions } from './jsonArrayElemMatchUtils.js';
+import { JSON_ELEM_ALIAS_PREFIX, jsonElemExists } from './jsonSql.js';
 import { SqlQueryContext } from './queryContext.js';
-export class AbstractSqlDialect extends AbstractDialect {
+import { VectorSqlDialect } from './vectorSqlDialect.js';
+export class AbstractSqlDialect extends VectorSqlDialect {
     isolationLevelStrategy = 'inline';
     alterColumnStrategy = 'single-statement';
     alterColumnSyntax = 'ALTER COLUMN';
@@ -17,9 +19,6 @@ export class AbstractSqlDialect extends AbstractDialect {
      * `insertMany` splits larger batches into multiple statements based on this limit.
      */
     maxBindValues = 32766;
-    /** Vector index operator classes, keyed by distance metric. Partial: not every dialect supports every metric. */
-    vectorOpsClass = undefined;
-    vectorExtension = undefined;
     getBeginTransactionStatements(isolationLevel) {
         const level = isolationLevel?.toUpperCase();
         const strategy = this.isolationLevelStrategy;
@@ -35,6 +34,19 @@ export class AbstractSqlDialect extends AbstractDialect {
     createContext() {
         return new SqlQueryContext(this);
     }
+    /**
+     * Builds SQL text in isolation via `build`, so the caller can embed it inline (e.g.
+     * `"col" = <text>`) instead of appending it at the end of `ctx`. The fragment binds any value
+     * straight into `ctx`'s own values array - shared by reference, not copied - so `addValue` numbers
+     * its placeholder correctly against the real query from the start; a fresh, empty array would
+     * instead number from `1` regardless of how many values `ctx` already has, misnumbering every
+     * bound value on `$n`-placeholder dialects once `ctx` isn't otherwise empty.
+     */
+    buildFragment(ctx, build) {
+        const fragmentCtx = new SqlQueryContext(this, ctx.values);
+        build(fragmentCtx);
+        return fragmentCtx.sql;
+    }
     addValue(values, value) {
         values.push(this.normalizeValue(value));
         return this.placeholder(values.length);
@@ -195,10 +207,11 @@ export class AbstractSqlDialect extends AbstractDialect {
                 ctx.append(`${joinAlias}.${this.escapeId(foreignColumnName)} = ${relPath}.${this.escapeId(localColumnName)}`);
                 refAppended = true;
             }
-            if (relQuery.$where) {
-                ctx.append(' AND ');
-                this.where(ctx, relEntity, relQuery.$where, { prefix: joinRelAlias, clause: false });
-            }
+            // Unconditional, not gated by `relQuery.$where`: a joined relation's own filters (in
+            // particular `security: true` ones) must apply even to a bare `$populate: { rel: true }`
+            // with no explicit `$where`. `where()` -> `renderWhere()` no-ops cleanly (appends nothing)
+            // when there is truly nothing to add, so this is a pure superset of the old behavior.
+            this.where(ctx, relEntity, relQuery.$where ?? {}, { prefix: joinRelAlias, clause: 'AND' });
             this.selectRelationJoins(ctx, relEntity, relQuery.$select, relQuery.$populate, { prefix: joinRelAlias });
         });
     }
@@ -389,6 +402,17 @@ export class AbstractSqlDialect extends AbstractDialect {
         ['$like', (v) => v],
         ['$ilike', (v) => v.toLowerCase()],
     ]);
+    /**
+     * The case-insensitive `LIKE_OP_MAP` keys - the value is lowercased, so the comparison must use
+     * `ilikeExpr` (Postgres's `ILIKE`) rather than `LIKE`. `$includes` is deliberately excluded even
+     * though it starts with the substring `$i`: it is case-sensitive, unlike `$iincludes`.
+     */
+    static LIKE_CASE_INSENSITIVE_OPS = new Set([
+        '$istartsWith',
+        '$iendsWith',
+        '$iincludes',
+        '$ilike',
+    ]);
     /** Builds `prefix.column` from an already-resolved field. */
     columnWithPrefix(key, field, prefix) {
         const columnName = this.resolveColumnName(key, field);
@@ -402,11 +426,8 @@ export class AbstractSqlDialect extends AbstractDialect {
     resolveOperandField(ctx, entity, key, opts) {
         const col = getMeta(entity).fields[key];
         if (col?.virtual) {
-            if (col.virtual instanceof QueryRaw) {
-                this.getComparisonKey(ctx, entity, key, opts);
-                return undefined;
-            }
-            return `(${col.virtual})`;
+            this.getComparisonKey(ctx, entity, key, opts);
+            return undefined;
         }
         return this.columnWithPrefix(key, col, opts.prefix);
     }
@@ -467,7 +488,7 @@ export class AbstractSqlDialect extends AbstractDialect {
         }
     }
     appendLikeOp(ctx, field, op, wrappedVal) {
-        const isIlike = op.startsWith('$i') || op === '$ilike';
+        const isIlike = AbstractSqlDialect.LIKE_CASE_INSENSITIVE_OPS.has(op);
         const ph = this.addValue(ctx.values, wrappedVal);
         if (isIlike && field) {
             ctx.append(this.ilikeExpr(field, ph));
@@ -501,15 +522,17 @@ export class AbstractSqlDialect extends AbstractDialect {
      * Used by both `$elemMatch` and dot-notation paths.
      * All dialect-specific behavior comes from overridable methods on `this`.
      */
-    buildJsonFieldCondition(ctx, fieldAccessor, jsonPath, op, value) {
+    buildJsonFieldCondition(ctx, fieldAccessor, jsonPath, op, value, asJson = false) {
         const jsonField = fieldAccessor(jsonPath);
         switch (op) {
             case '$eq':
-                return value === null ? `${jsonField} IS NULL` : `${jsonField} = ${this.addValue(ctx.values, value)}`;
+                if (value === null)
+                    return `${jsonField} IS NULL`;
+                return `${this.jsonComparand(jsonField, value)} = ${this.jsonOperand(ctx, value, asJson)}`;
             case '$ne':
                 if (value === null)
                     return `${jsonField} IS NOT NULL`;
-                return this.neExpr(jsonField, this.addValue(ctx.values, value));
+                return this.neExpr(this.jsonComparand(jsonField, value), this.jsonOperand(ctx, value, asJson));
             case '$gt':
                 return `${this.numericCast(jsonField)} > ${this.addValue(ctx.values, value)}`;
             case '$gte':
@@ -538,7 +561,7 @@ export class AbstractSqlDialect extends AbstractDialect {
                 return `${jsonField} ${this.regexpOp} ${this.addValue(ctx.values, value)}`;
             case '$in':
             case '$nin':
-                return this.jsonInNin(ctx, jsonField, op, value);
+                return this.jsonInNin(ctx, jsonField, op, value, asJson);
             case '$all':
                 return this.jsonAll(ctx, jsonField, value);
             case '$size':
@@ -549,20 +572,122 @@ export class AbstractSqlDialect extends AbstractDialect {
                 throw TypeError(`unknown operator: ${op}`);
         }
     }
-    jsonInNin(ctx, jsonField, op, value) {
-        return `${jsonField}${this.formatIn(ctx, Array.isArray(value) ? value : [], op === '$nin')}`;
+    jsonInNin(ctx, jsonField, op, value, asJson) {
+        const values = Array.isArray(value) ? value : [];
+        const negate = op === '$nin';
+        if (!asJson) {
+            return `${this.jsonComparand(jsonField, values)}${this.formatIn(ctx, values, negate)}`;
+        }
+        // JSON values have no portable array literal, so the set expands into explicit comparisons.
+        const comparisons = values.map((val) => `${jsonField} ${negate ? '<>' : '='} ${this.jsonScalarParam(ctx, val)}`);
+        return `(${comparisons.join(negate ? ' AND ' : ' OR ')})`;
+    }
+    /** The bound operand of a JSON comparison: JSON-encoded when comparing against the JSON value. */
+    jsonOperand(ctx, value, asJson) {
+        return asJson ? this.jsonScalarParam(ctx, value) : this.addValue(ctx.values, value);
     }
-    jsonAll(ctx, jsonField, value) {
-        throw TypeError(`$all is not supported in the base SQL dialect - override in dialect subclass`);
+    /**
+     * The left side of a comparison against a JSON scalar, cast when the operand is numeric - see
+     * {@link jsonCompareMode} for why each mode exists.
+     */
+    jsonComparand(jsonField, value) {
+        return this.jsonCompareMode(value) === 'numeric' ? this.numericCast(jsonField) : jsonField;
     }
-    jsonSize(ctx, jsonField, value) {
-        throw TypeError(`$size is not supported in the base SQL dialect - override in dialect subclass`);
+    /**
+     * How a JSON scalar has to be compared against `value` (or, for `$in`/`$nin`, against every element
+     * of it). Extracting a JSON value yields *text*, which loses the type, so each operand type is
+     * compared in the representation every engine agrees on:
+     * - `numeric` - cast the accessor. Keeps `1` equal to a stored `1.0`, which strict JSON equality
+     *   would not, and satisfies drivers that send typed parameters (`text = integer` otherwise).
+     * - `json` - compare the JSON value against a JSON-encoded parameter. No cast recovers a boolean
+     *   portably: PostgreSQL raises `text = boolean` and MySQL matches `'true'` against `1`.
+     * - `text` - compare as extracted, which is also what the string operators need.
+     *
+     * Mixed operand types fall back to `text`, since one comparison cannot be two shapes at once.
+     */
+    jsonCompareMode(value) {
+        const operands = Array.isArray(value) ? value : [value];
+        if (operands.length === 0) {
+            return 'text';
+        }
+        if (operands.every((operand) => typeof operand === 'boolean')) {
+            return 'json';
+        }
+        return operands.every((operand) => typeof operand === 'number') ? 'numeric' : 'text';
+    }
+    /**
+     * Whether the dialect's array containment ({@link jsonAll}) matches an object element that merely
+     * *includes* the given keys, as PostgreSQL's `@>` and MySQL's `JSON_CONTAINS` do. SQLite compares
+     * elements as whole JSON text, so it cannot express a partial match and always expands the
+     * per-field form below.
+     */
+    jsonContainmentIsPartial = true;
+    /**
+     * Whether an exploded *scalar* element keeps its SQL type. SQLite's `json_each` yields JSON
+     * booleans as `0`/`1` integers and numbers as numbers, so such an element compares directly to a
+     * bound value; PostgreSQL and MySQL explode scalars to text, losing the type, so a non-string
+     * operand there has to compare as JSON (see {@link isJsonbOp}).
+     */
+    jsonScalarElemKeepsType = false;
+    /**
+     * `$elemMatch`: at least one element of the JSON array satisfies `match`. Three shapes, decided
+     * here so every dialect only supplies {@link jsonElemFrom} / {@link jsonElemRef}:
+     * - keys are operators (`{ $startsWith: 'ad' }`) - scalar elements, conditions on the element;
+     * - a plain object with no nested operators - containment, which is the only form an index serves;
+     * - otherwise - per-field conditions over the exploded objects.
+     */
+    jsonElemMatch(ctx, jsonField, match) {
+        // Conditions on the element itself. One `FROM` serves them all, so the element is read as JSON
+        // only when *every* operand needs it - the same all-operands rule the comparison classifier uses.
+        if (isOperatorOnlyObject(match)) {
+            const entries = Object.entries(match);
+            const asJson = !this.jsonScalarElemKeepsType && entries.every(([op, val]) => this.isJsonbOp(op, val));
+            const alias = ctx.nextAlias(JSON_ELEM_ALIAS_PREFIX);
+            const conditions = entries.map(([op, val]) => this.buildJsonFieldCondition(ctx, () => this.jsonElemRef(alias, undefined, asJson), '', op, val, asJson));
+            return jsonElemExists(this.jsonElemFrom(jsonField, [], alias, asJson), conditions);
+        }
+        if (isOperatorObject(match)) {
+            throw TypeError(`$elemMatch cannot mix operators with field names: ${Object.keys(match).join(', ')}`);
+        }
+        // A plain object with no nested operators is containment, which is also the only form an index
+        // can serve. SQLite compares elements exactly, so it always expands the per-field form below.
+        if (this.jsonContainmentIsPartial && !someValue(match, isOperatorObject)) {
+            return this.jsonAll(ctx, jsonField, [match]);
+        }
+        const alias = ctx.nextAlias(JSON_ELEM_ALIAS_PREFIX);
+        const conditions = buildElemMatchConditions(match, (field, op, opVal) => {
+            const asJson = this.isJsonbOp(op, opVal);
+            return this.buildJsonFieldCondition(ctx, (f) => this.jsonElemRef(alias, f, asJson), field, op, opVal, asJson);
+        });
+        return jsonElemExists(this.jsonElemFrom(jsonField, Object.keys(match), alias), conditions);
     }
-    jsonElemMatch(ctx, jsonField, value) {
-        throw TypeError(`$elemMatch is not supported in the base SQL dialect - override in dialect subclass`);
+    /**
+     * Whether the operator reads the JSON *value* instead of its text form. The array operators always
+     * do. Equality joins them for boolean operands, because extracting JSON as text loses the type in
+     * a way no cast recovers portably: PostgreSQL raises `operator does not exist: text = boolean`,
+     * MySQL compares `'true'` to `1` and silently matches nothing, and SQLite's `json_extract` yields
+     * `1`. Comparing the JSON value against a JSON-encoded parameter is exact on every dialect.
+     *
+     * Numbers stay on the text accessor with a numeric cast ({@link jsonComparand}), which keeps
+     * `1` equal to `1.0` - JSON equality would not.
+     */
+    isJsonbOp(op, value) {
+        if (op === '$all' || op === '$size' || op === '$elemMatch') {
+            return true;
+        }
+        const comparesValue = op === '$eq' || op === '$ne' || op === '$in' || op === '$nin';
+        return comparesValue && this.jsonCompareMode(value) === 'json';
     }
-    isJsonbOp(op) {
-        return op === '$all' || op === '$size' || op === '$elemMatch';
+    /**
+     * A JSON-encoded bound parameter, cast to the dialect's JSON type. Only the positional-placeholder
+     * dialects use this - PostgreSQL binds JSON through {@link PgLikeSqlDialect.jsonScalarParam} instead.
+     */
+    jsonScalarParam(ctx, value) {
+        if (value instanceof QueryRaw) {
+            return this.addValue(ctx.values, value);
+        }
+        ctx.pushValue(JSON.stringify(value));
+        return this.jsonCast('?');
     }
     getComparisonKey(ctx, entity, key, { prefix } = {}) {
         const meta = getMeta(entity);
@@ -629,59 +754,6 @@ export class AbstractSqlDialect extends AbstractDialect {
             ctx.append(this.escapeId(name) + direction);
         });
     }
-    /**
-     * Resolve common parameters for a vector similarity ORDER BY expression.
-     * Shared by all dialect overrides of `appendVectorSort`.
-     */
-    resolveVectorSortParams(meta, key, search) {
-        const field = meta.fields[key];
-        const colName = this.resolveColumnName(key, field);
-        const distance = search.$distance ?? field?.distance ?? 'cosine';
-        const vectorCast = resolveVectorCast(field);
-        return { colName, distance, field, vectorCast };
-    }
-    /**
-     * Mapping of UQL vector distance metrics to native SQL functions.
-     * Override in dialects that use function-call syntax (e.g. SQLite, MariaDB).
-     * Dialects with operator-based syntax (e.g. Postgres) leave this empty and override `appendVectorSort` directly.
-     */
-    vectorDistanceFns = new Map();
-    /**
-     * Append a vector similarity function call: `fn(col, ?)`.
-     * Used by dialects that express vector distance via SQL functions (SQLite, MariaDB).
-     */
-    appendFunctionVectorSort(ctx, meta, key, search, dialectName) {
-        const { colName, distance, vectorCast } = this.resolveVectorSortParams(meta, key, search);
-        const fn = this.vectorDistanceFns.get(distance);
-        if (!fn) {
-            throw Error(`${dialectName} does not support vector distance metric: ${distance}`);
-        }
-        ctx.append(`${fn}(${this.escapeId(colName)}, `);
-        ctx.addValue(`[${search.$vector.join(',')}]`);
-        if (vectorCast && dialectName === 'PostgreSQL') {
-            ctx.append(`::${vectorCast}`);
-        }
-        ctx.append(')');
-    }
-    /**
-     * Append a vector distance projection.
-     */
-    appendVectorProjection(ctx, meta, key, search) {
-        this.appendVectorSort(ctx, meta, key, search);
-        ctx.append(` AS ${this.escapeId(search.$project)}`);
-    }
-    /**
-     * Append a vector similarity ORDER BY expression.
-     * Default: auto-delegates to `appendFunctionVectorSort` when `vectorDistanceFns` has entries.
-     * Override for operator-based syntax (e.g. PostgreSQL `<=>`, `<->` operators).
-     */
-    appendVectorSort(ctx, meta, key, search) {
-        if (this.vectorDistanceFns.size > 0) {
-            this.appendFunctionVectorSort(ctx, meta, key, search, this.dialectName);
-            return;
-        }
-        throw new TypeError('Vector similarity sort is not supported by this dialect. Use raw() for vector queries.');
-    }
     pager(ctx, opts) {
         if (opts.$limit) {
             ctx.append(` LIMIT ${Number(opts.$limit)}`);
@@ -891,8 +963,8 @@ export class AbstractSqlDialect extends AbstractDialect {
             const columnName = this.resolveColumnName(key, field);
             const escapedCol = this.escapeId(columnName);
             const value = filledPayload[key];
-            if (this.isJsonUpdateOp(value)) {
-                this.formatJsonUpdate(ctx, escapedCol, value);
+            if (isJsonUpdateOp(value)) {
+                this.formatJsonUpdate(ctx, escapedCol, value, field);
             }
             else {
                 ctx.append(`${escapedCol} = `);
@@ -930,28 +1002,11 @@ export class AbstractSqlDialect extends AbstractDialect {
             if (callback && Object.hasOwn(sample, col)) {
                 return `${this.escapeId(columnName)} = ${callback(this.escapeId(columnName))}`;
             }
-            const valCtx = this.createContext();
-            this.formatPersistableValue(valCtx, field, filledPayload[col]);
-            ctx.pushValue(...valCtx.values);
-            return `${this.escapeId(columnName)} = ${valCtx.sql}`;
+            const text = this.buildFragment(ctx, (fragmentCtx) => this.formatPersistableValue(fragmentCtx, field, filledPayload[col]));
+            return `${this.escapeId(columnName)} = ${text}`;
         })
             .join(', ');
     }
-    /**
-     * Shared ON CONFLICT ... DO UPDATE / DO NOTHING ... RETURNING logic for positional-placeholder
-     * dialects (SQLite). Uses a deferred context for update params so they follow INSERT params.
-     * PG uses its own implementation since `$N` numbered placeholders handle param ordering natively.
-     */
-    onConflictUpsert(ctx, entity, conflictPaths, payload, insertFn) {
-        const meta = getMeta(entity);
-        const updateCtx = this.createContext();
-        const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, (name) => `EXCLUDED.${name}`);
-        const keysStr = this.getUpsertConflictPathsStr(meta, conflictPaths);
-        const onConflict = update ? `DO UPDATE SET ${update}` : 'DO NOTHING';
-        insertFn(ctx, entity, payload);
-        ctx.append(` ON CONFLICT (${keysStr}) ${onConflict} ${this.returningId(entity)}`);
-        ctx.pushValue(...updateCtx.values);
-    }
     getUpsertConflictPathsStr(meta, conflictPaths) {
         return getKeys(conflictPaths)
             .map((key) => {
@@ -984,22 +1039,6 @@ export class AbstractSqlDialect extends AbstractDialect {
     escapeId(val, forbidQualified, addDot) {
         return escapeSqlId(val, this.escapeIdChar, forbidQualified, addDot);
     }
-    getPersistables(ctx, meta, payload, callbackKey) {
-        const payloads = fillOnFields(meta, payload, callbackKey);
-        return payloads.map((it) => this.getPersistable(ctx, meta, it, callbackKey));
-    }
-    getPersistable(ctx, meta, payload, callbackKey) {
-        const filledPayload = fillOnFields(meta, payload, callbackKey)[0];
-        const keys = filterFieldKeys(meta, filledPayload, callbackKey);
-        return keys.reduce((acc, key) => {
-            const field = meta.fields[key];
-            const valCtx = this.createContext();
-            this.formatPersistableValue(valCtx, field, filledPayload[key]);
-            ctx.pushValue(...valCtx.values);
-            acc[key] = valCtx.sql;
-            return acc;
-        }, {});
-    }
     formatPersistableValue(ctx, field, value) {
         if (value instanceof QueryRaw) {
             this.getRawValue(ctx, { value });
@@ -1016,50 +1055,52 @@ export class AbstractSqlDialect extends AbstractDialect {
         ctx.addValue(value);
     }
     /**
-     * Generate SQL for a JSONB merge and/or unset operation.
-     * Called from `update()` when a field value has `$merge`, `$unset`, and/or `$push` operators.
-     * Generates the full `"col" = <expression>` assignment.
-     *
-     * Base implementation uses MySQL-compatible syntax with *shallow* merge semantics
-     * (RHS top-level keys replace LHS top-level keys, matching PostgreSQL's `jsonb || jsonb`).
-     * Override in dialect subclasses when a dialect needs different JSON function semantics.
+     * Reads `operand` as a JSON value. Passing the `?` placeholder yields the cast for a bound
+     * parameter, and passing an expression re-reads text as JSON - the same SQL either way, which is
+     * why this is one hook rather than a placeholder variant plus an expression variant.
      */
-    getJsonCastExpr() {
-        return 'CAST(? AS JSON)';
+    jsonCast(operand) {
+        return `CAST(${operand} AS JSON)`;
     }
-    formatJsonUpdate(ctx, escapedCol, value) {
+    /**
+     * Generate the full `"col" = <expression>` assignment for a JSON update operator payload.
+     * Called from `update()` when a field value is a {@link JsonUpdateOp}.
+     *
+     * Each operator wraps the expression built so far, innermost-first in the order stated on
+     * {@link JsonUpdateOp} (`$pull` -> `$set` -> `$push` -> `$unset`), so dialects only supply the
+     * four SQL fragments below. Two invariants keep every dialect consistent and keep bound values in
+     * step with their placeholders:
+     * - `$pull` is innermost and its subquery reads `escapedCol`, so its value binds exactly once.
+     * - Later fragments reference `expr` at most once, so a `$pull` subquery is never duplicated
+     *   (which would bind its value twice on positional-placeholder dialects). PostgreSQL's `$push`
+     *   is the one exception, and is safe there because its placeholders are numbered.
+     */
+    formatJsonUpdate(ctx, escapedCol, value, field) {
+        // Centralizes the one narrowing cast: the payload's keys are typed against the entity's JSON
+        // payload, which the dialects do not need - they only build SQL from keys and values.
+        const { $pull, $set, $push, $unset } = value;
         let expr = escapedCol;
-        if (hasKeys(value.$merge)) {
-            const merge = value.$merge;
-            expr = `JSON_SET(COALESCE(${escapedCol}, '{}')`;
-            for (const [key, v] of Object.entries(merge)) {
-                expr += `, '$.${this.escapeJsonKey(key)}', ${this.getJsonCastExpr()}`;
-                ctx.pushValue(JSON.stringify(v));
-            }
-            expr += ')';
-        }
-        if (hasKeys(value.$push)) {
-            const push = value.$push;
-            expr = `JSON_ARRAY_APPEND(${expr}`;
-            for (const [key, v] of Object.entries(push)) {
-                expr += `, '$.${this.escapeJsonKey(key)}', ${this.getJsonCastExpr()}`;
-                ctx.pushValue(JSON.stringify(v));
-            }
-            expr += ')';
+        if (hasKeys($pull)) {
+            expr = this.jsonPull(ctx, expr, escapedCol, $pull);
         }
-        if (value.$unset?.length) {
-            for (const key of value.$unset) {
-                expr = `JSON_REMOVE(${expr}, '$.${this.escapeJsonKey(key)}')`;
-            }
+        if (hasKeys($set)) {
+            expr = this.jsonSet(ctx, expr, $set, field);
+        }
+        if (hasKeys($push)) {
+            expr = this.jsonPush(ctx, expr, $push);
+        }
+        if ($unset?.length) {
+            expr = this.jsonUnset(ctx, expr, $unset);
         }
         ctx.append(`${escapedCol} = ${expr}`);
     }
-    isJsonUpdateOp(value) {
-        return typeof value === 'object' && value !== null && ('$merge' in value || '$unset' in value || '$push' in value);
-    }
-    /** Escapes a JSON key for safe interpolation into SQL string literals. */
-    escapeJsonKey(key) {
-        return key.replace(/'/g, "''");
+    /**
+     * Remove every element equal to the given value, per array key. Each key wraps the expression
+     * built so far, so dialects only supply {@link jsonPullKey} - and because every key reads
+     * `escapedCol` rather than the accumulated expression, values bind once, in key order.
+     */
+    jsonPull(ctx, expr, escapedCol, pull) {
+        return Object.entries(pull).reduce((acc, [key, value]) => this.jsonPullKey(ctx, acc, escapedCol, key, value), expr);
     }
     getRawValue(ctx, opts) {
         const { value, prefix = '', escapedPrefix, autoPrefixAlias } = opts;
@@ -1105,7 +1146,6 @@ export class AbstractSqlDialect extends AbstractDialect {
         const colName = this.resolveColumnName(root, field);
         const escapedCol = (prefix ? this.escapeId(prefix, true, true) : '') + this.escapeId(colName);
         return {
-            root,
             jsonPath,
             accessor: (asJsonb) => asJsonb ? this.getJsonPathJsonbExpr(escapedCol, jsonPath) : this.getJsonPathScalarExpr(escapedCol, jsonPath),
         };
@@ -1124,7 +1164,8 @@ export class AbstractSqlDialect extends AbstractDialect {
         operators.forEach((op, index) => {
             if (index > 0)
                 ctx.append(' AND ');
-            const sql = this.buildJsonFieldCondition(ctx, (f) => accessor(this.isJsonbOp(op)), jsonPath, op, value[op]);
+            const asJson = this.isJsonbOp(op, value[op]);
+            const sql = this.buildJsonFieldCondition(ctx, () => accessor(asJson), jsonPath, op, value[op], asJson);
             if (sql) {
                 ctx.append(sql);
             }
@@ -1143,7 +1184,7 @@ export class AbstractSqlDialect extends AbstractDialect {
         let expr = escapedColumn;
         for (let i = 0; i < segments.length; i++) {
             const op = i === segments.length - 1 ? '->>' : '->';
-            expr = `(${expr}${op}'${this.escapeJsonKey(segments[i])}')`;
+            expr = `(${expr}${op}'${escapeSingleQuotes(segments[i])}')`;
         }
         return expr;
     }
@@ -1151,7 +1192,7 @@ export class AbstractSqlDialect extends AbstractDialect {
         const segments = jsonPath.split('.');
         let expr = escapedColumn;
         for (const segment of segments) {
-            expr = `(${expr}->'${this.escapeJsonKey(segment)}')`;
+            expr = `(${expr}->'${escapeSingleQuotes(segment)}')`;
         }
         return expr;
     }
@@ -1170,15 +1211,25 @@ export class AbstractSqlDialect extends AbstractDialect {
      * Filter by relation using an EXISTS subquery.
      * Supports all cardinalities: mm (via junction), 1m, m1, and 11.
      */
-    compareRelation(ctx, entity, key, val, rel, opts) {
+    /**
+     * The parent side of a relation-filtering subquery: its table name, escaped id reference, and a
+     * guard against a relation with no configured references. Shared by
+     * `compareRelation`/`compareRelationSize`. `rel.references` is asserted non-null at call sites
+     * relying on this guard, since the check lives here instead of in the caller's own scope.
+     */
+    resolveRelationParent(entity, key, rel, opts) {
         const meta = getMeta(entity);
         const parentTable = this.resolveTableName(entity, meta);
-        const parentId = meta.id;
-        const escapedParentId = (opts.prefix ? this.escapeId(opts.prefix, true, true) : this.escapeId(parentTable, false, true)) +
-            this.escapeId(parentId);
         if (!rel.references?.length) {
             throw new TypeError(`Relation '${key}' on '${parentTable}' has no references defined`);
         }
+        const escapedParentId = (opts.prefix ? this.escapeId(opts.prefix, true, true) : this.escapeId(parentTable, false, true)) +
+            this.escapeId(meta.id);
+        return { parentTable, escapedParentId };
+    }
+    compareRelation(ctx, entity, key, val, rel, opts) {
+        const { parentTable, escapedParentId } = this.resolveRelationParent(entity, key, rel, opts);
+        const references = rel.references;
         const relatedEntity = rel.entity();
         const relatedMeta = getMeta(relatedEntity);
         const relatedTable = this.resolveTableName(relatedEntity, relatedMeta);
@@ -1188,8 +1239,8 @@ export class AbstractSqlDialect extends AbstractDialect {
             const throughEntity = rel.through();
             const throughMeta = getMeta(throughEntity);
             const throughTable = this.resolveTableName(throughEntity, throughMeta);
-            const localFk = rel.references[0].local;
-            const foreignFk = rel.references[1].local;
+            const localFk = references[0].local;
+            const foreignFk = references[1].local;
             const relatedId = relatedMeta.id;
             ctx.append(this.escapeId(throughTable));
             ctx.append(` WHERE ${this.escapeId(throughTable, false, true)}${this.escapeId(localFk)} = ${escapedParentId}`);
@@ -1206,11 +1257,11 @@ export class AbstractSqlDialect extends AbstractDialect {
             // 1m / m1 / 11: EXISTS (SELECT 1 FROM Related WHERE related.fk_or_pk = parent.pk_or_fk AND ...)
             // Left side is always relatedTable.references[0].foreign
             // Right side is the parent's PK (1m) or the parent's FK (m1/11)
-            const joinLeft = `${this.escapeId(relatedTable, false, true)}${this.escapeId(rel.references[0].foreign)}`;
+            const joinLeft = `${this.escapeId(relatedTable, false, true)}${this.escapeId(references[0].foreign)}`;
             const joinRight = rel.cardinality === '1m'
                 ? escapedParentId
                 : (opts.prefix ? this.escapeId(opts.prefix, true, true) : this.escapeId(parentTable, false, true)) +
-                    this.escapeId(rel.references[0].local);
+                    this.escapeId(references[0].local);
             ctx.append(this.escapeId(relatedTable));
             ctx.append(` WHERE ${joinLeft} = ${joinRight}`);
             this.where(ctx, relatedEntity, val, {
@@ -1226,14 +1277,7 @@ export class AbstractSqlDialect extends AbstractDialect {
      * Supports all cardinalities: mm (via junction), 1m.
      */
     compareRelationSize(ctx, entity, key, sizeVal, rel, opts) {
-        const meta = getMeta(entity);
-        const parentTable = this.resolveTableName(entity, meta);
-        const parentId = meta.id;
-        const escapedParentId = (opts.prefix ? this.escapeId(opts.prefix, true, true) : this.escapeId(parentTable, false, true)) +
-            this.escapeId(parentId);
-        if (!rel.references?.length) {
-            throw new TypeError(`Relation '${key}' on '${parentTable}' has no references defined`);
-        }
+        const { escapedParentId } = this.resolveRelationParent(entity, key, rel, opts);
         const appendSubquery = () => {
             ctx.append('(SELECT COUNT(*) FROM ');
             if (rel.cardinality === 'mm' && rel.through) {
@@ -1324,6 +1368,10 @@ export class AbstractSqlDialect extends AbstractDialect {
                 throw TypeError(`unsupported $size comparison operator: ${op}`);
         }
     }
+    /** ANSI-style single-quote escaping. MySQL-family dialects override this for backslash escaping. */
+    escape(value) {
+        return escapeAnsiSqlLiteral(value);
+    }
     get regexpOp() {
         return 'REGEXP';
     }