uql-orm 0.51.0 → 0.53.0

package/dist/schema/canonicalType.js

@@ -44,6 +44,9 @@ const SQL_TO_CANONICAL = {
     char: { category: 'string' },
     character: { category: 'string' },
     varchar: { category: 'string' },
+    varchar2: { category: 'string' },
+    nvarchar: { category: 'string' },
+    nchar: { category: 'string' },
     'character varying': { category: 'string' },
     text: { category: 'string', size: 'small' },
     tinytext: { category: 'string', size: 'tiny' },
@@ -64,11 +67,15 @@ const SQL_TO_CANONICAL = {
     'timestamp with time zone': { category: 'timestamp', withTimezone: true },
     timestamptz: { category: 'timestamp', withTimezone: true },
     datetime: { category: 'timestamp' },
+    datetime2: { category: 'timestamp' },
+    smalldatetime: { category: 'timestamp' },
+    datetimeoffset: { category: 'timestamp', withTimezone: true },
     // === JSON ===
     json: { category: 'json' },
     jsonb: { category: 'json' },
     // === UUID ===
     uuid: { category: 'uuid' },
+    uniqueidentifier: { category: 'uuid' },
     // === Binary ===
     blob: { category: 'blob' },
     bytea: { category: 'blob' },
@@ -77,15 +84,16 @@ const SQL_TO_CANONICAL = {
     tinyblob: { category: 'blob', size: 'tiny' },
     mediumblob: { category: 'blob', size: 'medium' },
     longblob: { category: 'blob', size: 'big' },
+    image: { category: 'blob', size: 'big' },
     // === Vector (for AI/embeddings) ===
     vector: { category: 'vector' },
     halfvec: { category: 'halfvec' },
     sparsevec: { category: 'sparsevec' },
 };
 /**
- * pgvector is the only engine with three vector column types, so every other dialect maps all three
- * canonical categories onto the single type it does have (see `hasNarrowVectorTypes` on the dialect, the
- * dialect-side half of the same fact).
+ * pgvector is the only engine with three vector column types, so every other engine maps all three
+ * canonical categories onto the single type it does have (see `hasNarrowVectorTypes` on the dialect,
+ * the dialect-side half of the same fact).
  */
 function withVectorType(scalars, vector) {
     return { ...scalars, vector, halfvec: vector, sparsevec: vector };
@@ -103,11 +111,9 @@ const PG_SCALAR_MAP = {
     uuid: 'UUID',
     blob: 'BYTEA',
 };
-const PG_TYPE_MAP = {
-    ...PG_SCALAR_MAP,
-    vector: 'VECTOR',
-    halfvec: 'HALFVEC',
-    sparsevec: 'SPARSEVEC',
+const PG_SIZES = {
+    integer: { tiny: 'SMALLINT', small: 'SMALLINT', medium: 'INTEGER', big: 'BIGINT' },
+    float: { tiny: 'REAL', small: 'REAL', medium: 'DOUBLE PRECISION', big: 'DOUBLE PRECISION' },
 };
 const MYSQL_SCALAR_MAP = {
     integer: 'INT',
@@ -122,6 +128,13 @@ const MYSQL_SCALAR_MAP = {
     uuid: 'CHAR(36)',
     blob: 'BLOB',
 };
+/** MariaDB is a MySQL fork and spells every one of these the same way, so both take the one map. */
+const MYSQL_SIZES = {
+    integer: { tiny: 'TINYINT', small: 'SMALLINT', medium: 'MEDIUMINT', big: 'BIGINT' },
+    float: { tiny: 'FLOAT', small: 'FLOAT', medium: 'DOUBLE', big: 'DOUBLE' },
+    string: { tiny: 'TINYTEXT', small: 'TEXT', medium: 'MEDIUMTEXT', big: 'LONGTEXT' },
+    blob: { tiny: 'TINYBLOB', small: 'BLOB', medium: 'MEDIUMBLOB', big: 'LONGBLOB' },
+};
 const SQLITE_SCALAR_MAP = {
     integer: 'INTEGER',
     float: 'REAL',
@@ -135,6 +148,35 @@ const SQLITE_SCALAR_MAP = {
     uuid: 'TEXT',
     blob: 'BLOB',
 };
+/**
+ * Every string column is `NVARCHAR`: `VARCHAR` is a codepage type on SQL Server and silently destroys
+ * anything outside it on write. UQL never exposes the choice, so there is nothing to weigh per column.
+ */
+const MSSQL_SCALAR_MAP = {
+    integer: 'INT',
+    float: 'REAL',
+    decimal: 'DECIMAL',
+    string: 'NVARCHAR',
+    boolean: 'BIT',
+    date: 'DATE',
+    time: 'TIME',
+    timestamp: 'DATETIME2',
+    json: 'NVARCHAR(MAX)',
+    uuid: 'UNIQUEIDENTIFIER',
+    blob: 'VARBINARY(MAX)',
+};
+/** `FLOAT` is eight bytes here and `REAL` four - the opposite of the MySQL family's spelling. */
+const MSSQL_SIZES = {
+    integer: { tiny: 'TINYINT', small: 'SMALLINT', medium: 'INT', big: 'BIGINT' },
+    float: { tiny: 'REAL', small: 'REAL', medium: 'FLOAT', big: 'FLOAT' },
+    string: { tiny: 'NVARCHAR(255)', small: 'NVARCHAR(MAX)', medium: 'NVARCHAR(MAX)', big: 'NVARCHAR(MAX)' },
+    blob: {
+        tiny: 'VARBINARY(255)',
+        small: 'VARBINARY(MAX)',
+        medium: 'VARBINARY(MAX)',
+        big: 'VARBINARY(MAX)',
+    },
+};
 /** MongoDB uses BSON types, not SQL types. These are placeholders for compatibility. */
 const MONGO_SCALAR_MAP = {
     integer: 'int',
@@ -149,73 +191,31 @@ const MONGO_SCALAR_MAP = {
     uuid: 'binData',
     blob: 'binData',
 };
-/** Every engine's scalars, and the one spelling it gives all three vector widths. */
-const CANONICAL_TO_SQL = {
-    postgres: PG_TYPE_MAP,
+/** Every engine's spelling of the canonical types. A new engine is one entry here and nothing else. */
+const ENGINE_TYPES = {
+    postgres: {
+        scalars: { ...PG_SCALAR_MAP, vector: 'VECTOR', halfvec: 'HALFVEC', sparsevec: 'SPARSEVEC' },
+        sizes: PG_SIZES,
+    },
     // CockroachDB's VECTOR is native, no extension needed.
-    cockroachdb: withVectorType(PG_SCALAR_MAP, 'VECTOR'),
+    cockroachdb: { scalars: withVectorType(PG_SCALAR_MAP, 'VECTOR'), sizes: PG_SIZES },
     // MySQL does have a `VECTOR` type (26.7), but no distance function outside HeatWave and no vector
     // index, so JSON keeps the column queryable with the JSON operators and needs no conversion.
-    mysql: withVectorType(MYSQL_SCALAR_MAP, 'JSON'),
-    mariadb: withVectorType(MYSQL_SCALAR_MAP, 'VECTOR'),
-    sqlite: withVectorType(SQLITE_SCALAR_MAP, 'TEXT'),
-    mongodb: withVectorType(MONGO_SCALAR_MAP, 'array'),
-};
-/**
- * Size variant modifiers for SQL types.
- */
-const PG_SIZE_MODIFIERS = {
-    integer: {
-        tiny: 'SMALLINT',
-        small: 'SMALLINT',
-        medium: 'INTEGER',
-        big: 'BIGINT',
-    },
-    float: {
-        tiny: 'REAL',
-        small: 'REAL',
-        medium: 'DOUBLE PRECISION',
-        big: 'DOUBLE PRECISION',
-    },
-};
-/**
- * MariaDB is a MySQL fork and spells every one of these the same way, so both take the one map.
- * Listed per-dialect, MariaDB's had only `integer`: a `double` column was created `FLOAT` there, four
- * bytes where the entity asked for eight, and a `big` string or blob lost its `LONG` prefix.
- */
-const MYSQL_SIZE_MODIFIERS = {
-    integer: {
-        tiny: 'TINYINT',
-        small: 'SMALLINT',
-        medium: 'MEDIUMINT',
-        big: 'BIGINT',
+    mysql: {
+        scalars: withVectorType(MYSQL_SCALAR_MAP, 'JSON'),
+        sizes: MYSQL_SIZES,
+        decimal: { precision: 10, scale: 2 },
     },
-    float: {
-        tiny: 'FLOAT',
-        small: 'FLOAT',
-        medium: 'DOUBLE',
-        big: 'DOUBLE',
+    mariadb: {
+        scalars: withVectorType(MYSQL_SCALAR_MAP, 'VECTOR'),
+        sizes: MYSQL_SIZES,
+        decimal: { precision: 10, scale: 2 },
     },
-    string: {
-        tiny: 'TINYTEXT',
-        small: 'TEXT',
-        medium: 'MEDIUMTEXT',
-        big: 'LONGTEXT',
-    },
-    blob: {
-        tiny: 'TINYBLOB',
-        small: 'BLOB',
-        medium: 'MEDIUMBLOB',
-        big: 'LONGBLOB',
-    },
-};
-const SIZE_MODIFIERS = {
-    postgres: PG_SIZE_MODIFIERS,
-    cockroachdb: PG_SIZE_MODIFIERS,
-    mysql: MYSQL_SIZE_MODIFIERS,
-    sqlite: {}, // SQLite uses affinity, no size modifiers
-    mariadb: MYSQL_SIZE_MODIFIERS,
-    mongodb: {},
+    // SQLite uses affinity, so no size variants.
+    sqlite: { scalars: withVectorType(SQLITE_SCALAR_MAP, 'TEXT') },
+    // 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') },
 };
 /**
  * Maps canonical types to TypeScript types for entity generation.
@@ -317,61 +317,44 @@ export function canonicalColumnType(sqlType, reported = {}) {
 export function canonicalToSql(type, dialect) {
     if (type.raw)
         return type.raw;
-    const dialectName = dialect.dialectName;
-    let sqlType = getBaseSqlType(type, dialectName);
-    if (type.category === 'string') {
-        sqlType = formatStringSqlType(type, dialect);
+    const engine = ENGINE_TYPES[dialect.dialectName];
+    const { features } = dialect;
+    // A `size` the engine spells out wins outright; anything else falls through to the rules below.
+    // `TEXT` canonicalizes to `size: 'small'`, so a string counts as unsized only where the engine
+    // declares no variant for it, which is how Postgres reaches `TEXT` rather than its base `VARCHAR`.
+    const sized = engine.sizes?.[type.category]?.[type.size];
+    let sqlType = sized ?? engine.scalars[type.category];
+    if (type.category === 'string' && !sized) {
+        sqlType = formatStringSqlType(type, engine.scalars.string, features.stringSizing);
     }
     else if (type.category === 'decimal') {
-        sqlType = formatDecimalSqlType(type, dialectName, sqlType);
+        sqlType = formatDecimalSqlType(type, engine.decimal, sqlType);
     }
-    else if (isVectorCategory(type.category) && type.length && dialect.features.vectorSupportsLength) {
+    else if (isVectorCategory(type.category) && type.length && features.vectorSupportsLength) {
         sqlType = `${sqlType}(${type.length})`;
     }
-    if (type.category === 'timestamp' && type.withTimezone && dialect.features.supportsTimestamptz) {
+    if (type.category === 'timestamp' && type.withTimezone && features.supportsTimestamptz) {
         sqlType = 'TIMESTAMPTZ';
     }
-    if (type.unsigned && (dialectName === 'mysql' || dialectName === 'mariadb')) {
-        sqlType = `${sqlType} UNSIGNED`;
-    }
-    return sqlType;
+    return type.unsigned && features.supportsUnsigned ? `${sqlType} UNSIGNED` : sqlType;
 }
-function getBaseSqlType(type, dialect) {
-    let sqlType = CANONICAL_TO_SQL[dialect][type.category];
-    if (type.size) {
-        const sizeMap = SIZE_MODIFIERS[dialect][type.category];
-        if (sizeMap?.[type.size]) {
-            sqlType = sizeMap[type.size];
-        }
+/** See {@link EngineFeatures.stringSizing} for what each mode means. */
+function formatStringSqlType(type, base, sizing) {
+    if (sizing === 'text') {
+        return base;
     }
-    return sqlType;
-}
-function formatStringSqlType(type, dialect) {
-    const { dialectName, features } = dialect;
-    if (dialectName === 'sqlite')
-        return 'TEXT';
-    if (features.defaultStringAsText)
-        return type.length ? `VARCHAR(${type.length})` : 'TEXT';
-    if (dialectName === 'mysql' || dialectName === 'mariadb') {
-        if (type.size === 'tiny')
-            return 'TINYTEXT';
-        if (type.size === 'small')
-            return 'TEXT';
-        if (type.size === 'medium')
-            return 'MEDIUMTEXT';
-        if (type.size === 'big')
-            return 'LONGTEXT';
-        return type.length ? `VARCHAR(${type.length})` : 'VARCHAR(255)';
+    if (type.length) {
+        return `${base}(${type.length})`;
     }
-    return type.length ? `VARCHAR(${type.length})` : 'VARCHAR(255)';
+    return sizing === 'bounded-text' ? 'TEXT' : `${base}(255)`;
 }
-function formatDecimalSqlType(type, dialect, baseType) {
-    const p = type.precision ?? (dialect === 'mysql' || dialect === 'mariadb' ? 10 : undefined);
-    const s = type.scale ?? (dialect === 'mysql' || dialect === 'mariadb' ? 2 : undefined);
-    if (p !== undefined) {
-        return s !== undefined ? `${baseType}(${p}, ${s})` : `${baseType}(${p})`;
+function formatDecimalSqlType(type, fallback, baseType) {
+    const p = type.precision ?? fallback?.precision;
+    const s = type.scale ?? fallback?.scale;
+    if (p === undefined) {
+        return baseType;
     }
-    return baseType;
+    return s === undefined ? `${baseType}(${p})` : `${baseType}(${p}, ${s})`;
 }
 /**
  * Convert a canonical type to a TypeScript type string.

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
@@ -19,7 +18,9 @@ export class SqliteDialect extends AbstractSqlDialect {
         vectorIndexRequiresNotNull: false,
         vectorSupportsLength: false,
         supportsTimestamptz: false,
-        defaultStringAsText: true,
+        stringSizing: 'text',
+        supportsUnsigned: false,
+        serverSideCursors: false,
     };
     dialectName = 'sqlite';
     escapeIdChar = '`';

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
@@ -128,8 +127,28 @@ export interface EngineFeatures {
     readonly vectorSupportsLength: boolean;
     /** Whether the dialect natively supports the TIMESTAMPTZ alias/type. */
     readonly supportsTimestamptz: boolean;
-    /** Whether the dialect defaults to TEXT for strings when no length is specified (e.g. Postgres). */
-    readonly defaultStringAsText: boolean;
+    /**
+     * How a `string` column is sized: `text` is always the unbounded type whatever length was asked
+     * for (SQLite, whose affinity makes a bound meaningless), `bounded-text` takes the bound when there
+     * is one and the unbounded type otherwise (the Postgres family), `varchar` is always bounded and
+     * falls back to 255 (the MySQL family, SQL Server).
+     *
+     * Three-way for the reason {@link commentSyntax} is: a boolean puts SQLite and Postgres on the
+     * same branch, and they need different answers.
+     */
+    readonly stringSizing: 'text' | 'bounded-text' | 'varchar';
+    /** Whether the engine has unsigned integers, so `@Field({ unsigned: true })` reaches the column. */
+    readonly supportsUnsigned: 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
+     * `postgres/pgCursorStream.ts`. True across the Postgres wire family, whose spelling that helper
+     * speaks; SQL Server and Oracle have cursors of their own but not this syntax.
+     *
+     * The node-`pg` family reports `true` and goes on using `pg-query-stream`: the flag says the engine
+     * has cursors, not that the driver needs them.
+     */
+    readonly serverSideCursors: boolean;
 }
 export interface DialectFeatures extends EngineFeatures, DriverCapabilities {
 }
@@ -219,13 +238,13 @@ export interface QueryDialect {
 /**
  * Supported SQL dialect identifiers.
  */
-export type SqlDialectName = 'postgres' | 'cockroachdb' | 'mysql' | 'mariadb' | 'sqlite';
+export type SqlDialectName = 'postgres' | 'cockroachdb' | 'mysql' | 'mariadb' | 'sqlite' | 'mssql';
 /**
  * Minimal dialect interface exposing escapeIdChar for SQL operations
  */
 export interface SqlQueryDialect extends QueryDialect {
     /**
-     * The SQL dialect name (postgres, mysql, mariadb, sqlite).
+     * The SQL dialect name (postgres, mysql, mariadb, sqlite, mssql).
      */
     readonly dialectName: SqlDialectName;
     /**

package/dist/type/migratorDialect.d.ts

@@ -1,5 +1,5 @@
 import type { DialectName } from './querier.js';
-declare const KNOWN_MIGRATOR_DIALECTS: readonly ["postgres", "cockroachdb", "mysql", "mariadb", "sqlite", "mongodb"];
+declare const KNOWN_MIGRATOR_DIALECTS: readonly ["postgres", "cockroachdb", "mysql", "mariadb", "sqlite", "mssql", "mongodb"];
 export type KnownMigratorDialect = (typeof KNOWN_MIGRATOR_DIALECTS)[number];
 /**
  * Whether `d` is supported by built-in migrator introspection / schema generators.

package/dist/type/migratorDialect.js

@@ -4,6 +4,7 @@ const KNOWN_MIGRATOR_DIALECTS = [
     'mysql',
     'mariadb',
     'sqlite',
+    'mssql',
     'mongodb',
 ];
 /**

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