uql-orm 0.67.0 → 0.68.0

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;
 }

package/dist/mssql/mssqlDialect.js

@@ -1,7 +1,7 @@
 import { relationTermKey } from '../dialect/abstractSqlDialect.js';
-import { COUNT_ALIAS, JSON_ELEM_ALIAS } from '../dialect/aliases.js';
+import { COUNT_ALIAS, JSON_PULL_ALIAS } from '../dialect/aliases.js';
 import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
-import { jsonPath } from '../dialect/jsonSql.js';
+import { jsonArraySlotArgs, jsonPath, jsonSlotArgs } from '../dialect/jsonSql.js';
 import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
 import { fieldOptionsToCanonical } from '../schema/canonicalType.js';
@@ -34,12 +34,17 @@ const MSSQL_FEATURES = {
     rowLockOf: true,
     orderedUpsertReturning: false,
     orderedJsonAggregates: true,
-    partialJsonContainment: false,
-    typedJsonElements: false,
     narrowVectorTypes: false,
     vectorTuningNeedsTransaction: false,
     serialDeclaresPrimaryKey: false,
 };
+/** The `type` `OPENJSON` reports for the JSON scalar an element is compared with; anything else binds as a string. */
+function openJsonType(value) {
+    if (typeof value === 'number') {
+        return 2;
+    }
+    return typeof value === 'boolean' ? 3 : 1;
+}
 /** Microsoft SQL Server 2017 and up. Identifiers are `"`-quoted, the ANSI spelling `tedious` enables. */
 export class MsSqlDialect extends MergeSqlDialect {
     features = MSSQL_FEATURES;
@@ -234,25 +239,19 @@ export class MsSqlDialect extends MergeSqlDialect {
         return `TRY_CAST(${expr} AS FLOAT)`;
     }
     /**
-     * `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.
      */
-    getJsonPathScalarExpr(escapedColumn, jsonPathStr) {
-        const dot = jsonPathStr.lastIndexOf('.');
-        const parent = dot === -1 ? '$' : `$.${jsonPathStr.slice(0, dot).split('.').map(escapeSingleQuotes).join('.')}`;
-        const leaf = escapeSingleQuotes(jsonPathStr.slice(dot + 1));
+    jsonPathReading(escapedColumn, path) {
+        if (!path) {
+            return escapedColumn;
+        }
+        const dot = path.lastIndexOf('.');
+        const parent = dot === -1 ? '$' : `$.${path.slice(0, dot).split('.').map(escapeSingleQuotes).join('.')}`;
+        const leaf = escapeSingleQuotes(path.slice(dot + 1));
         return `(SELECT ${this.#elem.value} FROM OPENJSON(${escapedColumn}, '${parent}') WHERE ${this.#elem.key} = N'${leaf}')`;
     }
-    /**
-     * 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.
-     */
-    getJsonPathJsonbExpr(escapedColumn, jsonPathStr) {
-        return this.getJsonPathScalarExpr(escapedColumn, jsonPathStr);
-    }
     /**
      * 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.
@@ -286,24 +285,37 @@ export class MsSqlDialect extends MergeSqlDialect {
         }
         return `JSON_QUERY(${this.addValue(ctx, JSON.stringify(value))})`;
     }
-    jsonElemFrom(jsonField, _fields, alias) {
-        return `OPENJSON(${jsonField}) ${alias}`;
+    jsonElemFrom(slot, alias) {
+        return `OPENJSON(${jsonArraySlotArgs(slot, this.jsonIsArray(slot))}) ${alias}`;
+    }
+    /** `JSON_QUERY` answers an array or an object as written, and a scalar as NULL. */
+    jsonIsArray(slot) {
+        return `LEFT(JSON_QUERY(${jsonSlotArgs(slot)}), 1) = '['`;
     }
-    /** `JSON_VALUE`'s 4000-character bound applies to an element's field, unlike a whole column. */
-    jsonElemRef(alias, field) {
-        return field === undefined
-            ? `${alias}.${this.#elem.value}`
-            : `JSON_VALUE(${alias}.${this.#elem.value}, ${jsonPath(field)})`;
+    /** An object element's `value` is its JSON text, which its fields are paths into. */
+    jsonElemDoc(alias) {
+        return `${alias}.${this.#elem.value}`;
     }
-    jsonAll(ctx, jsonField, value) {
-        const alias = ctx.claimAlias(JSON_ELEM_ALIAS);
-        const conditions = value.map((val) => `EXISTS (SELECT 1 FROM OPENJSON(${jsonField}) ${alias} WHERE ${alias}.${this.#elem.value} = ${this.jsonScalarParam(ctx, val)})`);
-        return `(${conditions.join(' AND ')})`;
+    /**
+     * 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.
+     */
+    jsonElemEquals(ctx, _slot, alias, value) {
+        const type = `${alias}.${this.#elem.type}`;
+        if (value === null) {
+            return `${type} = 0`;
+        }
+        const elem = this.jsonElemDoc(alias);
+        const param = this.jsonScalarParam(ctx, value);
+        const equal = typeof value === 'number' ? `${this.numericCast(elem)} = ${this.numericCast(param)}` : `${elem} = ${param}`;
+        return `${equal} AND ${type} = ${openJsonType(value)}`;
     }
-    jsonSize(ctx, jsonField, value) {
-        const alias = ctx.claimAlias(JSON_ELEM_ALIAS);
-        return this.buildFragment(ctx, (fragmentCtx) => this.buildSizeComparison(fragmentCtx, () => fragmentCtx.append(`(SELECT COUNT(*) FROM OPENJSON(${jsonField}) ${alias})`), value));
+    jsonLength(slot) {
+        return `(SELECT COUNT(*) FROM OPENJSON(${jsonArraySlotArgs(slot, this.jsonIsArray(slot))}))`;
     }
+    /** SQL Server orders JSON as the text `OPENJSON` reads, so a number sorts by its value first. */
+    jsonSortModes = ['numeric', 'text'];
     /** `JSON_MODIFY` takes one path per call, so several keys chain into one expression. */
     jsonSet(ctx, expr, set, _field) {
         for (const [key, value] of Object.entries(set)) {
@@ -323,25 +335,24 @@ export class MsSqlDialect extends MergeSqlDialect {
     }
     /**
      * 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.
      */
     jsonPullKey(ctx, expr, escapedCol, key, value) {
-        const alias = ctx.claimAlias(JSON_ELEM_ALIAS);
-        const val = `${alias}.${this.#elem.value}`;
+        const slot = { base: escapedCol, path: key };
+        const val = this.jsonElemDoc(JSON_PULL_ALIAS);
         // `OPENJSON` hands back a string element unquoted and a null one as SQL NULL, so each survivor is
         // re-encoded from its reported `type` before the array is put back together - concatenated raw,
         // the result is text the engine then refuses to parse as JSON.
-        const encoded = `CASE ${alias}.${this.#elem.type}` +
+        const encoded = `CASE ${JSON_PULL_ALIAS}.${this.#elem.type}` +
             ` WHEN 0 THEN 'null'` +
             ` WHEN 1 THEN '"' + STRING_ESCAPE(${val}, 'json') + '"'` +
             ` ELSE ${val} END`;
         // `IS NULL OR` because a JSON null element reads back as SQL NULL, and `<>` against one is
         // unknown rather than true - which silently dropped every null from the array it rebuilt.
-        const kept = `SELECT '[' + STRING_AGG(${encoded}, ',') + ']' FROM OPENJSON(${escapedCol}, ${jsonPath(key)}) ${alias}` +
+        const kept = `SELECT '[' + STRING_AGG(${encoded}, ',') + ']' FROM ${this.jsonElemFrom(slot, JSON_PULL_ALIAS)}` +
             ` WHERE ${val} IS NULL OR ${val} <> ${this.jsonScalarParam(ctx, value)}`;
-        // `JSON_MODIFY` creates a path it does not find, so a `$pull` against an absent key would add an
-        // empty array where the other engines leave the document alone.
-        const path = jsonPath(key);
-        return `CASE WHEN JSON_QUERY(${escapedCol}, ${path}) IS NULL THEN ${expr} ELSE JSON_MODIFY(${expr}, ${path}, JSON_QUERY(COALESCE((${kept}), '[]'))) END`;
+        const pulled = `JSON_MODIFY(${expr}, ${jsonPath(key)}, JSON_QUERY(COALESCE((${kept}), '[]')))`;
+        return `CASE WHEN ${this.jsonIsArray(slot)} THEN ${pulled} ELSE ${expr} END`;
     }
 }