uql-orm 0.66.0 → 0.67.0

package/dist/type/queryRaw.js

@@ -11,14 +11,7 @@ export class QueryRaw {
     as(alias) {
         return new QueryRaw(this[RAW_VALUE], alias);
     }
-    /**
-     * Emit this expression into `opts.ctx`. How a raw value becomes SQL is the raw value's own
-     * business, which is what lets a `raw` tagged template resolve an interpolated fragment without
-     * the dialect having to expose a method for it.
-     *
-     * The alias is not emitted here: it names a `$select` projection, which writes it after the term,
-     * and anywhere else it would land mid-expression.
-     */
+    /** Writes the expression into `opts.ctx`. The alias is the projection's to write, after the term. */
     render(opts) {
         const emitted = this[RAW_VALUE](opts);
         if (typeof emitted === 'string' || (typeof emitted === 'number' && !Number.isNaN(emitted))) {

package/dist/type/queryWhere.d.ts

@@ -22,19 +22,9 @@ export type QueryTextSearchOptions<E> = {
     $config?: string;
 };
 /**
- * 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
- * (untyped `Json` payloads accept any `field.suffix` path with a permissive value). Relations are
- * filtered via nested typed objects; dotted relation paths are not supported (the dialects throw
- * for non-JSON dotted keys).
- *
- * Fields and relations share one mapped type over `K extends keyof E`, which keeps each key linked to
- * its property (see {@link QuerySelect}). JSON paths are not keys of `E`, so they are a second member,
- * and only where the entity has one: an empty member would switch off the weak-type check that
- * rejects `$where: 1`.
- *
- * 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.
+ * A filter by fields, JSON paths (typed by their payload) and relations, one mapped type over the
+ * entity's keys so each stays linked for rename. An object and nothing else, so a wrong value is
+ * reported on its key: ids go through `{ id: 1 }` or the by-id methods.
  */
 export type QueryWhere<E, K extends keyof E = FieldKey<E> | RelationKey<E>> = QueryWhereRootOperator<E> & {
     [P in K]?: P extends FieldKey<E> ? QueryWhereFieldValue<E[P]> : QueryWhere<RelationTarget<E[P]>> | QueryRelationSizeFilter;
@@ -103,29 +93,9 @@ export type QuerySizeComparisonOps = {
     [K in QueryHavingOp | '$between']?: NonNullable<QueryWhereFieldOperatorMap<number>[K]>;
 };
 /**
- * Filter by distance to a query vector: `$where`'s counterpart to `$sort`'s ranking, so "the closest
- * ten" and "everything closer than 0.35" stay separate asks.
- *
- * Bounded by {@link QueryOrderedOp} - what {@link QuerySizeComparisonOps} ranges over, minus
- * `$eq`/`$ne`. A distance is a float, so exact equality against one is a bug every time, where
- * `$size` compares an integer `COUNT`. No `$project` either: naming the distance is `$sort`'s job,
- * since the `SELECT` list is built from `$sort` alone and a `$near` nested inside an `$or` has no
- * business projecting a column.
- *
- * `$distance` is here for the same reason `$sort` has it: each clause states its own search
- * completely, so neither depends on the other. Omitted, it falls back to the field's declared metric,
- * which is where the metric belongs - beside the index it has to match. Naming a different one per
- * query mostly buys a full scan, since an ANN index is built for exactly one operator class.
- *
- * `$vector` is required, and repeating it beside a `$sort` that ranks by the same field is the point:
- * every other `$where` operator means the same thing wherever it appears, and inheriting one from a
- * sibling clause would make this the first whose validity depends on what else the query contains -
- * unfixable in the type, and carried into merged entity filters and `/http` payloads alike. Naming
- * the vector in a `const` is what removes the repetition, at the call site where it belongs.
- *
- * A `$near` carrying no bound is a `WHERE` that is always true. The dialect rejects that rather than
- * the type: `/http` casts client JSON straight to `Query`, so the check has to exist there anyway,
- * and an "at least one of these five" union would cost every caller worse errors for a second copy.
+ * Filter by distance to a vector, `{ $near: { $vector: v, $lt: 0.35 } }`: ordered bounds only, since a
+ * distance is a float. Each clause names its own `$vector`, and `$distance` falls back to the field's.
+ * One with no bound is refused at run time, where `/http` input is checked anyway.
  */
 export type QueryVectorNear = QueryVectorQuery & {
     [K in QueryOrderedOp]?: NonNullable<QueryWhereFieldOperatorMap<number>[K]>;
@@ -224,13 +194,7 @@ export type QueryWhereFieldOperatorMap<T> = {
      * @example { tags: { $all: ['typescript', 'orm'] } }
      */
     $all?: unknown extends T ? unknown[] : NonNullable<T> extends readonly (infer U)[] ? ExpandScalar<U>[] : never;
-    /**
-     * whether an array has the specified length.
-     * Accepts a number for exact match, or a comparison operator object for range queries.
-     * @example { roles: { $size: 3 } }
-     * @example { roles: { $size: { $gte: 2 } } }
-     * @example { roles: { $size: { $gt: 0, $lte: 5 } } }
-     */
+    /** whether an array has the given length, or one in range: `{ roles: { $size: { $gte: 2 } } }`. */
     $size?: number | QuerySizeComparisonOps;
     /**
      * whether an array contains at least one element matching all specified conditions.
@@ -292,11 +256,8 @@ type QueryOrderedOp = QueryCompareOp | keyof Pick<QueryWhereFieldOperatorMap<unk
  */
 type QueryVectorOp = keyof Pick<QueryWhereFieldOperatorMap<unknown>, '$near'>;
 /**
- * Operators applicable to every field type: equality, membership, negation, and null checks.
- *
- * @remarks This is a subtraction, not a list, so an operator added to
- * {@link QueryWhereFieldOperatorMap} without also being classified above lands here and is offered
- * on every field - `$near` on a `boolean`, say. Classify first, then add.
+ * The operators every field takes. A subtraction, so an operator added to the map without being
+ * classified above is offered on every field: classify it first.
  */
 type QueryCommonOp = Exclude<keyof QueryWhereFieldOperatorMap<unknown>, QueryStringOp | QueryArrayOp | QueryOrderedOp | QueryVectorOp>;
 /**
@@ -305,13 +266,8 @@ type QueryCommonOp = Exclude<keyof QueryWhereFieldOperatorMap<unknown>, QueryStr
  */
 type QueryAllowedOp<T> = QueryCommonOp | ([NonNullable<T>] extends [QueryComparableScalar] ? QueryOrderedOp : never) | ([NonNullable<T>] extends [string] ? QueryStringOp : never) | ([NonNullable<T>] extends [readonly number[] | Uint8Array] ? QueryVectorOp : never) | (IsMany<T> extends true ? QueryArrayOp : never);
 /**
- * Operators applicable to a field of type `T`: string operators require string fields, ordering
- * operators comparable fields, array operators array fields.
- *
- * Two shapes stay fully permissive, because neither says anything to check against: `unknown`
- * (untyped JSON dot-paths, erased dialect shapes), and a field typed as every scalar at once - the
- * column of a content type defined at runtime. Narrowing to what they share would leave a dynamic
- * row with equality alone, since no operator applies to a boolean and a blob both.
+ * The operators a field of type `T` takes. `unknown`, and a column typed as every scalar at once (a
+ * runtime-defined entity), take all of them, since nothing narrows what they hold.
  */
 export type QueryWhereFieldOperators<T> = unknown extends T ? QueryWhereFieldOperatorMap<T> : IsUntypedColumn<T> extends true ? QueryWhereFieldOperatorMap<T> : Pick<QueryWhereFieldOperatorMap<T>, QueryAllowedOp<T>>;
 /**
@@ -321,12 +277,8 @@ export type QueryWhereFieldOperators<T> = unknown extends T ? QueryWhereFieldOpe
  */
 type IsUntypedColumn<T> = [Scalar] extends [NonNullable<T>] ? true : false;
 /**
- * Value for a field comparison. A bare array is an implicit `$in` for scalar fields only:
- * on array-typed fields (e.g. a vector `number[]`) an array of arrays is ambiguous, so
- * membership there requires an explicit operator.
- *
- * `null` is accepted on a nullable field (an optional property is a nullable column), matching what
- * `$eq: null` already took.
+ * A field's filter value: the value, `null` where it is optional, a list as an implicit `$in` (not on
+ * an array field, where it would be ambiguous), or an operator map.
  */
 export type QueryWhereFieldValue<T> = T | (undefined extends T ? null : never) | (IsMany<T> extends true ? never : T[]) | QueryWhereFieldOperators<T> | QueryRaw;
 /**

package/dist/type/universalQuerier.d.ts

@@ -4,24 +4,11 @@ import type { QueryAggMap, QueryAggregate, QueryAggregateResult, QueryGroupMap }
 import type { Type } from './utility.js';
 import type { QuerierCountedResult, QuerierResult, QuerierTransport } from './wire.js';
 /**
- * The operations {@link UniversalQuerier} and `ClientQuerier` declare identically, written once and
- * instantiated per transport: `SharedQuerier<'server', QueryOptions>` against
- * `SharedQuerier<'client', RequestOptions, QueryOptions & RequestOptions>`. See {@link QuerierResult}
- * for how the return type follows `W`.
- *
- * @typeParam W - which side of the wire, picking each method's return type.
- * @typeParam O - the per-call options.
- * @typeParam DO - the delete methods' options, which the client also lets carry {@link QueryOptions}
- * (`hardDelete`, `filters`) since it has no other way to reach them.
+ * The operations the server and the browser client declare alike, per transport `W`, options `O`,
+ * and delete options `DO`, which on the client also carry the {@link QueryOptions} it cannot pass otherwise.
  */
 export interface SharedQuerier<W extends QuerierTransport, O, DO = O> {
-    /**
-     * obtains the record with the given primary key.
-     * @param entity the target entity
-     * @param id the primary key value
-     * @param q the additional criteria options
-     * @return the record
-     */
+    /** Find the record with the given primary key. */
     findOneById<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, id: EntityId<E>, q?: QueryOneProjected<E, S, V, X, P, C>, opts?: O): QuerierResult<W, QueryFindResult<E, S, V, X, P, C> | undefined>;
     /**
      * obtains the first record matching the given search parameters.
@@ -37,45 +24,15 @@ export interface SharedQuerier<W extends QuerierTransport, O, DO = O> {
      * @return the records
      */
     findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: O): QuerierResult<W, QueryFindResult<E, S, V, X, P, C>[]>;
-    /**
-     * obtains the records matching the given search parameters,
-     * also counts the number of matches ignoring pagination.
-     * @param entity the target entity
-     * @param q the criteria options
-     * @return the records and the count
-     */
+    /** Find the records matching the query, and count every match past its page. */
     findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: O): QuerierCountedResult<W, QueryFindResult<E, S, V, X, P, C>>;
-    /**
-     * counts the number of records matching the given filter, optionally paged - a `$skip`/`$limit`
-     * settles the matching rows first and counts them, rather than scanning every match.
-     * @param entity the target entity
-     * @param q the filter
-     * @return the count
-     */
+    /** Count the records matching the filter, or those a page of them takes. */
     count<E extends object>(entity: Type<E>, q?: QueryPage<E>, opts?: O): QuerierResult<W, number>;
-    /**
-     * whether any record matches the given filter - a count capped at one row, so the engine stops at
-     * the first match instead of scanning every other one.
-     * @param entity the target entity
-     * @param q the filter
-     * @return whether anything matched
-     */
+    /** Whether any record matches: a count capped at one row, so the engine stops at the first match. */
     exists<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: O): QuerierResult<W, boolean>;
-    /**
-     * updates a record partially.
-     * @param entity the entity to persist on
-     * @param id the primary key of the record to be updated
-     * @param payload the data to be persisted
-     * @return the number of affected records
-     */
+    /** Update the record with the given primary key; resolves to the number of affected rows. */
     updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdatePayload<E>, opts?: O): QuerierResult<W, number>;
-    /**
-     * updates many records partially.
-     * @param entity the entity to persist on
-     * @param q the criteria to look for the records
-     * @param payload the data to be persisted
-     * @return the number of affected records
-     */
+    /** Update the records matching the query; resolves to the number of affected rows. */
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: O): QuerierResult<W, number>;
     /**
      * delete or SoftDelete a record.
@@ -97,56 +54,21 @@ export interface SharedQuerier<W extends QuerierTransport, O, DO = O> {
  */
 export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions> {
     /**
-     * streams the records matching the given search parameters as an async iterable, each with the
-     * relations and counts `findMany` reads. Fires no lifecycle hooks, and holds one row at a time, for
-     * bulk reads (ETL, exports, migrations).
-     * @param entity the target entity
-     * @param q the criteria options
-     * @return an async iterable of records
+     * Stream the records matching the query one at a time, each with the relations and counts `findMany`
+     * reads, for bulk reads. Fires no lifecycle hooks.
      */
     findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P, C>>;
-    /**
-     * Insert a single record and return its ID (provided, `onInsert`-generated, or
-     * database-generated - see {@link UniversalQuerier.insertMany} for the exact semantics).
-     * Returns `undefined` only where the database cannot report one: MySQL, whose `LAST_INSERT_ID()`
-     * speaks for `AUTO_INCREMENT` columns alone and is left *stale* rather than cleared otherwise, so
-     * a non-auto-increment key the caller did not supply has no id to give and a header read would
-     * hand back an earlier row's. Every other backend uses `RETURNING` and is exact, SQLite included.
-     * @param entity the entity to persist on
-     * @param payload the data to be persisted
-     * @return the ID
-     */
+    /** Insert a record and resolve to its id. See {@link UniversalQuerier.insertMany}. */
     insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
     /**
-     * Insert multiple records in a single statement (auto-chunked when the batch exceeds the
-     * dialect's bind-parameter limit) and return their IDs in payload order.
-     *
-     * Provided IDs and client-generated ones (`@Id({ onInsert })`) are always returned as-is.
-     * Database-generated IDs are exact wherever the statement returns them, which is everywhere but
-     * MySQL: there 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 as written, `onInsert` columns included.
-     * @param entity the entity to persist on
-     * @param payload the data to be persisted
-     * @return the IDs
+     * Insert records in as few statements as the bind limit allows, resolving to their ids in payload order.
+     * Ids are exact everywhere but MySQL, which infers them from its header and reports `undefined` rather
+     * than a guess where it cannot: a batch naming some keys, or a key that is not `AUTO_INCREMENT`.
      */
     insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
-    /**
-     * Insert or update a record based on the conflict paths.
-     * @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 the id and whether it was created; see {@link QueryUpsertOneResult}
-     */
+    /** Insert or update a record by its conflict paths; resolves to its id and whether it was created. */
     upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpsertOneResult<E>>;
-    /**
-     * Insert or update many records based on the conflict paths.
-     * @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 the ids, in payload order; see {@link QueryUpsertManyResult}
-     */
+    /** Insert or update records by their conflict paths; resolves to their ids in payload order. */
     upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpsertManyResult<E>>;
     /**
      * insert or update a record.
@@ -176,17 +98,8 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      */
     aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     /**
-     * How many rows the engine's own statistics say the table holds, without reading one: Postgres'
-     * `pg_class.reltuples`, CockroachDB's table statistics, MySQL/MariaDB's `information_schema`,
-     * MongoDB's `estimatedDocumentCount`. For a table too big to {@link count} cheaply.
-     *
-     * The whole table, and only ever approximately. It takes no filter because none of those sources
-     * can answer one, which also puts soft-deleted rows and every entity `filters` inside the number.
-     * It is as stale as the last `ANALYZE`/autovacuum (Postgres reports nothing at all until the
-     * first one, which reads here as `0`), and a table SQLite can answer for does not exist - it
-     * throws there rather than quietly running the scan this exists to avoid.
-     * @param entity the target entity
-     * @return the estimated number of rows
+     * The table's row count as the engine's statistics state it, without reading a row: approximate, as
+     * stale as the last `ANALYZE`, and unfiltered, so soft-deleted rows count. SQLite has none and throws.
      */
     estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
 }

package/dist/type/utility.d.ts

@@ -4,14 +4,8 @@ export type MongoId = {
     toHexString: () => string;
 };
 /**
- * Every value type storable in an entity column. Superset of {@link QueryComparableScalar}
- * and {@link PrimaryKey}.
- *
- * `Uint8Array` rather than `Buffer`, which every `Buffer` still satisfies: naming an ambient Node
- * global here made the whole key-checking layer depend on `@types/node` being in scope. Without it
- * `Buffer` resolves to nothing, this union collapses to `any`, and `FieldKey` - the basis of
- * `$select`, `$where`, `$sort`, `@Index` and `defineEntity({ fields })` - silently stops checking
- * anything. A browser or edge project would have got no type safety and no error saying so.
+ * Every value a column may hold. `Uint8Array` rather than `Buffer`, which would need `@types/node` and
+ * collapse to `any` without it, switching every key check off.
  */
 export type Scalar = string | number | boolean | bigint | Date | RegExp | Uint8Array | MongoId;
 /**
@@ -23,16 +17,8 @@ export type QueryComparableScalar = string | number | bigint | Date;
  */
 export type PrimaryKey = string | number | bigint;
 /**
- * Marker type for JSON/JSONB fields.
- * Wrapping a field's TypeScript type with `Json<T>` ensures it is classified as a `FieldKey`
- * (not a `RelationKey`), enabling type-safe usage in `$where`, `$select`, and `$sort`. A column
- * holding a list of documents is `Json<T>[]`, also a field, whose dot-paths address the element.
- *
- * @example
- * ```ts
- * @Field({ type: 'jsonb' })
- * settings?: Json<{ isArchived?: boolean }>;
- * ```
+ * Brands a JSON field, `settings?: Json<{ isArchived?: boolean }>`, so it reads as a field rather than a
+ * relation; `Json<T>[]` is a list of documents.
  */
 export type Json<T = unknown> = T & {
     readonly __json?: never;
@@ -48,16 +34,18 @@ export type Writable<T> = {
     -readonly [K in keyof T]: T[K];
 };
 /**
- * `Omit`, fixed on three counts. Its key has to exist, where `Omit<T, K extends keyof any>` lets a
- * typo or a renamed property silently omit nothing. Being a homomorphic mapped type it distributes
- * over unions, where `Omit` intersects each member's keys and flattens a discriminated union (e.g.
- * `EntityIndexMeta`'s `type`/`distance` pairing) into one non-discriminated shape. And it removes
- * the key from types carrying an index signature, where `Exclude<keyof T, K>` widens back to
- * `string | number` and leaves the key in place.
+ * `Omit` whose key has to exist, which distributes over a union rather than flattening it, and removes
+ * a key from a type with an index signature.
  */
 export type Except<T, K extends keyof T> = {
     [P in keyof T as P extends K ? never : P]: T[P];
 };
+/**
+ * Each key of `K` mapped to `never`, so an intersection with it makes naming one a compile error;
+ * `unknown`, inert, when there are none. A captured type parameter needs it: TypeScript skips the
+ * excess-property check on one.
+ */
+export type RejectKeys<K> = [K] extends [never] ? unknown : Record<K & string, never>;
 export type Unpacked<T> = T extends readonly (infer U)[] ? U : T extends (...args: unknown[]) => infer U ? U : T extends Promise<infer U> ? U : T;
 /**
  * Whether the value a property holds is many rather than one: a to-many relation, a scalar array, a

package/dist/type/vector.d.ts

@@ -1,14 +1,7 @@
 import type { IndexType } from '../schema/types.js';
 /**
- * Distance metrics supported by vector similarity search.
- * - `cosine` - best for text/LLM embeddings (default)
- * - `l2` - Euclidean distance
- * - `inner` - inner (dot) product
- * - `l1` - Manhattan distance
- *
- * @remarks Hamming distance is absent because no engine can express it over a float vector column:
- * pgvector's `<~>`/`bit_hamming_ops` and sqlite-vec's `vec_distance_hamming` both require a *bit*
- * vector, which no field type maps to. It would be a value that compiles and always throws.
+ * A vector search's metric: `cosine` (the default), `l2`, `inner` product or `l1`. No hamming: every
+ * engine's takes a bit vector, which no field type maps to.
  */
 export type VectorDistance = 'cosine' | 'l2' | 'inner' | 'l1';
 /**
@@ -24,42 +17,19 @@ export interface QueryVectorQuery {
 }
 /** The keys that describe the search rather than bound it, so `$near`'s bounds are what is left. */
 export declare const VECTOR_QUERY_KEYS: readonly ["$vector", "$distance"];
-/**
- * Vector similarity search options - used inside `$sort` on vector fields.
- *
- * @example
- * ```ts
- * querier.findMany(Article, {
- *   $sort: { embedding: { $vector: queryVec } },
- *   $limit: 10,
- * });
- * ```
- */
+/** A vector search in `$sort`: `{ $sort: { embedding: { $vector: queryVec } }, $limit: 10 }`. */
 export interface QueryVectorSearch extends QueryVectorQuery {
     /** Project the computed distance as a named field in the result. */
     readonly $project?: string;
 }
 /**
- * Augments a row with the distance a vector-search `$sort.$project` computes, which is not
- * inferred. Wrap whatever the query returns - the entity, or a projected row:
- * ```ts
- * const results = (await querier.findMany(Article, {
- *   $sort: { embedding: { $vector: queryVec, $project: 'similarity' } },
- * })) as WithDistance<Article, 'similarity'>[];
- * ```
+ * A row with the distance a `$sort` `$project` names, which is not inferred:
+ * `(await querier.findMany(Article, q)) as WithDistance<Article, 'similarity'>[]`.
  */
 export type WithDistance<E, K extends string = '_distance'> = E & Record<K, number>;
 /**
- * How one dialect spells one distance metric. Two shapes exist across engines - an infix operator
- * (`"col" <=> $1`, pgvector) or a function call (`VEC_DISTANCE_COSINE(col, ?)`, MariaDB and the
- * SQLite family) - so they are one discriminated map rather than two parallel ones. That is what
- * lets a single `appendVectorSort` serve every engine, and makes the map's key set the one answer
- * to "does this dialect have this metric".
- *
- * `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. `metricArg` is for the engine with one function
- * taking the metric by name: SQL Server's `VECTOR_DISTANCE('cosine', a, b)`.
+ * How a dialect spells a metric: an operator with the operator class an index names from it, or a
+ * function, `metricArg` where it takes the metric by name. One map, so its keys say which metrics exist.
  */
 export type VectorMetric = {
     readonly op: string;
@@ -72,7 +42,7 @@ export type VectorMetric = {
 export type VectorOperatorMetric = Extract<VectorMetric, {
     op: string;
 }>;
-/** Every dialect words this the same, and one of them used to throw a bare `Error` for it. */
+/** The error every dialect throws for a metric it lacks. */
 export declare function unsupportedVectorMetric(dialectName: string, distance: VectorDistance, indexName?: string): TypeError;
 /**
  * Vector-specific tuning options shared by `@Index` decorator, entity metadata, and migration schema.

package/dist/type/vector.js

@@ -1,6 +1,6 @@
 /** The keys that describe the search rather than bound it, so `$near`'s bounds are what is left. */
 export const VECTOR_QUERY_KEYS = ['$vector', '$distance'];
-/** Every dialect words this the same, and one of them used to throw a bare `Error` for it. */
+/** The error every dialect throws for a metric it lacks. */
 export function unsupportedVectorMetric(dialectName, distance, indexName) {
     const where = indexName === undefined ? '' : ` (index "${indexName}")`;
     return new TypeError(`${dialectName} does not support vector distance metric: ${distance}${where}`);

package/dist/type/wire.d.ts

@@ -17,11 +17,8 @@ export type RequestCountedSuccessResponse<E> = RequestSuccessResponse<E> & {
  */
 export type QuerierTransport = 'server' | 'client';
 /**
- * A querier method's result on the given transport, so one signature serves both:
- * `QuerierResult<'server', User[]>` is `Promise<User[]>` and `QuerierResult<'client', User[]>` is
- * `Promise<RequestSuccessResponse<User[]>>`. Indexing a map by the transport is what stands in for
- * the higher-kinded wrapper TypeScript cannot express, and it resolves away: errors and hovers show
- * the `Promise<User[]>` it picked, never this indirection.
+ * A querier method's result on a transport: `Promise<User[]>` on the server, the response envelope on
+ * the client. A map indexed by the transport, which resolves away in hovers.
  */
 export type QuerierResult<W extends QuerierTransport, T> = {
     server: Promise<T>;

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

@@ -1,7 +1,7 @@
 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 QueryTextSearchOptions, 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`. */
+/** The keys of `payload` a write persists as columns. */
+export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E> | UpdatePayload<E>, callbackKey: CallbackKey): FieldKey<E>[];
 /**
  * The insertable keys `record` itself carries, as a string, for grouping rows by the statement they
  * can share. Only the row's own keys: the `onInsert` columns {@link getInsertFieldKeys} appends are a
@@ -9,16 +9,8 @@ export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityD
  */
 export declare function insertShapeOf<E>(meta: EntityMeta<E>, record: EntityData<E>): string;
 /**
- * Resolves the columns of an INSERT statement: the union of the persistable fields provided by
- * any record (in first-seen order), plus every `onInsert` field. Records missing one of these
- * columns insert its database default.
- *
- * The column list is seeded from the first record, then extended by every other record's
- * not-yet-seen columns - a no-op scan for a homogeneous batch (every record the same shape).
- *
- * `onInsert` fields are always included so the column set is stable whether or not the caller
- * has run {@link fillOnFields} first (it stamps them on every record, but the querier's
- * chunk-size estimate inspects the raw payload).
+ * An insert's columns: every record's writable fields in first-seen order, plus every `onInsert` field,
+ * whether or not it was filled yet. A record missing one writes its default.
  */
 export declare function getInsertFieldKeys<E>(meta: EntityMeta<E>, payloads: EntityData<E>[]): FieldKey<E>[];
 export declare function getFieldCallbackValue(val: OnFieldCallback): string | number | bigint | boolean | Date | QueryRaw | readonly {
@@ -104,17 +96,9 @@ export declare function assertWhere<E>(meta: EntityMeta<E>, where: unknown): voi
 /** 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'];
 /**
- * Returns a new `$where` map with every active entity filter's condition merged in, resolving
- * parameterized conditions against the explicit or ambient {@link UqlContext}. Never mutates the input.
- *
- * Convenience filters are active by default (unless `opts.filters === false` or bypassed by name), and
- * their keys are applied only when absent from the map, so an explicit `$where` on that key opts out.
- *
- * `security` filters are always active (bypass is ignored) and AND-merged, so a client `$where` on the
- * same field can't override them. A security condition that returns `undefined` fails the query closed
- * (throws {@link UqlSecurityError}) unless its `onMissing` is `skip`; one that returns an empty object
- * (`{}`) 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).
+ * `$where` with the entity's active filters merged in, against the ambient {@link UqlContext}. A convenience
+ * filter yields to a `$where` on its key; a `security` one is always ANDed, and throws where its condition
+ * resolves to nothing, unless `onMissing: 'skip'`.
  */
 export declare function applyFilters<E>(meta: EntityMeta<E>, whereMap: QueryWhere<E>, opts?: QueryOptions): QueryWhere<E>;
 /**
@@ -132,10 +116,8 @@ export type ParsedGroupEntry = {
     readonly distinct: boolean;
 };
 /**
- * The `$size` of a relation condition (`{ comments: { $size: { $gte: 2 } } }`), or `undefined` when the
- * condition constrains the target's fields instead. Shared so every dialect agrees on which of the two
- * a relation key means, and so the ambiguous mix fails loudly: `{ $size: 2, name: 'x' }` used to fall
- * through to field filtering and emit a condition on a `$size` *column*.
+ * The `$size` of a relation condition, `{ comments: { $size: { $gte: 2 } } }`, or `undefined` where it
+ * filters the target's fields; a mix of the two, `{ $size: 2, name: 'x' }`, is refused.
  */
 export declare function parseRelationSize(val: unknown): number | QuerySizeComparisonOps | undefined;
 /**

package/dist/util/dialect.util.js

@@ -4,6 +4,7 @@ import { QueryRaw, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index
 import { VECTOR_INDEX_TYPES } from '../type/vector.js';
 import { isDatabaseWritten } from './field.util.js';
 import { entityName, getFieldKeys, getKeys, hasKeys, isScalarId, isRecord, isWhereMap, someKey, } from './object.util.js';
+/** The keys of `payload` a write persists as columns. */
 export function filterFieldKeys(meta, payload, callbackKey) {
     return getKeys(payload).filter((key) => {
         const fieldOpts = meta.fields[key];
@@ -15,7 +16,6 @@ function isInsertableField(meta, record, key) {
     const field = meta.fields[key];
     return !!field && !isDatabaseWritten(field) && record[key] !== undefined;
 }
-/** Appends `record`'s not-yet-`seen` insertable keys (real, caller-written, defined value) to `keys`. */
 /**
  * The insertable keys `record` itself carries, as a string, for grouping rows by the statement they
  * can share. Only the row's own keys: the `onInsert` columns {@link getInsertFieldKeys} appends are a
@@ -30,6 +30,7 @@ export function insertShapeOf(meta, record) {
     }
     return shape;
 }
+/** Appends `record`'s not-yet-`seen` insertable keys to `keys`. */
 function addInsertFieldKeys(meta, record, seen, keys) {
     for (const key of getKeys(record)) {
         if (!seen.has(key) && isInsertableField(meta, record, key)) {
@@ -39,16 +40,8 @@ function addInsertFieldKeys(meta, record, seen, keys) {
     }
 }
 /**
- * Resolves the columns of an INSERT statement: the union of the persistable fields provided by
- * any record (in first-seen order), plus every `onInsert` field. Records missing one of these
- * columns insert its database default.
- *
- * The column list is seeded from the first record, then extended by every other record's
- * not-yet-seen columns - a no-op scan for a homogeneous batch (every record the same shape).
- *
- * `onInsert` fields are always included so the column set is stable whether or not the caller
- * has run {@link fillOnFields} first (it stamps them on every record, but the querier's
- * chunk-size estimate inspects the raw payload).
+ * An insert's columns: every record's writable fields in first-seen order, plus every `onInsert` field,
+ * whether or not it was filled yet. A record missing one writes its default.
  */
 export function getInsertFieldKeys(meta, payloads) {
     const seen = new Set();
@@ -186,7 +179,7 @@ export function isVectorSearch(value) {
  * which, as they did when one took the first and the other the last.
  */
 export function findVectorSort(sort) {
-    for (const key of getKeys(sort ?? {})) {
+    for (const key of getKeys(sort)) {
         const search = sort?.[key];
         // The guard narrows here, where a `.find()` over entries would hand back an untyped tuple.
         if (isVectorSearch(search)) {
@@ -259,17 +252,9 @@ export function withoutSoftDeleteFilter(filters) {
     return filters === false ? false : { ...filters, [SOFT_DELETE_FILTER]: false };
 }
 /**
- * Returns a new `$where` map with every active entity filter's condition merged in, resolving
- * parameterized conditions against the explicit or ambient {@link UqlContext}. Never mutates the input.
- *
- * Convenience filters are active by default (unless `opts.filters === false` or bypassed by name), and
- * their keys are applied only when absent from the map, so an explicit `$where` on that key opts out.
- *
- * `security` filters are always active (bypass is ignored) and AND-merged, so a client `$where` on the
- * same field can't override them. A security condition that returns `undefined` fails the query closed
- * (throws {@link UqlSecurityError}) unless its `onMissing` is `skip`; one that returns an empty object
- * (`{}`) 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).
+ * `$where` with the entity's active filters merged in, against the ambient {@link UqlContext}. A convenience
+ * filter yields to a `$where` on its key; a `security` one is always ANDed, and throws where its condition
+ * resolves to nothing, unless `onMissing: 'skip'`.
  */
 export function applyFilters(meta, whereMap, opts) {
     if (!meta.filters) {
@@ -323,10 +308,8 @@ export function applyFilters(meta, whereMap, opts) {
     return result;
 }
 /**
- * The `$size` of a relation condition (`{ comments: { $size: { $gte: 2 } } }`), or `undefined` when the
- * condition constrains the target's fields instead. Shared so every dialect agrees on which of the two
- * a relation key means, and so the ambiguous mix fails loudly: `{ $size: 2, name: 'x' }` used to fall
- * through to field filtering and emit a condition on a `$size` *column*.
+ * The `$size` of a relation condition, `{ comments: { $size: { $gte: 2 } } }`, or `undefined` where it
+ * filters the target's fields; a mix of the two, `{ $size: 2, name: 'x' }`, is refused.
  */
 export function parseRelationSize(val) {
     if (!val || typeof val !== 'object' || !('$size' in val)) {