uql-orm 0.52.0 → 0.54.0

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 { getMeta, idOf, namesKey } from '../entity/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';
 /**
@@ -22,50 +22,36 @@ function partitionBySuppliedId(payload, idKey) {
     return supplied.length && generated.length ? [supplied, generated] : [supplied.length ? supplied : generated];
 }
 /**
- * Rows grouped by the columns they carry, payload order kept within each group - or `undefined` when
- * they all carry the same ones, which is the batch as it stands and needs no grouping at all.
+ * Row indexes grouped by the columns their rows carry, payload order kept within each group.
  *
  * Deliberately finer than {@link partitionBySuppliedId}: an upsert's `DO UPDATE SET` is one
  * assignment list for the whole statement, so rows of different shapes cannot share one at all.
  */
 function groupByInsertShape(meta, payload) {
-    const first = insertShapeOf(meta, payload[0]);
-    let index = 1;
-    while (index < payload.length && insertShapeOf(meta, payload[index]) === first) {
-        index++;
-    }
-    if (index === payload.length) {
-        return undefined;
-    }
-    const groups = new Map([[first, payload.slice(0, index)]]);
-    for (; index < payload.length; index++) {
-        const row = payload[index];
-        const shape = insertShapeOf(meta, row);
+    const groups = new Map();
+    for (let index = 0; index < payload.length; index++) {
+        const shape = insertShapeOf(meta, payload[index]);
         const group = groups.get(shape);
         if (group) {
-            group.push(row);
+            group.push(index);
         }
         else {
-            groups.set(shape, [row]);
+            groups.set(shape, [index]);
         }
     }
     return [...groups.values()];
 }
 /**
- * How many rows one statement can carry within the dialect's bind budget. `DEFAULT` cells bind no
- * parameter, so fields-per-record is a safe upper bound. Every multi-row write splits on this: D1
- * allows 100 binds, which a couple of dozen rows reach.
+ * A group's row indexes split into statements within the dialect's bind budget, payload order kept.
+ * `DEFAULT` cells bind no parameter, so fields-per-record is a safe upper bound. Every multi-row
+ * write splits on this: D1 allows 100 binds, which a couple of dozen rows reach.
  */
-function bindBudgetChunkSize(meta, rows, maxBindValues) {
-    const fieldsPerRecord = getInsertFieldKeys(meta, rows).length || 1;
-    return Math.max(1, Math.floor(maxBindValues / fieldsPerRecord));
-}
-/** `rows` split into statement-sized slices, payload order kept. */
-function chunkByBindBudget(meta, rows, maxBindValues) {
-    const size = bindBudgetChunkSize(meta, rows, maxBindValues);
+function chunkByBindBudget(meta, payload, group, maxBindValues) {
+    const fieldsPerRecord = getInsertFieldKeys(meta, group.map((index) => payload[index])).length;
+    const size = Math.max(1, Math.floor(maxBindValues / (fieldsPerRecord || 1)));
     const chunks = [];
-    for (let start = 0; start < rows.length; start += size) {
-        chunks.push(rows.slice(start, start + size));
+    for (let start = 0; start < group.length; start += size) {
+        chunks.push(group.slice(start, start + size));
     }
     return chunks;
 }
@@ -186,17 +172,6 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         this.dialect.findPerParent(ctx, entity, q, partition);
         return this.hydrateRows(entity, q, await this.all(ctx.sql, ctx.values));
     }
-    /**
-     * One statement for both: the page carries its own unpaged total in an extra column. An empty page
-     * has no row to carry it, which is the one case still needing a count of its own - a `$skip` past
-     * the end, or a filter nothing matched.
-     *
-     * A `$required` relation needs no special case: the window counts what the INNER JOIN left, which
-     * is exactly the total a caller of a filtered read is asking for. A `$lock` is the one clause an
-     * engine may refuse to have in the same statement, which {@link AbstractSqlDialect.supportsWindowWithRowLock}
-     * answers; where it does, the total comes from a count of its own. A `$distinct` read needs one
-     * too, and a deduplicating one: see {@link AbstractSqlDialect.countDistinct}.
-     */
     /**
      * How to count when the total cannot ride along in the read's own `COUNT(*) OVER ()` column, or
      * `undefined` when it can. Two clauses rule the window out: `$distinct`, because a window counts
@@ -212,6 +187,17 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
         return undefined;
     }
+    /**
+     * One statement for both: the page carries its own unpaged total in an extra column. An empty page
+     * has no row to carry it, which is the one case still needing a count of its own - a `$skip` past
+     * the end, or a filter nothing matched.
+     *
+     * A `$required` relation needs no special case: the window counts what the INNER JOIN left, which
+     * is exactly the total a caller of a filtered read is asking for. A `$lock` is the one clause an
+     * engine may refuse to have in the same statement, which {@link AbstractSqlDialect.supportsWindowWithRowLock}
+     * answers; where it does, the total comes from a count of its own. A `$distinct` read needs one
+     * too, and a deduplicating one: see {@link AbstractSqlDialect.countDistinct}.
+     */
     async internalFindManyAndCount(entity, q, opts) {
         const separately = this.countedSeparately(entity, q, opts);
         if (separately) {
@@ -359,24 +345,15 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
         return res;
     }
-    async internalInsertMany(entity, payload) {
-        if (!payload?.length) {
-            return [];
-        }
-        payload = clone(payload);
+    async internalInsertMany(entity, rows) {
         const meta = getMeta(entity);
-        // What comes back is one column's value, so a composite reports nothing here and `insertMany`
-        // names those rows from the payload instead. `sole` is what keeps every id path off a key that
-        // is several columns.
+        // What comes back is one column's value, so nothing is read back for a composite: its rows
+        // already carry every column of it. `sole` is what keeps every id path off such a key.
         const [idKey] = meta.ids;
         const sole = meta.ids.length === 1;
         const idField = sole ? meta.fields[idKey] : undefined;
         const generatedKey = !!idField && isAutoIncrement(idField, true);
-        const payloadIds = new Array(payload.length);
-        for (const group of partitionBySuppliedId(payload, idKey)) {
-            // Per group, not per batch: the two carry different columns - one names the key, one does not -
-            // so a budget taken over their union would under-fill the statement that is missing one.
-            const chunkSize = bindBudgetChunkSize(meta, group.map((index) => payload[index]), this.dialect.maxBindValues);
+        for (const group of partitionBySuppliedId(rows, idKey)) {
             // RETURNING-based ids are exact per row. Header-derived ones (LAST_INSERT_ID / lastInsertRowid
             // arithmetic) are only sound when the key is database-generated and every row *in this
             // statement* left it to the database. That is a property of the statement, not of the batch:
@@ -385,28 +362,26 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             // most one extra statement and keeps each of them inferable.
             const idsReliable = sole &&
                 (this.dialect.insertIdSource === 'returning' ||
-                    (generatedKey && group.every((index) => payload[index][idKey] === undefined)));
+                    (generatedKey && group.every((index) => rows[index][idKey] === undefined)));
             // Inferring multiple ids from the single header id (MySQL) assumes a known stride; a clustered
             // server may set `auto_increment_increment` > 1, so probe it (once, cached) before inferring.
             if (idsReliable && group.length > 1 && this.dialect.insertIdSource === 'firstId') {
                 this.#insertIdIncrement ??= await this.loadInsertIdIncrement();
             }
-            for (let start = 0; start < group.length; start += chunkSize) {
-                const indexes = group.slice(start, start + chunkSize);
+            // Per group, not per batch: the two carry different columns - one names the key, one does not -
+            // so a budget taken over their union would under-fill the statement that is missing one.
+            for (const indexes of chunkByBindBudget(meta, rows, group, this.dialect.maxBindValues)) {
                 const ctx = this.dialect.createContext();
-                this.dialect.insert(ctx, entity, indexes.map((index) => payload[index]));
+                this.dialect.insert(ctx, entity, indexes.map((index) => rows[index]));
                 const { ids = [] } = await this.run(ctx.sql, ctx.values);
-                indexes.forEach((index, position) => {
-                    const it = payload[index];
-                    if (idsReliable) {
-                        it[idKey] ??= ids[position];
+                if (idsReliable) {
+                    for (let position = 0; position < indexes.length; position++) {
+                        rows[indexes[position]][idKey] ??= ids[position];
                     }
-                    payloadIds[index] = sole ? it[idKey] : undefined;
-                });
+                }
             }
         }
-        await this.insertRelations(entity, payload);
-        return payloadIds;
+        await this.insertRelations(entity, rows);
     }
     async internalUpdateMany(entity, q, payload, opts) {
         payload = clone(payload);
@@ -418,7 +393,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);
@@ -446,8 +421,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         // One statement per shape, each split again to stay inside the bind budget. Grouping first is
         // what makes the budget arithmetic right: every row of a group carries the same columns, so the
         // `DO UPDATE SET` resolves to non-binding `EXCLUDED` references rather than inlined values.
-        const groups = groupByInsertShape(meta, payload);
-        const statements = (groups ?? [payload]).flatMap((group) => chunkByBindBudget(meta, group, this.dialect.maxBindValues));
+        const statements = groupByInsertShape(meta, payload).flatMap((group) => chunkByBindBudget(meta, payload, group, this.dialect.maxBindValues));
         if (statements.length === 1) {
             return this.runUpsert(entity, conflictPaths, payload);
         }
@@ -459,31 +433,41 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         // than one statement; `transaction` is re-entrant, so this is free inside a caller's own.
         return this.transaction(async () => {
             let changes = 0;
-            const ids = [];
-            for (const statement of statements) {
-                const result = await this.runUpsert(entity, conflictPaths, statement);
-                changes += result.changes ?? 0;
-                if (result.ids) {
-                    ids.push(...result.ids);
+            // Placed by index, since grouping by shape reorders the rows. A statement reporting fewer ids
+            // than it wrote places none.
+            const ids = new Array(payload.length);
+            for (const indexes of statements) {
+                const { changes: written = 0, ids: reported } = await this.runUpsert(entity, conflictPaths, indexes.map((index) => payload[index]));
+                changes += written;
+                if (reported?.length === indexes.length) {
+                    for (let position = 0; position < indexes.length; position++) {
+                        ids[indexes[position]] = reported[position];
+                    }
                 }
             }
-            // No `created`/`firstId`: both speak for a single statement, and there were several.
-            return ids.length ? { changes, ids } : { changes };
+            // No `created`: it speaks for a single statement, and there were several.
+            return { changes, ids };
         });
     }
     async runUpsert(entity, conflictPaths, payload) {
+        const meta = getMeta(entity);
+        // Asked first: the statement fills an `onInsert` key into these rows whether it inserts them or not.
+        const unnamed = meta.ids.length === 1 && payload.some((row) => !namesKey(meta, row));
         const ctx = this.dialect.createContext();
         this.dialect.upsert(ctx, entity, conflictPaths, payload);
         const result = await this.run(ctx.sql, ctx.values);
-        // On a `firstId` dialect (MySQL: no `RETURNING`), a multi-row upsert's `affectedRows` is a
-        // per-row weighted sum (1=insert, 2=update, 0=no-op), not a row count, so `buildUpdateResult`'s
-        // header-derived `ids`/`firstId`/`created` can't be trusted the moment more than one row is
-        // involved (verified: a 1-insert-1-update batch reports `changes: 3`, which would otherwise
-        // infer 3 sequential ids for only 2 real rows). A single-row batch (`upsertOne`) is unambiguous.
-        if (this.dialect.insertIdSource !== 'returning' && payload.length > 1) {
-            return { changes: result.changes };
-        }
-        return result;
+        const ordered = payload.length === 1 || (this.dialect.insertIdSource === 'returning' && this.dialect.upsertReturningOrdered);
+        if (ordered && result.ids?.length === payload.length) {
+            return result;
+        }
+        // The statement's ids name its rows only in order and for every one. A MySQL batch reports a
+        // weighted count (1=insert, 2=update) instead, CockroachDB and SQL Server answer out of order, and
+        // `DO NOTHING` skips rows, so there the ids are read back by the conflict columns.
+        const { changes } = result;
+        const created = payload.length === 1 ? result.created : undefined;
+        return unnamed
+            ? { changes, created, ids: await this.idsByConflict(entity, conflictPaths, payload) }
+            : { changes, created };
     }
     async internalDeleteMany(entity, q, opts) {
         const meta = getMeta(entity);
@@ -507,7 +491,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/schema/schemaASTBuilder.js

@@ -7,7 +7,7 @@
  */
 import { getMeta, soleIdOf } from '../entity/metadata/definition.js';
 import { ddlText } from '../util/ddlExpression.util.js';
-import { computedExpression, isInlinedExpression } from '../util/field.util.js';
+import { isInlinedExpression } from '../util/field.util.js';
 import { isSoleIdField } from '../util/field.util.js';
 import { isAutoIncrement } from '../util/field.util.js';
 import { derivedForeignKeyName, derivedIndexName, qualifyName } from '../util/sql.util.js';
@@ -101,7 +101,7 @@ function addTableFromEntity(ctx, meta) {
             isPrimaryKey,
             isAutoIncrement: isAutoIncrement(field, isSoleKey),
             isUnique: field.unique ?? false,
-            generatedAs: ddlText(computedExpression(field), `the computed column '${columnName}'`),
+            generatedAs: ddlText(field.computed, `the computed column '${columnName}'`),
             comment: field.comment,
             enum: field.enum,
             table,
@@ -202,16 +202,16 @@ function addIndexesFromEntity(ctx, meta) {
         addCompositeIndex(ctx, table, meta, idxMeta);
     }
 }
-/**
- * One `@Index([...])`. Its entries keep the authored form (expression, prefix length, order) with
- * names resolved, so the generator renders exactly what was declared; `columns` is the resolvable
- * subset, which is what diffing and introspection compare.
- */
 /** An `include` column is named like any other, so a naming strategy has to reach it too. */
 function resolveIncludeColumn(ctx, meta, column) {
     const field = meta.fields[column];
     return field ? ctx.resolveColumnName(column, field) : column;
 }
+/**
+ * One `@Index([...])`. Its entries keep the authored form (expression, prefix length, order) with
+ * names resolved, so the generator renders exactly what was declared; `columns` is the resolvable
+ * subset, which is what diffing and introspection compare.
+ */
 function addCompositeIndex(ctx, table, meta, idxMeta) {
     // An entry survives if it is an expression (nothing to resolve) or names a column that exists;
     // an index left with none is dropped, the same as one naming only unknown columns always was.

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/entity.d.ts

@@ -359,11 +359,6 @@ export type FieldOptions<V = TsTypeOf<FieldType>> = {
      * @example `@Field({ type: String, enum: ['draft', 'paid'] as const })`
      */
     readonly enum?: EnumValues;
-    /**
-     * @deprecated Renamed to {@link FieldOptions.computed}, which also takes `stored`. `npx uql-codemod`
-     * rewrites it. Giving both throws.
-     */
-    readonly virtual?: QueryRaw;
     /**
      * An expression the database computes, rather than a value the caller writes. Never part of an
      * insert or update either way.
@@ -818,12 +813,6 @@ export type EntityMeta<E> = {
     /** The revision `getMeta` last finalized, which is what makes finalizing idempotent and re-entrant. */
     processedAt?: number;
 };
-/**
- * Configurable options for an entity (`@Entity()` / `defineEntity`).
- *
- * Optional `fields`, `relations`, `indexes`, and `hooks` register metadata in one call for
- * decorator-free setups. Omit them when using `@Field` / `@ManyToOne` / etc.
- */
 /**
  * A table-level `CHECK`. The expression is `raw` with no interpolation, like an index expression:
  * this is DDL, so there is no placeholder a bound value could go into.
@@ -843,6 +832,12 @@ export type EntityMembers = {
     readonly relations?: Readonly<Record<string, RelationOptions | undefined>>;
     readonly hooks?: Readonly<Partial<Record<HookEvent, readonly string[]>>>;
 };
+/**
+ * Configurable options for an entity (`@Entity()` / `defineEntity`).
+ *
+ * Optional `fields`, `relations`, `indexes`, and `hooks` register metadata in one call for
+ * decorator-free setups. Omit them when using `@Field` / `@ManyToOne` / etc.
+ */
 export type EntityOptions<E = unknown> = {
     readonly name?: string;
     /**

package/dist/type/migration.d.ts

@@ -372,9 +372,6 @@ export interface SchemaIntrospector {
      * the database side never reports it, and no migration can close the gap.
      */
     readonly indexFacets: ReadonlySet<IndexFacet>;
-    /**
-     * Introspect entire database schema and return SchemaAST.
-     */
     /** The whole database, or just the tables named. Names nothing matches are left out. */
     introspect(tables?: readonly string[]): Promise<SchemaAST>;
     /**

package/dist/type/query.d.ts

@@ -59,17 +59,17 @@ export type QueryExclude<E> = QuerySelect<E>;
 export type QueryPopulate<E> = {
     [K in RelationKey<E>]?: BooleanLike | QueryPopulateRelationOptions<E[K]>;
 };
+/**
+ * The key a read carries its relation tallies under. One spelling for the type and the runtime that
+ * fills it: they sit in different modules, so a drift would type-check and answer `undefined`.
+ */
+export declare const COUNT_RESULT_KEY = "_count";
 /**
  * How many rows each named relation holds per parent, `true` for all of them or a filter to narrow
  * which ones count. One statement per relation named here, batched over every parent at once, so it
  * stays flat however many rows the read returned. Comes back under `_count`, which keeps it clear of
  * a relation of the same name that `$populate` filled with rows.
  */
-/**
- * The key a read carries its relation tallies under. One spelling for the type and the runtime that
- * fills it: they sit in different modules, so a drift would type-check and answer `undefined`.
- */
-export declare const COUNT_RESULT_KEY = "_count";
 export type QueryCount<E> = {
     [K in ToManyRelationKey<E>]?: BooleanLike | QueryFilter<RelationTarget<E[K]>>;
 };
@@ -141,9 +141,16 @@ type ToOneRelationKey<E> = {
 }[RelationKey<E>];
 /** The relation names a parent holds many rows of, which a populated query fills with a list. */
 type ToManyRelationKey<E> = Exclude<RelationKey<E>, ToOneRelationKey<E>>;
+/**
+ * Ordering parents by how many rows a to-many relation holds - "the ten users with the most posts".
+ * The tally is computed per parent as a correlated count, never by loading the rows.
+ */
+export type QuerySortByCount = {
+    $count: QuerySortDirection;
+};
 /**
  * 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.
@@ -153,13 +160,6 @@ type ToManyRelationKey<E> = Exclude<RelationKey<E>, ToOneRelationKey<E>>;
  * against an intersection is repeated per constituent, which made this the single most expensive
  * type in the package to check.
  */
-/**
- * Ordering parents by how many rows a to-many relation holds - "the ten users with the most posts".
- * The tally is computed per parent as a correlated count, never by loading the rows.
- */
-export type QuerySortByCount = {
-    $count: QuerySortDirection;
-};
 export type QuerySortMap<E, Vector extends boolean = true> = {
     [K in FieldKey<E> | JsonFieldPaths<E> | RelationKey<E>]?: K extends RelationKey<E> ? IsMany<E[K]> extends true ? QuerySortByCount : QuerySortMap<RelationTarget<E[K]>, false> : K extends FieldKey<E> ? Vector extends true ? NonNullable<E[K]> extends readonly number[] ? QuerySortValue : QuerySortDirection : QuerySortDirection : QuerySortDirection;
 };

package/dist/type/query.js

@@ -1,9 +1,3 @@
-/**
- * How many rows each named relation holds per parent, `true` for all of them or a filter to narrow
- * which ones count. One statement per relation named here, batched over every parent at once, so it
- * stays flat however many rows the read returned. Comes back under `_count`, which keeps it clear of
- * a relation of the same name that `$populate` filled with rows.
- */
 /**
  * The key a read carries its relation tallies under. One spelling for the type and the runtime that
  * fills it: they sit in different modules, so a drift would type-check and answer `undefined`.

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/universalQuerier.d.ts

@@ -126,7 +126,7 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * on MySQL/SQLite they are inferred from the driver header, which is only reliable for
      * auto-increment keys in batches without explicit IDs - otherwise those entries are
      * `undefined` rather than potentially wrong values. A composite key is never one the statement
-     * reports, so those rows are named from the payload instead.
+     * reports, so those rows are named as written, `onInsert` columns included.
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the IDs
@@ -137,7 +137,7 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * @param entity the entity to persist on
      * @param conflictPaths the keys to use for the unique search
      * @param payload the data to be persisted
-     * @return operation metadata; see {@link QueryUpdateResult}
+     * @return the id and whether it was created; see {@link QueryUpsertOneResult}
      */
     upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpsertOneResult<E>>;
     /**
@@ -145,7 +145,7 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * @param entity the entity to persist on
      * @param conflictPaths the keys to use for the unique search
      * @param payload the data to be persisted
-     * @return operation metadata; see {@link QueryUpdateResult}
+     * @return the ids, in payload order; see {@link QueryUpsertManyResult}
      */
     upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpsertManyResult<E>>;
     /**

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, type UpdatePayload } 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`. */
@@ -35,7 +35,8 @@ export declare function getSoftDeleteValue(field: FieldOptions): string | number
 }[] | readonly number[] | Uint8Array<ArrayBufferLike> | {
     readonly __json?: never;
 };
-export declare function fillOnFields<E>(meta: EntityMeta<E>, payload: EntityData<E> | EntityData<E>[], callbackKey: CallbackKey): EntityData<E>[];
+/** Fills each field `callbackKey` generates on `payload` in place, where the caller left it unset. */
+export declare function fillOnFields<E, R extends EntityData<E> | UpdatePayload<E>>(meta: EntityMeta<E>, payload: R | R[], callbackKey: CallbackKey): R[];
 /**
  * The relation keys present in `payload` whose cascade configuration allows `action`. Only
  * `payload`'s keys are read, so any keys-bearing object works (an entity, an update payload,
@@ -90,13 +91,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 +116,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.
  */