uql-orm 0.56.0 → 0.58.0

package/dist/type/query.js

@@ -9,8 +9,8 @@ export const COUNT_RESULT_KEY = '_count';
  * Declared beside the type they describe so the two cannot drift, and `satisfies` fails the build
  * rather than the runtime if a clause is ever renamed.
  *
- * `$lock` belongs to no group on purpose: it is the one clause neither a wire query nor a relation's
- * query accepts, so leaving it out is what excludes it from both.
+ * `$lock` is only in {@link QUERY_STATEMENT_CLAUSES}: neither a wire query nor a relation's query
+ * accepts it.
  */
 export const QUERY_OBJECT_CLAUSES = [
     '$select',
@@ -20,9 +20,8 @@ export const QUERY_OBJECT_CLAUSES = [
     '$sort',
 ];
 /**
- * Object clauses only the statement itself takes, never a relation's own query - the mirror of
- * `$lock`, which neither takes. Counting a relation is batched over the rows a read returned, and a
- * populated relation's rows are assembled after that, so there is nothing for a nested one to count.
+ * Object clauses only the statement itself takes: a populated relation's rows keep their declared type,
+ * so a `$count` inside one would have no `_count` to land in.
  */
 export const QUERY_ROOT_OBJECT_CLAUSES = ['$count'];
 export const QUERY_NUMBER_CLAUSES = ['$skip', '$limit'];
@@ -33,3 +32,9 @@ export const QUERY_NUMBER_CLAUSES = ['$skip', '$limit'];
  */
 export const QUERY_ROOT_NUMBER_CLAUSES = ['$candidates'];
 export const QUERY_BOOLEAN_CLAUSES = ['$distinct'];
+/** The clauses that describe the statement, which a populated relation's own query refuses by name. */
+export const QUERY_STATEMENT_CLAUSES = [
+    '$lock',
+    ...QUERY_ROOT_OBJECT_CLAUSES,
+    ...QUERY_ROOT_NUMBER_CLAUSES,
+];

package/dist/type/queryAggregate.d.ts

@@ -1,9 +1,9 @@
 import type { FieldKey } from './entity.js';
-import type { QueryPager, QuerySortDirection } from './query.js';
+import type { QueryPager, QuerySelect, QuerySortDirection } from './query.js';
 import type { QueryWhere, QueryWhereFieldValue } from './queryWhere.js';
 /**
  * Maps the offending keys to `never`, turning an excess key into a compile error; resolves to
- * `unknown` (an inert intersection member) when there are none. Needed because `$group`/`$agg` are
+ * `unknown` (an inert intersection member) when there are none. Needed because `$group`/`$select` are
  * captured as whole maps, and TypeScript skips excess-property checking on a naked type parameter.
  * A find captures key sets instead, where an unknown key fails the capture's own constraint.
  * @internal
@@ -21,7 +21,7 @@ type GroupedKeys<G> = {
 }[keyof G];
 /**
  * The keys `T` declares by name, or `never` when `T` is only an index signature - which is what an
- * uninferred `$agg` is, and what would otherwise make every key look like a declared alias.
+ * uninferred `$select` is, and what would otherwise make every key look like a declared alias.
  * @internal
  */
 type NamedKeys<T> = string extends keyof T ? never : keyof T;
@@ -37,7 +37,7 @@ export type QueryAggregateOp = (typeof QUERY_AGGREGATE_OPS)[number];
 export declare function isQueryAggregateOp(op: string): op is QueryAggregateOp;
 /**
  * DISTINCT-qualified aggregate ops, each mapped to the base op it applies to a field's distinct
- * values: `$countDistinct` → `COUNT(DISTINCT col)`, and likewise `$sumDistinct`/`$avgDistinct`. Flat
+ * values: `$countDistinct` -> `COUNT(DISTINCT col)`, and likewise `$sumDistinct`/`$avgDistinct`. Flat
  * (not a nested `{ $distinct }` argument) so the op is self-documenting and greppable. `$min`/`$max`
  * are omitted: DISTINCT is a no-op for them.
  */
@@ -57,8 +57,20 @@ export declare function resolveAggregateOp(key: string): {
     op: QueryAggregateOp;
     distinct: boolean;
 };
+/**
+ * Exactly one key of `T` with its value; every other key is forbidden (`never`). `Pick`, not `Record`,
+ * so the chosen key stays linked to `T`'s own property and renames follow it through.
+ */
+type ExactlyOne<T> = {
+    [K in keyof T]: Readonly<Pick<T, K>> & Partial<Readonly<Record<Exclude<keyof T, K>, never>>>;
+}[keyof T];
+/**
+ * One field named as a key - `{ amount: true }` - the way a statement names every field, so an editor
+ * rename reaches it where a string never would. `F` narrows which fields qualify.
+ */
+export type QueryFieldRef<E, F extends keyof E = FieldKey<E>> = ExactlyOne<Required<QuerySelect<E, F, true>>>;
 /** The argument of an aggregate function: a field, or `'*'` (only meaningful for `COUNT(*)`). */
-export type QueryAggregateArg<E> = FieldKey<E> | '*';
+export type QueryAggregateArg<E> = QueryFieldRef<E> | '*';
 /**
  * Fields `SUM`/`AVG` can total. Restricted to numeric columns because the result is declared
  * `number`: totalling a text or date column is either an engine error or a coercion, and neither
@@ -81,21 +93,17 @@ type TotallingOp = OpsOf<'$sum' | '$avg' | '$sumDistinct' | '$avgDistinct'>;
  * Every aggregate op mapped to the argument it accepts: `$count` a field or `'*'` (`COUNT(*)`),
  * the totalling ops a numeric field, `$min`/`$max`/`$countDistinct` any field.
  */
-type QueryAggregateArgMap<E> = Record<'$count', QueryAggregateArg<E>> & Record<TotallingOp, NumericFieldKey<E>> & Record<Exclude<AggregateOp, '$count' | TotallingOp>, FieldKey<E>>;
-/** Exactly one key of `T`: the chosen op with its value; every other op key is forbidden (`never`). */
-type ExactlyOne<T> = {
-    [K in keyof T]: Readonly<Record<K, T[K]>> & Partial<Readonly<Record<Exclude<keyof T, K>, never>>>;
-}[keyof T];
+type QueryAggregateArgMap<E> = Record<'$count', QueryAggregateArg<E>> & Record<TotallingOp, QueryFieldRef<E, NumericFieldKey<E>>> & Record<Exclude<AggregateOp, '$count' | TotallingOp>, QueryFieldRef<E>>;
 /**
  * An aggregate function applied to a field. Exactly one operation per entry (a second op is a
  * compile error). Only `$count` accepts `'*'` (i.e. `COUNT(*)`); every other op requires a field.
  * DISTINCT variants are flat ops (`$countDistinct`/`$sumDistinct`/`$avgDistinct`) taking a field.
  *
- * @example { $count: '*' }            → COUNT(*)
- * @example { $countDistinct: 'id' }   → COUNT(DISTINCT "id")
- * @example { $sum: 'amount' }         → SUM("amount")
- * @example { $sumDistinct: 'amount' } → SUM(DISTINCT "amount")
- * @example { $avg: 'age' }            → AVG("age")
+ * @example { $count: '*' }                    -> COUNT(*)
+ * @example { $countDistinct: { id: true } }   -> COUNT(DISTINCT "id")
+ * @example { $sum: { amount: true } }         -> SUM("amount")
+ * @example { $sumDistinct: { amount: true } } -> SUM(DISTINCT "amount")
+ * @example { $avg: { age: true } }            -> AVG("age")
  */
 export type QueryAggregateFn<E> = ExactlyOne<QueryAggregateArgMap<E>>;
 /** A single-key `{ [op]: unknown }` shape for each op in `Ops`, matched to infer that op's result. */
@@ -109,16 +117,14 @@ type CountingOp = OpsOf<'$count' | '$countDistinct'>;
 /**
  * Group-by columns: an object mapping entity field keys to `true`, exactly like {@link QuerySelect}.
  * Typed against the entity, so a typo'd column is a compile error. Compute aggregate columns with
- * {@link QueryAggMap} (the `$agg` key), not here.
+ * {@link QueryAggMap} (the `$select` key), not here.
  *
  * @example
  * ```ts
- * { status: true } // → GROUP BY "status"
+ * { status: true } // -> GROUP BY "status"
  * ```
  */
-export type QueryGroupMap<E> = {
-    readonly [K in FieldKey<E>]?: true;
-};
+export type QueryGroupMap<E> = Readonly<QuerySelect<E, FieldKey<E>, true>>;
 /**
  * Computed aggregate columns: an object mapping your chosen output alias to an aggregate function.
  * Alias names are free (you are naming new columns); the aggregated field reference inside each
@@ -126,8 +132,8 @@ export type QueryGroupMap<E> = {
  *
  * @example
  * ```ts
- * { count: { $count: '*' }, avgAge: { $avg: 'age' } }
- * // → COUNT(*) AS "count", AVG("age") AS "avgAge"
+ * { count: { $count: '*' }, avgAge: { $avg: { age: true } } }
+ * // -> COUNT(*) AS "count", AVG("age") AS "avgAge"
  * ```
  */
 export type QueryAggMap<E> = {
@@ -151,7 +157,7 @@ type QueryAggregateFnResult<E, Fn> = Fn extends FnWithOp<CountingOp> ? number :
     readonly $min: infer F;
 } | {
     readonly $max: infer F;
-} ? FieldValueType<E, F> | null : unknown;
+} ? FieldValueType<E, keyof F> | null : unknown;
 /**
  * Flattens an intersection into a single object literal for readable editor hovers.
  * @internal
@@ -166,17 +172,15 @@ type Simplify<T> = {
  * Grouped columns come from {@link GroupedKeys}, not `keyof G`, so a `$group` the compiler could
  * not read contributes none rather than all of them.
  */
-export type QueryAggregateResult<E, G, A> = Simplify<{
-    -readonly [K in GroupedKeys<G> & FieldKey<E>]: E[K];
-} & {
+export type QueryAggregateResult<E, G, A> = Simplify<Pick<E, GroupedKeys<G> & FieldKey<E>> & {
     -readonly [K in keyof A]: QueryAggregateFnResult<E, A[K]>;
 }>;
 /**
- * Erased runtime shape of a HAVING clause (alias → comparison), consumed by the dialect builders.
+ * Erased runtime shape of a HAVING clause (alias -> comparison), consumed by the dialect builders.
  * Values are `unknown` because the SQL is built generically; the typed, per-column value checking
  * lives in {@link QueryAggregate.$having}.
  *
- * @example { count: { $gt: 5 } }   → HAVING COUNT(*) > 5
+ * @example { count: { $gt: 5 } }   -> HAVING COUNT(*) > 5
  */
 export type QueryHavingMap = {
     readonly [alias: string]: QueryWhereFieldValue<unknown> | undefined;
@@ -190,7 +194,7 @@ export type QueryHavingMap = {
  * querier.aggregate(User, {
  *   $where: { deletedAt: { $isNull: true } },
  *   $group: { status: true },
- *   $agg: { count: { $count: '*' }, avgAge: { $avg: 'age' } },
+ *   $select: { count: { $count: '*' }, avgAge: { $avg: { age: true } } },
  *   $having: { count: { $gt: 5 } },
  *   $sort: { count: -1 },
  * });
@@ -203,17 +207,22 @@ export type QueryAggregate<E, G extends QueryGroupMap<E> = QueryGroupMap<E>, A e
     readonly $where?: QueryWhere<E>;
     /**
      * Columns to group by - `{ status: true }`, typed against the entity like `$select`. A computed
-     * aggregate wrongly placed here (it belongs in `$agg`) is rejected via {@link Reject}, since
-     * `$group` is captured as a generic and a bare generic skips excess-property checking.
+     * aggregate wrongly placed here (it belongs in `$select`) is rejected via {@link Reject}, since
+     * `$group` is captured as a generic and a bare generic skips excess-property checking. The captured
+     * map meets its schema, {@link QueryGroupMap}, so each key keeps its link to the entity property.
      */
-    readonly $group?: G & Reject<Exclude<keyof G, FieldKey<E>>>;
+    readonly $group?: G & QueryGroupMap<E> & Reject<Exclude<keyof G, FieldKey<E>>>;
     /**
-     * Computed aggregate columns - `{ count: { $count: '*' }, avgAge: { $avg: 'age' } }`.
+     * Computed aggregate columns - `{ count: { $count: '*' }, avgAge: { $avg: { age: true } } }`. The
+     * captured map meets its schema over the same aliases, as `$group` does, so field keys stay linked
+     * (a `Record<keyof A, ...>` spelling of the same type breaks the inference of `A`).
      *
      * An alias repeating a `$group` column is rejected: both would be emitted under that one name,
      * leaving the driver to keep whichever it read last.
      */
-    readonly $agg?: A & Reject<NamedKeys<A> & GroupedKeys<G>>;
+    readonly $select?: A & {
+        readonly [K in keyof A]: QueryAggregateFn<E>;
+    } & Reject<NamedKeys<A> & GroupedKeys<G>>;
     /**
      * Post-aggregation filtering, applied after grouping (SQL `HAVING`, MongoDB post-group `$match`).
      * Keyed by the result columns (grouped columns + computed aliases), and each value is typed to that

package/dist/type/queryAggregate.js

@@ -8,7 +8,7 @@ export function isQueryAggregateOp(op) {
 }
 /**
  * DISTINCT-qualified aggregate ops, each mapped to the base op it applies to a field's distinct
- * values: `$countDistinct` → `COUNT(DISTINCT col)`, and likewise `$sumDistinct`/`$avgDistinct`. Flat
+ * values: `$countDistinct` -> `COUNT(DISTINCT col)`, and likewise `$sumDistinct`/`$avgDistinct`. Flat
  * (not a nested `{ $distinct }` argument) so the op is self-documenting and greppable. `$min`/`$max`
  * are omitted: DISTINCT is a no-op for them.
  */

package/dist/type/queryWhere.d.ts

@@ -1,4 +1,5 @@
 import type { FieldKey, JsonFieldPaths, JsonFieldPathValue, RelationKey, RelationTarget } from './entity.js';
+import type { QuerySelect } from './query.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { ExpandScalar, IsMany, QueryComparableScalar, Scalar } from './utility.js';
 import type { QueryVectorQuery } from './vector.js';
@@ -11,9 +12,9 @@ export type QueryTextSearchOptions<E> = {
      */
     $value: string;
     /**
-     * list of fields to search on.
+     * the fields to search, `{ title: true, body: true }`, in the order a MySQL `FULLTEXT` index lists them.
      */
-    $fields?: FieldKey<E>[];
+    $fields?: QuerySelect<E>;
     /**
      * Postgres text-search configuration (e.g. `'english'`), applied to both the document and the
      * query. Defaults to the server's `default_text_search_config`. Ignored by other dialects.
@@ -27,17 +28,19 @@ export type QueryTextSearchOptions<E> = {
  * filtered via nested typed objects; dotted relation paths are not supported (the dialects throw
  * for non-JSON dotted keys).
  *
- * One mapped type over the three key sets rather than three intersected, for the reason
- * {@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.
+ * 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.
  */
-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>>;
-};
+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;
+} & ([JsonFieldPaths<E>] extends [never] ? unknown : {
+    [P in JsonFieldPaths<E>]?: QueryWhereFieldValue<JsonFieldPathValue<E, P>>;
+});
 /**
  * Filter a to-many relation by its row count.
  * @example { users: { $size: 2 } }

package/dist/type/universalQuerier.d.ts

@@ -1,5 +1,5 @@
 import type { EntityData, EntityId, FieldKey, RelationKey, UpdatePayload, WrittenId } from './entity.js';
-import type { QueryConflictPaths, QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpsertOneResult, QueryUpsertManyResult } from './query.js';
+import type { QueryConflictPaths, QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryUpsertOneResult, QueryUpsertManyResult } from './query.js';
 import type { QueryAggMap, QueryAggregate, QueryAggregateResult, QueryGroupMap } from './queryAggregate.js';
 import type { Type } from './utility.js';
 import type { QuerierCountedResult, QuerierResult, QuerierTransport } from './wire.js';
@@ -97,14 +97,14 @@ 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.
-     * Does not fill relations or fire lifecycle hooks - designed for high-performance
+     * 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
      */
-    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>(entity: Type<E>, q: QueryStreamProjected<E, S, V, X, P>, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P>>;
+    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).

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

@@ -128,7 +128,7 @@ export type ParsedGroupEntry = {
     readonly alias: string;
     readonly op: QueryAggregateOp;
     readonly fieldRef: string;
-    /** `true` for a flat distinct op (`$countDistinct`, ...) → `COUNT(DISTINCT field)`. */
+    /** `true` for a flat distinct op (`$countDistinct`, ...) -> `COUNT(DISTINCT field)`. */
     readonly distinct: boolean;
 };
 /**
@@ -145,10 +145,10 @@ export declare function parseRelationSize(val: unknown): number | QuerySizeCompa
  */
 export declare function parseSortByCount(val: unknown): unknown;
 /**
- * Parse the `$group` (grouped columns) and `$agg` (computed aggregates) maps into structured
+ * Parse the `$group` (grouped columns) and `$select` (computed aggregates) maps into structured
  * entries consumable by any dialect. Grouped columns come first, then computed columns.
  */
-export declare function parseGroupMap<E>(group?: QueryGroupMap<E>, agg?: QueryAggMap<E>): ParsedGroupEntry[];
+export declare function parseGroupMap<E>(group?: QueryGroupMap<E>, select?: QueryAggMap<E>): ParsedGroupEntry[];
 /**
  * Whether `value` is a map of comparison operators rather than a value to compare against. Only a
  * plain object qualifies: `Date`, `QueryRaw`, `Uint8Array` and arrays are all `typeof 'object'`, and
@@ -165,7 +165,7 @@ export declare function isOperatorMap(value: unknown): value is Record<string, u
 export declare function assertNonNegativeInteger(value: number, clause: string): number;
 /**
  * Rejects a `$having`/`$sort` key naming something an aggregate does not emit. Its rows are its
- * `$group` columns and its `$agg` aliases; anything else is a value that is not there. Shared so
+ * `$group` columns and its `$select` aliases; anything else is a value that is not there. Shared so
  * SQL and MongoDB refuse the same query with the same words.
  */
 export declare function throwUnknownAggregateColumn(key: string, clause: string): never;

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, isWhereMap, someKey } from './object.util.js';
+import { entityName, getFieldKeys, getKeys, hasKeys, isScalarId, isRecord, isWhereMap, someKey, } from './object.util.js';
 export function filterFieldKeys(meta, payload, callbackKey) {
     return getKeys(payload).filter((key) => {
         const fieldOpts = meta.fields[key];
@@ -355,10 +355,10 @@ export function parseSortByCount(val) {
     return val.$count;
 }
 /**
- * Parse the `$group` (grouped columns) and `$agg` (computed aggregates) maps into structured
+ * Parse the `$group` (grouped columns) and `$select` (computed aggregates) maps into structured
  * entries consumable by any dialect. Grouped columns come first, then computed columns.
  */
-export function parseGroupMap(group, agg) {
+export function parseGroupMap(group, select) {
     const entries = [];
     const groupMap = group ?? {};
     for (const alias of getKeys(groupMap)) {
@@ -366,22 +366,30 @@ export function parseGroupMap(group, agg) {
             entries.push({ kind: 'key', alias });
         }
     }
-    if (!agg) {
+    if (!select) {
         return entries;
     }
-    for (const alias of getKeys(agg)) {
-        const fnEntry = agg[alias];
+    for (const alias of getKeys(select)) {
+        const fnEntry = select[alias];
         const key = getKeys(fnEntry)[0];
         // Flat DISTINCT ops (`$countDistinct`, ...) normalize to their base op + a `distinct` flag.
         const { op, distinct } = resolveAggregateOp(key);
-        const fieldRef = fnEntry[key];
-        if (fieldRef === undefined) {
-            throw TypeError(`empty aggregate function for: ${alias}`);
-        }
-        entries.push({ kind: 'fn', alias, op, fieldRef, distinct });
+        entries.push({ kind: 'fn', alias, op, fieldRef: aggregateFieldRef(alias, fnEntry[key]), distinct });
     }
     return entries;
 }
+/** The column an aggregate reads: `'*'`, or the one field its `{ field: true }` names. */
+function aggregateFieldRef(alias, arg) {
+    const [field, ...rest] = arg === '*' ? [arg] : namedKeys(arg);
+    if (field === undefined || rest.length) {
+        throw new TypeError(`aggregate '${alias}' takes one field as { field: true }, or '*': got ${JSON.stringify(arg)}`);
+    }
+    return field;
+}
+/** The keys a `{ key: true }` map switches on; anything that is not such a map switches on none. */
+function namedKeys(map) {
+    return isRecord(map) ? getKeys(map).filter((key) => map[key]) : [];
+}
 /**
  * Whether `value` is a map of comparison operators rather than a value to compare against. Only a
  * plain object qualifies: `Date`, `QueryRaw`, `Uint8Array` and arrays are all `typeof 'object'`, and
@@ -410,11 +418,11 @@ export function assertNonNegativeInteger(value, clause) {
 }
 /**
  * Rejects a `$having`/`$sort` key naming something an aggregate does not emit. Its rows are its
- * `$group` columns and its `$agg` aliases; anything else is a value that is not there. Shared so
+ * `$group` columns and its `$select` aliases; anything else is a value that is not there. Shared so
  * SQL and MongoDB refuse the same query with the same words.
  */
 export function throwUnknownAggregateColumn(key, clause) {
-    throw new TypeError(`cannot ${clause} by '${key}': it is neither a $group column nor an $agg alias`);
+    throw new TypeError(`cannot ${clause} by '${key}': it is neither a $group column nor a $select alias`);
 }
 /** {@link throwUnknownAggregateColumn} over every key of a clause, for backends that check up front. */
 export function assertAggregateColumns(clauseMap, emitted, clause) {
@@ -430,8 +438,9 @@ export function assertAggregateColumns(clauseMap, emitted, clause) {
  * where neither says, rather than guessed: every engine answers a guess with an error of its own.
  */
 export function textSearchFields(meta, search) {
-    if (search.$fields?.length) {
-        return search.$fields;
+    const named = namedKeys(search.$fields);
+    if (named.length) {
+        return named;
     }
     const fulltext = (meta.indexes ?? []).filter((index) => index.type === 'fulltext');
     if (fulltext.length === 1) {

package/dist/util/field.util.d.ts

@@ -22,6 +22,11 @@ export declare const COLUMN_TYPES_BY_FAMILY: {
 };
 /** The family of a logical field type, or `undefined` where it names none. */
 export declare function columnFamily(type: unknown): ColumnFamily | undefined;
+/**
+ * Whether a field's column holds whole numbers: a declared integer type, or a `Number` or `BigInt`
+ * with no scale, which every engine here stores as BIGINT.
+ */
+export declare function isIntegerColumn(field: Pick<FieldOptions, 'type' | 'columnType' | 'precision' | 'scale'>): boolean;
 /**
  * Whether the field's expression is spliced into each statement that reads it, rather than stored.
  * Every read site asks this - the DDL skip, the projection, the `$where` and `ORDER BY` operands -

package/dist/util/field.util.js

@@ -46,6 +46,25 @@ for (const family of getKeys(COLUMN_TYPES_BY_FAMILY)) {
 export function columnFamily(type) {
     return FAMILY_OF.get(typeof type === 'string' ? type.toLowerCase() : type);
 }
+/** The numeric column types that hold whole numbers. */
+const INTEGER_COLUMN_TYPES = new Set([
+    'int',
+    'integer',
+    'tinyint',
+    'smallint',
+    'bigint',
+]);
+/**
+ * Whether a field's column holds whole numbers: a declared integer type, or a `Number` or `BigInt`
+ * with no scale, which every engine here stores as BIGINT.
+ */
+export function isIntegerColumn(field) {
+    const type = field.columnType ?? field.type;
+    if (typeof type === 'string') {
+        return INTEGER_COLUMN_TYPES.has(type.toLowerCase());
+    }
+    return type === BigInt || (type === Number && !field.precision && !field.scale);
+}
 /**
  * Whether the field's expression is spliced into each statement that reads it, rather than stored.
  * Every read site asks this - the DDL skip, the projection, the `$where` and `ORDER BY` operands -

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

@@ -19,6 +19,8 @@ export declare function someValue(obj: object, pred: (value: unknown) => boolean
 export declare function isOperatorObject(value: unknown): value is Record<string, unknown>;
 /** Whether every key of the non-empty object `value` is an operator (no plain field names mixed in). */
 export declare function isOperatorOnlyObject(value: unknown): value is Record<string, unknown>;
+/** Whether `value` is an object that is not an array, whose keys can be read. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
 export declare function getKeys<T extends object>(obj: T): (keyof T & string)[];
 /** The entries of `record` holding a value: a key declared but left `undefined` is no entry at all. */
 export declare function definedEntries<K extends string, V>(record: Partial<Record<K, V>>): [K, V][];

package/dist/util/object.util.js

@@ -49,6 +49,10 @@ export function isOperatorObject(value) {
 export function isOperatorOnlyObject(value) {
     return hasKeys(value) && !Array.isArray(value) && !someKey(value, (key) => !isOperatorKey(key));
 }
+/** Whether `value` is an object that is not an array, whose keys can be read. */
+export function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
 export function getKeys(obj) {
     return obj ? Object.keys(obj) : [];
 }

package/dist/util/relationQuery.util.d.ts

@@ -1,4 +1,4 @@
-import type { EntityMeta, FieldMeta, Except, Query, QueryPopulate, RelationKey, RelationMeta } from '../type/index.js';
+import type { EntityMeta, QueryCount, QueryPopulate, RelationKey, RelationMeta, RelationQuery, QueryWhere } from '../type/index.js';
 export type RelationRequestSummary<E> = {
     readonly requestedKeys: readonly RelationKey<E>[];
     readonly joinableKeys: readonly RelationKey<E>[];
@@ -32,67 +32,10 @@ export declare function parentJoins(relOpts: Pick<RelationMeta, 'references' | '
  * which is the mistake this module exists to prevent.
  */
 export declare function targetKeyColumns(relOpts: Pick<RelationMeta, 'references'>, parentKeyCount: number): string[];
-/** `{ joined column: true }`: the projection or grouping that keeps a parent's key on the rows read. */
-export declare function joinedColumns(joins: readonly ParentJoin[]): Record<string, true>;
-/**
- * One side's columns: `'parent'` for the columns a parent is keyed by, `'joined'` for the ones a
- * child or tally row carries that key in. Matching the two halves means agreeing on every column, so
- * each side is read through `joins` rather than through the parent's own key list - the same set only
- * for a to-many, and silently a different one otherwise. `keyof ParentJoin` is what keeps the two
- * sides from being spelled apart.
- *
- * Lifted out of `joins` once per relation, not once per row: {@link rowKey} takes the list and reads
- * each row itself, so a page of children costs one key each and nothing else.
- */
-export declare function keyColumns(joins: readonly ParentJoin[], side: keyof ParentJoin): string[];
-/**
- * `{ joined column: every parent's value for it }`, the filter that fetches a whole page of parents'
- * children in one statement.
- *
- * A composite over-selects, because the lists are independent and a pairing no parent has can still
- * match. Regrouping the rows keys on every column, so those rows find no parent and are dropped -
- * cheaper than the row-value comparison no engine spells the same way.
- */
-export declare function parentsIn(joins: readonly ParentJoin[], parents: readonly unknown[]): Record<string, unknown[]>;
-/**
- * The parents a bounded to-many read fans out over: the rows themselves, the columns matching them to
- * their children.
- */
-export type ParentPartition = {
-    readonly joins: readonly ParentJoin[];
-    readonly parents: readonly unknown[];
-    /** The parent's own fields: a `LATERAL` row source has to spell its key column's type. */
-    readonly parentFields: Readonly<Record<string, FieldMeta | undefined>>;
-};
-/**
- * Whether a to-many's own query asks for a share *per parent* rather than a slice of the whole page.
- * Only `$limit`/`$skip` do: without one, a single flat statement over an `IN (...)` list is both
- * correct and cheaper.
- */
-export declare function isBoundedPerParent(query: Pick<RelationQuery, '$limit' | '$skip'>): boolean;
-/**
- * `query` narrowed to one parent's children: what a single branch of a bounded per-parent read asks
- * for. Shared by the backends so how the parent's filter merges into the relation's own is decided
- * once - both spelled it out, and a rule that ever needs more than a spread would have to change twice.
- */
-export declare function queryChildrenOf<E>(query: Query<E>, joins: readonly ParentJoin[], parent: unknown): Query<E>;
-/**
- * `query` narrowed to the children of a whole page of parents, which is the flat read a relation with
- * no share of its own takes. Over-selects on a composite key exactly as {@link parentsIn} does.
- */
-export declare function queryChildrenOfAll<E>(query: Query<E>, joins: readonly ParentJoin[], parents: readonly unknown[]): Query<E>;
-/**
- * `query` with `filter` merged into its own `$where`: the one rule for narrowing a relation's query to
- * the parents it is being read for, whether the filter names their keys as values or, for a correlated
- * shape, as a reference to a row source.
- */
-export declare function queryNarrowedTo<E>(query: Query<E>, filter: Record<string, unknown>): Query<E>;
 /**
  * The `$where` naming exactly the children of the rows `parentIds` identifies: an `IN` over the one
- * column a single key contributes, an OR of key maps for several.
- *
- * Exact, unlike {@link parentsIn}: a read absorbs over-selection by regrouping its rows, and a write
- * has nothing to regroup - a pairing no parent has would delete a child of a parent that survives.
+ * column a single key contributes, an OR of whole key maps for several - lists of each column apart
+ * would pair values no parent has, and a delete would take a child of a parent that survives.
  */
 export declare function childrenOf(joins: readonly ParentJoin[], parentIds: readonly unknown[]): Record<string, unknown>;
 /**
@@ -107,11 +50,15 @@ export type JoinedRelationRejectedKey = (typeof JOINED_RELATION_REJECTIONS)[numb
 export declare function getRelationRequestSummary<E>(meta: EntityMeta<E>, populate?: QueryPopulate<E>): RelationRequestSummary<E>;
 /** True when `$populate` includes at least one relation key. */
 export declare function populatesRelations<E>(meta: EntityMeta<E>, populate?: QueryPopulate<E>): boolean;
-export type RelationQuery<E extends object = object> = Except<Query<E>, StatementOnlyClause> & {
-    $required?: boolean;
-};
-/** The clauses that describe the statement rather than what a query selects. */
-type StatementOnlyClause = '$lock' | '$candidates';
+/**
+ * Each relation a `$count` tallies, and the filter narrowing what it counts: the target's, whose type
+ * only the metadata knows this far down, as for a relation filter reaching the same subquery.
+ */
+export declare function countedRelations<E>(meta: EntityMeta<E>, counts: QueryCount<E> | undefined): {
+    readonly relKey: RelationKey<E>;
+    readonly relation: RelationMeta;
+    readonly where: QueryWhere<object>;
+}[];
 export type ParsedRelationQuery<E extends object = object> = {
     query: RelationQuery<E>;
     required: boolean;