uql-orm 0.67.1 → 0.68.1

package/dist/migrate/ddl/pgIndexDdl.js

@@ -1,4 +1,3 @@
-import { COCKROACH_VECTOR_METRICS, PG_VECTOR_METRICS } from '../../dialect/pgVectorMetrics.js';
 import { unsupportedVectorMetric } from '../../type/vector.js';
 import { IndexDdl } from './indexDdl.js';
 /** `$text` computes its `TO_TSVECTOR` per row, which no index over the raw columns serves. */
@@ -26,8 +25,6 @@ export class PgIndexDdl extends IndexDdl {
         'include',
         'jsonPath',
     ]);
-    /** The metrics its vector index takes, each naming the operator class it is built with. */
-    vectorMetrics = PG_VECTOR_METRICS;
     /** pgvector's own index types; CockroachDB's native one widens this. */
     isVectorIndex(index) {
         return index.type === 'hnsw' || index.type === 'ivfflat';
@@ -43,12 +40,12 @@ export class PgIndexDdl extends IndexDdl {
         if (!this.isVectorIndex(index) || !index.distance) {
             return entry.opsClass ? ` ${entry.opsClass}` : '';
         }
-        const metric = this.vectorMetrics.get(index.distance);
+        const metric = this.dialect.vectorMetrics.get(index.distance)?.index;
         if (!metric) {
             throw unsupportedVectorMetric(this.dialect.dialectName, index.distance, index.name);
         }
         const vectorType = this.dialect.supportedVectorType(index.vectorType ?? 'vector');
-        const opsClass = `${vectorType}_${metric.opsSuffix}_ops`;
+        const opsClass = `${vectorType}_${metric}_ops`;
         // IVFFlat has neither a sparsevec nor an L1 operator class; HNSW has all of them (pgvector 0.8.2).
         if (index.type === 'ivfflat' && (vectorType === 'sparsevec' || index.distance === 'l1')) {
             throw new TypeError(`ivfflat has no ${opsClass} operator class (index "${index.name}"); use hnsw`);
@@ -83,7 +80,6 @@ export class CockroachIndexDdl extends PgIndexDdl {
         ...PG_INDEX_TYPE_HINTS,
         ['ivfflat', "; declare type: 'vector' instead"],
     ]);
-    vectorMetrics = COCKROACH_VECTOR_METRICS;
     isNativeVectorIndex(index) {
         return index.type === 'vector';
     }

package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts

@@ -12,6 +12,15 @@ import { BaseSqlIntrospector } from './baseSqlIntrospector.js';
  * it is four avoidable ones.
  */
 export type TableRowReader = <T extends RawRow>(sql: string, params?: unknown[]) => Promise<T[]>;
+/** A foreign key as MySQL and SQL Server list one: a row, its column lists comma-joined. */
+export type JoinedForeignKeyRow = {
+    readonly constraint_name: string;
+    readonly columns: string;
+    readonly referenced_table: string;
+    readonly referenced_columns: string;
+    readonly delete_rule: string;
+    readonly update_rule: string;
+};
 /** A SQL introspector: an engine states its catalogue queries (`get*Query`) and how their rows map (`map*Result`). */
 export declare abstract class AbstractSqlSchemaIntrospector extends BaseSqlIntrospector implements SchemaIntrospector {
     protected readonly pool: QuerierPool;
@@ -48,8 +57,10 @@ export declare abstract class AbstractSqlSchemaIntrospector extends BaseSqlIntro
     protected getIndexesParams(tableName: string): unknown[];
     protected getForeignKeysParams(tableName: string): unknown[];
     protected getPrimaryKeyParams(tableName: string): unknown[];
-    /** The {@link ForeignKeyAction} a catalogue names, whatever its case. */
+    /** The {@link ForeignKeyAction} a catalogue names, whatever its case, and `SET_NULL` as SQL Server spells it. */
     protected normalizeReferentialAction(action: string): ForeignKeyAction | undefined;
+    /** Foreign keys read one row each, as {@link JoinedForeignKeyRow} lists them. */
+    protected joinedForeignKeys(rows: readonly JoinedForeignKeyRow[]): ForeignKeySchema[];
     /**
      * Convert bigint/null values to number safely.
      */

package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js

@@ -100,10 +100,20 @@ export class AbstractSqlSchemaIntrospector extends BaseSqlIntrospector {
     getPrimaryKeyParams(tableName) {
         return [tableName];
     }
-    /** The {@link ForeignKeyAction} a catalogue names, whatever its case. */
+    /** The {@link ForeignKeyAction} a catalogue names, whatever its case, and `SET_NULL` as SQL Server spells it. */
     normalizeReferentialAction(action) {
-        const upper = action.toUpperCase();
-        return FOREIGN_KEY_ACTIONS.find((known) => known === upper);
+        const spelled = action.toUpperCase().replaceAll('_', ' ');
+        return FOREIGN_KEY_ACTIONS.find((known) => known === spelled);
+    }
+    /** Foreign keys read one row each, as {@link JoinedForeignKeyRow} lists them. */
+    joinedForeignKeys(rows) {
+        return rows.map((row) => ({
+            name: row.constraint_name,
+            columns: row.columns.split(','),
+            references: { table: row.referenced_table, columns: row.referenced_columns.split(',') },
+            onDelete: this.normalizeReferentialAction(row.delete_rule),
+            onUpdate: this.normalizeReferentialAction(row.update_rule),
+        }));
     }
     /**
      * Convert bigint/null values to number safely.

package/dist/migrate/introspection/mssqlIntrospector.d.ts

@@ -1,5 +1,5 @@
 import type { ColumnSchema, ForeignKeySchema, IndexSchema } from '../../type/index.js';
-import { AbstractSqlSchemaIntrospector, type TableRowReader } from './abstractSqlSchemaIntrospector.js';
+import { AbstractSqlSchemaIntrospector, type JoinedForeignKeyRow, type TableRowReader } from './abstractSqlSchemaIntrospector.js';
 /**
  * SQL Server schema introspector.
  *
@@ -31,14 +31,7 @@ export declare class MsSqlSchemaIntrospector extends AbstractSqlSchemaIntrospect
         columns: string;
         is_unique: boolean;
     }[]): Promise<IndexSchema[]>;
-    protected mapForeignKeysResult(_read: TableRowReader, _tableName: string, results: {
-        constraint_name: string;
-        columns: string;
-        referenced_table: string;
-        referenced_columns: string;
-        delete_rule: string;
-        update_rule: string;
-    }[]): Promise<ForeignKeySchema[]>;
+    protected mapForeignKeysResult(_read: TableRowReader, _tableName: string, results: JoinedForeignKeyRow[]): Promise<ForeignKeySchema[]>;
     /**
      * The engine reprints a default from its own parse tree: all of it in one pair of parentheses, and a
      * number in a second, so `((0))`, `((1)+(2))`, `(N'x')` and `(getdate())`.

package/dist/migrate/introspection/mssqlIntrospector.js

@@ -1,4 +1,4 @@
-import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.js';
+import { AbstractSqlSchemaIntrospector, } from './abstractSqlSchemaIntrospector.js';
 /**
  * SQL Server schema introspector.
  *
@@ -146,14 +146,7 @@ export class MsSqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         }));
     }
     async mapForeignKeysResult(_read, _tableName, results) {
-        return results.map((row) => ({
-            name: row.constraint_name,
-            columns: row.columns.split(','),
-            references: { table: row.referenced_table, columns: row.referenced_columns.split(',') },
-            // `sys` spells them with an underscore: `SET_NULL`, `NO_ACTION`.
-            onDelete: this.normalizeReferentialAction(row.delete_rule.replaceAll('_', ' ')),
-            onUpdate: this.normalizeReferentialAction(row.update_rule.replaceAll('_', ' ')),
-        }));
+        return this.joinedForeignKeys(results);
     }
     /**
      * The engine reprints a default from its own parse tree: all of it in one pair of parentheses, and a

package/dist/migrate/introspection/mysqlIntrospector.d.ts

@@ -1,5 +1,5 @@
 import type { ColumnSchema, ForeignKeySchema, IndexSchema } from '../../type/index.js';
-import { AbstractSqlSchemaIntrospector, type TableRowReader } from './abstractSqlSchemaIntrospector.js';
+import { AbstractSqlSchemaIntrospector, type JoinedForeignKeyRow, type TableRowReader } from './abstractSqlSchemaIntrospector.js';
 /**
  * MySQL/MariaDB schema introspector.
  * Works with both MySQL and MariaDB as they share the same information_schema structure.
@@ -21,14 +21,7 @@ export declare class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospect
         columns: string;
         is_unique: number;
     }[]): Promise<IndexSchema[]>;
-    protected mapForeignKeysResult(_read: TableRowReader, _tableName: string, results: {
-        constraint_name: string;
-        columns: string;
-        referenced_table: string;
-        referenced_columns: string;
-        delete_rule: string;
-        update_rule: string;
-    }[]): Promise<ForeignKeySchema[]>;
+    protected mapForeignKeysResult(_read: TableRowReader, _tableName: string, results: JoinedForeignKeyRow[]): Promise<ForeignKeySchema[]>;
     /**
      * MariaDB prints a string default as the literal it is (`'it''s'`). MySQL prints one bare, save an
      * expression default (`DEFAULT ('x')`, what a `TEXT` column takes), which comes with a charset

package/dist/migrate/introspection/mysqlIntrospector.js

@@ -1,5 +1,5 @@
 import { unescapeMysqlString } from '../../util/sqlLiteral.js';
-import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.js';
+import { AbstractSqlSchemaIntrospector, } from './abstractSqlSchemaIntrospector.js';
 /**
  * MySQL/MariaDB schema introspector.
  * Works with both MySQL and MariaDB as they share the same information_schema structure.
@@ -117,13 +117,7 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         }));
     }
     async mapForeignKeysResult(_read, _tableName, results) {
-        return results.map((row) => ({
-            name: row.constraint_name,
-            columns: row.columns.split(','),
-            references: { table: row.referenced_table, columns: row.referenced_columns.split(',') },
-            onDelete: this.normalizeReferentialAction(row.delete_rule),
-            onUpdate: this.normalizeReferentialAction(row.update_rule),
-        }));
+        return this.joinedForeignKeys(results);
     }
     /**
      * MariaDB prints a string default as the literal it is (`'it''s'`). MySQL prints one bare, save an

package/dist/mongo/mongoDialect.d.ts

@@ -55,12 +55,20 @@ export declare class MongoDialect extends AbstractDialect {
      */
     private appendLogicalOperator;
     /**
-     * Emits the correlated `$lookup` for one relation condition and returns the condition that tests its
-     * result: presence of a row for a plain relation filter, a comparison against the row count for
+     * Emits the correlated `$lookup` for one relation condition, and adds to `filter` the condition testing
+     * its result: presence of a row for a plain relation filter, a comparison against the row count for
      * `$size`. The target's (and, for ManyToMany, the junction's) own filters scope the lookup, so a
      * relation subquery can no more read out-of-scope rows than a direct query on the target can.
      */
     private appendRelationLookup;
+    /** Adds `expr` to `filter`'s `$expr`, `AND`ed with any already there. */
+    private static andExpr;
+    /**
+     * `$size` against bounds, which MongoDB's own `$size` takes only as a number: the array at `path` counted
+     * in an `$expr`, which no other value satisfies. `$and` may evaluate every operand, so the count reads an
+     * empty array in place of any other value.
+     */
+    private static arraySize;
     /**
      * The correlated `$lookup` for the target rows of one relation `where` narrows, as `temp`: straight at
      * the target, or for a many-to-many from inside its junction's rows. The caller's filter bypass is not
@@ -74,11 +82,8 @@ export declare class MongoDialect extends AbstractDialect {
      * Each end is one field matched against one `_id`, so both sides must be sole-keyed.
      */
     private junctionOf;
-    /**
-     * Compares the looked-up row count, which is `[{ n: <count> }]` or `[]` when nothing matched - hence
-     * the `$ifNull` fallback to 0, so `{ $size: 0 }` matches parents with no related row at all.
-     */
-    private compareRelationCount;
+    /** `count` compared with `size`, a number or its bounds, as an aggregation expression. */
+    private static compareCount;
     /** Whether a query subtracts `key` from the projection, via `$exclude` or a negative `$select`. */
     private subtractsKey;
     /**
@@ -104,10 +109,17 @@ export declare class MongoDialect extends AbstractDialect {
      */
     private transformOperators;
     /**
-     * Maps the conditions inside `$elemMatch`: an operator map applies to the element itself, anything
-     * else is a per-field map whose operator objects each need mapping.
+     * What a value holding `value` matches, as the SQL engines read it: an operator map tests it, an array
+     * holds each element by `$all`, an object each key by {@link containment}, and a scalar is equal.
+     */
+    private held;
+    /**
+     * `$all` as one `$elemMatch` per value, since native `$all` never looks into an element that is an array:
+     * an array element holds each of its values alike, an object or operator map as {@link held} reads it.
      */
-    private transformElemMatch;
+    private allHolding;
+    /** An object's keys as {@link held} reads each, a nested object's by its dotted path rather than whole. */
+    private containment;
     select<E extends Document>(entity: Type<E>, select?: QuerySelectValue<E>, exclude?: QueryExclude<E>): Record<string, 0 | 1>;
     /**
      * The `$sort` stage. A relation key reads the document a `$lookup` unwound onto the parent, so - as

package/dist/mongo/mongoDialect.js

@@ -5,7 +5,7 @@ import { resolveQueryJoins, resolveSortableJoin } from '../dialect/queryJoins.js
 import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/query.js';
 import { QueryRaw } from '../type/queryRaw.js';
-import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, someKey, targetKeyColumns, } from '../util/index.js';
+import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, someKey, targetKeyColumns, } from '../util/index.js';
 /** Default {@link DialectFeatures} for MongoDB. */
 export const mongoDialectFeatures = {
     ifNotExists: false,
@@ -105,7 +105,7 @@ export class MongoDialect extends AbstractDialect {
                 if (!lookups) {
                     throw new TypeError(`filtering by relation '${key}' is not supported here on MongoDB`);
                 }
-                Object.assign(filter, this.appendRelationLookup(meta, key, val, lookups));
+                this.appendRelationLookup(filter, meta, key, val, lookups);
             }
             else {
                 this.assertNoRaw(val);
@@ -115,13 +115,21 @@ export class MongoDialect extends AbstractDialect {
                 if ((key === MongoDialect.ID_KEY || isReference) && !isOperatorObject(val)) {
                     val = this.toWireId(val);
                 }
-                if (isOperatorObject(val)) {
-                    val = this.transformOperators(val);
+                if (!isOperatorObject(val)) {
+                    filter[key] = Array.isArray(val) ? { $in: val } : val;
+                    continue;
+                }
+                // MongoDB's `$size` takes only a number, so bounds become an `$expr` beside the other operators.
+                const { $size: size, ...ops } = val;
+                if (!isRecord(size)) {
+                    filter[key] = this.transformOperators(val);
                 }
-                else if (Array.isArray(val)) {
-                    val = { $in: val };
+                else {
+                    MongoDialect.andExpr(filter, MongoDialect.arraySize(key, size));
+                    if (hasKeys(ops)) {
+                        filter[key] = this.transformOperators(ops);
+                    }
                 }
-                filter[key] = val;
             }
         }
         return filter;
@@ -149,21 +157,38 @@ export class MongoDialect extends AbstractDialect {
         filter['$nor'] = [...(filter['$nor'] ?? []), ...negated];
     }
     /**
-     * Emits the correlated `$lookup` for one relation condition and returns the condition that tests its
-     * result: presence of a row for a plain relation filter, a comparison against the row count for
+     * Emits the correlated `$lookup` for one relation condition, and adds to `filter` the condition testing
+     * its result: presence of a row for a plain relation filter, a comparison against the row count for
      * `$size`. The target's (and, for ManyToMany, the junction's) own filters scope the lookup, so a
      * relation subquery can no more read out-of-scope rows than a direct query on the target can.
      */
-    appendRelationLookup(meta, relKey, val, lookups) {
+    appendRelationLookup(filter, meta, relKey, val, lookups) {
         const temp = `${REL_TEMP_PREFIX}${lookups.temps.length}`;
         const sizeVal = parseRelationSize(val);
         const tail = sizeVal === undefined ? [{ $limit: 1 }] : [{ $count: COUNT_ALIAS }];
         const where = (sizeVal === undefined ? val : {});
         lookups.temps.push(temp);
         lookups.stages.push(this.relationLookup(meta, meta.relations[relKey], where, temp, tail));
-        return sizeVal === undefined
-            ? { [`${temp}.0`]: { $exists: true } }
-            : { $expr: this.compareRelationCount(temp, sizeVal) };
+        if (sizeVal === undefined) {
+            filter[`${temp}.0`] = { $exists: true };
+        }
+        else {
+            MongoDialect.andExpr(filter, MongoDialect.compareCount(this.tally(temp), sizeVal));
+        }
+    }
+    /** Adds `expr` to `filter`'s `$expr`, `AND`ed with any already there. */
+    static andExpr(filter, expr) {
+        filter['$expr'] = filter['$expr'] ? { $and: [filter['$expr'], expr] } : expr;
+    }
+    /**
+     * `$size` against bounds, which MongoDB's own `$size` takes only as a number: the array at `path` counted
+     * in an `$expr`, which no other value satisfies. `$and` may evaluate every operand, so the count reads an
+     * empty array in place of any other value.
+     */
+    static arraySize(path, size) {
+        const value = `$${path}`;
+        const count = { $size: { $cond: [{ $isArray: value }, value, []] } };
+        return { $and: [{ $isArray: value }, MongoDialect.compareCount(count, size)] };
     }
     /**
      * The correlated `$lookup` for the target rows of one relation `where` narrows, as `temp`: straight at
@@ -222,22 +247,18 @@ export class MongoDialect extends AbstractDialect {
             target: this.columnOf(throughMeta, targetColumn),
         };
     }
-    /**
-     * Compares the looked-up row count, which is `[{ n: <count> }]` or `[]` when nothing matched - hence
-     * the `$ifNull` fallback to 0, so `{ $size: 0 }` matches parents with no related row at all.
-     */
-    compareRelationCount(temp, sizeVal) {
-        const count = this.tally(temp);
-        if (typeof sizeVal === 'number') {
-            return { $eq: [count, sizeVal] };
+    /** `count` compared with `size`, a number or its bounds, as an aggregation expression. */
+    static compareCount(count, size) {
+        if (typeof size === 'number') {
+            return { $eq: [count, size] };
         }
-        const comparisons = Object.entries(sizeVal)
+        const comparisons = Object.entries(size)
             .filter(([, bound]) => bound !== undefined)
-            .flatMap(([op, bound]) => op === '$between'
+            .flatMap(([op, bound]) => op === '$between' && Array.isArray(bound)
             ? [{ $gte: [count, bound[0]] }, { $lte: [count, bound[1]] }]
             : [{ [op]: [count, bound] }]);
         if (!comparisons.length) {
-            throw new TypeError('$size on a relation needs at least one comparison');
+            throw new TypeError('$size needs at least one comparison');
         }
         return comparisons.length === 1 ? comparisons[0] : { $and: comparisons };
     }
@@ -311,7 +332,13 @@ export class MongoDialect extends AbstractDialect {
             // mapping - passing it through raw sends UQL-only operators (`$startsWith`, `$between`, ...)
             // straight to the server, which rejects them as unknown.
             if (op === '$elemMatch') {
-                result[op] = this.transformElemMatch(val);
+                result[op] = this.held(val);
+                continue;
+            }
+            // An object or an array is matched by what it holds, as the SQL engines read it, where native `$all`
+            // compares the whole element. MongoDB takes `$elemMatch` there only when every value is one.
+            if (op === '$all' && Array.isArray(val) && val.some((value) => Array.isArray(value) || isOperatorMap(value))) {
+                result[op] = this.allHolding(val);
                 continue;
             }
             // Native MongoDB operators - pass through directly
@@ -354,14 +381,36 @@ export class MongoDialect extends AbstractDialect {
         return result;
     }
     /**
-     * Maps the conditions inside `$elemMatch`: an operator map applies to the element itself, anything
-     * else is a per-field map whose operator objects each need mapping.
+     * What a value holding `value` matches, as the SQL engines read it: an operator map tests it, an array
+     * holds each element by `$all`, an object each key by {@link containment}, and a scalar is equal.
      */
-    transformElemMatch(match) {
-        if (isOperatorObject(match)) {
-            return this.transformOperators(match);
+    held(value) {
+        if (Array.isArray(value)) {
+            return this.transformOperators({ $all: value });
         }
-        return Object.fromEntries(Object.entries(match).map(([field, val]) => [field, isOperatorObject(val) ? this.transformOperators(val) : val]));
+        if (!isOperatorMap(value)) {
+            return value;
+        }
+        return isOperatorObject(value) ? this.transformOperators(value) : this.containment(value);
+    }
+    /**
+     * `$all` as one `$elemMatch` per value, since native `$all` never looks into an element that is an array:
+     * an array element holds each of its values alike, an object or operator map as {@link held} reads it.
+     */
+    allHolding(values) {
+        return values.map((value) => {
+            if (Array.isArray(value)) {
+                return { $elemMatch: { $all: this.allHolding(value) } };
+            }
+            return { $elemMatch: isOperatorMap(value) ? this.held(value) : { $eq: value } };
+        });
+    }
+    /** An object's keys as {@link held} reads each, a nested object's by its dotted path rather than whole. */
+    containment(object, prefix = '') {
+        return Object.fromEntries(Object.entries(object).flatMap(([key, value]) => {
+            const path = prefix ? `${prefix}.${key}` : key;
+            return isJsonObject(value) ? Object.entries(this.containment(value, path)) : [[path, this.held(value)]];
+        }));
     }
     select(entity, select, exclude) {
         const meta = getMeta(entity);
@@ -832,16 +881,15 @@ export class MongoDialect extends AbstractDialect {
         const groups = this.groupUpdateOperators(persistable);
         const { set, push, pull, unset } = groups;
         const exprKeys = [...Object.keys(pull), ...Object.keys(set), ...Object.keys(push)];
-        // MongoDB rejects two operators targeting one path in a single update document, so any path
-        // reached by more than one operator group forces the pipeline form.
+        // Native `$pull` fails on a value that is no array, and MongoDB rejects two operators targeting one
+        // path in a single update document: either forces the pipeline form.
         const allPaths = [...exprKeys, ...unset];
-        if (new Set(allPaths).size < allPaths.length) {
+        if (hasKeys(pull) || new Set(allPaths).size < allPaths.length) {
             return this.getUpdatePipeline(groups, new Set(exprKeys));
         }
         return {
             ...(hasKeys(set) && { $set: set }),
             ...(hasKeys(push) && { $push: push }),
-            ...(hasKeys(pull) && { $pull: pull }),
             ...(unset.size > 0 && { $unset: Object.fromEntries([...unset].map((path) => [path, ''])) }),
         };
     }
@@ -862,9 +910,9 @@ export class MongoDialect extends AbstractDialect {
             if (path in push) {
                 expr = { $concatArrays: [expr, [{ $literal: push[path] }]] };
             }
-            // Only `$set` and `$push` create a key. A `$pull` alone has to leave an absent one absent, and
-            // `$$REMOVE` is how a pipeline `$set` skips a field - without it the filter would store `[]`.
-            assignments[path] = path in set || path in push ? expr : { $cond: [{ $isArray: `$${path}` }, expr, '$$REMOVE'] };
+            // Only `$set` and `$push` create a key. A `$pull` alone leaves any value that is no array as it is,
+            // and an absent one absent, since a pipeline `$set` of a missing field adds none.
+            assignments[path] = path in set || path in push ? expr : { $cond: [{ $isArray: `$${path}` }, expr, `$${path}`] };
         }
         return [{ $set: assignments }, ...(unset.size > 0 ? [{ $unset: [...unset] }] : [])];
     }

package/dist/mssql/mssqlDialect.d.ts

@@ -1,6 +1,7 @@
 import { type RelationRows } from '../dialect/abstractSqlDialect.js';
+import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
 import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
-import type { EntityMeta, FieldOptions, InsertIdSource, Query, QueryContext, QueryOptions, QueryPager, QuerySizeComparisonOps, SqlDialectFeatures, Type, VectorDistance, VectorMetric } from '../type/index.js';
+import type { EntityMeta, FieldOptions, InsertIdSource, Query, QueryContext, QueryOptions, QueryPager, SqlDialectFeatures, Type, VectorDistance, VectorMetric } from '../type/index.js';
 /** Microsoft SQL Server 2017 and up. Identifiers are `"`-quoted, the ANSI spelling `tedious` enables. */
 export declare class MsSqlDialect extends MergeSqlDialect {
     #private;
@@ -103,18 +104,11 @@ export declare class MsSqlDialect extends MergeSqlDialect {
     estimatedCount<E>(ctx: QueryContext, entity: Type<E>): void;
     protected numericCast(expr: string): string;
     /**
-     * `JSON_VALUE` returns `NVARCHAR(4000)` and, in the lax mode that is the default, answers NULL
-     * rather than erroring for anything longer - so a long string read through it disappears without a
-     * word. `OPENJSON` has no such bound, so the path is split and its last segment matched as a key.
+     * `OPENJSON` at the path's parent, matching its last segment as a key, in either reading: `JSON_VALUE`
+     * answers NULL for text past 4000 characters, and `JSON_QUERY` for a scalar. A value reads back as
+     * text, which {@link jsonScalarParam} binds its operand as, and an array or object as its own JSON.
      */
-    protected getJsonPathScalarExpr(escapedColumn: string, jsonPathStr: string): string;
-    /**
-     * The same read as the scalar one. `JSON_QUERY` answers NULL for anything that is not an object or
-     * an array, so it cannot serve the JSON access mode a boolean or a number operand asks for -
-     * `OPENJSON` returns both as text, and {@link jsonScalarParam} binds the operand as the matching
-     * text. An array or object comes back as its own JSON text, which is what `OPENJSON` takes next.
-     */
-    protected getJsonPathJsonbExpr(escapedColumn: string, jsonPathStr: string): string;
+    protected jsonPathReading(escapedColumn: string, path: string): string;
     /**
      * A value compared against a JSON path, which reads back as text, so only a boolean needs spelling as
      * `'true'`; SQL Server has no cast that parses text as JSON.
@@ -126,11 +120,20 @@ export declare class MsSqlDialect extends MergeSqlDialect {
      * flattened a boolean to 1/0 for this engine's columns, so the cast is what restores it.
      */
     protected jsonWriteParam(ctx: QueryContext, value: unknown): string;
-    protected jsonElemFrom(jsonField: string, _fields: readonly string[], alias: string): string;
-    /** `JSON_VALUE`'s 4000-character bound applies to an element's field, unlike a whole column. */
-    protected jsonElemRef(alias: string, field?: string): string;
-    protected jsonAll(ctx: QueryContext, jsonField: string, value: unknown): string;
-    protected jsonSize(ctx: QueryContext, jsonField: string, value: number | QuerySizeComparisonOps): string;
+    protected jsonElemFrom(slot: JsonSlot, alias: string): string;
+    /** `JSON_QUERY` answers an array or an object as written, and a scalar as NULL. */
+    protected jsonIsArray(slot: JsonSlot): string;
+    /** An object element's `value` is its JSON text, which its fields are paths into. */
+    protected jsonElemDoc(alias: string): string;
+    /**
+     * An element of the value's own JSON type: `OPENJSON` reads a string and a number back as the same text,
+     * so the `type` it reports is what tells `'5'` from `5`. A number compares by value, cast on both sides:
+     * text against a numeric parameter converts implicitly, which throws on an element that is no number.
+     */
+    protected jsonElemEquals(ctx: QueryContext, _slot: JsonSlot, alias: string, value: unknown): string;
+    protected jsonLength(slot: JsonSlot): string;
+    /** SQL Server orders JSON as the text `OPENJSON` reads, so a number sorts by its value first. */
+    protected readonly jsonSortModes: readonly JsonAccessMode[];
     /** `JSON_MODIFY` takes one path per call, so several keys chain into one expression. */
     protected jsonSet(ctx: QueryContext, expr: string, set: Record<string, unknown>, _field?: FieldOptions): string;
     /** `'append '` prefixing the path extends the array there, creating it where there is none. */
@@ -139,7 +142,8 @@ export declare class MsSqlDialect extends MergeSqlDialect {
     protected jsonUnset(_ctx: QueryContext, expr: string, unset: readonly string[]): string;
     /**
      * The surviving elements are re-aggregated into an array and written back whole - there is no
-     * remove-by-value. `JSON_QUERY` is what marks the rebuilt text as JSON rather than a string.
+     * remove-by-value. `JSON_QUERY` is what marks the rebuilt text as JSON rather than a string. Only an
+     * array is rewritten: `JSON_MODIFY` would create an absent key, and any other value stays as it is.
      */
     protected jsonPullKey(ctx: QueryContext, expr: string, escapedCol: string, key: string, value: unknown): string;
 }