uql-orm 0.52.0 → 0.53.0

package/dist/mongo/mongoDialect.js

@@ -4,7 +4,7 @@ import { COUNT_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, sortCountField } from '..
 import { resolveQueryJoins, resolveSortableJoin } from '../dialect/queryJoins.js';
 import { assertSoleId, getMeta, soleIdOf } from '../entity/index.js';
 import { QueryRaw } from '../type/queryRaw.js';
-import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, buildQueryWhereAsMap, columnFamily, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationSize, parseSortByCount, someKey, targetKeyColumns, } from '../util/index.js';
+import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationSize, parseSortByCount, someKey, targetKeyColumns, } from '../util/index.js';
 /** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
 export const mongoDialectFeatures = {
     explicitJsonCast: false,
@@ -14,7 +14,6 @@ export const mongoDialectFeatures = {
     indexIfNotExists: false,
     schemas: false, // the connection picks the database, and a collection name takes no dot
     dropTableCascade: false,
-    renameColumn: false,
     foreignKeyAlter: false,
     primaryKeyAlter: false,
     generatedColumnAdd: false,
@@ -24,7 +23,6 @@ export const mongoDialectFeatures = {
     supportsTimestamptz: false,
     stringSizing: 'bounded-text',
     supportsUnsigned: false,
-    multipleCascadePaths: true,
     serverSideCursors: false,
 };
 /** What `toWireId` converts: the hex spelling of an `ObjectId`, and nothing looser. */
@@ -70,7 +68,7 @@ export class MongoDialect extends AbstractDialect {
     where(entity, where = {}, opts = {}) {
         const meta = getMeta(entity);
         // Filters are applied once, here at the scope entry point; recursion uses `renderFilter`.
-        return this.renderFilter(entity, this.scopedWhereMap(meta, where, opts));
+        return this.renderFilter(entity, this.scopedWhere(meta, where, opts));
     }
     /**
      * A `$where` that may constrain relations, split into the `$lookup` stages it needs and the `$match`
@@ -82,7 +80,7 @@ export class MongoDialect extends AbstractDialect {
     whereWithRelations(entity, where = {}, opts = {}) {
         const meta = getMeta(entity);
         const lookups = { stages: [], temps: [] };
-        const filter = this.renderFilter(entity, this.scopedWhereMap(meta, where, opts), opts, lookups);
+        const filter = this.renderFilter(entity, this.scopedWhere(meta, where, opts), opts, lookups);
         return { stages: lookups.stages, filter, unset: lookups.temps };
     }
     /** Whether a `$where` constrains any relation, and so needs the aggregation path rather than a cursor. */
@@ -91,9 +89,9 @@ export class MongoDialect extends AbstractDialect {
             return false;
         }
         const meta = getMeta(entity);
-        const whereMap = buildQueryWhereAsMap(meta, where);
+        const whereMap = where;
         return someKey(whereMap, (key) => MongoDialect.isGroupOp(key)
-            ? (whereMap[key] ?? []).some((it) => this.constrainsRelations(entity, it))
+            ? (whereMap[key] ?? []).some((it) => !(it instanceof QueryRaw) && this.constrainsRelations(entity, it))
             : Boolean(meta.relations[key]));
     }
     /**
@@ -103,9 +101,8 @@ export class MongoDialect extends AbstractDialect {
      */
     renderFilter(entity, where = {}, opts, lookups) {
         const meta = getMeta(entity);
-        const whereMap = buildQueryWhereAsMap(meta, where);
         const filter = {};
-        for (const [rawKey, rawVal] of Object.entries(whereMap)) {
+        for (const [rawKey, rawVal] of Object.entries(where)) {
             let key = rawKey;
             let val = rawVal;
             if (MongoDialect.isGroupOp(key)) {
@@ -155,8 +152,6 @@ export class MongoDialect extends AbstractDialect {
         const { join, negate } = MongoDialect.GROUP_OPS[key];
         const parts = MongoDialect.groupClauses(key, val)
             .map((filterIt) => {
-            // A `QueryRaw` here would recurse forever: `buildQueryWhereAsMap` re-wraps it as
-            // `{ $and: [raw] }`, which lands back on this branch.
             this.assertNoRaw(filterIt);
             return this.renderFilter(entity, filterIt, opts, lookups);
         })
@@ -190,7 +185,7 @@ export class MongoDialect extends AbstractDialect {
         // `withDeleted()` or `hardDelete` on the parent must not un-hide trashed rows of the target, the
         // same rule the SQL dialects' relation subqueries follow.
         const targetCondition = (sizeVal === undefined ? val : {});
-        const targetScope = this.renderFilter(relEntity, this.scopedWhereMap(relMeta, targetCondition), opts);
+        const targetScope = this.renderFilter(relEntity, this.scopedWhere(relMeta, targetCondition), opts);
         lookups.temps.push(temp);
         lookups.stages.push(this.relationLookup(meta, relOpts, relMeta, relEntity, targetScope, temp, tail, opts));
         return sizeVal === undefined
@@ -221,7 +216,7 @@ export class MongoDialect extends AbstractDialect {
     junctionLookup(meta, relOpts, relMeta, targetScope, temp, tail, opts) {
         const throughEntity = relOpts.through();
         const throughMeta = getMeta(throughEntity);
-        const junctionScope = this.renderFilter(throughEntity, this.scopedWhereMap(throughMeta, {}), opts);
+        const junctionScope = this.renderFilter(throughEntity, this.scopedWhere(throughMeta, {}), opts);
         const nested = REL_NESTED_KEY;
         // Both ends are one column here - each `$lookup` matches one field against `_id` - so both sides
         // must be sole-keyed. Sliced rather than indexed positionally: `references[1]` is the parent's
@@ -493,7 +488,7 @@ export class MongoDialect extends AbstractDialect {
             const relEntity = relOpts.entity();
             const relMeta = getMeta(relEntity);
             const temp = sortCountField(key);
-            const targetScope = this.renderFilter(relEntity, this.scopedWhereMap(relMeta, {}), opts);
+            const targetScope = this.renderFilter(relEntity, this.scopedWhere(relMeta, {}), opts);
             const tail = [{ $count: COUNT_ALIAS }];
             stages.push(this.relationLookup(meta, relOpts, relMeta, relEntity, targetScope, temp, tail, opts), {
                 $addFields: { [temp]: { $ifNull: [{ $arrayElemAt: [`$${temp}.${COUNT_ALIAS}`, 0] }, 0] } },

package/dist/mssql/mssqlDialect.d.ts

@@ -1,5 +1,5 @@
 import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
-import type { DialectFeatures, EntityMeta, FieldOptions, InsertIdSource, Query, QueryContext, QueryOptions, QueryPager, QuerySizeComparisonOps, Type } from '../type/index.js';
+import type { DialectFeatures, EntityMeta, FieldOptions, InsertIdSource, Query, QueryContext, QueryOptions, QueryPager, QuerySizeComparisonOps, Type, VectorDistance, VectorMetric } from '../type/index.js';
 /**
  * Microsoft SQL Server 2017 and up - the floor `STRING_AGG` sets, every other construct here being
  * 2016 or older.
@@ -89,6 +89,17 @@ export declare class MsSqlDialect extends MergeSqlDialect {
      * `uuidv7()` is emitted on. It is a predicate rather than a value, so it stands alone.
      */
     protected regexCondition(operand: string, placeholder: string): string;
+    /**
+     * `VECTOR_DISTANCE('cosine', a, b)`, one function taking the metric by name; `dot` is the negated
+     * inner product, pgvector's `<#>` convention. Exact search, as on sqlite-vec: 2025's DiskANN index
+     * is a preview feature, and only `VECTOR_SEARCH` reads it, never an `ORDER BY VECTOR_DISTANCE`.
+     */
+    readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
+    /**
+     * `VECTOR_DISTANCE` refuses the `nvarchar` a vector binds as, so it is cast - to the value's own
+     * length, which is its dimension. A write would convert implicitly, and shares the cast anyway.
+     */
+    protected appendVectorValue(ctx: QueryContext, value: readonly unknown[]): void;
     /** There is no `CREATE SCHEMA IF NOT EXISTS`, and `CREATE SCHEMA` has to be alone in its batch. */
     createSchemaSql(schema: string): string;
     /** The estimate the engine already keeps per partition, live without a stats refresh. */

package/dist/mssql/mssqlDialect.js

@@ -27,22 +27,16 @@ export class MsSqlDialect extends MergeSqlDialect {
         indexIfNotExists: false,
         schemas: true,
         dropTableCascade: false,
-        // `sp_rename` is a stored procedure, not DDL, so a rename is refused by name rather than emitted
-        // as an `ALTER TABLE` the parser rejects.
-        renameColumn: false,
         foreignKeyAlter: true,
         primaryKeyAlter: true,
         generatedColumnAdd: true,
         // Extended properties are out-of-band metadata with their own procedures, not comments.
         commentSyntax: 'none',
         vectorIndexRequiresNotNull: false,
-        vectorSupportsLength: false,
+        vectorSupportsLength: true,
         supportsTimestamptz: false,
         stringSizing: 'varchar',
         supportsUnsigned: false,
-        // Error 1785: the constraint is refused at create time, so any diamond-shaped schema would fail
-        // to build at all rather than misbehave on write.
-        multipleCascadePaths: false,
         serverSideCursors: false,
     };
     dialectName = 'mssql';
@@ -188,6 +182,25 @@ export class MsSqlDialect extends MergeSqlDialect {
     regexCondition(operand, placeholder) {
         return `REGEXP_LIKE(${operand}, ${placeholder})`;
     }
+    /**
+     * `VECTOR_DISTANCE('cosine', a, b)`, one function taking the metric by name; `dot` is the negated
+     * inner product, pgvector's `<#>` convention. Exact search, as on sqlite-vec: 2025's DiskANN index
+     * is a preview feature, and only `VECTOR_SEARCH` reads it, never an `ORDER BY VECTOR_DISTANCE`.
+     */
+    vectorMetrics = new Map([
+        ['cosine', { fn: 'VECTOR_DISTANCE', metricArg: 'cosine' }],
+        ['l2', { fn: 'VECTOR_DISTANCE', metricArg: 'euclidean' }],
+        ['inner', { fn: 'VECTOR_DISTANCE', metricArg: 'dot' }],
+    ]);
+    /**
+     * `VECTOR_DISTANCE` refuses the `nvarchar` a vector binds as, so it is cast - to the value's own
+     * length, which is its dimension. A write would convert implicitly, and shares the cast anyway.
+     */
+    appendVectorValue(ctx, value) {
+        ctx.append('CAST(');
+        super.appendVectorValue(ctx, value);
+        ctx.append(` AS VECTOR(${value.length}))`);
+    }
     /** There is no `CREATE SCHEMA IF NOT EXISTS`, and `CREATE SCHEMA` has to be alone in its batch. */
     createSchemaSql(schema) {
         const literal = escapeSingleQuotes(schema);

package/dist/querier/abstractQuerier.js

@@ -1,12 +1,13 @@
 import { assertSoleId, getMeta, idOf, namesKey, soleIdOf } from '../entity/index.js';
-import { asSelectMap, augmentWhere, childrenOf, clone, dataKeyed, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, joinedColumns, keyColumns, LoggerWrapper, isBoundedPerParent, parentJoins, queryChildrenOfAll, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, childrenOf, clone, dataKeyed, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, joinedColumns, keyColumns, LoggerWrapper, isBoundedPerParent, parentJoins, queryChildrenOfAll, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
 import { enrichError } from './queryError.js';
 import { fillRelationCounts, withIdForCounts } from './relationCount.js';
 /**
  * Rejects a nullish primary key before it reaches a statement. The by-id methods reduce to
- * `{ $where: id }`, and a nullish `$where` is *no filter*, so an unchecked one addresses the whole
- * table. An entity declares its id optional, which puts `undefined` inside `IdValue<E>`, and the
- * HTTP layer reaches these methods with parsed JSON regardless, so the guard belongs at runtime.
+ * `{ $where: { id } }`, and a key compared to `undefined` is *no filter*, so an unchecked one
+ * addresses the whole table. An entity declares its id optional, which puts `undefined` inside
+ * `IdValue<E>`, and the HTTP layer reaches these methods with parsed JSON regardless, so the guard
+ * belongs at runtime.
  *
  * Its callers are all `async` so this surfaces as a rejection on every one of them: a guard that
  * threw synchronously from some and rejected from others would escape a caller's `.catch()`.
@@ -16,7 +17,7 @@ function assertIdValue(entity, id) {
         throw new TypeError(`'${entity.name}' was addressed by id, but the id is ${String(id)}`);
     }
     if (isScalarId(id)) {
-        // One value names one column, which `buildQueryWhereAsMap` refuses on a composite.
+        // One value names one column, which `whereIds` refuses on a composite.
         return;
     }
     // Every key, or the `$where` names only some of the columns and addresses each row that agrees on
@@ -119,7 +120,7 @@ export class AbstractQuerier {
     }
     async findOneById(entity, id, q = {}, opts) {
         assertIdValue(entity, id);
-        return this.findOne(entity, { ...q, $where: augmentWhere(getMeta(entity), q.$where, id) }, opts);
+        return this.findOne(entity, { ...q, $where: { ...q.$where, ...whereIds(getMeta(entity), id) } }, opts);
     }
     async findOne(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts);
@@ -194,21 +195,21 @@ export class AbstractQuerier {
     }
     async updateOneById(entity, id, payload, opts) {
         assertIdValue(entity, id);
-        return this.updateMany(entity, { $where: id }, payload, opts);
+        return this.updateMany(entity, { $where: whereIds(getMeta(entity), id) }, payload, opts);
     }
     async updateMany(entity, q, payload, opts) {
         return this.hooked(entity, 'Update', [payload], () => this.internalUpdateMany(entity, q, payload, opts));
     }
     async restoreOneById(entity, id) {
         assertIdValue(entity, id);
-        return this.restoreMany(entity, { $where: id });
+        return this.restoreMany(entity, { $where: whereIds(getMeta(entity), id) });
     }
     async restoreMany(entity, q) {
         const meta = getMeta(entity);
         if (!meta.softDelete) {
             throw new TypeError(`'${entity.name}' has not enabled 'softDelete'`);
         }
-        const $where = augmentWhere(meta, q.$where, { [meta.softDelete]: { $ne: null } });
+        const $where = { ...q.$where, [meta.softDelete]: { $ne: null } };
         return this.updateMany(entity, { ...q, $where }, { [meta.softDelete]: null }, {
             filters: { softDelete: false },
         });
@@ -234,7 +235,7 @@ export class AbstractQuerier {
     }
     async deleteOneById(entity, id, opts) {
         assertIdValue(entity, id);
-        return this.deleteMany(entity, { $where: id }, opts);
+        return this.deleteMany(entity, { $where: whereIds(getMeta(entity), id) }, opts);
     }
     async deleteMany(entityOrQuery, qOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, qOrOpts, maybeOpts);
@@ -248,7 +249,8 @@ export class AbstractQuerier {
         let target = q;
         if (doomed) {
             const meta = getMeta(entity);
-            target = { $where: doomed.map((it) => idOf(meta, it)) };
+            const ids = doomed.map((it) => idOf(meta, it));
+            target = { $where: whereIds(meta, ids) };
         }
         await this.emitHook(entity, 'beforeDelete', doomed ?? []);
         const changes = await this.internalDeleteMany(entity, target, opts);

package/dist/querier/abstractSqlQuerier.js

@@ -1,7 +1,7 @@
 import { COUNT_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
 import { decodeColumn } from '../dialect/hydrateColumn.js';
 import { getMeta, idOf, soleIdOf } from '../entity/index.js';
-import { buildUpdateResult, cascadesOnDelete, clone, getInsertFieldKeys, insertShapeOf, getRelationRequestSummary, hasKeys, idOnlyQuery, isAutoIncrement, isPagedQuery, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, withoutSoftDeleteFilter, } from '../util/index.js';
+import { buildUpdateResult, cascadesOnDelete, clone, getInsertFieldKeys, insertShapeOf, getRelationRequestSummary, hasKeys, idOnlyQuery, isAutoIncrement, isPagedQuery, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 import { enrichError } from './queryError.js';
 /**
@@ -418,7 +418,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             if (!ids.length) {
                 return 0;
             }
-            target = { $where: ids };
+            target = { $where: whereIds(getMeta(entity), ids) };
         }
         const ctx = this.dialect.createContext();
         this.dialect.update(ctx, entity, target, payload, opts);
@@ -507,7 +507,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         // outright by any schema that declares the constraint without `ON DELETE CASCADE`.
         await this.deleteRelations(entity, ids, opts);
         const deleteCtx = this.dialect.createContext();
-        this.dialect.delete(deleteCtx, entity, { $where: ids }, opts);
+        this.dialect.delete(deleteCtx, entity, { $where: whereIds(meta, ids) }, opts);
         const { changes = 0 } = await this.run(deleteCtx.sql, deleteCtx.values);
         return changes;
     }

package/dist/schema/canonicalType.js

@@ -213,8 +213,8 @@ const ENGINE_TYPES = {
     },
     // SQLite uses affinity, so no size variants.
     sqlite: { scalars: withVectorType(SQLITE_SCALAR_MAP, 'TEXT') },
-    // A 2025 server has a native `VECTOR`; below that the column is JSON text, which stays queryable.
-    mssql: { scalars: withVectorType(MSSQL_SCALAR_MAP, 'NVARCHAR(MAX)'), sizes: MSSQL_SIZES },
+    // 2025 and up; below that the server refuses the type rather than storing it as text.
+    mssql: { scalars: withVectorType(MSSQL_SCALAR_MAP, 'VECTOR'), sizes: MSSQL_SIZES },
     mongodb: { scalars: withVectorType(MONGO_SCALAR_MAP, 'array') },
 };
 /**

package/dist/sqlite/sqliteDialect.js

@@ -11,7 +11,6 @@ export class SqliteDialect extends AbstractSqlDialect {
         indexIfNotExists: true,
         schemas: false, // SQLite's namespaces are attached database files, not declared objects
         dropTableCascade: false,
-        renameColumn: true,
         foreignKeyAlter: false, // SQLite does not support adding FKs to existing tables
         primaryKeyAlter: false, // nor changing a key: the only route is rebuilding the table
         generatedColumnAdd: false, // accepted in a CREATE TABLE, rejected in an ALTER
@@ -21,7 +20,6 @@ export class SqliteDialect extends AbstractSqlDialect {
         supportsTimestamptz: false,
         stringSizing: 'text',
         supportsUnsigned: false,
-        multipleCascadePaths: true,
         serverSideCursors: false,
     };
     dialectName = 'sqlite';

package/dist/type/dialect.d.ts

@@ -89,7 +89,6 @@ export interface EngineFeatures {
      */
     readonly schemas: boolean;
     readonly dropTableCascade: boolean;
-    readonly renameColumn: boolean;
     readonly foreignKeyAlter: boolean;
     /**
      * Whether a table's primary key can be changed on an existing table. False on SQLite, whose only
@@ -140,13 +139,6 @@ export interface EngineFeatures {
     readonly stringSizing: 'text' | 'bounded-text' | 'varchar';
     /** Whether the engine has unsigned integers, so `@Field({ unsigned: true })` reaches the column. */
     readonly supportsUnsigned: boolean;
-    /**
-     * Whether one table can be reached by two cascading foreign-key paths. SQL Server refuses the
-     * constraint outright ("may cause cycles or multiple cascade paths", error 1785) and Oracle
-     * likewise, so a cascade is downgraded to `NO ACTION` there rather than emitting DDL the engine
-     * rejects - which would otherwise fail on any diamond-shaped schema at create time.
-     */
-    readonly multipleCascadePaths: boolean;
     /**
      * Whether the engine has SQL-level cursors (`DECLARE`/`FETCH FORWARD`/`CLOSE`), which is how a
      * driver with no cursor API of its own still streams a result set instead of buffering it - see

package/dist/type/query.d.ts

@@ -143,7 +143,7 @@ type ToOneRelationKey<E> = {
 type ToManyRelationKey<E> = Exclude<RelationKey<E>, ToOneRelationKey<E>>;
 /**
  * sort by map - supports field keys, JSON dot-notation paths (restricted to real JSON fields,
- * like `QueryWhereMap`), relation sort via nested objects, and vector similarity search on
+ * like `QueryWhere`), relation sort via nested objects, and vector similarity search on
  * `number[]` fields. `Vector` is what confines a vector search to the level the statement ranks:
  * the queried entity. A relation of it is joined in one row at a time, so there is nothing to rank
  * there - the SQL dialects throw, and MongoDB would quietly drop it, so this is its only guard.

package/dist/type/queryWhere.d.ts

@@ -1,4 +1,4 @@
-import type { EntityId, FieldKey, JsonFieldPaths, JsonFieldPathValue, RelationKey, RelationTarget } from './entity.js';
+import type { FieldKey, JsonFieldPaths, JsonFieldPathValue, RelationKey, RelationTarget } from './entity.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { ExpandScalar, IsMany, QueryComparableScalar, Scalar } from './utility.js';
 import type { QueryVectorQuery } from './vector.js';
@@ -20,12 +20,6 @@ export type QueryTextSearchOptions<E> = {
      */
     $config?: string;
 };
-/**
- * comparison by fields.
- */
-export type QueryWhereFieldMap<E> = {
-    [K in FieldKey<E>]?: QueryWhereFieldValue<E[K]>;
-};
 /**
  * Field comparison, JSON dot-path access, and relation filtering - all fully typed.
  * JSON dot-paths are restricted to real JSON fields, and typed payloads type each path's value
@@ -37,9 +31,12 @@ export type QueryWhereFieldMap<E> = {
  * {@link QuerySortMap} is: the sets are disjoint, and an assignability check against an
  * intersection is repeated per constituent, which every `$where` in a codebase pays. The root
  * operators stay a separate member - they are a fixed shape, not keyed off the entity.
+ *
+ * An object and nothing else: in a union with ids or lists, TypeScript reports a wrong value against
+ * the whole `$where` instead of the key holding it. Ids are `{ id: 1 }`, or the by-id methods.
  */
-export type QueryWhereMap<E> = QueryWhereRootOperator<E> & {
-    [K in FieldKey<E> | RelationKey<E> | JsonFieldPaths<E>]?: K extends FieldKey<E> ? QueryWhereFieldValue<E[K]> : K extends RelationKey<E> ? QueryWhereMap<RelationTarget<E[K]>> | QueryRelationSizeFilter : QueryWhereFieldValue<JsonFieldPathValue<E, K & string>>;
+export type QueryWhere<E> = QueryWhereRootOperator<E> & {
+    [K in FieldKey<E> | RelationKey<E> | JsonFieldPaths<E>]?: K extends FieldKey<E> ? QueryWhereFieldValue<E[K]> : K extends RelationKey<E> ? QueryWhere<RelationTarget<E[K]>> | QueryRelationSizeFilter : QueryWhereFieldValue<JsonFieldPathValue<E, K & string>>;
 };
 /**
  * Filter a to-many relation by its row count.
@@ -332,14 +329,5 @@ export type QueryWhereFieldValue<T> = T | (undefined extends T ? null : never) |
 /**
  * query filter array - the value every {@link QueryGroupOp} takes.
  */
-export type QueryWhereArray<E> = (QueryWhereMap<E> | QueryRaw)[];
-/**
- * query filter.
- */
-/**
- * `EntityId` rather than `IdValue`: a by-id method reduces to `$where: id`, and a composite key is
- * addressed by an object carrying every key. That object is a where map naming those columns, so the
- * two spellings meet here rather than needing a conversion.
- */
-export type QueryWhere<E> = EntityId<E> | EntityId<E>[] | QueryWhereMap<E> | QueryWhereArray<E> | QueryRaw;
+export type QueryWhereArray<E> = (QueryWhere<E> | QueryRaw)[];
 export {};

package/dist/type/vector.d.ts

@@ -58,13 +58,15 @@ export type WithDistance<E, K extends string = '_distance'> = E & Record<K, numb
  *
  * `opsSuffix` rides along on the operator form because pgvector's index operator class is named from
  * the same metric (`vector_cosine_ops`): keeping them together is what stops a dialect from having
- * the operator but not the class it indexes with.
+ * the operator but not the class it indexes with. `metricArg` is for the engine with one function
+ * taking the metric by name: SQL Server's `VECTOR_DISTANCE('cosine', a, b)`.
  */
 export type VectorMetric = {
     readonly op: string;
     readonly opsSuffix: string;
 } | {
     readonly fn: string;
+    readonly metricArg?: string;
 };
 /** The operator form, for the pgvector-family dialects whose index DDL also needs `opsSuffix`. */
 export type VectorOperatorMetric = Extract<VectorMetric, {

package/dist/util/dialect.util.d.ts

@@ -1,4 +1,4 @@
-import { type CascadeType, type EntityData, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryVectorSearch, type QueryWhere, type QueryWhereMap, type RelationKey } from '../type/index.js';
+import { type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryVectorSearch, type QueryWhere, type RelationKey } from '../type/index.js';
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E>, callbackKey: CallbackKey): FieldKey<E>[];
 /** Appends `record`'s not-yet-`seen` insertable keys (real, caller-written, defined value) to `keys`. */
@@ -90,13 +90,16 @@ export declare function findVectorIndex<E>(meta: EntityMeta<E>, key: string): En
 export declare function hasVectorNear(where: unknown): boolean;
 /** Type guard: checks whether an update payload value is a JSON operator object. */
 export declare function isJsonUpdateOp(value: unknown): value is JsonUpdateOp;
-export declare function augmentWhere<E>(meta: EntityMeta<E>, target?: QueryWhere<E>, source?: QueryWhere<E>): QueryWhere<E>;
 /**
- * Normalizes any `$where` shape (id, id[], raw, or map) to a `QueryWhereMap`. Read-only: for a map
- * input it returns that same object by reference (no copy), so callers must not mutate the result -
- * {@link applyFilters} and {@link augmentWhere} return new objects instead.
+ * The `$where` naming rows by key: a bare value names the one key column (refused on a composite), a
+ * composite's key map is a `$where` already, and a list is an `IN` of bare values or an OR of maps.
  */
-export declare function buildQueryWhereAsMap<E>(meta: EntityMeta<E>, filter?: QueryWhere<E>): QueryWhereMap<E>;
+export declare function whereIds<E>(meta: EntityMeta<E>, ids: EntityId<E> | EntityId<E>[]): QueryWhere<E>;
+/**
+ * Refuses a `$where` that is not a map. Untyped JS and parsed JSON can still pass an id or a list of
+ * them, and a scalar read as a map has no keys: the statement would address every row.
+ */
+export declare function assertWhere<E>(meta: EntityMeta<E>, where: unknown): void;
 /** Returns a `QueryOptions.filters` value with the built-in soft-delete filter disabled (used by hard delete). */
 export declare function withoutSoftDeleteFilter(filters: QueryOptions['filters']): QueryOptions['filters'];
 /**
@@ -112,7 +115,7 @@ export declare function withoutSoftDeleteFilter(filters: QueryOptions['filters']
  * (`{}`) resolved to "no restriction" and adds nothing - the escape hatch for trusted cross-tenant
  * work (e.g. a maintenance job running under a `system` context).
  */
-export declare function applyFilters<E>(meta: EntityMeta<E>, whereMap: QueryWhereMap<E>, opts?: QueryOptions): QueryWhereMap<E>;
+export declare function applyFilters<E>(meta: EntityMeta<E>, whereMap: QueryWhere<E>, opts?: QueryOptions): QueryWhere<E>;
 /**
  * Parsed entry from a `$group` map - either a raw group key or an aggregate function call.
  */

package/dist/util/dialect.util.js

@@ -3,7 +3,7 @@ import { soleIdOf } from '../entity/metadata/definition.js';
 import { QueryRaw, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index.js';
 import { VECTOR_INDEX_TYPES } from '../type/vector.js';
 import { isDatabaseWritten } from './field.util.js';
-import { entityName, getFieldKeys, getKeys, hasKeys, isScalarId, someKey } from './object.util.js';
+import { entityName, getFieldKeys, getKeys, hasKeys, isScalarId, isWhereMap, someKey } from './object.util.js';
 export function filterFieldKeys(meta, payload, callbackKey) {
     return getKeys(payload).filter((key) => {
         const fieldOpts = meta.fields[key];
@@ -234,37 +234,24 @@ const JSON_UPDATE_OPS = [
 export function isJsonUpdateOp(value) {
     return value !== null && typeof value === 'object' && someKey(value, (key) => JSON_UPDATE_OPS.includes(key));
 }
-export function augmentWhere(meta, target = {}, source = {}) {
-    const targetComparison = buildQueryWhereAsMap(meta, target);
-    const sourceComparison = buildQueryWhereAsMap(meta, source);
-    return {
-        ...targetComparison,
-        ...sourceComparison,
-    };
-}
 /**
- * Normalizes any `$where` shape (id, id[], raw, or map) to a `QueryWhereMap`. Read-only: for a map
- * input it returns that same object by reference (no copy), so callers must not mutate the result -
- * {@link applyFilters} and {@link augmentWhere} return new objects instead.
+ * The `$where` naming rows by key: a bare value names the one key column (refused on a composite), a
+ * composite's key map is a `$where` already, and a list is an `IN` of bare values or an OR of maps.
  */
-export function buildQueryWhereAsMap(meta, filter = {}) {
-    if (filter instanceof QueryRaw) {
-        return { $and: [filter] };
-    }
-    if (Array.isArray(filter)) {
-        // A list of bare ids is an `IN` over the one key column; a list of anything else is a list of
-        // `$where`s, which is an OR - and that is how a composite's id objects name a settled set of rows.
-        return filter.every(isScalarId)
-            ? { [soleIdOf(meta, 'addressing by a bare id value')]: filter }
-            : { $or: filter };
+export function whereIds(meta, ids) {
+    if (Array.isArray(ids) ? ids.every(isScalarId) : isScalarId(ids)) {
+        return { [soleIdOf(meta, 'addressing by a bare id value')]: ids };
     }
-    if (isScalarId(filter)) {
-        // A scalar can only name one column, so on a composite it would address every row agreeing on
-        // that one. A composite is addressed by a map, which falls through below as the `$where` it
-        // already is - an id object and a where map are the same shape by design.
-        return { [soleIdOf(meta, 'addressing by a bare id value')]: filter };
+    return (Array.isArray(ids) ? { $or: ids } : ids);
+}
+/**
+ * Refuses a `$where` that is not a map. Untyped JS and parsed JSON can still pass an id or a list of
+ * them, and a scalar read as a map has no keys: the statement would address every row.
+ */
+export function assertWhere(meta, where) {
+    if (!isWhereMap(where)) {
+        throw new TypeError(`$where on '${entityName(meta)}' must be a map of conditions, such as { id: 1 }`);
     }
-    return filter;
 }
 /** Returns a `QueryOptions.filters` value with the built-in soft-delete filter disabled (used by hard delete). */
 export function withoutSoftDeleteFilter(filters) {
@@ -314,7 +301,7 @@ export function applyFilters(meta, whereMap, opts) {
             }
             continue;
         }
-        const conditionMap = buildQueryWhereAsMap(meta, condition);
+        const conditionMap = condition;
         if (!hasKeys(conditionMap)) {
             continue; // resolved to "no restriction" (e.g. a trusted system context) - nothing to merge
         }

package/dist/util/object.util.d.ts

@@ -35,3 +35,5 @@ export declare function getFieldKeys<E>(fields: {
  * is what a `$where` map and a composite key's id object both are; an array is a list of either.
  */
 export declare function isScalarId(value: unknown): boolean;
+/** Whether `value` is a plain object naming columns, the one shape a `$where` takes. */
+export declare function isWhereMap(value: unknown): value is Record<string, unknown>;

package/dist/util/object.util.js

@@ -81,3 +81,7 @@ export function isScalarId(value) {
     const proto = Object.getPrototypeOf(value);
     return proto !== Object.prototype && proto !== null;
 }
+/** Whether `value` is a plain object naming columns, the one shape a `$where` takes. */
+export function isWhereMap(value) {
+    return !Array.isArray(value) && !isScalarId(value);
+}

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -151,7 +151,7 @@
     "express": "^5.2.1",
     "mariadb": "^3.5.4",
     "mongodb": "^7.6.0",
-    "mssql": "^11",
+    "mssql": "^12",
     "mysql2": "^3.24.4",
     "pg": "^8.23.0",
     "pg-query-stream": "^4.17.0",